opentrons-integration

Opentrons 集成

概述

为 Opentrons Flex 和 OT-2 创建适用于生产环境的 Python Protocol API v2 协议。本技能涵盖协议结构、硬件和甲板配置、液体处理、运行时自定义、模块控制、仿真和安全部署。

截至 2026-07-23，经过验证的基线如下：

• opentrons==9.1.1，用于可复现的 Flex 仿真。
• opentrons==9.0.0，用于与本地 OT-2 API 2.28 兼容的仿真。
• 在当前软件版本中，Flex 支持 API 级别 2.15 至 2.29。
• 在当前软件版本中，OT-2 支持 API 级别 2.0 至 2.28。
• 在此基线下，API 2.29 仅适用于 Flex。不要在 OT-2 协议中使用 2.29。

请阅读 references/sources.md，了解此快照所用的上游文档。若要面向更新的机器人软件版本，请重新查阅官方版本页面。

安全边界

Opentrons 协议会控制物理设备。Python 语法检查通过或本地仿真成功，都不代表可以在机器人上运行。

在实际运行之前：

1. 使用编写协议时所用的相同固定版本 opentrons 在本地进行仿真。
2. 将协议导入正确的 Opentrons App，并确保分析成功。
3. 核实机器人型号、软件、移液器、安装位置、模块、适配器、耗材定义、甲板固定装置、吸头数量、源液体积、死体积和目的容器容量。
4. 与操作员一起检查运行预览和甲板布局图。
5. 如果几何结构、自定义耗材、部分吸头拾取或夹爪移动是新的操作，请使用无害液体进行慢速空运行。
6. 确保急停装置触手可及，并遵循现场的生物安全、化学品安全和污染控制规程。

仿真无法验证物理校准、液体属性、弯月面行为、耗材制造公差、盖子或封膜的移除、管路或所有可能的碰撞情况。

选择正确的接口

对于导入 Opentrons App 并通过 Protocol API 运行的 Python 文件，请使用本技能。

• 对于受支持的无代码工作流，请使用 Protocol Designer。
• 对于跨供应商的硬件无关工作流，请使用 PyLabRobot。
• 请将机器人的 HTTP API 视为独立的集成接口。如果明确要求直接通过 HTTP 控制，请使用目标机器人提供的 OpenAPI 文档，不要根据 Protocol API 方法推断端点。

必需的前置信息

在明确以下信息之前，不要编写最终协议代码：

• 机器人：Flex 或 OT-2，以及已安装的机器人软件。
• 移液器型号、体积范围、通道数和安装位置。
• 模块及其代际；Flex Gripper 或 Stacker 是否可用。
• 确切的耗材 API 加载名称，以及任何自定义定义文件。
• 甲板固定装置：Flex 垃圾桶、废液槽、暂存槽或 Stackers。
• 源液体积、目的液体积、死体积、混匀需求和液体特性。
• 吸头策略：污染边界、重复使用策略、滤芯、部分吸头拾取和吸头总数。
• 操作员干预、孵育时间、运行时参数和输出文件。
• 验收标准：允许的体积误差、必需的对照和空运行计划。

如果任何物理配置尚不确定，请生成参数化草稿和明确的假设列表，而不要猜测。

安装和仿真

Flex：

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

9.1.1 软件包会有意拒绝 Flex/OT-2 发布线拆分之后的 OT-2 协议。请始终在当前的 OT-2 App 中完成 OT-2 分析。

专用 Flex 环境：

uv venv --python 3.10
uv pip install --python .venv/bin/python -r skills/opentrons-integration/requirements-flex.txt
.venv/bin/opentrons_simulate protocol.py

对于 OT-2 兼容环境，请改用 requirements-ot2.txt。在 Windows 上，请运行 .venv\Scripts\opentrons_simulate.exe 中的可执行文件。本地仿真适用于 Python 协议；Protocol Designer JSON 文件应导入相应的 Opentrons App。

协议骨架

Flex，API 2.29

对于 Flex，requirements 为必填项。请仅在 requirements 中指定 apiLevel，不要同时在 metadata 和 requirements 中指定。

