Latch 工作流 UI 与自动化实战指南：LatchMetadata、Launch Plans、消息、结果与 Automations 全解析-港品优选

Latch 工作流 UI 与自动化实战指南：LatchMetadata、Launch Plans、消息、结果与 Automations 全解析

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本指南基于 latchbio-integration 技能中 ui-and-automation.md 参考文档，系统讲解如何在 Latch（SDK 2.76.8）上把工作流界面（UI）当作正确性的一部分来设计：从LatchMetadata的表单定义、flow布局编排，到 Launch Plans 预置测试数据、任务内消息推送、结果页发布，再到数据新增/定时两类自动化触发。读完本文，你将能独立为一个生物信息学工作流设计出带校验规则、分层布局、样本表和预设参数的完整用户界面，并安全地配置自动触发与可观测性。

核心理念：接口设计就是工作流正确性的一部分

在 Latch 上，一个工作流由两部分共同决定用户看到的形态：

工作流签名（signature）定义参数的类型；
LatchMetadata定义用户如何理解并填写这些值。

二者缺一不可。签名只回答"这个参数是什么类型"，元数据回答"这个参数在科学上意味着什么、该填什么、怎么填才合法"。正如 ui-and-automation.md 开篇强调的：Treat interface design as part of workflow correctness——把界面设计视为工作流正确性的一部分。一个参数类型正确但缺乏校验、缺少说明、默认值隐含科学假设的表单，会让用户在不经意间提交错误分析。

配套的 SKILL.md 给出两条贯穿性约束：

元数据参数键必须与工作流签名参数名一一对应，SDK 会拒绝签名中不存在的元数据键（workflow-creation.md 也复述了这一点）；
模块导入期保持纯净——不要在 import 时触发网络调用、数据变更或密钥读取，元数据对象应在导入期被安全求值。

LatchMetadata：定义一个完整的科学表单

下面是一个完整的元数据定义示例（来自 ui-and-automation.md），它把"Bulk RNA-seq QC"工作流包装成一个结构清晰、带校验和分区的表单：

from latch.types.metadata import ( LatchAuthor, LatchMetadata, LatchParameter, LatchRule, Params, Section, Spoiler, Text, ) metadata = LatchMetadata( display_name="Bulk RNA-seq QC", author=LatchAuthor( name="Workflow Team", github="https://github.com/example", ), documentation="https://example.org/docs/rnaseq-qc", repository="https://github.com/example/rnaseq-qc", license="MIT", tags=["RNA-seq", "QC"], parameters={ "reads": LatchParameter( display_name="Reads", description="FASTQ input files.", samplesheet=True, ), "minimum_quality": LatchParameter( display_name="Minimum quality", description="Minimum accepted Phred score.", rules=[ LatchRule( regex=r"^(?:[0-9]|[1-3][0-9]|40)$", message="Choose an integer from 0 through 40.", ) ], ), "output_directory": LatchParameter( display_name="Output directory", description="Destination for reports and processed outputs.", output=True, ), }, flow=[ Section( "Inputs", Text("Select samples and input reads."), Params("reads"), ), Spoiler( "Advanced quality settings", Params("minimum_quality"), ), Section( "Outputs", Params("output_directory"), ), ], )

关键字段语义如下：

字段	用途
`display_name`/`description`	呈现给用户的科学含义说明
`samplesheet=True`	将参数渲染为表格（样本表）输入，配合 dataclass 承载结构化行数据
`rules=[LatchRule(regex=..., message=...)]`	对输入做正则语法校验，`message`是校验失败时的提示
`output=True`	标记该参数是输出目的地，与`LatchOutputFile`/`LatchOutputDir`类型呼应
`hidden`	隐藏很少改动的值（注意：是"隐藏"，不是"安全"，见下文参数指南）
`allowed_tables`	限制 Registry 导入时允许的表
`batch_table_column`	标记适合批量运行的高价值字段

