Latch Registry SDK 实战指南：用 scientific-agent-skills 掌握事务式 Registry 读写与 Samplesheet 集成

Latch Registry SDK 实战指南：用 scientific-agent-skills 掌握事务式 Registry 读写与 Samplesheet 集成

【免费下载链接】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

Latch Registry 是 Latch 平台上的结构化数据管理服务，用于承载生物信息学项目中的项目（Project）、表（Table）与记录（Record）。本指南以 LatchBio Integration 技能 中的 Registry SDK 参考文档 为主体，结合仓库中的 SDK 检测脚本与测试用例，系统讲解 Latch SDK 2.76.8 下基于对象与事务模型的 Registry 读写、事务式更新、DataFrame 批量读取，以及在 workflow 表单中通过SamplesheetItem打通 Registry 与工作流的完整方案。读完本文，你将掌握 Registry 的推荐读写姿势、事务边界控制与错误处理原则，并能直接落地到自己的 Latch workflow 中。

版本基线：为什么锚定latch==2.76.8

Registry 的 API 正处于演进期：当前 Registry API 是对象化（object-based）与事务化（transaction-based）的，而旧版示例中的Project.create、Table.create、Record.create、Record.list、record.update、record.delete等直接调用式写法已与当前 SDK 不匹配，不应再照搬。

技能主文档 给出的基线是Latch SDK 2.76.8（2026-07-10 发布），支持 Python 3.9–3.12，推荐 Python 3.12，使用uv安装。建议在可复现的虚拟环境中操作：

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

在动手前，还可以用仓库自带的 SDK 巡检脚本确认当前安装环境的符号可用性（该脚本只做本地importlib/inspect内省，不发起认证与网络请求）：

uv run --no-project --python 3.12 --with "latch==2.76.8" \ python skills/latchbio-integration/scripts/inspect_latch_sdk.py

需要机器可读的对比输出时加--json，加--strict则会在核心符号缺失时以非零码退出。从脚本源码可以看到，Registry 相关的核心符号被单独归为一组，包括latch.account.Account、latch.registry.project.Project、latch.registry.table.Table、latch.registry.record.Record，并对Table重点探测了load、list_records、get_dataframe、update四个方法——这正是本文要展开的四个核心能力面。对应的测试用例还验证了脚本在 SDK 缺失时优雅降级（退出码 2）、输出可 JSON 序列化、地址脱敏可幂等等契约。

Registry 对象模型：Account → Project → Table → Record

Registry 的数据按四层嵌套组织：

Account (workspace) └── Project └── Table └── Record

• Account对应一个工作区（workspace），是权限与命名空间的边界；
• Project是研究项目容器；
• Table是带列结构的表；
• Record是表中的一行数据记录。

当前推荐导入路径为：

from latch.account import Account from latch.registry.project import Project from latch.registry.record import Record from latch.registry.table import Table

两条必须牢记的标识符规则：

1. 对象一律用数字字符串 ID（numeric-string ID）标识；
2. 显示名（display name）不全局唯一，绝不能当作稳定标识符使用。

后者直接引出一个常见的坑：如果靠"取第一个名字匹配的对象"来推断 ID，在存在同名对象或并发创建时会得到错误对象。这也是下文"一致性与错误处理"中明确禁止的行为。

读取项目与表

读取入口是当前工作区的Account对象：

from latch.account import Account account = Account.current() for project in account.list_registry_projects(): print(project.id, project.get_display_name()) for table in project.list_tables(): print(" ", table.id, table.get_display_name())

这里有两个值得注意的机制：

• 惰性加载与缓存：大多数 getter（如get_display_name()）会惰性调用load()并把结果缓存起来。当另一个进程可能已修改对象、需要拿到最新状态时，应显式调用load()刷新。
• 权限评估：Registry 权限基于当前激活的 CLI 工作区或运行任务的工作区进行评估。这与运维参考文档中的说明一致——latch workspace选择的工作区同时控制未限定的latch:///路径、Registry 访问、workflow 注册与程序化执行。因此，在执行删除等危险操作前，务必先确认当前工作区正确。

