企业官网建设流程全解析

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.29，OT-2 支持 2.0–2.28，API 2.29 仅限 Flex。仓库 api_reference.md 已按此基线校验过每个模块 load name 与最低 API 版本。

一、模块兼容性：既是 API 问题，也是物理硬件问题

Opentrons 的模块兼容性从来不是一个单纯的 API 问题：即使 load name 合法，物理硬件（机器人型号、模块代数、caddy/适配器、固件、甲板槽位、耗材）不匹配，协议依然无法运行。在编写任何命令之前，必须先确认这五件事：机器人型号、模块代数、caddy 或适配器、固件、甲板位置与耗材。

下表来自 modules_and_deck.md 的官方兼容快照，是编写load_module()的第一手依据：

四条关键注意事项：

• 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 Models）：Flex 与 OT-2 完全不同

Flex 使用坐标式槽位（A1–D4），OT-2 使用数字槽位（1–11），两者的甲板物理布局、垃圾桶/废料口配置与 Gripper 能力截然不同。仓库 test_scripts.py 中甚至有专门的测试断言：Flex 模板的所有槽位必须匹配^[A-D][1-4]$，OT-2 模板的所有槽位必须是纯数字。

Flex 甲板

• 工作甲板：A1–D3，移液器与 Gripper 均可到达。
• 暂存区（staging area）：A4–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_name="heaterShakerModuleV1", location="D1", )

耗材通过模块加载（此时耗材的甲板位置由模块决定）：