应用元数据并保持签名一致

元数据通过@workflow(metadata)挂接到工作流上（ui-and-automation.md）：

from dataclasses import dataclass from pathlib import Path from latch import small_task, workflow from latch.types import LatchDir, LatchFile, LatchOutputDir @dataclass class SampleRow: sample_name: str reads: LatchFile @small_task def run_qc( reads: list[SampleRow], output_directory: LatchOutputDir, minimum_quality: int, ) -> LatchDir: local_output = Path("/root/rnaseq-qc") local_output.mkdir(parents=True, exist_ok=True) (local_output / "summary.txt").write_text( f"samples={len(reads)}\nminimum_quality={minimum_quality}\n", encoding="utf-8", ) remote = output_directory.remote_path if remote is None: raise ValueError("output_directory must have a remote path") return LatchDir(str(local_output), remote) @workflow(metadata) def rnaseq_qc( reads: list[SampleRow], output_directory: LatchOutputDir, minimum_quality: int = 20, ) -> LatchDir: return run_qc( reads=reads, output_directory=output_directory, minimum_quality=minimum_quality, )

注意reads是list[SampleRow]的 dataclass 列表，这正是samplesheet=True的落点：用户在 Console 中以表格逐行填写样本。任务内通过output_directory.remote_path拿到远端输出路径，再把本地结果目录与远端目标配对成LatchDir返回，SDK 会自动上传。

三条来自 ui-and-automation.md 的硬性规则：

元数据参数键必须匹配签名：SDK 会为元数据对象中遗漏的签名参数自动补默认元数据；
about_page_path存在已知缺陷：虽然文档仍然描述它，但 SDK 2.76.8 在序列化其Path值时会失败，应优先使用documentation=加一段描述性工作流 docstring，直到该缺陷修复；
不要在表单中依赖"隐藏"来兜底科学假设（见参数指南）。

flow 元素：从默认纵向布局到精心编排

flow字段取代默认的自上而下布局，让你决定参数出现的顺序、分组和可见性。当前可用的 flow 类（ui-and-automation.md）：

Section(title, *children)：带标题的分区
Text(markdown)：分区内的说明文本
Title(markdown_title)：标题文本
Params(*parameter_names)：按名字引用参数
Spoiler(title, *children)：默认折叠的"高级设置"分组
Fork(parameter_name, display_name, **branches)：按某个字符串参数分流
ForkBranch(display_name, *children)：Fork 的一个分支

编排原则：让每个可见参数都有意为之——要么明确归属某个 Section，要么放进 Spoiler 表明"高级选项"，要么经 Fork 按用户选择动态展示。

Fork只能配合签名中存在且匹配的字符串参数使用：

from latch.types.metadata import Fork, ForkBranch, Params read_type_flow = Fork( "read_type", "Read layout", paired=ForkBranch("Paired-end", Params("read1", "read2")), single=ForkBranch("Single-end", Params("read1")), )

这里read_type必须是工作流签名的字符串参数，分支键paired/single对应其取值；选择 paired 时表单展示read1、read2两个输入，选择 single 时只展示read1。这种交互式分流能显著降低误填概率。

参数设计指南：科学语义优先

ui-and-automation.md 给出了一套明确的参数设计取舍：

应该用：

display_name和description承载科学含义；
rules做语法校验（如 Phred 分值必须是 0–40 的整数）；
hidden隐藏极少改动的值——但它只是隐藏，不是安全机制；
batch_table_column标记批量运行中的高价值字段；
samplesheet=True处理 dataclass 支撑的表格化输入；
allowed_tables限制 Registry 导入范围；
output=True或LatchOutputFile/LatchOutputDir类型标记新的输出目的地。

不应该用：

不要用表单默认值掩盖科学假设。参考基因组、链特异性（strandedness）、单位、算法默认值都必须显式声明，而不是悄悄塞进默认值里。

