Opentrons Protocol API v2 从 2.19 迁移到 2.29 基线：Flex 与 OT-2 协议升级实战指南

Opentrons Protocol API v2 从 2.19 迁移到 2.29 基线：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

本文以scientific-agent-skills仓库中 opentrons-integration 技能的迁移文档 migration-api-2-19-to-2-29.md 为骨架，系统讲解如何把基于机器人软件 7.3.1、Protocol API 2.19 编写的旧协议升级到 2026-07-23 验证基线（Flex API 2.29 / OT-2 API 2.28）。读完本文，你将掌握版本与机器人选型、pipette 新命名、Flex 废料与磁力工作流改造、液体装载 API 迁移、板式读板机调用、复杂命令清理、行为变化清单以及完整的分层迁移测试计划，并了解仓库内对应的源码模板与验证工具。

迁移基线概览

迁移的目标是把围绕robot software 7.3.1 和 Protocol API 2.19编写的协议更新到本技能验证的 2026-07-23 基线，其核心版本组合如下：

这两个本地模拟环境由仓库中的 requirements-flex.txt（opentrons==9.1.1）与 requirements-ot2.txt（opentrons==9.0.0）分别固定。如 api_reference.md 所确认，当前软件下 Flex 支持 API 2.15–2.29，OT-2 支持 API 2.0–2.28。

关键警告：不要机械地只改 API 版本字符串。新级别会改变命令验证规则与行为语义（如 command validation 和运行行为），只改字符串而不审计调用，协议可能仍然无法通过 App 分析，甚至在物理运行时产生危险动作。

1. 确定目标机器人

API 2.29 在本基线下不支持 OT-2，OT-2 协议必须停留在 2.28：

# Flex requirements = {"robotType": "Flex", "apiLevel": "2.29"} # OT-2 requirements = {"robotType": "OT-2", "apiLevel": "2.28"}

同时要求只声明一次apiLevel。旧文件经常同时写在metadata和requirements里，当前分析会直接拒绝这种写法：

# 迁移前（错误：apiLevel 声明了两处） metadata = {"apiLevel": "2.19", "protocolName": "Example"} requirements = {"robotType": "Flex", "apiLevel": "2.19"} # 迁移后（正确：只保留在 requirements） metadata = {"protocolName": "Example"} requirements = {"robotType": "Flex", "apiLevel": "2.29"}

如果协议必须兼容更旧的机器人软件，则保持 2.19，只应用该级别可用的改动。如 api_reference.md 所述，Flex 始终强制要求requirements块，OT-2 使用 API 2.15+ 时也建议加上；选择 API 级别的最低原则是"取能覆盖全部所需特性的最低级别"，混合软件机群运行时尤其如此。

2. 替换错误的 Flex Pipette 名称

当前 Flex 装载名（load name）描述的是通道数与量程，旧的p*_flex模式已失效：

此外还提供：

• flex_96channel_200—— API 2.25+。
• flex_96channel_1000。

选择时不能只依据最大单次转移体积，必须把每一步操作放到 pipette 的上下量程与兼容 tip 容量范围内核对。OT-2 GEN2 名称保持不变：p20_*_gen2、p300_*_gen2和p1000_single_gen2。

仓库 api_reference.md 给出了完整的名义量程表：例如flex_1channel_50为 1–50 µL、flex_1channel_1000为 5–1000 µL、flex_96channel_200为 1–200 µL，并提醒 96 通道移液器占用两个挂架，API 2.16 起其mount参数可选。SKILL.md 的 Common Failure Modes 中亦将"使用p300_single_flex等旧名称"列为首要故障模式。

3. 让 Flex 废料收集显式化

Flex 的 API 2.16+ 协议应当装载实际安装的固件/配件：

trash = protocol.load_trash_bin("A3")

或者：

chute = protocol.load_waste_chute()

