企业官网建设流程全解析

PyLabRobot 0.2.1 物料处理设备自动化指南：泵、加热振荡器、温控、离心机与存储的安全编程实践

【免费下载链接】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 仓库中 material-handling 参考文档 的深度展开版本。它聚焦 PyLabRobot 0.2.1 中会"真正产生物理运动、压力、热量或储能"的一类设备——泵、加热/振荡器、温度控制器、离心机与存储/孵育单元——给出经核验的稳定前端 API、过时命名辨析、完整安全核验清单，并结合本仓库的inspect_backends.py源码与测试证明"零连接检查"的实现原理。读完本文，你将能：区分稳定前端方法与已被废弃的旧签名，为每类设备写出不触发任何物理动作的离线代码，并通过无连接检查工具验证当前环境中 0.2.1 API 表面是否完整。

为什么"物料处理"需要单独对待

在 PyLabRobot 的架构里，前端（frontend）负责校验与记录标准操作，后端（backend）负责把操作翻译给具体设备族，资源树（resource tree）提供几何与状态。相比 liquid-handling.md 中讨论的移液操作，物料处理设备的每次 API 调用都可能产生物理运动、压力、热量或储能——泵转动、加热器升温、振荡器摇晃、离心机高速旋转、存储单元启闭舱门。因此本 skill 的核心原则是：文中的代码片段只标识 API，绝不连接设备。

这份参考文档于2026-07-23对照PyLabRobot 0.2.1（PyPI 发布 2026-03-23，见 SKILL.md 的 Verified snapshot）逐项核验，与/dev/、仓库main分支描述的未发布工作严格划清界限。支持级别标签（Full / Mostly / Basic / WIP）全部取自 stable 版 supported-machines 页面，其定义如下（见 hardware-backends.md）：

• WIP：开发中；
• Basics/Basic：核心功能已集成并有文档；
• Mostly：大部分能力可用，但存在已知缺失命令；
• Full：上游认为至少 90% 的硬件/固件能力有完整文档支持。

这些标签不代表特定固件、附件、电脑、传输方式或协议已验证通过。

泵（Pumps）

稳定导入与方法

0.2.1 中经核验的稳定导入仅包含一个前端与一个稳定后端导出：

from pylabrobot.pumps import MasterflexBackend, Pump

Pump上经核验的稳定方法：

run_revolutions(num_revolutions) run_continuously(speed) run_for_duration(speed, duration) halt()

过时 API 辨析：halt()才是泵的运动命令

文档明确列出以下过时方法不可作为 0.2.1 通用前端使用：作为泵送命令的start、stop、pump_volume，以及calibrate(duration=..., speed=..., volume=...)。其中的关键区分是：stop()属于机器生命周期（machine lifecycle）方法，用于关闭整个设备实例；halt()才是泵送运动（pump-motion）的停止命令。把stop()当作"停泵"来用，是旧示例中最常见的错误之一。

后端与支持设备

MasterflexBackend(com_port)是传输相关的后端，不能在设计/发现阶段实例化它——它需要真实的串口参数，仅用于经授权的实机连接。stable 支持表中被标记为Full的设备族包括：

• Cole-Parmer Masterflex L/S 系列列出的型号；
• Agrowtek Pump Array。

泵送安全清单

在经单独授权的运行开始前，必须人工核验以下各项，文档逐条列出：

• 硬件识别：精确的泵/泵头/管路型号、材质、内径、方向、挤压件（occlusion）、接头、阀门、夹具与目的地；
• 校准关系：命令速度/转数/时间与实际输送体积之间的校准关系，须针对当前流体、管路老化程度、背压与温度重新确认——时间/速度命令不等于实测体积；
• 管路与残液：预充/排空路径、气泡、虹吸、死体积、残留体积、最大压力/流速、泄漏围堵与废液容量；
• 兼容性：化学/生物兼容性、交叉污染控制、管路更换策略；
• 异常行为：可触达的停止装置，以及断连、超时或部分输送时的安全行为。

如需闭环确认，文档要求：记录校准数据与其不确定度，并使用经过验证的秤或流量传感器——永远不要用"跑了多久"代替"送了多少体积"。

加热振荡器与振荡器（Heater shakers and shakers）

稳定导入与命名陷阱

from pylabrobot.heating_shaking import ( HamiltonHeaterShakerBackend, HeaterShaker, InhecoThermoshakeBackend, ) from pylabrobot.shaking import Shaker

这里有一个极易踩中的命名陷阱：稳定的类名是InhecoThermoshakeBackend（Thermoshake中是小写s），而不是过时的InhecoThermoShakeBackend。导入旧名称会在 0.2.1 中直接失败。

经核验的方法

set_temperature(temperature, passive=False) get_temperature() shake(speed, duration=None, **backend_kwargs) stop_shaking(**backend_kwargs) lock_plate(**backend_kwargs) unlock_plate(**backend_kwargs)