这一条与 SKILL.md 的"Operational Safety"一脉相承：表单是用户与计算之间唯一的契约，含糊的默认值等于把科学决策外包给了平台默认。

Launch Plans：一键复现的命名参数集

LaunchPlan为工作流创建一组命名默认值，注册后会显示在 Console 的Test Data下（ui-and-automation.md）：

from latch.resources.launch_plan import LaunchPlan from latch.types import LatchFile, LatchOutputDir LaunchPlan( rnaseq_qc, "Small public example", { "reads": [ SampleRow( sample_name="example", reads=LatchFile("latch:///test-data/example.fastq.gz"), ) ], "minimum_quality": 20, "output_directory": LatchOutputDir( "latch:///test-results/rnaseq-qc" ), }, description="Small input for interface and integration testing.", )

构造器签名：

LaunchPlan( workflow, name, default_params, *, description=None, )

使用规则：

在模块作用域定义 launch plan，注册阶段才能发现它们；
参数键和值必须与工作流签名匹配；
launch plan 名称不能包含.；
使用小型公开数据或工作区安全测试数据；
避免使用会被并发用户共享的输出目的地；
绝不把密钥放进 launch plan。

Launch plan 不只是演示工具：它还是 CI 回归的抓手。在 operations-and-debugging.md 的发布清单中，"运行一个代表性 launch plan、确认结果链接与元数据"是--mark-as-release之前的必做步骤；而latch_cli.services.launch.launch_v2.launch_from_launch_plan允许 Python 侧直接按 launch plan 名称启动执行（该符号在 inspect_latch_sdk.py 的execution组中可被验证）。

执行消息：面向用户的信号，而不是原始日志

message()用于向用户界面发送简短、可操作的信号，不要把它当成日志通道（ui-and-automation.md）：

from latch import message, small_task @small_task def validate_columns(columns: list[str]) -> bool: required = {"sample_id", "condition"} missing = sorted(required.difference(columns)) if missing: message( typ="error", data={ "title": "Missing required columns", "body": ", ".join(missing), }, ) raise ValueError(f"missing columns: {missing}") message( typ="info", data={ "title": "Input validated", "body": "Required sample columns are present.", }, ) return True

协议约束：

合法的消息类型只有三种：info、warning、error；
data字典必须包含title和body；
不要在消息中放密钥、签名 URL、患者标识符或过量的原始数据。

这与 operations-and-debugging.md 的生产可观测性三层模型一致：message()负责可操作告警与错误，结果链接负责高价值输出，结构化日志负责详细诊断——三者各司其职，且一律不得记录密钥或签名 URL。

结果页：把最有价值的产物放到最显眼的位置

add_execution_results让你把关键输出路径发布到执行结果页，提高可发现性（ui-and-automation.md）：

from latch import small_task from latch.executions import add_execution_results from latch.types import LatchOutputDir @small_task def publish_results(output_directory: LatchOutputDir) -> None: remote = output_directory.remote_path if remote is None: raise ValueError("output directory must have a remote path") add_execution_results( [ remote, f"{remote.rstrip('/')}/multiqc_report.html", ] )

要点：

结果链接只是增强可发现性——它不会替你上传缺失的输出，也不会验证科学有效性；
对于 Nextflow 参数，NextflowParameter.results_paths可以发布输出目录下的指定子路径。

结合 operations-and-debugging.md 的监控章节：Console 执行监控会呈现执行状态、图与任务节点状态、输入输出、日志、溯源与结果文件、资源监控，结果页就是其中"结果文件"面向用户的门面。把 MultiQC 报告、关键统计表这类高频查看产物提前到结果页顶部，能显著缩短用户的验证闭环。

Automations：让工作流在数据到达时自动跑起来

Automations 在 Latch Console 中配置，支持两类触发器（ui-and-automation.md）：

数据新增触发（data-added）：监控的 Latch Data 目录下任意深度新增了子项；
定时触发（interval）：按固定时间间隔重复执行。