OT-2 保留 12 号槽的固定废料仓，不要调用load_trash_bin()。若协议中同时存在废料桶与废料槽，需设定 pipette 预期的废料容器，或向复杂命令传递文档规定的trash_location。

从 modules_and_deck.md 的甲板模型可知：Flex 工作区为 A1–D3，暂存区为 A4–D4（pipette 够不到、Gripper 可以），废料桶需在 column-1 或 column-3 支持槽位显式装载；load_waste_chute()固定占用 D3，两者不可同时占 D3。只装载本次运行物理安装的固件。

4. 更新液体装载：API 2.22+

Well.load_liquid()已弃用，且当前包中不存在Well.load_empty()。两者都应迁移到 labware 级 API：

# 迁移前（弃用/不存在） reservoir["A1"].load_liquid(liquid=buffer, volume=10_000) plate["A1"].load_empty() # 迁移后 reservoir.load_liquid( wells=["A1"], volume=10_000, liquid=buffer, ) plate.load_empty(wells=["A1"])

逐孔体积不一致时使用load_liquid_by_well()：

plate.load_liquid_by_well( volumes={"A1": 20, "B1": 30}, liquid=sample, )

仓库 api_reference.md 中的液体可视化示例还展示了配套的液体定义方式：先用protocol.define_liquid(name, description, display_color)定义液体，再在 labware 上装载。这些方法的主要价值在于改善 App 中的 setup 可视化，SKILL.md 明确要求新 API 2.22+ 协议不再使用已弃用的Well.load_liquid()。

5. 更新 Adapter 装载

ProtocolContext.load_labware_on_adapter()已不是当前方法。正确顺序是先装载 adapter，再调用 adapter 自己的方法：

adapter = protocol.load_adapter( "opentrons_96_well_aluminum_block", "D1", ) plate = adapter.load_labware( "opentrons_96_wellplate_200ul_pcr_full_skirt" )

部分load_labware()调用也可为支持的堆叠组合传入adapter=装载名。应始终参照当前官方文档针对确切硬件的写法。从源码结构看，modules_and_deck.md 中 Temperature Module 的装载示例也遵循"模块 → adapter → labware"的嵌套顺序，这正是当前 API 的推荐模式。

6. 修正 Flex 磁力工作流

带电的 Magnetic Module 仅限 OT-2。旧的 Flex 模式（错误）：

magnetic_module = protocol.load_module( "magnetic module gen2", "C2", ) magnetic_module.engage(height_from_base=6.5)

当前 Flex 模式（正确）：

magnetic_block = protocol.load_module("magneticBlockV1", "C2") protocol.move_labware( labware=plate, new_location=magnetic_block, use_gripper=True, ) protocol.delay(minutes=5) protocol.move_labware( labware=plate, new_location="B2", use_gripper=True, )

Magnetic Block 是被动硬件，没有engage()或disengage()方法——磁珠分离靠 Gripper 把兼容 labware 移上/移下模块来完成。modules_and_deck.md 补充确认：Flex 使用被动 Magnetic Block（magneticBlockV1，API 2.15+），OT-2 使用带电 Magnetic Module（magnetic module/magnetic module gen2），且 Magnetic Module 已停产但继续为存量 OT-2 硬件提供支持；OT-2 的engage(height_from_base=...)高度因 labware 与实验而异，不能从其他板随意复制。

7. 修正吸光度板式读板机调用

读板机（Absorbance Plate Reader）在 API 2.21 加入，仅限 Flex，且不接受read(wavelengths=[...])。

错误写法：

result = plate_reader.read(wavelengths=[450, 650])

正确流程（先初始化，再读数）：

reader = protocol.load_module("absorbanceReaderV1", "D3") reader.close_lid() reader.initialize(mode="multi", wavelengths=[450, 650]) reader.open_lid() protocol.move_labware( labware=plate, new_location=reader, use_gripper=True, ) reader.close_lid() result = reader.read(export_filename="absorbance")