from opentrons import protocol_api

metadata = {
    "protocolName": "Flex transfer",
    "author": "Your Name",
    "description": "Transfer buffer into a plate.",
}
requirements = {"robotType": "Flex", "apiLevel": "2.29"}


def run(protocol: protocol_api.ProtocolContext) -> None:
    tips = protocol.load_labware(
        "opentrons_flex_96_tiprack_200ul", "D1"
    )
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "D2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "C2")
    protocol.load_trash_bin("A3")
    pipette = protocol.load_instrument(
        "flex_1channel_1000", "left", tip_racks=[tips]
    )

    pipette.transfer(
        100,
        reservoir["A1"],
        plate["A1"],
        new_tip="always",
    )

OT-2，API 2.28

对于 OT-2 API 2.15 及更高版本，建议使用 requirements 块。OT-2 在 12 号槽位设有固定垃圾桶；不要调用 load_trash_bin()。

from opentrons import protocol_api

metadata = {
    "protocolName": "OT-2 transfer",
    "author": "Your Name",
}
requirements = {"robotType": "OT-2", "apiLevel": "2.28"}


def run(protocol: protocol_api.ProtocolContext) -> None:
    tips = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
    reservoir = protocol.load_labware("nest_12_reservoir_15ml", "2")
    plate = protocol.load_labware("nest_96_wellplate_200ul_flat", "3")
    pipette = protocol.load_instrument(
        "p300_single_gen2", "left", tip_racks=[tips]
    )
    pipette.transfer(100, reservoir["A1"], plate["A1"])

如果协议必须在软件版本不一的设备上运行，请使用能够提供所有必需功能的最低 API 级别。只有当工作流需要当前最高版本的行为或功能时，才使用当前最高版本。

编写工作流

1. 选择机器人和 API 级别

在 App 中检查机器人的高级设置，确认支持的最高 API 级别。使用 references/api_reference.md，将每项所需功能对应到其最低 API 级别。

重要版本门槛：

• 2.20：CSV 运行时参数、液体存在检测、扩展的部分吸头布局。
• 2.21：吸光度酶标仪。
• 2.22：当前版本的实验室器具级液体加载方法。
• 2.23：弯月面位置和实验室器具盖。
• 2.24：液体类别和液体类别复杂命令。
• 2.25：Flex Stacker 和 Flex 96 通道 200 µL 移液器。
• 2.27：动态移液和并发模块操作。
• 2.28：20 µL Flex 吸头、改进的部分吸头退回功能和热循环仪升温速率。
• 2.29：步骤分组；仅适用于已验证基线的 Flex。

2. 明确构建工作台布局

• 使用官方 Labware Library 中的准确加载名称。
• 明确加载 Flex 垃圾桶或废料槽。
• 考虑模块占用空间、暂存槽位、Stacker 穿梭装置、夹爪路径以及高型实验室器具的相邻布局。
• 按照文档所述顺序，将实验室器具加载到适配器或模块环境中。
• 绝不要用名称相似的实验室器具定义替代；几何形状和偏移量属于协议安全模型的一部分。

请参阅 references/modules_and_deck.md。

3. 选择移液器和吸头

当前加载名称如下：

• Flex：flex_1channel_50、flex_1channel_1000、 flex_8channel_50、flex_8channel_1000、 flex_96channel_200、flex_96channel_1000。
• OT-2 GEN2：p20_single_gen2、p20_multi_gen2、 p300_single_gen2、p300_multi_gen2、p1000_single_gen2。

检查每个所需体积是否在已配置的移液器和吸头量程内。100 nL 操作不属于 Opentrons 移液任务。

4. 选择液体处理层

• 使用 aspirate()、dispense()、mix()、air_gap()、blow_out() 和 touch_tip() 进行明确控制。
• 使用 transfer()、distribute() 和 consolidate() 执行标准移液操作。
• 在 Flex 上，可考虑使用 transfer_with_liquid_class()、 distribute_with_liquid_class() 或 consolidate_with_liquid_class()，以采用 Opentrons 验证过的水性、挥发性或黏稠液体处理行为。
• 仅当 API 2.27+ 且几何布局经过审核时，才使用动态起止位置或 dynamic_mix()。