数据新增触发的工作流契约

自动化工作流必须恰好有一个参数：

from latch import small_task, workflow from latch.types import LatchDir @small_task def process_new_data(input_directory: LatchDir) -> None: children = list(input_directory.iterdir()) print(f"observed {len(children)} children") @workflow def automation_workflow(input_directory: LatchDir) -> None: process_new_data(input_directory=input_directory)

触发语义：最后一次新增之后，经过配置的 follow-up/update 等待期才触发。仅修改或删除文件不会触发运行——这要求监控目录里放的是"只增不改"的输入。

定时触发的工作流契约

定时工作流不能有任何参数：

from latch import small_task, workflow @small_task def run_scheduled_check() -> None: print("scheduled check started") @workflow def scheduled_workflow() -> None: run_scheduled_check()

自动化安全清单

自动化会把"有人点运行"变成"平台自动运行"，因此必须把代价与幂等性纳入设计：

成本：自动化可能产生周期性付费计算。启用前审视触发频率、map 宽度与最坏情况成本（SKILL.md 同样要求：启动付费计算前先获得确认）；
幂等：处理逻辑必须可重复执行，用 Registry 记录或持久标记防止重复处理——这正是 registry.md 中Account/Project/Table/Record事务化更新的典型场景；
密钥：不要硬编码密钥，任务内用get_secret()获取；
先手动后自动：启用触发器前先手动跑通工作流；
防风暴：起始 debounce/update 周期要足够长，避免 launch storm；
契约冻结：修改工作流契约前先停用自动化；
目录隔离：确保监控目录不包含自动化自身的输出，否则新增输出会再次触发自身，形成循环。

配套验证工具：以安装的 SDK 为准

ui-and-automation.md 中所有代码针对Latch SDK 2.76.8（Python 3.9–3.12）。使用任何版本敏感符号前，建议用技能自带的 inspect_latch_sdk.py 对当前安装的 SDK 做本地内省——它只做本地 import，不联网、不鉴权：

uv run --no-project --python 3.12 --with "latch==2.76.8" \ python scripts/inspect_latch_sdk.py # JSON 输出便于自动化对比 uv run --no-project --python 3.12 --with "latch==2.76.8" \ python scripts/inspect_latch_sdk.py --json

该脚本会逐一检查latch.types.metadata.LatchMetadata、latch.types.metadata.LatchParameter、latch.resources.launch_plan.LaunchPlan（见 inspect_latch_sdk.py 的metadata组）以及Execution的poll/wait/abort方法是否存在、签名是否变化，--strict模式下核心符号缺失时以非零码退出，适合接进 CI。这也是官方资料与本地事实冲突时的仲裁方式：以安装包及其 changelog 为准。

参考文档速查

本指南是 latchbio-integration 技能"UI 与自动化"参考文档的展开版。需要更完整的上下文时，可按需阅读同一技能下的其他参考：

workflow-creation.md：任务、工作流、map_task、条件节点、缓存与超时——UI 背后的图编排基础
operations-and-debugging.md：注册、staging、latch develop、程序化执行与监控——发布前验证 UI 与 launch plan 的配套流程
registry.md：Registry 对象模型与事务化更新——自动化幂等标记与allowed_tables的落点
data-management.md：LPath、LatchFile/LatchDir与latch:///路径语义——launch plan 默认值中文件参数的来源
resource-configuration.md：CPU/内存/GPU 配置——评估自动化最坏情况成本的依据
latch-mcp.md：通过 MCP 交互式启动与监控——自动化之外的人工操作通道

官方来源方面，原文档列出的 UI 定义（LatchMetadata）、Launch Plans、Messages、Results、Automation 概览、数据新增触发与定时触发示例等主题文档，可在 Latch Wiki 的对应工作流章节检索获取，并以当前安装的 SDK 与 changelog 为准核对版本差异。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析