企业官网建设流程全解析

PyLabRobot Agent Skill 实战指南：面向科研 Agent 的离线安全液体处理协议规划与验证

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

导读

本指南围绕科学 Agent 技能库中的pylabrobot技能展开，讲解如何在不连接任何物理设备的前提下，使用 PyLabRobot 0.2.1 完成液体处理协议的清单校验、deck 几何检查、转移规划、仿真计划生成与后端能力审计。读完本文，你将掌握一套"离线优先、人工把关、杜绝误触硬件"的完整工作流：既能在纯软件环境里写出可验证的移液协议，也能为真实设备接入预留严格的六步人工放行门槛。

技能定位：从"写协议"到"安全地写协议"

pylabrobot技能的核心职责是：开发与审查基于 PyLabRobot 的实验室自动化资源、液体处理计划、离线仿真，以及受支持的设备集成。它的适用范围包括 PyLabRobot 协议编写、API 咨询等场景，同时强约束一点：任何物理执行都必须经过显式的操作员安全闸门（operator safety gate）。

该技能在技能库中的能力元数据如下（见 SKILL.md）：

• 兼容性：基于 PyLabRobot 0.2.1、Python 3.9+ 验证；技能自带的规划 CLI 仅需 Python 3.11+，且不建立任何串口、USB 或网络连接；
• 允许工具：Read / Write / Edit / Bash；
• 许可：MIT；
• 核心原则：默认使用本地清单校验、台账记录（bookkeeping）与纯软件 chatterbox 后端，绝不在未获授权时连接硬件。

一句话概括其设计哲学：规划是软件问题，执行是安全与工程问题。技能把前者做到极致（确定性、可复现、fail-closed），把后者留给训练有素的真人。

已验证版本快照：锁定 0.2.1，避免开发版污染

技能明确记录了在2026-07-23核验过的稳定版本事实：

• 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.1tag 与 changelog。

这条"稳定版锁定"策略贯穿整个技能：所有示例、CLI 与 API 规则都只对 0.2.1 负责，凡是CHANGELOG.md中Unreleased段描述的能力（例如 HighRes MicroSpin 支持、stacking_z_height）一律不作为稳定能力呈现。

不可逾越的硬件边界：为什么"仿真变实机"被明令禁止

这是整个技能最重要的一条红线：绝不自动连接、初始化、回零（home）、移动、加热、振荡、旋转、泵送或开关任何物理设备。也禁止仅通过修改环境变量、配置值或 import 方式，把一个仿真计划变成 live 后端——这是刻意的"物理执行不可被代码间接触发"设计。

任何单独授权的实机运行之前，必须有训练有素的操作员完成六步确认（详见 SKILL.md）：

1. 明确确认精确的后端、设备身份、固件、传输方式、deck 与协议版本；
2. 将物理 deck 与资源树逐一对账：载架（carrier）、适配器、盖、板、吸头盒、废液区、耗材朝向、条码与每一个占用坐标；
3. 验证校准、示教、运动包络、碰撞风险、抓爪/通道间隙，以及所有吸/排液坐标；
4. 复核液源身份与实际灌装量、死体积、目标容量、吸头类型/容量/滤芯兼容性、通道映射、单位、高度、速率、liquid class、吹出/混匀与污染边界；
5. 确认防护罩、门、废液容量、密闭性、急停就绪、PPE、生物/化学安全控制，以及安全的中止/恢复流程；
6. 当任何环节是新的或发生变化时，先批准一次慢速空跑或无害的试运行。

技能还反复强调三类工具的边界，防止把"台账"误当"传感"：

• Tracker 状态只是记账（bookkeeping），不是传感，无法证明液体或吸头真实存在；
• Visualizer只是渲染资源/追踪事件，不建模物理；
• Chatterbox只是打印计划操作，无法证明校准、可达性、无碰撞、液体行为或设备状态。

必需输入清单：不允许猜测

技能要求在使用前收集齐以下信息，任何缺失都只能产出"假设/阻塞清单 + 离线草稿"（见 SKILL.md 的 Required intake 一节）：

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

这条规则的用意很直接：AI Agent 在物理实验场景中的最大风险就是"合理猜测"，而技能选择在缺失信息时拒绝前进，只产出离线条目。

可复现安装：只装软件，不碰硬件依赖