plate = heater_shaker.load_labware( "corning_96_wellplate_360ul_flat", label="Mixing 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(celsius=4) # 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(minutes=5) 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 级别的实际签名为准。

四条安全铁律：

• 振荡前必须先关闭 latch（labware 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(temperature=105) thermocycler.set_block_temperature( temperature=95, hold_time_seconds=180, block_max_volume=25, ) thermocycler.execute_profile( steps=[ {"temperature": 95, "hold_time_seconds": 15}, {"temperature": 60, "hold_time_seconds": 30}, {"temperature": 72, "hold_time_seconds": 30}, ], repetitions=35, block_max_volume=25, ) thermocycler.set_block_temperature( temperature=4, block_max_volume=25, ) 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 Block（Flex）与带电 Magnetic Module（OT-2）

Flex 的被动式 Magnetic Block

Magnetic Block 是被动硬件——它没有engage()/disengage()方法。磁珠分离通过 Gripper 把兼容耗材移上/移下磁块实现：

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

必须确认 Gripper 兼容性与板的朝向（orientation）。避免吸到磁珠的要点：验证沉降时间（settle time）、吸液侧（aspiration side）、底部间隙（bottom clearance）与流速（flow rate）——这些参数共同决定吸液口与磁珠层之间的距离。

OT-2 的带电 Magnetic Module

带电机的 Magnetic Module 仅限 OT-2：

magnetic_module = protocol.load_module( "magnetic module gen2", "1", ) plate = magnetic_module.load_labware( "nest_96_wellplate_2ml_deep" ) magnetic_module.engage(height_from_base=6.5) protocol.delay(minutes=5) magnetic_module.disengage()

注意：

• engage 高度是耗材与实验特异性的——不要从另一块板随意复制一个高度，不同深孔板、不同磁珠量对应的最佳拉磁高度不同。
• Magnetic Module 已停产（discontinued），但对现有 OT-2 硬件仍然受支持。不要在 Flex 上加载它，这是 SKILL.md "Common Failure Modes" 中明确列出的高频错误。

八、酶标仪：Absorbance Plate Reader（Flex，API 2.21+）

酶标仪是Flex 专属模块，加载在 A3–D3，其 caddy 会占用对应的 column-4 位置供lid 移动行程（盖子打开时向 column-4 方向退让）。

必须遵循的工作流（顺序敏感）：

1. 加载模块。
2. 在无板状态下关闭 lid。
3. 初始化（initialize）酶标仪。
4. 打开 lid。
5. 用 Gripper 将兼容板移动到模块上。
6. 关闭 lid。
7. 读取（read）。

reader = protocol.load_module( module_name="absorbanceReaderV1", location="D3", ) plate = protocol.load_labware( "corning_96_wellplate_360ul_flat", "C2", ) reader.close_lid() reader.initialize( mode="multi", wavelengths=[450, 562, 600], ) reader.open_lid() protocol.move_labware( labware=plate, new_location=reader, use_gripper=True, ) reader.close_lid() data = reader.read(export_filename="plate_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、初始化mode="multi"、wavelengths=[450, 650]、Gripper 移板、read(export_filename="absorbance")、再移回 C2。对应测试 test_scripts.py 断言了"初始化前必须先 close_lid"、两次 Gripper 移动（上板与回位）、以及"无移液器时不需要 trash bin"等约束。

九、Flex Stacker（API 2.25+）

最多四个 Stacker 连接在 Flex 右侧，每个 shuttle 对应一个 column-4 位置进行寻址：

stacker = protocol.load_module( module_name="flexStackerModuleV1", location="A4", )

每个 Stacker 配置一种耗材类型：

stacker.set_stored_labware( load_name="opentrons_flex_96_tiprack_200ul", count=5, lid="opentrons_flex_tiprack_lid", )

取用并移动：

tip_rack = stacker.retrieve() protocol.move_labware( labware=tip_rack, new_location="B2", use_gripper=True, )

放回存储：

protocol.move_labware( labware=plate, new_location=stacker, use_gripper=True, ) stacker.store()

fill()与empty()会暂停等待操作员手动装载或卸载。

约束条件：

• 在retrieve()或store()之前必须先set_stored_labware()配置存储内容。
• 每个 Stacker 同一时间只支持一种耗材类型。
• Flex tip rack 需要兼容的 lid 才能堆叠。
• Stacker 不会识别操作员实际物理装载了什么——count与实际装载不一致时风险由人负责。
• 预留对应行的 shuttle 移动路径，并检查 column-3 冲突（Stacker 穿梭仓进出会穿过该行，详见"甲板模型"一节）。
• 使用容量辅助方法（capacity helper）核对具体耗材高度下的可堆叠数量。

十、移动耗材与盖板（Labware and Lids）

Flex 的自动化移动由 Gripper 完成：

protocol.move_labware( labware=plate, new_location="C2", use_gripper=True, )

手动移动（use_gripper=False）会暂停等待操作员操作，必须确保提示信息与 run setup 让源/目标位置无歧义：

protocol.move_labware( labware=plate, new_location="C2", use_gripper=False, )

API 2.23+支持盖板堆叠（lid stacks）与move_lid()。使用前确认盖板与耗材兼容性、朝向、堆叠数量与废弃位置。

Gripper 移动与耗材安全相关的验证在仓库测试中有直接体现：absorbance_reader_template.py的两次移板测试断言运行日志中移动都"with gripper"，且模拟日志显示"Moving Assay Plate ... to slot C2"（test_scripts.py）。

十一、并发模块操作（Concurrent Module Actions，API 2.27+）

并发方法可以把耗时的模块动作与独立的移液操作重叠起来：

• Temperature：start_set_temperature()。
• Heater-Shaker：非阻塞的温度或振荡速度方法。
• Thermocycler：start_set_block_temperature()、start_set_lid_temperature()、start_execute_profile()。

标准模式三步走：

1. 启动操作并保存返回的 task。
2. 只执行物理上独立的命令（例如与模块无关的移液）。
3. 在任何假设该操作已完成的步骤之前等待 task。

并发是手段而非目的：不要仅仅为了缩短运行时间而制造并发。并发前必须检查甲板访问冲突、振动影响、热依赖与碰撞风险——例如加热振荡器振荡时邻近移液可能受振动干扰，热循环仪升降温时依赖其温度的步骤不能提前执行。

十二、模块状态检查清单（Module State Checklist）

发布任何协议前，对照以下清单逐项确认：

• 正确的机器人与模块代际（Flex vs OT-2，GEN1 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 个模板脚本（scripts）：basic_protocol_template.py（最小 Flex 2.29 转移）、ot2_basic_protocol_template.py（最小 OT-2 2.28 转移）、serial_dilution_template.py（8 通道整板 1:2 稀释）、pcr_setup_template.py（Flex PCR 配置与循环）、runtime_parameters_template.py（数值/布尔运行时参数）、absorbance_reader_template.py（酶标仪初始化与读取工作流）。
• 本地模拟：Flex 用uv run --with "opentrons==9.1.1" opentrons_simulate protocol.py（依赖固定于 requirements-flex.txt），OT-2 用uv run --with "opentrons==9.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、稀释模板的 1+11+1 个吸头预算等。这些测试把上文所有"检查清单"变成了可机器验证的断言，是学习模块与甲板规则的绝佳教材。

模板只是起点而非验证过的实验方法：替换体积、耗材、液体、时间与吸头策略前，务必先核对硬件兼容性与湿法实验方法（参见 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 chute（Flex 无固定垃圾桶）。
• 在 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