bears-machines

BEARS 设备

目标

为 PUDA 工作流提供设备选择和功能指导，然后在生成命令前加载正确的设备参考文档。

重要规则

如果不确定某条命令应该使用哪台设备，请先询问用户再继续。 不要自行假设。

设备功能及使用时机

第一台设备（machine_id: "first"）

用于液体处理和载板操作。

功能：

• 移液工作流：吸液、排液、装上吸头、卸下吸头
• 载板和实验室器具工作流：加载载板、依赖位置的操作
• 湿实验室协议中的机器人顺序操作步骤

在以下情况下使用此设备：

• 任务涉及在孔或实验室器具之间转移液体
• 用户提到吸头使用、吸液/排液或载板槽位/实验室器具设置

生成命令前：

• 参考：第一台设备
• 运行 puda machine commands first 以了解可用命令
• 遵循 references/first-machine.md 中的约束和操作顺序

Biologic 设备（machine_id: "biologic"）

用于电化学测试和表征。

功能：

• OCV（开路电压）
• CA（计时电流法）
• PEIS / GEIS（阻抗谱）
• CV（循环伏安法）
• MPP 变体（MPP、MPP_Cycles、MPP_Tracking）

在以下情况下使用此设备：

• 任务涉及电化学测量或电池/电芯表征
• 用户要求进行 OCV、CA、EIS、CV 或 MPP 测试

生成命令前：

• 参考：Biologic 设备
• 运行 puda machine commands biologic 以了解可用命令
• 遵循 references/biologic-machine.md 中的约束

天平设备

用于通过基于 Arduino 的 Linux USB 称重传感器天平进行重量测量。

功能：

• 通过 USB 串口（/dev/ttyUSB* 或 /dev/ttyACM*）连续读取经校准的质量
• 后台读取线程以约 4 Hz 的频率持续传输读数；无需轮询
• 在分液步骤前执行去皮命令，将天平归零
• 新鲜度检查（fresh 标志），用于检测读数是否过时或连接是否断开
• 通过边缘服务发布 NATS 遥测数据
• 支持自定义校准 CSV

在以下情况下使用此设备：

• 工作流需要在液体转移前后称量容器
• 用户要求进行重量校准、计算转移误差或获取天平反馈
• 任务涉及需要质量数据的黏度或转移精度实验

使用前：

• 参考：天平设备
• 向用户询问 Linux 串口（例如 /dev/ttyUSB1）——不要自行假设
• 确保边缘服务正在运行（uv run --package balance-edge python edge/balance.py）

Opentrons Machine (machine_id: "opentrons")

用于 在 Opentrons OT-2 机器人上进行自动化液体处理和完整协议生成。

功能：

• 通过 Protocol.to_python_code() 生成完整协议代码——生成有效且可运行的 OT-2 Python 代码
• 移液工作流：aspirate、dispense、transfer（大体积时自动分批）
• 吸头管理：pick_up_tip、drop_tip
• 实验台和实验室器皿设置：load_labware、load_instrument
• 流程控制：flow_rate、air_gap、blow_out、touch_tip、move_to
• 协议工具：delay、comment、home
• CSV 驱动的循环：使用 read_csv_file + loop 编写数据驱动协议
• 自定义实验室器皿支持：AMDM 天平小瓶（30 mL、50 mL），从 Opentrons 驱动程序的实验室器皿目录中发现，并通过常规的 load_labware 命令加载
• 所有 Gen2 移液器类型：p10、p20、p300、p1000（单通道和多通道）
• 外部相机图像捕获：camera_capture——触发安装在实验台上方的外部相机，拍摄并保存一张孔板静态图像

在以下情况下使用此机器：

• 用户提到 Opentrons OT-2 机器人
• 任务涉及生成完整的 OT-2 协议或单条液体处理命令
• 用户提到 Opentrons 实验室器皿（吸头架、孔板、储液槽、NEST、Corning、天平小瓶）
• 工作流需要根据 CSV 文件进行数据驱动的分液
• 工作流需要在分液步骤后拍摄孔板图像

生成命令前：

• 参考：opentrons-machine
• 在进行任何实际的 Opentrons 运行前，加载并遵循 puda-opentrons-vision-validation：拍摄一张最新的实验台图像，确认每个协议槽位都放置了预期的实验室器皿或物品，并在实验室器皿不确定或不匹配时，请用户确认后再执行。
• 运行 puda machine commands opentrons，了解可用命令
• 遵循 references/opentrons-machine.md 中规定的所有命令类型、参数、执行顺序规则和实验室器皿限制

Elephant Machine (machine_id: "elephant")

用于 六轴机械臂操作、笛卡尔坐标/关节运动、电动夹爪动作、扫描/复位流程以及相机引导的视觉步骤。

功能：

• 笛卡尔位姿运动和相对移动
• 关节角度和单轴运动控制
• 扫描定位和面向复位的恢复工作流
• 电动夹爪操作：init_gripper、open_gripper、close_gripper
• 用于视觉引导任务的 Pi 摄像头和实时视频图像捕获
• 用于校准相机工作流的像素到机器人偏移量转换

在以下情况下使用此机器：

• 任务需要机械臂移动到指定坐标或执行类似抓取和放置的步骤
• 用户要求 Elephant 机械臂运动、扫描/复位行为，或在停止/断电后恢复机械臂
• 工作流包括夹爪控制、Pi 摄像头捕获，或从 Elephant 设置中捕获实时视频快照

生成命令前：

• 参考：elephant-machine
• 运行 puda machine commands elephant，了解可用命令
• 遵循 references/elephant.md 中规定的运动、夹爪、相机和执行顺序限制

选择工作流

1. 解析用户意图并确定任务。
2. 将用户意图与上述机器功能相匹配。
3. 如果机器选择不明确或存在歧义，请询问用户并等待确认。
4. 加载相应的参考文件和 CLI 帮助信息。
5. 只有在确认机器选择后，才生成命令。

输出指引

回答机器选择相关问题时：

• 说明推荐的机器，并给出一句与其功能相对应的理由。
• 如果无法确定，请直接提出澄清问题，不要猜测。

关键顺序规则

• opentrons 协议必须始终以所有移液器均未装有吸头的状态结束。
• 每条 load_labware 命令中的 opentrons 载板位（location）都必须由用户明确确认——绝不假定载板位。
• 执行任何实体 opentrons 运行之前，必须通过视觉验证载板位占用情况和实验室器具；如果所需载板位为空、实验室器具不匹配、受到阻挡或不可见，则不得运行，除非用户明确批准。
• opentrons 的 capture_image 必须单独作为一个协议——绝不能在同一协议中与移液命令组合。
• balance——读取前始终调用 startup()，之后调用 shutdown()。执行分液步骤前始终去皮。使用读数前始终确认 fresh == True。
• elephant——运动前确保机械臂已连接并通电。对于电动夹爪工作流，在断电重启后，先调用 init_gripper()，再调用 open_gripper() 或 close_gripper()。进行相机引导的操作前，优先调用 scan()。