注意set_temperature(temperature, passive=False)中passive参数的含义与后端相关。旧名称set_shake_rate和set_temperature(None)不是0.2.1 的核验签名。文档特别警告：不要用零值或None来代替"关闭/冷却"——除非对应后端文档明确支持，否则应使用设备页面上规定的降温/失活方式。

构造要求

HeaterShaker的构造需要name、尺寸、backend 以及一个child_location（板位位置）。后端构造本身也是设备拓扑相关的：

• HamiltonHeaterShakerBackend(index, interface)
• InhecoThermoshakeBackend(index, control_box)

二者都要求经批准共享的接口/控制器（shared interfaces/controllers），不能凭空捏造参数。

支持设备清单（全部 Full）

• Inheco Thermoshake 与 Thermoshake AC
• Opentrons Thermoshake
• Hamilton Heater Shaker
• QInstruments BioShake

加热/振荡安全

确认板兼容性、质量与平衡、盖/密封、锁定机制、冷凝、溅漏围堵、轨道/速度限制、热限制、升温/平衡时间、传感器校准与安全解锁温度。振荡过程中绝不解锁或移动板。把设定点（setpoint）视为"命令"而非"结果"——请求的温度不证明样品已达到该温度。

温度控制器（Temperature controllers）

稳定前端导入：

from pylabrobot.temperature_controlling import TemperatureController

经核验方法：

set_temperature(temperature, passive=False) get_temperature() deactivate()

注意这里的关闭方法是deactivate()，与加热振荡器体系不同。稳定支持包括：

• Inheco CPAC：Full；
• Opentrons Temperature Module：Mostly（在完整 stable 表中）。

实操核验项：主动制冷、冷凝控制、板/适配器接触、设定点范围、升温速率、传感器位置、过冲（overshoot），以及样品温度与模块温度的差异——模块显示的温度不代表孔内液体已达到相同温度。

离心机（Centrifuges）

稳定导入与方法

from pylabrobot.centrifuge import Access2Backend, Centrifuge, VSpinBackend

经核验前端方法：

open_door() close_door() lock_door() unlock_door() spin(g, duration, **backend_kwargs)

核心 API 变化：用 RCF 而不是 RPM

稳定方法接受相对离心力spin(g, duration, ...)，而不是过时的speed=...RPM 参数。把 RPM 换算为 RCF 需要正确的转子半径（rotor radius）——文档警告永远不要猜测该半径。如果你手上只有 RPM 规格，必须先拿到该型号转子的准确半径再换算，否则实际离心力可能完全错误。

后端与支持设备

• Agilent VSpin：Mostly；
• Agilent VSpin Access2 Loader：Full。

后端构造为设备特定形式：VSpinBackend(device_id=None)与Access2Backend(device_id, timeout=60)。在真实脚本中不要使用占位 ID。

MicroSpin：未发布 API 的警示

当前 changelog 把 HighRes Biosolutions MicroSpin 列在Unreleased部分。虽然开发分支main可能已经暴露MicroSpin，但它不是0.2.1 稳定 API，不得在钉住版本的示例中导入。这正是本 skill 反复强调"stable 与 main 分离"的典型例证。

离心机安全

要求人工核验：转子/吊桶/适配器型号、板额定值、方向、平衡、最大 RCF、时长、加速/减速曲线、盖/门互锁、装载位置、间隙、维护与应急程序。转子旋转期间绝不打开/解锁门，也不要仅仅为了测试连接而发出运动命令。超时或断连时，假设转子可能仍在转动，直到物理上确认安全为止。

存储/孵育（Storage/incubation）

stable 设备清单包含多个 Thermo Fisher/Heraeus Cytomat 型号（Full）以及 Inheco Incubator Shaker/SCILA（Mostly）。关键约束：其 API 是型号特定的，不要照搬过时的通用示例——例如from pylabrobot.incubation import Incubator必须在钉住的 wheel 中确认该符号确实存在后再使用。

存储移动需要显式的板身份、插槽映射、占用状态、门/舱口/互锁状态、朝向、环境设定点，以及中断交接（interrupted handoff）的恢复流程。文档特别强调：软件记录的占用状态不是物理探测——追踪器只是记账，无法证明某块板真的在那个位置。

多设备编排（Multi-device orchestration）

不要因为前端是 async 就随意对硬件操作使用gather()并发。安全并发要求经批准的工作单元互锁（workcell interlocks）和一个拥有以下职责的调度器：

• 设备与板状态；
• 碰撞区与转移所有权；
• 门/托盘/吊桶/锁的前置条件；
• 超时、重试、幂等性与部分完成处理；
• 紧急停止与重启/对账行为。

文档给出推荐的默认顺序，这是任何实机协议上线前的标准递进流程：

