latchbio-integration

LatchBio 集成

当前基线

此技能面向 Latch SDK 2.76.8，该版本于 2026 年 7 月 10 日发布。包元数据支持 Python 3.9–3.12，并声明要求 Python 3.9+。

当指南与 SDK 不一致时，以已安装的包及其变更日志为准。部分 Latch 指南仍保留较旧的 Python 版本范围或针对兼容性的预发布版本固定要求，Snakemake v2 教程尤为如此。未经版本要求核实，切勿混用不同路线的命令或导入语句。

适用场景

使用此技能来：

• 创建或维护 Python SDK 工作流和任务图
• 打包并注册 Python、Nextflow 或 Snakemake 流水线
• 配置任务的 CPU、内存、存储、GPU、缓存、重试和超时
• 通过 LPath、LatchFile、LatchDir 或 CLI 使用 Latch Data
• 读取或更新 Latch Registry 项目、表和记录
• 设计工作流表单、启动计划、样本表、消息和结果链接
• 使用 latch register --staging 和 latch develop 暂存并调试工作流镜像
• 通过 Python 或 Latch MCP 启动并监控工作流
• 发现并使用可直接运行的 Latch 工作流

查找合适的参考资料

只阅读任务所需的参考资料：

需求	参考资料
Python 工作流、任务、映射、条件、缓存	references/workflow-creation.md
LPath、旧版文件类型、Latch URL、数据 CLI	references/data-management.md
Registry 读取、事务、样本表	references/registry.md
CPU、内存、存储、GPU、动态资源	references/resource-configuration.md
Nextflow 和 Snakemake 打包	references/nextflow-snakemake.md
元数据、表单、启动计划、消息、自动化	references/ui-and-automation.md
注册、开发、执行、监控	references/operations-and-debugging.md
可直接使用的工作流和 latch.verified	references/verified-workflows.md
远程 MCP 设置和工具工作流	references/latch-mcp.md

在依赖某个符号之前，针对目标 SDK 版本运行 scripts/inspect_latch_sdk.py。该脚本仅执行本地导入，不会进行身份验证或发起网络请求。

安装和身份验证

如需可复现的环境：

uv venv --python 3.12
source .venv/bin/activate
uv pip install "latch==2.76.8"

在 Windows 上，使用 WSL 运行文档中介绍的 Linux 工作流工具。

通过受支持的 OAuth 流程进行身份验证；不要手动读取、打印、复制或解析 ~/.latch/token：

latch login
latch workspace

当已知工作区的数字 ID 时，可通过非交互方式选择该工作区：

latch workspace --id 12345

latch login 凭据供 SDK 和 CLI 使用。Latch MCP 使用单独的 OAuth 授权，其凭据不能用于常规 SDK 访问。

快速开始

创建并远程注册维护中的子进程模板：

latch init covid-wf --template subprocess
latch register --yes --open covid-wf

默认使用远程镜像构建。仅当本地 Docker 守护进程可用且确实需要本地构建时，才使用 --no-remote。

最简 Python 工作流

保持工作流主体采用声明式写法：调用任务并返回其 Promise。在任务内部执行计算和副作用。

from latch import small_task, workflow


@small_task
def reverse_complement(sequence: str) -> str:
    table = str.maketrans("ACGTacgt", "TGCAtgca")
    return sequence.translate(table)[::-1]


@workflow
def reverse_complement_workflow(sequence: str) -> str:
    """Return the reverse complement of a DNA sequence."""
    return reverse_complement(sequence=sequence)

如果生成的界面需要自定义标签、分区、验证规则、样本表或文档链接，请使用 @workflow(metadata)。使用 LatchFile 或 LatchDir 自动暂存任务输入并上传输出；使用 LPath 执行命令式远程路径操作。

推荐的开发生命周期

1. 检查兼容性

   • 确认已安装的 SDK 和 Python 版本。
   • 判断项目属于 Python、Nextflow、旧版 Snakemake 标志路径，还是单独固定版本的 Snakemake v2 教程路线。

2. 定义类型化接口

   • 为每个工作流和任务的输入、输出添加类型注释。
   • 确保模块导入时不执行网络调用、数据修改或机密检索。将文档中说明的例外情况隔离开来，例如 workflow_reference，它会在计算其装饰器时解析活动工作区。
   • 使用 dataclass 和枚举表示结构化参数。

3. 配置元数据和资源

   • 确保元数据参数键与工作流签名一致。
   • 从命名任务装饰器开始，仅在经过测量的需求确有必要时才使用 custom_task。

4. 在执行镜像中验证

   全新的 Nextflow 和 Snakemake 项目必须在暂存之前生成与版本兼容的 Python 入口点。在 SDK 2.76.8 中，暂存分支不会通过 --nf-script 或 --snakefile 生成入口点。

   latch register --staging .
   latch develop .
   

   更改 Dockerfile 或依赖项后，重新运行暂存注册。开发容器内所做的编辑不会同步回来。

5. 审慎注册

   latch register --yes --open .
   

   实用的控制选项：

   latch register --workspace-id 12345 .
   latch register --mark-as-release .
   latch register --workflow-module wf.custom_entrypoint .
   

   重复注册会以状态码 2 退出；这与构建失败不同。

6. 审查成本和参数后再启动

   • 交互操作优先使用 Console 或 Latch MCP。
   • Python 自动化优先使用 latch_cli.services.launch.launch_v2。
   • 不要将已弃用的 latch launch CLI 用作新的集成模式。

7. 监控并验证

   • 检查终端状态、任务日志、结果链接和科学输出。
   • 将成功的编排视为科学验证的必要条件，而非充分条件。

运行安全

• 启动付费计算前，尤其是 GPU 或大型批处理任务，先征求确认。
• 执行 LPath.rmr、latch rmr、Registry 删除或覆盖共享目标前，先征求确认。
• 切勿记录机密、SDK 令牌、签名 URL 或机密值。
• 仅在任务内调用 get_secret()，返回值仅用于其预期服务，绝不能将其作为工作流输出返回。
• 不要通过 shell 命令传递不可信字符串。优先使用 subprocess.run(..., check=True) 和参数列表。
• 发布时固定 SDK 和工作流依赖项。只有在审查变更日志并重新运行暂存测试后，才进行升级。
• 将生成的文件视为生成文件：自定义文档说明的扩展文件，而不是 CLI 会覆盖的输出文件。

检查已安装的 SDK

在此技能目录中：

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

权威来源

• 文档索引：https://wiki.latch.bio/llms.txt
• 工作流和 SDK 指南：https://wiki.latch.bio/workflows/overview
• SDK API 参考：https://wiki.latch.bio/reference/sdk
• PyPI 软件包：https://pypi.org/project/latch/
• SDK 2.76.8 发布源码：https://github.com/latchbio/latch/tree/0faa9dcd8186444ac008f50adf95d43f0fa30e06
• SDK 变更日志：https://github.com/latchbio/latch/blob/0faa9dcd8186444ac008f50adf95d43f0fa30e06/CHANGELOG.md
• Latch Console：https://console.latch.bio

相关技能

• dnanexus-integration：使用 dx CLI、dxpy、apps/applets、原生工作流、dxCompiler 和 Nextfl…，在 DNAnexus 上构建和运行可复现的基因组工作负载。
• nextflow：端到端构建、运行和调试 Nextflow 数据管道及 nf-core 工作流。
• benchling-integration：用于 Registry 实体、库存、ELN 条目、工作流、Benchling Apps 和 Data Warehouse… 的 Benchling Python SDK 和 REST API 集成。