离线 API 检查与 chatterbox 仿真的标准安装方式（Python 3.11 虚拟环境 + 精确版本锁定）：

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。不要提前安装硬件 extras——只有在用户指名设备并明确批准其传输依赖后，才去核对匹配的稳定设备页面，再考虑诸如"PyLabRobot[serial]==0.2.1"或"PyLabRobot[usb]==0.2.1"的固定安装。

基座PyLabRobot==0.2.1把硬件依赖保持为可选，稳定安装文档列出的 extras 包括serial、usb、ftdi、hid、modbus、opentrons、sila、microscopy、pico、all（详见 hardware-backends.md）。注意all在稳定 0.2.1 中故意不含 microscopy，因为其独立的 NumPy/SDK 约束会带来兼容问题。可选的传输包可能枚举或通信设备——安装本身不构成使用授权。

离线优先工作流：五个零依赖 CLI

技能自带的五个 CLI 全部从仓库根目录运行，遵循严格约束：有界 UTF-8 JSON/CSV、本地非符号链接路径、固定 allowlist、JSON 输出，且任何一个都无法选中 live 后端。

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

各工具的定位与边界（结合 scripts/_common.py 源码确认）：

• validate_manifest.py：校验 protocol manifest schema v1.0。mode必须是offline，单位必须精确等于{"volume": "uL", "length": "mm", "rate": "uL/s", "time": "s"}，并要求声明至少一个 waste 资源、requires_human_confirmation必须为true（见 validate_manifest.py）；
• check_deck_geometry.py：保守的静态轴对齐包围盒检查——资源是否越出 deck 边界、两两是否发生轴对齐重叠。它不是运动规划器，不建模旋转、运动包络、盖子、管路、线缆或公差；
• plan_transfers.py：确定性体积台账 + 一次性吸头分配。要求每行一个全新吸头，检查源/死/目标体积、吸头容量、孔位、通道、高度、速率、单位与 allowlist；
• generate_simulation_plan.py：产出不可执行的 JSON 计划（非 Python 代码）。它把每个转移展开为取吸头、吸液、排液、弃头四步，并固定目标为PyLabRobot==0.2.1、只允许LiquidHandlerChatterboxBackend、把 live 后端标记为禁止、记录零连接尝试，最后附上强制人工复核清单；
• inspect_backends.py：离线后端能力审计。只在参数解析后按固定 allowlist 导入稳定类，读取已安装发行版元数据，检查类签名/方法存在性，但创建零后端实例、不调用setup()、不做任何串口/USB/HID/FTDI/Modbus/网络操作。

其中_common.py的实现给出了具体边界常量：输入文件最大 2 MB、资源最多 256 个、转移最多 10,000 行、尺寸上限 5000 mm、体积上限 1,000,000 µL、速率上限 10,000 µL/s、通道上限 96。safe_input_path会拒绝路径穿越、符号链接与非普通文件，load_json通过object_pairs_hook拒绝重复键、通过parse_constant拒绝非有限数值。

Manifest 结构速览

技能自带合成夹具 tests/pylabrobot/fixtures/protocol_manifest.json 展示了 manifest 的完整形态：顶层为schema_version、protocol_id、mode、units、deck、resources、constraints七个字段；resources支持plate、reservoir、tube_rack、tip_rack、waste五类；液体类资源需要grid（行列、孔容量、死体积、孔深）与initial_volumes_uL；tip_rack 需要tip_type与tips_available；constraints声明允许的 liquid class、吸头类型、通道数、单次最大转移体积与最大速率。正式项目可参照它制作专属 manifest，并以 assets/protocol-manifest.schema.json 为文档级参照。

测试证据：确定性失败即通过

测试套件 tests/pylabrobot/test_clis.py 验证了上述工具的可复现性，值得注意的断言包括：

• 碰撞夹具collision_manifest.json被几何检查以退出码 3 拒绝，且精确报告source_plate与destination_plate的重叠；
• 转移规划对夹具输出tips:A1、tips:B1两个分配，最终台账精确到source_plate:A1=150.0、destination_plate:B1=25.0；
• 仿真计划报告plan_kind=offline_review_only、live_backend_permitted=False、connection_attempted=False，共 8 个步骤；
• 重复 JSON 键与父目录穿越均被确定性拒绝（退出码 2）；
• 后端检查器在零连接断言下通过。

运行方式（技能文档给出的标准命令）：

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \ -s tests/pylabrobot -p "test_*.py" -v

纯软件示例：Chatterbox 协议冒烟

