Opentrons 协议编写实战指南面向 Flex 与 OT-2 的 Protocol API v2 全流程【免费下载链接】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导读本文基于 scientific-agent-skills 仓库中 opentrons-integration 技能的 Protocol Authoring Guide系统讲解如何将一份湿实验wet-lab方法转化为可审查、可模拟、可安全部署的 Opentrons Python 协议。内容以 Protocol API v2 为主线覆盖协议规范设计、API 级别选择、顶层代码结构、台面Deck清单、耗材定义、液体表示、运行时参数、吸头与污染策略、体积预算、数据依赖以及完整的审查清单。读完本文你将掌握从实验方法到可在 Opentrons App 中通过分析并投入试运行的协议文件的完整工程化路径并理解每一处设计决策背后的安全含义。本文配套代码与验证方法可在仓库以下位置找到SKILL.md、api_reference.md、liquid_handling.md、modules_and_deck.md、validation_and_operations.md以及skills/opentrons-integration/scripts/下的六个可运行模板。1. 把实验方法转化为显式输入先写协议规范再写代码在动手写任何 Python 代码之前先产出一份协议规范protocol specification。Opentrons 协议控制的是物理设备任何先跑起来再说的念头都会把错误放大成真实台面上的碰撞、污染或样品报废。规范应当覆盖以下四类事实。硬件Hardware机器人型号Flex 或 OT-2与已安装的机器人软件版本移液器pipette的 load name、安装臂mount、通道数以及标定过的体积量程所需模块Module及其代际generation是否需要 Flex Gripper、Stacker、废液滑道waste chute、暂存槽位staging slot和废枪头盒trash bin是否有需要人工开盖或移动耗材的操作员动作。硬件信息是台面布局和 API 级别选择的前提。仓库的 modules_and_deck.md 强调模块兼容性既是 API 问题也是物理硬件问题必须同时确认机器人型号、模块代际、caddy 或 adapter、固件、台面位置和耗材再开始编写命令。耗材与实验器具Labware and consumables每个耗材精确的 API load name、namespace 与 definition version每个耗材下方垫的 adapter 或模块吸头容量、是否滤芯头filter tip、枪头盒数量盖子、封膜、管帽以及需要手动移除的步骤自定义耗材 JSON 及其尺寸验证方式。load name 标识的是几何定义而非产品类别这一点在第 5 节会展开。液体与实验约束Liquids and assay constraints初始源体积与死体积dead volume单次转移体积、目标孔数量与目标孔容量黏度、挥发性、起泡风险、是否含会沉降的细胞或磁珠、温度敏感性是否需要预润湿pre-wet、混匀mix、气隙air-gap、延时delay、碰壁touch-tip、吹出blowout或推挤push-out行为污染边界以及是否允许吸头复用。这些约束直接决定后续第 7 节的运行时参数设计、第 9 节的吸头策略和第 10 节的体积预算。操作与运行Operations可在运行时配置的值及其安全默认值必须的操作员暂停与提示信息模块温度、转速、循环曲线与保持hold行为数据输入与输出文件空跑dry-run与验收标准。记录所有尚未经操作员确认的假设并在交付协议时一并给出假设清单assumptions list。仓库 SKILL.md 的Required Intake部分同样强调任何物理配置不确定时宁可产出一个参数化草稿加显式假设清单也不要靠猜测写死。2. 审慎选择 API 级别它决定方法与行为API level 不只是文档标签它同时控制可用的方法集合与运行行为。选择原则在 App 中查看机器人支持的最大级别为每个必需特性找到最低 API 级别取所有最低级别中的最大值仅在方法确实需要某个特定修复或行为时才进一步抬高级别。以 2026-07-23 验证基线为准Flex 最大支持 API 2.29OT-2 最大支持 API 2.28一个同时兼容 Flex/OT-2 的代码生成器不能假定 API 2.29。不要仅仅因为本地新版 Python 包能模拟某个 API就在协议里声明机器人不支持的级别——App 分析会直接判定失败。仓库 api_reference.md 给出了版本基线表与 2.19 之后的高价值特性门控API高价值新增特性2.20CSV 运行时参数、液体存在检测、行/单孔/部分列喷头布局2.21吸光度酶标仪absorbanceReaderV12.22耗材级液体加载方法load_liquid()等、机器人电机控制2.23Well.meniscus()、耗材盖与移盖2.24液体类别liquid classes及高级液体类别复杂命令2.25Flex Stacker、flex_96channel_2002.26flex_96channel_200的液体类别支持2.27并发模块操作、动态吸排液与动态混匀、capture_image()2.28Flex 20 µL 吸头、部分吸头归还、热循环仪升降温速率2.29协议步骤分组step grouping仅 Flex关键结论API 2.29 在当前基线下是 Flex 独占不要把2.29写进 OT-2 协议。3. 保持顶层代码声明式无副作用、单入口一个规范的协议文件通常包含imports、metadata、requirements、可选的参数定义、辅助函数以及唯一的run()入口from opentrons import protocol_api metadata { protocolName: Assay setup, author: Automation Team, description: Prepare an eight-sample assay plate., } requirements {robotType: Flex, apiLevel: 2.29} def add_parameters(parameters: protocol_api.ParameterContext) - None: parameters.add_int( variable_namesample_count, display_nameSample count, default8, minimum1, maximum24, ) def run(protocol: protocol_api.ProtocolContext) - None: sample_count protocol.params.sample_count protocol.comment(fPreparing {sample_count} samples)需要注意禁止顶层副作用不要做顶层网络请求、包安装、读取本地机器路径等操作。协议分析analysis会在受控环境中评估协议而机器人可能没有工作站包或网络访问权限。apiLevel只能出现一处使用requirements后就不要在metadata里再写一次。Flex 的requirements是必需的OT-2 使用 API 2.15 时也推荐写requirements见 api_reference.md。仓库 basic_protocol_template.py 是符合上述结构的完整最小 Flex 模板并演示了protocol.group_steps()API 2.29 步骤分组与protocol.comment()的用法。4. 构建台面清单Deck Manifest先画台面再调加载方法在调用任何load_*方法之前先建立一张简单的台面清单。原文档示例SlotItemAdapter/moduleNotesA3Flex trash bin—Required for dropped tipsC150 µL tip rackFlex tip-rack adapter if requiredLeft pipetteC2Sample rack—Tubes 1–8D1Temperature Module GEN2Aluminum blockMaster mixThermocyclerPCR plateThermocycler Module GEN2Destination然后逐项检查模块与 adapter 的占地面积footprintFlex 第 4 列暂存槽位与第 3 列的冲突热循环仪占用的槽位Heater-Shaker 的间隙与闩锁状态Gripper 的接近路径与耗材兼容性高壁耗材与部分喷头取吸头partial-nozzle pickup的相邻关系盖子与酶标仪盖板移动轨迹是否留足空间。使用有名字的变量与标签而不是plate1这类无意义命名sample_rack protocol.load_labware( opentrons_24_tuberack_nest_1.5ml_snapcap, C2, labelSamples 1-8, )标签会显示在 App 的 setup 视图与运行视图中远胜于泛化名称。仓库 pcr_setup_template.py 中两把移液器、两个枪头盒、试剂管架与热循环仪的实际台面编排可作为参考。关于台面硬件的更多细节Flex 工作台面为 A1–D3暂存区为 A4–D4移液器够不到、但 Gripper 可以够到废液滑道通过protocol.load_waste_chute()加载并固定占用 D3OT-2 使用槽位 1–11槽位 12 是固定废枪头区不要调用load_trash_bin()详见 modules_and_deck.md。5. 使用精确的耗材定义load name 就是安全模型的一部分API load name 标识的是几何定义不是产品类别。规则从 Labware Library 复制 load name当某耗材有多个修订版本时核对 definition version不要用差不多的板或管架替换缺失的定义必要时把精确的自定义耗材 JSON 与协议一起打包验证自定义耗材的尺寸、孔坐标与堆叠偏移首次使用前执行 Labware Position Check或当前 App 的等价功能。放在 adapter 上的耗材应体现物理堆叠关系adapter protocol.load_adapter( opentrons_96_well_aluminum_block, D1, ) plate adapter.load_labware( opentrons_96_wellplate_200ul_pcr_full_skirt )对于模块应调用模块或模块 adapter 的load_labware()方法不要重复传入已经提供给load_module()的台面槽位。模块加载会让该模块成为本次运行的硬性要求——App 在预期模块未连接时不会允许启动见 modules_and_deck.md。仓库 validation_and_operations.md 给出了自定义耗材的验证阶梯校验 JSON schema → 对照厂商图纸与实物测量确认尺寸 → 检查孔深、孔径与总容量 → 检查 corner offset 与孔序 → 为垫在 adapter 上的自定义耗材补充堆叠偏移 → 将精确定义导入 App → 执行 Labware Position Check → 对最高风险的孔与边缘位置做空跑。不要在缺少自定义定义时静默替换为标准耗材。6. 表示初始液体可视化辅助不移动液体液体定义liquid definitions改善 setup 可视化但不会移动或计量液体master_mix protocol.define_liquid( nameMaster mix, description2x PCR master mix, display_color#E377C2, ) reagent_rack.load_liquid( wells[A1], volume500, liquidmaster_mix, )各孔体积不同时使用按孔加载sample_rack.load_liquid_by_well( volumes{A1: 30, A2: 40, A3: 50}, liquidsample, )在 API 2.22 的协议中优先使用耗材级方法而不是已废弃的Well.load_liquid()。声明的体积用于可视化和弯月面meniscus计算不能替代物理 setup 检查也不能替代源体积预算。补充知识来自 liquid_handling.mdAPI 2.23 起还可通过well.meniscus(z..., targetstart/end)获取按液体体积与耗材几何推算出的液面位置配合动态吸排液使用但只有声明的体积、孔几何和液面行为在机器人上验证之后才可依赖弯月面定位。7. 定义运行时参数把可配置留给操作员把安全留给代码运行时参数runtime parameters用于操作员在不编辑代码的前提下设置的值样本数量在已验证范围内的转移体积循环次数孵育时间空跑模式固定的移液器选择或工作流分支CSV 板图。硬件几何与安全关键不变量必须留在代码里除非每一种允许的选择都单独验证过。def add_parameters(parameters: protocol_api.ParameterContext) - None: parameters.add_float( variable_nametransfer_volume, display_nameTransfer volume, descriptionVolume delivered to each destination., default25.0, minimum10.0, maximum40.0, unitµL, ) parameters.add_bool( variable_namedry_run, display_nameDry run, descriptionShorten delays and use test-safe behavior., defaultFalse, )约束要点显示名display name最多 30 字符描述description最多 100 字符数值参数必须带 min/max 范围或枚举选项CSV 参数没有默认值App 与触屏当前每次运行只支持一个 CSV 参数CSV 单元格初始为字符串必须在发出任何命令前解析并校验每一行、每一列、孔名与数值。add_parameters定义的参数在run()内通过protocol.params.variable_name读取见 api_reference.md。可用的参数类型方法包括add_bool、add_int、add_float、add_str与add_csv_fileAPI 2.20。默认值必须保证能成功模拟且绝不能把危险设置作为默认值。仓库 runtime_parameters_template.py 是完整范例它把dry_run的默认值设为True并将孵育延时在空跑时缩短为 1 秒、正式运行时为 60 秒——这正是默认值安全且可模拟的落地写法。该模板还演示了用protocol.group_steps()包裹参数化distribute()、以及reservoir.load_liquid()与plate.load_empty()的可视化配合。8. 组织协议结构配置与重复动作分离把配置与重复动作拆开让重复动作成为可审查的辅助函数def transfer_samples( pipette: protocol_api.InstrumentContext, sources: list[protocol_api.Well], destinations: list[protocol_api.Well], volume: float, ) - None: for source, destination in zip(sources, destinations, strictTrue): pipette.transfer( volume, source, destination, new_tipalways, mix_after(3, min(volume, 20)), )编写指南安全关键的孔序使用显式列表仅在机器人 Python 版本支持时使用zip(..., strictTrue)——当前基线为 Python 3.10支持在生成命令前校验列表长度物理量命名带单位例如volume_ul、temperature_c所有机器人命令放在run()或其调用的辅助函数内让 Protocol API 错误直接中止分析或执行不要大范围捕获异常后继续物理运动需要操作员介入时使用protocol.pause()。特别提醒protocol.comment()的文本是在分析阶段计算的不要用它报告只在物理执行期存在的实时传感器值。类似地validation_and_operations.md 指出复杂命令transfer/distribute/consolidate会在模拟日志中展开为大量基本动作展开结果随参数与 API 级别变化务必检查模拟日志确认命令顺序符合预期。9. 规划吸头与污染先定策略再选 new_tip在选择new_tip之前先定义污染策略always隔离样本或源-目标对消耗最大但最安全once整个复杂命令使用一支吸头仅当所有接触点属于同一污染域时安全never调用方必须已经持有吸头并负责处理丢弃。不安全的优化示例向样本分液后又用同一支吸头回到共享试剂中在阳性和阴性对照之间复用吸头把湿吸头放回枪头盒留作无关用途液体存在检测之后复用吸头——下一次检测要求新鲜、干燥的吸头。多通道吸头按吸头组计数一次完整 8 通道取吸头消耗 8 支一次完整 96 通道取吸头消耗整个枪头盒。计算吸头预算时必须覆盖每个条件分支与重试策略。更多细节来自 liquid_handling.md对共享试剂若吸头从未接触不相容的目标液体用一支吸头反复从同一源吸液或许可接受但浸没式分液可能润湿吸头外壁或内壁而 touch-tip、mix 或底部接触分液都会增加污染风险对照与样本通常必须分开吸头。10. 预算体积把死体积、混合损失与余量算进去对每个源required source volume delivered volume disposal volume mixing and pre-wet loss geometry-dependent dead volume validated reserve对每个目标孔计算最大中间体积不只是最终期望体积包括混匀行程、carryover 拆分以及后续转移前遗留在孔内的任何物料。不要让移液器工作在支持量程之下。例如 100 nL 低于当前所有 Opentrons 移液器的量程需要不同的分液技术或重新设计的稀释方案。参考 api_reference.md 的量程表如flex_1channel_50为 1–50 µL、flex_1channel_1000为 5–1000 µLOT-2 的p300_single_gen2为 20–300 µL、p1000_single_gen2为 100–1000 µL。混合时选择低于可用液体体积与移液器上限的混匀体积并考虑磁珠、细胞、起泡与封膜等因素。一个直观范例serial_dilution_template.py 要求源槽 A1 至少 12 mL 稀释液、第 1 列每孔 200 µL 原液它填充第 2–12 列各 100 µL 稀释液、逐列串联转移 100 µL、再从第 12 列移除 100 µL使每孔最终恰好 100 µL——每一步的源余量、目标中间体积与最终吸头预算都经过预先核算。11. 数据与依赖CSV 进、固定资源打包、运行中不联网操作员提供的表格数据优先使用运行时 CSV 参数工作流需要固定资源时把静态数据与协议一起打包在生成任何机器人命令之前校验文件 schema、必需列、允许的孔名、体积范围、重复项与总体积运行期间不下载数据或安装包不把凭据写进协议也不让协议依赖宽泛的环境变量访问固定本地用于模拟的opentrons包版本但始终记住机器人执行的是它自身安装的软件栈。仓库 validation_and_operations.md 补充了模拟器的数据文件用法opentrons_simulate -d plate_map.csv protocol.py只加载命名的数据文件可重复-d-D会加载目录内所有文件到内存绝不指向含凭据、无关数据或大文件的目录。12. 发布前审查清单Review Checklist对照清单逐项确认机器人与 API 级别正确移液器 load name 为当前名称且吸头兼容耗材定义与 adapter 精确Flex 废枪头盒或废液滑道已显式声明无台面冲突、无可达性问题的部分喷头目标源与目标体积预算通过吸头数量覆盖每个分支与重试策略污染策略已文档化运行时参数默认值安全且可模拟模块状态转换完整每个操作员暂停都有可执行的提示信息本地模拟与 App 分析均成功新几何已由非危险空跑覆盖。13. 从编写到上线分层验证与常见失败模式分层验证阶梯按仓库 validation_and_operations.md 与 SKILL.md 的约定验证是分层的语法通过或本地模拟成功都不等于可以上机编译python -m py_compile protocol.py只查语法不实例化 Protocol API 对象本地模拟使用钉死的包版本模拟Flex 用uv run --with opentrons9.1.1 opentrons_simulate protocol.pyOT-2 用uv run --with opentrons9.0.0 opentrons_simulate protocol.py资源审计独立核算吸头组数、源体积预算、目标最大中间体积、含气隙的移液器容量、台面位置数、盖子与 Gripper 路径、最坏参数下的运行时长App 分析在目标机器人对应的 App 中导入协议与所需自定义耗材/数据要求分析成功审查起始台面、模块 setup、运行时参数、可视化与偏移量操作员复核二次确认协议修订号、台面图与实物、耗材朝向、吸头类型与数量、源身份与体积、目标容量、手动步骤、废料容量与紧急停止空跑dry run用去离子水等已验证的非危险替代物移除珍贵样品与危险试剂从低风险几何和降速开始观察每一次 Gripper、盖子、Stacker 与部分喷头动作受控发布记录协议文件哈希/版本、本地模拟所用opentrons版本、机器人软件与 App 版本、自定义耗材定义、运行时参数记录、空跑与鉴定结果。补充opentrons9.1.1在 Flex/OT-2 发布线拆分后故意拒绝 OT-2 协议OT-2 的权威分析始终在当前的 OT-2 App 中完成。模拟器还提供-l info更详细日志、-L自定义耗材目录可重复、-e实验性耗时估算等选项。可以这样核验本地包的 API 能力上限uv run --with opentrons9.1.1 python -c \ import opentrons; from opentrons import protocol_api; print(opentrons.__version__, protocol_api.MAX_SUPPORTED_VERSION)模拟无法验证的内容移液器标定或机械磨损耗材制造公差与摆放误差真实瓶盖、封膜、盖子、变形板或障碍物实际液体体积或身份黏度、挥发性、表面张力、起泡或气溶胶磁珠沉降、沉淀位置或细胞沉降所选液体下的可靠液面检测Gripper 摩擦与每一种碰撞场景模块在样品内的热平衡酶标仪光学性能模拟读数恒为 0操作员对暂停提示的执行。常见失败模式速查仓库 SKILL.md 归纳了高频错误写作时逐条规避使用旧名称如p300_single_flex应使用当前flex_*load names在metadata与requirements同时声明apiLevel给 OT-2 使用 API 2.29忘记 Flex 废枪头盒或废液滑道在 Flex 上加载 OT-2 的带电 Magnetic ModuleFlex 应使用无源 Magnetic Block酶标仪未先initialize()就read(wavelengths...)使用已废弃的Well.load_liquid()而非耗材级方法假定模拟能验证标定、液面高度或物理间隙把不安全的孔传给部分喷头移液器可能把吸头送到耗材之外造成碰撞在不满足污染要求的样本之间使用new_tiponce。仓库模板速查skills/opentrons-integration/scripts/提供六个可直接模拟的起点模板是起点不是已验证的检测方法替换任何体积、耗材、液体、时序与吸头策略前都要重新核对硬件兼容性与湿实验方法文件用途basic_protocol_template.py最小 Flex 2.29 转移模板ot2_basic_protocol_template.py最小 OT-2 2.28 转移模板serial_dilution_template.py8 通道 Flex 全板 1:2 梯度稀释pcr_setup_template.pyFlex PCR 配样与热循环仪跑循环runtime_parameters_template.py安全的数值与布尔运行时参数absorbance_reader_template.pyFlex 酶标仪正确的 initialize/read 工作流结语Opentrons 协议编写是一道把湿实验方法翻译成可审查的显式状态机的工程问题。本文梳理的十二步流程——从协议规范、API 级别、声明式顶层结构、台面清单、精确耗材、液体可视化、运行时参数、代码组织、吸头与污染策略、体积预算、数据依赖到发布审查——构成了一个可复用、可审计、可安全落地的编写范式。任何一步的省略最终都会以物理台面上不可挽回的方式暴露出来。配合仓库中的 Protocol Authoring Guide、API Reference、Liquid Handling Guide、Modules and Deck Guide 与 Validation and Operations Guide你可以在任何新实验方法进入 Flex 或 OT-2 之前先把它变成一份经过模拟、审查与空跑验证的安全协议。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考