Opentrons 模块与甲板布局实战指南Flex/OT-2 兼容性、加载与并发控制scientific-agent-skills【免费下载链接】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 技能模块的references/modules_and_deck.md文档展开系统讲解 Opentrons Flex 与 OT-2 机器人的模块兼容性、甲板deck模型、模块加载方式以及温度模块、加热振荡器、热循环仪、磁性硬件、酶标仪、Stacker 等核心硬件的协议 API 用法。读完本文你将掌握如何为正确的机器人选择正确的模块 load name、如何在甲板上安全布署模块与耗材、如何编写从加载到收尾的完整模块控制代码以及如何利用 API 2.27 的并发机制和仓库自带的模板脚本与测试进行验证。本文基线以仓库 SKILL.md 记载的 2026-07-23 快照为准Flex 支持 API 2.15–2.29OT-2 支持 2.0–2.28API 2.29 仅限 Flex。仓库 api_reference.md 已按此基线校验过每个模块 load name 与最低 API 版本。一、模块兼容性既是 API 问题也是物理硬件问题Opentrons 的模块兼容性从来不是一个单纯的 API 问题即使 load name 合法物理硬件机器人型号、模块代数、caddy/适配器、固件、甲板槽位、耗材不匹配协议依然无法运行。在编写任何命令之前必须先确认这五件事机器人型号、模块代数、caddy 或适配器、固件、甲板位置与耗材。下表来自 modules_and_deck.md 的官方兼容快照是编写load_module()的第一手依据硬件FlexOT-2Protocol API load nameAbsorbance Plate Reader酶标仪YesNoabsorbanceReaderV1Flex StackerYesNoflexStackerModuleV1Heater-Shaker GEN1加热振荡器YesYesheaterShakerModuleV1Magnetic Block GEN1磁性底座YesNomagneticBlockV1Magnetic Module GEN1/GEN2磁性模块NoYesmagnetic module/magnetic module gen2Temperature Module GEN2温度模块YesYestemperature module gen2Thermocycler GEN2热循环仪YesYesthermocyclerModuleV2四条关键注意事项Flex 使用被动式 Magnetic Block。带电机的 OT-2 Magnetic Module 不受 Flex 支持反之亦然——这是最常见的load name 合法但硬件不匹配错误。Flex 上的 Thermocycler 必须为 GEN2以保证与 Gripper 兼容的操作如抓取移板。较老代际的模块可能只支持 OT-2。load name 必须与硬件标签严格对应例如magnetic module与magnetic module gen2是两个不同的 load name。HEPA/UV 附件属于 Flex 操作的一部分但它不作为 Protocol API 模块加载与控制——不要在协议里试图load_module()它。仓库 api_reference.md 的 Module Load Names 一节进一步给出了每个模块的最低 API 版本门控例如temperature module gen2需 API 2.3、thermocyclerModuleV2需 API 2.13、absorbanceReaderV1需 API 2.21、flexStackerModuleV1需 API 2.25。选 load name 时务必交叉核对机器人型号、物理代际和 API 级别三者。二、甲板模型Deck ModelsFlex 与 OT-2 完全不同Flex 使用坐标式槽位A1–D4OT-2 使用数字槽位1–11两者的甲板物理布局、垃圾桶/废料口配置与 Gripper 能力截然不同。仓库 test_scripts.py 中甚至有专门的测试断言Flex 模板的所有槽位必须匹配^[A-D][1-4]$OT-2 模板的所有槽位必须是纯数字。Flex 甲板工作甲板A1–D3移液器与 Gripper 均可到达。暂存区staging areaA4–D4移液器无法到达但Gripper 可以。它是为中途暂存板、Stacker 穿梭仓等保留的区域。垃圾桶trash bin需在支持的 column-1 或 column-3 槽位显式加载例如 A3。废料口waste chute通过protocol.load_waste_chute()加载固定占用D3。垃圾桶和废料口不能同时装在 D3。带电源的模块 caddy 与暂存槽位可能在同一行产生冲突布板时需检查同行占用。Column-4 的硬件可以预留或穿过对应的 column-3 位置例如 Stacker 穿梭仓的移动路径这是甲板规划中容易忽略的干涉源。trash protocol.load_trash_bin(A3) chute protocol.load_waste_chute() # D3 only; do not load both into D3只加载本次运行物理上真实安装的 fixtures。仓库模板严格遵守这一规则例如 basic_protocol_template.py 和 serial_dilution_template.py 都在 A3 显式加载垃圾桶。测试 test_scripts.py 还验证了任何加载了移液器的 Flex 模板都必须调用load_trash_bin()——因为 Flex 没有固定垃圾桶不声明丢弃位置会导致分析失败。OT-2 甲板用户甲板槽位1–11。固定垃圾桶fixed trash槽位 12不要调用load_trash_bin()——OT-2 上这是一个错误。没有 Gripper、没有暂存区。耗材移动是手动操作员动作协议无法用 Gripper 自动搬板。对应地ot2_basic_protocol_template.py 中只有注释提到槽位 12 的固定垃圾桶测试 test_scripts.py 断言该模板的调用集合中不存在load_trash_bin。这份按机器人区分垃圾桶策略正是两个机器人甲板模型差异的直接体现。三、模块加载load_module 与 run 前置条件模块通过protocol.load_module(module_name, location)加载。关键语义是加载一个带电模块就使其成为 run requirement——如果实际连接的模块缺失或与 load name 不匹配Opentrons App 会在 run 开始前阻止运行。heater_shaker protocol.load_module( module_nameheaterShakerModuleV1, locationD1, )耗材通过模块加载此时耗材的甲板位置由模块决定plate heater_shaker.load_labware( corning_96_wellplate_360ul_flat, labelMixing Plate, )当存在独立适配器adapter时需要先load_adapter()再在适配器上load_labware()temperature_module protocol.load_module( temperature module gen2, D3, ) adapter temperature_module.load_adapter( opentrons_96_well_aluminum_block ) plate adapter.load_labware( opentrons_96_wellplate_200ul_pcr_full_skirt )需要强调的是API 无法证明每一种不常见的模块 × 适配器 × 耗材组合在物理上都是合法的。代码能跑通不代表物理上放得下务必核对官方兼容列表仓库文档也在 modules_and_deck.md 中明确提示了这一点并在 SKILL.md 的 Safety Boundary 中要求验证模块、适配器、耗材定义后再上机。四、温度模块Temperature Module GEN2温度模块的典型控制是设定目标温度、执行操作、最后停用temperature_module.set_temperature(celsius4) # Pipetting or incubation commands... temperature_module.deactivate()set_temperature()是阻塞式调用会一直等到目标温度达到才返回。在API 2.27中start_set_temperature()可以非阻塞地启动降温/升温并返回一个 task 句柄供并发执行其他独立操作在依赖目标温度之前必须等待该 task 完成详见后文并发模块操作。操作检查清单使用正确的铝块或适配器不同板型对应不同适配器见上文load_adapter示例。在湿法实验方法中考虑冷凝和冷表面效应——低温板上方会凝结水汽。当方法不再需要温控时务必调用deactivate()避免协议结束后模块仍处于工作状态。不要假设液体本身瞬间达到模块温度——板与液体之间存在热传导延迟set_temperature()返回仅代表模块通常是金属块到达目标温度。五、加热振荡器Heater-Shaker GEN1加热振荡器同时提供加热与振荡两种能力典型序列如下heater_shaker.close_labware_latch() heater_shaker.set_and_wait_for_temperature(37) heater_shaker.set_and_wait_for_shake_speed(1000) protocol.delay(minutes5) heater_shaker.deactivate_shaker() heater_shaker.deactivate_heater()温度方法的准确名称取决于 API 行为当前上下文中可用的方法包括set_target_temperature()、set_and_wait_for_temperature()、wait_for_temperature()、set_and_wait_for_shake_speed()、deactivate_shaker()、deactivate_heater()。编写时以目标 API 级别的实际签名为准。四条安全铁律振荡前必须先关闭 latchlabware latch否则板会被甩出。打开 latch 或移动耗材前必须先停止振荡。核对特定耗材与填充体积下的最大允许转速——装满液体的板与空板允许的转速不同。考虑相邻槽位的净空限制——振荡时板有位移与邻近高耗材可能碰撞。API 2.27为振荡与温度操作提供了非阻塞版本用于与独立的移液动作并发同样要持有 task 句柄并在依赖步骤之前等待。六、热循环仪Thermocycler GEN2热循环仪是 PCR 自动化的核心。标准流程开盖 → 移液 → 关盖 → 设置盖温与块温 → 执行循环 profile → 降温保持 → 停用加热盖thermocycler protocol.load_module(thermocyclerModuleV2) plate thermocycler.load_labware( opentrons_96_wellplate_200ul_pcr_full_skirt ) thermocycler.open_lid() # Pipette into plate. thermocycler.close_lid() thermocycler.set_lid_temperature(temperature105) thermocycler.set_block_temperature( temperature95, hold_time_seconds180, block_max_volume25, ) thermocycler.execute_profile( steps[ {temperature: 95, hold_time_seconds: 15}, {temperature: 60, hold_time_seconds: 30}, {temperature: 72, hold_time_seconds: 30}, ], repetitions35, block_max_volume25, ) thermocycler.set_block_temperature( temperature4, block_max_volume25, ) thermocycler.deactivate_lid()API 2.28为块温命令新增了可选的ramp_rate升温速率参数。检查清单使用热循环仪对应的正确板与封膜seal全裙边 PCR 板是典型选择。加热与循环之前必须关闭 lid开盖状态下加热是物理风险。block_max_volume必须匹配每孔实际反应体积——它驱动升温速度低估会导致升温不足、反应未充分加热。仓库 test_scripts.py 断言pcr_setup_template.py中每个set_block_temperature和execute_profile调用都声明了block_max_volume。确认最终保持final hold行为是刻意的——很多方法在 4 °C 保持到用户停止。按方法要求决定 lid 与 block 是停用还是保持激活。没有任何甲板物品与热循环仪 footprint 冲突。仓库的 pcr_setup_template.py 是一个完整的 Flex PCR 模板8 个 25 µL 反应、两把移液器flex_1channel_50与flex_1channel_1000、95 °C 3 分钟激活、35 个循环95/60/72 °C、72 °C 5 分钟延伸、4 °C 保持。其测试 test_scripts.py 验证了反应体积预算、母液一次吸液 170 µL、模板来自各自独立 tube不污染母液 A1、35 次循环、盖温 105 °C 以及移液在开盖与关盖之间、循环结束后再次开盖的时序顺序。七、磁性硬件被动式 Magnetic BlockFlex与带电 Magnetic ModuleOT-2Flex 的被动式 Magnetic BlockMagnetic Block 是被动硬件——它没有engage()/disengage()方法。磁珠分离通过 Gripper 把兼容耗材移上/移下磁块实现magnetic_block protocol.load_module(magneticBlockV1, D1) protocol.move_labware( labwareplate, new_locationmagnetic_block, use_gripperTrue, ) protocol.delay(minutes5) protocol.move_labware( labwareplate, new_locationC1, use_gripperTrue, )必须确认 Gripper 兼容性与板的朝向orientation。避免吸到磁珠的要点验证沉降时间settle time、吸液侧aspiration side、底部间隙bottom clearance与流速flow rate——这些参数共同决定吸液口与磁珠层之间的距离。OT-2 的带电 Magnetic Module带电机的 Magnetic Module 仅限 OT-2magnetic_module protocol.load_module( magnetic module gen2, 1, ) plate magnetic_module.load_labware( nest_96_wellplate_2ml_deep ) magnetic_module.engage(height_from_base6.5) protocol.delay(minutes5) magnetic_module.disengage()注意engage 高度是耗材与实验特异性的——不要从另一块板随意复制一个高度不同深孔板、不同磁珠量对应的最佳拉磁高度不同。Magnetic Module 已停产discontinued但对现有 OT-2 硬件仍然受支持。不要在 Flex 上加载它这是 SKILL.md Common Failure Modes 中明确列出的高频错误。八、酶标仪Absorbance Plate ReaderFlexAPI 2.21酶标仪是Flex 专属模块加载在 A3–D3其 caddy 会占用对应的 column-4 位置供lid 移动行程盖子打开时向 column-4 方向退让。必须遵循的工作流顺序敏感加载模块。在无板状态下关闭 lid。初始化initialize酶标仪。打开 lid。用 Gripper 将兼容板移动到模块上。关闭 lid。读取read。reader protocol.load_module( module_nameabsorbanceReaderV1, locationD3, ) plate protocol.load_labware( corning_96_wellplate_360ul_flat, C2, ) reader.close_lid() reader.initialize( modemulti, wavelengths[450, 562, 600], ) reader.open_lid() protocol.move_labware( labwareplate, new_locationreader, use_gripperTrue, ) reader.close_lid() data reader.read(export_filenameplate_data)默认硬件波长为 450、562、600、650 nm。read()返回类型为dict[int, dict[str, float]]第一层 key 是波长第二层 key 是孔名well name。模拟行为在模拟中每个测量值都是 0且不写输出文件。因此要保护任何会除以读数的计算if not protocol.is_simulating(): normalized data[450][A1] / data[450][H12]不要手动移动酶标仪的 lid——lid 由模块控制手动干预会破坏行程与对位。仓库 absorbance_reader_template.py 提供了完整可运行的 Flex 2.29 模板加载 D3、初始化modemulti、wavelengths[450, 650]、Gripper 移板、read(export_filenameabsorbance)、再移回 C2。对应测试 test_scripts.py 断言了初始化前必须先 close_lid、两次 Gripper 移动上板与回位、以及无移液器时不需要 trash bin等约束。九、Flex StackerAPI 2.25最多四个 Stacker 连接在 Flex 右侧每个 shuttle 对应一个 column-4 位置进行寻址stacker protocol.load_module( module_nameflexStackerModuleV1, locationA4, )每个 Stacker 配置一种耗材类型stacker.set_stored_labware( load_nameopentrons_flex_96_tiprack_200ul, count5, lidopentrons_flex_tiprack_lid, )取用并移动tip_rack stacker.retrieve() protocol.move_labware( labwaretip_rack, new_locationB2, use_gripperTrue, )放回存储protocol.move_labware( labwareplate, new_locationstacker, use_gripperTrue, ) stacker.store()fill()与empty()会暂停等待操作员手动装载或卸载。约束条件在retrieve()或store()之前必须先set_stored_labware()配置存储内容。每个 Stacker 同一时间只支持一种耗材类型。Flex tip rack 需要兼容的 lid 才能堆叠。Stacker 不会识别操作员实际物理装载了什么——count与实际装载不一致时风险由人负责。预留对应行的 shuttle 移动路径并检查 column-3 冲突Stacker 穿梭仓进出会穿过该行详见甲板模型一节。使用容量辅助方法capacity helper核对具体耗材高度下的可堆叠数量。十、移动耗材与盖板Labware and LidsFlex 的自动化移动由 Gripper 完成protocol.move_labware( labwareplate, new_locationC2, use_gripperTrue, )手动移动use_gripperFalse会暂停等待操作员操作必须确保提示信息与 run setup 让源/目标位置无歧义protocol.move_labware( labwareplate, new_locationC2, use_gripperFalse, )API 2.23支持盖板堆叠lid stacks与move_lid()。使用前确认盖板与耗材兼容性、朝向、堆叠数量与废弃位置。Gripper 移动与耗材安全相关的验证在仓库测试中有直接体现absorbance_reader_template.py的两次移板测试断言运行日志中移动都with gripper且模拟日志显示Moving Assay Plate ... to slot C2test_scripts.py。十一、并发模块操作Concurrent Module ActionsAPI 2.27并发方法可以把耗时的模块动作与独立的移液操作重叠起来Temperaturestart_set_temperature()。Heater-Shaker非阻塞的温度或振荡速度方法。Thermocyclerstart_set_block_temperature()、start_set_lid_temperature()、start_execute_profile()。标准模式三步走启动操作并保存返回的 task。只执行物理上独立的命令例如与模块无关的移液。在任何假设该操作已完成的步骤之前等待 task。并发是手段而非目的不要仅仅为了缩短运行时间而制造并发。并发前必须检查甲板访问冲突、振动影响、热依赖与碰撞风险——例如加热振荡器振荡时邻近移液可能受振动干扰热循环仪升降温时依赖其温度的步骤不能提前执行。十二、模块状态检查清单Module State Checklist发布任何协议前对照以下清单逐项确认正确的机器人与模块代际Flex vs OT-2GEN1 vs GEN2。正确的 load name 与 API 级别交叉核对 modules_and_deck.md 与 api_reference.md。合法的甲板槽位且无 footprint 冲突Flex 用坐标、OT-2 用数字。正确的 caddy、适配器与耗材不常见的组合 API 无法证明物理合法性。移动前 latch/lid 状态安全振荡前关 latch、加热前关 lid。温度、速度与时间参数已按方法验证如block_max_volume。每个已启动的并发 task 都被等待。Gripper 移动使用兼容耗材且路径畅通。模块在协议结束时停用或有意保持激活如 PCR 末尾 4 °C 保持。App 分析与一次物理 dry run 覆盖了完整配置。十三、在仓库中落地模板、模拟与测试验证本技能在仓库中提供了一整套可直接复用与验证的资源6 个模板脚本scriptsbasic_protocol_template.py最小 Flex 2.29 转移、ot2_basic_protocol_template.py最小 OT-2 2.28 转移、serial_dilution_template.py8 通道整板 1:2 稀释、pcr_setup_template.pyFlex PCR 配置与循环、runtime_parameters_template.py数值/布尔运行时参数、absorbance_reader_template.py酶标仪初始化与读取工作流。本地模拟Flex 用uv run --with opentrons9.1.1 opentrons_simulate protocol.py依赖固定于 requirements-flex.txtOT-2 用uv run --with opentrons9.0.0 opentrons_simulate protocol.py依赖固定于 requirements-ot2.txt。注意opentrons 9.1.1 会直接拒绝 OT-2 协议Flex/OT-2 发行线拆分后因此 OT-2 的最终分析必须在当前 OT-2 App 中完成。自动化测试test_scripts.py 对全部模板执行真实模拟opentrons.simulate.simulate()并逐项断言包括Flex 坐标槽位与 OT-2 数字槽位、Flex 必须加载 trash bin 而 OT-2 禁止、酶标仪 close_lid→initialize 顺序、热循环仪每个块温命令都必须带block_max_volume、稀释模板的 1111 个吸头预算等。这些测试把上文所有检查清单变成了可机器验证的断言是学习模块与甲板规则的绝佳教材。模板只是起点而非验证过的实验方法替换体积、耗材、液体、时间与吸头策略前务必先核对硬件兼容性与湿法实验方法参见 SKILL.md 的 Safety Boundary 与 Authoring Workflow。十四、高频失败模式小结结合本文内容与 SKILL.md 的 Common Failure Modes模块与甲板相关的典型错误包括在 Flex 上加载 Magnetic Module——Flex 应使用被动式 Magnetic Block。对酶标仪调用read(wavelengths...)——应先initialize()再read()。忘记 Flex 的 trash bin 或 waste chuteFlex 无固定垃圾桶。在 OT-2 上调用load_trash_bin()槽位 12 是固定垃圾桶。热循环仪未声明block_max_volume导致升温行为与反应体积不匹配。开盖状态加热循环、振荡前不关 latch。未等待并发 task 就执行依赖步骤。把局部相对链接当作全局、把不兼容的耗材定义混用于另一机器人导致 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），仅供参考