下面这段示例是完全软件化的后端——Chatterbox 会把每个操作打印出来并更新软件状态，不连接任何机器人、不建模机器人物理（见 SKILL.md 的 Verified software-only example）：

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()

这段代码展示了技能推荐的"安全操作形态"：开启双 tracker → 构建 deck 资源树 → 用assign_child_resource放到指定 rails → 设置规划态体积 → 以try/finally保证setup()与stop()成对出现。注意setup()在此只因为后端被字面量构造为软件后端才安全，绝不能从配置字符串、环境变量或插件替换成 live 类。

0.2.1 前端方法签名

参考文档 liquid-handling.md 给出了 0.2.1 的重要前端签名：

pick_up_tips(tip_spots, use_channels=None, offsets=None, **backend_kwargs) drop_tips(tip_spots, use_channels=None, offsets=None, allow_nonzero_volume=False, **backend_kwargs) return_tips(use_channels=None, allow_nonzero_volume=False, offsets=None, **backend_kwargs) aspirate(resources, vols, use_channels=None, flow_rates=None, offsets=None, liquid_height=None, blow_out_air_volume=None, spread="wide", mix=None, **backend_kwargs) dispense(resources, vols, use_channels=None, flow_rates=None, offsets=None, liquid_height=None, blow_out_air_volume=None, spread="wide", mix=None, **backend_kwargs)

单位约定：体积为微升（uL），坐标/高度为毫米（mm），流速为uL/s（除非具体后端页面另有说明）。务必使用与所选资源/通道数量一致的长度列表，不要依赖旧示例里的标量广播。

另一个重要提醒：0.2.1 的transfer(source, targets, ...)表示"从单一源分发到多个目标"，不再是旧的整板复制 API。一对一转移请显式规划 aspirate/dispense 对，并校验通道与吸头状态。

Tracker 与 Liquid Class 的边界

• set_tip_tracking(True)在操作前开启；TipRack.fill()、empty()、set_tip_state(...)修改规划态；return_tips()依赖操作历史。tracker 能捕捉不一致的规划操作，但检测不了吸头是否物理存在、坐稳、堵塞、损坏或类型不符。不要为了绕过NoTipError/HasTipError而关闭 tracking；
• set_volume_tracking(True)后，well.tracker.set_volume(...)、get_used_volume()、get_free_volume()维护规划体积，可拒绝欠吸、吸头过载或孔过载；但不测量弯月面、不确认液体身份，初始状态必须来自可信准备记录与人工对账；
• 0.2.1 中不存在通用的from pylabrobot.liquid_handling import LiquidClass。稳定 liquid class 是厂商专属的，例如pylabrobot.liquid_handling.liquid_classes.hamilton.HamiltonLiquidClass及star子模块下的具体类（如HighVolumeFilter_Water_DispenseSurface_Part），且通过hamilton_liquid_classes=[...]这类STAR 后端 kwarg传入，不是通用前端契约。禁止仅凭名称选择 class，自定义 class 需要文件化称重或测定验证与操作员批准。

API 防陈旧规则：命名即契约

技能整理了 0.2.1 与旧文档/旧代码的命名差异（见 hardware-backends.md 与 SKILL.md）：

• Visualizer(resource=...)必须传入根资源，随后await vis.setup()、await vis.stop()；稳定默认端口是 WebSocket 2121 与文件服务 1337（不是 1234），只应绑定回环地址，受控测试保持open_browser=False；
• 前端方法多为 async；后端 kwargs 与能力是厂商/型号专属的，共享前端不意味着行为一致；
• 支持等级以稳定版 supported-machines 页面为准：Hamilton STAR(let) 为Full（STARDeck/STARLetDeck），Hamilton Vantage 为Mostly，Hamilton Prep/Nimbus 为WIP，Tecan Freedom EVO 为Basic（勿描述为完整或与 STAR 等价），Opentrons OT-2 为Mostly（OpentronsOT2Backend(host, port=31950)）。等级标签不验证特定固件、附件、电脑、传输或协议。

资源树、序列化与安全输入

PyLabRobot 把工作单元建模为资源树：LiquidHandler/Deck→ 载架、适配器、站点、模块 →Plate、TipRack、储液槽、管架、Trash→Well、TipSpot、Tip。每个资源有唯一名称、毫米尺寸、相对父级的可选位置与父子关系，Deck.get_resource(name)依赖唯一名称解析嵌套资源（见 resources.md）。

