pylabrobot

PyLabRobot

使用 PyLabRobot 与硬件无关的前端、资源树、跟踪器和设备专用后端开发实验室自动化。默认使用本地清单验证、记账功能和仅软件的 chatterbox 后端。

已验证的快照

• PyPI 稳定版：PyLabRobot==0.2.1，于 2026-03-23 发布。
• 上游要求：Python >=3.9。本技能使用 Python 3.11 运行可复现的冒烟测试。
• /stable/ 文档标明自身对应 0.2.1。/dev/ 和仓库 main 描述的是尚未发布的工作，不应假定这些内容在 0.2.1 中可用。
• 稳定版液体处理器后端包括 STARBackend、VantageBackend、EVOBackend、OpentronsOT2Backend 和离线的 LiquidHandlerChatterboxBackend。
• PyLabRobot 的 GitHub Releases 页面没有 0.2.x 软件版本发布记录；应使用 PyPI 历史记录、v0.2.1 标签和变更日志作为版本发布依据。

不可逾越的硬件边界

绝不自动连接、初始化、归零、移动、加热、振荡、旋转、泵送、开启或关闭实体设备，也不得以其他方式向其发送指令。不得仅通过更改环境变量、配置值或导入项，就将仿真计划转换为实时后端。

在任何单独获准的实时运行之前，必须由受过培训的人员：

1. 明确确认确切的后端、设备身份、固件、传输方式、平台和协议版本。
2. 对照资源树核验实体平台，包括载架、适配器、盖子、板、吸头架、废弃物容器、实验室器皿的方向、条形码以及每个已占用坐标。
3. 验证校准、示教、运动范围、碰撞风险、抓手或通道间隙，以及所有吸液／分液坐标。
4. 检查源容器身份和实际填充体积、死体积、目标容量、吸头类型／容量／滤芯兼容性、通道映射、单位、高度、速率、液体类别、吹出／混匀以及污染边界。
5. 确认防护装置、舱门、废弃物容量、围堵措施、急停就绪状态、个人防护装备、生物安全／化学品控制措施，以及安全的中止／恢复流程。
6. 如果有任何内容是新的或已更改，则批准低速干运行或使用无害材料进行调试运行。

跟踪器状态是记账信息，不是传感信息。它无法证明实体中确实存在液体或吸头。Visualizer 会呈现资源／跟踪器事件，但不会模拟物理过程。Chatterbox 会打印计划执行的操作，但无法证明校准正确、设备可达、不会发生碰撞、液体行为符合预期或设备状态正常。

必要信息

以下信息一律不得猜测：

• 确切的设备型号、已安装选件、固件、计算机／操作系统和传输方式。
• 稳定版 PyLabRobot 版本及所需额外依赖。
• 平台／平台原点、载架、适配器、资源定义、尺寸、坐标、方向和运动间隙。
• 板／管／储液槽容量和死体积；初始实体体积。
• 吸头型号、滤芯、适配性、容量、吸头架状态、通道数和通道映射。
• 转移单位（uL、mm、uL/s、s）、高度、速率、混匀、气隙、吹出、液体属性以及经过验证的厂商液体类别。
• 污染策略、对照、废弃物处理、操作员干预、验收标准和恢复流程。

如果信息缺失，请列出假设／阻碍事项，并且只生成离线草稿。

可复现安装

用于离线 API 检查和 chatterbox 仿真：

uv venv --python 3.11 .venv-pylabrobot
uv pip install --python .venv-pylabrobot/bin/python "PyLabRobot==0.2.1"

在 Windows 上，使用 .venv-pylabrobot\Scripts\python.exe。在用户指定设备并明确批准其传输依赖之前，不要安装硬件额外依赖。之后，先检查对应设备的稳定版页面，再考虑固定版本，例如 "PyLabRobot[serial]==0.2.1" 或 "PyLabRobot[usb]==0.2.1"。

离线优先工作流

从仓库根目录运行。所有捆绑的 CLI 都使用严格且有界的 UTF-8 JSON/CSV、本地非符号链接路径、固定的允许列表，并输出 JSON。它们均无法 选择实时后端。

python3 skills/pylabrobot/scripts/validate_manifest.py \
  --input tests/pylabrobot/fixtures/protocol_manifest.json

python3 skills/pylabrobot/scripts/check_deck_geometry.py \
  --input tests/pylabrobot/fixtures/protocol_manifest.json

python3 skills/pylabrobot/scripts/plan_transfers.py \
  --manifest tests/pylabrobot/fixtures/protocol_manifest.json \
  --transfers tests/pylabrobot/fixtures/transfers.csv

python3 skills/pylabrobot/scripts/generate_simulation_plan.py \
  --manifest tests/pylabrobot/fixtures/protocol_manifest.json \
  --transfers tests/pylabrobot/fixtures/transfers.csv

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