模拟期间读板机返回全 0，仿真分支中要避免除零逻辑。仓库 absorbance_reader_template.py 给出了完整模板：它用protocol.group_steps()（API 2.29 特性）组织"Initialize Reader / Load and Read Plate / Unload Plate"三个步骤组，并在读板后将板移回 C2。modules_and_deck.md 还给出读板机数据格式dict[int, dict[str, float]]（第一层键为波长、第二层为孔名）、默认硬件波长 450/562/600/650 nm，以及仿真防护写法：

if not protocol.is_simulating(): normalized = data[450]["A1"] / data[450]["H12"]

8. 移除不支持的复杂命令选项

不要因为旧参考文档列出了某个选项就保留它。例如，gradient=(start, end)不是当前 API 的通用transfer()选项。改为显式构造经过验证的体积列表：

volumes = [10, 20, 30, 40] pipette.transfer( volume=volumes, source=reservoir["A1"], dest=plate.wells()[:4], new_tip="always", )

不常见的选项必须对照当前方法与 API 级别的精确签名核对。标准命令与 liquid-class 命令支持的选项并不完全相同。api_reference.md 列出常见复杂命令选项包括new_tip（"always"/"once"/"never"）、mix_before、mix_after、touch_tip、blow_out、blowout_location、disposal_volume、trash_location等，并强调"不同命令与 API 级别支持的选项不同"，这正是本节规则的工具级佐证。

9. 重审行为变化

以下按 API 级别列出 2.19 之后引入的关键行为变化，迁移时应逐条核对协议是否受其影响：

API 2.20

• 液体存在检测（liquid presence detection）。
• CSV 运行时参数。
• 扩展的 partial-nozzle 布局。

API 2.21

• 吸光度板式读板机。
• 液体存在检测只在一次mix()循环的首次吸取执行。

API 2.22

• labware 级液体装载。
• Well.load_liquid()弃用。
• 低层机器人电机控制。

API 2.23

• 弯月面位置（meniscus locations）。
• labware 盖与盖板移动。
• labware offset 行为与新版 App 检查对齐。

API 2.24

• 已验证与自定义液体类别（liquid classes）。
• transfer_with_liquid_class()、distribute_with_liquid_class()、consolidate_with_liquid_class()。
• 额外的流速、延迟、位置与 push-out 选项。

API 2.25

• Flex Stacker。
• Flex 96 通道 200 µL 移液器。

API 2.26

• 96 通道 200 µL 移液器的液体类别支持。

API 2.27

• 并发模块任务。
• 动态吸液、分液与混匀路径。
• 内置相机拍照。
• 液体类别转移的显式 tip。

API 2.28

• Flex 20 µL tip。
• 改进的部分吸 tip 归还。
• 绝对 blowout 定制。
• Thermocycler 变温速率（ramp-rate）控制。
• set_empty()tip 架状态。
• 大空间内不安全的touch_tip()会报错。

API 2.29

• 源程序与协议可视化的步骤分组（step grouping）。
• 在本迁移基线中仅限 Flex。

关于 liquid-class 命令，api_reference.md 补充了实操细节：通过protocol.get_liquid_class("water")获取类，Opentrons 已验证的类别包括 water、80% 乙醇、50% 甘油，兼容性取决于具体 Flex pipette 与 tip 组合；API 2.24+ 还支持define_liquid_class()自定义。

10. 重审模块与甲板假设

迁移时检查旧代码中可能隐藏的甲板/模块假设：

• Flex 废料桶或废料槽未在旧代码中体现。
• 暂存区与 column-3 的冲突。
• 新的 Gripper 或盖板移动。
• Heater-Shaker 闩锁状态。
• Thermocycler 代际与占地。
• 读板机 caddy 与盖板行程。
• Stacker 穿梭路径。
• 96 通道全列与部分列取 tip 的 tip-rack adapter 要求。