读取记录

Table.list_records()是**分页（paginated）**的，逐页返回以记录 ID 为键的字典：

from latch.registry.table import Table table = Table(id="12345") for page in table.list_records(page_size=100): for record_id, record in page.items(): print( record_id, record.get_name(), record.get_values(), record.get_creation_time(), record.get_last_updated(), )

分页参数page_size控制每页大小，适合批量场景下的内存控制。注意：

• 记录名只在所属表内唯一，跨表可能出现重名；
• 需要全局唯一标识时必须使用record.id；
• 明确知道某个记录 ID 时，可直接构造Record对象读取，无需先遍历表：

from latch.registry.record import Record record = Record(id="67890") values = record.get_values() table_id = record.get_table_id()

get_values()返回该记录的列值字典，get_table_id()则能拿到所属表 ID——这个能力在后续 Samplesheet 回写场景中非常关键。

用 DataFrame 批量读取

当需要把整张表读成 DataFrame 做下游分析时，Table.get_dataframe()是直接路径，但它依赖 pandas 额外依赖，需要安装带pandasextra 的 SDK：

uv pip install "latch[pandas]==2.76.8"

frame = Table(id="12345").get_dataframe()

取舍建议（原文档给出的明确指引）：对流式处理或依赖最小化有要求的场景，优先用list_records()分页读取；DataFrame 适合一次性把表载入内存做分析。

事务式更新：创建、写入与删除

Registry 的更新不是即时的直接调用，而是通过上下文管理器排队、上下文成功退出时原子提交：

with <对象>.update() as update: update.xxx(...)

事务失败会阻止该上下文的提交，因此应把一次逻辑更新放进同一个事务，避免"一行一个事务"的低效与部分成功风险。

创建项目

from latch.account import Account account = Account.current() with account.update() as update: update.upsert_registry_project("RNA-seq Studies")

⚠️ 重要语义澄清：尽管方法名带upsert，创建项目/表并不是幂等的——相同显示名调用两次会创建两个对象。这是与一般upsert直觉最大的差异点。

创建表

from latch.registry.project import Project project = Project(id="123") with project.update() as update: update.upsert_table("Samples")

添加列与记录

from latch.registry.table import Table from latch.types import LatchFile table = Table(id="456") with table.update() as update: update.upsert_column("condition", str, required=True) update.upsert_column("replicate", int) update.upsert_column("reads", LatchFile) with table.update() as update: update.upsert_record( "sample-001", condition="treated", replicate=1, reads=LatchFile("latch:///inputs/sample-001.fastq.gz"), )

upsert_record的签名约定：第一个位置参数是记录名，其余为关键字传参的列值；传入了不存在的列会直接报错。因此先建列、再写记录，且列名与关键字严格一致，是推荐的顺序。

支持的列类型包括：字符串、整数、浮点数、日期、日期时间、布尔值、LatchFile、LatchDir、枚举、链接记录（linked records）以及选定的列表形态（selected list forms）。对于更冷门的嵌套类型，原文档建议在动手前先检查已安装 SDK 中TableUpdate.upsert_column的签名实现。

此外，SDK 2.67.22 及以后，TableUpdate.upsert_record还接受LPath值——这与数据管理参考文档中"SDK 2.67.22+ 可在 Registry 中存储LPath"的说明相互印证：

from latch.ldata.path import LPath with table.update() as update: update.upsert_record( "sample-002", reads=LPath("latch:///inputs/sample-002.fastq.gz"), )

删除

删除同样通过对应层级的 updater 排队执行，且删除标识符的规则各层不同：

with table.update() as update: update.delete_record("sample-001") # 记录按名称删除 with project.update() as update: update.delete_table("456") # 表按 ID 删除 with account.update() as update: update.delete_registry_project("123") # 项目按 ID 删除

即：记录删除用记录名，表与项目删除用 ID。删除是破坏性操作，执行前务必确认目标与当前工作区——这也与技能主文档的"操作安全"原则一致：执行 Registry 删除前应先征得确认。

