Opentrons Integration 是一个用于 Opentrons Flex 和 OT-2 机器人的协议开发技能，目标是帮助用户创建、审查、迁移、模拟和排查官方 Python Protocol API v2 协议。
用途 该技能适用于需要为 Opentrons Flex 或 OT-2 编写生产级 Python 协议的工作流，涵盖协议结构、硬件与工作台配置、液体处理、运行时定制、模块控制、模拟以及安全部署。资料明确指出，如果使用受支持的无代码工作流，应使用 Protocol Designer；如果需要跨厂商的硬件无关工作流，应使用 PyLabRobot；机器人 HTTP API 属于独立的集成面，若明确需要直接 HTTP 控制，应使用目标机器人提供的 OpenAPI 文档，而不是从 Protocol API 方法推断端点。
版本基线 资料给出的验证基线为：Flex 可复现模拟使用 opentrons==9.1.1；OT-2 API 2.28 本地兼容模拟使用 opentrons==9.0.0。Flex 在当前软件上支持 API 2.15 至 2.29，OT-2 支持 API 2.0 至 2.28。API 2.29 在该基线下仅限 Flex，不应放入 OT-2 协议。9.1.1 包在 Flex/OT-2 发布线拆分后会有意拒绝 OT-2 协议，OT-2 分析应在当前 OT-2 App 中完成。
安全边界 Opentrons 协议控制物理设备，因此不能把 Python 语法通过或本地模拟成功当作上机运行的许可。上机执行前需要：使用与编写时相同的固定 opentrons 版本进行本地模拟；将协议导入正确的 Opentrons App 并要求分析成功；核对机器人型号、软件、移液器、安装位、模块、适配器、耗材定义、工作台固定件、吸头数量、源体积、死体积和目标容量；与操作员一起审查运行预览和工作台图；当几何结构、自定义耗材、部分吸头拾取或夹爪移动是新的时，使用非危险液体进行慢速试运行；保持急停可触及，并遵循现场特定的生物安全、化学安全和污染控制程序。模拟无法验证物理校准、液体性质、弯月面行为、耗材制造公差、盖子或密封件移除、管路以及所有可能的碰撞。
必要输入 在编写最终协议代码前，需要明确以下事实：机器人是 Flex 还是 OT-2 以及已安装的机器人软件；移液器型号、体积范围、通道数和安装位；模块及其代次、Flex Gripper 或 Stacker 是否可用；确切的耗材 API 加载名称和自定义定义文件（如有）；工作台固定件，如 Flex 垃圾桶、废液槽、暂存槽或 Stacker；源体积、目标体积、死体积、混合需求和液体特性；吸头策略，包括污染边界、复用策略、滤芯、部分拾取和吸头总数；操作员干预、孵育时间、运行时参数和输出文件；验收标准，包括允许的体积误差、所需对照和试运行计划。如果任何物理配置不确定，应生成参数化草稿和明确的假设列表，而不是猜测。
安装与模拟 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。专用 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 和 OT-2 API 2.28 的骨架示例。Flex 必须提供 requirements，apiLevel 只放在 requirements 中，不要同时放在 metadata 和 requirements 中。OT-2 API 2.15 及以后建议使用 requirements 块；OT-2 在槽位 12 有固定垃圾桶，不要调用 load_trash_bin()。当协议需要跨混合软件版本运行时，应使用能提供所有所需功能的最低 API 级别；仅当工作流需要其行为或能力时才使用当前最高版本。
编写工作流 编写流程包括：选择机器人和 API 级别，检查 App 中机器人高级设置下的最大支持 API，并将每个请求的功能映射到最低 API 级别；显式构建工作台，使用官方 Labware Library 中的确切加载名称，显式加载 Flex 垃圾桶或废液槽，考虑模块占用、暂存槽、Stacker 穿梭、夹爪路径和高耗材相邻关系，按文档顺序在适配器或模块上下文上加载耗材，绝不替换名称相似的耗材定义；选择移液器和吸头，资料列出了 Flex 和 OT-2 GEN2 的当前加载名称，并提醒检查每个请求体积是否在配置的移液器和吸头范围内；选择液体处理层，可使用 aspirate()、dispense()、mix()、air_gap()、blow_out()、touch_tip() 进行显式控制，使用 transfer()、distribute()、consolidate() 进行标准移动，在 Flex 上可考虑 transfer_with_liquid_class() 等方法，动态起始/结束位置或 dynamic_mix() 仅在 API 2.27+ 且几何结构已审查时使用，并在优化吸头前建模污染边界；添加设置信息和运行时控制，使用 define_liquid() 和耗材级 load_liquid() 或 load_liquid_by_well()，不要在新 API 2.22+ 协议中使用已弃用的 Well.load_liquid()，在 add_parameters() 中定义操作员控制值并从 protocol.params 读取；预算资源，计算每个分支所需的吸头或吸头组、源体积、每次添加和混合后的最大目标体积、模块/适配器/垃圾桶/暂存位置数量以及孵育和模块计时；分层验证，包括编译、使用固定包模拟、检查运行日志、导入相应 App 并要求分析成功、检查协议可视化与运行时参数默认值、工作台图、模块设置和耗材偏移，并在首次使用前进行由操作员审查的试运行。
常见失败模式 资料列出多种常见问题：使用旧名称如 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"。
模板与参考 资料附带模板脚本，包括基础 Flex 2.29 转移、基础 OT-2 2.28 转移、使用 8 通道 Flex 移液器的整板 1:2 稀释、Flex PCR 设置与热循环、安全数值和布尔运行时参数、以及正确的 Flex 板读取器初始化与读取工作流。模板是起点而非已验证的检测方法，只有在检查硬件兼容性和湿实验室方法后才能替换体积、耗材、液体、时间和吸头策略。参考文档涵盖 API 参考、协议编写、液体处理、模块与工作台、验证与操作、从 API 2.19 迁移到 2.29 以及官方文档来源。相关技能包括 pylabrobot 和 protocolsio-integration。