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 稳定版为PyLabRobot0.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明确确认精确的后端、设备身份、固件、传输方式、deck 与协议版本将物理 deck 与资源树逐一对账载架carrier、适配器、盖、板、吸头盒、废液区、耗材朝向、条码与每一个占用坐标验证校准、示教、运动包络、碰撞风险、抓爪/通道间隙以及所有吸/排液坐标复核液源身份与实际灌装量、死体积、目标容量、吸头类型/容量/滤芯兼容性、通道映射、单位、高度、速率、liquid class、吹出/混匀与污染边界确认防护罩、门、废液容量、密闭性、急停就绪、PPE、生物/化学安全控制以及安全的中止/恢复流程当任何环节是新的或发生变化时先批准一次慢速空跑或无害的试运行。技能还反复强调三类工具的边界防止把台账误当传感Tracker 状态只是记账bookkeeping不是传感无法证明液体或吸头真实存在Visualizer只是渲染资源/追踪事件不建模物理Chatterbox只是打印计划操作无法证明校准、可达性、无碰撞、液体行为或设备状态。必需输入清单不允许猜测技能要求在使用前收集齐以下信息任何缺失都只能产出假设/阻塞清单 离线草稿见 SKILL.md 的 Required intake 一节精确的设备型号、已装选件、固件、计算机/OS 与传输方式稳定的 PyLabRobot 版本与所需 extrasdeck/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 PyLabRobot0.2.1Windows 下改用.venv-pylabrobot\Scripts\python.exe。不要提前安装硬件 extras——只有在用户指名设备并明确批准其传输依赖后才去核对匹配的稳定设备页面再考虑诸如PyLabRobot[serial]0.2.1或PyLabRobot[usb]0.2.1的固定安装。基座PyLabRobot0.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.pycheck_deck_geometry.py保守的静态轴对齐包围盒检查——资源是否越出 deck 边界、两两是否发生轴对齐重叠。它不是运动规划器不建模旋转、运动包络、盖子、管路、线缆或公差plan_transfers.py确定性体积台账 一次性吸头分配。要求每行一个全新吸头检查源/死/目标体积、吸头容量、孔位、通道、高度、速率、单位与 allowlistgenerate_simulation_plan.py产出不可执行的 JSON 计划非 Python 代码。它把每个转移展开为取吸头、吸液、排液、弃头四步并固定目标为PyLabRobot0.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_uLtip_rack 需要tip_type与tips_availableconstraints声明允许的 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:A1150.0、destination_plate:B125.0仿真计划报告plan_kindoffline_review_only、live_backend_permittedFalse、connection_attemptedFalse共 8 个步骤重复 JSON 键与父目录穿越均被确定性拒绝退出码 2后端检查器在零连接断言下通过。运行方式技能文档给出的标准命令PYTHONDONTWRITEBYTECODE1 python3 -m unittest discover \ -s tests/pylabrobot -p test_*.py -v纯软件示例Chatterbox 协议冒烟下面这段示例是完全软件化的后端——Chatterbox 会把每个操作打印出来并更新软件状态不连接任何机器人、不建模机器人物理见 SKILL.md 的 Verified software-only examplefrom 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(nametip_carrier) tips hamilton_96_tiprack_1000uL_filter(nametips) tip_carrier[0] tips plate_carrier PLT_CAR_L5AC_A00(nameplate_carrier) source Cor_96_wellplate_360ul_Fb(namesource) destination Cor_96_wellplate_360ul_Fb(namedestination) plate_carrier[0] source plate_carrier[1] destination deck.assign_child_resource(tip_carrier, rails3) deck.assign_child_resource(plate_carrier, rails15) source.get_well(A1).tracker.set_volume(100.0) # planned state, not sensing lh LiquidHandler(backendLiquidHandlerChatterboxBackend(), deckdeck) 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_channelsNone, offsetsNone, **backend_kwargs) drop_tips(tip_spots, use_channelsNone, offsetsNone, allow_nonzero_volumeFalse, **backend_kwargs) return_tips(use_channelsNone, allow_nonzero_volumeFalse, offsetsNone, **backend_kwargs) aspirate(resources, vols, use_channelsNone, flow_ratesNone, offsetsNone, liquid_heightNone, blow_out_air_volumeNone, spreadwide, mixNone, **backend_kwargs) dispense(resources, vols, use_channelsNone, flow_ratesNone, offsetsNone, liquid_heightNone, blow_out_air_volumeNone, spreadwide, mixNone, **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而关闭 trackingset_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正确命名陈旧/错误命名说明STARBackendSTAR稳定高层后端名VantageBackend—稳定类EVOBackendTecanBackend0.2.1 的 Tecan EVO 后端OpentronsOT2BackendOpentronsBackend网络/API/固件兼容性依型号而异LiquidHandlerChatterboxBackendChatterboxBackend/ChatterBoxBackend后者是独立的历史遗留导出类勿混用Visualizer(resource...)必须传入根资源随后await vis.setup()、await vis.stop()稳定默认端口是 WebSocket 2121 与文件服务 1337不是 1234只应绑定回环地址受控测试保持open_browserFalse前端方法多为 async后端 kwargs 与能力是厂商/型号专属的共享前端不意味着行为一致支持等级以稳定版 supported-machines 页面为准Hamilton STAR(let) 为FullSTARDeck/STARLetDeckHamilton Vantage 为MostlyHamilton Prep/Nimbus 为WIPTecan Freedom EVO 为Basic勿描述为完整或与 STAR 等价Opentrons OT-2 为MostlyOpentronsOT2Backend(host, port31950)。等级标签不验证特定固件、附件、电脑、传输或协议。资源树、序列化与安全输入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, rails3)会在分配时执行碰撞检查并提供ignore_collision逃生口——但不要为了通过布局而设置ignore_collisionTrue应修正定义或摆放后再做物理复核。序列化方面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_marshalFalse)的安全默认值。技能自带的 CLI 不反序列化 PyLabRobot 类而是使用上述严格 manifest schemaPython 校验器在文档级 schema 之上追加了边界与跨字段检查。三层软件化能力不要把渲染当仿真参考文档 visualization.md 明确区分了三层Manifest/台账规划——本技能自带的零依赖 CLI校验有界 JSON/CSV产出不可执行 JSONChatterbox 后端——PyLabRobot 校验前端/tracker 操作把操作打印出来而非发送硬件命令Visualizer——浏览器渲染器通过 localhost HTTP/WebSocket 接收资源与 tracker 事件。三者都不是机器人物理仿真器、碰撞-运动规划器、液体动力学模型或物理传感器。Visualizer 会渲染资源树、接收分配/回收回调、渲染规划态吸头与体积但它不算轨迹/间隙、检测不了缺失的资源/吸头/液体、不建模弯月面/黏度/泡沫/压力/残留也不仿真固件时序、传感器、互锁、门、手臂或故障。上游贡献者文档明确把浏览器描述为被动渲染不执行仿真逻辑。多级证据链与测试策略技能推荐的证据分层见 visualization.md严格 manifest schema 校验静态 deck 边界与轴对齐重叠筛查转移/死体积/目标/吸头/通道/速率/高度台账不可执行仿真计划复核固定 0.2.1 的 import/签名检查且零后端实例Chatterbox-only 协议冒烟合成资源可选 Visualizer 复核已批准的 loopback 主机仅在显式操作员批准后进行独立物理试运行。测试失败必须确定性呈现不要捕获宽泛异常后继续、不要关闭 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考