1. 离线验证清单（manifest）与转移计划；
2. 生成不可执行的仿真计划；
3. 在有条件时仅使用软件前端（software-only frontends）演练；
4. 与操作员逐项审查每次交接（handoff）；
5. 为精确的实机协议取得显式确认；
6. 在场地规程下逐台设备、逐次移动完成调试（commissioning）。

无连接检查（No-connection inspection）

参考文档提供了一个不构造任何设备、不调用setup()的检查命令：

python3 skills/pylabrobot/scripts/inspect_backends.py \ --expected-version 0.2.1 --strict

源码级原理：检查到底做了什么

本仓库的 inspect_backends.py 完整实现了这个"零连接检查"。其核心设计保证（对应 test_clis.py 中test_backend_inspector_never_connects与test_all_help_paths_are_dependency_free两个测试的断言）：

• 导入是惰性的：只有完成参数解析后才导入固定的允许列表类；
• 零实例化：检查过程创建 0 个后端实例（报告中显式输出backend_instances_created: 0）；
• 不调用setup()：任何方法都不会触发设备初始化；
• 无传输访问：报告显式声明serial_usb_network_access: False、connection_attempted: False；
• 签名检查：通过inspect.signature()读取类签名，通过hasattr()探测声明的方法是否存在。

其中与本文主题直接相关的部分位于method_map（inspect_backends.py），它把每类物料处理设备的稳定方法集合固定下来：

method_map: dict[str, tuple[type[Any], tuple[str, ...]]] = { "Pump": (Pump, ("setup", "stop", "run_for_duration", "run_continuously", "halt")), "HeaterShaker": ( HeaterShaker, ("setup", "stop", "set_temperature", "shake", "stop_shaking"), ), "Shaker": (Shaker, ("setup", "stop", "shake", "stop_shaking")), "TemperatureController": ( TemperatureController, ("setup", "stop", "set_temperature", "get_temperature", "deactivate"), ), "Centrifuge": ( Centrifuge, ("setup", "stop", "open_door", "close_door", "lock_door", "spin"), ), }

对照参考文档可以发现两者完全一致：Pump核验run_for_duration/run_continuously/halt，Centrifuge核验open_door/close_door/lock_door/spin（注意这里正是spin而非过时的speed参数），TemperatureController核验deactivate()而非set_temperature(None)。也就是说，运行这条命令就等于自动化执行了参考文档中"稳定方法"一节的核对工作。

--strict模式下，如果 PyLabRobot 未安装、版本不匹配或任一符号导入失败，命令以退出码 4 失败并输出 JSON 报告。--expected-version参数强制使用X.Y.Z数值格式（由VERSION_RE校验），默认值0.2.1定义在 _common.py。

一个重要边界（hardware-backends.md 同样强调）：方法存在（hasattr为 True）不等于该型号实现了此操作——某些后端会故意抛出NotImplementedError。此检查只验证 API 表面，不验证硬件能力。

版本与证据边界

本文所有 API 均以 PyLabRobot0.2.1（wheel 与v0.2.1tag，日期 2026-03-23）为准。参考文档的 Sources 部分核验日期为2026-07-23，依据是 stable 版 supported-machines 页面、stable 版泵/加热振荡/离心机指南与 API 文档、v0.2.1源码 tag 以及 changelog 的Unreleased部分。在仓库内可对照的本地证据包括：

• SKILL.md：版本快照、可复现安装命令（uv pip install "PyLabRobot==0.2.1"）与"非协商硬件边界"六大人工确认项；
• hardware-backends.md：支持级别定义与 stable/development 分离原则；
• inspect_backends.py：无连接检查实现；
• test_clis.py：验证检查器从不建立连接、帮助路径零依赖；
• analytical-equipment.md：配套的酶标仪与天平类分析设备的并行安全清单。

结语：把"能写"和"能跑"分开

物料处理设备的共同规律是：每一个 API 调用都可能产生真实世界的后果。PyLabRobot 0.2.1 在前端统一了操作语义，但后端是否支持、参数如何解析、物理行为如何，全部依赖具体型号。最佳实践可以概括为三步：

1. 离线验证：用inspect_backends.py --expected-version 0.2.1 --strict确认当前环境的稳定 API 表面；
2. 软件演练：用LiquidHandlerChatterboxBackend等软件后端在追踪器上推进计划状态，绝不把仿真计划因改一个环境变量/配置就变成实机后端；
3. 人工门禁：任何实机运行前，按本文每节的安全清单逐项人工核验，一次只调试一台设备、一次只移动一个步骤，并保留校准记录与不确定性。

记住三句安全格言：时间/速度命令不等于实测体积；设定点命令不等于样品已达该温度；软件记账不等于物理探测。遵守这些边界，PyLabRobot 0.2.1 的物料处理前端就能在受控的离线工作流中被安全地开发、审查与验证。

【免费下载链接】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