把 Registry 接进 Workflow 表单：Samplesheet 集成

SamplesheetItem的价值在于：当用户在 workflow 表单中从 Registry 导入行时，它会保留源 Registry 记录（Record）的引用，让任务代码在运行期拿到这条记录，从而做回写、状态标记等操作。下面是原文档中的完整可运行示例（一个"Registry 感知的 QC"工作流）：

from dataclasses import dataclass from latch import small_task, workflow from latch.registry.table import Table from latch.types import LatchFile from latch.types.metadata import ( LatchAuthor, LatchMetadata, LatchParameter, ) from latch.types.samplesheet_item import SamplesheetItem @dataclass class SampleRow: sample_name: str reads: LatchFile qc_status: str metadata = LatchMetadata( display_name="Registry-aware QC", author=LatchAuthor(name="Workflow Team"), parameters={ "samples": LatchParameter( display_name="Samples", samplesheet=True, ) }, ) @small_task def process_samples(samples: list[SamplesheetItem[SampleRow]]) -> int: updated = 0 for item in samples: if item.record is None: continue table = Table(id=item.record.get_table_id()) with table.update() as update: update.upsert_record( item.record.get_name(), qc_status="complete", ) updated += 1 return updated @workflow(metadata) def registry_qc(samples: list[SamplesheetItem[SampleRow]]) -> int: return process_samples(samples=samples)

这段代码把前面所有的知识串成了一条闭环：表单中samplesheet=True的LatchParameter接收 Registry 行 → 任务内通过item.record.get_table_id()定位表 → 用item.record.get_name()作为记录名 → 在事务中回写qc_status列。

原文档强调的关键行为：

• item.data是类型化的 dataclass 值（即SampleRow）；
• item.record在从 Registry 导入时为Record对象；
• item.record在手动输入的行中为None——代码中必须判空；
• dataclass 字段尽量与 Registry 列名对齐，便于读写一致；
• 目标表必须已包含任务要写入的列（本例中要先有qc_status列）；
• 当 workflow 不应接受任意 Registry schema 时，用LatchParameter.allowed_tables限制可选表——这与界面与自动化参考文档中allowed_tables用于限制 Registry 导入的指导一致。

一致性与错误处理：生产级 Registry 操作的守则

原文档给出了一组操作性极强的实践守则，归纳如下：

1. 外带变更后重新load()：其他进程改动对象后，缓存会过期，需要显式load()刷新；
2. NotFoundError变体要双重解读：既可能是对象不存在，也可能是权限不足，排查时两者都要考虑；
3. 不要用"第一个匹配显示名的对象"推断 ID：显示名不唯一，这种做法必然不可靠；
4. 事务要聚焦：一次失败会阻止整个上下文的提交，混入无关操作会放大失败面；
5. 避免一行一个事务：单个 updater 能批量提交大量变更时，就把它放进同一次事务；
6. 大批量更新前先校验所有路径与类型：避免事务中途因类型错误整体回滚；
7. 记录溯源（provenance）字段，不要覆盖源元数据：回写状态时只更新自己负责的列，保持数据血缘清晰。

把这些守则与技能主文档的"操作安全"清单（不打印密钥与签名 URL、破坏性操作先确认、发布前固定依赖版本）配合使用，就能在真实项目中把 Registry 读写做得既正确又安全。

结语

Latch Registry SDK 2.76.8 的核心范式可以浓缩为三句话：用对象模型（Account → Project → Table → Record）表达数据、用数字字符串 ID 定位对象、用上下文管理器事务提交变更。读取侧推荐list_records()分页或get_dataframe()批量载入，写入侧遵循"先建列、再写记录、事务聚焦、批量提交"的顺序，再配合SamplesheetItem把 Registry 记录引用带进 workflow 实现状态回写闭环。动手前记得先用仓库自带的 inspect_latch_sdk.py 对照目标 SDK 版本核实符号可用性，并以已安装 SDK 的源码与 changelog 为最终权威。

【免费下载链接】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