API 分析已大幅改进，一个新出现的甲板冲突错误可能恰恰揭示旧协议中一个从未在物理上安全的假设——此时应把该错误视为真实风险信号，而不是绕过它。SKILL.md 的 Authoring Workflow 同样强调"永远不要用名字相似但不同的 labware 定义做替换，几何与 offset 是协议安全模型的一部分"。

11. 重新验证 Tip 与体积策略

不要假设新版移液行为会产生与旧版等同的实验结果。迁移后必须：

• 重新计算 tip 数量。
• 重新计算源体积与死体积。
• 在运行日志中确认复杂命令的展开结果。
• 重新确认流速、混匀行为、底部间隙、气隙与 blowout。
• 复查污染策略。
• 复查多通道与 partial-nozzle 的孔定位。

validation_and_operations.md 的资源审计清单可作核对依据：独立核算每根 tip/每组多通道 tip、源体积（含分液弃液、死体积、混匀损耗与储备）、每个目标孔的最大中间体积、含气隙的移液器容量、模块/适配器/暂存/废料位置、盖板与 Gripper 路径，以及最坏参数下的运行时长。模拟成功并不能证明液体预算充足。

12. 迁移测试计划

按以下 10 步执行迁移测试：

1. 保留原始协议与预期运行日志。
2. 更新声明与装载名。
3. 替换弃用或无效调用。
4. 使用机器人专属版本模拟：Flex 用opentrons==9.1.1，OT-2 用opentrons==9.0.0。
5. 对比命令顺序、tip 使用、源/目标映射与模块状态。
6. 测试每个运行时参数分支。
7. 导入到正确的 App 与目标机器人。
8. 解决所有分析警告与错误。
9. 执行一次非危险干跑（dry run）。
10. 生产使用前重新确认实验性能。

不要仅凭模拟成功就宣称迁移等价。

仓库提供了完整的本地模拟命令与验证阶梯（见 SKILL.md 与 validation_and_operations.md）：

# Flex（API 2.29） uv run --with "opentrons==9.1.1" opentrons_simulate protocol.py # OT-2（API 2.28 兼容模拟） uv run --with "opentrons==9.0.0" opentrons_simulate protocol.py

注意opentrons==9.1.1在 Flex/OT-2 发布线拆分后有意拒绝 OT-2 协议，OT-2 分析必须始终在 OT-2 App 中完成。模拟器还支持-l info（更多诊断日志）、-L（自定义 labware 目录）、-d（仅加载指定数据文件）、-e（实验性耗时估算）等选项；优先用-d而非-D，因为-D会把整个目录载入内存。迁移后若出现"unsupported API version / 无效 pipette 或 labware 装载名 / 甲板冲突 / tip 不足 / 源体积不足 / 模块未就绪 / 仅仿真时读板机计算失败"等问题，validation_and_operations.md 的 Failure Triage 章节提供了逐项排查清单。

仓库内的可复用模板

本技能随附 6 个可直接作为迁移起点的模板（见 scripts 目录）：

例如 basic_protocol_template.py 演示了完整的迁移后骨架：requirements单独声明 API 2.29、load_trash_bin("A3")显式废料、flex_1channel_1000新名称、define_liquid()+reservoir.load_liquid()的 API 2.22+ 液体装载，以及group_steps()步骤分组。这些模板只是起点而非验证过的实验方案，替换体积、labware、液体、时序与 tip 策略前，必须核对硬件兼容性与湿实验方法。

结语

Protocol API 2.19 → 2.29 的迁移远不止改一个版本字符串：它涉及机器人选型约束（2.29 仅 Flex）、pipette 命名体系更新、废料与模块工作流重构（Magnetic Block 被动化、读板机先初始化后读取）、液体装载 API 换代，以及 2.20–2.29 各版本行为变化的逐条核对。以本技能固定版本（Flexopentrons==9.1.1/ OT-2opentrons==9.0.0）做本地模拟，再走完 App 分析、干跑与实验性能再确认的分层验证阶梯，是让迁移后的协议既通过分析又物理安全的可靠路径。

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