几何检查器使用保守的静态轴对齐包围盒；它不是运动规划器。转移规划器要求 每行对应一个新吸头，并检查源液量、死体积和目标液量、吸头容量、孔位、通道、高度、速率、 单位和允许列表。请先查看 assets/protocol-manifest.schema.json 和合成测试样例，再制作项目专用的清单。

已验证的纯软件示例

以下精确后端仅用于软件。请勿替换为硬件后端。

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.liquid_handling.backends import LiquidHandlerChatterboxBackend
from pylabrobot.resources import (
    Cor_96_wellplate_360ul_Fb,
    PLT_CAR_L5AC_A00,
    TIP_CAR_480_A00,
    hamilton_96_tiprack_1000uL_filter,
    set_tip_tracking,
    set_volume_tracking,
)
from pylabrobot.resources.hamilton import STARLetDeck

set_tip_tracking(True)
set_volume_tracking(True)

deck = STARLetDeck()
tip_carrier = TIP_CAR_480_A00(name="tip_carrier")
tips = hamilton_96_tiprack_1000uL_filter(name="tips")
tip_carrier[0] = tips
plate_carrier = PLT_CAR_L5AC_A00(name="plate_carrier")
source = Cor_96_wellplate_360ul_Fb(name="source")
destination = Cor_96_wellplate_360ul_Fb(name="destination")
plate_carrier[0] = source
plate_carrier[1] = destination
deck.assign_child_resource(tip_carrier, rails=3)
deck.assign_child_resource(plate_carrier, rails=15)
source.get_well("A1").tracker.set_volume(100.0)  # planned state, not sensing

lh = LiquidHandler(backend=LiquidHandlerChatterboxBackend(), deck=deck)
await lh.setup()  # safe here only because the backend above is software-only
try:
    await lh.pick_up_tips(tips["A1"])
    await lh.aspirate(source["A1"], vols=[10.0])
    await lh.dispense(destination["A1"], vols=[10.0])
    await lh.return_tips()
finally:
    await lh.stop()

避免使用过时代码的 API 规则

• 当前名称为 STARBackend、VantageBackend、EVOBackend 和 OpentronsOT2Backend；不要使用过时的 STAR、TecanBackend、 OpentronsBackend 或 ChatterboxBackend 导入。
• 通用离线液体处理器测试请使用 LiquidHandlerChatterboxBackend。 ChatterBoxBackend 是单独导出的旧名称；不要将两者混为一谈。
• Visualizer(resource=...) 有效，后续调用 await vis.setup() 和 await vis.stop()；它会启动本地主机 HTTP/WebSocket 服务，并且可能打开浏览器。
• 在 0.2.1 中，不存在通用的 from pylabrobot.liquid_handling import LiquidClass。 稳定的液体类别是特定于厂商的，例如 pylabrobot.liquid_handling.liquid_classes.hamilton.HamiltonLiquidClass。
• 大多数前端方法都是异步的。后端关键字参数和功能因厂商／型号而异；共享前端并不意味着行为完全相同。

参考资料

• 液体处理 — 操作、吸头、追踪、 液体类别、单位和验证。
• 资源 — 工作台、坐标、微孔板、吸头架、 碰撞、状态和序列化。
• 硬件后端 — 已验证名称、 支持级别、功能和实时运行门控。
• 分析设备 — 微孔板读数仪 和秤。
• 物料处理 — 泵、加热器、 振荡器、温度控制、存储和离心机。
• 可视化 — chatterbox、Visualizer、 本地主机服务和仿真限制。

有日期的上游来源

核查日期：2026-07-23：

• PyPI 0.2.1 — 发布于 2026-03-23； Python >=3.9；额外依赖和构件。
• 稳定版安装指南 — 稳定版与源码／开发版安装方式，以及可选传输组。
• 稳定版 API 和 支持的设备 — 0.2.1 API 和特定型号的支持标记。
• v0.2.1 源码标签 和 变更日志 — 标签日期为 2026-03-23；Unreleased 仅用于开发。

Agent 操作流程

1. 检查环境。 确认仪器或平台型号、API 版本、凭据，以及是否有可用的模拟器。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问确认，而不是猜测。
3. 先运行小规模版本。 在使用真实样本前，先模拟协议，或使用水或虚拟实验室器皿运行。
4. 使用上方的说明和参考资料执行完整任务。
5. 验证结果。 核对体积、平台布局和实验室器皿定义；执行前须由人工批准协议。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
协议在模拟中失败	在模拟中修正；切勿在硬件上运行未经验证的协议。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数有歧义	询问用户，或在运行前明确说明所作的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请如实说明。
• 未经用户明确确认，切勿触发实体操作、下单或收费。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、消耗共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• opentrons-integration：为 Flex 和 OT-2 机器人编写、审查、迁移、模拟和排查官方 Opentrons Python Protocol API v2 协议。
• fluidsim：使用明确的数值有效性 a…规划、配置、检查、重启和分析有界 FluidSim 计算流体动力学模拟。