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 基线其核心版本组合如下目标版本FlexProtocol API 2.29OT-2Protocol API 2.28Flex 本地模拟器opentrons9.1.1OT-2 本地兼容模拟器opentrons9.0.0随后在 OT-2 App 中完成分析这两个本地模拟环境由仓库中的 requirements-flex.txtopentrons9.1.1与 requirements-ot2.txtopentrons9.0.0分别固定。如 api_reference.md 所确认当前软件下 Flex 支持 API 2.15–2.29OT-2 支持 API 2.0–2.28。关键警告不要机械地只改 API 版本字符串。新级别会改变命令验证规则与行为语义如 command validation 和运行行为只改字符串而不审计调用协议可能仍然无法通过 App 分析甚至在物理运行时产生危险动作。1. 确定目标机器人API 2.29 在本基线下不支持 OT-2OT-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模式已失效旧或错误的模式当前应选名称p50_single_flexflex_1channel_50p50_multi_flexflex_8channel_50p1000_single_flexflex_1channel_1000p1000_multi_flexflex_8channel_1000p300_single_flex无直接等价物按验证过的体积需求选flex_1channel_50或flex_1channel_1000p300_multi_flex无直接等价物按验证过的体积需求选flex_8channel_50或flex_8channel_1000此外还提供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–D4pipette 够不到、Gripper 可以废料桶需在 column-1 或 column-3 支持槽位显式装载load_waste_chute()固定占用 D3两者不可同时占 D3。只装载本次运行物理安装的固件。4. 更新液体装载API 2.22Well.load_liquid()已弃用且当前包中不存在Well.load_empty()。两者都应迁移到 labware 级 API# 迁移前弃用/不存在 reservoir[A1].load_liquid(liquidbuffer, volume10_000) plate[A1].load_empty() # 迁移后 reservoir.load_liquid( wells[A1], volume10_000, liquidbuffer, ) plate.load_empty(wells[A1])逐孔体积不一致时使用load_liquid_by_well()plate.load_liquid_by_well( volumes{A1: 20, B1: 30}, liquidsample, )仓库 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_base6.5)当前 Flex 模式正确magnetic_block protocol.load_module(magneticBlockV1, C2) protocol.move_labware( labwareplate, new_locationmagnetic_block, use_gripperTrue, ) protocol.delay(minutes5) protocol.move_labware( labwareplate, new_locationB2, use_gripperTrue, )Magnetic Block 是被动硬件没有engage()或disengage()方法——磁珠分离靠 Gripper 把兼容 labware 移上/移下模块来完成。modules_and_deck.md 补充确认Flex 使用被动 Magnetic BlockmagneticBlockV1API 2.15OT-2 使用带电 Magnetic Modulemagnetic 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(modemulti, wavelengths[450, 650]) reader.open_lid() protocol.move_labware( labwareplate, new_locationreader, use_gripperTrue, ) reader.close_lid() result reader.read(export_filenameabsorbance)模拟期间读板机返回全 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( volumevolumes, sourcereservoir[A1], destplate.wells()[:4], new_tipalways, )不常见的选项必须对照当前方法与 API 级别的精确签名核对。标准命令与 liquid-class 命令支持的选项并不完全相同。api_reference.md 列出常见复杂命令选项包括new_tipalways/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.22labware 级液体装载。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.25Flex Stacker。Flex 96 通道 200 µL 移液器。API 2.2696 通道 200 µL 移液器的液体类别支持。API 2.27并发模块任务。动态吸液、分液与混匀路径。内置相机拍照。液体类别转移的显式 tip。API 2.28Flex 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 步执行迁移测试保留原始协议与预期运行日志。更新声明与装载名。替换弃用或无效调用。使用机器人专属版本模拟Flex 用opentrons9.1.1OT-2 用opentrons9.0.0。对比命令顺序、tip 使用、源/目标映射与模块状态。测试每个运行时参数分支。导入到正确的 App 与目标机器人。解决所有分析警告与错误。执行一次非危险干跑dry run。生产使用前重新确认实验性能。不要仅凭模拟成功就宣称迁移等价。仓库提供了完整的本地模拟命令与验证阶梯见 SKILL.md 与 validation_and_operations.md# FlexAPI 2.29 uv run --with opentrons9.1.1 opentrons_simulate protocol.py # OT-2API 2.28 兼容模拟 uv run --with opentrons9.0.0 opentrons_simulate protocol.py注意opentrons9.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最小 Flex 2.29 转移协议含新命名与 group_stepsot2_basic_protocol_template.py最小 OT-2 2.28 转移协议serial_dilution_template.py8 通道 Flex 全板 1:2 倍比稀释pcr_setup_template.pyFlex PCR 建板与 Thermocycler 循环runtime_parameters_template.py安全的数值与布尔运行时参数absorbance_reader_template.py正确的 Flex 读板机初始化与读取流程例如 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 各版本行为变化的逐条核对。以本技能固定版本Flexopentrons9.1.1/ OT-2opentrons9.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考