在优化吸头使用之前，先建立污染边界模型。绝不要仅为减少耗材而在无关样品之间重复使用吸头。请参阅 references/liquid_handling.md。

5. 添加设置信息和运行时控件

使用 define_liquid() 和实验室器具级的 load_liquid() 或 load_liquid_by_well()，以改进设置可视化。对于新的 API 2.22+ 协议，不要使用已弃用的 Well.load_liquid()。

在 add_parameters() 中定义由操作员控制的值，并从 protocol.params 读取。验证取值范围，并使用能生成安全且有意义模拟结果的默认值。CSV 参数没有默认值，且每次运行只能选择一个 CSV 参数。

6. 估算资源

模拟前，请计算：

• 每个分支所需的吸头或吸头组数量。
• 源液体积 = 分液体积 + 混匀损耗 + 弃液体积 + 死体积 + 有依据的余量。
• 每次添加和混匀后的目标液体积上限。
• 模块、适配器、垃圾桶和暂存位置的数量。
• 孵育和模块操作所需时间，包括并发任务。

7. 分层验证

1. 编译：python -m py_compile protocol.py。
2. 使用固定版本的软件包进行模拟。
3. 检查运行日志中的命令数量、吸头变化、暂停以及意外位置。
4. 导入相应的 App，并确认分析成功。
5. 检查协议可视化、运行时参数默认值、板位图、模块设置和耗材偏移。
6. 首次使用前，执行由操作员审核的干运行。

参见 references/validation_and_operations.md。

常见故障模式

• 使用 p300_single_flex 等旧名称；请使用当前的 flex_* 加载名称。
• 在 metadata 和 requirements 中同时声明 apiLevel。
• 在 OT-2 上使用 API 2.29。
• 忘记 Flex 垃圾桶或废液槽。
• 在 Flex 上加载 Magnetic Module；请使用受支持的 Flex 磁力硬件。
• 在板读仪上调用 read(wavelengths=...)；应先调用 initialize()，再调用 read()。
• 使用已弃用的 Well.load_liquid()，而不是耗材级方法。
• 误以为模拟能够验证校准、液面高度或物理间隙。
• 将不安全的孔传给部分吸头移液器，这可能导致吸头伸出耗材范围并引发崩溃。
• 对污染要求不兼容的样本使用 new_tip="once"。

随附模板

文件	用途
scripts/basic_protocol_template.py	使用当前名称的最简 Flex 2.29 转移
scripts/ot2_basic_protocol_template.py	最简 OT-2 2.28 转移
scripts/serial_dilution_template.py	使用 8 通道 Flex 移液器进行全板 1:2 稀释
scripts/pcr_setup_template.py	Flex PCR 配置和热循环仪循环
scripts/runtime_parameters_template.py	安全的数值和布尔型运行时参数
scripts/absorbance_reader_template.py	正确的 Flex 板读仪初始化和读取工作流

模板只是起点，并非经过验证的检测方案。只有在确认硬件兼容性和湿实验方法后，才能更改体积、耗材、液体、时间安排和吸头策略。

参考指南

参考资料	用途
references/api_reference.md	当前加载名称、版本要求和重要方法
references/protocol_authoring.md	要求、耗材、运行时参数和设计工作流
references/liquid_handling.md	命令选择、液体类别、感应和部分吸头
references/modules_and_deck.md	模块兼容性、板位配件、抓手和 Stacker
references/validation_and_operations.md	模拟、App 分析、干运行和故障排除
references/migration-api-2-19-to-2-29.md	更新旧协议及本技能以前使用的模式
references/sources.md	官方文档和版本发布来源

相关技能

• pylabrobot：开发和审查 PyLabRobot 实验室自动化资源、液体处理计划、离线模拟和受支持的设备集成。
• protocolsio-integration：使用文档规定的 REST v3/v4 端点和官方 MCP 端点读取、验证并导出 protocols.io 数据，并构建非可执行的…