稳定访问方式示例：

well = plate.get_well("A1") wells = plate.get_wells(["A1", "B1"]) selected_wells = plate["A1"] # list[Well] tip_spot = tips.get_item("A1") tip = tip_spot.get_tip()

Hamilton 的 rails 放置（deck.assign_child_resource(carrier, rails=3)）会在分配时执行碰撞检查并提供ignore_collision逃生口——但不要为了通过布局而设置ignore_collision=True，应修正定义或摆放后再做物理复核。

序列化方面，0.2.1 的稳定方法包括resource.save("deck.json")/Resource.load_from_json_file(...)，以及serialize_all_state()/load_all_state()/save_state_to_file()/load_state_from_file()。技能明确要求：把序列化文件当作不可信输入——只接受有界 UTF-8 JSON 与已批准本地路径，拒绝重复/未知键与非有限值，绝不加载任意 Python/pickle/插件或用户指定类，并保持Resource.deserialize(..., allow_marshal=False)的安全默认值。技能自带的 CLI 不反序列化 PyLabRobot 类，而是使用上述严格 manifest schema，Python 校验器在文档级 schema 之上追加了边界与跨字段检查。

三层软件化能力：不要把"渲染"当"仿真"

参考文档 visualization.md 明确区分了三层：

1. Manifest/台账规划——本技能自带的零依赖 CLI，校验有界 JSON/CSV，产出不可执行 JSON；
2. Chatterbox 后端——PyLabRobot 校验前端/tracker 操作，把操作打印出来而非发送硬件命令；
3. Visualizer——浏览器渲染器，通过 localhost HTTP/WebSocket 接收资源与 tracker 事件。

三者都不是机器人物理仿真器、碰撞-运动规划器、液体动力学模型或物理传感器。Visualizer 会渲染资源树、接收分配/回收回调、渲染规划态吸头与体积；但它不算轨迹/间隙、检测不了缺失的资源/吸头/液体、不建模弯月面/黏度/泡沫/压力/残留，也不仿真固件时序、传感器、互锁、门、手臂或故障。上游贡献者文档明确把浏览器描述为"被动渲染，不执行仿真逻辑"。

多级证据链与测试策略

技能推荐的证据分层（见 visualization.md）：

1. 严格 manifest schema 校验；
2. 静态 deck 边界与轴对齐重叠筛查；
3. 转移/死体积/目标/吸头/通道/速率/高度台账；
4. 不可执行仿真计划复核；
5. 固定 0.2.1 的 import/签名检查且零后端实例；
6. Chatterbox-only 协议冒烟（合成资源）；
7. 可选 Visualizer 复核（已批准的 loopback 主机）；
8. 仅在显式操作员批准后进行独立物理试运行。

测试失败必须确定性呈现：不要捕获宽泛异常后继续、不要关闭 tracker、不要为了通过失败断言而改变期望状态。

何时可以考虑升级版本

当评估后续发布时，技能要求按序执行（见 hardware-backends.md）：确认它在 PyPI 上存在且非预发布 → 对比Requires-Python、extras、tag、changelog 与源码 → 在隔离环境中运行 import/签名与纯软件测试 → 对每个目标型号/固件重新验证并重复试运行。永远以仓库当前锁定的 0.2.1 与v0.2.1tag 为基准。

延伸阅读（仓库内资料）

技能目录下还有六篇专项参考文档，可作为深入研读的入口：

• liquid-handling.md——操作、吸头、tracking、liquid class、单位与验证；
• resources.md——deck、坐标、板、吸头盒、碰撞、状态与序列化；
• hardware-backends.md——验证过的后端名、支持等级、能力与实机放行门槛；
• analytical-equipment.md——酶标仪与天平；
• material-handling.md——泵、加热器、振荡器、温控、存储与离心机；
• visualization.md——chatterbox、Visualizer、localhost 服务与仿真边界。

结语

pylabrobot技能为科研 Agent 提供了一套"规划全离线、执行需真人"的液体处理工作流：以精确版本锁定消除漂移，以五条零依赖 CLI 提供确定性检查，以严格 schema 与 fail-closed 校验守住数据边界，以六步操作员闸门隔离物理风险。对开发者而言，它能作为编写可审查移液协议的脚手架；对实验室而言，它是一份把"软件能力"与"物理责任"清晰切分的工程规范。

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