node_to_plr_dict: WareHouse 子节点不写入 PLR children 列表

WareHouse 通过 sites 字符串追踪占位，不依赖 PLR children tree。
当同一载架（如 BIOYOND_PolymerStation_1BottleCarrier）出现在多个
WareHouse 的 children 下时，PLR _check_naming_conflicts 会因
同名子资源（flask_1）重复而报 ValueError。

将 WareHouse 的 children 排除在 PLR dict 外，PLR 树只保留
WareHouse 本身（位置/尺寸），不包含其持有的载架。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.conda/scripts/post-link.bat

@@ -1,9 +0,0 @@
-@echo off
-setlocal enabledelayedexpansion
-
-REM upgrade pip
-"%PREFIX%\python.exe" -m pip install --upgrade pip
-
-REM install extra deps
-"%PREFIX%\python.exe" -m pip install paho-mqtt opentrons_shared_data
-"%PREFIX%\python.exe" -m pip install git+https://github.com/Xuwznln/pylabrobot.git

.conda/scripts/post-link.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-set -euxo pipefail
-
-# make sure pip is available
-"$PREFIX/bin/python" -m pip install --upgrade pip
-
-# install extra deps
-"$PREFIX/bin/python" -m pip install paho-mqtt opentrons_shared_data
-"$PREFIX/bin/python" -m pip install git+https://github.com/Xuwznln/pylabrobot.git

.cursor/rules/device-drivers.mdc

@@ -0,0 +1,328 @@
+---
+description: 设备驱动开发规范
+globs: ["unilabos/devices/**/*.py"]
+---
+
+# 设备驱动开发规范
+
+## 目录结构
+
+```
+unilabos/devices/
+├── virtual/           # 虚拟设备（用于测试）
+│   ├── virtual_stirrer.py
+│   └── virtual_centrifuge.py
+├── liquid_handling/   # 液体处理设备
+├── balance/           # 天平设备
+├── hplc/              # HPLC设备
+├── pump_and_valve/    # 泵和阀门
+├── temperature/       # 温度控制设备
+├── workstation/       # 工作站（组合设备）
+└── ...
+```
+
+## 设备类完整模板
+
+```python
+import asyncio
+import logging
+import time as time_module
+from typing import Dict, Any, Optional
+
+from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
+
+
+class MyDevice:
+    """
+    设备类描述
+
+    Attributes:
+        device_id: 设备唯一标识
+        config: 设备配置字典
+        data: 设备状态数据
+    """
+
+    _ros_node: BaseROS2DeviceNode
+
+    def __init__(
+        self,
+        device_id: str = None,
+        config: Dict[str, Any] = None,
+        **kwargs
+    ):
+        """
+        初始化设备
+
+        Args:
+            device_id: 设备ID
+            config: 配置字典
+            **kwargs: 其他参数
+        """
+        # 兼容不同调用方式
+        if device_id is None and 'id' in kwargs:
+            device_id = kwargs.pop('id')
+        if config is None and 'config' in kwargs:
+            config = kwargs.pop('config')
+
+        self.device_id = device_id or "unknown_device"
+        self.config = config or {}
+        self.data = {}
+
+        # 从config读取参数
+        self.port = self.config.get('port') or kwargs.get('port', 'COM1')
+        self._max_value = self.config.get('max_value', 1000.0)
+
+        # 初始化日志
+        self.logger = logging.getLogger(f"MyDevice.{self.device_id}")
+
+        self.logger.info(f"设备 {self.device_id} 已创建")
+
+    def post_init(self, ros_node: BaseROS2DeviceNode):
+        """
+        ROS节点注入 - 在ROS节点创建后调用
+
+        Args:
+            ros_node: ROS2设备节点实例
+        """
+        self._ros_node = ros_node
+
+    async def initialize(self) -> bool:
+        """
+        初始化设备 - 连接硬件、设置初始状态
+
+        Returns:
+            bool: 初始化是否成功
+        """
+        self.logger.info(f"初始化设备 {self.device_id}")
+
+        try:
+            # 执行硬件初始化
+            # await self._connect_hardware()
+
+            # 设置初始状态
+            self.data.update({
+                "status": "待机",
+                "is_running": False,
+                "current_value": 0.0,
+            })
+
+            self.logger.info(f"设备 {self.device_id} 初始化完成")
+            return True
+
+        except Exception as e:
+            self.logger.error(f"初始化失败: {e}")
+            self.data["status"] = f"错误: {e}"
+            return False
+
+    async def cleanup(self) -> bool:
+        """
+        清理设备 - 断开连接、释放资源
+
+        Returns:
+            bool: 清理是否成功
+        """
+        self.logger.info(f"清理设备 {self.device_id}")
+
+        self.data.update({
+            "status": "离线",
+            "is_running": False,
+        })
+
+        return True
+
+    # ==================== 设备动作 ====================
+
+    async def execute_action(
+        self,
+        param1: float,
+        param2: str = "",
+        **kwargs
+    ) -> bool:
+        """
+        执行设备动作
+
+        Args:
+            param1: 参数1
+            param2: 参数2（可选）
+
+        Returns:
+            bool: 动作是否成功
+        """
+        # 类型转换和验证
+        try:
+            param1 = float(param1)
+        except (ValueError, TypeError) as e:
+            self.logger.error(f"参数类型错误: {e}")
+            return False
+
+        # 参数验证
+        if param1 > self._max_value:
+            self.logger.error(f"参数超出范围: {param1} > {self._max_value}")
+            return False
+
+        self.logger.info(f"执行动作: param1={param1}, param2={param2}")
+
+        # 更新状态
+        self.data.update({
+            "status": "运行中",
+            "is_running": True,
+        })
+
+        # 执行动作（带进度反馈）
+        duration = 10.0  # 秒
+        start_time = time_module.time()
+
+        while True:
+            elapsed = time_module.time() - start_time
+            remaining = max(0, duration - elapsed)
+            progress = min(100, (elapsed / duration) * 100)
+
+            self.data.update({
+                "status": f"运行中: {progress:.0f}%",
+                "remaining_time": remaining,
+            })
+
+            if remaining <= 0:
+                break
+
+            await self._ros_node.sleep(1.0)
+
+        # 完成
+        self.data.update({
+            "status": "完成",
+            "is_running": False,
+        })
+
+        self.logger.info("动作执行完成")
+        return True
+
+    # ==================== 状态属性 ====================
+
+    @property
+    def status(self) -> str:
+        """设备状态 - 自动发布为ROS Topic"""
+        return self.data.get("status", "未知")
+
+    @property
+    def is_running(self) -> bool:
+        """是否正在运行"""
+        return self.data.get("is_running", False)
+
+    @property
+    def current_value(self) -> float:
+        """当前值"""
+        return self.data.get("current_value", 0.0)
+
+    # ==================== 辅助方法 ====================
+
+    def get_device_info(self) -> Dict[str, Any]:
+        """获取设备信息"""
+        return {
+            "device_id": self.device_id,
+            "status": self.status,
+            "is_running": self.is_running,
+            "current_value": self.current_value,
+        }
+
+    def __str__(self) -> str:
+        return f"MyDevice({self.device_id}: {self.status})"
+```
+
+## 关键规则
+
+### 1. 参数处理
+
+所有动作方法的参数都可能以字符串形式传入，必须进行类型转换：
+
+```python
+async def my_action(self, value: float, **kwargs) -> bool:
+    # 始终进行类型转换
+    try:
+        value = float(value)
+    except (ValueError, TypeError) as e:
+        self.logger.error(f"参数类型错误: {e}")
+        return False
+```
+
+### 2. vessel 参数处理
+
+vessel 参数可能是字符串ID或字典：
+
+```python
+def extract_vessel_id(vessel: Union[str, dict]) -> str:
+    if isinstance(vessel, dict):
+        return vessel.get("id", "")
+    return str(vessel) if vessel else ""
+```
+
+### 3. 状态更新
+
+使用 `self.data` 字典存储状态，属性读取状态：
+
+```python
+# 更新状态
+self.data["status"] = "运行中"
+self.data["current_speed"] = 300.0
+
+# 读取状态（通过属性）
+@property
+def status(self) -> str:
+    return self.data.get("status", "待机")
+```
+
+### 4. 异步等待
+
+使用 ROS 节点的 sleep 方法：
+
+```python
+# 正确
+await self._ros_node.sleep(1.0)
+
+# 避免（除非在纯 Python 测试环境）
+await asyncio.sleep(1.0)
+```
+
+### 5. 进度反馈
+
+长时间运行的操作需要提供进度反馈：
+
+```python
+while remaining > 0:
+    progress = (elapsed / total_time) * 100
+    self.data["status"] = f"运行中: {progress:.0f}%"
+    self.data["remaining_time"] = remaining
+
+    await self._ros_node.sleep(1.0)
+```
+
+## 虚拟设备
+
+虚拟设备用于测试和演示，放在 `unilabos/devices/virtual/` 目录：
+
+- 类名以 `Virtual` 开头
+- 文件名以 `virtual_` 开头
+- 模拟真实设备的行为和时序
+- 使用表情符号增强日志可读性（可选）
+
+## 工作站设备
+
+工作站是组合多个设备的复杂设备：
+
+```python
+from unilabos.devices.workstation.workstation_base import WorkstationBase
+
+class MyWorkstation(WorkstationBase):
+    """组合工作站"""
+
+    async def execute_workflow(self, workflow: Dict[str, Any]) -> bool:
+        """执行工作流"""
+        pass
+```
+
+## 设备注册
+
+设备类开发完成后，需要在注册表中注册：
+
+1. 创建/编辑 `unilabos/registry/devices/my_category.yaml`
+2. 添加设备配置（参考 `virtual_device.yaml`）
+3. 运行 `--complete_registry` 自动生成 schema

.cursor/rules/protocol-development.mdc

@@ -0,0 +1,240 @@
+---
+description: 协议编译器开发规范
+globs: ["unilabos/compile/**/*.py"]
+---
+
+# 协议编译器开发规范
+
+## 概述
+
+协议编译器负责将高级实验操作（如 Stir、Add、Filter）编译为设备可执行的动作序列。
+
+## 文件命名
+
+- 位置: `unilabos/compile/`
+- 命名: `{operation}_protocol.py`
+- 示例: `stir_protocol.py`, `add_protocol.py`, `filter_protocol.py`
+
+## 协议函数模板
+
+```python
+from typing import List, Dict, Any, Union
+import networkx as nx
+import logging
+
+from .utils.unit_parser import parse_time_input
+from .utils.vessel_parser import extract_vessel_id
+
+logger = logging.getLogger(__name__)
+
+
+def generate_{operation}_protocol(
+    G: nx.DiGraph,
+    vessel: Union[str, dict],
+    param1: Union[str, float] = "0",
+    param2: float = 0.0,
+    **kwargs
+) -> List[Dict[str, Any]]:
+    """
+    生成{操作}协议序列
+
+    Args:
+        G: 物理拓扑图 (NetworkX DiGraph)
+        vessel: 容器ID或Resource字典
+        param1: 参数1（支持字符串单位，如 "5 min"）
+        param2: 参数2
+        **kwargs: 其他参数
+
+    Returns:
+        List[Dict]: 动作序列
+
+    Raises:
+        ValueError: 参数无效时
+    """
+    # 1. 提取 vessel_id
+    vessel_id = extract_vessel_id(vessel)
+
+    # 2. 验证参数
+    if not vessel_id:
+        raise ValueError("vessel 参数不能为空")
+
+    if vessel_id not in G.nodes():
+        raise ValueError(f"容器 '{vessel_id}' 不存在于系统中")
+
+    # 3. 解析参数（支持单位）
+    parsed_param1 = parse_time_input(param1)  # "5 min" -> 300.0
+
+    # 4. 查找设备
+    device_id = find_connected_device(G, vessel_id, device_type="my_device")
+
+    # 5. 生成动作序列
+    action_sequence = []
+
+    action = {
+        "device_id": device_id,
+        "action_name": "my_action",
+        "action_kwargs": {
+            "vessel": {"id": vessel_id},  # 始终使用字典格式
+            "param1": float(parsed_param1),
+            "param2": float(param2),
+        }
+    }
+    action_sequence.append(action)
+
+    logger.info(f"生成协议: {len(action_sequence)} 个动作")
+    return action_sequence
+
+
+def find_connected_device(
+    G: nx.DiGraph,
+    vessel_id: str,
+    device_type: str = ""
+) -> str:
+    """
+    查找与容器相连的设备
+
+    Args:
+        G: 拓扑图
+        vessel_id: 容器ID
+        device_type: 设备类型关键字
+
+    Returns:
+        str: 设备ID
+    """
+    # 查找所有匹配类型的设备
+    device_nodes = []
+    for node in G.nodes():
+        node_class = G.nodes[node].get('class', '') or ''
+        if device_type.lower() in node_class.lower():
+            device_nodes.append(node)
+
+    # 检查连接
+    if vessel_id and device_nodes:
+        for device in device_nodes:
+            if G.has_edge(device, vessel_id) or G.has_edge(vessel_id, device):
+                return device
+
+    # 返回第一个可用设备
+    if device_nodes:
+        return device_nodes[0]
+
+    # 默认设备
+    return f"{device_type}_1"
+```
+
+## 关键规则
+
+### 1. vessel 参数处理
+
+vessel 参数可能是字符串或字典，需要统一处理：
+
+```python
+def extract_vessel_id(vessel: Union[str, dict]) -> str:
+    """提取vessel_id"""
+    if isinstance(vessel, dict):
+        # 可能是 {"id": "xxx"} 或完整 Resource 对象
+        return vessel.get("id", list(vessel.values())[0].get("id", ""))
+    return str(vessel) if vessel else ""
+```
+
+### 2. action_kwargs 中的 vessel
+
+始终使用 `{"id": vessel_id}` 格式传递 vessel：
+
+```python
+# 正确
+"action_kwargs": {
+    "vessel": {"id": vessel_id},  # 字符串ID包装为字典
+}
+
+# 避免
+"action_kwargs": {
+    "vessel": vessel_resource,  # 不要传递完整 Resource 对象
+}
+```
+
+### 3. 单位解析
+
+使用 `parse_time_input` 解析时间参数：
+
+```python
+from .utils.unit_parser import parse_time_input
+
+# 支持格式: "5 min", "1 h", "300", "1.5 hours"
+time_seconds = parse_time_input("5 min")  # -> 300.0
+time_seconds = parse_time_input(120)      # -> 120.0
+time_seconds = parse_time_input("1 h")    # -> 3600.0
+```
+
+### 4. 参数验证
+
+所有参数必须进行验证和类型转换：
+
+```python
+# 验证范围
+if speed < 10.0 or speed > 1500.0:
+    logger.warning(f"速度 {speed} 超出范围，修正为 300")
+    speed = 300.0
+
+# 类型转换
+param = float(param) if not isinstance(param, (int, float)) else param
+```
+
+### 5. 日志记录
+
+使用项目日志记录器：
+
+```python
+logger = logging.getLogger(__name__)
+
+def generate_protocol(...):
+    logger.info(f"开始生成协议...")
+    logger.debug(f"参数: vessel={vessel_id}, time={time}")
+    logger.warning(f"参数修正: {old_value} -> {new_value}")
+```
+
+## 便捷函数
+
+为常用操作提供便捷函数：
+
+```python
+def stir_briefly(G: nx.DiGraph, vessel: Union[str, dict],
+                speed: float = 300.0) -> List[Dict[str, Any]]:
+    """短时间搅拌（30秒）"""
+    return generate_stir_protocol(G, vessel, time="30", stir_speed=speed)
+
+def stir_vigorously(G: nx.DiGraph, vessel: Union[str, dict],
+                   time: str = "5 min") -> List[Dict[str, Any]]:
+    """剧烈搅拌"""
+    return generate_stir_protocol(G, vessel, time=time, stir_speed=800.0)
+```
+
+## 测试函数
+
+每个协议文件应包含测试函数：
+
+```python
+def test_{operation}_protocol():
+    """测试协议生成"""
+    # 测试参数处理
+    vessel_dict = {"id": "flask_1", "name": "反应瓶1"}
+    vessel_id = extract_vessel_id(vessel_dict)
+    assert vessel_id == "flask_1"
+
+    # 测试单位解析
+    time_s = parse_time_input("5 min")
+    assert time_s == 300.0
+
+
+if __name__ == "__main__":
+    test_{operation}_protocol()
+```
+
+## 现有协议参考
+
+- `stir_protocol.py` - 搅拌操作
+- `add_protocol.py` - 添加物料
+- `filter_protocol.py` - 过滤操作
+- `heatchill_protocol.py` - 加热/冷却
+- `separate_protocol.py` - 分离操作
+- `evaporate_protocol.py` - 蒸发操作

.cursor/rules/registry-config.mdc

@@ -0,0 +1,319 @@
+---
+description: 注册表配置规范 (YAML)
+globs: ["unilabos/registry/**/*.yaml"]
+---
+
+# 注册表配置规范
+
+## 概述
+
+注册表使用 YAML 格式定义设备和资源类型，是 Uni-Lab-OS 的核心配置系统。
+
+## 目录结构
+
+```
+unilabos/registry/
+├── devices/              # 设备类型注册
+│   ├── virtual_device.yaml
+│   ├── liquid_handler.yaml
+│   └── ...
+├── device_comms/         # 通信设备配置
+│   ├── communication_devices.yaml
+│   └── modbus_ioboard.yaml
+└── resources/            # 资源类型注册
+    ├── bioyond/
+    ├── organic/
+    ├── opentrons/
+    └── ...
+```
+
+## 设备注册表格式
+
+### 基本结构
+
+```yaml
+device_type_id:
+  # 基本信息
+  description: "设备描述"
+  version: "1.0.0"
+  category:
+    - category_name
+  icon: "icon_device.webp"
+
+  # 类配置
+  class:
+    module: "unilabos.devices.my_module:MyClass"
+    type: python
+
+    # 状态类型（属性 -> ROS消息类型）
+    status_types:
+      status: String
+      temperature: Float64
+      is_running: Bool
+
+    # 动作映射
+    action_value_mappings:
+      action_name:
+        type: UniLabJsonCommand  # 或 UniLabJsonCommandAsync
+        goal: {}
+        feedback: {}
+        result: {}
+        schema: {...}
+        handles: {}
+```
+
+### action_value_mappings 详细格式
+
+```yaml
+action_value_mappings:
+  # 同步动作
+  my_sync_action:
+    type: UniLabJsonCommand
+    goal:
+      param1: param1
+      param2: param2
+    feedback: {}
+    result:
+      success: success
+      message: message
+    goal_default:
+      param1: 0.0
+      param2: ""
+    handles: {}
+    placeholder_keys:
+      device_param: unilabos_devices   # 设备选择器
+      resource_param: unilabos_resources  # 资源选择器
+    schema:
+      title: "动作名称参数"
+      description: "动作描述"
+      type: object
+      properties:
+        goal:
+          type: object
+          properties:
+            param1:
+              type: number
+            param2:
+              type: string
+          required:
+            - param1
+        feedback: {}
+        result:
+          type: object
+          properties:
+            success:
+              type: boolean
+            message:
+              type: string
+      required:
+        - goal
+
+  # 异步动作
+  my_async_action:
+    type: UniLabJsonCommandAsync
+    goal: {}
+    feedback:
+      progress: progress
+      current_status: status
+    result:
+      success: success
+    schema: {...}
+```
+
+### 自动生成的动作
+
+以 `auto-` 开头的动作由系统自动生成：
+
+```yaml
+action_value_mappings:
+  auto-initialize:
+    type: UniLabJsonCommandAsync
+    goal: {}
+    feedback: {}
+    result: {}
+    schema: {...}
+
+  auto-cleanup:
+    type: UniLabJsonCommandAsync
+    goal: {}
+    feedback: {}
+    result: {}
+    schema: {...}
+```
+
+### handles 配置
+
+用于工作流编辑器中的数据流连接：
+
+```yaml
+handles:
+  input:
+    - handler_key: "input_resource"
+      data_type: "resource"
+      label: "输入资源"
+      data_source: "handle"
+      data_key: "resources"
+  output:
+    - handler_key: "output_labware"
+      data_type: "resource"
+      label: "输出器皿"
+      data_source: "executor"
+      data_key: "created_resource.@flatten"
+```
+
+## 资源注册表格式
+
+```yaml
+resource_type_id:
+  description: "资源描述"
+  version: "1.0.0"
+  category:
+    - category_name
+  icon: ""
+  handles: []
+  init_param_schema: {}
+
+  class:
+    module: "unilabos.resources.my_module:MyResource"
+    type: pylabrobot  # 或 python
+```
+
+### PyLabRobot 资源示例
+
+```yaml
+BIOYOND_Electrolyte_6VialCarrier:
+  category:
+    - bottle_carriers
+    - bioyond
+  class:
+    module: "unilabos.resources.bioyond.bottle_carriers:BIOYOND_Electrolyte_6VialCarrier"
+    type: pylabrobot
+  version: "1.0.0"
+```
+
+## 状态类型映射
+
+Python 类型到 ROS 消息类型的映射：
+
+| Python 类型 | ROS 消息类型 |
+|------------|-------------|
+| `str` | `String` |
+| `bool` | `Bool` |
+| `int` | `Int64` |
+| `float` | `Float64` |
+| `list` | `String` (序列化) |
+| `dict` | `String` (序列化) |
+
+## 自动完善注册表
+
+使用 `--complete_registry` 参数自动生成 schema：
+
+```bash
+python -m unilabos.app.main --complete_registry
+```
+
+这会：
+1. 扫描设备类的方法签名
+2. 自动生成 `auto-` 前缀的动作
+3. 生成 JSON Schema
+4. 更新 YAML 文件
+
+## 验证规则
+
+1. **device_type_id** 必须唯一
+2. **module** 路径必须正确可导入
+3. **status_types** 的类型必须是有效的 ROS 消息类型
+4. **schema** 必须是有效的 JSON Schema
+
+## 示例：完整设备配置
+
+```yaml
+virtual_stirrer:
+  category:
+    - virtual_device
+  description: "虚拟搅拌器设备"
+  version: "1.0.0"
+  icon: "icon_stirrer.webp"
+  handles: []
+  init_param_schema: {}
+
+  class:
+    module: "unilabos.devices.virtual.virtual_stirrer:VirtualStirrer"
+    type: python
+
+    status_types:
+      status: String
+      operation_mode: String
+      current_speed: Float64
+      is_stirring: Bool
+      remaining_time: Float64
+
+    action_value_mappings:
+      auto-initialize:
+        type: UniLabJsonCommandAsync
+        goal: {}
+        feedback: {}
+        result: {}
+        schema:
+          title: "initialize参数"
+          type: object
+          properties:
+            goal:
+              type: object
+              properties: {}
+            feedback: {}
+            result: {}
+          required:
+            - goal
+
+      stir:
+        type: UniLabJsonCommandAsync
+        goal:
+          stir_time: stir_time
+          stir_speed: stir_speed
+          settling_time: settling_time
+        feedback:
+          current_speed: current_speed
+          remaining_time: remaining_time
+        result:
+          success: success
+        goal_default:
+          stir_time: 60.0
+          stir_speed: 300.0
+          settling_time: 30.0
+        handles: {}
+        schema:
+          title: "stir参数"
+          description: "搅拌操作"
+          type: object
+          properties:
+            goal:
+              type: object
+              properties:
+                stir_time:
+                  type: number
+                  description: "搅拌时间（秒）"
+                stir_speed:
+                  type: number
+                  description: "搅拌速度（RPM）"
+                settling_time:
+                  type: number
+                  description: "沉降时间（秒）"
+              required:
+                - stir_time
+                - stir_speed
+            feedback:
+              type: object
+              properties:
+                current_speed:
+                  type: number
+                remaining_time:
+                  type: number
+            result:
+              type: object
+              properties:
+                success:
+                  type: boolean
+          required:
+            - goal
+```

.cursor/rules/ros-integration.mdc

@@ -0,0 +1,233 @@
+---
+description: ROS 2 集成开发规范
+globs: ["unilabos/ros/**/*.py", "**/*_node.py"]
+---
+
+# ROS 2 集成开发规范
+
+## 概述
+
+Uni-Lab-OS 使用 ROS 2 作为设备通信中间件，基于 rclpy 实现。
+
+## 核心组件
+
+### BaseROS2DeviceNode
+
+设备节点基类，提供：
+- ROS Topic 自动发布（状态属性）
+- Action Server 自动创建（设备动作）
+- 资源管理服务
+- 异步任务调度
+
+```python
+from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
+```
+
+### 消息转换器
+
+```python
+from unilabos.ros.msgs.message_converter import (
+    convert_to_ros_msg,
+    convert_from_ros_msg_with_mapping,
+    msg_converter_manager,
+    ros_action_to_json_schema,
+    ros_message_to_json_schema,
+)
+```
+
+## 设备与 ROS 集成
+
+### post_init 方法
+
+设备类必须实现 `post_init` 方法接收 ROS 节点：
+
+```python
+class MyDevice:
+    _ros_node: BaseROS2DeviceNode
+
+    def post_init(self, ros_node: BaseROS2DeviceNode):
+        """ROS节点注入"""
+        self._ros_node = ros_node
+```
+
+### 状态属性发布
+
+设备的 `@property` 属性会自动发布为 ROS Topic：
+
+```python
+class MyDevice:
+    @property
+    def temperature(self) -> float:
+        return self._temperature
+
+    # 自动发布到 /{namespace}/temperature Topic
+```
+
+### Topic 配置装饰器
+
+```python
+from unilabos.utils.decorator import topic_config
+
+class MyDevice:
+    @property
+    @topic_config(period=1.0, print_publish=False, qos=10)
+    def fast_data(self) -> float:
+        """高频数据 - 每秒发布一次"""
+        return self._fast_data
+
+    @property
+    @topic_config(period=5.0)
+    def slow_data(self) -> str:
+        """低频数据 - 每5秒发布一次"""
+        return self._slow_data
+```
+
+### 订阅装饰器
+
+```python
+from unilabos.utils.decorator import subscribe
+
+class MyDevice:
+    @subscribe(topic="/external/sensor_data", qos=10)
+    def on_sensor_data(self, msg):
+        """订阅外部Topic"""
+        self._sensor_value = msg.data
+```
+
+## 异步操作
+
+### 使用 ROS 节点睡眠
+
+```python
+# 推荐：使用ROS节点的睡眠方法
+await self._ros_node.sleep(1.0)
+
+# 不推荐：直接使用asyncio（可能导致回调阻塞）
+await asyncio.sleep(1.0)
+```
+
+### 获取事件循环
+
+```python
+from unilabos.ros.x.rclpyx import get_event_loop
+
+loop = get_event_loop()
+```
+
+## 消息类型
+
+### unilabos_msgs 包
+
+```python
+from unilabos_msgs.msg import Resource
+from unilabos_msgs.srv import (
+    ResourceAdd,
+    ResourceDelete,
+    ResourceUpdate,
+    ResourceList,
+    SerialCommand,
+)
+from unilabos_msgs.action import SendCmd
+```
+
+### Resource 消息结构
+
+```python
+Resource:
+    id: str
+    name: str
+    category: str
+    type: str
+    parent: str
+    children: List[str]
+    config: str  # JSON字符串
+    data: str    # JSON字符串
+    sample_id: str
+    pose: Pose
+```
+
+## 日志适配器
+
+```python
+from unilabos.utils.log import info, debug, warning, error, trace
+
+class MyDevice:
+    def __init__(self):
+        # 创建设备专属日志器
+        self.logger = logging.getLogger(f"MyDevice.{self.device_id}")
+```
+
+ROSLoggerAdapter 同时向自定义日志和 ROS 日志发送消息。
+
+## Action Server
+
+设备动作自动创建为 ROS Action Server：
+
+```yaml
+# 在注册表中配置
+action_value_mappings:
+  my_action:
+    type: UniLabJsonCommandAsync  # 异步Action
+    goal: {...}
+    feedback: {...}
+    result: {...}
+```
+
+### Action 类型
+
+- **UniLabJsonCommand**: 同步动作
+- **UniLabJsonCommandAsync**: 异步动作（支持feedback）
+
+## 服务客户端
+
+```python
+from rclpy.client import Client
+
+# 调用其他节点的服务
+response = await self._ros_node.call_service(
+    service_name="/other_node/service",
+    request=MyServiceRequest(...)
+)
+```
+
+## 命名空间
+
+设备节点使用命名空间隔离：
+
+```
+/{device_id}/                 # 设备命名空间
+/{device_id}/status          # 状态Topic
+/{device_id}/temperature     # 温度Topic
+/{device_id}/my_action       # 动作Server
+```
+
+## 调试
+
+### 查看 Topic
+
+```bash
+ros2 topic list
+ros2 topic echo /{device_id}/status
+```
+
+### 查看 Action
+
+```bash
+ros2 action list
+ros2 action info /{device_id}/my_action
+```
+
+### 查看 Service
+
+```bash
+ros2 service list
+ros2 service call /{device_id}/resource_list unilabos_msgs/srv/ResourceList
+```
+
+## 最佳实践
+
+1. **状态属性命名**: 使用蛇形命名法（snake_case）
+2. **Topic 频率**: 根据数据变化频率调整，避免过高频率
+3. **Action 反馈**: 长时间操作提供进度反馈
+4. **错误处理**: 使用 try-except 捕获并记录错误
+5. **资源清理**: 在 cleanup 方法中正确清理资源

.cursor/rules/testing-patterns.mdc

@@ -0,0 +1,357 @@
+---
+description: 测试开发规范
+globs: ["tests/**/*.py", "**/test_*.py"]
+---
+
+# 测试开发规范
+
+## 目录结构
+
+```
+tests/
+├── __init__.py
+├── devices/              # 设备测试
+│   └── liquid_handling/
+│       └── test_transfer_liquid.py
+├── resources/            # 资源测试
+│   ├── test_bottle_carrier.py
+│   └── test_resourcetreeset.py
+├── ros/                  # ROS消息测试
+│   └── msgs/
+│       ├── test_basic.py
+│       ├── test_conversion.py
+│       └── test_mapping.py
+└── workflow/             # 工作流测试
+    └── merge_workflow.py
+```
+
+## 测试框架
+
+使用 pytest 作为测试框架：
+
+```bash
+# 运行所有测试
+pytest tests/
+
+# 运行特定测试文件
+pytest tests/resources/test_bottle_carrier.py
+
+# 运行特定测试函数
+pytest tests/resources/test_bottle_carrier.py::test_bottle_carrier
+
+# 显示详细输出
+pytest -v tests/
+
+# 显示打印输出
+pytest -s tests/
+```
+
+## 测试文件模板
+
+```python
+import pytest
+from typing import List, Dict, Any
+
+# 导入被测试的模块
+from unilabos.resources.bioyond.bottle_carriers import (
+    BIOYOND_Electrolyte_6VialCarrier,
+)
+from unilabos.resources.bioyond.bottles import (
+    BIOYOND_PolymerStation_Solid_Vial,
+)
+
+
+class TestBottleCarrier:
+    """BottleCarrier 测试类"""
+
+    def setup_method(self):
+        """每个测试方法前执行"""
+        self.carrier = BIOYOND_Electrolyte_6VialCarrier("test_carrier")
+
+    def teardown_method(self):
+        """每个测试方法后执行"""
+        pass
+
+    def test_carrier_creation(self):
+        """测试载架创建"""
+        assert self.carrier.name == "test_carrier"
+        assert len(self.carrier.sites) == 6
+
+    def test_bottle_placement(self):
+        """测试瓶子放置"""
+        bottle = BIOYOND_PolymerStation_Solid_Vial("test_bottle")
+        # 测试逻辑...
+        assert bottle.name == "test_bottle"
+
+
+def test_standalone_function():
+    """独立测试函数"""
+    result = some_function()
+    assert result is True
+
+
+# 参数化测试
+@pytest.mark.parametrize("input,expected", [
+    ("5 min", 300.0),
+    ("1 h", 3600.0),
+    ("120", 120.0),
+    (60, 60.0),
+])
+def test_time_parsing(input, expected):
+    """测试时间解析"""
+    from unilabos.compile.utils.unit_parser import parse_time_input
+    assert parse_time_input(input) == expected
+
+
+# 异常测试
+def test_invalid_input_raises_error():
+    """测试无效输入抛出异常"""
+    with pytest.raises(ValueError) as exc_info:
+        invalid_function("bad_input")
+    assert "invalid" in str(exc_info.value).lower()
+
+
+# 跳过条件测试
+@pytest.mark.skipif(
+    not os.environ.get("ROS_DISTRO"),
+    reason="需要ROS环境"
+)
+def test_ros_feature():
+    """需要ROS环境的测试"""
+    pass
+```
+
+## 设备测试
+
+### 虚拟设备测试
+
+```python
+import pytest
+import asyncio
+from unittest.mock import MagicMock, AsyncMock
+
+from unilabos.devices.virtual.virtual_stirrer import VirtualStirrer
+
+
+class TestVirtualStirrer:
+    """VirtualStirrer 测试"""
+
+    @pytest.fixture
+    def stirrer(self):
+        """创建测试用搅拌器"""
+        device = VirtualStirrer(
+            device_id="test_stirrer",
+            config={"max_speed": 1500.0, "min_speed": 50.0}
+        )
+
+        # Mock ROS节点
+        mock_node = MagicMock()
+        mock_node.sleep = AsyncMock(return_value=None)
+        device.post_init(mock_node)
+
+        return device
+
+    @pytest.mark.asyncio
+    async def test_initialize(self, stirrer):
+        """测试初始化"""
+        result = await stirrer.initialize()
+        assert result is True
+        assert stirrer.status == "待机中"
+
+    @pytest.mark.asyncio
+    async def test_stir_action(self, stirrer):
+        """测试搅拌动作"""
+        await stirrer.initialize()
+
+        result = await stirrer.stir(
+            stir_time=5.0,
+            stir_speed=300.0,
+            settling_time=2.0
+        )
+
+        assert result is True
+        assert stirrer.operation_mode == "Completed"
+
+    @pytest.mark.asyncio
+    async def test_stir_invalid_speed(self, stirrer):
+        """测试无效速度"""
+        await stirrer.initialize()
+
+        # 速度超出范围
+        result = await stirrer.stir(
+            stir_time=5.0,
+            stir_speed=2000.0,  # 超过max_speed
+            settling_time=0.0
+        )
+
+        assert result is False
+        assert "错误" in stirrer.status
+```
+
+### 异步测试配置
+
+```python
+# conftest.py
+import pytest
+import asyncio
+
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """创建事件循环"""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+```
+
+## 资源测试
+
+```python
+import pytest
+from unilabos.resources.resource_tracker import (
+    ResourceTreeSet,
+    ResourceTreeInstance,
+)
+
+
+def test_resource_tree_creation():
+    """测试资源树创建"""
+    tree_set = ResourceTreeSet()
+
+    # 添加资源
+    resource = {"id": "res_1", "name": "Resource 1"}
+    tree_set.add_resource(resource)
+
+    # 验证
+    assert len(tree_set.all_nodes) == 1
+    assert tree_set.get_resource("res_1") is not None
+
+
+def test_resource_tree_merge():
+    """测试资源树合并"""
+    local_set = ResourceTreeSet()
+    remote_set = ResourceTreeSet()
+
+    # 设置数据...
+
+    local_set.merge_remote_resources(remote_set)
+
+    # 验证合并结果...
+```
+
+## ROS 消息测试
+
+```python
+import pytest
+from unilabos.ros.msgs.message_converter import (
+    convert_to_ros_msg,
+    convert_from_ros_msg_with_mapping,
+    msg_converter_manager,
+)
+
+
+def test_message_conversion():
+    """测试消息转换"""
+    # Python -> ROS
+    python_data = {"id": "test", "value": 42}
+    ros_msg = convert_to_ros_msg(python_data, MyMsgType)
+
+    assert ros_msg.id == "test"
+    assert ros_msg.value == 42
+
+    # ROS -> Python
+    result = convert_from_ros_msg_with_mapping(ros_msg, mapping)
+    assert result["id"] == "test"
+```
+
+## 协议测试
+
+```python
+import pytest
+import networkx as nx
+from unilabos.compile.stir_protocol import (
+    generate_stir_protocol,
+    extract_vessel_id,
+)
+
+
+@pytest.fixture
+def topology_graph():
+    """创建测试拓扑图"""
+    G = nx.DiGraph()
+    G.add_node("flask_1", **{"class": "flask"})
+    G.add_node("stirrer_1", **{"class": "virtual_stirrer"})
+    G.add_edge("stirrer_1", "flask_1")
+    return G
+
+
+def test_generate_stir_protocol(topology_graph):
+    """测试搅拌协议生成"""
+    actions = generate_stir_protocol(
+        G=topology_graph,
+        vessel="flask_1",
+        time="5 min",
+        stir_speed=300.0
+    )
+
+    assert len(actions) == 1
+    assert actions[0]["device_id"] == "stirrer_1"
+    assert actions[0]["action_name"] == "stir"
+
+
+def test_extract_vessel_id():
+    """测试vessel_id提取"""
+    # 字典格式
+    assert extract_vessel_id({"id": "flask_1"}) == "flask_1"
+
+    # 字符串格式
+    assert extract_vessel_id("flask_2") == "flask_2"
+
+    # 空值
+    assert extract_vessel_id("") == ""
+```
+
+## 测试标记
+
+```python
+# 慢速测试
+@pytest.mark.slow
+def test_long_running():
+    pass
+
+# 需要网络
+@pytest.mark.network
+def test_network_call():
+    pass
+
+# 需要ROS
+@pytest.mark.ros
+def test_ros_feature():
+    pass
+```
+
+运行特定标记的测试：
+
+```bash
+pytest -m "not slow"  # 排除慢速测试
+pytest -m ros         # 仅ROS测试
+```
+
+## 覆盖率
+
+```bash
+# 生成覆盖率报告
+pytest --cov=unilabos tests/
+
+# HTML报告
+pytest --cov=unilabos --cov-report=html tests/
+```
+
+## 最佳实践
+
+1. **测试命名**: `test_{功能}_{场景}_{预期结果}`
+2. **独立性**: 每个测试独立运行，不依赖其他测试
+3. **Mock外部依赖**: 使用 unittest.mock 模拟外部服务
+4. **参数化**: 使用 `@pytest.mark.parametrize` 减少重复代码
+5. **fixtures**: 使用 fixtures 共享测试设置
+6. **断言清晰**: 每个断言只验证一件事

.cursor/rules/unilabos-project.mdc

@@ -0,0 +1,353 @@
+---
+description: Uni-Lab-OS 实验室自动化平台开发规范 - 核心规则
+globs: ["**/*.py", "**/*.yaml", "**/*.json"]
+---
+
+# Uni-Lab-OS 项目开发规范
+
+## 项目概述
+
+Uni-Lab-OS 是一个实验室自动化操作系统，用于连接和控制各种实验设备，实现实验工作流的自动化和标准化。
+
+## 技术栈
+
+- **Python 3.11** - 核心开发语言
+- **ROS 2** - 设备通信中间件 (rclpy)
+- **Conda/Mamba** - 包管理 (robostack-staging, conda-forge)
+- **FastAPI** - Web API 服务
+- **WebSocket** - 实时通信
+- **NetworkX** - 拓扑图管理
+- **YAML** - 配置和注册表定义
+- **PyLabRobot** - 实验室自动化库集成
+- **pytest** - 测试框架
+- **asyncio** - 异步编程
+
+## 项目结构
+
+```
+unilabos/
+├── app/           # 应用入口、Web服务、后端
+├── compile/       # 协议编译器 (stir, add, filter 等)
+├── config/        # 配置管理
+├── devices/       # 设备驱动 (真实/虚拟)
+├── device_comms/  # 设备通信协议
+├── device_mesh/   # 3D网格和可视化
+├── registry/      # 设备和资源类型注册表 (YAML)
+├── resources/     # 资源定义
+├── ros/           # ROS 2 集成
+├── utils/         # 工具函数
+└── workflow/      # 工作流管理
+```
+
+## 代码规范
+
+### Python 风格
+
+1. **类型注解**：所有函数必须使用类型注解
+   ```python
+   def transfer_liquid(
+       source: str,
+       destination: str,
+       volume: float,
+       **kwargs
+   ) -> List[Dict[str, Any]]:
+   ```
+
+2. **Docstring**：使用 Google 风格的文档字符串
+   ```python
+   def initialize(self) -> bool:
+       """
+       初始化设备
+
+       Returns:
+           bool: 初始化是否成功
+       """
+   ```
+
+3. **导入顺序**：
+   - 标准库
+   - 第三方库
+   - ROS 相关 (rclpy, unilabos_msgs)
+   - 项目内部模块
+
+### 异步编程
+
+1. 设备操作方法使用 `async def`
+2. 使用 `await self._ros_node.sleep()` 而非 `asyncio.sleep()`
+3. 长时间运行操作需提供进度反馈
+
+```python
+async def stir(self, stir_time: float, stir_speed: float, **kwargs) -> bool:
+    """执行搅拌操作"""
+    start_time = time_module.time()
+    while True:
+        elapsed = time_module.time() - start_time
+        remaining = max(0, stir_time - elapsed)
+
+        self.data.update({
+            "remaining_time": remaining,
+            "status": f"搅拌中: {stir_speed} RPM"
+        })
+
+        if remaining <= 0:
+            break
+        await self._ros_node.sleep(1.0)
+    return True
+```
+
+### 日志规范
+
+使用项目自定义日志系统：
+
+```python
+from unilabos.utils.log import logger, info, debug, warning, error, trace
+
+# 在设备类中使用
+self.logger = logging.getLogger(f"DeviceName.{self.device_id}")
+self.logger.info("设备初始化完成")
+```
+
+## 设备驱动开发
+
+### 设备类结构
+
+```python
+from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
+
+class MyDevice:
+    """设备驱动类"""
+
+    _ros_node: BaseROS2DeviceNode
+
+    def __init__(self, device_id: str = None, config: Dict[str, Any] = None, **kwargs):
+        self.device_id = device_id or "unknown_device"
+        self.config = config or {}
+        self.data = {}  # 设备状态数据
+
+    def post_init(self, ros_node: BaseROS2DeviceNode):
+        """ROS节点注入"""
+        self._ros_node = ros_node
+
+    async def initialize(self) -> bool:
+        """初始化设备"""
+        pass
+
+    async def cleanup(self) -> bool:
+        """清理设备"""
+        pass
+
+    # 状态属性 - 自动发布为 ROS Topic
+    @property
+    def status(self) -> str:
+        return self.data.get("status", "待机")
+```
+
+### 状态属性装饰器
+
+```python
+from unilabos.utils.decorator import topic_config
+
+class MyDevice:
+    @property
+    @topic_config(period=1.0, qos=10)  # 每秒发布一次
+    def temperature(self) -> float:
+        return self._temperature
+```
+
+### 虚拟设备
+
+虚拟设备放置在 `unilabos/devices/virtual/` 目录下，命名为 `virtual_*.py`
+
+## 注册表配置
+
+### 设备注册表 (YAML)
+
+位置: `unilabos/registry/devices/*.yaml`
+
+```yaml
+my_device_type:
+  category:
+    - my_category
+  description: "设备描述"
+  version: "1.0.0"
+  class:
+    module: "unilabos.devices.my_device:MyDevice"
+    type: python
+    status_types:
+      status: String
+      temperature: Float64
+    action_value_mappings:
+      auto-initialize:
+        type: UniLabJsonCommandAsync
+        goal: {}
+        feedback: {}
+        result: {}
+        schema: {...}
+```
+
+### 资源注册表 (YAML)
+
+位置: `unilabos/registry/resources/**/*.yaml`
+
+```yaml
+my_container:
+  category:
+    - container
+  class:
+    module: "unilabos.resources.my_resource:MyContainer"
+    type: pylabrobot
+  version: "1.0.0"
+```
+
+## 协议编译器
+
+位置: `unilabos/compile/*_protocol.py`
+
+### 协议生成函数模板
+
+```python
+from typing import List, Dict, Any, Union
+import networkx as nx
+
+def generate_my_protocol(
+    G: nx.DiGraph,
+    vessel: Union[str, dict],
+    param1: float = 0.0,
+    **kwargs
+) -> List[Dict[str, Any]]:
+    """
+    生成操作协议序列
+
+    Args:
+        G: 物理拓扑图
+        vessel: 容器ID或字典
+        param1: 参数1
+
+    Returns:
+        List[Dict]: 动作序列
+    """
+    # 提取vessel_id
+    vessel_id = vessel if isinstance(vessel, str) else vessel.get("id", "")
+
+    # 查找设备
+    device_id = find_connected_device(G, vessel_id)
+
+    # 生成动作
+    action_sequence = [{
+        "device_id": device_id,
+        "action_name": "my_action",
+        "action_kwargs": {
+            "vessel": {"id": vessel_id},
+            "param1": float(param1)
+        }
+    }]
+
+    return action_sequence
+```
+
+## 测试规范
+
+### 测试文件位置
+
+- 单元测试: `tests/` 目录
+- 设备测试: `tests/devices/`
+- 资源测试: `tests/resources/`
+- ROS消息测试: `tests/ros/msgs/`
+
+### 测试命名
+
+```python
+# tests/devices/my_device/test_my_device.py
+
+import pytest
+
+def test_device_initialization():
+    """测试设备初始化"""
+    pass
+
+def test_device_action():
+    """测试设备动作"""
+    pass
+```
+
+## 错误处理
+
+```python
+from unilabos.utils.exception import UniLabException
+
+try:
+    result = await device.execute_action()
+except ValueError as e:
+    self.logger.error(f"参数错误: {e}")
+    self.data["status"] = "错误: 参数无效"
+    return False
+except Exception as e:
+    self.logger.error(f"执行失败: {e}")
+    raise
+```
+
+## 配置管理
+
+```python
+from unilabos.config.config import BasicConfig, HTTPConfig
+
+# 读取配置
+port = BasicConfig.port
+is_host = BasicConfig.is_host_mode
+
+# 配置文件: local_config.py
+```
+
+## 常用工具
+
+### 单例模式
+
+```python
+from unilabos.utils.decorator import singleton
+
+@singleton
+class MyManager:
+    pass
+```
+
+### 类型检查
+
+```python
+from unilabos.utils.type_check import NoAliasDumper
+
+yaml.dump(data, f, Dumper=NoAliasDumper)
+```
+
+### 导入管理
+
+```python
+from unilabos.utils.import_manager import get_class
+
+device_class = get_class("unilabos.devices.my_device:MyDevice")
+```
+
+## Git 提交规范
+
+提交信息格式:
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+类型:
+- `feat`: 新功能
+- `fix`: 修复bug
+- `docs`: 文档更新
+- `refactor`: 重构
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+
+示例:
+```
+feat(devices): 添加虚拟搅拌器设备
+
+- 实现VirtualStirrer类
+- 支持定时搅拌和持续搅拌模式
+- 添加速度验证逻辑
+```

.cursor/skills/add-device/SKILL.md

@@ -71,22 +71,6 @@ from unilabos.registry.decorators import action
 - `_` 开头的方法 → 不扫描
 - `@not_action` 标记的方法 → 排除
 
-### 参数文档 → JSON Schema 元数据
-
-在 `__init__` 和 action 方法 docstring 的 `Args:` 小节里，使用以下格式生成入参 schema 的显示信息：
-
-```python
-"""
-Args:
-    param[显示名称]: 参数说明，会写入 JSON Schema 的 description。
-"""
-```
-
-- `param[显示名称]` 的显示名称会写入 goal property 的 `title`。
-- `:` 后面的说明会写入 goal property 的 `description`。
-- 如果只写 `param: 参数说明`，`title` 会兜底为字段名，`description` 使用参数说明。
-- 如果没有写参数文档，生成器也会兜底补齐 `title=<字段名>` 和 `description=""`，但新设备应优先写清楚显示名和说明。
-
 ### @topic_config — 状态属性配置
 
 ```python
@@ -121,27 +105,13 @@ import logging
 from typing import Any, Dict, Optional
 
 from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
-from unilabos.registry.decorators import action, device, not_action, topic_config
+from unilabos.registry.decorators import device, action, topic_config, not_action
 
-@device(
-    id="my_device",
-    category=["my_category"],
-    description="设备描述",
-    display_name="设备显示名",
-)
+@device(id="my_device", category=["my_category"], description="设备描述")
 class MyDevice:
-    """设备类说明。"""
-
     _ros_node: BaseROS2DeviceNode
 
     def __init__(self, device_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, **kwargs):
-        """
-        初始化设备。
-
-        Args:
-            device_id[设备ID]: 设备实例 ID，默认使用 my_device。
-            config[设备配置]: 设备启动配置。
-        """
         self.device_id = device_id or "my_device"
         self.config = config or {}
         self.logger = logging.getLogger(f"MyDevice.{self.device_id}")
@@ -163,13 +133,7 @@ class MyDevice:
 
     @action(description="执行操作")
     def my_action(self, param: float = 0.0, name: str = "") -> Dict[str, Any]:
-        """
-        带 @action 装饰器 → 注册为 'my_action' 动作。
-
-        Args:
-            param[操作数值]: 操作使用的数值参数。
-            name[操作名称]: 操作名称或备注。
-        """
+        """带 @action 装饰器 → 注册为 'my_action' 动作"""
         return {"success": True}
 
     def get_info(self) -> Dict[str, Any]:

.cursor/skills/host-node/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: host-node
+description: Operate Uni-Lab host node via REST API — create resources, test latency, test resource tree, manual confirm. Use when the user mentions host_node, creating resources, resource management, testing latency, or any host node operation.
+---
+
+# Host Node API Skill
+
+## 设备信息
+
+- **device_id**: `host_node`
+- **Python 源码**: `unilabos/ros/nodes/presets/host_node.py`
+- **设备类**: `HostNode`
+- **动作数**: 4（`create_resource`, `test_latency`, `auto-test_resource`, `manual_confirm`）
+
+## 前置条件（缺一不可）
+
+使用本 skill 前，**必须**先确认以下信息。如果缺少任何一项，**立即向用户询问并终止**，等补齐后再继续。
+
+### 1. ak / sk → AUTH
+
+从启动参数 `--ak` `--sk` 或 config.py 中获取，生成 token：`base64(ak:sk)` → `Authorization: Lab <token>`
+
+### 2. --addr → BASE URL
+
+| `--addr` 值  | BASE                                |
+| ------------ | ----------------------------------- |
+| `test`       | `https://leap-lab.test.bohrium.com` |
+| `uat`        | `https://leap-lab.uat.bohrium.com`  |
+| `local`      | `http://127.0.0.1:48197`            |
+| 不传（默认） | `https://leap-lab.bohrium.com`      |
+
+确认后设置：
+
+```bash
+BASE="<根据 addr 确定的 URL>"
+AUTH="Authorization: Lab <token>"
+```
+
+**两项全部就绪后才可发起 API 请求。**
+
+## Session State
+
+在整个对话过程中，agent 需要记住以下状态，避免重复询问用户：
+
+- `lab_uuid` — 实验室 UUID（首次通过 API #1 自动获取，**不需要问用户**）
+- `device_name` — `host_node`
+
+## 请求约定
+
+所有请求使用 `curl -s`，POST/PATCH/DELETE 需加 `Content-Type: application/json`。
+
+> **Windows 平台**必须使用 `curl.exe`（而非 PowerShell 的 `curl` 别名）。
+
+---
+
+## API Endpoints
+
+### 1. 获取实验室信息（自动获取 lab_uuid）
+
+```bash
+curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH"
+```
+
+返回 `data.uuid` 为 `lab_uuid`，`data.name` 为 `lab_name`。
+
+### 2. 创建工作流
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/owner" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"name":"<名称>","lab_uuid":"<lab_uuid>","description":"<描述>"}'
+```
+
+返回 `data.uuid` 为 `workflow_uuid`。创建成功后告知用户链接：`$BASE/laboratory/$lab_uuid/workflow/$workflow_uuid`
+
+### 3. 创建节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/edge/workflow/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"workflow_uuid":"<workflow_uuid>","resource_template_name":"host_node","node_template_name":"<action_name>"}'
+```
+
+- `resource_template_name` 固定为 `host_node`
+- `node_template_name` — action 名称（如 `create_resource`, `test_latency`）
+
+### 4. 删除节点
+
+```bash
+curl -s -X DELETE "$BASE/api/v1/lab/workflow/nodes" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuids":["<uuid1>"],"workflow_uuid":"<workflow_uuid>"}'
+```
+
+### 5. 更新节点参数
+
+```bash
+curl -s -X PATCH "$BASE/api/v1/lab/workflow/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"workflow_uuid":"<wf_uuid>","uuid":"<node_uuid>","param":{...}}'
+```
+
+`param` 直接使用创建节点返回的 `data.param` 结构，修改需要填入的字段值。参考 [action-index.md](action-index.md) 确定哪些字段是 Slot。
+
+### 6. 查询节点 handles
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/node-handles" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuids":["<node_uuid_1>","<node_uuid_2>"]}'
+```
+
+### 7. 批量创建边
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/edges" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"edges":[{"source_node_uuid":"<uuid>","target_node_uuid":"<uuid>","source_handle_uuid":"<uuid>","target_handle_uuid":"<uuid>"}]}'
+```
+
+### 8. 启动工作流
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/<workflow_uuid>/run" -H "$AUTH"
+```
+
+### 9. 运行设备单动作
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/mcp/run/action" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"lab_uuid":"<lab_uuid>","device_id":"host_node","action":"<action_name>","action_type":"<type>","param":{...}}'
+```
+
+`param` 直接放 goal 里的属性，**不要**再包一层 `{"goal": {...}}`。
+
+> **WARNING: `action_type` 必须正确，传错会导致任务永远卡住无法完成。** 从下表或 `actions/<name>.json` 的 `type` 字段获取。
+
+#### action_type 速查表
+
+| action | action_type |
+|--------|-------------|
+| `test_latency` | `UniLabJsonCommand` |
+| `create_resource` | `ResourceCreateFromOuterEasy` |
+| `auto-test_resource` | `UniLabJsonCommand` |
+| `manual_confirm` | `UniLabJsonCommand` |
+
+### 10. 查询任务状态
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/mcp/task/<task_uuid>" -H "$AUTH"
+```
+
+### 11. 运行工作流单节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/mcp/run/workflow/action" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuid":"<node_uuid>"}'
+```
+
+### 12. 获取资源树（物料信息）
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/material/download/$lab_uuid" -H "$AUTH"
+```
+
+注意 `lab_uuid` 在路径中。返回 `data.nodes[]` 含所有节点（设备 + 物料），每个节点含 `name`、`uuid`、`type`、`parent`。
+
+### 13. 获取工作流模板详情
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/workflow/template/detail/$workflow_uuid" -H "$AUTH"
+```
+
+> 必须使用 `/lab/workflow/template/detail/{uuid}`，其他路径会返回 404。
+
+### 14. 按名称查询物料模板
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/material/template/by-name?lab_uuid=$lab_uuid&name=<template_name>" -H "$AUTH"
+```
+
+返回 `data.uuid` 为 `res_template_uuid`，用于 API #15。
+
+### 15. 创建物料节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/edge/material/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"res_template_uuid":"<uuid>","name":"<名称>","display_name":"<显示名>","parent_uuid":"<父节点uuid>","data":{...}}'
+```
+
+### 16. 更新物料节点
+
+```bash
+curl -s -X PUT "$BASE/api/v1/edge/material/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"uuid":"<节点uuid>","display_name":"<新名称>","data":{...}}'
+```
+
+---
+
+## Placeholder Slot 填写规则
+
+| `placeholder_keys` 值 | Slot 类型    | 填写格式                                              | 选取范围               |
+| --------------------- | ------------ | ----------------------------------------------------- | ---------------------- |
+| `unilabos_resources`  | ResourceSlot | `{"id": "/path/name", "name": "name", "uuid": "xxx"}` | 仅物料节点（非设备）   |
+| `unilabos_devices`    | DeviceSlot   | `"/parent/device_name"`                               | 仅设备节点（type=device） |
+| `unilabos_nodes`      | NodeSlot     | `"/parent/node_name"`                                 | 所有节点（设备 + 物料）   |
+| `unilabos_class`      | ClassSlot    | `"class_name"`                                        | 注册表中已注册的资源类    |
+
+### host_node 设备的 Slot 字段表
+
+| Action            | 字段        | Slot 类型    | 说明                           |
+| ----------------- | ----------- | ------------ | ------------------------------ |
+| `create_resource` | `res_id`    | ResourceSlot | 新资源路径（可填不存在的路径） |
+| `create_resource` | `device_id` | DeviceSlot   | 归属设备                       |
+| `create_resource` | `parent`    | NodeSlot     | 父节点路径                     |
+| `create_resource` | `class_name`| ClassSlot    | 资源类名如 `"container"`       |
+| `auto-test_resource` | `resource`  | ResourceSlot | 单个测试物料                |
+| `auto-test_resource` | `resources` | ResourceSlot | 测试物料数组                |
+| `auto-test_resource` | `device`    | DeviceSlot   | 测试设备                    |
+| `auto-test_resource` | `devices`   | DeviceSlot   | 测试设备                    |
+
+---
+
+## 渐进加载策略
+
+1. **SKILL.md**（本文件）— API 端点 + session state 管理
+2. **[action-index.md](action-index.md)** — 按分类浏览 4 个动作的描述和核心参数
+3. **[actions/\<name\>.json](actions/)** — 仅在需要构建具体请求时，加载对应 action 的完整 JSON Schema
+
+---
+
+## 完整工作流 Checklist
+
+```
+Task Progress:
+- [ ] Step 1: GET /edge/lab/info 获取 lab_uuid
+- [ ] Step 2: 获取资源树 (GET #12) → 记住可用物料
+- [ ] Step 3: 读 action-index.md 确定要用的 action 名
+- [ ] Step 4: 创建工作流 (POST #2) → 记住 workflow_uuid，告知用户链接
+- [ ] Step 5: 创建节点 (POST #3, resource_template_name=host_node) → 记住 node_uuid + data.param
+- [ ] Step 6: 根据 _unilabos_placeholder_info 和资源树，填写 data.param 中的 Slot 字段
+- [ ] Step 7: 更新节点参数 (PATCH #5)
+- [ ] Step 8: 查询节点 handles (POST #6) → 获取各节点的 handle_uuid
+- [ ] Step 9: 批量创建边 (POST #7) → 用 handle_uuid 连接节点
+- [ ] Step 10: 启动工作流 (POST #8) 或运行单节点 (POST #11)
+- [ ] Step 11: 查询任务状态 (GET #10) 确认完成
+```

.cursor/skills/host-node/action-index.md

@@ -0,0 +1,58 @@
+# Action Index — host_node
+
+4 个动作，按功能分类。每个动作的完整 JSON Schema 在 `actions/<name>.json`。
+
+---
+
+## 资源管理
+
+### `create_resource`
+
+在资源树中创建新资源（容器、物料等），支持指定位置、类型和初始液体
+
+- **action_type**: `ResourceCreateFromOuterEasy`
+- **Schema**: [`actions/create_resource.json`](actions/create_resource.json)
+- **可选参数**: `res_id`, `device_id`, `class_name`, `parent`, `bind_locations`, `liquid_input_slot`, `liquid_type`, `liquid_volume`, `slot_on_deck`
+- **占位符字段**:
+  - `res_id` — **ResourceSlot**（特例：目标物料可能尚不存在，直接填期望路径）
+  - `device_id` — **DeviceSlot**，填路径字符串如 `"/host_node"`
+  - `parent` — **NodeSlot**，填路径字符串如 `"/workstation/deck"`
+  - `class_name` — **ClassSlot**，填类名如 `"container"`
+
+### `auto-test_resource`
+
+测试资源系统，返回当前资源树和设备列表
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/test_resource.json`](actions/test_resource.json)
+- **可选参数**: `resource`, `resources`, `device`, `devices`
+- **占位符字段**:
+  - `resource` — **ResourceSlot**，单个物料节点 `{id, name, uuid}`
+  - `resources` — **ResourceSlot**，物料节点数组 `[{id, name, uuid}, ...]`
+  - `device` — **DeviceSlot**，设备路径字符串
+  - `devices` — **DeviceSlot**，设备路径字符串
+
+---
+
+## 系统工具
+
+### `test_latency`
+
+测试设备通信延迟，返回 RTT、时间差、任务延迟等指标
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/test_latency.json`](actions/test_latency.json)
+- **参数**: 无（零参数调用）
+
+---
+
+## 人工确认
+
+### `manual_confirm`
+
+创建人工确认节点，等待用户手动确认后继续
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/manual_confirm.json`](actions/manual_confirm.json)
+- **核心参数**: `timeout_seconds`（超时时间，秒）, `assignee_user_ids`（指派用户 ID 列表）
+- **占位符字段**: `assignee_user_ids` — `unilabos_manual_confirm` 类型

.cursor/skills/host-node/actions/create_resource.json

@@ -0,0 +1,93 @@
+{
+  "type": "ResourceCreateFromOuterEasy",
+  "goal": {
+    "res_id": "res_id",
+    "class_name": "class_name",
+    "parent": "parent",
+    "device_id": "device_id",
+    "bind_locations": "bind_locations",
+    "liquid_input_slot": "liquid_input_slot[]",
+    "liquid_type": "liquid_type[]",
+    "liquid_volume": "liquid_volume[]",
+    "slot_on_deck": "slot_on_deck"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "res_id": {
+        "type": "string"
+      },
+      "device_id": {
+        "type": "string"
+      },
+      "class_name": {
+        "type": "string"
+      },
+      "parent": {
+        "type": "string"
+      },
+      "bind_locations": {
+        "type": "object",
+        "properties": {
+          "x": {
+            "type": "number",
+            "minimum": -1.7976931348623157e+308,
+            "maximum": 1.7976931348623157e+308
+          },
+          "y": {
+            "type": "number",
+            "minimum": -1.7976931348623157e+308,
+            "maximum": 1.7976931348623157e+308
+          },
+          "z": {
+            "type": "number",
+            "minimum": -1.7976931348623157e+308,
+            "maximum": 1.7976931348623157e+308
+          }
+        },
+        "required": [
+          "x",
+          "y",
+          "z"
+        ],
+        "title": "bind_locations",
+        "additionalProperties": false
+      },
+      "liquid_input_slot": {
+        "type": "array",
+        "items": {
+          "type": "integer"
+        }
+      },
+      "liquid_type": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "liquid_volume": {
+        "type": "array",
+        "items": {
+          "type": "number"
+        }
+      },
+      "slot_on_deck": {
+        "type": "string"
+      }
+    },
+    "required": [],
+    "_unilabos_placeholder_info": {
+      "res_id": "unilabos_resources",
+      "device_id": "unilabos_devices",
+      "parent": "unilabos_nodes",
+      "class_name": "unilabos_class"
+    }
+  },
+  "goal_default": {},
+  "placeholder_keys": {
+    "res_id": "unilabos_resources",
+    "device_id": "unilabos_devices",
+    "parent": "unilabos_nodes",
+    "class_name": "unilabos_class"
+  }
+}

.cursor/skills/host-node/actions/manual_confirm.json

@@ -0,0 +1,32 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "timeout_seconds": "timeout_seconds",
+    "assignee_user_ids": "assignee_user_ids"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "timeout_seconds": {
+        "type": "integer"
+      },
+      "assignee_user_ids": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "required": [
+      "timeout_seconds",
+      "assignee_user_ids"
+    ],
+    "_unilabos_placeholder_info": {
+      "assignee_user_ids": "unilabos_manual_confirm"
+    }
+  },
+  "goal_default": {},
+  "placeholder_keys": {
+    "assignee_user_ids": "unilabos_manual_confirm"
+  }
+}

.cursor/skills/host-node/actions/test_latency.json

@@ -0,0 +1,11 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {},
+  "schema": {
+    "type": "object",
+    "properties": {},
+    "required": []
+  },
+  "goal_default": {},
+  "placeholder_keys": {}
+}

.cursor/skills/host-node/actions/test_resource.json

@@ -0,0 +1,255 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "resource": "resource",
+    "resources": "resources",
+    "device": "device",
+    "devices": "devices"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "resource": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "sample_id": {
+            "type": "string"
+          },
+          "children": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "parent": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string"
+          },
+          "pose": {
+            "type": "object",
+            "properties": {
+              "position": {
+                "type": "object",
+                "properties": {
+                  "x": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  },
+                  "y": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  },
+                  "z": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  }
+                },
+                "required": [
+                  "x",
+                  "y",
+                  "z"
+                ],
+                "title": "position",
+                "additionalProperties": false
+              },
+              "orientation": {
+                "type": "object",
+                "properties": {
+                  "x": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  },
+                  "y": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  },
+                  "z": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  },
+                  "w": {
+                    "type": "number",
+                    "minimum": -1.7976931348623157e+308,
+                    "maximum": 1.7976931348623157e+308
+                  }
+                },
+                "required": [
+                  "x",
+                  "y",
+                  "z",
+                  "w"
+                ],
+                "title": "orientation",
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "position",
+              "orientation"
+            ],
+            "title": "pose",
+            "additionalProperties": false
+          },
+          "config": {
+            "type": "string"
+          },
+          "data": {
+            "type": "string"
+          }
+        },
+        "title": "resource"
+      },
+      "resources": {
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sample_id": {
+              "type": "string"
+            },
+            "children": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "parent": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "pose": {
+              "type": "object",
+              "properties": {
+                "position": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z"
+                  ],
+                  "title": "position",
+                  "additionalProperties": false
+                },
+                "orientation": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "w": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z",
+                    "w"
+                  ],
+                  "title": "orientation",
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "position",
+                "orientation"
+              ],
+              "title": "pose",
+              "additionalProperties": false
+            },
+            "config": {
+              "type": "string"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "title": "resources"
+        },
+        "type": "array"
+      },
+      "device": {
+        "type": "string",
+        "description": "device reference"
+      },
+      "devices": {
+        "type": "string",
+        "description": "device reference"
+      }
+    },
+    "required": [],
+    "_unilabos_placeholder_info": {
+      "resource": "unilabos_resources",
+      "resources": "unilabos_resources",
+      "device": "unilabos_devices",
+      "devices": "unilabos_devices"
+    }
+  },
+  "goal_default": {},
+  "placeholder_keys": {
+    "resource": "unilabos_resources",
+    "resources": "unilabos_resources",
+    "device": "unilabos_devices",
+    "devices": "unilabos_devices"
+  }
+}

.cursor/skills/virtual-workbench/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: virtual-workbench
+description: Operate Virtual Workbench via REST API — prepare materials, move to heating stations, start heating, move to output, transfer resources. Use when the user mentions virtual workbench, virtual_workbench, 虚拟工作台, heating stations, material processing, or workbench operations.
+---
+
+# Virtual Workbench API Skill
+
+## 设备信息
+
+- **device_id**: `virtual_workbench`
+- **Python 源码**: `unilabos/devices/virtual/workbench.py`
+- **设备类**: `VirtualWorkbench`
+- **动作数**: 6（`auto-prepare_materials`, `auto-move_to_heating_station`, `auto-start_heating`, `auto-move_to_output`, `transfer`, `manual_confirm`）
+- **设备描述**: 模拟工作台，包含 1 个机械臂（每次操作 2s，独占锁）和 3 个加热台（每次加热 60s，可并行）
+
+### 典型工作流程
+
+1. `prepare_materials` — 生成 A1-A5 物料（5 个 output handle）
+2. `move_to_heating_station` — 物料并发竞争机械臂，移动到空闲加热台
+3. `start_heating` — 启动加热（3 个加热台可并行）
+4. `move_to_output` — 加热完成后移到输出位置 Cn
+
+## 前置条件（缺一不可）
+
+使用本 skill 前，**必须**先确认以下信息。如果缺少任何一项，**立即向用户询问并终止**，等补齐后再继续。
+
+### 1. ak / sk → AUTH
+
+从启动参数 `--ak` `--sk` 或 config.py 中获取，生成 token：`base64(ak:sk)` → `Authorization: Lab <token>`
+
+### 2. --addr → BASE URL
+
+| `--addr` 值  | BASE                                |
+| ------------ | ----------------------------------- |
+| `test`       | `https://leap-lab.test.bohrium.com` |
+| `uat`        | `https://leap-lab.uat.bohrium.com`  |
+| `local`      | `http://127.0.0.1:48197`            |
+| 不传（默认） | `https://leap-lab.bohrium.com`      |
+
+确认后设置：
+
+```bash
+BASE="<根据 addr 确定的 URL>"
+AUTH="Authorization: Lab <token>"
+```
+
+**两项全部就绪后才可发起 API 请求。**
+
+## Session State
+
+- `lab_uuid` — 实验室 UUID（首次通过 API #1 自动获取，**不需要问用户**）
+- `device_name` — `virtual_workbench`
+
+## 请求约定
+
+所有请求使用 `curl -s`，POST/PATCH/DELETE 需加 `Content-Type: application/json`。
+
+> **Windows 平台**必须使用 `curl.exe`（而非 PowerShell 的 `curl` 别名）。
+
+---
+
+## API Endpoints
+
+### 1. 获取实验室信息（自动获取 lab_uuid）
+
+```bash
+curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH"
+```
+
+返回 `data.uuid` 为 `lab_uuid`，`data.name` 为 `lab_name`。
+
+### 2. 创建工作流
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/owner" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"name":"<名称>","lab_uuid":"<lab_uuid>","description":"<描述>"}'
+```
+
+返回 `data.uuid` 为 `workflow_uuid`。创建成功后告知用户链接：`$BASE/laboratory/$lab_uuid/workflow/$workflow_uuid`
+
+### 3. 创建节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/edge/workflow/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"workflow_uuid":"<workflow_uuid>","resource_template_name":"virtual_workbench","node_template_name":"<action_name>"}'
+```
+
+- `resource_template_name` 固定为 `virtual_workbench`
+- `node_template_name` — action 名称（如 `auto-prepare_materials`, `auto-move_to_heating_station`）
+
+### 4. 删除节点
+
+```bash
+curl -s -X DELETE "$BASE/api/v1/lab/workflow/nodes" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuids":["<uuid1>"],"workflow_uuid":"<workflow_uuid>"}'
+```
+
+### 5. 更新节点参数
+
+```bash
+curl -s -X PATCH "$BASE/api/v1/lab/workflow/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"workflow_uuid":"<wf_uuid>","uuid":"<node_uuid>","param":{...}}'
+```
+
+参考 [action-index.md](action-index.md) 确定哪些字段是 Slot。
+
+### 6. 查询节点 handles
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/node-handles" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuids":["<node_uuid_1>","<node_uuid_2>"]}'
+```
+
+### 7. 批量创建边
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/edges" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"edges":[{"source_node_uuid":"<uuid>","target_node_uuid":"<uuid>","source_handle_uuid":"<uuid>","target_handle_uuid":"<uuid>"}]}'
+```
+
+### 8. 启动工作流
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/workflow/<workflow_uuid>/run" -H "$AUTH"
+```
+
+### 9. 运行设备单动作
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/mcp/run/action" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"lab_uuid":"<lab_uuid>","device_id":"virtual_workbench","action":"<action_name>","action_type":"<type>","param":{...}}'
+```
+
+`param` 直接放 goal 里的属性，**不要**再包一层 `{"goal": {...}}`。
+
+> **WARNING: `action_type` 必须正确，传错会导致任务永远卡住无法完成。** 从下表或 `actions/<name>.json` 的 `type` 字段获取。
+
+#### action_type 速查表
+
+| action | action_type |
+|--------|-------------|
+| `auto-prepare_materials` | `UniLabJsonCommand` |
+| `auto-move_to_heating_station` | `UniLabJsonCommand` |
+| `auto-start_heating` | `UniLabJsonCommand` |
+| `auto-move_to_output` | `UniLabJsonCommand` |
+| `transfer` | `UniLabJsonCommandAsync` |
+| `manual_confirm` | `UniLabJsonCommand` |
+
+### 10. 查询任务状态
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/mcp/task/<task_uuid>" -H "$AUTH"
+```
+
+### 11. 运行工作流单节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/lab/mcp/run/workflow/action" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"node_uuid":"<node_uuid>"}'
+```
+
+### 12. 获取资源树（物料信息）
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/material/download/$lab_uuid" -H "$AUTH"
+```
+
+注意 `lab_uuid` 在路径中。返回 `data.nodes[]` 含所有节点（设备 + 物料），每个节点含 `name`、`uuid`、`type`、`parent`。
+
+### 13. 获取工作流模板详情
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/workflow/template/detail/$workflow_uuid" -H "$AUTH"
+```
+
+> 必须使用 `/lab/workflow/template/detail/{uuid}`，其他路径会返回 404。
+
+### 14. 按名称查询物料模板
+
+```bash
+curl -s -X GET "$BASE/api/v1/lab/material/template/by-name?lab_uuid=$lab_uuid&name=<template_name>" -H "$AUTH"
+```
+
+返回 `data.uuid` 为 `res_template_uuid`，用于 API #15。
+
+### 15. 创建物料节点
+
+```bash
+curl -s -X POST "$BASE/api/v1/edge/material/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"res_template_uuid":"<uuid>","name":"<名称>","display_name":"<显示名>","parent_uuid":"<父节点uuid>","data":{...}}'
+```
+
+### 16. 更新物料节点
+
+```bash
+curl -s -X PUT "$BASE/api/v1/edge/material/node" \
+  -H "$AUTH" -H "Content-Type: application/json" \
+  -d '{"uuid":"<节点uuid>","display_name":"<新名称>","data":{...}}'
+```
+
+---
+
+## Placeholder Slot 填写规则
+
+| `placeholder_keys` 值 | Slot 类型    | 填写格式                                              | 选取范围               |
+| --------------------- | ------------ | ----------------------------------------------------- | ---------------------- |
+| `unilabos_resources`  | ResourceSlot | `{"id": "/path/name", "name": "name", "uuid": "xxx"}` | 仅物料节点（非设备）   |
+| `unilabos_devices`    | DeviceSlot   | `"/parent/device_name"`                               | 仅设备节点（type=device） |
+| `unilabos_nodes`      | NodeSlot     | `"/parent/node_name"`                                 | 所有节点（设备 + 物料）   |
+| `unilabos_class`      | ClassSlot    | `"class_name"`                                        | 注册表中已注册的资源类    |
+
+### virtual_workbench 设备的 Slot 字段表
+
+| Action            | 字段             | Slot 类型    | 说明                 |
+| ----------------- | ---------------- | ------------ | -------------------- |
+| `transfer`        | `resource`       | ResourceSlot | 待转移物料数组       |
+| `transfer`        | `target_device`  | DeviceSlot   | 目标设备路径         |
+| `transfer`        | `mount_resource` | ResourceSlot | 目标孔位数组         |
+| `manual_confirm`  | `resource`       | ResourceSlot | 确认用物料数组       |
+| `manual_confirm`  | `target_device`  | DeviceSlot   | 确认用目标设备       |
+| `manual_confirm`  | `mount_resource` | ResourceSlot | 确认用目标孔位数组   |
+
+> `prepare_materials`、`move_to_heating_station`、`start_heating`、`move_to_output` 这 4 个动作**无 Slot 字段**，参数为纯数值/整数。
+
+---
+
+## 渐进加载策略
+
+1. **SKILL.md**（本文件）— API 端点 + session state 管理 + 设备工作流概览
+2. **[action-index.md](action-index.md)** — 按分类浏览 6 个动作的描述和核心参数
+3. **[actions/\<name\>.json](actions/)** — 仅在需要构建具体请求时，加载对应 action 的完整 JSON Schema
+
+---
+
+## 完整工作流 Checklist
+
+```
+Task Progress:
+- [ ] Step 1: GET /edge/lab/info 获取 lab_uuid
+- [ ] Step 2: 获取资源树 (GET #12) → 记住可用物料
+- [ ] Step 3: 读 action-index.md 确定要用的 action 名
+- [ ] Step 4: 创建工作流 (POST #2) → 记住 workflow_uuid，告知用户链接
+- [ ] Step 5: 创建节点 (POST #3, resource_template_name=virtual_workbench) → 记住 node_uuid + data.param
+- [ ] Step 6: 根据 _unilabos_placeholder_info 和资源树，填写 data.param 中的 Slot 字段
+- [ ] Step 7: 更新节点参数 (PATCH #5)
+- [ ] Step 8: 查询节点 handles (POST #6) → 获取各节点的 handle_uuid
+- [ ] Step 9: 批量创建边 (POST #7) → 用 handle_uuid 连接节点
+- [ ] Step 10: 启动工作流 (POST #8) 或运行单节点 (POST #11)
+- [ ] Step 11: 查询任务状态 (GET #10) 确认完成
+```
+
+### 典型 5 物料并发加热工作流示例
+
+```
+prepare_materials (count=5)
+  ├─ channel_1 → move_to_heating_station (material_number=1) → start_heating → move_to_output
+  ├─ channel_2 → move_to_heating_station (material_number=2) → start_heating → move_to_output
+  ├─ channel_3 → move_to_heating_station (material_number=3) → start_heating → move_to_output
+  ├─ channel_4 → move_to_heating_station (material_number=4) → start_heating → move_to_output
+  └─ channel_5 → move_to_heating_station (material_number=5) → start_heating → move_to_output
+```
+
+创建节点时，`prepare_materials` 的 5 个 output handle（`channel_1` ~ `channel_5`）分别连接到 5 个 `move_to_heating_station` 节点的 `material_input` handle。每个 `move_to_heating_station` 的 `heating_station_output` 和 `material_number_output` 连接到对应 `start_heating` 的 `station_id_input` 和 `material_number_input`。

.cursor/skills/virtual-workbench/action-index.md

@@ -0,0 +1,76 @@
+# Action Index — virtual_workbench
+
+6 个动作，按功能分类。每个动作的完整 JSON Schema 在 `actions/<name>.json`。
+
+---
+
+## 物料准备
+
+### `auto-prepare_materials`
+
+批量准备物料（虚拟起始节点），生成 A1-A5 物料编号，输出 5 个 handle 供后续节点使用
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/prepare_materials.json`](actions/prepare_materials.json)
+- **可选参数**: `count`（物料数量，默认 5）
+
+---
+
+## 机械臂 & 加热台操作
+
+### `auto-move_to_heating_station`
+
+将物料从 An 位置移动到空闲加热台（竞争机械臂，自动查找空闲加热台）
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/move_to_heating_station.json`](actions/move_to_heating_station.json)
+- **核心参数**: `material_number`（物料编号，integer）
+
+### `auto-start_heating`
+
+启动指定加热台的加热程序（可并行，3 个加热台同时工作）
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/start_heating.json`](actions/start_heating.json)
+- **核心参数**: `station_id`（加热台 ID），`material_number`（物料编号）
+
+### `auto-move_to_output`
+
+将加热完成的物料从加热台移动到输出位置 Cn
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/move_to_output.json`](actions/move_to_output.json)
+- **核心参数**: `station_id`（加热台 ID），`material_number`（物料编号）
+
+---
+
+## 物料转移
+
+### `transfer`
+
+异步转移物料到目标设备（通过 ROS 资源转移）
+
+- **action_type**: `UniLabJsonCommandAsync`
+- **Schema**: [`actions/transfer.json`](actions/transfer.json)
+- **核心参数**: `resource`, `target_device`, `mount_resource`
+- **占位符字段**:
+  - `resource` — **ResourceSlot**，待转移的物料数组 `[{id, name, uuid}, ...]`
+  - `target_device` — **DeviceSlot**，目标设备路径字符串
+  - `mount_resource` — **ResourceSlot**，目标孔位数组 `[{id, name, uuid}, ...]`
+
+---
+
+## 人工确认
+
+### `manual_confirm`
+
+创建人工确认节点，等待用户手动确认后继续（含物料转移上下文）
+
+- **action_type**: `UniLabJsonCommand`
+- **Schema**: [`actions/manual_confirm.json`](actions/manual_confirm.json)
+- **核心参数**: `resource`, `target_device`, `mount_resource`, `timeout_seconds`, `assignee_user_ids`
+- **占位符字段**:
+  - `resource` — **ResourceSlot**，物料数组
+  - `target_device` — **DeviceSlot**，目标设备路径
+  - `mount_resource` — **ResourceSlot**，目标孔位数组
+  - `assignee_user_ids` — `unilabos_manual_confirm` 类型

.cursor/skills/virtual-workbench/actions/manual_confirm.json

@@ -0,0 +1,270 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "resource": "resource",
+    "target_device": "target_device",
+    "mount_resource": "mount_resource",
+    "timeout_seconds": "timeout_seconds",
+    "assignee_user_ids": "assignee_user_ids"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "resource": {
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sample_id": {
+              "type": "string"
+            },
+            "children": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "parent": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "pose": {
+              "type": "object",
+              "properties": {
+                "position": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z"
+                  ],
+                  "title": "position",
+                  "additionalProperties": false
+                },
+                "orientation": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "w": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z",
+                    "w"
+                  ],
+                  "title": "orientation",
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "position",
+                "orientation"
+              ],
+              "title": "pose",
+              "additionalProperties": false
+            },
+            "config": {
+              "type": "string"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "title": "resource"
+        },
+        "type": "array"
+      },
+      "target_device": {
+        "type": "string",
+        "description": "device reference"
+      },
+      "mount_resource": {
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sample_id": {
+              "type": "string"
+            },
+            "children": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "parent": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "pose": {
+              "type": "object",
+              "properties": {
+                "position": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z"
+                  ],
+                  "title": "position",
+                  "additionalProperties": false
+                },
+                "orientation": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "w": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z",
+                    "w"
+                  ],
+                  "title": "orientation",
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "position",
+                "orientation"
+              ],
+              "title": "pose",
+              "additionalProperties": false
+            },
+            "config": {
+              "type": "string"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "title": "mount_resource"
+        },
+        "type": "array"
+      },
+      "timeout_seconds": {
+        "type": "integer"
+      },
+      "assignee_user_ids": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "required": [
+      "resource",
+      "target_device",
+      "mount_resource",
+      "timeout_seconds",
+      "assignee_user_ids"
+    ],
+    "_unilabos_placeholder_info": {
+      "resource": "unilabos_resources",
+      "target_device": "unilabos_devices",
+      "mount_resource": "unilabos_resources",
+      "assignee_user_ids": "unilabos_manual_confirm"
+    }
+  },
+  "goal_default": {},
+  "placeholder_keys": {
+    "resource": "unilabos_resources",
+    "target_device": "unilabos_devices",
+    "mount_resource": "unilabos_resources",
+    "assignee_user_ids": "unilabos_manual_confirm"
+  }
+}

.cursor/skills/virtual-workbench/actions/move_to_heating_station.json

@@ -0,0 +1,19 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "material_number": "material_number"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "material_number": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "material_number"
+    ]
+  },
+  "goal_default": {},
+  "placeholder_keys": {}
+}

.cursor/skills/virtual-workbench/actions/move_to_output.json

@@ -0,0 +1,24 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "station_id": "station_id",
+    "material_number": "material_number"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "station_id": {
+        "type": "integer"
+      },
+      "material_number": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "station_id",
+      "material_number"
+    ]
+  },
+  "goal_default": {},
+  "placeholder_keys": {}
+}

.cursor/skills/virtual-workbench/actions/prepare_materials.json

@@ -0,0 +1,20 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "count": "count"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "count": {
+        "type": "integer",
+        "default": 5
+      }
+    },
+    "required": []
+  },
+  "goal_default": {
+    "count": 5
+  },
+  "placeholder_keys": {}
+}

.cursor/skills/virtual-workbench/actions/start_heating.json

@@ -0,0 +1,24 @@
+{
+  "type": "UniLabJsonCommand",
+  "goal": {
+    "station_id": "station_id",
+    "material_number": "material_number"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "station_id": {
+        "type": "integer"
+      },
+      "material_number": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "station_id",
+      "material_number"
+    ]
+  },
+  "goal_default": {},
+  "placeholder_keys": {}
+}

.cursor/skills/virtual-workbench/actions/transfer.json

@@ -0,0 +1,255 @@
+{
+  "type": "UniLabJsonCommandAsync",
+  "goal": {
+    "resource": "resource",
+    "target_device": "target_device",
+    "mount_resource": "mount_resource"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "resource": {
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sample_id": {
+              "type": "string"
+            },
+            "children": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "parent": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "pose": {
+              "type": "object",
+              "properties": {
+                "position": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z"
+                  ],
+                  "title": "position",
+                  "additionalProperties": false
+                },
+                "orientation": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "w": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z",
+                    "w"
+                  ],
+                  "title": "orientation",
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "position",
+                "orientation"
+              ],
+              "title": "pose",
+              "additionalProperties": false
+            },
+            "config": {
+              "type": "string"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "title": "resource"
+        },
+        "type": "array"
+      },
+      "target_device": {
+        "type": "string",
+        "description": "device reference"
+      },
+      "mount_resource": {
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sample_id": {
+              "type": "string"
+            },
+            "children": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "parent": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string"
+            },
+            "category": {
+              "type": "string"
+            },
+            "pose": {
+              "type": "object",
+              "properties": {
+                "position": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z"
+                  ],
+                  "title": "position",
+                  "additionalProperties": false
+                },
+                "orientation": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "y": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "z": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    },
+                    "w": {
+                      "type": "number",
+                      "minimum": -1.7976931348623157e+308,
+                      "maximum": 1.7976931348623157e+308
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "z",
+                    "w"
+                  ],
+                  "title": "orientation",
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "position",
+                "orientation"
+              ],
+              "title": "pose",
+              "additionalProperties": false
+            },
+            "config": {
+              "type": "string"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "title": "mount_resource"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "resource",
+      "target_device",
+      "mount_resource"
+    ],
+    "_unilabos_placeholder_info": {
+      "resource": "unilabos_resources",
+      "target_device": "unilabos_devices",
+      "mount_resource": "unilabos_resources"
+    }
+  },
+  "goal_default": {},
+  "placeholder_keys": {
+    "resource": "unilabos_resources",
+    "target_device": "unilabos_devices",
+    "mount_resource": "unilabos_resources"
+  }
+}

.cursorignore

@@ -1,26 +1,188 @@
-.conda
-# .github
-.idea
-# .vscode
-output
-pylabrobot_repo
-recipes
-scripts
-service
-temp
-# unilabos/test
-# unilabos/app/web
-unilabos/device_mesh
-unilabos_data
-unilabos_msgs
-unilabos.egg-info
-CONTRIBUTORS
-# LICENSE
-MANIFEST.in
+# ============================================================
+# Uni-Lab-OS Cursor Ignore 配置，控制 Cursor AI 的文件索引范围
+# ============================================================
+
+# ==================== 敏感配置文件 ====================
+# 本地配置（可能包含密钥）
+**/local_config.py
+test_config.py
+local_test*.py
+
+# 环境变量和密钥
+.env
+.env.*
+**/.certs/
+*.pem
+*.key
+credentials.json
+secrets.yaml
+
+# ==================== 二进制和 3D 模型文件 ====================
+# 3D 模型文件（无需索引）
+*.stl
+*.dae
+*.glb
+*.gltf
+*.obj
+*.fbx
+*.blend
+
+# URDF/Xacro 机器人描述文件（大型XML）
+*.xacro
+
+# 图片文件
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.webp
+*.ico
+*.svg
+*.bmp
+
+# 压缩包
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+*.bz2
+*.rar
+*.7z
+
+# ==================== Python 生成文件 ====================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.egg
+*.egg-info/
+.eggs/
+dist/
+build/
+*.manifest
+*.spec
+
+# ==================== IDE 和编辑器 ====================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.#*
+
+# ==================== 测试和覆盖率 ====================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# ==================== 虚拟环境 ====================
+.venv/
+venv/
+env/
+ENV/
+
+# ==================== ROS 2 生成文件 ====================
+# ROS 构建目录
+build/
+install/
+log/
+logs/
+devel/
+
+# ROS 消息生成
+msg_gen/
+srv_gen/
+msg/*Action.msg
+msg/*ActionFeedback.msg
+msg/*ActionGoal.msg
+msg/*ActionResult.msg
+msg/*Feedback.msg
+msg/*Goal.msg
+msg/*Result.msg
+msg/_*.py
+srv/_*.py
+build_isolated/
+devel_isolated/
+
+# ROS 动态配置
+*.cfgc
+/cfg/cpp/
+/cfg/*.py
+
+# ==================== 项目特定目录 ====================
+# 工作数据目录
+unilabos_data/
+
+# 临时和输出目录
+temp/
+output/
+cursor_docs/
+configs/
+
+# 文档构建
+docs/_build/
+/site
+
+# ==================== 大型数据文件 ====================
+# 点云数据
+*.pcd
+
+# GraphML 图形文件
+*.graphml
+
+# 日志文件
+*.log
+
+# 数据库
+*.sqlite3
+*.db
+
+# Jupyter 检查点
+.ipynb_checkpoints/
+
+# ==================== 设备网格资源 ====================
+# 3D 网格文件目录（包含大量 STL/DAE 文件）
+unilabos/device_mesh/devices/**/*.stl
+unilabos/device_mesh/devices/**/*.dae
+unilabos/device_mesh/resources/**/*.stl
+unilabos/device_mesh/resources/**/*.glb
+unilabos/device_mesh/resources/**/*.xacro
+
+# RViz 配置
+*.rviz
+
+# ==================== 系统文件 ====================
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ==================== 锁文件 ====================
+poetry.lock
+Pipfile.lock
+pdm.lock
+package-lock.json
+yarn.lock
+
+# ==================== 类型检查缓存 ====================
+.mypy_cache/
+.dmypy.json
+.pytype/
+.pyre/
 pyrightconfig.json
-# README.md
-# README_zh.md
-setup.py
-setup.cfg
-.gitattrubutes
-**/__pycache__
+
+# ==================== 其他 ====================
+# Catkin
+CATKIN_IGNORE
+
+# Eclipse/Qt
+.project
+.cproject
+CMakeLists.txt.user
+*.user
+qtcreator-*

.github/copilot-instructions.md

@@ -0,0 +1,11 @@
+## 设备接入
+
+当被要求添加设备驱动时，参考 `docs/ai_guides/add_device.md`。
+该指南包含完整的模板和已有设备接口参考。
+
+## 关键规则
+
+- 动作方法的参数名是接口契约，不可重命名
+- `status` 字符串必须与同类已有设备一致
+- `self.data` 必须在 `__init__` 中预填充所有属性字段
+- 异步方法中使用 `await self._ros_node.sleep()`，禁止 `time.sleep()`

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+# GitHub Actions
+- package-ecosystem: "github-actions"
+  directory: "/"
+  target-branch: "dev"
+  schedule:
+    interval: "weekly"
+    day: "monday"
+    time: "06:00"
+  open-pull-requests-limit: 5
+  reviewers:
+  - "msgcenterpy-team"
+  labels:
+  - "dependencies"
+  - "github-actions"
+  commit-message:
+    prefix: "ci"
+    include: "scope"

.github/workflows/ci-check.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Install ROS dependencies, uv and unilabos-msgs
         run: |
           echo Installing ROS dependencies...
-          mamba install -n check-env --override-channels -c robostack-staging -c conda-forge -c uni-lab conda-forge::uv conda-forge::opencv robostack-staging::ros-humble-ros-core robostack-staging::ros-humble-action-msgs robostack-staging::ros-humble-std-msgs robostack-staging::ros-humble-geometry-msgs robostack-staging::ros-humble-control-msgs robostack-staging::ros-humble-nav2-msgs uni-lab::ros-humble-unilabos-msgs robostack-staging::ros-humble-cv-bridge robostack-staging::ros-humble-vision-opencv robostack-staging::ros-humble-tf-transformations robostack-staging::ros-humble-moveit-msgs robostack-staging::ros-humble-tf2-ros robostack-staging::ros-humble-tf2-ros-py conda-forge::transforms3d -y
+          mamba install -n check-env conda-forge::uv conda-forge::opencv robostack-staging::ros-humble-ros-core robostack-staging::ros-humble-action-msgs robostack-staging::ros-humble-std-msgs robostack-staging::ros-humble-geometry-msgs robostack-staging::ros-humble-control-msgs robostack-staging::ros-humble-nav2-msgs uni-lab::ros-humble-unilabos-msgs robostack-staging::ros-humble-cv-bridge robostack-staging::ros-humble-vision-opencv robostack-staging::ros-humble-tf-transformations robostack-staging::ros-humble-moveit-msgs robostack-staging::ros-humble-tf2-ros robostack-staging::ros-humble-tf2-ros-py conda-forge::transforms3d -c robostack-staging -c conda-forge -c uni-lab -y
 
       - name: Install pip dependencies and unilabos
         run: |

.github/workflows/conda-pack-build.yml

@@ -1,10 +1,6 @@
 name: Build Conda-Pack Environment
 
 on:
-  # 在 UniLabOS Conda Build 成功上传后自动构建非全量 conda-pack
-  workflow_run:
-    workflows: ["UniLabOS Conda Build"]
-    types: [completed]
   workflow_dispatch:
     inputs:
       branch:
@@ -25,16 +21,6 @@ on:
 
 jobs:
   build-conda-pack:
-    if: |
-      github.event_name == 'workflow_dispatch' ||
-      (
-        github.event_name == 'workflow_run' &&
-        github.event.workflow_run.conclusion == 'success' &&
-        github.event.workflow_run.event == 'workflow_run'
-      )
-    env:
-      BUILD_FULL: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.build_full == 'true' }}
-      PACKAGE_REF: ${{ github.event.inputs.branch || github.event.workflow_run.head_sha || github.ref_name }}
     strategy:
       fail-fast: false
       matrix:
@@ -68,9 +54,7 @@ jobs:
         id: should_build
         shell: bash
         run: |
-          if [[ "${{ github.event_name }}" != "workflow_dispatch" ]]; then
-            echo "should_build=true" >> $GITHUB_OUTPUT
-          elif [[ -z "${{ github.event.inputs.platforms }}" ]]; then
+          if [[ -z "${{ github.event.inputs.platforms }}" ]]; then
             echo "should_build=true" >> $GITHUB_OUTPUT
           elif [[ "${{ github.event.inputs.platforms }}" == *"${{ matrix.platform }}"* ]]; then
             echo "should_build=true" >> $GITHUB_OUTPUT
@@ -81,7 +65,7 @@ jobs:
       - uses: actions/checkout@v6
         if: steps.should_build.outputs.should_build == 'true'
         with:
-          ref: ${{ github.event.inputs.branch || github.event.workflow_run.head_sha || github.ref }}
+          ref: ${{ github.event.inputs.branch }}
           fetch-depth: 0
 
       - name: Setup Miniforge (with mamba)
@@ -91,7 +75,7 @@ jobs:
           miniforge-version: latest
           use-mamba: true
           python-version: '3.11.14'
-          channels: conda-forge,robostack-staging,uni-lab
+          channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: flexible
           activate-environment: unilab
           auto-update-conda: false
@@ -102,13 +86,13 @@ jobs:
         run: |
           echo Installing unilabos and dependencies to unilab environment...
           echo Using mamba for faster and more reliable dependency resolution...
-          echo Build full: ${{ env.BUILD_FULL }}
-          if "${{ env.BUILD_FULL }}"=="true" (
+          echo Build full: ${{ github.event.inputs.build_full }}
+          if "${{ github.event.inputs.build_full }}"=="true" (
             echo Installing unilabos-full ^(complete package^)...
-            mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos-full conda-pack zstandard -y
+            mamba install -n unilab uni-lab::unilabos-full conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
           ) else (
             echo Installing unilabos ^(minimal package^)...
-            mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos conda-pack zstandard -y
+            mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
           )
 
       - name: Install conda-pack, unilabos and dependencies (Unix)
@@ -117,13 +101,13 @@ jobs:
         run: |
           echo "Installing unilabos and dependencies to unilab environment..."
           echo "Using mamba for faster and more reliable dependency resolution..."
-          echo "Build full: ${{ env.BUILD_FULL }}"
-          if [[ "${{ env.BUILD_FULL }}" == "true" ]]; then
+          echo "Build full: ${{ github.event.inputs.build_full }}"
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
             echo "Installing unilabos-full (complete package)..."
-            mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos-full conda-pack zstandard -y
+            mamba install -n unilab uni-lab::unilabos-full conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
           else
             echo "Installing unilabos (minimal package)..."
-            mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos conda-pack zstandard -y
+            mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
           fi
 
       - name: Get latest ros-humble-unilabos-msgs version (Windows)
@@ -150,27 +134,27 @@ jobs:
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform == 'win-64'
         run: |
           echo Checking for available ros-humble-unilabos-msgs versions...
-          mamba search --override-channels -c uni-lab -c robostack-staging -c conda-forge ros-humble-unilabos-msgs || echo Search completed
+          mamba search ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge || echo Search completed
           echo.
           echo Updating ros-humble-unilabos-msgs to latest version...
-          mamba update -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge ros-humble-unilabos-msgs -y || echo Already at latest version
+          mamba update -n unilab ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge -y || echo Already at latest version
 
       - name: Check for newer ros-humble-unilabos-msgs (Unix)
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform != 'win-64'
         shell: bash
         run: |
           echo "Checking for available ros-humble-unilabos-msgs versions..."
-          mamba search --override-channels -c uni-lab -c robostack-staging -c conda-forge ros-humble-unilabos-msgs || echo "Search completed"
+          mamba search ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge || echo "Search completed"
           echo ""
           echo "Updating ros-humble-unilabos-msgs to latest version..."
-          mamba update -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge ros-humble-unilabos-msgs -y || echo "Already at latest version"
+          mamba update -n unilab ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge -y || echo "Already at latest version"
 
       - name: Install latest unilabos from source (Windows)
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform == 'win-64'
         run: |
           echo Uninstalling existing unilabos...
           mamba run -n unilab pip uninstall unilabos -y || echo unilabos not installed via pip
-          echo Installing unilabos from source (ref: ${{ env.PACKAGE_REF }})...
+          echo Installing unilabos from source (branch: ${{ github.event.inputs.branch }})...
           mamba run -n unilab pip install .
           echo Verifying installation...
           mamba run -n unilab pip show unilabos
@@ -181,7 +165,7 @@ jobs:
         run: |
           echo "Uninstalling existing unilabos..."
           mamba run -n unilab pip uninstall unilabos -y || echo "unilabos not installed via pip"
-          echo "Installing unilabos from source (ref: ${{ env.PACKAGE_REF }})..."
+          echo "Installing unilabos from source (branch: ${{ github.event.inputs.branch }})..."
           mamba run -n unilab pip install .
           echo "Verifying installation..."
           mamba run -n unilab pip show unilabos
@@ -242,9 +226,7 @@ jobs:
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform == 'win-64'
         run: |
           echo Packing unilab environment with conda-pack...
-          for /f "delims=" %%i in ('mamba run -n unilab python -c "import os; print(os.environ['CONDA_PREFIX'])"') do set "UNILAB_PREFIX=%%i"
-          echo Packing environment at: %UNILAB_PREFIX%
-          mamba run -n unilab conda-pack -p "%UNILAB_PREFIX%" -o unilab-env-${{ matrix.platform }}.tar.gz --ignore-missing-files
+          mamba activate unilab && conda pack -n unilab -o unilab-env-${{ matrix.platform }}.tar.gz --ignore-missing-files
           echo Pack file created:
           dir unilab-env-${{ matrix.platform }}.tar.gz
 
@@ -253,9 +235,8 @@ jobs:
         shell: bash
         run: |
           echo "Packing unilab environment with conda-pack..."
-          UNILAB_PREFIX="$(mamba run -n unilab python -c 'import os; print(os.environ["CONDA_PREFIX"])')"
-          echo "Packing environment at: $UNILAB_PREFIX"
-          mamba run -n unilab conda-pack -p "$UNILAB_PREFIX" -o unilab-env-${{ matrix.platform }}.tar.gz --ignore-missing-files
+          mamba install conda-pack -c conda-forge -y
+          conda pack -n unilab -o unilab-env-${{ matrix.platform }}.tar.gz --ignore-missing-files
           echo "Pack file created:"
           ls -lh unilab-env-${{ matrix.platform }}.tar.gz
 
@@ -286,7 +267,7 @@ jobs:
 
           rem Create README using Python script
           echo Creating: README.txt
-          python scripts\create_readme.py ${{ matrix.platform }} ${{ env.PACKAGE_REF }} dist-package\README.txt
+          python scripts\create_readme.py ${{ matrix.platform }} ${{ github.event.inputs.branch }} dist-package\README.txt
 
           echo.
           echo Distribution package contents:
@@ -322,7 +303,7 @@ jobs:
 
           # Create README using Python script
           echo "Creating: README.txt"
-          python scripts/create_readme.py ${{ matrix.platform }} ${{ env.PACKAGE_REF }} dist-package/README.txt
+          python scripts/create_readme.py ${{ matrix.platform }} ${{ github.event.inputs.branch }} dist-package/README.txt
 
           echo ""
           echo "Distribution package contents:"
@@ -333,7 +314,7 @@ jobs:
         if: steps.should_build.outputs.should_build == 'true'
         uses: actions/upload-artifact@v6
         with:
-          name: unilab-pack-${{ matrix.platform }}-${{ env.PACKAGE_REF }}
+          name: unilab-pack-${{ matrix.platform }}-${{ github.event.inputs.branch }}
           path: dist-package/
           retention-days: 90
           if-no-files-found: error
@@ -345,9 +326,9 @@ jobs:
           echo Build Summary
           echo ==========================================
           echo Platform: ${{ matrix.platform }}
-          echo Branch: ${{ env.PACKAGE_REF }}
+          echo Branch: ${{ github.event.inputs.branch }}
           echo Python version: 3.11.14
-          if "${{ env.BUILD_FULL }}"=="true" (
+          if "${{ github.event.inputs.build_full }}"=="true" (
             echo Package: unilabos-full ^(complete^)
           ) else (
             echo Package: unilabos ^(minimal^)
@@ -356,7 +337,7 @@ jobs:
           echo Distribution package contents:
           dir dist-package
           echo.
-          echo Artifact name: unilab-pack-${{ matrix.platform }}-${{ env.PACKAGE_REF }}
+          echo Artifact name: unilab-pack-${{ matrix.platform }}-${{ github.event.inputs.branch }}
           echo.
           echo After download, extract the ZIP and run:
           echo   install_unilab.bat
@@ -370,9 +351,9 @@ jobs:
           echo "Build Summary"
           echo "=========================================="
           echo "Platform: ${{ matrix.platform }}"
-          echo "Branch: ${{ env.PACKAGE_REF }}"
+          echo "Branch: ${{ github.event.inputs.branch }}"
           echo "Python version: 3.11.14"
-          if [[ "${{ env.BUILD_FULL }}" == "true" ]]; then
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
             echo "Package: unilabos-full (complete)"
           else
             echo "Package: unilabos (minimal)"
@@ -381,7 +362,7 @@ jobs:
           echo "Distribution package contents:"
           ls -lh dist-package/
           echo ""
-          echo "Artifact name: unilab-pack-${{ matrix.platform }}-${{ env.PACKAGE_REF }}"
+          echo "Artifact name: unilab-pack-${{ matrix.platform }}-${{ github.event.inputs.branch }}"
           echo ""
           echo "After download:"
           echo "  install_unilab.sh"

.github/workflows/deploy-docs.yml

@@ -56,7 +56,7 @@ jobs:
           miniforge-version: latest
           use-mamba: true
           python-version: '3.11.14'
-          channels: conda-forge,robostack-staging,uni-lab
+          channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: flexible
           activate-environment: unilab
           auto-update-conda: false
@@ -66,7 +66,7 @@ jobs:
         run: |
           echo "Installing unilabos and dependencies to unilab environment..."
           echo "Using mamba for faster and more reliable dependency resolution..."
-          mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos -y
+          mamba install -n unilab uni-lab::unilabos -c uni-lab -c robostack-staging -c conda-forge -y
 
       - name: Install latest unilabos from source
         run: |

.github/workflows/multi-platform-build.yml

@@ -10,9 +10,6 @@ on:
   # 支持 tag 推送（不依赖 CI Check）
   push:
     tags: ['v*']
-  # GitHub Release 发布时自动构建并上传
-  release:
-    types: [published]
   # 手动触发
   workflow_dispatch:
     inputs:
@@ -83,7 +80,7 @@ jobs:
       - uses: actions/checkout@v6
         with:
           # 如果是 workflow_run 触发，使用触发 CI Check 的 commit
-          ref: ${{ github.event.workflow_run.head_sha || github.event.release.tag_name || github.ref }}
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 0
 
       - name: Check if platform should be built
@@ -99,13 +96,12 @@ jobs:
             echo "should_build=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Setup Miniforge
+      - name: Setup Miniconda
         if: steps.should_build.outputs.should_build == 'true'
         uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-version: latest
-          use-mamba: true
-          channels: conda-forge,robostack-staging
+          miniconda-version: 'latest'
+          channels: conda-forge,robostack-staging,defaults
           channel-priority: strict
           activate-environment: build-env
           auto-update-conda: false
@@ -114,7 +110,7 @@ jobs:
       - name: Install rattler-build and anaconda-client
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          mamba install --override-channels -c conda-forge rattler-build anaconda-client -y
+          conda install -c conda-forge rattler-build anaconda-client
 
       - name: Show environment info
         if: steps.should_build.outputs.should_build == 'true'
@@ -161,13 +157,7 @@ jobs:
           retention-days: 30
 
       - name: Upload to Anaconda.org (unilab organization)
-        if: |
-          steps.should_build.outputs.should_build == 'true' &&
-          (
-            github.event_name == 'release' ||
-            startsWith(github.ref, 'refs/tags/') ||
-            github.event.inputs.upload_to_anaconda == 'true'
-          )
+        if: steps.should_build.outputs.should_build == 'true' && github.event.inputs.upload_to_anaconda == 'true'
         run: |
           for package in $(find ./output -name "*.conda"); do
             echo "Uploading $package to unilab organization..."

.github/workflows/unilabos-conda-build.yml

@@ -1,10 +1,14 @@
 name: UniLabOS Conda Build
 
 on:
-  # 在 Multi-Platform Conda Build 成功上传 msgs 后自动触发
+  # 在 CI Check 成功后自动触发
   workflow_run:
-    workflows: ["Multi-Platform Conda Build"]
+    workflows: ["CI Check"]
     types: [completed]
+    branches: [main, dev]
+  # 标签推送时直接触发（发布版本）
+  push:
+    tags: ['v*']
   # 手动触发
   workflow_dispatch:
     inputs:
@@ -29,30 +33,30 @@ on:
         type: boolean
 
 jobs:
-  # 等待上游 msgs 构建完成的 job (仅用于 workflow_run 触发)
-  wait-for-upstream:
+  # 等待 CI Check 完成的 job (仅用于 workflow_run 触发)
+  wait-for-ci:
     runs-on: ubuntu-latest
     if: github.event_name == 'workflow_run'
     outputs:
       should_continue: ${{ steps.check.outputs.should_continue }}
     steps:
-      - name: Check upstream workflow status
+      - name: Check CI status
         id: check
         run: |
-          if [[ "${{ github.event.workflow_run.conclusion }}" == "success" && ( "${{ github.event.workflow_run.event }}" == "release" || "${{ github.event.workflow_run.event }}" == "push" ) ]]; then
+          if [[ "${{ github.event.workflow_run.conclusion }}" == "success" ]]; then
             echo "should_continue=true" >> $GITHUB_OUTPUT
-            echo "Multi-Platform Conda Build passed for release/tag, proceeding with UniLabOS build"
+            echo "CI Check passed, proceeding with build"
           else
             echo "should_continue=false" >> $GITHUB_OUTPUT
-            echo "Upstream workflow is not a successful release/tag build (status: ${{ github.event.workflow_run.conclusion }}, event: ${{ github.event.workflow_run.event }}), skipping build"
+            echo "CI Check did not succeed (status: ${{ github.event.workflow_run.conclusion }}), skipping build"
           fi
 
   build:
-    needs: [wait-for-upstream]
-    # 运行条件：workflow_run 触发且上游成功，或者手动触发
+    needs: [wait-for-ci]
+    # 运行条件：workflow_run 触发且 CI 成功，或者其他触发方式
     if: |
       always() &&
-      (needs.wait-for-upstream.result == 'skipped' || needs.wait-for-upstream.outputs.should_continue == 'true')
+      (needs.wait-for-ci.result == 'skipped' || needs.wait-for-ci.outputs.should_continue == 'true')
     strategy:
       fail-fast: false
       matrix:
@@ -75,7 +79,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          # 如果是 workflow_run 触发，使用上游 conda 包构建的 commit
+          # 如果是 workflow_run 触发，使用触发 CI Check 的 commit
           ref: ${{ github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 0
 
@@ -92,13 +96,12 @@ jobs:
             echo "should_build=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Setup Miniforge
+      - name: Setup Miniconda
         if: steps.should_build.outputs.should_build == 'true'
         uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-version: latest
-          use-mamba: true
-          channels: conda-forge,robostack-staging,uni-lab
+          miniconda-version: 'latest'
+          channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: strict
           activate-environment: build-env
           auto-update-conda: false
@@ -107,7 +110,7 @@ jobs:
       - name: Install rattler-build and anaconda-client
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          mamba install --override-channels -c conda-forge rattler-build anaconda-client -y
+          conda install -c conda-forge rattler-build anaconda-client
 
       - name: Show environment info
         if: steps.should_build.outputs.should_build == 'true'
@@ -116,11 +119,11 @@ jobs:
           conda list | grep -E "(rattler-build|anaconda-client)"
           echo "Platform: ${{ matrix.platform }}"
           echo "OS: ${{ matrix.os }}"
-          echo "Build full package: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.build_full == 'true' }}"
+          echo "Build full package: ${{ github.event.inputs.build_full || 'false' }}"
           echo "Building packages:"
           echo "  - unilabos-env (environment dependencies)"
           echo "  - unilabos (with pip package)"
-          if [[ "${{ github.event_name == 'workflow_dispatch' && github.event.inputs.build_full == 'true' }}" == "true" ]]; then
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
             echo "  - unilabos-full (complete package)"
           fi
 
@@ -131,12 +134,7 @@ jobs:
           rattler-build build -r .conda/environment/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge
 
       - name: Upload unilabos-env to Anaconda.org (if enabled)
-        if: |
-          steps.should_build.outputs.should_build == 'true' &&
-          (
-            github.event_name == 'workflow_run' ||
-            github.event.inputs.upload_to_anaconda == 'true'
-          )
+        if: steps.should_build.outputs.should_build == 'true' && github.event.inputs.upload_to_anaconda == 'true'
         run: |
           echo "Uploading unilabos-env to uni-lab organization..."
           for package in $(find ./output -name "unilabos-env*.conda"); do
@@ -151,12 +149,7 @@ jobs:
           rattler-build build -r .conda/base/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge --channel ./output
 
       - name: Upload unilabos to Anaconda.org (if enabled)
-        if: |
-          steps.should_build.outputs.should_build == 'true' &&
-          (
-            github.event_name == 'workflow_run' ||
-            github.event.inputs.upload_to_anaconda == 'true'
-          )
+        if: steps.should_build.outputs.should_build == 'true' && github.event.inputs.upload_to_anaconda == 'true'
         run: |
           echo "Uploading unilabos to uni-lab organization..."
           for package in $(find ./output -name "unilabos-0*.conda" -o -name "unilabos-[0-9]*.conda"); do
@@ -166,7 +159,6 @@ jobs:
       - name: Build unilabos-full - Only when explicitly requested
         if: |
           steps.should_build.outputs.should_build == 'true' && 
-          github.event_name == 'workflow_dispatch' &&
           github.event.inputs.build_full == 'true'
         run: |
           echo "Building unilabos-full package on ${{ matrix.platform }}..."
@@ -175,7 +167,6 @@ jobs:
       - name: Upload unilabos-full to Anaconda.org (if enabled)
         if: |
           steps.should_build.outputs.should_build == 'true' && 
-          github.event_name == 'workflow_dispatch' &&
           github.event.inputs.build_full == 'true' &&
           github.event.inputs.upload_to_anaconda == 'true'
         run: |

.gitignore

@@ -252,5 +252,3 @@ ros-humble-unilabos-msgs-0.9.13-h6403a04_5.tar.bz2
 test_config.py
 
 
-/.claude
-/.cursor

docs/ai_guides/agent_prompt_template.md

@@ -0,0 +1,344 @@
+# Uni-Lab-OS 设备接入 Agent — 提示词模板
+
+> 本文件提供一套可直接复制使用的 Agent 系统提示词，以及各平台的配置说明。
+> 提示词模板与 `add_device.md`（领域知识）配合使用，前者控制 Agent 行为，后者提供完整的技术细节。
+
+---
+
+## 系统提示词模板
+
+以下内容可直接作为系统提示词 / Instructions / Custom Instructions 使用。`{{...}}` 标记的变量根据平台替换。
+
+---
+
+### 开始复制 ↓
+
+```
+你是 Uni-Lab-OS 设备接入专家。你的任务是帮助用户将新的实验室硬件设备接入 Uni-Lab-OS 系统。
+
+你能做的事：
+- 根据用户描述，生成完整的设备驱动代码（Python）、注册表（YAML）和实验图文件（JSON）
+- 解读用户提供的通信协议文档、SDK 代码、或口述的指令格式
+- 诊断已有驱动代码的接口对齐问题
+
+你不能做的事：
+- 凭空猜测硬件私有通信指令（必须从用户提供的资料中获取）
+- 替代真实硬件联调测试
+
+## 知识来源
+
+{{KNOWLEDGE_LOADING}}
+
+## 工作流程
+
+当用户要求接入新设备时，严格按以下流程执行。每个暂停点必须等待用户确认后再继续。
+
+### 阶段 1：设备画像（交互）
+
+向用户收集以下三个信息，可以一次性提问：
+
+1. **设备类别** — 属于以下哪一种？
+   - temperature（温控）、pump_and_valve（泵阀）、motor（电机）
+   - heaterstirrer（加热搅拌）、balance（天平）、sensor（传感器）
+   - liquid_handling（液体处理）、robot_arm（机械臂）、workstation（工作站）
+   - virtual（虚拟设备）、custom（自定义）
+   - 如果是 pump_and_valve，进一步确认子类型：注射泵 / 电磁阀 / 蠕动泵
+
+2. **设备英文名称** — 用于文件名和类名（如 my_heater、runze_sy03b）
+
+3. **通信协议** — Serial(RS232/RS485) / Modbus RTU / Modbus TCP / TCP Socket / HTTP API / OPC UA / 无通信（虚拟）
+
+⏸️ **暂停：等待用户回答后继续**
+
+### 阶段 2：指令协议收集（交互）
+
+根据上一步确定的通信协议，引导用户提供指令信息：
+
+- 如果用户有 **SDK/驱动代码**：请用户提供代码文件，你从中提取通信逻辑
+- 如果用户有 **协议文档**：请用户提供文档（PDF/图片/文本），你从中解析指令格式
+- 如果用户 **口头描述**：针对每个标准动作逐一确认硬件指令
+- 如果是 **标准协议**（Modbus 寄存器表、SCPI）：请用户提供寄存器/指令映射
+- 如果是 **虚拟设备**：跳过此阶段
+
+⏸️ **暂停：确认已获取足够的指令协议信息**
+
+### 阶段 3：确认摘要
+
+在开始生成代码前，向用户展示你的理解摘要：
+
+```
+设备接入摘要：
+- 设备名称：<name>
+- 设备类别：<category>（<subtype>）
+- 通信协议：<protocol>
+- 指令来源：<source>
+- 将要实现的属性：<list>
+- 将要实现的动作：<list>
+- 同类已有设备：<existing>（将对齐其接口）
+```
+
+⏸️ **暂停：用户确认"没问题"后再生成代码**
+
+### 阶段 4：自动生成（无需暂停）
+
+按以下顺序自动执行：
+
+1. **对齐同类设备接口**（指南第四步）
+   - 查阅指南中的「现有设备接口快照」或搜索仓库注册表
+   - 确保所有已有设备的 status_types 和动作方法都被覆盖
+   - 参数名必须完全一致
+
+2. **生成驱动代码** — `unilabos/devices/<category>/<name>.py`
+
+3. **生成注册表** — `unilabos/registry/devices/<name>.yaml`（最小配置）
+
+4. **生成图文件** — `unilabos/test/experiments/graph_example_<name>.json`
+
+### 阶段 5：验证输出
+
+生成完成后，逐项检查对齐验证清单并展示结果：
+
+```
+对齐验证清单：
+- [x] 所有动作方法的参数名与已有设备完全一致
+- [x] status 属性返回的字符串值与已有设备一致
+- [x] 已有设备的所有 status_types 字段都有对应 @property
+- [x] 已有设备的所有非 auto- 前缀的 action 都有对应方法
+- [x] self.data 在 __init__ 中已预填充所有属性字段的默认值
+- [x] 串口/二进制协议的响应解析先定位帧起始标记
+```
+
+如果有未通过的项，主动修复后再展示。
+
+## 硬约束（违反任何一条都会导致设备接入失败）
+
+1. **禁止重命名参数** — 动作方法的参数名（如 volume、position、max_velocity）是接口契约，框架通过参数名分派调用。绝不能加后缀（如 volume_ml）、改名（如 speed_ml_s）。单位写在 docstring 中。
+
+2. **status 字符串必须一致** — 如果同类已有设备用英文（如 "Idle" / "Busy"），新驱动必须用相同的字符串，不能改为中文（如 "就绪"）。
+
+3. **self.data 必须预填充** — 不能用空字典 {}。框架在 initialize() 之前就可能读取属性值。每个 @property 对应的键都必须在 __init__ 中有初始值。
+
+4. **禁止跳过接口对齐** — 对齐同类设备接口是强制步骤。缺失的属性和动作会导致设备在工作流中不可互换。
+
+5. **串口解析先找帧头** — RS-485 总线上响应前常有回声/噪声字节。必须先定位帧起始标记（如 /、0xFE），禁止用硬编码索引直接解析。
+
+6. **异步等待用 _ros_node.sleep** — 在 async 方法中使用 await self._ros_node.sleep()，禁止 time.sleep()（阻塞事件循环）和 asyncio.sleep()。
+
+7. **物理单位对外暴露** — 对外参数使用用户友好的物理单位（mL、°C、RPM），驱动内部负责转换到硬件原始值（步数、Hz、寄存器值）。
+
+## 代码骨架参考
+
+所有设备驱动遵循以下结构：
+
+```python
+import logging
+import time as time_module
+from typing import Dict, Any
+
+try:
+    from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
+except ImportError:
+    BaseROS2DeviceNode = None
+
+class MyDevice:
+    _ros_node: "BaseROS2DeviceNode"
+
+    def __init__(self, device_id: str = None, config: Dict[str, Any] = None, **kwargs):
+        if device_id is None and 'id' in kwargs:
+            device_id = kwargs.pop('id')
+        if config is None and 'config' in kwargs:
+            config = kwargs.pop('config')
+        self.device_id = device_id or "unknown_device"
+        self.config = config or {}
+        self.logger = logging.getLogger(f"MyDevice.{self.device_id}")
+        self.data = {
+            "status": "Idle",
+            # 所有 @property 的键都必须在此预填充
+        }
+
+    def post_init(self, ros_node: "BaseROS2DeviceNode"):
+        self._ros_node = ros_node
+
+    async def initialize(self) -> bool:
+        self.data["status"] = "Idle"
+        return True
+
+    async def cleanup(self) -> bool:
+        self.data["status"] = "Offline"
+        return True
+
+    @property
+    def status(self) -> str:
+        return self.data.get("status", "Idle")
+```
+
+## 注册表最小配置
+
+```yaml
+my_device:
+  class:
+    module: unilabos.devices.<category>.<file>:MyDevice
+    type: python
+```
+
+启动时 --complete_registry 自动生成 status_types 和 action_value_mappings。
+
+## 图文件模板
+
+```json
+{
+    "nodes": [
+        {
+            "id": "my_device_1",
+            "name": "设备名称",
+            "children": [],
+            "parent": null,
+            "type": "device",
+            "class": "my_device",
+            "position": {"x": 0, "y": 0, "z": 0},
+            "config": {},
+            "data": {}
+        }
+    ]
+}
+```
+
+## 现有设备接口快照（对齐用）
+
+对齐时参考以下已有设备接口。如果能联网，优先从 GitHub 获取最新版本：
+https://github.com/dptech-corp/Uni-Lab-OS/tree/main/unilabos/registry/devices/
+
+### pump_and_valve — 注射泵
+
+已有设备：syringe_pump_with_valve.runze.SY03B-T06
+
+属性：status(str, "Idle"/"Busy"), valve_position(str), position(float, mL), max_velocity(float, mL/s), mode(int), plunger_position(String), velocity_grade(String), velocity_init(String), velocity_end(String)
+
+方法签名（参数名不可改）：
+- initialize()
+- set_valve_position(position)
+- set_position(position: float, max_velocity: float = None)
+- pull_plunger(volume: float)
+- push_plunger(volume: float)
+- set_max_velocity(velocity: float)
+- set_velocity_grade(velocity)
+- stop_operation()
+
+### pump_and_valve — 电磁阀
+
+属性：status(str), valve_position(str)
+方法：open(), close(), set_valve_position(position), is_open(), is_closed()
+
+### temperature
+
+属性：status(str), temp(float, °C), temp_target(float, °C), stir_speed(float, RPM), temp_warning(float, °C)
+
+### motor
+
+属性：status(str), position(int)
+
+### sensor
+
+属性：level(bool), rssi(int)
+```
+
+### 结束复制 ↑
+
+---
+
+## `{{KNOWLEDGE_LOADING}}` 变量替换
+
+根据平台能力，将提示词中的 `{{KNOWLEDGE_LOADING}}` 替换为以下对应内容：
+
+### 方案 A：有知识库（Custom GPT / Claude Project）
+
+```
+你的知识库中包含 add_device.md 文件，这是完整的设备接入指南。
+执行工作流时，参考该文件获取物模型模板、通信协议代码片段、指令协议模式和常见错误检查清单。
+本提示词中的「现有设备接口快照」和「硬约束」是从指南中提炼的关键内容，以确保即使知识库检索不完整也能正确工作。
+```
+
+### 方案 B：有联网能力
+
+```
+执行工作流前，从以下 URL 获取完整的设备接入指南：
+https://raw.githubusercontent.com/dptech-corp/Uni-Lab-OS/main/docs/ai_guides/add_device.md
+
+该指南包含物模型模板、通信协议代码片段、指令协议模式和常见错误检查清单。
+如果无法访问 URL，使用本提示词中内联的「现有设备接口快照」和「代码骨架参考」作为兜底。
+```
+
+### 方案 C：无知识库、无联网
+
+```
+完整的设备接入指南需要用户在对话中提供。
+如果用户未主动提供，请在阶段 1 开始前询问：
+"请将 add_device.md 的内容粘贴到对话中，或上传该文件。如果没有该文件，我将使用内置的精简规则工作。"
+
+本提示词已内联了最关键的内容（硬约束 + 代码骨架 + 接口快照），足以生成基本正确的驱动。
+但完整指南包含更多物模型模板和通信协议代码片段，能显著提升生成质量。
+```
+
+---
+
+## 各平台配置指南
+
+### OpenAI Custom GPT
+
+1. 进入 https://chat.openai.com/gpts/editor
+2. **Name**：Uni-Lab-OS 设备接入助手
+3. **Description**：帮助用户将实验室硬件设备接入 Uni-Lab-OS 系统，自动生成驱动代码、注册表和图文件。
+4. **Instructions**：粘贴上方系统提示词，`{{KNOWLEDGE_LOADING}}` 替换为方案 A
+5. **Knowledge**：上传 `docs/ai_guides/add_device.md`
+6. **Capabilities**：开启 Code Interpreter（用于代码验证）
+7. **Conversation starters**：
+   - "我要接入一个新的注射泵"
+   - "帮我把这个 SDK 包装成 UniLab 驱动"
+   - "检查我的设备驱动有没有接口问题"
+
+### Claude Project
+
+1. 创建新 Project
+2. **Custom Instructions**：粘贴系统提示词，`{{KNOWLEDGE_LOADING}}` 替换为方案 A
+3. **Project Knowledge**：上传 `docs/ai_guides/add_device.md`
+
+### API Agent（LangChain / AutoGen / 自建框架）
+
+```python
+system_prompt = """
+<粘贴完整系统提示词，{{KNOWLEDGE_LOADING}} 替换为方案 B>
+"""
+
+# 如果框架支持工具调用，可注册以下工具：
+tools = [
+    {
+        "name": "fetch_device_guide",
+        "description": "获取最新的 Uni-Lab-OS 设备接入指南",
+        "url": "https://raw.githubusercontent.com/dptech-corp/Uni-Lab-OS/main/docs/ai_guides/add_device.md"
+    },
+    {
+        "name": "fetch_registry",
+        "description": "获取最新的设备注册表",
+        "url": "https://raw.githubusercontent.com/dptech-corp/Uni-Lab-OS/main/unilabos/registry/devices/{category}.yaml"
+    },
+]
+```
+
+### Cursor Agent Mode
+
+无需使用本模板。Cursor 中使用已有的 `.cursor/skills/add-device/SKILL.md`，它会自动读取 `docs/ai_guides/add_device.md` 并利用 Cursor 的工具能力（Grep 搜索注册表、AskQuestion 收集信息等）。
+
+### 纯网页对话（ChatGPT / Claude 无 Project）
+
+1. 第一条消息粘贴系统提示词（`{{KNOWLEDGE_LOADING}}` 替换为方案 C）
+2. 第二条消息上传或粘贴 `add_device.md`
+3. 第三条消息开始描述设备
+
+---
+
+## 维护说明
+
+- **硬约束更新**：如果 `add_device.md` 中新增了禁止事项或常见错误，需要同步更新本模板的「硬约束」部分
+- **接口快照更新**：新增设备类别或已有设备接口变更时，需要同步更新本模板的「现有设备接口快照」部分
+- **工作流调整**：如果接入流程发生变化（新增步骤、合并步骤），需要同步调整「工作流程」部分
+- 本模板与 `add_device.md` 是**互补关系**：模板定义 Agent 行为，指南提供领域知识。两者独立维护

docs/developer_guide/add_old_device.md

@@ -18,13 +18,15 @@ Uni-Lab 开发团队在仓库中提供了 3 个样例：
 
 - 单一机械设备**电夹爪**，通讯协议可见 [增广夹爪通讯协议](https://doc.rmaxis.com/docs/communication/fieldbus/)，驱动代码位于 `unilabos/devices/gripper/rmaxis_v4.py`
 - 单一通信设备**IO 板卡**，驱动代码位于 `unilabos/device_comms/gripper/SRND_16_IO.py`
-- 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`
+- 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`。详细框架说明请参考 {doc}`plc_framework`
 
 ---
 
 ## 其他工业通信协议：CANopen, Ethernet, OPCUA...
 
-【敬请期待】
+Uni-Lab 已实现基于 OPC UA 协议的 PLC 接管框架，用于后处理工站等项目。与 Modbus 框架相比，OPC UA 框架额外提供了自动节点发现、订阅推送、断线重连等特性。详细说明请参考 {doc}`plc_framework`。
+
+其他协议（CANopen、EtherCAT 等）【敬请期待】
 
 ## 没有接口的老设备老软件：使用 PyWinAuto
 

docs/developer_guide/plc_framework.md

@@ -0,0 +1,281 @@
+# PLC 设备接管框架
+
+> 本文档面向初次接触 UniLab-OS 的开发者，介绍系统如何通过工业协议"接管"（连接并控制）PLC 设备。
+
+## 什么是"PLC 接管"？
+
+**PLC**（可编程逻辑控制器）是工厂设备的控制核心，驱动机械臂、泵、阀门等硬件。UniLab-OS 通过网络协议直接读写 PLC 内部变量，从而控制设备运行：
+
+```
+UniLab-OS（Python）  ←通信协议→  PLC  ←电信号→  电机/气缸/传感器
+```
+
+UniLab-OS 提供两套接管框架，对应两种工业协议：
+
+| 框架            | 协议             | 应用项目           | 核心文件                                                    |
+| --------------- | ---------------- | ------------------ | ----------------------------------------------------------- |
+| **Modbus 框架** | Modbus TCP / RTU | 扣式电池装配工站   | `unilabos/device_comms/modbus_plc/client.py`                |
+| **OPC UA 框架** | OPC UA           | 后处理工站（怀柔） | `unilabos/devices/workstation/post_process/post_process.py` |
+
+两套框架**设计思想完全一致**，底层通信协议不同。理解一个，另一个基本触类旁通。
+
+---
+
+## 核心概念
+
+### 节点（Node）
+
+节点是 PLC 内部一个具体的变量地址，可以理解为 PLC 的一个输入/输出端口。
+
+| 属性 | 说明                                   | 示例                 |
+| ---- | -------------------------------------- | -------------------- |
+| 名称 | 人类可读标识                           | `COIL_SYS_START_CMD` |
+| 地址 | PLC 内存地址                           | `0x0064`             |
+| 类型 | Coil / HoldRegister / InputRegister 等 | `coil`               |
+
+```
+PLC 内存空间
+├── Coil 区:    True / False  ← 控制开关量（启动/停止/复位）
+├── Hold Reg:   120, 35.5 …  ← 存参数值（速度、位置）
+└── Input Reg:  99.8, 42 …   ← 只读传感器数据
+```
+
+### 动作生命周期（Action Lifecycle）
+
+每个设备动作被拆分为 4 个阶段，用 `try/finally` 保证安全性：
+
+```python
+try:
+    init(...)    # 写入参数（速度、位置等）— 可选
+    start(...)   # 发触发信号 + 轮询等待完成
+    stop(...)    # 复位触发信号（成功时执行）
+except:
+    is_err = True
+finally:
+    cleanup(...) # 无论成败都执行，作为安全兜底
+```
+
+| 阶段      | 何时执行                | 典型内容                             |
+| --------- | ----------------------- | ------------------------------------ |
+| `init`    | 成功路径（可选）        | 写运动速度 = 20.0                    |
+| `start`   | 成功路径                | 写启动位 = True，等待完成位 = True   |
+| `stop`    | 成功路径                | 写启动位 = False（正常复位）         |
+| `cleanup` | **无论成败**（finally） | 安全兜底复位，防止异常时设备持续运动 |
+
+> **为什么 `cleanup` 无论成败都执行？**
+> 若 `start` 阶段因传感器故障抛出异常，`stop` 会被跳过，PLC 触发位仍为 `True`——设备可能持续运动。`cleanup` 放在 `finally` 块中，作为最后的安全保障，确保 PLC 一定被复位到安全状态。实际上大多数动作将 `cleanup` 设为 `null`，由 `stop` 负责正常复位即可。
+
+---
+
+## Modbus 框架
+
+**核心文件**：`unilabos/device_comms/modbus_plc/client.py`
+**参考实现**：`unilabos/devices/workstation/coin_cell_assembly/coin_cell_assembly.py`
+
+### 连接与节点注册
+
+```python
+from unilabos.device_comms.modbus_plc.client import TCPClient, BaseClient
+
+# 1. 建立 TCP 连接
+client = TCPClient(addr="172.16.28.102", port=502)
+client.client.connect()
+
+# 2. 从 CSV 加载节点定义
+nodes = BaseClient.load_csv("coin_cell_assembly_b.csv")
+
+# 3. 注册节点，之后可按名称访问
+client.register_node_list(nodes)
+
+# 访问节点
+client.use_node('COIL_SYS_START_CMD').write(True)
+value, err = client.use_node('COIL_SYS_START_STATUS').read(1)
+```
+
+**CSV 格式**（`Name` / `DeviceType` / `Address` / `DataType`）：
+
+| Name               | DeviceType    | Address | DataType |
+| ------------------ | ------------- | ------- | -------- |
+| COIL_SYS_START_CMD | coil          | 100     | INT16    |
+| REG_SPEED          | hold_register | 200     | FLOAT32  |
+
+### 三段式接管流程（扣式电池工站）
+
+PLC 设备通常需要按固定顺序切换模式，以扣式电池工站为例：
+
+```
+Python                             PLC
+  │── 写 HAND_CMD = True ─────────>│ 切换到手动模式
+  │<─ 读 HAND_STATUS = True ────────│ 确认进入手动
+  │── 写 INIT_CMD = True ──────────>│ 执行初始化
+  │<─ 读 INIT_STATUS = True ─────────│ 初始化完成
+  │── 写 HAND_CMD = False ──────────>│ 复位（脉冲信号）
+  │── 写 INIT_CMD = False ──────────>│ 复位
+  │── 写 AUTO_CMD = True ───────────>│ 切换自动模式
+  │<─ 读 AUTO_STATUS = True ─────────│ 自动模式就绪
+  │── 写 AUTO_CMD = False ──────────>│ 复位
+  │── 写 START_CMD = True ──────────>│ 开始运行
+  │<─ 读 START_STATUS = True ────────│ 运行确认
+  │── 写 START_CMD = False ──────────>│ 复位
+```
+
+> **脉冲信号模式**：命令写 `True` → 等待 PLC 状态位确认 → 命令写回 `False`，这是大多数 PLC 的标准触发方式，而不是保持高电平。
+
+### JSON 配置方式
+
+Modbus 框架支持纯 JSON 配置，无需手写 Python 流程：
+
+```json
+{
+    "register_node_list_from_csv_path": {"path": "M01.csv"},
+    "create_flow": [
+        {
+            "name": "归位",
+            "action": [{
+                "address_function_to_create": [
+                    {"func_name": "pos_tip",      "node_name": "M01_idlepos_coil_w",    "mode": "write", "value": true},
+                    {"func_name": "pos_tip_read", "node_name": "M01_idlepos_coil_r",    "mode": "read",  "value": 1},
+                    {"func_name": "manual_stop",  "node_name": "M01_manual_stop_coil_r","mode": "read",  "value": 1}
+                ],
+                "create_init_function":  {"func_name": "idel_init", "node_name": "M01_idlepos_velocity_rw", "mode": "write", "value": 20.0},
+                "create_start_function": {
+                    "func_name": "idel_position",
+                    "write_functions": ["pos_tip"],
+                    "condition_functions": ["pos_tip_read", "manual_stop"],
+                    "stop_condition_expression": "pos_tip_read[0] and manual_stop[0]"
+                },
+                "create_stop_function":  {"func_name": "idel_stop", "node_name": "M01_idlepos_coil_w", "mode": "write", "value": false},
+                "create_cleanup_function": null
+            }]
+        }
+    ],
+    "execute_flow": ["归位"]
+}
+```
+
+执行：
+
+```python
+client.execute_procedure_from_json(json_data)
+```
+
+---
+
+## OPC UA 框架
+
+**核心文件**：`unilabos/devices/workstation/post_process/post_process.py`
+**参考实现**：`unilabos/devices/workstation/post_process/opcua_huairou.json`
+
+### 与 Modbus 的主要区别
+
+| 特性       | Modbus               | OPC UA                            |
+| ---------- | -------------------- | --------------------------------- |
+| 节点发现   | 手动填写 CSV 地址    | **自动遍历**服务器节点树          |
+| 数据获取   | 轮询（主动问）       | **订阅推送**（有变化时通知）      |
+| 节点标识   | 数字地址（如 `100`） | 字符串 NodeId（如 `ns=2;s=速度`） |
+| 断线处理   | 无                   | **后台监控线程**自动重连          |
+| 认证安全   | 无                   | 支持用户名/密码                   |
+| 工作流调用 | 手动调用             | **自动注册为实例方法**            |
+
+### 连接与节点发现
+
+```python
+from unilabos.devices.workstation.post_process.post_process import OpcUaClient
+
+client = OpcUaClient(
+    url="opc.tcp://192.168.1.100:4840",
+    username="admin",              # 可选
+    password="123456",             # 可选
+    config_path="opcua_huairou.json",  # 自动加载工作流配置
+    cache_timeout=5.0,             # 节点值缓存 5 秒
+    subscription_interval=500,     # 每 500ms 接收推送
+)
+
+# 节点自动通过订阅保持最新值，读取直接查本地缓存
+value = client.get_node_value("grab_complete")
+```
+
+### JSON 配置方式
+
+```json
+{
+    "register_node_list_from_csv_path": {"path": "opcua_nodes_huairou.csv"},
+    "create_flow": [
+        {
+            "name": "trigger_grab_action",
+            "description": "触发反应罐及原料罐抓取动作",
+            "parameters": ["reaction_tank_number", "raw_tank_number"],
+            "action": [{
+                "init_function": {
+                    "func_name": "init_grab_params",
+                    "write_nodes": ["reaction_tank_number", "raw_tank_number"]
+                },
+                "start_function": {
+                    "func_name": "start_grab",
+                    "write_nodes": {"grab_trigger": true},
+                    "condition_nodes": ["grab_complete"],
+                    "stop_condition_expression": "grab_complete == True",
+                    "timeout_seconds": 999999.0
+                },
+                "stop_function": {
+                    "func_name": "stop_grab",
+                    "write_nodes": {"grab_trigger": false}
+                }
+            }]
+        }
+    ]
+}
+```
+
+配置加载后，工作流自动注册为实例方法：
+
+```python
+# 直接调用，传入参数，框架自动写入对应节点
+client.trigger_grab_action(reaction_tank_number=2, raw_tank_number=3)
+```
+
+---
+
+## 新增设备快速上手
+
+### 使用 Modbus 框架
+
+```
+1. 从 PLC 工程师处拿到地址表，按格式填写 CSV（Name/DeviceType/Address/DataType）
+2. 继承 BaseClient，在 __init__ 中连接并注册节点
+3. 参考 coin_cell_assembly.py 编写三段式接管函数（手动→初始化→自动→启动）
+4. 或直接编写 JSON 配置，调用 execute_procedure_from_json()
+```
+
+### 使用 OPC UA 框架
+
+```
+1. 确认设备支持 OPC UA，拿到服务器 URL（格式：opc.tcp://IP:PORT）
+2. 准备 CSV 节点定义文件（可选，也可让框架自动发现）
+3. 编写 JSON 配置：定义 parameters、init/start/stop 函数
+4. 实例化 OpcUaClient，传入 config_path，直接调用自动注册的工作流方法
+```
+
+---
+
+## 常见问题
+
+**Q: `node {name} is not registered` 报错？**
+A: 节点名不在 CSV 或未调用 `register_node_list_from_csv_path()`。
+
+**Q: 程序卡死在 `while not status(): sleep(1)`？**
+A: PLC 未返回预期完成信号。检查：PLC 是否在正确运行模式、状态位地址是否正确、PLC 有无报警。
+
+**Q: OPC UA 连接成功但读不到节点？**
+A: 检查节点名称是否与服务器显示名一致（区分中英文）。可调用 `_find_nodes()` 打印服务器全部节点。
+
+**Q: 应该选 Modbus 还是 OPC UA？**
+A: 取决于设备支持的协议，由 PLC 工程师决定。OPC UA 功能更完整，条件允许优先选择。
+
+---
+
+## 下一步
+
+- {doc}`add_device` - 将驱动集成进 UniLab-OS 设备节点
+- {doc}`add_action` - 为设备添加可调度的动作指令
+- {doc}`add_yaml` - 编写设备注册表 YAML 文件

docs/index.md

@@ -17,6 +17,9 @@ developer_guide/http_api.md
 developer_guide/networking_overview.md
 developer_guide/add_device.md
 developer_guide/add_action.md
+developer_guide/add_old_device.md
+developer_guide/plc_framework.md
+developer_guide/add_protocol.md
 developer_guide/add_registry.md
 developer_guide/add_yaml.md
 developer_guide/action_includes.md

recipes/conda_build_config.yaml

@@ -1,5 +1,5 @@
 channel_sources:
-  - robostack,robostack-staging,conda-forge
+  - robostack,robostack-staging,conda-forge,defaults
   
 gazebo:
   - '11'

test/devices/test_prcxi.py

@@ -1,539 +0,0 @@
-import pytest
-import json
-import os
-import asyncio
-import collections
-from typing import List, Dict, Any
-
-from pylabrobot.resources import Coordinate
-from pylabrobot.resources.opentrons.tip_racks import opentrons_96_tiprack_300ul, opentrons_96_tiprack_10ul
-from pylabrobot.resources.opentrons.plates import corning_96_wellplate_360ul_flat, nest_96_wellplate_2ml_deep
-
-from unilabos.devices.liquid_handling.prcxi.prcxi import (
-    PRCXI9300Deck,
-    PRCXI9300Container,
-    PRCXI9300Trash,
-    PRCXI9300Handler,
-    PRCXI9300Backend,
-    DefaultLayout,
-    Material,
-    WorkTablets,
-    MatrixInfo
-)
-
-
-@pytest.fixture
-def prcxi_materials() -> Dict[str, Any]:
-    """加载 PRCXI 物料数据"""
-    print("加载 PRCXI 物料数据...")
-    material_path = os.path.join(os.path.dirname(__file__), "..", "..", "unilabos", "devices", "liquid_handling", "prcxi", "prcxi_material.json")
-    with open(material_path, "r", encoding="utf-8") as f:
-        data = json.load(f)
-    print(f"加载了 {len(data)} 条物料数据")
-    return data
-
-
-@pytest.fixture
-def prcxi_9300_deck() -> PRCXI9300Deck:
-    """创建 PRCXI 9300 工作台"""
-    return PRCXI9300Deck(name="PRCXI_Deck_9300", size_x=100, size_y=100, size_z=100, model="9300")
-
-
-@pytest.fixture
-def prcxi_9320_deck() -> PRCXI9300Deck:
-    """创建 PRCXI 9320 工作台"""
-    return PRCXI9300Deck(name="PRCXI_Deck_9320", size_x=100, size_y=100, size_z=100, model="9320")
-
-
-@pytest.fixture
-def prcxi_9300_handler(prcxi_9300_deck) -> PRCXI9300Handler:
-    """创建 PRCXI 9300 处理器（模拟模式）"""
-    return PRCXI9300Handler(
-        deck=prcxi_9300_deck,
-        host="192.168.1.201",
-        port=9999,
-        timeout=10.0,
-        channel_num=8,
-        axis="Left",
-        setup=False,
-        debug=True,
-        simulator=True,
-        matrix_id="test-matrix-9300"
-    )
-
-
-@pytest.fixture
-def prcxi_9320_handler(prcxi_9320_deck) -> PRCXI9300Handler:
-    """创建 PRCXI 9320 处理器（模拟模式）"""
-    return PRCXI9300Handler(
-        deck=prcxi_9320_deck,
-        host="192.168.1.201",
-        port=9999,
-        timeout=10.0,
-        channel_num=1,
-        axis="Right",
-        setup=False,
-        debug=True,
-        simulator=True,
-        matrix_id="test-matrix-9320",
-        is_9320=True
-    )
-
-
-@pytest.fixture
-def tip_rack_300ul(prcxi_materials) -> PRCXI9300Container:
-    """创建 300μL 枪头盒"""
-    tip_rack = PRCXI9300Container(
-        name="tip_rack_300ul",
-        size_x=50,
-        size_y=50,
-        size_z=10,
-        category="tip_rack",
-        ordering=collections.OrderedDict()
-    )
-    tip_rack.load_state({
-        "Material": {
-            "uuid": prcxi_materials["300μL Tip头"]["uuid"],
-            "Code": "ZX-001-300",
-            "Name": "300μL Tip头"
-        }
-    })
-    return tip_rack
-
-
-@pytest.fixture
-def tip_rack_10ul(prcxi_materials) -> PRCXI9300Container:
-    """创建 10μL 枪头盒"""
-    tip_rack = PRCXI9300Container(
-        name="tip_rack_10ul",
-        size_x=50,
-        size_y=50,
-        size_z=10,
-        category="tip_rack",
-        ordering=collections.OrderedDict()
-    )
-    tip_rack.load_state({
-        "Material": {
-            "uuid": prcxi_materials["10μL加长 Tip头"]["uuid"],
-            "Code": "ZX-001-10+",
-            "Name": "10μL加长 Tip头"
-        }
-    })
-    return tip_rack
-
-
-@pytest.fixture
-def well_plate_96(prcxi_materials) -> PRCXI9300Container:
-    """创建 96 孔板"""
-    plate = PRCXI9300Container(
-        name="well_plate_96",
-        size_x=50,
-        size_y=50,
-        size_z=10,
-        category="plate",
-        ordering=collections.OrderedDict()
-    )
-    plate.load_state({
-        "Material": {
-            "uuid": prcxi_materials["96深孔板"]["uuid"],
-            "Code": "ZX-019-2.2",
-            "Name": "96深孔板"
-        }
-    })
-    return plate
-
-
-@pytest.fixture
-def deep_well_plate(prcxi_materials) -> PRCXI9300Container:
-    """创建深孔板"""
-    plate = PRCXI9300Container(
-        name="deep_well_plate",
-        size_x=50,
-        size_y=50,
-        size_z=10,
-        category="plate",
-        ordering=collections.OrderedDict()
-    )
-    plate.load_state({
-        "Material": {
-            "uuid": prcxi_materials["96深孔板"]["uuid"],
-            "Code": "ZX-019-2.2",
-            "Name": "96深孔板"
-        }
-    })
-    return plate
-
-
-@pytest.fixture
-def trash_container(prcxi_materials) -> PRCXI9300Trash:
-    """创建垃圾桶"""
-    trash = PRCXI9300Trash(name="trash", size_x=50, size_y=50, size_z=10, category="trash")
-    trash.load_state({
-        "Material": {
-            "uuid": prcxi_materials["废弃槽"]["uuid"]
-        }
-    })
-    return trash
-
-
-@pytest.fixture
-def default_layout_9300() -> DefaultLayout:
-    """创建 PRCXI 9300 默认布局"""
-    return DefaultLayout("PRCXI9300")
-
-
-@pytest.fixture
-def default_layout_9320() -> DefaultLayout:
-    """创建 PRCXI 9320 默认布局"""
-    return DefaultLayout("PRCXI9320")
-
-
-class TestPRCXIDeckSetup:
-    """测试 PRCXI 工作台设置功能"""
-
-    def test_prcxi_9300_deck_creation(self, prcxi_9300_deck):
-        """测试 PRCXI 9300 工作台创建"""
-        assert prcxi_9300_deck.name == "PRCXI_Deck_9300"
-        assert len(prcxi_9300_deck.sites) == 6
-        assert prcxi_9300_deck._size_x == 100
-        assert prcxi_9300_deck._size_y == 100
-        assert prcxi_9300_deck._size_z == 100
-
-    def test_prcxi_9320_deck_creation(self, prcxi_9320_deck):
-        """测试 PRCXI 9320 工作台创建"""
-        assert prcxi_9320_deck.name == "PRCXI_Deck_9320"
-        assert len(prcxi_9320_deck.sites) == 16
-        assert prcxi_9320_deck._size_x == 100
-        assert prcxi_9320_deck._size_y == 100
-        assert prcxi_9320_deck._size_z == 100
-
-    def test_container_assignment(self, prcxi_9300_deck, tip_rack_300ul, well_plate_96, trash_container):
-        """测试容器分配到工作台"""
-        # 分配枪头盒
-        prcxi_9300_deck.assign_child_resource(tip_rack_300ul, location=Coordinate(0, 0, 0))
-        assert tip_rack_300ul in prcxi_9300_deck.children
-        
-        # 分配孔板
-        prcxi_9300_deck.assign_child_resource(well_plate_96, location=Coordinate(0, 0, 0))
-        assert well_plate_96 in prcxi_9300_deck.children
-        
-        # 分配垃圾桶
-        prcxi_9300_deck.assign_child_resource(trash_container, location=Coordinate(0, 0, 0))
-        assert trash_container in prcxi_9300_deck.children
-
-    def test_container_material_loading(self, tip_rack_300ul, well_plate_96, prcxi_materials):
-        """测试容器物料信息加载"""
-        # 测试枪头盒物料信息
-        tip_material = tip_rack_300ul._unilabos_state["Material"]
-        assert tip_material["uuid"] == prcxi_materials["300μL Tip头"]["uuid"]
-        assert tip_material["Name"] == "300μL Tip头"
-        
-        # 测试孔板物料信息
-        plate_material = well_plate_96._unilabos_state["Material"]
-        assert plate_material["uuid"] == prcxi_materials["96深孔板"]["uuid"]
-        assert plate_material["Name"] == "96深孔板"
-
-
-class TestPRCXISingleStepOperations:
-    """测试 PRCXI 单步操作功能"""
-
-    @pytest.mark.asyncio
-    async def test_pick_up_tips_single_channel(self, prcxi_9320_handler, prcxi_9320_deck, tip_rack_10ul):
-        """测试单通道拾取枪头"""
-        # 将枪头盒添加到工作台
-        prcxi_9320_deck.assign_child_resource(tip_rack_10ul, location=Coordinate(0, 0, 0))
-        
-        # 初始化处理器
-        await prcxi_9320_handler.setup()
-        
-        # 设置枪头盒
-        prcxi_9320_handler.set_tiprack([tip_rack_10ul])
-        
-        # 创建模拟的枪头位置
-        from pylabrobot.resources import TipSpot, Tip
-        tip = Tip(has_filter=False, total_tip_length=10, maximal_volume=10, fitting_depth=5)
-        tip_spot = TipSpot("A1", size_x=1, size_y=1, size_z=1, make_tip=lambda: tip)
-        tip_rack_10ul.assign_child_resource(tip_spot, location=Coordinate(0, 0, 0))
-        
-        # 直接测试后端方法
-        from pylabrobot.liquid_handling import Pickup
-        pickup = Pickup(resource=tip_spot, offset=None, tip=tip)
-        await prcxi_9320_handler._unilabos_backend.pick_up_tips([pickup], [0])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "Load"
-
-    @pytest.mark.asyncio
-    async def test_pick_up_tips_multi_channel(self, prcxi_9300_handler, tip_rack_300ul):
-        """测试多通道拾取枪头"""
-        # 设置枪头盒
-        prcxi_9300_handler.set_tiprack([tip_rack_300ul])
-        
-        # 拾取8个枪头
-        tip_spots = tip_rack_300ul.children[:8]
-        await prcxi_9300_handler.pick_up_tips(tip_spots, [0, 1, 2, 3, 4, 5, 6, 7])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9300_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9300_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "Load"
-
-    @pytest.mark.asyncio
-    async def test_aspirate_single_channel(self, prcxi_9320_handler, well_plate_96):
-        """测试单通道吸取液体"""
-        # 设置液体
-        well = well_plate_96.get_item("A1")
-        prcxi_9320_handler.set_liquid([well], ["water"], [50])
-        
-        # 吸取液体
-        await prcxi_9320_handler.aspirate([well], [50], [0])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "Imbibing"
-        assert step["DosageNum"] == 50
-
-    @pytest.mark.asyncio
-    async def test_dispense_single_channel(self, prcxi_9320_handler, well_plate_96):
-        """测试单通道分配液体"""
-        # 分配液体
-        well = well_plate_96.get_item("A1")
-        await prcxi_9320_handler.dispense([well], [25], [0])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "Tapping"
-        assert step["DosageNum"] == 25
-
-    @pytest.mark.asyncio
-    async def test_mix_single_channel(self, prcxi_9320_handler, well_plate_96):
-        """测试单通道混合液体"""
-        # 混合液体
-        well = well_plate_96.get_item("A1")
-        await prcxi_9320_handler.mix([well], mix_time=3, mix_vol=50)
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "Blending"
-        assert step["BlendingTimes"] == 3
-        assert step["DosageNum"] == 50
-
-    @pytest.mark.asyncio
-    async def test_drop_tips_to_trash(self, prcxi_9320_handler, trash_container):
-        """测试丢弃枪头到垃圾桶"""
-        # 丢弃枪头
-        await prcxi_9320_handler.drop_tips([trash_container], [0])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "UnLoad"
-
-    @pytest.mark.asyncio
-    async def test_discard_tips(self, prcxi_9320_handler):
-        """测试丢弃枪头"""
-        # 丢弃枪头
-        await prcxi_9320_handler.discard_tips([0])
-        
-        # 验证步骤已添加到待办列表
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 1
-        step = prcxi_9320_handler._unilabos_backend.steps_todo_list[0]
-        assert step["Function"] == "UnLoad"
-
-    @pytest.mark.asyncio
-    async def test_liquid_transfer_workflow(self, prcxi_9320_handler, tip_rack_10ul, well_plate_96):
-        """测试完整的液体转移工作流程"""
-        # 设置枪头盒和液体
-        prcxi_9320_handler.set_tiprack([tip_rack_10ul])
-        source_well = well_plate_96.get_item("A1")
-        target_well = well_plate_96.get_item("B1")
-        prcxi_9320_handler.set_liquid([source_well], ["water"], [100])
-        
-        # 创建协议
-        await prcxi_9320_handler.create_protocol(protocol_name="Test Transfer Protocol")
-        
-        # 执行转移流程
-        tip_spot = tip_rack_10ul.get_item("A1")
-        await prcxi_9320_handler.pick_up_tips([tip_spot], [0])
-        await prcxi_9320_handler.aspirate([source_well], [50], [0])
-        await prcxi_9320_handler.dispense([target_well], [50], [0])
-        await prcxi_9320_handler.discard_tips([0])
-        
-        # 验证所有步骤都已添加
-        assert len(prcxi_9320_handler._unilabos_backend.steps_todo_list) == 4
-        functions = [step["Function"] for step in prcxi_9320_handler._unilabos_backend.steps_todo_list]
-        assert functions == ["Load", "Imbibing", "Tapping", "UnLoad"]
-
-
-class TestPRCXILayoutRecommendation:
-    """测试 PRCXI 板位推荐功能"""
-
-    def test_9300_layout_creation(self, default_layout_9300):
-        """测试 PRCXI 9300 布局创建"""
-        layout_info = default_layout_9300.get_layout()
-        assert layout_info["rows"] == 2
-        assert layout_info["columns"] == 3
-        assert len(layout_info["layout"]) == 6
-        assert layout_info["trash_slot"] == 6
-        assert "waste_liquid_slot" not in layout_info
-
-    def test_9320_layout_creation(self, default_layout_9320):
-        """测试 PRCXI 9320 布局创建"""
-        layout_info = default_layout_9320.get_layout()
-        assert layout_info["rows"] == 4
-        assert layout_info["columns"] == 4
-        assert len(layout_info["layout"]) == 16
-        assert layout_info["trash_slot"] == 16
-        assert layout_info["waste_liquid_slot"] == 12
-
-    def test_layout_recommendation_9320(self, default_layout_9320, prcxi_materials):
-        """测试 PRCXI 9320 板位推荐功能"""
-        # 添加物料信息
-        default_layout_9320.add_lab_resource(prcxi_materials)
-        
-        # 推荐布局
-        needs = [
-            ("reagent_1", "96 细胞培养皿", 3),
-            ("reagent_2", "12道储液槽", 1),
-            ("reagent_3", "200μL Tip头", 7),
-            ("reagent_4", "10μL加长 Tip头", 1),
-        ]
-        
-        matrix_layout, layout_list = default_layout_9320.recommend_layout(needs)
-        
-        # 验证返回结果
-        assert "MatrixId" in matrix_layout
-        assert "MatrixName" in matrix_layout
-        assert "MatrixCount" in matrix_layout
-        assert "WorkTablets" in matrix_layout
-        assert len(layout_list) == 12  # 3+1+7+1 = 12个位置
-        
-        # 验证推荐的位置不包含预留位置
-        reserved_positions = {12, 16}
-        recommended_positions = [item["positions"] for item in layout_list]
-        for pos in recommended_positions:
-            assert pos not in reserved_positions
-
-    def test_layout_recommendation_insufficient_space(self, default_layout_9320, prcxi_materials):
-        """测试板位推荐空间不足的情况"""
-        # 添加物料信息
-        default_layout_9320.add_lab_resource(prcxi_materials)
-        
-        # 尝试推荐超过可用空间的布局
-        needs = [
-            ("reagent_1", "96 细胞培养皿", 15),  # 需要15个位置，但只有14个可用
-        ]
-        
-        with pytest.raises(ValueError, match="需要 .* 个位置，但只有 .* 个可用位置"):
-            default_layout_9320.recommend_layout(needs)
-
-    def test_layout_recommendation_material_not_found(self, default_layout_9320, prcxi_materials):
-        """测试板位推荐物料不存在的情况"""
-        # 添加物料信息
-        default_layout_9320.add_lab_resource(prcxi_materials)
-        
-        # 尝试推荐不存在的物料
-        needs = [
-            ("reagent_1", "不存在的物料", 1),
-        ]
-        
-        with pytest.raises(ValueError, match="Material .* not found in lab resources"):
-            default_layout_9320.recommend_layout(needs)
-
-
-class TestPRCXIBackendOperations:
-    """测试 PRCXI 后端操作功能"""
-
-    def test_backend_initialization(self, prcxi_9300_handler):
-        """测试后端初始化"""
-        backend = prcxi_9300_handler._unilabos_backend
-        assert isinstance(backend, PRCXI9300Backend)
-        assert backend._num_channels == 8
-        assert backend.debug is True
-
-    def test_protocol_creation(self, prcxi_9300_handler):
-        """测试协议创建"""
-        backend = prcxi_9300_handler._unilabos_backend
-        backend.create_protocol("Test Protocol")
-        assert backend.protocol_name == "Test Protocol"
-        assert len(backend.steps_todo_list) == 0
-
-    def test_channel_validation(self):
-        """测试通道验证"""
-        # 测试正确的8通道配置
-        valid_channels = [0, 1, 2, 3, 4, 5, 6, 7]
-        result = PRCXI9300Backend.check_channels(valid_channels)
-        assert result == valid_channels
-        
-        # 测试错误的通道配置
-        invalid_channels = [0, 1, 2, 3]
-        result = PRCXI9300Backend.check_channels(invalid_channels)
-        assert result == [0, 1, 2, 3, 4, 5, 6, 7]
-
-    def test_matrix_info_creation(self, prcxi_9300_handler):
-        """测试矩阵信息创建"""
-        backend = prcxi_9300_handler._unilabos_backend
-        backend.create_protocol("Test Protocol")
-        
-        # 模拟运行协议时的矩阵信息创建
-        run_time = 1234567890
-        matrix_info = MatrixInfo(
-            MatrixId=f"{int(run_time)}",
-            MatrixName=f"protocol_{run_time}",
-            MatrixCount=len(backend.tablets_info),
-            WorkTablets=backend.tablets_info,
-        )
-        
-        assert matrix_info["MatrixId"] == str(int(run_time))
-        assert matrix_info["MatrixName"] == f"protocol_{run_time}"
-        assert "WorkTablets" in matrix_info
-
-
-class TestPRCXIContainerOperations:
-    """测试 PRCXI 容器操作功能"""
-
-    def test_container_serialization(self, tip_rack_300ul):
-        """测试容器序列化"""
-        serialized = tip_rack_300ul.serialize_state()
-        assert "Material" in serialized
-        assert serialized["Material"]["Name"] == "300μL Tip头"
-
-    def test_container_deserialization(self, tip_rack_300ul):
-        """测试容器反序列化"""
-        # 序列化
-        serialized = tip_rack_300ul.serialize_state()
-        
-        # 创建新容器并反序列化
-        new_tip_rack = PRCXI9300Container(
-            name="new_tip_rack",
-            size_x=50,
-            size_y=50,
-            size_z=10,
-            category="tip_rack",
-            ordering=collections.OrderedDict()
-        )
-        new_tip_rack.load_state(serialized)
-        
-        assert new_tip_rack._unilabos_state["Material"]["Name"] == "300μL Tip头"
-
-    def test_trash_container_creation(self, prcxi_materials):
-        """测试垃圾桶容器创建"""
-        trash = PRCXI9300Trash(name="trash", size_x=50, size_y=50, size_z=10, category="trash")
-        trash.load_state({
-            "Material": {
-                "uuid": prcxi_materials["废弃槽"]["uuid"]
-            }
-        })
-        
-        assert trash.name == "trash"
-        assert trash._unilabos_state["Material"]["uuid"] == prcxi_materials["废弃槽"]["uuid"]
-
-
-if __name__ == "__main__":
-    # 运行测试
-    pytest.main([__file__, "-v"])

tests/devices/liquid_handling/README.md

@@ -1,15 +0,0 @@
-# Liquid handling 集成测试
-
-`test_transfer_liquid.py` 现在会调用 PRCXI 的 RViz 仿真 backend，运行前请确保：
-
-1. 已安装包含 `pylabrobot`、`rclpy` 的运行环境；
-2. 启动 ROS 依赖（`rviz` 可选，但是 `rviz_backend` 会创建 ROS 节点）；
-3. 在 shell 中设置 `UNILAB_SIM_TEST=1`，否则 pytest 会自动跳过这些慢速用例：
-
-```bash
-export UNILAB_SIM_TEST=1
-pytest tests/devices/liquid_handling/test_transfer_liquid.py -m slow
-```
-
-如果只需验证逻辑层（不依赖仿真），可以直接运行 `tests/devices/liquid_handling/unit_test.py`，该文件使用 Fake backend，适合作为 CI 的快速测试。***
-

tests/devices/liquid_handling/test_transfer_liquid.py

@@ -39,11 +39,6 @@ class FakeLiquidHandler(LiquidHandlerAbstract):
         self.current_tip = iter(make_tip_iter())
         self.calls: List[Tuple[str, Any]] = []
 
-    def set_tiprack(self, tip_racks):
-        if not tip_racks:
-            return
-        super().set_tiprack(tip_racks)
-
     async def pick_up_tips(self, tip_spots, use_channels=None, offsets=None, **backend_kwargs):
         self.calls.append(("pick_up_tips", {"tips": list(tip_spots), "use_channels": use_channels}))
 

tests/devices/liquid_handling/unit_test.py

@@ -1,608 +0,0 @@
-import asyncio
-from dataclasses import dataclass
-from typing import Any, Iterable, List, Optional, Sequence, Tuple
-
-import pytest
-
-from unilabos.devices.liquid_handling.liquid_handler_abstract import LiquidHandlerAbstract
-
-
-@dataclass(frozen=True)
-class DummyContainer:
-    name: str
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return f"DummyContainer({self.name})"
-
-
-@dataclass(frozen=True)
-class DummyTipSpot:
-    name: str
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return f"DummyTipSpot({self.name})"
-
-
-def make_tip_iter(n: int = 256) -> Iterable[List[DummyTipSpot]]:
-    """Yield lists so code can safely call `tip.extend(next(self.current_tip))`."""
-    for i in range(n):
-        yield [DummyTipSpot(f"tip_{i}")]
-
-
-class FakeLiquidHandler(LiquidHandlerAbstract):
-    """不初始化真实 backend/deck；仅用来记录 transfer_liquid 内部调用序列。"""
-
-    def __init__(self, channel_num: int = 8):
-        # 不调用 super().__init__，避免真实硬件/后端依赖
-        self.channel_num = channel_num
-        self.support_touch_tip = True
-        self.current_tip = iter(make_tip_iter())
-        self.calls: List[Tuple[str, Any]] = []
-
-    def set_tiprack(self, tip_racks):
-        # transfer_liquid 总会调用 set_tiprack；测试用 Dummy 枪头时 tip_racks 为空，需保留自种子的 current_tip
-        if not tip_racks:
-            return
-        super().set_tiprack(tip_racks)
-
-    async def pick_up_tips(self, tip_spots, use_channels=None, offsets=None, **backend_kwargs):
-        self.calls.append(("pick_up_tips", {"tips": list(tip_spots), "use_channels": use_channels}))
-
-    async def aspirate(
-        self,
-        resources: Sequence[Any],
-        vols: List[float],
-        use_channels: Optional[List[int]] = None,
-        flow_rates: Optional[List[Optional[float]]] = None,
-        offsets: Any = None,
-        liquid_height: Any = None,
-        blow_out_air_volume: Any = None,
-        spread: str = "wide",
-        **backend_kwargs,
-    ):
-        self.calls.append(
-            (
-                "aspirate",
-                {
-                    "resources": list(resources),
-                    "vols": list(vols),
-                    "use_channels": list(use_channels) if use_channels is not None else None,
-                    "flow_rates": list(flow_rates) if flow_rates is not None else None,
-                    "offsets": list(offsets) if offsets is not None else None,
-                    "liquid_height": list(liquid_height) if liquid_height is not None else None,
-                    "blow_out_air_volume": list(blow_out_air_volume) if blow_out_air_volume is not None else None,
-                },
-            )
-        )
-
-    async def dispense(
-        self,
-        resources: Sequence[Any],
-        vols: List[float],
-        use_channels: Optional[List[int]] = None,
-        flow_rates: Optional[List[Optional[float]]] = None,
-        offsets: Any = None,
-        liquid_height: Any = None,
-        blow_out_air_volume: Any = None,
-        spread: str = "wide",
-        **backend_kwargs,
-    ):
-        self.calls.append(
-            (
-                "dispense",
-                {
-                    "resources": list(resources),
-                    "vols": list(vols),
-                    "use_channels": list(use_channels) if use_channels is not None else None,
-                    "flow_rates": list(flow_rates) if flow_rates is not None else None,
-                    "offsets": list(offsets) if offsets is not None else None,
-                    "liquid_height": list(liquid_height) if liquid_height is not None else None,
-                    "blow_out_air_volume": list(blow_out_air_volume) if blow_out_air_volume is not None else None,
-                },
-            )
-        )
-
-    async def discard_tips(self, use_channels=None, *args, **kwargs):
-        # 有的分支是 discard_tips(use_channels=[0])，有的分支是 discard_tips([0..7])（位置参数）
-        self.calls.append(("discard_tips", {"use_channels": list(use_channels) if use_channels is not None else None}))
-
-    async def custom_delay(self, seconds=0, msg=None):
-        self.calls.append(("custom_delay", {"seconds": seconds, "msg": msg}))
-
-    async def touch_tip(self, targets):
-        # 原实现会访问 targets.get_size_x() 等；测试里只记录调用
-        self.calls.append(("touch_tip", {"targets": targets}))
-
-def run(coro):
-    return asyncio.run(coro)
-
-
-def test_one_to_one_single_channel_basic_calls():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(64))
-
-  sources = [DummyContainer(f"S{i}") for i in range(3)]
-  targets = [DummyContainer(f"T{i}") for i in range(3)]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=targets,
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=[1, 2, 3],
-      dis_vols=[4, 5, 6],
-      mix_times=None,  # 应该仍能执行（不 mix）
-    )
-  )
-
-  assert [c[0] for c in lh.calls].count("pick_up_tips") == 3
-  assert [c[0] for c in lh.calls].count("aspirate") == 3
-  assert [c[0] for c in lh.calls].count("dispense") == 3
-  assert [c[0] for c in lh.calls].count("discard_tips") == 3
-
-  # 每次 aspirate/dispense 都是单孔列表
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  assert aspirates[0]["resources"] == [sources[0]]
-  assert aspirates[0]["vols"] == [1.0]
-
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert dispenses[2]["resources"] == [targets[2]]
-  assert dispenses[2]["vols"] == [6.0]
-
-
-def test_one_to_one_single_channel_before_stage_mixes_prior_to_aspirate():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(16))
-
-  source = DummyContainer("S0")
-  target = DummyContainer("T0")
-
-  run(
-    lh.transfer_liquid(
-      sources=[source],
-      targets=[target],
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=[5],
-      dis_vols=[5],
-      mix_stage="before",
-      mix_times=1,
-      mix_vol=3,
-    )
-  )
-
-  aspirate_calls = [(idx, payload) for idx, (name, payload) in enumerate(lh.calls) if name == "aspirate"]
-  assert len(aspirate_calls) >= 2
-  mix_idx, mix_payload = aspirate_calls[0]
-  assert mix_payload["resources"] == [target]
-  assert mix_payload["vols"] == [3]
-  transfer_idx, transfer_payload = aspirate_calls[1]
-  assert transfer_payload["resources"] == [source]
-  assert mix_idx < transfer_idx
-
-
-def test_one_to_one_eight_channel_groups_by_8():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(256))
-
-  sources = [DummyContainer(f"S{i}") for i in range(16)]
-  targets = [DummyContainer(f"T{i}") for i in range(16)]
-  asp_vols = list(range(1, 17))
-  dis_vols = list(range(101, 117))
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=targets,
-      tip_racks=[],
-      use_channels=list(range(8)),
-      asp_vols=asp_vols,
-      dis_vols=dis_vols,
-      mix_times=0,  # 触发逻辑但不 mix
-    )
-  )
-
-  # 16 个任务 -> 2 组，每组 8 通道一起做
-  assert [c[0] for c in lh.calls].count("pick_up_tips") == 2
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert len(aspirates) == 2
-  assert len(dispenses) == 2
-
-  assert aspirates[0]["resources"] == sources[0:8]
-  assert aspirates[0]["vols"] == [float(v) for v in asp_vols[0:8]]
-  assert dispenses[1]["resources"] == targets[8:16]
-  assert dispenses[1]["vols"] == [float(v) for v in dis_vols[8:16]]
-
-
-def test_one_to_one_eight_channel_requires_multiple_of_8_targets():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(64))
-
-  sources = [DummyContainer(f"S{i}") for i in range(9)]
-  targets = [DummyContainer(f"T{i}") for i in range(9)]
-
-  with pytest.raises(ValueError, match="multiple of 8"):
-    run(
-      lh.transfer_liquid(
-        sources=sources,
-        targets=targets,
-        tip_racks=[],
-        use_channels=list(range(8)),
-        asp_vols=[1] * 9,
-        dis_vols=[1] * 9,
-        mix_times=0,
-      )
-    )
-
-
-def test_one_to_one_eight_channel_parameter_lists_are_chunked_per_8():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(512))
-
-  sources = [DummyContainer(f"S{i}") for i in range(16)]
-  targets = [DummyContainer(f"T{i}") for i in range(16)]
-  asp_vols = [i + 1 for i in range(16)]
-  dis_vols = [200 + i for i in range(16)]
-  asp_flow_rates = [0.1 * (i + 1) for i in range(16)]
-  dis_flow_rates = [0.2 * (i + 1) for i in range(16)]
-  offsets = [f"offset_{i}" for i in range(16)]
-  liquid_heights = [i * 0.5 for i in range(16)]
-  blow_out_air_volume = [i + 0.05 for i in range(16)]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=targets,
-      tip_racks=[],
-      use_channels=list(range(8)),
-      asp_vols=asp_vols,
-      dis_vols=dis_vols,
-      asp_flow_rates=asp_flow_rates,
-      dis_flow_rates=dis_flow_rates,
-      offsets=offsets,
-      liquid_height=liquid_heights,
-      blow_out_air_volume=blow_out_air_volume,
-      mix_times=0,
-    )
-  )
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert len(aspirates) == len(dispenses) == 2
-
-  for batch_idx in range(2):
-    start = batch_idx * 8
-    end = start + 8
-    asp_call = aspirates[batch_idx]
-    dis_call = dispenses[batch_idx]
-    assert asp_call["resources"] == sources[start:end]
-    assert asp_call["flow_rates"] == asp_flow_rates[start:end]
-    assert asp_call["offsets"] == offsets[start:end]
-    assert asp_call["liquid_height"] == liquid_heights[start:end]
-    assert asp_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
-    assert dis_call["flow_rates"] == dis_flow_rates[start:end]
-    assert dis_call["offsets"] == offsets[start:end]
-    assert dis_call["liquid_height"] == liquid_heights[start:end]
-    assert dis_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
-
-
-def test_one_to_one_eight_channel_handles_32_tasks_four_batches():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(1024))
-
-  sources = [DummyContainer(f"S{i}") for i in range(32)]
-  targets = [DummyContainer(f"T{i}") for i in range(32)]
-  asp_vols = [i + 1 for i in range(32)]
-  dis_vols = [300 + i for i in range(32)]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=targets,
-      tip_racks=[],
-      use_channels=list(range(8)),
-      asp_vols=asp_vols,
-      dis_vols=dis_vols,
-      mix_times=0,
-    )
-  )
-
-  pick_calls = [name for name, _ in lh.calls if name == "pick_up_tips"]
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert len(pick_calls) == 4
-  assert len(aspirates) == len(dispenses) == 4
-  assert aspirates[0]["resources"] == sources[0:8]
-  assert aspirates[-1]["resources"] == sources[24:32]
-  assert dispenses[0]["resources"] == targets[0:8]
-  assert dispenses[-1]["resources"] == targets[24:32]
-
-
-def test_one_to_many_single_channel_aspirates_total_when_asp_vol_too_small():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(64))
-
-  source = DummyContainer("SRC")
-  targets = [DummyContainer(f"T{i}") for i in range(3)]
-  dis_vols = [10, 20, 30]  # sum=60
-
-  run(
-    lh.transfer_liquid(
-      sources=[source],
-      targets=targets,
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=10,  # 小于 sum(dis_vols) -> 应吸 60
-      dis_vols=dis_vols,
-      mix_times=0,
-    )
-  )
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  assert len(aspirates) == 1
-  assert aspirates[0]["resources"] == [source]
-  assert aspirates[0]["vols"] == [60.0]
-  assert aspirates[0]["use_channels"] == [0]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert [d["vols"][0] for d in dispenses] == [10.0, 20.0, 30.0]
-
-
-def test_one_to_many_eight_channel_basic():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(128))
-
-  source = DummyContainer("SRC")
-  targets = [DummyContainer(f"T{i}") for i in range(8)]
-  dis_vols = [i + 1 for i in range(8)]
-
-  run(
-    lh.transfer_liquid(
-      sources=[source],
-      targets=targets,
-      tip_racks=[],
-      use_channels=list(range(8)),
-      asp_vols=999,  # one-to-many 8ch 会按 dis_vols 吸（每通道各自）
-      dis_vols=dis_vols,
-      mix_times=0,
-    )
-  )
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  assert aspirates[0]["resources"] == [source] * 8
-  assert aspirates[0]["vols"] == [float(v) for v in dis_vols]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert dispenses[0]["resources"] == targets
-  assert dispenses[0]["vols"] == [float(v) for v in dis_vols]
-
-
-def test_many_to_one_single_channel_standard_dispense_equals_asp_by_default():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(128))
-
-  sources = [DummyContainer(f"S{i}") for i in range(3)]
-  target = DummyContainer("T")
-  asp_vols = [5, 6, 7]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=[target],
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=asp_vols,
-      dis_vols=1,  # many-to-one 允许标量；非比例模式下实际每次分液=对应 asp_vol
-      mix_times=0,
-    )
-  )
-
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert [d["vols"][0] for d in dispenses] == [float(v) for v in asp_vols]
-  assert all(d["resources"] == [target] for d in dispenses)
-
-
-def test_many_to_one_single_channel_before_stage_mixes_target_once():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(128))
-
-  sources = [DummyContainer("S0"), DummyContainer("S1")]
-  target = DummyContainer("T")
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=[target],
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=[5, 6],
-      dis_vols=1,
-      mix_stage="before",
-      mix_times=2,
-      mix_vol=4,
-    )
-  )
-
-  aspirate_calls = [(idx, payload) for idx, (name, payload) in enumerate(lh.calls) if name == "aspirate"]
-  assert len(aspirate_calls) >= 1
-  mix_idx, mix_payload = aspirate_calls[0]
-  assert mix_payload["resources"] == [target]
-  assert mix_payload["vols"] == [4]
-  # 第一個 mix 之後會真正開始吸 source
-  assert any(call["resources"] == [sources[0]] for _, call in aspirate_calls[1:])
-
-
-def test_many_to_one_single_channel_proportional_mixing_uses_dis_vols_per_source():
-  lh = FakeLiquidHandler(channel_num=1)
-  lh.current_tip = iter(make_tip_iter(128))
-
-  sources = [DummyContainer(f"S{i}") for i in range(3)]
-  target = DummyContainer("T")
-  asp_vols = [5, 6, 7]
-  dis_vols = [1, 2, 3]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=[target],
-      tip_racks=[],
-      use_channels=[0],
-      asp_vols=asp_vols,
-      dis_vols=dis_vols,  # 比例模式
-      mix_times=0,
-    )
-  )
-
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert [d["vols"][0] for d in dispenses] == [float(v) for v in dis_vols]
-
-
-def test_many_to_one_eight_channel_basic():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(256))
-
-  sources = [DummyContainer(f"S{i}") for i in range(8)]
-  target = DummyContainer("T")
-  asp_vols = [10 + i for i in range(8)]
-
-  run(
-    lh.transfer_liquid(
-      sources=sources,
-      targets=[target],
-      tip_racks=[],
-      use_channels=list(range(8)),
-      asp_vols=asp_vols,
-      dis_vols=999,  # 非比例模式下每通道分液=对应 asp_vol
-      mix_times=0,
-    )
-  )
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert aspirates[0]["resources"] == sources
-  assert aspirates[0]["vols"] == [float(v) for v in asp_vols]
-  assert dispenses[0]["resources"] == [target] * 8
-  assert dispenses[0]["vols"] == [float(v) for v in asp_vols]
-
-
-def test_transfer_liquid_mode_detection_unsupported_shape_raises():
-  lh = FakeLiquidHandler(channel_num=8)
-  lh.current_tip = iter(make_tip_iter(64))
-
-  sources = [DummyContainer("S0"), DummyContainer("S1")]
-  targets = [DummyContainer("T0"), DummyContainer("T1"), DummyContainer("T2")]
-
-  with pytest.raises(ValueError, match="Unsupported transfer mode"):
-    run(
-      lh.transfer_liquid(
-        sources=sources,
-        targets=targets,
-        tip_racks=[],
-        use_channels=[0],
-        asp_vols=[1, 1],
-        dis_vols=[1, 1, 1],
-        mix_times=0,
-      )
-    )
-
-
-def test_mix_single_target_produces_matching_cycles():
-  lh = FakeLiquidHandler(channel_num=1)
-  target = DummyContainer("T_mix")
-
-  run(lh.mix(targets=[target], mix_time=2, mix_vol=5))
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
-  assert len(aspirates) == len(dispenses) == 2
-  assert all(call["resources"] == [target] for call in aspirates)
-  assert all(call["vols"] == [5] for call in aspirates)
-  assert all(call["resources"] == [target] for call in dispenses)
-  assert all(call["vols"] == [5] for call in dispenses)
-
-
-def test_mix_multiple_targets_supports_per_target_offsets():
-  lh = FakeLiquidHandler(channel_num=1)
-  targets = [DummyContainer("T0"), DummyContainer("T1")]
-  offsets = ["left", "right"]
-  heights = [0.1, 0.2]
-  rates = [0.5, 1.0]
-
-  run(
-    lh.mix(
-      targets=targets,
-      mix_time=1,
-      mix_vol=3,
-      offsets=offsets,
-      height_to_bottom=heights,
-      mix_rate=rates,
-    )
-  )
-
-  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
-  assert len(aspirates) == 2
-  assert aspirates[0]["resources"] == [targets[0]]
-  assert aspirates[0]["offsets"] == [offsets[0]]
-  assert aspirates[0]["liquid_height"] == [heights[0]]
-  assert aspirates[0]["flow_rates"] == [rates[0]]
-  assert aspirates[1]["resources"] == [targets[1]]
-  assert aspirates[1]["offsets"] == [offsets[1]]
-  assert aspirates[1]["liquid_height"] == [heights[1]]
-  assert aspirates[1]["flow_rates"] == [rates[1]]
-
-
-def test_set_tiprack_per_type_resumes_first_physical_rack():
-    """同型号多次 set_tiprack 时接续第一盒剩余孔位，而非从新盒 A1 开始。"""
-    from pylabrobot.liquid_handling import LiquidHandlerChatterboxBackend
-    from pylabrobot.resources import Deck, Tip, TipRack, TipSpot, create_equally_spaced
-
-    mk = lambda: Tip(
-        has_filter=False, total_tip_length=10.0, maximal_volume=300.0, fitting_depth=2.0
-    )
-
-    class TipTypeAlpha(TipRack):
-        pass
-
-    class TipTypeBeta(TipRack):
-        pass
-
-    def make_rack(cls: type, name: str) -> TipRack:
-        items = create_equally_spaced(
-            TipSpot,
-            num_items_x=12,
-            num_items_y=2,
-            dx=0,
-            dy=0,
-            dz=0,
-            item_dx=9,
-            item_dy=9,
-            size_x=1,
-            size_y=1,
-            make_tip=mk,
-        )
-        return cls(name, 120, 40, 10, items=items)
-
-    rack1 = make_rack(TipTypeAlpha, "rack_phys_1")
-    rack2 = make_rack(TipTypeBeta, "rack_phys_2")
-    rack3 = make_rack(TipTypeAlpha, "rack_phys_3")
-
-    lh = LiquidHandlerAbstract(
-        LiquidHandlerChatterboxBackend(1), Deck(), channel_num=1, simulator=False
-    )
-    flat1 = lh._flatten_tips_from_one(rack1)
-    assert len(flat1) == 24
-
-    lh.set_tiprack([rack1])
-    for i in range(12):
-        assert lh._get_next_tip() is flat1[i]
-
-    lh.set_tiprack([rack2])
-    spot_b = lh._get_next_tip()
-    assert "rack_phys_2" in spot_b.name
-
-    lh.set_tiprack([rack3])
-    spot_resume = lh._get_next_tip()
-    assert spot_resume is flat1[12], "第三次同型号应接续 rack1 第二行首孔，而非 rack3 首孔"
-    assert spot_resume is not lh._flatten_tips_from_one(rack3)[0]
-
-

unilabos/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m unilabos`."""
+
+from unilabos.app.main import main
+
+if __name__ == "__main__":
+    main()

unilabos/app/web/controller.py

@@ -58,14 +58,14 @@ class JobResultStore:
                 feedback=feedback or {},
                 timestamp=time.time(),
             )
-            logger.debug(f"[JobResultStore] Stored result for job {job_id[:8]}, status={status}")
+            logger.trace(f"[JobResultStore] Stored result for job {job_id[:8]}, status={status}")
 
     def get_and_remove(self, job_id: str) -> Optional[JobResult]:
         """获取并删除任务结果"""
         with self._results_lock:
             result = self._results.pop(job_id, None)
             if result:
-                logger.debug(f"[JobResultStore] Retrieved and removed result for job {job_id[:8]}")
+                logger.trace(f"[JobResultStore] Retrieved and removed result for job {job_id[:8]}")
             return result
 
     def get_result(self, job_id: str) -> Optional[JobResult]:

unilabos/device_comms/opcua_client/node/uniopcua.py

@@ -43,7 +43,7 @@ class Base(ABC):
         self._type = typ
         self._data_type = data_type
         self._node: Optional[Node] = None
-        
+
     def _get_node(self) -> Node:
         if self._node is None:
             try:
@@ -66,7 +66,7 @@ class Base(ABC):
                 # 直接以字符串形式处理
                 if isinstance(nid, str):
                     nid = nid.strip()
-                    
+
                     # 处理包含类名的格式，如 'StringNodeId(ns=4;s=...)' 或 'NumericNodeId(ns=2;i=...)'
                     # 提取括号内的内容
                     match_wrapped = re.match(r'(String|Numeric|Byte|Guid|TwoByteNode|FourByteNode)NodeId\((.*)\)', nid)
@@ -116,16 +116,16 @@ class Base(ABC):
     def read(self) -> Tuple[Any, bool]:
         """读取节点值，返回(值, 是否出错)"""
         pass
-    
+
     @abstractmethod
     def write(self, value: Any) -> bool:
         """写入节点值，返回是否出错"""
         pass
-    
+
     @property
     def type(self) -> NodeType:
         return self._type
-    
+
     @property
     def node_id(self) -> str:
         return self._node_id
@@ -210,15 +210,15 @@ class Method(Base):
         super().__init__(client, name, node_id, NodeType.METHOD, data_type)
         self._parent_node_id = parent_node_id
         self._parent_node = None
-        
+
     def _get_parent_node(self) -> Node:
         if self._parent_node is None:
             try:
                 # 处理父节点ID，使用与_get_node相同的解析逻辑
                 import re
-                
+
                 nid = self._parent_node_id
-                
+
                 # 如果已经是 NodeId 对象，直接使用
                 try:
                     from opcua.ua import NodeId as UaNodeId
@@ -227,16 +227,16 @@ class Method(Base):
                         return self._parent_node
                 except Exception:
                     pass
-                
+
                 # 字符串处理
                 if isinstance(nid, str):
                     nid = nid.strip()
-                    
+
                     # 处理包含类名的格式
                     match_wrapped = re.match(r'(String|Numeric|Byte|Guid|TwoByteNode|FourByteNode)NodeId\((.*)\)', nid)
                     if match_wrapped:
                         nid = match_wrapped.group(2).strip()
-                    
+
                     # 常见短格式
                     if re.match(r'^ns=\d+;[is]=', nid):
                         self._parent_node = self._client.get_node(nid)
@@ -271,7 +271,7 @@ class Method(Base):
     def write(self, value: Any) -> bool:
         """方法节点不支持写入操作"""
         return True
-        
+
     def call(self, *args) -> Tuple[Any, bool]:
         """调用方法，返回(返回值, 是否出错)"""
         try:
@@ -285,7 +285,7 @@ class Method(Base):
 class Object(Base):
     def __init__(self, client: Client, name: str, node_id: str):
         super().__init__(client, name, node_id, NodeType.OBJECT, None)
-        
+
     def read(self) -> Tuple[Any, bool]:
         """对象节点不支持直接读取操作"""
         return None, True
@@ -293,7 +293,7 @@ class Object(Base):
     def write(self, value: Any) -> bool:
         """对象节点不支持直接写入操作"""
         return True
-    
+
     def get_children(self) -> Tuple[List[Node], bool]:
         """获取子节点列表，返回(子节点列表, 是否出错)"""
         try:
@@ -301,4 +301,4 @@ class Object(Base):
             return children, False
         except Exception as e:
             print(f"获取对象 {self._name} 的子节点失败: {e}")
-            return [], True 
+            return [], True

unilabos/device_mesh/resource_visalization.py

@@ -201,42 +201,17 @@ class ResourceVisualization:
                 self.moveit_controllers_yaml['moveit_simple_controller_manager'][f"{name}_{controller_name}"] = moveit_dict['moveit_simple_controller_manager'][controller_name]
 
 
-    @staticmethod
-    def _ensure_ros2_env() -> dict:
-        """确保 ROS2 环境变量正确设置，返回可用于子进程的 env dict"""
-        import sys
-        env = dict(os.environ)
-        conda_prefix = os.path.dirname(os.path.dirname(sys.executable))
-
-        if "AMENT_PREFIX_PATH" not in env or not env["AMENT_PREFIX_PATH"].strip():
-            candidate = os.pathsep.join([conda_prefix, os.path.join(conda_prefix, "Library")])
-            env["AMENT_PREFIX_PATH"] = candidate
-            os.environ["AMENT_PREFIX_PATH"] = candidate
-
-        extra_bin_dirs = [
-            os.path.join(conda_prefix, "Library", "bin"),
-            os.path.join(conda_prefix, "Library", "lib"),
-            os.path.join(conda_prefix, "Scripts"),
-            conda_prefix,
-        ]
-        current_path = env.get("PATH", "")
-        for d in extra_bin_dirs:
-            if d not in current_path:
-                current_path = d + os.pathsep + current_path
-        env["PATH"] = current_path
-        os.environ["PATH"] = current_path
-
-        return env
-
     def create_launch_description(self) -> LaunchDescription:
         """
         创建launch描述，包含robot_state_publisher和move_group节点
 
+        Args:
+            urdf_str: URDF文本
+
         Returns:
             LaunchDescription: launch描述对象
         """
-        launch_env = self._ensure_ros2_env()
-
+        # 检查ROS 2环境变量
         if "AMENT_PREFIX_PATH" not in os.environ:
             raise OSError(
                 "ROS 2环境未正确设置。需要设置 AMENT_PREFIX_PATH 环境变量。\n"
@@ -315,7 +290,7 @@ class ResourceVisualization:
                         {"robot_description": robot_description},
                         ros2_controllers,
                     ],
-                    env=launch_env,
+                    env=dict(os.environ)
                 )
             )
             for controller in self.moveit_controllers_yaml['moveit_simple_controller_manager']['controller_names']:
@@ -325,7 +300,7 @@ class ResourceVisualization:
                         executable="spawner",
                         arguments=[f"{controller}", "--controller-manager", f"controller_manager"],
                         output="screen",
-                        env=launch_env,
+                        env=dict(os.environ)
                     )
                 )
             controllers.append(
@@ -334,7 +309,7 @@ class ResourceVisualization:
                         executable="spawner",
                         arguments=["joint_state_broadcaster", "--controller-manager", f"controller_manager"],
                         output="screen",
-                        env=launch_env,
+                        env=dict(os.environ)
                 )
             )
             for i in controllers:
@@ -342,6 +317,7 @@ class ResourceVisualization:
         else:
             ros2_controllers = None
 
+        # 创建robot_state_publisher节点
         robot_state_publisher = nd(
             package='robot_state_publisher',
             executable='robot_state_publisher',
@@ -351,8 +327,9 @@ class ResourceVisualization:
                 'robot_description': robot_description,
                 'use_sim_time': False
             },
+            # kinematics_dict
             ],
-            env=launch_env,
+            env=dict(os.environ)
         )
 
 
@@ -384,7 +361,7 @@ class ResourceVisualization:
             executable='move_group',
             output='screen',
             parameters=moveit_params,
-            env=launch_env,
+            env=dict(os.environ)
         )
 
 
@@ -402,11 +379,13 @@ class ResourceVisualization:
                 arguments=['-d', f"{str(self.mesh_path)}/view_robot.rviz"],
                 output='screen',
                 parameters=[
-                    {'robot_description_kinematics': kinematics_dict},
+                    {'robot_description_kinematics': kinematics_dict,
+                     },
                     robot_description_planning,
                     planning_pipelines,
+
                 ],
-                env=launch_env,
+                env=dict(os.environ)
             )
             self.launch_description.add_action(rviz_node)
 

unilabos/devices/liquid_handling/laiyu/backend/__init__.py

@@ -1,9 +1,7 @@
 """
 LaiYu液体处理设备后端模块
-
-提供设备后端接口和实现
 """
 
-from .laiyu_backend import LaiYuLiquidBackend, create_laiyu_backend
+from .laiyu_v_backend import UniLiquidHandlerLaiyuBackend
 
-__all__ = ['LaiYuLiquidBackend', 'create_laiyu_backend']
+__all__ = ['UniLiquidHandlerLaiyuBackend']

unilabos/devices/liquid_handling/laiyu/backend/laiyu_backend.py

@@ -1,334 +0,0 @@
-"""
-LaiYu液体处理设备后端实现
-
-提供设备的后端接口和控制逻辑
-"""
-
-import logging
-from typing import Dict, Any, Optional, List
-from abc import ABC, abstractmethod
-
-# 尝试导入PyLabRobot后端
-try:
-    from pylabrobot.liquid_handling.backends import LiquidHandlerBackend
-    PYLABROBOT_AVAILABLE = True
-except ImportError:
-    PYLABROBOT_AVAILABLE = False
-    # 创建模拟后端基类
-    class LiquidHandlerBackend:
-        def __init__(self, name: str):
-            self.name = name
-            self.is_connected = False
-        
-        def connect(self):
-            """连接设备"""
-            pass
-        
-        def disconnect(self):
-            """断开连接"""
-            pass
-
-
-class LaiYuLiquidBackend(LiquidHandlerBackend):
-    """LaiYu液体处理设备后端"""
-    
-    def __init__(self, name: str = "LaiYu_Liquid_Backend"):
-        """
-        初始化LaiYu液体处理设备后端
-        
-        Args:
-            name: 后端名称
-        """
-        if PYLABROBOT_AVAILABLE:
-            # PyLabRobot 的 LiquidHandlerBackend 不接受参数
-            super().__init__()
-        else:
-            # 模拟版本接受 name 参数
-            super().__init__(name)
-        
-        self.name = name
-        self.logger = logging.getLogger(__name__)
-        self.is_connected = False
-        self.device_info = {
-            "name": "LaiYu液体处理设备",
-            "version": "1.0.0",
-            "manufacturer": "LaiYu",
-            "model": "LaiYu_Liquid_Handler"
-        }
-    
-    def connect(self) -> bool:
-        """
-        连接到LaiYu液体处理设备
-        
-        Returns:
-            bool: 连接是否成功
-        """
-        try:
-            self.logger.info("正在连接到LaiYu液体处理设备...")
-            # 这里应该实现实际的设备连接逻辑
-            # 目前返回模拟连接成功
-            self.is_connected = True
-            self.logger.info("成功连接到LaiYu液体处理设备")
-            return True
-        except Exception as e:
-            self.logger.error(f"连接LaiYu液体处理设备失败: {e}")
-            self.is_connected = False
-            return False
-    
-    def disconnect(self) -> bool:
-        """
-        断开与LaiYu液体处理设备的连接
-        
-        Returns:
-            bool: 断开连接是否成功
-        """
-        try:
-            self.logger.info("正在断开与LaiYu液体处理设备的连接...")
-            # 这里应该实现实际的设备断开连接逻辑
-            self.is_connected = False
-            self.logger.info("成功断开与LaiYu液体处理设备的连接")
-            return True
-        except Exception as e:
-            self.logger.error(f"断开LaiYu液体处理设备连接失败: {e}")
-            return False
-    
-    def is_device_connected(self) -> bool:
-        """
-        检查设备是否已连接
-        
-        Returns:
-            bool: 设备是否已连接
-        """
-        return self.is_connected
-    
-    def get_device_info(self) -> Dict[str, Any]:
-        """
-        获取设备信息
-        
-        Returns:
-            Dict[str, Any]: 设备信息字典
-        """
-        return self.device_info.copy()
-    
-    def home_device(self) -> bool:
-        """
-        设备归零操作
-        
-        Returns:
-            bool: 归零是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行归零操作")
-            return False
-        
-        try:
-            self.logger.info("正在执行设备归零操作...")
-            # 这里应该实现实际的设备归零逻辑
-            self.logger.info("设备归零操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"设备归零操作失败: {e}")
-            return False
-    
-    def aspirate(self, volume: float, location: Dict[str, Any]) -> bool:
-        """
-        吸液操作
-        
-        Args:
-            volume: 吸液体积 (微升)
-            location: 吸液位置信息
-            
-        Returns:
-            bool: 吸液是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行吸液操作")
-            return False
-        
-        try:
-            self.logger.info(f"正在执行吸液操作: 体积={volume}μL, 位置={location}")
-            # 这里应该实现实际的吸液逻辑
-            self.logger.info("吸液操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"吸液操作失败: {e}")
-            return False
-    
-    def dispense(self, volume: float, location: Dict[str, Any]) -> bool:
-        """
-        排液操作
-        
-        Args:
-            volume: 排液体积 (微升)
-            location: 排液位置信息
-            
-        Returns:
-            bool: 排液是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行排液操作")
-            return False
-        
-        try:
-            self.logger.info(f"正在执行排液操作: 体积={volume}μL, 位置={location}")
-            # 这里应该实现实际的排液逻辑
-            self.logger.info("排液操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"排液操作失败: {e}")
-            return False
-    
-    def pick_up_tip(self, location: Dict[str, Any]) -> bool:
-        """
-        取枪头操作
-        
-        Args:
-            location: 枪头位置信息
-            
-        Returns:
-            bool: 取枪头是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行取枪头操作")
-            return False
-        
-        try:
-            self.logger.info(f"正在执行取枪头操作: 位置={location}")
-            # 这里应该实现实际的取枪头逻辑
-            self.logger.info("取枪头操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"取枪头操作失败: {e}")
-            return False
-    
-    def drop_tip(self, location: Dict[str, Any]) -> bool:
-        """
-        丢弃枪头操作
-        
-        Args:
-            location: 丢弃位置信息
-            
-        Returns:
-            bool: 丢弃枪头是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行丢弃枪头操作")
-            return False
-        
-        try:
-            self.logger.info(f"正在执行丢弃枪头操作: 位置={location}")
-            # 这里应该实现实际的丢弃枪头逻辑
-            self.logger.info("丢弃枪头操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"丢弃枪头操作失败: {e}")
-            return False
-    
-    def move_to(self, location: Dict[str, Any]) -> bool:
-        """
-        移动到指定位置
-        
-        Args:
-            location: 目标位置信息
-            
-        Returns:
-            bool: 移动是否成功
-        """
-        if not self.is_connected:
-            self.logger.error("设备未连接，无法执行移动操作")
-            return False
-        
-        try:
-            self.logger.info(f"正在移动到位置: {location}")
-            # 这里应该实现实际的移动逻辑
-            self.logger.info("移动操作完成")
-            return True
-        except Exception as e:
-            self.logger.error(f"移动操作失败: {e}")
-            return False
-    
-    def get_status(self) -> Dict[str, Any]:
-        """
-        获取设备状态
-        
-        Returns:
-            Dict[str, Any]: 设备状态信息
-        """
-        return {
-            "connected": self.is_connected,
-            "device_info": self.device_info,
-            "status": "ready" if self.is_connected else "disconnected"
-        }
-    
-    # PyLabRobot 抽象方法实现
-    def stop(self):
-        """停止所有操作"""
-        self.logger.info("停止所有操作")
-        pass
-    
-    @property
-    def num_channels(self) -> int:
-        """返回通道数量"""
-        return 1  # 单通道移液器
-    
-    def can_pick_up_tip(self, tip_rack, tip_position) -> bool:
-        """检查是否可以拾取吸头"""
-        return True  # 简化实现，总是返回True
-    
-    def pick_up_tips(self, tip_rack, tip_positions):
-        """拾取多个吸头"""
-        self.logger.info(f"拾取吸头: {tip_positions}")
-        pass
-    
-    def drop_tips(self, tip_rack, tip_positions):
-        """丢弃多个吸头"""
-        self.logger.info(f"丢弃吸头: {tip_positions}")
-        pass
-    
-    def pick_up_tips96(self, tip_rack):
-        """拾取96个吸头"""
-        self.logger.info("拾取96个吸头")
-        pass
-    
-    def drop_tips96(self, tip_rack):
-        """丢弃96个吸头"""
-        self.logger.info("丢弃96个吸头")
-        pass
-    
-    def aspirate96(self, volume, plate, well_positions):
-        """96通道吸液"""
-        self.logger.info(f"96通道吸液: 体积={volume}")
-        pass
-    
-    def dispense96(self, volume, plate, well_positions):
-        """96通道排液"""
-        self.logger.info(f"96通道排液: 体积={volume}")
-        pass
-    
-    def pick_up_resource(self, resource, location):
-        """拾取资源"""
-        self.logger.info(f"拾取资源: {resource}")
-        pass
-    
-    def drop_resource(self, resource, location):
-        """放置资源"""
-        self.logger.info(f"放置资源: {resource}")
-        pass
-    
-    def move_picked_up_resource(self, resource, location):
-        """移动已拾取的资源"""
-        self.logger.info(f"移动资源: {resource} 到 {location}")
-        pass
-
-
-def create_laiyu_backend(name: str = "LaiYu_Liquid_Backend") -> LaiYuLiquidBackend:
-    """
-    创建LaiYu液体处理设备后端实例
-    
-    Args:
-        name: 后端名称
-        
-    Returns:
-        LaiYuLiquidBackend: 后端实例
-    """
-    return LaiYuLiquidBackend(name)

unilabos/devices/liquid_handling/laiyu/backend/laiyu_v_backend.py

@@ -1,385 +1,307 @@
-      
-import json
+"""LaiYu PLR 后端 — 对齐路径 B 硬件交互模式
+
+硬件初始化顺序与 laiyu_liquid_station.py (路径 B) 一致:
+  1. XYZController(auto_connect=True) — 先开串口
+  2. PipetteController.connect_shared() — 共享 XYZ 的串口 / 锁
+  3. home_all_axes() + pipette.initialize()
+"""
+
+import logging
 from typing import List, Optional, Union
 
-from pylabrobot.liquid_handling.backends.backend import (
-  LiquidHandlerBackend,
-)
+from pylabrobot.liquid_handling.backends.backend import LiquidHandlerBackend
 from pylabrobot.liquid_handling.standard import (
-  Drop,
-  DropTipRack,
-  MultiHeadAspirationContainer,
-  MultiHeadAspirationPlate,
-  MultiHeadDispenseContainer,
-  MultiHeadDispensePlate,
-  Pickup,
-  PickupTipRack,
-  ResourceDrop,
-  ResourceMove,
-  ResourcePickup,
-  SingleChannelAspiration,
-  SingleChannelDispense,
+    Drop,
+    DropTipRack,
+    MultiHeadAspirationContainer,
+    MultiHeadAspirationPlate,
+    MultiHeadDispenseContainer,
+    MultiHeadDispensePlate,
+    Pickup,
+    PickupTipRack,
+    ResourceDrop,
+    ResourceMove,
+    ResourcePickup,
+    SingleChannelAspiration,
+    SingleChannelDispense,
 )
 from pylabrobot.resources import Resource, Tip
 
-import rclpy
-from rclpy.node import Node
-from sensor_msgs.msg import JointState
-import time
-from rclpy.action import ActionClient
-from unilabos_msgs.action import SendCmd
-import re
+from unilabos.devices.liquid_handling.laiyu.controllers.xyz_controller import XYZController
+from unilabos.devices.liquid_handling.laiyu.controllers.pipette_controller import (
+    PipetteController,
+    TipStatus,
+)
 
-from unilabos.devices.ros_dev.liquid_handler_joint_publisher import JointStatePublisher
-from unilabos.devices.liquid_handling.laiyu.controllers.pipette_controller import PipetteController, TipStatus
+logger = logging.getLogger(__name__)
 
 
 class UniLiquidHandlerLaiyuBackend(LiquidHandlerBackend):
-  """Chatter box backend for device-free testing. Prints out all operations."""
+    """LaiYu 硬件后端 — PLR Backend 接口实现"""
 
-  _pip_length = 5
-  _vol_length = 8
-  _resource_length = 20
-  _offset_length = 16
-  _flow_rate_length = 10
-  _blowout_length = 10
-  _lld_z_length = 10
-  _kwargs_length = 15
-  _tip_type_length = 12
-  _max_volume_length = 16
-  _fitting_depth_length = 20
-  _tip_length_length = 16
-  # _pickup_method_length = 20
-  _filter_length = 10
+    def __init__(
+        self,
+        num_channels: int = 1,
+        tip_length: float = 0,
+        total_height: float = 310,
+        port: str = "/dev/ttyUSB0",
+        baudrate: int = 115200,
+        pipette_address: int = 4,
+    ):
+        super().__init__()
+        self._num_channels = num_channels
+        self.tip_length = tip_length
+        self.total_height = total_height
 
-  def __init__(self, num_channels: int = 8 , tip_length: float = 0 , total_height: float = 310, port: str = "/dev/ttyUSB0"):
-    """Initialize a chatter box backend."""
-    super().__init__()
-    self._num_channels = num_channels
-    self.tip_length = tip_length
-    self.total_height = total_height
-# rclpy.init()
-    if not rclpy.ok():
-        rclpy.init()
-    self.joint_state_publisher = None
-    self.hardware_interface = PipetteController(port=port)
+        # 保存配置，延迟到 setup() 再创建硬件对象
+        self._port = port
+        self._baudrate = baudrate
+        self._pipette_address = pipette_address
 
-  async def setup(self):
-    # self.joint_state_publisher = JointStatePublisher()
-    # self.hardware_interface.xyz_controller.connect_device()
-    # self.hardware_interface.xyz_controller.home_all_axes()
-    await super().setup()
-    self.hardware_interface.connect()
-    self.hardware_interface.initialize()
+        self._xyz: Optional[XYZController] = None
+        self._pipette_ctrl: Optional[PipetteController] = None
+        self._ros_node = None
 
-    print("Setting up the liquid handler.")
+    # ------------------------------------------------------------------ lifecycle
 
-  async def stop(self):
-    print("Stopping the liquid handler.")
+    def post_init(self, ros_node):
+        """接收 ROS 节点引用（由 Handler.post_init 调用）"""
+        self._ros_node = ros_node
 
-  def serialize(self) -> dict:
-    return {**super().serialize(), "num_channels": self.num_channels}
+    async def setup(self):
+        """按路径 B 顺序初始化硬件"""
+        await super().setup()
 
-  def pipette_aspirate(self, volume: float, flow_rate: float):
+        # 1. XYZ 先开串口
+        self._xyz = XYZController(
+            port=self._port,
+            baudrate=self._baudrate,
+            auto_connect=True,
+        )
+        if not self._xyz.is_connected:
+            raise RuntimeError("XYZ 控制器连接失败")
 
-    self.hardware_interface.pipette.set_max_speed(flow_rate)
-    res = self.hardware_interface.pipette.aspirate(volume=volume)
-    
-    if not res:
-        self.hardware_interface.logger.error("吸取失败，当前体积: {self.hardware_interface.current_volume}")
-        return
+        # 2. PipetteController 共享 XYZ 串口
+        self._pipette_ctrl = PipetteController(
+            port=self._port,
+            address=self._pipette_address,
+        )
+        self._pipette_ctrl.connect_shared(
+            serial_conn=self._xyz.serial_conn,
+            serial_lock=self._xyz.serial_lock,
+            xyz_controller=self._xyz,
+        )
 
-    self.hardware_interface.current_volume += volume 
+        # 3. 回零 + 移液器初始化
+        self._xyz.home_all_axes()
+        self._pipette_ctrl.initialize()
 
-  def pipette_dispense(self, volume: float, flow_rate: float):
+        logger.info("LaiYu 后端硬件初始化完成")
 
-    self.hardware_interface.pipette.set_max_speed(flow_rate)
-    res = self.hardware_interface.pipette.dispense(volume=volume)
-    if not res:
-        self.hardware_interface.logger.error("排液失败，当前体积: {self.hardware_interface.current_volume}")
-        return
-    self.hardware_interface.current_volume -= volume
+    async def stop(self):
+        """正确断开硬件"""
+        try:
+            if self._pipette_ctrl:
+                self._pipette_ctrl.disconnect_shared()
+            if self._xyz:
+                self._xyz.disconnect()
+            logger.info("LaiYu 后端硬件已断开")
+        except Exception as e:
+            logger.error(f"停止后端失败: {e}")
 
-  @property
-  def num_channels(self) -> int:
-    return self._num_channels
+    # ------------------------------------------------------------------ helpers
 
-  async def assigned_resource_callback(self, resource: Resource):
-    print(f"Resource {resource.name} was assigned to the liquid handler.")
+    def _plr_to_machine_coords(self, resource, offset):
+        """PLR Resource 坐标 → 机器坐标 (倒置龙门架: total_height - z, -y)"""
+        coordinate = resource.get_absolute_location(x="c", y="c")
+        x = coordinate.x + offset.x
+        y = coordinate.y + offset.y
+        z_plr = coordinate.z + offset.z
+        return x, -y, self.total_height - (z_plr + self.tip_length)
 
-  async def unassigned_resource_callback(self, name: str):
-    print(f"Resource {name} was unassigned from the liquid handler.")
+    def _pipette_aspirate(self, volume: float, flow_rate: float):
+        self._pipette_ctrl.pipette.set_max_speed(flow_rate)
+        res = self._pipette_ctrl.pipette.aspirate(volume=volume)
+        if not res:
+            logger.error(f"吸取失败，当前体积: {self._pipette_ctrl.current_volume}")
+            return
+        self._pipette_ctrl.current_volume += volume
 
-  async def pick_up_tips(self, ops: List[Pickup], use_channels: List[int], **backend_kwargs):
-    print("Picking up tips:")
-    # print(ops.tip)
-    header = (
-      f"{'pip#':<{UniLiquidHandlerLaiyuBackend._pip_length}} "
-      f"{'resource':<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-      f"{'offset':<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-      f"{'tip type':<{UniLiquidHandlerLaiyuBackend._tip_type_length}} "
-      f"{'max volume (µL)':<{UniLiquidHandlerLaiyuBackend._max_volume_length}} "
-      f"{'fitting depth (mm)':<{UniLiquidHandlerLaiyuBackend._fitting_depth_length}} "
-      f"{'tip length (mm)':<{UniLiquidHandlerLaiyuBackend._tip_length_length}} "
-      # f"{'pickup method':<{ChatterboxBackend._pickup_method_length}} "
-      f"{'filter':<{UniLiquidHandlerLaiyuBackend._filter_length}}"
-    )
-    # print(header)
+    def _pipette_dispense(self, volume: float, flow_rate: float):
+        self._pipette_ctrl.pipette.set_max_speed(flow_rate)
+        res = self._pipette_ctrl.pipette.dispense(volume=volume)
+        if not res:
+            logger.error(f"排液失败，当前体积: {self._pipette_ctrl.current_volume}")
+            return
+        self._pipette_ctrl.current_volume -= volume
 
-    for op, channel in zip(ops, use_channels):
-      offset = f"{round(op.offset.x, 1)},{round(op.offset.y, 1)},{round(op.offset.z, 1)}"
-      row = (
-        f"  p{channel}: "
-        f"{op.resource.name[-30:]:<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-        f"{offset:<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-        f"{op.tip.__class__.__name__:<{UniLiquidHandlerLaiyuBackend._tip_type_length}} "
-        f"{op.tip.maximal_volume:<{UniLiquidHandlerLaiyuBackend._max_volume_length}} "
-        f"{op.tip.fitting_depth:<{UniLiquidHandlerLaiyuBackend._fitting_depth_length}} "
-        f"{op.tip.total_tip_length:<{UniLiquidHandlerLaiyuBackend._tip_length_length}} "
-        # f"{str(op.tip.pickup_method)[-20:]:<{ChatterboxBackend._pickup_method_length}} "
-        f"{'Yes' if op.tip.has_filter else 'No':<{UniLiquidHandlerLaiyuBackend._filter_length}}"
-      )
-      # print(row)
-      # print(op.resource.get_absolute_location())
-    
-    self.tip_length = ops[0].tip.total_tip_length
-    coordinate = ops[0].resource.get_absolute_location(x="c",y="c")
-    offset_xyz = ops[0].offset
-    x = coordinate.x + offset_xyz.x
-    y = coordinate.y + offset_xyz.y
-    z = self.total_height - (coordinate.z + self.tip_length) + offset_xyz.z
-    # print("moving")
-    self.hardware_interface._update_tip_status()
-    if self.hardware_interface.tip_status == TipStatus.TIP_ATTACHED:
-        print("已有枪头，无需重复拾取")
-        return
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(x=x, y=-y, z=z,speed=200)
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(z=self.hardware_interface.xyz_controller.machine_config.safe_z_height,speed=100)
-    # self.joint_state_publisher.send_resource_action(ops[0].resource.name, x, y, z, "pick",channels=use_channels)
-    #   goback()
+    # ------------------------------------------------------------------ properties
 
+    def serialize(self) -> dict:
+        return {**super().serialize(), "num_channels": self.num_channels}
 
+    @property
+    def num_channels(self) -> int:
+        return self._num_channels
 
+    # ------------------------------------------------------------------ resource callbacks
 
-  async def drop_tips(self, ops: List[Drop], use_channels: List[int], **backend_kwargs):
-    print("Dropping tips:")
-    header = (
-      f"{'pip#':<{UniLiquidHandlerLaiyuBackend._pip_length}} "
-      f"{'resource':<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-      f"{'offset':<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-      f"{'tip type':<{UniLiquidHandlerLaiyuBackend._tip_type_length}} "
-      f"{'max volume (µL)':<{UniLiquidHandlerLaiyuBackend._max_volume_length}} "
-      f"{'fitting depth (mm)':<{UniLiquidHandlerLaiyuBackend._fitting_depth_length}} "
-      f"{'tip length (mm)':<{UniLiquidHandlerLaiyuBackend._tip_length_length}} "
-      # f"{'pickup method':<{ChatterboxBackend._pickup_method_length}} "
-      f"{'filter':<{UniLiquidHandlerLaiyuBackend._filter_length}}"
-    )
-    # print(header)
+    async def assigned_resource_callback(self, resource: Resource):
+        logger.info(f"Resource {resource.name} was assigned to the liquid handler.")
 
-    for op, channel in zip(ops, use_channels):
-      offset = f"{round(op.offset.x, 1)},{round(op.offset.y, 1)},{round(op.offset.z, 1)}"
-      row = (
-        f"  p{channel}: "
-        f"{op.resource.name[-30:]:<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-        f"{offset:<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-        f"{op.tip.__class__.__name__:<{UniLiquidHandlerLaiyuBackend._tip_type_length}} "
-        f"{op.tip.maximal_volume:<{UniLiquidHandlerLaiyuBackend._max_volume_length}} "
-        f"{op.tip.fitting_depth:<{UniLiquidHandlerLaiyuBackend._fitting_depth_length}} "
-        f"{op.tip.total_tip_length:<{UniLiquidHandlerLaiyuBackend._tip_length_length}} "
-        # f"{str(op.tip.pickup_method)[-20:]:<{ChatterboxBackend._pickup_method_length}} "
-        f"{'Yes' if op.tip.has_filter else 'No':<{UniLiquidHandlerLaiyuBackend._filter_length}}"
-      )
-      # print(row)
+    async def unassigned_resource_callback(self, name: str):
+        logger.info(f"Resource {name} was unassigned from the liquid handler.")
 
-    coordinate = ops[0].resource.get_absolute_location(x="c",y="c")
-    offset_xyz = ops[0].offset
-    x = coordinate.x + offset_xyz.x
-    y = coordinate.y + offset_xyz.y
-    z = self.total_height - (coordinate.z + self.tip_length) + offset_xyz.z -20
-    # print(x, y, z)
-    # print("moving")
-    self.hardware_interface._update_tip_status()
-    if self.hardware_interface.tip_status == TipStatus.NO_TIP:
-        print("无枪头，无需丢弃")
-        return
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(x=x, y=-y, z=z,speed=200)
-    self.hardware_interface.eject_tip
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(z=self.hardware_interface.xyz_controller.machine_config.safe_z_height)  
+    # ------------------------------------------------------------------ pick_up_tips
 
-  async def aspirate(
-    self,
-    ops: List[SingleChannelAspiration],
-    use_channels: List[int],
-    **backend_kwargs,
-  ):
-    print("Aspirating:")
-    header = (
-      f"{'pip#':<{UniLiquidHandlerLaiyuBackend._pip_length}} "
-      f"{'vol(ul)':<{UniLiquidHandlerLaiyuBackend._vol_length}} "
-      f"{'resource':<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-      f"{'offset':<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-      f"{'flow rate':<{UniLiquidHandlerLaiyuBackend._flow_rate_length}} "
-      f"{'blowout':<{UniLiquidHandlerLaiyuBackend._blowout_length}} "
-      f"{'lld_z':<{UniLiquidHandlerLaiyuBackend._lld_z_length}}  "
-      # f"{'liquids':<20}" # TODO: add liquids
-    )
-    for key in backend_kwargs:
-      header += f"{key:<{UniLiquidHandlerLaiyuBackend._kwargs_length}} "[-16:]
-    # print(header)
+    async def pick_up_tips(self, ops: List[Pickup], use_channels: List[int], **backend_kwargs):
+        tip = ops[0].tip
+        self.tip_length = tip.total_tip_length
+        x, y, z_top = self._plr_to_machine_coords(ops[0].resource, ops[0].offset)
 
-    for o, p in zip(ops, use_channels):
-      offset = f"{round(o.offset.x, 1)},{round(o.offset.y, 1)},{round(o.offset.z, 1)}"
-      row = (
-        f"  p{p}: "
-        f"{o.volume:<{UniLiquidHandlerLaiyuBackend._vol_length}} "
-        f"{o.resource.name[-20:]:<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-        f"{offset:<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-        f"{str(o.flow_rate):<{UniLiquidHandlerLaiyuBackend._flow_rate_length}} "
-        f"{str(o.blow_out_air_volume):<{UniLiquidHandlerLaiyuBackend._blowout_length}} "
-        f"{str(o.liquid_height):<{UniLiquidHandlerLaiyuBackend._lld_z_length}} "
-        # f"{o.liquids if o.liquids is not None else 'none'}"
-      )
-      for key, value in backend_kwargs.items():
-        if isinstance(value, list) and all(isinstance(v, bool) for v in value):
-          value = "".join("T" if v else "F" for v in value)
-        if isinstance(value, list):
-          value = "".join(map(str, value))
-        row += f" {value:<15}"
-      # print(row)
-    coordinate = ops[0].resource.get_absolute_location(x="c",y="c")
-    offset_xyz = ops[0].offset
-    x = coordinate.x + offset_xyz.x
-    y = coordinate.y + offset_xyz.y
-    z = self.total_height - (coordinate.z + self.tip_length) + offset_xyz.z
-    # print(x, y, z)
-    # print("moving")
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status == TipStatus.TIP_ATTACHED:
+            logger.warning("已有枪头，无需重复拾取")
+            return
 
-    # 判断枪头是否存在
-    self.hardware_interface._update_tip_status()
-    if not self.hardware_interface.tip_status == TipStatus.TIP_ATTACHED:
-        print("无枪头，无法吸液")
-        return
-    # 判断吸液量是否超过枪头容量
-    flow_rate = backend_kwargs["flow_rate"] if "flow_rate" in backend_kwargs else 500
-    blow_out_air_volume = backend_kwargs["blow_out_air_volume"] if "blow_out_air_volume" in backend_kwargs else 0
-    if self.hardware_interface.current_volume + ops[0].volume + blow_out_air_volume > self.hardware_interface.max_volume:
-        self.hardware_interface.logger.error(f"吸液量超过枪头容量: {self.hardware_interface.current_volume + ops[0].volume} > {self.hardware_interface.max_volume}")
-        return
+        try:
+            # 1. 移到枪头正上方
+            self._xyz.move_to_work_coord_safe(x=x, y=y, z=z_top, speed=200)
+            # 2. 下压到套枪头深度（fitting_depth 是枪头套入长度）
+            z_pickup = z_top + tip.fitting_depth
+            self._xyz.move_to_work_coord_safe(z=z_pickup, speed=100)
+            # 3. 退回安全高度
+            self._xyz.move_to_work_coord_safe(
+                z=self._xyz.machine_config.safe_z_height, speed=100
+            )
+        except Exception as e:
+            logger.error(f"pick_up_tips 移动失败: {e}")
+            raise
 
-    # 移动到吸液位置
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(x=x, y=-y, z=z,speed=200)
-    self.pipette_aspirate(volume=ops[0].volume, flow_rate=flow_rate)
+    # ------------------------------------------------------------------ drop_tips
 
+    async def drop_tips(self, ops: List[Drop], use_channels: List[int], **backend_kwargs):
+        x, y, z = self._plr_to_machine_coords(ops[0].resource, ops[0].offset)
+        z -= 20  # 额外下移补偿
 
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(z=self.hardware_interface.xyz_controller.machine_config.safe_z_height)
-    if blow_out_air_volume >0: 
-        self.pipette_aspirate(volume=blow_out_air_volume, flow_rate=flow_rate)
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status == TipStatus.NO_TIP:
+            logger.warning("无枪头，无需丢弃")
+            return
 
+        try:
+            self._xyz.move_to_work_coord_safe(x=x, y=y, z=z, speed=200)
+            self._pipette_ctrl.eject_tip()  # 修复: 原来缺少 ()
+            self._xyz.move_to_work_coord_safe(
+                z=self._xyz.machine_config.safe_z_height
+            )
+        except Exception as e:
+            logger.error(f"drop_tips 失败: {e}")
+            raise
 
+    # ------------------------------------------------------------------ aspirate
 
+    async def aspirate(
+        self,
+        ops: List[SingleChannelAspiration],
+        use_channels: List[int],
+        **backend_kwargs,
+    ):
+        x, y, z = self._plr_to_machine_coords(ops[0].resource, ops[0].offset)
 
-  async def dispense(
-    self,
-    ops: List[SingleChannelDispense],
-    use_channels: List[int],
-    **backend_kwargs,
-  ):
-    # print("Dispensing:")
-    header = (
-      f"{'pip#':<{UniLiquidHandlerLaiyuBackend._pip_length}} "
-      f"{'vol(ul)':<{UniLiquidHandlerLaiyuBackend._vol_length}} "
-      f"{'resource':<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-      f"{'offset':<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-      f"{'flow rate':<{UniLiquidHandlerLaiyuBackend._flow_rate_length}} "
-      f"{'blowout':<{UniLiquidHandlerLaiyuBackend._blowout_length}} "
-      f"{'lld_z':<{UniLiquidHandlerLaiyuBackend._lld_z_length}}  "
-      # f"{'liquids':<20}" # TODO: add liquids
-    )
-    for key in backend_kwargs:
-      header += f"{key:<{UniLiquidHandlerLaiyuBackend._kwargs_length}} "[-16:]
-    # print(header)
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status != TipStatus.TIP_ATTACHED:
+            raise RuntimeError("无枪头，无法吸液")
 
-    for o, p in zip(ops, use_channels):
-      offset = f"{round(o.offset.x, 1)},{round(o.offset.y, 1)},{round(o.offset.z, 1)}"
-      row = (
-        f"  p{p}: "
-        f"{o.volume:<{UniLiquidHandlerLaiyuBackend._vol_length}} "
-        f"{o.resource.name[-20:]:<{UniLiquidHandlerLaiyuBackend._resource_length}} "
-        f"{offset:<{UniLiquidHandlerLaiyuBackend._offset_length}} "
-        f"{str(o.flow_rate):<{UniLiquidHandlerLaiyuBackend._flow_rate_length}} "
-        f"{str(o.blow_out_air_volume):<{UniLiquidHandlerLaiyuBackend._blowout_length}} "
-        f"{str(o.liquid_height):<{UniLiquidHandlerLaiyuBackend._lld_z_length}} "
-        # f"{o.liquids if o.liquids is not None else 'none'}"
-      )
-      for key, value in backend_kwargs.items():
-        if isinstance(value, list) and all(isinstance(v, bool) for v in value):
-          value = "".join("T" if v else "F" for v in value)
-        if isinstance(value, list):
-          value = "".join(map(str, value))
-        row += f" {value:<{UniLiquidHandlerLaiyuBackend._kwargs_length}}"
-      # print(row)
-    coordinate = ops[0].resource.get_absolute_location(x="c",y="c")
-    offset_xyz = ops[0].offset
-    x = coordinate.x + offset_xyz.x
-    y = coordinate.y + offset_xyz.y
-    z = self.total_height - (coordinate.z + self.tip_length) + offset_xyz.z
-    # print(x, y, z)
-    # print("moving")
+        flow_rate = backend_kwargs.get("flow_rate", 500)
+        blow_out_air_volume = backend_kwargs.get("blow_out_air_volume", 0)
 
-    # 判断枪头是否存在
-    self.hardware_interface._update_tip_status()
-    if not self.hardware_interface.tip_status == TipStatus.TIP_ATTACHED:
-        print("无枪头，无法排液")
-        return
-    # 判断排液量是否超过枪头容量
-    flow_rate = backend_kwargs["flow_rate"] if "flow_rate" in backend_kwargs else 500
-    blow_out_air_volume = backend_kwargs["blow_out_air_volume"] if "blow_out_air_volume" in backend_kwargs else 0
-    if self.hardware_interface.current_volume - ops[0].volume - blow_out_air_volume < 0:
-        self.hardware_interface.logger.error(f"排液量超过枪头容量: {self.hardware_interface.current_volume - ops[0].volume - blow_out_air_volume} < 0")
-        return
+        if (
+            self._pipette_ctrl.current_volume + ops[0].volume + blow_out_air_volume
+            > self._pipette_ctrl.max_volume
+        ):
+            raise RuntimeError(
+                f"吸液量超过枪头容量: "
+                f"{self._pipette_ctrl.current_volume + ops[0].volume} > {self._pipette_ctrl.max_volume}"
+            )
 
-    
-    # 移动到排液位置  
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(x=x, y=-y, z=z,speed=200)
-    self.pipette_dispense(volume=ops[0].volume, flow_rate=flow_rate)
+        self._xyz.move_to_work_coord_safe(x=x, y=y, z=z, speed=200)
+        self._pipette_aspirate(volume=ops[0].volume, flow_rate=flow_rate)
 
+        self._xyz.move_to_work_coord_safe(
+            z=self._xyz.machine_config.safe_z_height
+        )
+        if blow_out_air_volume > 0:
+            self._pipette_aspirate(volume=blow_out_air_volume, flow_rate=flow_rate)
 
-    self.hardware_interface.xyz_controller.move_to_work_coord_safe(z=self.hardware_interface.xyz_controller.machine_config.safe_z_height)
-    if blow_out_air_volume > 0: 
-        self.pipette_dispense(volume=blow_out_air_volume, flow_rate=flow_rate)
-    # self.joint_state_publisher.send_resource_action(ops[0].resource.name, x, y, z, "",channels=use_channels)
+    # ------------------------------------------------------------------ dispense
 
-  async def pick_up_tips96(self, pickup: PickupTipRack, **backend_kwargs):
-    print(f"Picking up tips from {pickup.resource.name}.")
+    async def dispense(
+        self,
+        ops: List[SingleChannelDispense],
+        use_channels: List[int],
+        **backend_kwargs,
+    ):
+        x, y, z = self._plr_to_machine_coords(ops[0].resource, ops[0].offset)
 
-  async def drop_tips96(self, drop: DropTipRack, **backend_kwargs):
-    print(f"Dropping tips to {drop.resource.name}.")
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status != TipStatus.TIP_ATTACHED:
+            raise RuntimeError("无枪头，无法排液")
 
-  async def aspirate96(
-    self, aspiration: Union[MultiHeadAspirationPlate, MultiHeadAspirationContainer]
-  ):
-    if isinstance(aspiration, MultiHeadAspirationPlate):
-      resource = aspiration.wells[0].parent
-    else:
-      resource = aspiration.container
-    print(f"Aspirating {aspiration.volume} from {resource}.")
+        flow_rate = backend_kwargs.get("flow_rate", 500)
+        blow_out_air_volume = backend_kwargs.get("blow_out_air_volume", 0)
 
-  async def dispense96(self, dispense: Union[MultiHeadDispensePlate, MultiHeadDispenseContainer]):
-    if isinstance(dispense, MultiHeadDispensePlate):
-      resource = dispense.wells[0].parent
-    else:
-      resource = dispense.container
-    print(f"Dispensing {dispense.volume} to {resource}.")
+        if (
+            self._pipette_ctrl.current_volume - ops[0].volume - blow_out_air_volume < 0
+        ):
+            raise RuntimeError(
+                f"排液量超过当前体积: "
+                f"{self._pipette_ctrl.current_volume - ops[0].volume - blow_out_air_volume} < 0"
+            )
 
-  async def pick_up_resource(self, pickup: ResourcePickup):
-    print(f"Picking up resource: {pickup}")
+        self._xyz.move_to_work_coord_safe(x=x, y=y, z=z, speed=200)
+        self._pipette_dispense(volume=ops[0].volume, flow_rate=flow_rate)
 
-  async def move_picked_up_resource(self, move: ResourceMove):
-    print(f"Moving picked up resource: {move}")
+        self._xyz.move_to_work_coord_safe(
+            z=self._xyz.machine_config.safe_z_height
+        )
+        if blow_out_air_volume > 0:
+            self._pipette_dispense(volume=blow_out_air_volume, flow_rate=flow_rate)
 
-  async def drop_resource(self, drop: ResourceDrop):
-    print(f"Dropping resource: {drop}")
+    # ------------------------------------------------------------------ 96-channel stubs
 
-  def can_pick_up_tip(self, channel_idx: int, tip: Tip) -> bool:
-    return True
-    
+    async def pick_up_tips96(self, pickup: PickupTipRack, **backend_kwargs):
+        logger.info(f"Picking up tips from {pickup.resource.name}.")
+
+    async def drop_tips96(self, drop: DropTipRack, **backend_kwargs):
+        logger.info(f"Dropping tips to {drop.resource.name}.")
+
+    async def aspirate96(
+        self, aspiration: Union[MultiHeadAspirationPlate, MultiHeadAspirationContainer]
+    ):
+        if isinstance(aspiration, MultiHeadAspirationPlate):
+            resource = aspiration.wells[0].parent
+        else:
+            resource = aspiration.container
+        logger.info(f"Aspirating {aspiration.volume} from {resource}.")
+
+    async def dispense96(
+        self, dispense: Union[MultiHeadDispensePlate, MultiHeadDispenseContainer]
+    ):
+        if isinstance(dispense, MultiHeadDispensePlate):
+            resource = dispense.wells[0].parent
+        else:
+            resource = dispense.container
+        logger.info(f"Dispensing {dispense.volume} to {resource}.")
+
+    async def pick_up_resource(self, pickup: ResourcePickup):
+        logger.info(f"Picking up resource: {pickup}")
+
+    async def move_picked_up_resource(self, move: ResourceMove):
+        logger.info(f"Moving picked up resource: {move}")
+
+    async def drop_resource(self, drop: ResourceDrop):
+        logger.info(f"Dropping resource: {drop}")
+
+    def can_pick_up_tip(self, channel_idx: int, tip: Tip) -> bool:
+        return True

unilabos/devices/liquid_handling/laiyu/controllers/pipette_controller.py

@@ -5,21 +5,16 @@
 封装SOPA移液器的高级控制功能
 """
 
-# 添加项目根目录到Python路径以解决模块导入问题
 import sys
 import os
-from tkinter import N
+
+_current_file = os.path.abspath(__file__)
+_project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(_current_file)))))
+if _project_root not in sys.path:
+    sys.path.insert(0, _project_root)
 
 from unilabos.devices.liquid_handling.laiyu.drivers.xyz_stepper_driver import ModbusException
 
-# 无论如何都添加项目根目录到路径
-current_file = os.path.abspath(__file__)
-# 从 .../Uni-Lab-OS/unilabos/devices/LaiYu_Liquid/controllers/pipette_controller.py
-# 向上5级到 .../Uni-Lab-OS
-project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(current_file)))))
-# 强制添加项目根目录到sys.path的开头
-sys.path.insert(0, project_root)
-
 import time
 import logging
 from typing import Optional, List, Dict, Tuple
@@ -153,7 +148,7 @@ class PipetteController:
                 logger.error("移液器连接失败")
                 return False
             logger.info("移液器连接成功")
-            
+
             # 连接XYZ步进电机控制器（如果提供了端口）
             if self.xyz_port != self.pipette_port:
                 try:
@@ -172,24 +167,62 @@ class PipetteController:
                 try:
                     self.xyz_controller = XYZController(self.xyz_port, auto_connect=False)
                     self.xyz_controller.serial_conn = self.pipette.serial_port
+                    self.xyz_controller.serial_lock = self.pipette.lock
                     self.xyz_controller.is_connected = True
+                    logger.info("XYZ控制器与移液器共享串口和互斥锁")
                 except Exception as e:
-                    logger.info("未配置XYZ步进电机端口，跳过运动控制器连接")
-            
+                    logger.warning(f"共享端口 XYZ 控制器创建失败: {e}")
+                    self.xyz_controller = None
+                    self.xyz_connected = False
+
             return True
         except Exception as e:
             logger.error(f"设备连接失败: {e}")
             return False
 
+    def connect_shared(self, serial_conn, serial_lock, xyz_controller: XYZController) -> bool:
+        """使用已连接的串口和XYZ控制器（路径 B 模式：XYZ 先开串口，移液器共享）
+
+        Args:
+            serial_conn: 已打开的串口连接（来自 XYZController）
+            serial_lock: 串口互斥锁（来自 XYZController）
+            xyz_controller: 已连接的 XYZController 实例
+        """
+        try:
+            self.pipette.serial_port = serial_conn
+            self.pipette.lock = serial_lock
+            self.pipette.is_connected = True
+
+            self.xyz_controller = xyz_controller
+            self.xyz_connected = True
+
+            logger.info("移液控制器已通过 connect_shared 共享 XYZ 串口")
+            return True
+        except Exception as e:
+            logger.error(f"connect_shared 失败: {e}")
+            return False
+
+    def disconnect_shared(self) -> None:
+        """释放共享串口引用（与 connect_shared 对称）。
+
+        注意：不关闭串口本身，串口由 XYZController 负责关闭。
+        """
+        try:
+            self.pipette.serial_port = None
+            self.pipette.lock = None
+            self.pipette.is_connected = False
+            self.xyz_controller = None
+            self.xyz_connected = False
+            logger.info("移液控制器已释放共享串口引用")
+        except Exception as e:
+            logger.error(f"disconnect_shared 失败: {e}")
+
     def initialize(self) -> bool:
         """初始化移液器"""
         try:
             if self.pipette.initialize():
                 logger.info("移液器初始化成功")
-                # 检查枪头状态
                 self._update_tip_status()
-                self.xyz_controller.home_all_axes()
-                self.xyz_controller.move_to_work_coord_safe(x=0, y=-150, z=0)
                 return True
             return False
         except Exception as e:
@@ -198,56 +231,58 @@ class PipetteController:
 
     def disconnect(self):
         """断开连接"""
-        # 断开移液器连接
+        if self.xyz_controller and self.xyz_connected:
+            if self.xyz_port != self.pipette_port:
+                try:
+                    self.xyz_controller.disconnect()
+                    logger.info("XYZ 步进电机已断开")
+                except Exception as e:
+                    logger.error(f"断开 XYZ 步进电机失败: {e}")
+            else:
+                self.xyz_controller.serial_conn = None
+            self.xyz_connected = False
+            self.xyz_controller = None
+
         self.pipette.disconnect()
         logger.info("移液器已断开")
-        
-        # 断开 XYZ 步进电机连接
-        if self.xyz_controller and self.xyz_connected:
-            try:
-                self.xyz_controller.disconnect()
-                self.xyz_connected = False
-                logger.info("XYZ 步进电机已断开")
-            except Exception as e:
-                logger.error(f"断开 XYZ 步进电机失败: {e}")
 
     def _check_xyz_safety(self, axis: MotorAxis, target_position: int) -> bool:
         """
         检查 XYZ 轴移动的安全性
-        
+
         Args:
             axis: 电机轴
             target_position: 目标位置(步数)
-            
+
         Returns:
             是否安全
         """
         try:
             # 获取当前电机状态
             motor_position = self.xyz_controller.get_motor_status(axis)
-            
+
             # 检查电机状态是否正常 (不是碰撞停止或限位停止)
-            if motor_position.status in [MotorStatus.COLLISION_STOP, 
-                                       MotorStatus.FORWARD_LIMIT_STOP, 
+            if motor_position.status in [MotorStatus.COLLISION_STOP,
+                                       MotorStatus.FORWARD_LIMIT_STOP,
                                        MotorStatus.REVERSE_LIMIT_STOP]:
                 logger.error(f"{axis.name} 轴电机处于错误状态: {motor_position.status.name}")
                 return False
-                
+
             # 检查位置限制 (扩大安全范围以适应实际硬件)
             # 步进电机的位置范围通常很大，这里设置更合理的范围
             if target_position < -500000 or target_position > 500000:
                 logger.error(f"{axis.name} 轴目标位置超出安全范围: {target_position}")
                 return False
-                
+
             # 检查移动距离是否过大 (单次移动不超过 20000 步，约12mm)
             current_position = motor_position.steps
             move_distance = abs(target_position - current_position)
             if move_distance > 20000:
                 logger.error(f"{axis.name} 轴单次移动距离过大: {move_distance}步")
                 return False
-                
+
             return True
-            
+
         except Exception as e:
             logger.error(f"安全检查失败: {e}")
             return False
@@ -255,48 +290,48 @@ class PipetteController:
     def move_z_relative(self, distance_mm: float, speed: int = 2000, acceleration: int = 500) -> bool:
         """
         Z轴相对移动
-        
+
         Args:
             distance_mm: 移动距离(mm)，正值向下，负值向上
             speed: 移动速度(rpm)
             acceleration: 加速度(rpm/s)
-            
+
         Returns:
             移动是否成功
         """
         if not self.xyz_controller or not self.xyz_connected:
             logger.error("XYZ 步进电机未连接，无法执行移动")
             return False
-            
+
         try:
             # 参数验证
             if abs(distance_mm) > 15.0:
                 logger.error(f"移动距离过大: {distance_mm}mm，最大允许15mm")
                 return False
-                
+
             if speed < 100 or speed > 5000:
                 logger.error(f"速度参数无效: {speed}rpm，范围应为100-5000")
                 return False
-                
+
             # 获取当前 Z 轴位置
             current_status = self.xyz_controller.get_motor_status(MotorAxis.Z)
             current_z_position = current_status.steps
-            
+
             # 计算移动距离对应的步数 (1mm = 1638.4步)
             mm_to_steps = 1638.4
             move_distance_steps = int(distance_mm * mm_to_steps)
-            
+
             # 计算目标位置
             target_z_position = current_z_position + move_distance_steps
-            
+
             # 安全检查
             if not self._check_xyz_safety(MotorAxis.Z, target_z_position):
                 logger.error("Z轴移动安全检查失败")
                 return False
-            
+
             logger.info(f"Z轴相对移动: {distance_mm}mm ({move_distance_steps}步)")
             logger.info(f"当前位置: {current_z_position}步 -> 目标位置: {target_z_position}步")
-            
+
             # 执行移动
             success = self.xyz_controller.move_to_position(
                 axis=MotorAxis.Z,
@@ -305,28 +340,28 @@ class PipetteController:
                 acceleration=acceleration,
                 precision=50
             )
-            
+
             if not success:
                 logger.error("Z轴移动命令发送失败")
                 return False
-                
+
             # 等待移动完成
             if not self.xyz_controller.wait_for_completion(MotorAxis.Z, timeout=10.0):
                 logger.error("Z轴移动超时")
                 return False
-                
+
             # 验证移动结果
             final_status = self.xyz_controller.get_motor_status(MotorAxis.Z)
             final_position = final_status.steps
             position_error = abs(final_position - target_z_position)
-            
+
             logger.info(f"Z轴移动完成，最终位置: {final_position}步，误差: {position_error}步")
-            
+
             if position_error > 100:
                 logger.warning(f"Z轴位置误差较大: {position_error}步")
-                
+
             return True
-            
+
         except ModbusException as e:
             logger.error(f"Modbus通信错误: {e}")
             return False
@@ -337,21 +372,20 @@ class PipetteController:
     def emergency_stop(self) -> bool:
         """
         紧急停止所有运动
-        
+
         Returns:
             停止是否成功
         """
         success = True
-        
-        # 停止移液器操作
+
         try:
-            if self.pipette and self.connected:
-                # 这里可以添加移液器的紧急停止逻辑
+            if self.pipette and self.pipette.is_connected:
+                self.pipette.emergency_stop()
                 logger.info("移液器紧急停止")
         except Exception as e:
             logger.error(f"移液器紧急停止失败: {e}")
             success = False
-            
+
         # 停止 XYZ 轴运动
         try:
             if self.xyz_controller and self.xyz_connected:
@@ -360,7 +394,7 @@ class PipetteController:
         except Exception as e:
             logger.error(f"XYZ 轴紧急停止失败: {e}")
             success = False
-            
+
         return success
 
     def pickup_tip(self) -> bool:
@@ -376,7 +410,7 @@ class PipetteController:
             return True
 
         logger.info("开始装载枪头 - Z轴向下移动10mm")
-        
+
         # 使用相对移动方法，向下移动10mm
         if self.move_z_relative(distance_mm=10.0, speed=2000, acceleration=500):
             # 更新枪头状态
@@ -688,31 +722,31 @@ class PipetteController:
 if __name__ == "__main__":
     # 配置日志
     import logging
-    
+
     # 设置日志级别
     logging.basicConfig(
         level=logging.INFO,
         format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
     )
-    
+
     def interactive_test():
         """交互式测试模式 - 适用于已连接的设备"""
         print("\n" + "=" * 60)
         print("🧪 移液器交互式测试模式")
         print("=" * 60)
-        
+
         # 获取用户输入的连接参数
         print("\n📡 设备连接配置:")
         port = input("请输入移液器串口端口 (默认: /dev/ttyUSB_CH340): ").strip() or "/dev/ttyUSB_CH340"
         address_input = input("请输入移液器设备地址 (默认: 4): ").strip()
         address = int(address_input) if address_input else 4
-        
+
         # 询问是否连接 XYZ 步进电机控制器
         xyz_enable = input("是否连接 XYZ 步进电机控制器? (y/N): ").strip().lower()
         xyz_port = None
         if xyz_enable not in ['n', 'no']:
             xyz_port = input("请输入 XYZ 控制器串口端口 (默认: /dev/ttyUSB_CH340): ").strip() or "/dev/ttyUSB_CH340"
-        
+
         try:
             # 创建移液控制器实例
             if xyz_port:
@@ -721,21 +755,21 @@ if __name__ == "__main__":
             else:
                 print(f"\n🔧 创建移液控制器实例 (端口: {port}, 地址: {address})...")
                 pipette = PipetteController(port=port, address=address)
-            
+
             # 连接设备
             print("\n📞 连接移液器设备...")
             if not pipette.connect():
                 print("❌ 设备连接失败，请检查连接")
                 return
             print("✅ 设备连接成功")
-            
+
             # 初始化设备
             print("\n🚀 初始化设备...")
             if not pipette.initialize():
                 print("❌ 设备初始化失败")
                 return
             print("✅ 设备初始化成功")
-            
+
             # 交互式菜单
             while True:
                 print("\n" + "=" * 50)
@@ -755,9 +789,9 @@ if __name__ == "__main__":
                 print("99. 🚨 紧急停止")
                 print("0. 🚪 退出程序")
                 print("=" * 50)
-                
+
                 choice = input("\n请选择操作 (0-12, 99): ").strip()
-                
+
                 if choice == "0":
                     print("\n👋 退出程序...")
                     break
@@ -773,7 +807,7 @@ if __name__ == "__main__":
                     # print(f"    🔧 枪头使用次数: {status['statistics']['tip_count']}")
                     print(f"    ⬆️  吸液次数: {status['statistics']['aspirate_count']}")
                     print(f"    ⬇️  排液次数: {status['statistics']['dispense_count']}")
-                
+
                 elif choice == "2":
                     # 装载枪头
                     print("\n🔧 装载枪头...")
@@ -781,14 +815,14 @@ if __name__ == "__main__":
                         print("📍 使用 XYZ 控制器进行 Z 轴定位 (下移 10mm)")
                     else:
                         print("⚠️  未连接 XYZ 控制器，仅执行移液器枪头装载")
-                    
+
                     if pipette.pickup_tip():
                         print("✅ 枪头装载成功")
                         if pipette.xyz_connected:
                             print("📍 Z 轴已移动到装载位置")
                     else:
                         print("❌ 枪头装载失败")
-                
+
                 elif choice == "3":
                     # 弹出枪头
                     print("\n🗑️ 弹出枪头...")
@@ -796,7 +830,7 @@ if __name__ == "__main__":
                         print("✅ 枪头弹出成功")
                     else:
                         print("❌ 枪头弹出失败")
-                
+
                 elif choice == "4":
                     # 吸液操作
                     try:
@@ -810,7 +844,7 @@ if __name__ == "__main__":
                             print("❌ 吸液失败")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "5":
                     # 排液操作
                     try:
@@ -824,7 +858,7 @@ if __name__ == "__main__":
                             print("❌ 排液失败")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "6":
                     # 混合操作
                     try:
@@ -838,7 +872,7 @@ if __name__ == "__main__":
                             print("❌ 混合失败")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "7":
                     # 液体转移
                     try:
@@ -846,7 +880,7 @@ if __name__ == "__main__":
                         source = input("源孔位 (可选, 如A1): ").strip() or None
                         dest = input("目标孔位 (可选, 如B1): ").strip() or None
                         new_tip = input("是否使用新枪头? (y/n, 默认y): ").strip().lower() != 'n'
-                        
+
                         print(f"\n🔄 执行液体转移 ({volume}ul)...")
                         if pipette.transfer(volume=volume, source_well=source, dest_well=dest, new_tip=new_tip):
                             print("✅ 液体转移完成")
@@ -854,7 +888,7 @@ if __name__ == "__main__":
                             print("❌ 液体转移失败")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "8":
                     # 设置液体类型
                     print("\n🧪 可用液体类型:")
@@ -864,16 +898,16 @@ if __name__ == "__main__":
                         "3": (LiquidClass.VISCOUS, "粘稠液体"),
                         "4": (LiquidClass.VOLATILE, "挥发性液体")
                     }
-                    
+
                     for key, (liquid_class, description) in liquid_options.items():
                         print(f"  {key}. {description}")
-                    
+
                     liquid_choice = input("请选择液体类型 (1-4): ").strip()
                     if liquid_choice in liquid_options:
                         liquid_class, description = liquid_options[liquid_choice]
                         pipette.set_liquid_class(liquid_class)
                         print(f"✅ 液体类型设置为: {description}")
-                        
+
                         # 显示参数
                         params = pipette.liquid_params
                         print(f"📋 参数设置:")
@@ -883,7 +917,7 @@ if __name__ == "__main__":
                         print(f"  💧 预润湿: {'是' if params.pre_wet else '否'}")
                     else:
                         print("❌ 无效选择")
-                
+
                 elif choice == "9":
                     # 自定义参数
                     try:
@@ -892,19 +926,19 @@ if __name__ == "__main__":
                         dispense_speed = input("排液速度 (默认800): ").strip()
                         air_gap = input("空气间隙 (ul, 默认10.0): ").strip()
                         pre_wet = input("预润湿 (y/n, 默认n): ").strip().lower() == 'y'
-                        
+
                         custom_params = LiquidParameters(
                             aspirate_speed=int(aspirate_speed) if aspirate_speed else 500,
                             dispense_speed=int(dispense_speed) if dispense_speed else 800,
                             air_gap=float(air_gap) if air_gap else 10.0,
                             pre_wet=pre_wet
                         )
-                        
+
                         pipette.set_custom_parameters(custom_params)
                         print("✅ 自定义参数设置完成")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "10":
                     # 校准体积
                     try:
@@ -914,12 +948,12 @@ if __name__ == "__main__":
                         print(f"✅ 校准完成，校准系数: {actual/expected:.3f}")
                     except ValueError:
                         print("❌ 请输入有效的数字")
-                
+
                 elif choice == "11":
                     # 重置统计
                     pipette.reset_statistics()
                     print("✅ 统计信息已重置")
-                
+
                 elif choice == "12":
                     # 液体类型测试
                     print("\n🧪 液体类型参数对比:")
@@ -929,7 +963,7 @@ if __name__ == "__main__":
                         (LiquidClass.VISCOUS, "粘稠液体"),
                         (LiquidClass.VOLATILE, "挥发性液体")
                     ]
-                    
+
                     for liquid_class, description in liquid_tests:
                         params = pipette.LIQUID_PARAMS[liquid_class]
                         print(f"\n📋 {description} ({liquid_class.value}):")
@@ -938,7 +972,7 @@ if __name__ == "__main__":
                         print(f"  💨 空气间隙: {params.air_gap}ul")
                         print(f"  💧 预润湿: {'是' if params.pre_wet else '否'}")
                         print(f"  ⏱️ 吸液后延时: {params.delay_after_aspirate}s")
-                
+
                 elif choice == "99":
                     # 紧急停止
                     print("\n🚨 执行紧急停止...")
@@ -949,19 +983,19 @@ if __name__ == "__main__":
                     else:
                         print("❌ 紧急停止执行失败")
                         print("⚠️ 请手动检查设备状态并采取必要措施")
-                    
+
                     # 紧急停止后询问是否继续
                     continue_choice = input("\n是否继续操作？(y/n): ").strip().lower()
                     if continue_choice != 'y':
                         print("🚪 退出程序")
                         break
-                
+
                 else:
                     print("❌ 无效选择，请重新输入")
-                
+
                 # 等待用户确认继续
                 input("\n按回车键继续...")
-            
+
         except KeyboardInterrupt:
             print("\n\n⚠️ 用户中断操作")
         except Exception as e:
@@ -974,19 +1008,19 @@ if __name__ == "__main__":
                 print("✅ 连接已断开")
             except:
                 print("⚠️ 断开连接时出现问题")
-    
+
     def demo_test():
         """演示测试模式 - 完整功能演示"""
         print("\n" + "=" * 60)
         print("🎬 移液控制器演示测试")
         print("=" * 60)
-        
+
         try:
             # 创建移液控制器实例
             print("1. 🔧 创建移液控制器实例...")
             pipette = PipetteController(port="/dev/ttyUSB0", address=4)
             print("✅ 移液控制器实例创建成功")
-            
+
             # 连接设备
             print("\n2. 📞 连接移液器设备...")
             if pipette.connect():
@@ -994,7 +1028,7 @@ if __name__ == "__main__":
             else:
                 print("❌ 设备连接失败")
                 return False
-            
+
             # 初始化设备
             print("\n3. 🚀 初始化设备...")
             if pipette.initialize():
@@ -1002,19 +1036,19 @@ if __name__ == "__main__":
             else:
                 print("❌ 设备初始化失败")
                 return False
-            
+
             # 装载枪头
             print("\n4. 🔧 装载枪头...")
             if pipette.pickup_tip():
                 print("✅ 枪头装载成功")
             else:
                 print("❌ 枪头装载失败")
-            
+
             # 设置液体类型
             print("\n5. 🧪 设置液体类型为血清...")
             pipette.set_liquid_class(LiquidClass.SERUM)
             print("✅ 液体类型设置完成")
-            
+
             # 吸液操作
             print("\n6. 💧 执行吸液操作...")
             volume_to_aspirate = 100.0
@@ -1023,7 +1057,7 @@ if __name__ == "__main__":
                 print(f"📊 当前体积: {pipette.current_volume}ul")
             else:
                 print("❌ 吸液失败")
-            
+
             # 排液操作
             print("\n7. 💦 执行排液操作...")
             volume_to_dispense = 50.0
@@ -1032,14 +1066,14 @@ if __name__ == "__main__":
                 print(f"📊 剩余体积: {pipette.current_volume}ul")
             else:
                 print("❌ 排液失败")
-            
+
             # 混合操作
             print("\n8. 🌀 执行混合操作...")
             if pipette.mix(cycles=3, volume=30.0):
                 print("✅ 混合完成")
             else:
                 print("❌ 混合失败")
-            
+
             # 获取状态信息
             print("\n9. 📊 获取设备状态...")
             status = pipette.get_status()
@@ -1052,30 +1086,30 @@ if __name__ == "__main__":
             # print(f"    🔧 枪头使用次数: {status['statistics']['tip_count']}")
             print(f"    ⬆️ 吸液次数: {status['statistics']['aspirate_count']}")
             print(f"    ⬇️ 排液次数: {status['statistics']['dispense_count']}")
-            
+
             # 弹出枪头
             print("\n10. 🗑️ 弹出枪头...")
             if pipette.eject_tip():
                 print("✅ 枪头弹出成功")
             else:
                 print("❌ 枪头弹出失败")
-            
+
             print("\n" + "=" * 60)
             print("✅ 移液控制器演示测试完成")
             print("=" * 60)
-            
+
             return True
-            
+
         except Exception as e:
             print(f"\n❌ 测试过程中发生异常: {e}")
             return False
-            
+
         finally:
             # 断开连接
             print("\n📞 断开连接...")
             pipette.disconnect()
             print("✅ 连接已断开")
-    
+
     # 主程序入口
     print("🧪 移液器控制器测试程序")
     print("=" * 40)
@@ -1083,9 +1117,9 @@ if __name__ == "__main__":
     print("2. 🎬 演示测试")
     print("0. 🚪 退出")
     print("=" * 40)
-    
+
     mode = input("请选择测试模式 (0-2): ").strip()
-    
+
     if mode == "1":
         interactive_test()
     elif mode == "2":
@@ -1094,7 +1128,7 @@ if __name__ == "__main__":
         print("👋 再见！")
     else:
         print("❌ 无效选择")
-    
+
     print("\n🎉 程序结束！")
     print("\n💡 使用说明:")
     print("1. 确保移液器硬件已正确连接")

unilabos/devices/liquid_handling/laiyu/laiyu.py

@@ -13,7 +13,7 @@ from pylabrobot.liquid_handling import (
     SingleChannelDispense,
     PickupTipRack,
     DropTipRack,
-    MultiHeadAspirationPlate, ChatterBoxBackend, LiquidHandlerChatterboxBackend,
+    MultiHeadAspirationPlate,
 )
 from pylabrobot.liquid_handling.standard import (
     MultiHeadAspirationContainer,
@@ -41,12 +41,6 @@ class TransformXYZDeck(Deck):
         super().__init__(name, size_x, size_y, size_z)
         self.name = name
 
-class TransformXYZBackend(LiquidHandlerBackend):
-    def __init__(self, name: str, host: str, port: int, timeout: float):
-        super().__init__()
-        self.host = host
-        self.port = port
-        self.timeout = timeout
 
 class TransformXYZRvizBackend(UniLiquidHandlerRvizBackend):
     def __init__(self, name: str, channel_num: int):
@@ -86,7 +80,9 @@ class TransformXYZContainer(Plate, TipRack):
 class TransformXYZHandler(LiquidHandlerAbstract):
     support_touch_tip = False
 
-    def __init__(self, deck: Deck, host: str = "127.0.0.1", port: int = 9999, timeout: float = 10.0, channel_num=1, simulator=True, **backend_kwargs):
+    def __init__(self, deck: Deck, host: str = "127.0.0.1", port: int = 9999, timeout: float = 10.0, channel_num=1, simulator=True,
+                 serial_port: str = "/dev/ttyUSB0", baudrate: int = 115200, pipette_address: int = 4,
+                 total_height: float = 310, **backend_kwargs):
         # Handle case where deck is passed as a dict (from serialization)
         if isinstance(deck, dict):
             # Try to create a TransformXYZDeck from the dict
@@ -102,11 +98,22 @@ class TransformXYZHandler(LiquidHandlerAbstract):
                 deck = TransformXYZDeck(name='deck', size_x=100, size_y=100, size_z=100)
 
         if simulator:
-            self._unilabos_backend = TransformXYZRvizBackend(name="laiyu",channel_num=channel_num)
+            self._unilabos_backend = TransformXYZRvizBackend(name="laiyu", channel_num=channel_num)
         else:
-            self._unilabos_backend = TransformXYZBackend(name="laiyu",host=host, port=port, timeout=timeout)
+            self._unilabos_backend = UniLiquidHandlerLaiyuBackend(
+                num_channels=channel_num,
+                total_height=total_height,
+                port=serial_port,
+                baudrate=baudrate,
+                pipette_address=pipette_address,
+            )
         super().__init__(backend=self._unilabos_backend, deck=deck, simulator=simulator, channel_num=channel_num)
 
+    def post_init(self, ros_node):
+        super().post_init(ros_node)
+        if hasattr(self._unilabos_backend, 'post_init'):
+            self._unilabos_backend.post_init(ros_node)
+
     async def add_liquid(
         self,
         asp_vols: Union[List[float], float],
@@ -128,7 +135,25 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         mix_liquid_height: Optional[float] = None,
         none_keys: List[str] = [],
     ):
-        pass
+        return await super().add_liquid(
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,
+            reagent_sources=reagent_sources,
+            targets=targets,
+            use_channels=use_channels,
+            flow_rates=flow_rates,
+            offsets=offsets,
+            liquid_height=liquid_height,
+            blow_out_air_volume=blow_out_air_volume,
+            spread=spread,
+            is_96_well=is_96_well,
+            delays=delays,
+            mix_time=mix_time,
+            mix_vol=mix_vol,
+            mix_rate=mix_rate,
+            mix_liquid_height=mix_liquid_height,
+            none_keys=none_keys,
+        )
 
     async def aspirate(
         self,
@@ -142,7 +167,17 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         spread: Literal["wide", "tight", "custom"] = "wide",
         **backend_kwargs,
     ):
-        pass
+        return await super().aspirate(
+            resources=resources,
+            vols=vols,
+            use_channels=use_channels,
+            flow_rates=flow_rates,
+            offsets=offsets,
+            liquid_height=liquid_height,
+            blow_out_air_volume=blow_out_air_volume,
+            spread=spread,
+            **backend_kwargs,
+        )
 
     async def dispense(
         self,
@@ -156,7 +191,17 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         spread: Literal["wide", "tight", "custom"] = "wide",
         **backend_kwargs,
     ):
-        pass
+        return await super().dispense(
+            resources=resources,
+            vols=vols,
+            use_channels=use_channels,
+            flow_rates=flow_rates,
+            offsets=offsets,
+            liquid_height=liquid_height,
+            blow_out_air_volume=blow_out_air_volume,
+            spread=spread,
+            **backend_kwargs,
+        )
 
     async def drop_tips(
         self,
@@ -166,7 +211,13 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         allow_nonzero_volume: bool = False,
         **backend_kwargs,
     ):
-        pass
+        return await super().drop_tips(
+            tip_spots=tip_spots,
+            use_channels=use_channels,
+            offsets=offsets,
+            allow_nonzero_volume=allow_nonzero_volume,
+            **backend_kwargs,
+        )
 
     async def mix(
         self,
@@ -178,7 +229,15 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         mix_rate: Optional[float] = None,
         none_keys: List[str] = [],
     ):
-        pass
+        return await super().mix(
+            targets=targets,
+            mix_time=mix_time,
+            mix_vol=mix_vol,
+            height_to_bottom=height_to_bottom,
+            offsets=offsets,
+            mix_rate=mix_rate,
+            none_keys=none_keys,
+        )
 
     async def pick_up_tips(
         self,
@@ -187,7 +246,12 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         offsets: Optional[List[Coordinate]] = None,
         **backend_kwargs,
     ):
-        pass
+        return await super().pick_up_tips(
+            tip_spots=tip_spots,
+            use_channels=use_channels,
+            offsets=offsets,
+            **backend_kwargs,
+        )
 
     async def transfer_liquid(
         self,
@@ -214,5 +278,26 @@ class TransformXYZHandler(LiquidHandlerAbstract):
         delays: Optional[List[int]] = None,
         none_keys: List[str] = [],
     ):
-        pass
-    
+        return await super().transfer_liquid(
+            sources=sources,
+            targets=targets,
+            tip_racks=tip_racks,
+            use_channels=use_channels,
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,
+            asp_flow_rates=asp_flow_rates,
+            dis_flow_rates=dis_flow_rates,
+            offsets=offsets,
+            touch_tip=touch_tip,
+            liquid_height=liquid_height,
+            blow_out_air_volume=blow_out_air_volume,
+            spread=spread,
+            is_96_well=is_96_well,
+            mix_stage=mix_stage,
+            mix_times=mix_times,
+            mix_vol=mix_vol,
+            mix_rate=mix_rate,
+            mix_liquid_height=mix_liquid_height,
+            delays=delays,
+            none_keys=none_keys,
+        )

unilabos/devices/liquid_handling/prcxi/prcxi_modules.py

@@ -1,150 +0,0 @@
-from typing import Any, Dict, Optional
-
-from .prcxi import PRCXI9300ModuleSite
-
-
-class PRCXI9300FunctionalModule(PRCXI9300ModuleSite):
-    """
-    PRCXI 9300 功能模块基类（加热/冷却/震荡/加热震荡/磁吸等）。
-
-    设计目标：
-    - 作为一个可以在工作台上拖拽摆放的实体资源（继承自 PRCXI9300ModuleSite -> ItemizedCarrier）。
-    - 顶面存在一个站点（site），可吸附标准板类资源（plate / tip_rack / tube_rack 等）。
-    - 支持注入 `material_info` (UUID 等)，并且在 serialize_state 时做安全过滤。
-    """
-
-    def __init__(
-        self,
-        name: str,
-        size_x: float,
-        size_y: float,
-        size_z: float,
-        module_type: Optional[str] = None,
-        category: str = "module",
-        model: Optional[str] = None,
-        material_info: Optional[Dict[str, Any]] = None,
-        **kwargs: Any,
-    ):
-        super().__init__(
-            name=name,
-            size_x=size_x,
-            size_y=size_y,
-            size_z=size_z,
-            material_info=material_info,
-            model=model,
-            category=category,
-            **kwargs,
-        )
-
-        # 记录模块类型（加热 / 冷却 / 震荡 / 加热震荡 / 磁吸）
-        self.module_type = module_type or "generic"
-
-        # 与 PRCXI9300PlateAdapter 一致，使用 _unilabos_state 保存扩展信息
-        if not hasattr(self, "_unilabos_state") or self._unilabos_state is None:
-            self._unilabos_state = {}
-
-        # super().__init__ 已经在有 material_info 时写入 "Material"，这里仅确保存在
-        if material_info is not None and "Material" not in self._unilabos_state:
-            self._unilabos_state["Material"] = material_info
-
-        # 额外标记 category 和模块类型，便于前端或上层逻辑区分
-        self._unilabos_state.setdefault("category", category)
-        self._unilabos_state["module_type"] = module_type
-
-
-# ============================================================================
-# 具体功能模块定义
-# 这里的尺寸和 material_info 目前为占位参数，后续可根据实际测量/JSON 配置进行更新。
-# 顶面站点尺寸与模块外形一致，保证可以吸附标准 96 板/储液槽等。
-# ============================================================================
-
-
-def PRCXI_Heating_Module(name: str) -> PRCXI9300FunctionalModule:
-    """加热模块（顶面可吸附标准板）。"""
-    return PRCXI9300FunctionalModule(
-        name=name,
-        size_x=127.76,
-        size_y=85.48,
-        size_z=40.0,
-        module_type="heating",
-        model="PRCXI_Heating_Module",
-        material_info={
-            "uuid": "TODO-HEATING-MODULE-UUID",
-            "Code": "HEAT-MOD",
-            "Name": "PRCXI 加热模块",
-            "SupplyType": 3,
-        },
-    )
-
-
-def PRCXI_MetalCooling_Module(name: str) -> PRCXI9300FunctionalModule:
-    """金属冷却模块（顶面可吸附标准板）。"""
-    return PRCXI9300FunctionalModule(
-        name=name,
-        size_x=127.76,
-        size_y=85.48,
-        size_z=40.0,
-        module_type="metal_cooling",
-        model="PRCXI_MetalCooling_Module",
-        material_info={
-            "uuid": "TODO-METAL-COOLING-MODULE-UUID",
-            "Code": "METAL-COOL-MOD",
-            "Name": "PRCXI 金属冷却模块",
-            "SupplyType": 3,
-        },
-    )
-
-
-def PRCXI_Shaking_Module(name: str) -> PRCXI9300FunctionalModule:
-    """震荡模块（顶面可吸附标准板）。"""
-    return PRCXI9300FunctionalModule(
-        name=name,
-        size_x=127.76,
-        size_y=85.48,
-        size_z=50.0,
-        module_type="shaking",
-        model="PRCXI_Shaking_Module",
-        material_info={
-            "uuid": "TODO-SHAKING-MODULE-UUID",
-            "Code": "SHAKE-MOD",
-            "Name": "PRCXI 震荡模块",
-            "SupplyType": 3,
-        },
-    )
-
-
-def PRCXI_Heating_Shaking_Module(name: str) -> PRCXI9300FunctionalModule:
-    """加热震荡模块（顶面可吸附标准板）。"""
-    return PRCXI9300FunctionalModule(
-        name=name,
-        size_x=127.76,
-        size_y=85.48,
-        size_z=55.0,
-        module_type="heating_shaking",
-        model="PRCXI_Heating_Shaking_Module",
-        material_info={
-            "uuid": "TODO-HEATING-SHAKING-MODULE-UUID",
-            "Code": "HEAT-SHAKE-MOD",
-            "Name": "PRCXI 加热震荡模块",
-            "SupplyType": 3,
-        },
-    )
-
-
-def PRCXI_Magnetic_Module(name: str) -> PRCXI9300FunctionalModule:
-    """磁吸模块（顶面可吸附标准板）。"""
-    return PRCXI9300FunctionalModule(
-        name=name,
-        size_x=127.76,
-        size_y=85.48,
-        size_z=30.0,
-        module_type="magnetic",
-        model="PRCXI_Magnetic_Module",
-        material_info={
-            "uuid": "TODO-MAGNETIC-MODULE-UUID",
-            "Code": "MAG-MOD",
-            "Name": "PRCXI 磁吸模块",
-            "SupplyType": 3,
-        },
-    )
-

unilabos/devices/liquid_handling/rviz_backend.py

@@ -59,7 +59,6 @@ class UniLiquidHandlerRvizBackend(LiquidHandlerBackend):
     self.total_height = total_height
     self.joint_config = kwargs.get("joint_config", None)
     self.lh_device_id = kwargs.get("lh_device_id", "lh_joint_publisher")
-    self.simulate_rviz = kwargs.get("simulate_rviz", False)
     if not rclpy.ok():
         rclpy.init()
     self.joint_state_publisher = None
@@ -70,7 +69,7 @@ class UniLiquidHandlerRvizBackend(LiquidHandlerBackend):
     self.joint_state_publisher = LiquidHandlerJointPublisher(
                                 joint_config=self.joint_config,
                                 lh_device_id=self.lh_device_id,
-                                simulate_rviz=self.simulate_rviz)
+                                simulate_rviz=True)
 
     # 启动ROS executor
     self.executor = rclpy.executors.MultiThreadedExecutor()

unilabos/devices/motor/ZDT_X42.py

@@ -0,0 +1,376 @@
+# -*- coding: utf-8 -*-
+"""
+ZDT X42 Closed-Loop Stepper Motor Driver
+RS485 Serial Communication via USB-Serial Converter
+
+- Baudrate: 115200
+"""
+
+import serial
+import time
+import threading
+import struct
+import logging
+from typing import Optional, Any
+
+try:
+    from unilabos.device_comms.universal_driver import UniversalDriver
+except ImportError:
+    class UniversalDriver:
+        def __init__(self, *args, **kwargs):
+            self.logger = logging.getLogger(self.__class__.__name__)
+        def execute_command_from_outer(self, command: Any): pass
+
+from serial.rs485 import RS485Settings
+
+
+class ZDTX42Driver(UniversalDriver):
+    """
+    ZDT X42 闭环步进电机驱动器
+
+    支持功能:
+    - 速度模式运行
+    - 位置模式运行 (相对/绝对)
+    - 位置读取和清零
+    - 使能/禁用控制
+
+    通信协议:
+    - 帧格式: [设备ID] [功能码] [数据...] [校验位=0x6B]
+    - 响应长度根据功能码决定
+    """
+
+    def __init__(
+        self,
+        port: str,
+        baudrate: int = 115200,
+        device_id: int = 1,
+        timeout: float = 0.5,
+        debug: bool = False
+    ):
+        """
+        初始化 ZDT X42 电机驱动
+
+        Args:
+            port: 串口设备路径
+            baudrate: 波特率 (默认 115200)
+            device_id: 设备地址 (1-255)
+            timeout: 通信超时时间(秒)
+            debug: 是否启用调试输出
+        """
+        super().__init__()
+        self.id = device_id
+        self.debug = debug
+        self.lock = threading.RLock()
+        self.status = "idle"         # 对应注册表中的 status (str)
+        self.position = 0             # 对应注册表中的 position (int)
+
+        try:
+            self.ser = serial.Serial(
+                port=port,
+                baudrate=baudrate,
+                timeout=timeout,
+                bytesize=serial.EIGHTBITS,
+                parity=serial.PARITY_NONE,
+                stopbits=serial.STOPBITS_ONE
+            )
+
+            # 启用 RS485 模式
+            try:
+                self.ser.rs485_mode = RS485Settings(
+                    rts_level_for_tx=True,
+                    rts_level_for_rx=False
+                )
+            except Exception:
+                pass  # RS485 模式是可选的
+
+            self.logger.info(
+                f"ZDT X42 Motor connected: {port} "
+                f"(Baud: {baudrate}, ID: {device_id})"
+            )
+            # 自动使能电机，确保初始状态可运动
+            self.enable(True)
+
+            # 启动背景轮询线程，确保 position 实时刷新
+            self._stop_event = threading.Event()
+            self._polling_thread = threading.Thread(
+                target=self._update_loop,
+                name=f"ZDTPolling_{port}",
+                daemon=True
+            )
+            self._polling_thread.start()
+        except Exception as e:
+            self.logger.error(f"Failed to open serial port {port}: {e}")
+            self.ser = None
+
+    def _update_loop(self):
+        """背景循环读取电机位置"""
+        while not self._stop_event.is_set():
+            try:
+                self.get_position()
+            except Exception as e:
+                if self.debug:
+                    self.logger.error(f"Polling error: {e}")
+            time.sleep(1.0) # 每1秒刷新一次位置数据
+
+    def _send(self, func_code: int, payload: list) -> bytes:
+        """
+        发送指令并接收响应
+
+        Args:
+            func_code: 功能码
+            payload: 数据负载 (list of bytes)
+
+        Returns:
+            响应数据 (bytes)
+        """
+        if not self.ser:
+            self.logger.error("Serial port not available")
+            return b""
+
+        with self.lock:
+            # 清空输入缓冲区
+            self.ser.reset_input_buffer()
+
+            # 构建消息: [ID] [功能码] [数据...] [校验位=0x6B]
+            message = bytes([self.id, func_code] + payload + [0x6B])
+
+            # 发送
+            self.ser.write(message)
+
+            # 根据功能码决定响应长度
+            # 查询类指令返回 10 字节，控制类指令返回 4 字节
+            read_len = 10 if func_code in [0x31, 0x32, 0x35, 0x24, 0x27] else 4
+            response = self.ser.read(read_len)
+
+            # 调试输出
+            if self.debug:
+                sent_hex = message.hex().upper()
+                recv_hex = response.hex().upper() if response else 'TIMEOUT'
+                print(f"[ID {self.id}] TX: {sent_hex} → RX: {recv_hex}")
+
+            return response
+
+    def enable(self, on: bool = True) -> bool:
+        """
+        使能/禁用电机
+
+        Args:
+            on: True=使能(锁轴), False=禁用(松轴)
+
+        Returns:
+            是否成功
+        """
+        state = 1 if on else 0
+        resp = self._send(0xF3, [0xAB, state, 0])
+        return len(resp) >= 4
+
+    def move_speed(
+        self,
+        speed_rpm: int,
+        direction: str = "CW",
+        acceleration: int = 10
+    ) -> bool:
+        """
+        速度模式运行
+
+        Args:
+            speed_rpm: 转速 (RPM)
+            direction: 方向 ("CW"=顺时针, "CCW"=逆时针)
+            acceleration: 加速度 (0-255)
+
+        Returns:
+            是否成功
+        """
+        dir_val = 0 if direction.upper() in ["CW", "顺时针"] else 1
+        speed_bytes = struct.pack('>H', int(speed_rpm))
+        self.status = f"moving@{speed_rpm}rpm"
+        resp = self._send(0xF6, [dir_val, speed_bytes[0], speed_bytes[1], acceleration, 0])
+        return len(resp) >= 4
+
+    def move_position(
+        self,
+        pulses: int,
+        speed_rpm: int,
+        direction: str = "CW",
+        acceleration: int = 10,
+        absolute: bool = False
+    ) -> bool:
+        """
+        位置模式运行
+
+        Args:
+            pulses: 脉冲数
+            speed_rpm: 转速 (RPM)
+            direction: 方向 ("CW"=顺时针, "CCW"=逆时针)
+            acceleration: 加速度 (0-255)
+            absolute: True=绝对位置, False=相对位置
+
+        Returns:
+            是否成功
+        """
+        dir_val = 0 if direction.upper() in ["CW", "顺时针"] else 1
+        speed_bytes = struct.pack('>H', int(speed_rpm))
+        self.status = f"moving_to_{pulses}"
+        pulse_bytes = struct.pack('>I', int(pulses))
+        abs_flag = 1 if absolute else 0
+
+        payload = [
+            dir_val,
+            speed_bytes[0], speed_bytes[1],
+            acceleration,
+            pulse_bytes[0], pulse_bytes[1], pulse_bytes[2], pulse_bytes[3],
+            abs_flag,
+            0
+        ]
+
+        resp = self._send(0xFD, payload)
+        return len(resp) >= 4
+
+    def stop(self) -> bool:
+        """
+        停止电机
+
+        Returns:
+            是否成功
+        """
+        self.status = "idle"
+        resp = self._send(0xFE, [0x98, 0])
+        return len(resp) >= 4
+
+    def rotate_quarter(self, speed_rpm: int = 60, direction: str = "CW") -> bool:
+        """
+        电机旋转 1/4 圈 (阻塞式)
+        假设电机细分为 3200 脉冲/圈，1/4 圈 = 800 脉冲
+        """
+        pulses = 800
+        success = self.move_position(pulses=pulses, speed_rpm=speed_rpm, direction=direction, absolute=False)
+
+        if success:
+            # 计算预估旋转时间并进行阻塞等待 (Time = revolutions / (RPM/60))
+            # 1/4 rev / (RPM/60) = 15.0 / RPM
+            estimated_time = 15.0 / max(1, speed_rpm)
+            time.sleep(estimated_time + 0.5)  # 额外给 0.5 秒缓冲
+            self.status = "idle"
+
+        return success
+
+    def wait_time(self, duration_s: float) -> bool:
+        """
+        等待指定时间 (秒)
+        """
+        self.logger.info(f"Waiting for {duration_s} seconds...")
+        time.sleep(duration_s)
+        return True
+
+    def set_zero(self) -> bool:
+        """
+        清零当前位置
+
+        Returns:
+            是否成功
+        """
+        resp = self._send(0x0A, [])
+        return len(resp) >= 4
+
+    def get_position(self) -> Optional[int]:
+        """
+        读取当前位置 (脉冲数)
+
+        Returns:
+            当前位置脉冲数，失败返回 None
+        """
+        resp = self._send(0x32, [])
+
+        if len(resp) >= 8:
+            # 响应格式: [ID] [Func] [符号位] [数值4字节] [校验]
+            sign = resp[2]  # 0=正, 1=负
+            value = struct.unpack('>I', resp[3:7])[0]
+            self.position = -value if sign == 1 else value
+
+            if self.debug:
+                print(f"[Position] Raw: {resp.hex().upper()}, Parsed: {self.position}")
+
+            return self.position
+
+        self.logger.warning("Failed to read position")
+        return None
+
+    def close(self):
+        """关闭串口连接并停止线程"""
+        if hasattr(self, '_stop_event'):
+            self._stop_event.set()
+
+        if self.ser and self.ser.is_open:
+            self.ser.close()
+            self.logger.info("Serial port closed")
+
+
+# ============================================================
+# 测试和调试代码
+# ============================================================
+
+def test_motor():
+    """基础功能测试"""
+    logging.basicConfig(level=logging.INFO)
+
+    print("="*60)
+    print("ZDT X42 电机驱动测试")
+    print("="*60)
+
+    driver = ZDTX42Driver(
+        port="/dev/tty.usbserial-3110",
+        baudrate=115200,
+        device_id=2,
+        debug=True
+    )
+
+    if not driver.ser:
+        print("❌ 串口打开失败")
+        return
+
+    try:
+        # 测试 1: 读取位置
+        print("\n[1] 读取当前位置")
+        pos = driver.get_position()
+        print(f"✓ 当前位置: {pos} 脉冲")
+
+        # 测试 2: 使能
+        print("\n[2] 使能电机")
+        driver.enable(True)
+        time.sleep(0.3)
+        print("✓ 电机已锁定")
+
+        # 测试 3: 相对位置运动
+        print("\n[3] 相对位置运动 (1000脉冲)")
+        driver.move_position(pulses=1000, speed_rpm=60, direction="CW")
+        time.sleep(2)
+        pos = driver.get_position()
+        print(f"✓ 新位置: {pos}")
+
+        # 测试 4: 速度运动
+        print("\n[4] 速度模式 (30RPM, 3秒)")
+        driver.move_speed(speed_rpm=30, direction="CW")
+        time.sleep(3)
+        driver.stop()
+        pos = driver.get_position()
+        print(f"✓ 停止后位置: {pos}")
+
+        # 测试 5: 禁用
+        print("\n[5] 禁用电机")
+        driver.enable(False)
+        print("✓ 电机已松开")
+
+        print("\n" + "="*60)
+        print("✅ 测试完成")
+        print("="*60)
+
+    except Exception as e:
+        print(f"\n❌ 测试失败: {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        driver.close()
+
+
+if __name__ == "__main__":
+    test_motor()

unilabos/devices/ros_dev/liquid_handler_joint_publisher_node.py

@@ -42,7 +42,6 @@ class LiquidHandlerJointPublisher(Node):
             while self.resource_action is None:
                 self.resource_action = self.check_tf_update_actions()
                 time.sleep(1)
-                self.get_logger().info(f'Waiting for TfUpdate server: {self.resource_action}')
 
             self.resource_action_client = ActionClient(self, SendCmd, self.resource_action)
             while not self.resource_action_client.wait_for_server(timeout_sec=1.0):

unilabos/devices/ros_dev/moveit_interface.py

@@ -2,7 +2,6 @@ import json
 import time
 from copy import deepcopy
 from pathlib import Path
-from typing import Optional, Sequence
 
 from moveit_msgs.msg import JointConstraint, Constraints
 from rclpy.action import ActionClient
@@ -172,160 +171,173 @@ class MoveitInterface:
 
         return True
 
-    def pick_and_place(
-        self,
-        option: str,
-        move_group: str,
-        status: str,
-        resource: Optional[str] = None,
-        x_distance: Optional[float] = None,
-        y_distance: Optional[float] = None,
-        lift_height: Optional[float] = None,
-        retry: Optional[int] = None,
-        speed: Optional[float] = None,
-        target: Optional[str] = None,
-        constraints: Optional[Sequence[float]] = None,
-    ) -> None:
+    def pick_and_place(self, command: str):
         """
-        使用 MoveIt 完成抓取/放置等序列（pick/place/side_pick/side_place）。
+        Using MoveIt to make the robotic arm pick or place materials to a target point.
 
-        必选：option, move_group, status。
-        可选：resource, x_distance, y_distance, lift_height, retry, speed, target, constraints。
-        无返回值；失败时提前 return 或打印异常。
+        Args:
+            command: A JSON-formatted string that includes option, target, speed, lift_height, mt_height
+
+                    *option (string)    : Action type: pick/place/side_pick/side_place
+                    *move_group (string): The move group moveit will plan
+                    *status(string)     : Target pose
+                    resource(string)    : The target resource
+                    x_distance (float)  : The distance to the target in x direction(meters)
+                    y_distance (float)  : The distance to the target in y direction(meters)
+                    lift_height (float) : The height at which the material should be lifted(meters)
+                    retry (float)       : Retry times when moveit plan fails
+                    speed (float)       : The speed of the movement, speed > 0
+        Returns:
+            None
         """
+        result = SendCmd.Result()
+
         try:
-            if option not in self.move_option:
-                raise ValueError(f"Invalid option: {option}")
+            cmd_str = str(command).replace("'", '"')
+            cmd_dict = json.loads(cmd_str)
 
-            option_index = self.move_option.index(option)
-            place_flag = option_index % 2
+            if cmd_dict["option"] in self.move_option:
+                option_index = self.move_option.index(cmd_dict["option"])
+                place_flag = option_index % 2
 
-            config: dict = {"move_group": move_group}
-            if speed is not None:
-                config["speed"] = speed
-            if retry is not None:
-                config["retry"] = retry
+                config = {}
+                function_list = []
 
-            function_list = []
-            joint_positions_ = self.joint_poses[move_group][status]
+                status = cmd_dict["status"]
+                joint_positions_ = self.joint_poses[cmd_dict["move_group"]][status]
 
-            # 夹取 / 放置：绑定 resource 与 parent
-            if not place_flag:
-                if target is not None:
-                    function_list.append(lambda r=resource, t=target: self.resource_manager(r, t))
-                else:
-                    ee = self.moveit2[move_group].end_effector_name
-                    function_list.append(lambda r=resource: self.resource_manager(r, ee))
-            else:
-                function_list.append(lambda r=resource: self.resource_manager(r, "world"))
+                config.update({k: cmd_dict[k] for k in ["speed", "retry", "move_group"] if k in cmd_dict})
 
-            joint_constraint_msgs: list = []
-            if constraints is not None:
-                for i, c in enumerate(constraints):
-                    v = float(c)
-                    if v > 0:
-                        joint_constraint_msgs.append(
-                            JointConstraint(
-                                joint_name=self.moveit2[move_group].joint_names[i],
-                                position=joint_positions_[i],
-                                tolerance_above=v,
-                                tolerance_below=v,
-                                weight=1.0,
+                # 夹取
+                if not place_flag:
+                    if "target" in cmd_dict.keys():
+                        function_list.append(lambda: self.resource_manager(cmd_dict["resource"], cmd_dict["target"]))
+                    else:
+                        function_list.append(
+                            lambda: self.resource_manager(
+                                cmd_dict["resource"], self.moveit2[cmd_dict["move_group"]].end_effector_name
                             )
                         )
+                else:
+                    function_list.append(lambda: self.resource_manager(cmd_dict["resource"], "world"))
 
-            if lift_height is not None:
-                retval = None
-                attempts = config.get("retry", 10)
-                while retval is None and attempts > 0:
-                    retval = self.moveit2[move_group].compute_fk(joint_positions_)
-                    time.sleep(0.1)
-                    attempts -= 1
-                if retval is None:
-                    raise ValueError("Failed to compute forward kinematics")
-                pose = [retval.pose.position.x, retval.pose.position.y, retval.pose.position.z]
-                quaternion = [
-                    retval.pose.orientation.x,
-                    retval.pose.orientation.y,
-                    retval.pose.orientation.z,
-                    retval.pose.orientation.w,
-                ]
+                constraints = []
+                if "constraints" in cmd_dict.keys():
 
-                function_list = [
-                    lambda: self.moveit_task(
-                        position=[retval.pose.position.x, retval.pose.position.y, retval.pose.position.z],
-                        quaternion=quaternion,
-                        **config,
-                        cartesian=self.cartesian_flag,
-                    )
-                ] + function_list
+                    for i in range(len(cmd_dict["constraints"])):
+                        v = float(cmd_dict["constraints"][i])
+                        if v > 0:
+                            constraints.append(
+                                JointConstraint(
+                                    joint_name=self.moveit2[cmd_dict["move_group"]].joint_names[i],
+                                    position=joint_positions_[i],
+                                    tolerance_above=v,
+                                    tolerance_below=v,
+                                    weight=1.0,
+                                )
+                            )
 
-                pose[2] += float(lift_height)
-                function_list.append(
-                    lambda p=pose.copy(), q=quaternion, cfg=config: self.moveit_task(
-                        position=p, quaternion=q, **cfg, cartesian=self.cartesian_flag
-                    )
-                )
-                end_pose = list(pose)
-
-                if x_distance is not None or y_distance is not None:
-                    if x_distance is not None:
-                        deep_pose = deepcopy(pose)
-                        deep_pose[0] += float(x_distance)
-                    elif y_distance is not None:
-                        deep_pose = deepcopy(pose)
-                        deep_pose[1] += float(y_distance)
+                if "lift_height" in cmd_dict.keys():
+                    retval = None
+                    retry = config.get("retry", 10)
+                    while retval is None and retry > 0:
+                        retval = self.moveit2[cmd_dict["move_group"]].compute_fk(joint_positions_)
+                        time.sleep(0.1)
+                        retry -= 1
+                    if retval is None:
+                        result.success = False
+                        return result
+                    pose = [retval.pose.position.x, retval.pose.position.y, retval.pose.position.z]
+                    quaternion = [
+                        retval.pose.orientation.x,
+                        retval.pose.orientation.y,
+                        retval.pose.orientation.z,
+                        retval.pose.orientation.w,
+                    ]
 
                     function_list = [
-                        lambda p=pose.copy(), q=quaternion, cfg=config: self.moveit_task(
-                            position=p, quaternion=q, **cfg, cartesian=self.cartesian_flag
+                        lambda: self.moveit_task(
+                            position=[retval.pose.position.x, retval.pose.position.y, retval.pose.position.z],
+                            quaternion=quaternion,
+                            **config,
+                            cartesian=self.cartesian_flag,
                         )
                     ] + function_list
+
+                    pose[2] += float(cmd_dict["lift_height"])
                     function_list.append(
-                        lambda dp=deep_pose.copy(), q=quaternion, cfg=config: self.moveit_task(
-                            position=dp, quaternion=q, **cfg, cartesian=self.cartesian_flag
+                        lambda: self.moveit_task(
+                            position=pose, quaternion=quaternion, **config, cartesian=self.cartesian_flag
                         )
                     )
-                    end_pose = list(deep_pose)
+                    end_pose = pose
 
-                retval_ik = None
-                attempts_ik = config.get("retry", 10)
-                while retval_ik is None and attempts_ik > 0:
-                    retval_ik = self.moveit2[move_group].compute_ik(
-                        position=end_pose,
-                        quat_xyzw=quaternion,
-                        constraints=Constraints(joint_constraints=joint_constraint_msgs),
-                    )
-                    time.sleep(0.1)
-                    attempts_ik -= 1
-                if retval_ik is None:
-                    raise ValueError("Failed to compute inverse kinematics")
-                position_ = [
-                    retval_ik.position[retval_ik.name.index(i)] for i in self.moveit2[move_group].joint_names
-                ]
-                jn = self.moveit2[move_group].joint_names
-                function_list = [
-                    lambda pos=position_, names=jn, cfg=config: self.moveit_joint_task(
-                        joint_positions=pos, joint_names=names, **cfg
-                    )
-                ] + function_list
-            else:
-                function_list = [lambda cfg=config, jp=joint_positions_: self.moveit_joint_task(**cfg, joint_positions=jp)] + function_list
+                    if "x_distance" in cmd_dict.keys() or "y_distance" in cmd_dict.keys():
+                        if "x_distance" in cmd_dict.keys():
+                            deep_pose = deepcopy(pose)
+                            deep_pose[0] += float(cmd_dict["x_distance"])
+                        elif "y_distance" in cmd_dict.keys():
+                            deep_pose = deepcopy(pose)
+                            deep_pose[1] += float(cmd_dict["y_distance"])
 
-            for i in range(len(function_list)):
-                if i == 0:
-                    self.cartesian_flag = False
+                        function_list = [
+                            lambda: self.moveit_task(
+                                position=pose, quaternion=quaternion, **config, cartesian=self.cartesian_flag
+                            )
+                        ] + function_list
+                        function_list.append(
+                            lambda: self.moveit_task(
+                                position=deep_pose, quaternion=quaternion, **config, cartesian=self.cartesian_flag
+                            )
+                        )
+                        end_pose = deep_pose
+
+                    retval_ik = None
+                    retry = config.get("retry", 10)
+                    while retval_ik is None and retry > 0:
+                        retval_ik = self.moveit2[cmd_dict["move_group"]].compute_ik(
+                            position=end_pose, quat_xyzw=quaternion, constraints=Constraints(joint_constraints=constraints)
+                        )
+                        time.sleep(0.1)
+                        retry -= 1
+                    if retval_ik is None:
+                        result.success = False
+                        return result
+                    position_ = [
+                        retval_ik.position[retval_ik.name.index(i)]
+                        for i in self.moveit2[cmd_dict["move_group"]].joint_names
+                    ]
+                    function_list = [
+                        lambda: self.moveit_joint_task(
+                            joint_positions=position_,
+                            joint_names=self.moveit2[cmd_dict["move_group"]].joint_names,
+                            **config,
+                        )
+                    ] + function_list
                 else:
-                    self.cartesian_flag = True
+                    function_list = [
+                        lambda: self.moveit_joint_task(**config, joint_positions=joint_positions_)
+                    ] + function_list
 
-                re = function_list[i]()
-                if not re:
-                    print(i, re)
-                    raise ValueError(f"Failed to execute moveit task: {i}")
+                for i in range(len(function_list)):
+                    if i == 0:
+                        self.cartesian_flag = False
+                    else:
+                        self.cartesian_flag = True
+
+                    re = function_list[i]()
+                    if not re:
+                        print(i, re)
+                        result.success = False
+                        return result
+                result.success = True
 
         except Exception as e:
+            print(e)
             self.cartesian_flag = False
-            raise e
+            result.success = False
+
+        return result
 
     def set_status(self, command: str):
         """

unilabos/devices/separator/chinwe.py

@@ -623,6 +623,119 @@ class ChinweDevice(UniversalDriver):
         time.sleep(duration)
         return True
 
+    def separation_step(self, motor_id: int = 5, speed: int = 60, pulses: int = 700,
+                       max_cycles: int = 0, timeout: int = 300) -> bool:
+        """
+        分液步骤 - 液位传感器与电机联动
+        当液位传感器检测到"有液"时,电机顺时针旋转指定脉冲数
+        当液位传感器检测到"无液"时,电机逆时针旋转指定脉冲数
+
+        :param motor_id: 电机ID (必须在初始化时配置的motor_ids中)
+        :param speed: 电机转速 (RPM)
+        :param pulses: 每次旋转的脉冲数 (默认700约为1/4圈,假设3200脉冲/圈)
+        :param max_cycles: 最大执行循环次数 (0=无限制,默认0)
+        :param timeout: 整体超时时间 (秒)
+        :return: 成功返回True,超时或失败返回False
+        """
+        motor_id = int(motor_id)
+        speed = int(speed)
+        pulses = int(pulses)
+        max_cycles = int(max_cycles)
+        timeout = int(timeout)
+
+        # 检查电机是否存在
+        if motor_id not in self.motors:
+            self.logger.error(f"Motor {motor_id} not found in configured motors: {list(self.motors.keys())}")
+            return False
+
+        # 检查传感器是否可用
+        if not self.sensor:
+            self.logger.error("Sensor not initialized")
+            return False
+
+        motor = self.motors[motor_id]
+
+        # 停止轮询线程，避免与 separation_step 同时读取传感器造成串口冲突
+        self.logger.info("Stopping polling thread for separation_step...")
+        self._stop_event.set()
+        if self._poll_thread and self._poll_thread.is_alive():
+            self._poll_thread.join(timeout=2.0)
+
+        # 使能电机
+        self.logger.info(f"Enabling motor {motor_id}...")
+        motor.enable(True)
+        time.sleep(0.2)
+
+        self.logger.info(f"Starting separation step: motor_id={motor_id}, speed={speed} RPM, "
+                        f"pulses={pulses}, max_cycles={max_cycles}, timeout={timeout}s")
+
+        # 记录上一次的液位状态
+        last_level = None
+        cycle_count = 0
+        start_time = time.time()
+        error_count = 0
+
+        try:
+            while True:
+                # 检查超时
+                if time.time() - start_time > timeout:
+                    self.logger.warning(f"Separation step timeout after {timeout} seconds")
+                    return False
+
+                # 检查循环次数限制
+                if max_cycles > 0 and cycle_count >= max_cycles:
+                    self.logger.info(f"Separation step completed: reached max_cycles={max_cycles}")
+                    return True
+
+                # 读取传感器数据
+                data = self.sensor.read_level()
+
+                if data is None:
+                    error_count += 1
+                    if error_count > 5:
+                        self.logger.warning("Sensor read failed multiple times, retrying...")
+                        error_count = 0
+                    time.sleep(0.5)
+                    continue
+
+                error_count = 0
+                current_level = data['level']
+                rssi = data['rssi']
+
+                # 检测状态变化 (包括首次检测)
+                if current_level != last_level:
+                    cycle_count += 1
+
+                    if current_level:
+                        # 有液 -> 电机顺时针旋转
+                        self.logger.info(f"[Cycle {cycle_count}] Liquid detected (RSSI={rssi}), "
+                                       f"rotating motor {motor_id} clockwise {pulses} pulses")
+                        motor.run_position(pulses=pulses, speed_rpm=speed, direction=0, absolute=False)
+
+                        # 等待电机完成 (预估时间)
+                        estimated_time = 15.0 / max(1, speed)
+                        time.sleep(estimated_time + 0.5)
+
+                    else:
+                        # 无液 -> 电机逆时针旋转
+                        self.logger.info(f"[Cycle {cycle_count}] No liquid detected (RSSI={rssi}), "
+                                       f"rotating motor {motor_id} counter-clockwise {pulses} pulses")
+                        motor.run_position(pulses=pulses, speed_rpm=speed, direction=1, absolute=False)
+
+                        # 等待电机完成 (预估时间)
+                        estimated_time = 15.0 / max(1, speed)
+                        time.sleep(estimated_time + 0.5)
+
+                # 更新状态
+                last_level = current_level
+
+                # 轮询间隔
+                time.sleep(0.1)
+        finally:
+            # 恢复轮询线程
+            self.logger.info("Restarting polling thread...")
+            self._start_polling()
+
     def execute_command_from_outer(self, command_dict: Dict[str, Any]) -> bool:
         """支持标准 JSON 指令调用"""
         return super().execute_command_from_outer(command_dict)

unilabos/devices/separator/xkc_sensor.py

@@ -0,0 +1,379 @@
+# -*- coding: utf-8 -*-
+"""
+XKC RS485 液位传感器 (Modbus RTU)
+
+说明:
+    1. 遵循 Modbus-RTU 协议。
+    2. 数据寄存器: 0x0001 (液位状态, 1=有液, 0=无液), 0x0002 (RSSI 信号强度)。
+    3. 地址寄存器: 0x0004 (可读写, 范围 1-254)。
+    4. 波特率寄存器: 0x0005 (可写, 代码表见 change_baudrate 方法)。
+"""
+
+import struct
+import threading
+import time
+import logging
+import serial
+from typing import Optional, Dict, Any, List
+
+from unilabos.device_comms.universal_driver import UniversalDriver
+
+class TransportManager:
+    """
+    统一通信管理类。
+    仅支持 串口 (Serial/有线) 连接。
+    """
+    def __init__(self, port: str, baudrate: int = 9600, timeout: float = 3.0, logger=None):
+        self.port = port
+        self.baudrate = baudrate
+        self.timeout = timeout
+        self.logger = logger
+        self.lock = threading.RLock() # 线程锁，确保多设备共用一个连接时不冲突
+
+        self.serial = None
+        self._connect_serial()
+
+    def _connect_serial(self):
+        try:
+            self.serial = serial.Serial(
+                port=self.port,
+                baudrate=self.baudrate,
+                timeout=self.timeout
+            )
+        except Exception as e:
+            raise ConnectionError(f"Serial open failed: {e}")
+
+    def close(self):
+        """关闭连接"""
+        if self.serial and self.serial.is_open:
+            self.serial.close()
+
+    def clear_buffer(self):
+        """清空缓冲区 (Thread-safe)"""
+        with self.lock:
+            if self.serial:
+                self.serial.reset_input_buffer()
+
+    def write(self, data: bytes):
+        """发送原始字节"""
+        with self.lock:
+            if self.serial:
+                self.serial.write(data)
+
+    def read(self, size: int) -> bytes:
+        """读取指定长度字节"""
+        if self.serial:
+            return self.serial.read(size)
+        return b''
+
+class XKCSensorDriver(UniversalDriver):
+    """XKC RS485 液位传感器 (Modbus RTU)"""
+
+    def __init__(self, port: str, baudrate: int = 9600, device_id: int = 6,
+                 threshold: int = 300, timeout: float = 3.0, debug: bool = False):
+        super().__init__()
+        self.port = port
+        self.baudrate = baudrate
+        self.device_id = device_id
+        self.threshold = threshold
+        self.timeout = timeout
+        self.debug = debug
+        self.level = False
+        self.rssi = 0
+        self.status = {"level": self.level, "rssi": self.rssi}
+
+        try:
+            self.transport = TransportManager(port, baudrate, timeout, logger=self.logger)
+            self.logger.info(f"XKCSensorDriver connected to {port} (ID: {device_id})")
+        except Exception as e:
+            self.logger.error(f"Failed to connect XKCSensorDriver: {e}")
+            self.transport = None
+
+        # 启动背景轮询线程，确保 status 实时刷新
+        self._stop_event = threading.Event()
+        self._polling_thread = threading.Thread(
+            target=self._update_loop,
+            name=f"XKCPolling_{port}",
+            daemon=True
+        )
+        if self.transport:
+            self._polling_thread.start()
+
+    def _update_loop(self):
+        """背景循环读取传感器数据"""
+        while not self._stop_event.is_set():
+            try:
+                self.read_level()
+            except Exception as e:
+                if self.debug:
+                    self.logger.error(f"Polling error: {e}")
+            time.sleep(2.0) # 每2秒刷新一次数据
+
+    def _crc(self, data: bytes) -> bytes:
+        crc = 0xFFFF
+        for byte in data:
+            crc ^= byte
+            for _ in range(8):
+                if crc & 0x0001: crc = (crc >> 1) ^ 0xA001
+                else: crc >>= 1
+        return struct.pack('<H', crc)
+
+    def read_level(self) -> Optional[Dict[str, Any]]:
+        """
+        读取液位。
+        返回: {'level': bool, 'rssi': int}
+        """
+        if not self.transport:
+            return None
+
+        with self.transport.lock:
+            self.transport.clear_buffer()
+            # Modbus Read Registers: 01 03 00 01 00 02 CRC
+            payload = struct.pack('>HH', 0x0001, 0x0002)
+            msg = struct.pack('BB', self.device_id, 0x03) + payload
+            msg += self._crc(msg)
+
+            if self.debug:
+                self.logger.info(f"TX (ID {self.device_id}): {msg.hex().upper()}")
+
+            self.transport.write(msg)
+
+            # Read header
+            h = self.transport.read(3) # Addr, Func, Len
+            if self.debug:
+                self.logger.info(f"RX Header: {h.hex().upper()}")
+
+            if len(h) < 3: return None
+            length = h[2]
+
+            # Read body + CRC
+            body = self.transport.read(length + 2)
+            if self.debug:
+                self.logger.info(f"RX Body+CRC: {body.hex().upper()}")
+            if len(body) < length + 2:
+                # Firmware bug fix specific to some modules
+                if len(body) == 4 and length == 4:
+                    pass
+                else:
+                    return None
+
+            data = body[:-2]
+            # 根据手册说明:
+            # 寄存器 0x0001 (data[0:2]): 液位状态 (00 01 为有液, 00 00 为无液)
+            # 寄存器 0x0002 (data[2:4]): 信号强度 RSSI
+
+            hw_level = False
+            rssi = 0
+
+            if len(data) >= 4:
+                hw_level = ((data[0] << 8) | data[1]) == 1
+                rssi = (data[2] << 8) | data[3]
+            elif len(data) == 2:
+                # 兼容模式: 某些老固件可能只返回 1 个寄存器
+                rssi = (data[0] << 8) | data[1]
+                hw_level = rssi > self.threshold
+            else:
+                return None
+
+            # 最终判定: 优先使用硬件层级的 level 判定，但 RSSI 阈值逻辑作为补充/校验
+            # 注意: 如果用户显式设置了 THRESHOLD，我们可以在逻辑中做权衡
+            self.level = hw_level or (rssi > self.threshold)
+            self.rssi = rssi
+            result = {
+                'level': self.level,
+                'rssi': self.rssi
+            }
+            self.status = result
+            return result
+
+    def wait_level(self, target_state: bool, timeout: float = 60.0) -> bool:
+        """
+        等待液位达到目标状态 (阻塞式)
+        """
+        self.logger.info(f"Waiting for level: {target_state}")
+        start_time = time.time()
+        while (time.time() - start_time) < timeout:
+            res = self.read_level()
+            if res and res.get('level') == target_state:
+                return True
+            time.sleep(0.5)
+        self.logger.warning(f"Wait level timeout ({timeout}s)")
+        return False
+
+    def wait_for_liquid(self, target_state: bool, timeout: float = 120.0) -> bool:
+        """
+        实时检测电导率(RSSI)并等待用户指定的“有液”或“无液”状态。
+        一旦检测到符合目标状态，立即返回。
+
+        Args:
+            target_state: True 为“有液”, False 为“无液”
+            timeout: 最大等待时间(秒)
+        """
+        state_str = "有液" if target_state else "无液"
+        self.logger.info(f"开始实时检测电导率，等待状态: {state_str} (超时: {timeout}s)")
+
+        start_time = time.time()
+        while (time.time() - start_time) < timeout:
+            res = self.read_level() # 内部已更新 self.level 和 self.rssi
+            if res:
+                current_level = res.get('level')
+                current_rssi = res.get('rssi')
+                if current_level == target_state:
+                    self.logger.info(f"✅ 检测到目标状态: {state_str} (当前电导率/RSSI: {current_rssi})")
+                    return True
+
+                if self.debug:
+                    self.logger.debug(f"当前状态: {'有液' if current_level else '无液'}, RSSI: {current_rssi}")
+
+            time.sleep(0.2) # 高频采样
+
+        self.logger.warning(f"❌ 等待 {state_str} 状态超时 ({timeout}s)")
+        return False
+
+    def set_threshold(self, threshold: int):
+        """设置液位判定阈值"""
+        self.threshold = int(threshold)
+        self.logger.info(f"Threshold updated to: {self.threshold}")
+
+    def change_device_id(self, new_id: int) -> bool:
+        """
+        修改设备的 Modbus 从站地址。
+        寄存器: 0x0004, 功能码: 0x06
+        """
+        if not (1 <= new_id <= 254):
+            self.logger.error(f"Invalid device ID: {new_id}. Must be 1-254.")
+            return False
+
+        self.logger.info(f"Changing device ID from {self.device_id} to {new_id}")
+        success = self._write_single_register(0x0004, new_id)
+        if success:
+            self.device_id = new_id # 更新内存中的地址
+            self.logger.info(f"Device ID update command sent successfully (target {new_id}).")
+        return success
+
+    def change_baudrate(self, baud_code: int) -> bool:
+        """
+        更改通讯波特率 (寄存器: 0x0005)。
+        设置成功后传感器 LED 会闪烁，通常无数据返回。
+
+        波特率代码对照表 (16进制):
+        05: 2400
+        06: 4800
+        07: 9600 (默认)
+        08: 14400
+        09: 19200
+        0A: 28800
+        0C: 57600
+        0D: 115200
+        0E: 128000
+        0F: 256000
+        """
+        self.logger.info(f"Sending baudrate change command (Code: {baud_code:02X})")
+        # 写入寄存器 0x0005
+        self._write_single_register(0x0005, baud_code)
+        self.logger.info("Baudrate change command executed. Device LED should flash. Please update connection settings.")
+        return True
+
+    def factory_reset(self) -> bool:
+        """
+        恢复出厂设置 (通过广播地址 FF)。
+        设置地址为 01，逻辑为向 0x0004 写入 0x0002
+        """
+        self.logger.info("Sending factory reset command via broadcast address FF...")
+        # 广播指令通常无回显
+        self._write_single_register(0x0004, 0x0002, slave_id=0xFF)
+        self.logger.info("Factory reset command sent. Device address should be 01 now.")
+        return True
+
+    def _write_single_register(self, reg_addr: int, value: int, slave_id: Optional[int] = None) -> bool:
+        """内部辅助函数: Modbus 功能码 06 写单个寄存器"""
+        if not self.transport: return False
+
+        target_id = slave_id if slave_id is not None else self.device_id
+        msg = struct.pack('BBHH', target_id, 0x06, reg_addr, value)
+        msg += self._crc(msg)
+
+        with self.transport.lock:
+            self.transport.clear_buffer()
+            if self.debug:
+                self.logger.info(f"TX Write (Reg {reg_addr:#06x}): {msg.hex().upper()}")
+
+            self.transport.write(msg)
+
+            # 广播地址、波特率修改或厂家特定指令可能无回显
+            if target_id == 0xFF or reg_addr == 0x0005:
+                time.sleep(0.5)
+                return True
+
+            # 等待返回 (正常应返回相同报文)
+            resp = self.transport.read(len(msg))
+            if self.debug:
+                self.logger.info(f"RX Write Response: {resp.hex().upper()}")
+
+            return resp == msg
+
+    def close(self):
+        if self.transport:
+            self.transport.close()
+
+if __name__ == "__main__":
+    # 快速实例化测试
+    import logging
+    # 减少冗余日志，仅显示重要信息
+    logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
+
+    # 硬件配置 (根据实际情况修改)
+    TEST_PORT = "/dev/tty.usbserial-3110"
+    SLAVE_ID = 1
+    THRESHOLD = 300
+
+    print("\n" + "="*50)
+    print(f"  XKC RS485 传感器独立测试程序")
+    print(f"  端口: {TEST_PORT} | 地址: {SLAVE_ID} | 阈值: {THRESHOLD}")
+    print("="*50)
+
+    sensor = XKCSensorDriver(port=TEST_PORT, device_id=SLAVE_ID, threshold=THRESHOLD, debug=False)
+
+    try:
+        if sensor.transport:
+            print(f"\n开始实时连续采样测试 (持续 15 秒)...")
+            print(f"按 Ctrl+C 可提前停止\n")
+
+            start_time = time.time()
+            duration = 15
+            count = 0
+
+            while time.time() - start_time < duration:
+                count += 1
+                res = sensor.read_level()
+                if res:
+                    rssi = res['rssi']
+                    level = res['level']
+                    status_str = "【有液】" if level else "【无液】"
+                    # 使用 \r 实现单行刷新显示 (或者不刷，直接打印历史)
+                    # 为了方便查看变化，我们直接打印
+                    elapsed = time.time() - start_time
+                    print(f" [{elapsed:4.1f}s] 采样 {count:<3}: 电导率/RSSI = {rssi:<5} | 判定结果: {status_str}")
+                else:
+                    print(f" [{time.time()-start_time:4.1f}s] 采样 {count:<3}: 通信失败 (无响应)")
+
+                time.sleep(0.5) # 每秒采样 2 次
+
+            print(f"\n--- 15 秒采样测试完成 (总计 {count} 次) ---")
+
+            # [3] 测试动态修改阈值
+            print(f"\n[3] 动态修改阈值演示...")
+            new_threshold = 400
+            sensor.set_threshold(new_threshold)
+            res = sensor.read_level()
+            if res:
+                print(f"  采样 (当前阈值={new_threshold}): 电导率/RSSI = {res['rssi']:<5} | 判定结果: {'【有液】' if res['level'] else '【无液】'}")
+            sensor.set_threshold(THRESHOLD) # 还原
+
+    except KeyboardInterrupt:
+        print("\n[!] 用户中断测试")
+    except Exception as e:
+        print(f"\n[!] 测试运行出错: {e}")
+    finally:
+        sensor.close()
+        print("\n--- 测试程序已退出 ---\n")

unilabos/devices/virtual/workbench.py

@@ -14,30 +14,20 @@ Virtual Workbench Device - 模拟工作台设备
 
 import logging
 import time
+from typing import Dict, Any, Optional, List
 from dataclasses import dataclass
 from enum import Enum
 from threading import Lock, RLock
-from typing import Any, Dict, List, Optional, cast
 
 from typing_extensions import TypedDict
 
 from unilabos.registry.decorators import (
-    ActionInputHandle,
-    ActionOutputHandle,
-    DataSource,
-    NodeType,
-    action,
-    device,
-    not_action,
-    topic_config,
+    device, action, ActionInputHandle, ActionOutputHandle, DataSource, topic_config, not_action, NodeType
 )
 from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
 from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode, ROS2DeviceNode
-from unilabos.resources.resource_tracker import (
-    SampleUUIDsType,
-    LabSample,
-    ResourceTreeSet,
-)
+from unilabos.resources.resource_tracker import SampleUUIDsType, LabSample, ResourceTreeSet
+
 
 # ============ TypedDict 返回类型定义 ============
 
@@ -122,7 +112,6 @@ class HeatingStation:
 
 @device(
     id="virtual_workbench",
-    display_name="虚拟工作台",
     category=["virtual_device"],
     description="Virtual Workbench with 1 robotic arm and 3 heating stations for concurrent material processing",
 )
@@ -148,19 +137,7 @@ class VirtualWorkbench:
     HEATING_TIME: float = 60.0  # 加热时间(秒)
     NUM_HEATING_STATIONS: int = 3  # 加热台数量
 
-    def __init__(
-        self,
-        device_id: Optional[str] = None,
-        config: Optional[Dict[str, Any]] = None,
-        **kwargs,
-    ):
-        """
-        初始化虚拟工作台。
-
-        Args:
-            device_id[设备ID]: 工作台设备实例 ID，默认使用 virtual_workbench。
-            config[设备配置]: 可包含 arm_operation_time、heating_time、num_heating_stations。
-        """
+    def __init__(self, device_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, **kwargs):
         # 处理可能的不同调用方式
         if device_id is None and "id" in kwargs:
             device_id = kwargs.pop("id")
@@ -174,13 +151,9 @@ class VirtualWorkbench:
         self.data: Dict[str, Any] = {}
 
         # 从config中获取可配置参数
-        self.ARM_OPERATION_TIME = float(
-            self.config.get("arm_operation_time", self.ARM_OPERATION_TIME)
-        )
+        self.ARM_OPERATION_TIME = float(self.config.get("arm_operation_time", self.ARM_OPERATION_TIME))
         self.HEATING_TIME = float(self.config.get("heating_time", self.HEATING_TIME))
-        self.NUM_HEATING_STATIONS = int(
-            self.config.get("num_heating_stations", self.NUM_HEATING_STATIONS)
-        )
+        self.NUM_HEATING_STATIONS = int(self.config.get("num_heating_stations", self.NUM_HEATING_STATIONS))
 
         # 机械臂状态和锁
         self._arm_lock = Lock()
@@ -189,8 +162,7 @@ class VirtualWorkbench:
 
         # 加热台状态
         self._heating_stations: Dict[int, HeatingStation] = {
-            i: HeatingStation(station_id=i)
-            for i in range(1, self.NUM_HEATING_STATIONS + 1)
+            i: HeatingStation(station_id=i) for i in range(1, self.NUM_HEATING_STATIONS + 1)
         }
         self._stations_lock = RLock()
 
@@ -320,113 +292,45 @@ class VirtualWorkbench:
         self.logger.info(f"机械臂已释放 (完成: {task})")
 
     @action(
-        always_free=True,
-        node_type=NodeType.MANUAL_CONFIRM,
-        placeholder_keys={"assignee_user_ids": "unilabos_manual_confirm"},
-        goal_default={"timeout_seconds": 3600, "assignee_user_ids": []},
-        feedback_interval=300,
+        always_free=True, node_type=NodeType.MANUAL_CONFIRM, placeholder_keys={
+            "assignee_user_ids": "unilabos_manual_confirm"
+        }, goal_default={
+            "timeout_seconds": 3600,
+            "assignee_user_ids": []
+        }, feedback_interval=300,
         handles=[
-            ActionInputHandle(
-                key="target_device",
-                data_type="device_id",
-                label="目标设备",
-                data_key="target_device",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="resource",
-                data_type="resource",
-                label="待转移资源",
-                data_key="resource",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="mount_resource",
-                data_type="resource",
-                label="目标孔位",
-                data_key="mount_resource",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="collector_mass",
-                data_type="collector_mass",
-                label="极流体质量",
-                data_key="collector_mass",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="active_material",
-                data_type="active_material",
-                label="活性物质含量",
-                data_key="active_material",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="capacity",
-                data_type="capacity",
-                label="克容量",
-                data_key="capacity",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="battery_system",
-                data_type="battery_system",
-                label="电池体系",
-                data_key="battery_system",
-                data_source=DataSource.HANDLE,
-            ),
+            ActionInputHandle(key="target_device", data_type="device_id",
+                              label="目标设备", data_key="target_device", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="resource", data_type="resource",
+                              label="待转移资源", data_key="resource", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="mount_resource", data_type="resource",
+                              label="目标孔位", data_key="mount_resource", data_source=DataSource.HANDLE),
+
+            ActionInputHandle(key="collector_mass", data_type="collector_mass",
+                              label="极流体质量", data_key="collector_mass", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="active_material", data_type="active_material",
+                              label="活性物质含量", data_key="active_material", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="capacity", data_type="capacity",
+                              label="克容量", data_key="capacity", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="battery_system", data_type="battery_system",
+                              label="电池体系", data_key="battery_system", data_source=DataSource.HANDLE),
             # transfer使用
-            ActionOutputHandle(
-                key="target_device",
-                data_type="device_id",
-                label="目标设备",
-                data_key="target_device",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="resource",
-                data_type="resource",
-                label="待转移资源",
-                data_key="resource.@flatten",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="mount_resource",
-                data_type="resource",
-                label="目标孔位",
-                data_key="mount_resource.@flatten",
-                data_source=DataSource.EXECUTOR,
-            ),
+            ActionOutputHandle(key="target_device", data_type="device_id",
+                               label="目标设备", data_key="target_device", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="resource", data_type="resource",
+                              label="待转移资源", data_key="resource.@flatten", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="mount_resource", data_type="resource",
+                              label="目标孔位", data_key="mount_resource.@flatten", data_source=DataSource.EXECUTOR),
             # test使用
-            ActionOutputHandle(
-                key="collector_mass",
-                data_type="collector_mass",
-                label="极流体质量",
-                data_key="collector_mass",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="active_material",
-                data_type="active_material",
-                label="活性物质含量",
-                data_key="active_material",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="capacity",
-                data_type="capacity",
-                label="克容量",
-                data_key="capacity",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="battery_system",
-                data_type="battery_system",
-                label="电池体系",
-                data_key="battery_system",
-                data_source=DataSource.EXECUTOR,
-            ),
-        ],
+            ActionOutputHandle(key="collector_mass", data_type="collector_mass",
+                              label="极流体质量", data_key="collector_mass", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="active_material", data_type="active_material",
+                              label="活性物质含量", data_key="active_material", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="capacity", data_type="capacity",
+                              label="克容量", data_key="capacity", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="battery_system", data_type="battery_system",
+                              label="电池体系", data_key="battery_system", data_source=DataSource.EXECUTOR),
+        ]
     )
     def manual_confirm(
         self,
@@ -439,156 +343,67 @@ class VirtualWorkbench:
         battery_system: List[str],
         timeout_seconds: int,
         assignee_user_ids: list[str],
-        **kwargs,
+        **kwargs
     ) -> dict:
         """
-        人工确认资源转移和扣电测试参数。
-
-        Args:
-            resource[待转移资源]: 需要人工确认的资源列表。
-            target_device[目标设备]: 资源要转移到的目标设备 ID。
-            mount_resource[目标孔位]: 资源要挂载到的目标孔位列表。
-            collector_mass[极流体质量]: 每个样品对应的极流体质量。
-            active_material[活性物质含量]: 每个样品对应的活性物质含量。
-            capacity[克容量]: 每个样品对应的克容量，单位 mAh/g。
-            battery_system[电池体系]: 每个样品对应的电池体系名称。
-            timeout_seconds[超时时间]: 人工确认超时时间，单位秒。
-            assignee_user_ids[确认人]: 指定处理人工确认任务的用户 ID 列表。
-
-        Note:
-            修改的结果无效，是只读的。
+        timeout_seconds: 超时时间（秒），默认3600秒
+        collector_mass: 极流体质量
+        active_material: 活性物质含量
+        capacity: 克容量（mAh/g）
+        battery_system: 电池体系
+        修改的结果无效，是只读的
         """
-        resource_tree = ResourceTreeSet.from_plr_resources(cast(Any, resource)).dump()
-        mount_resource_tree = ResourceTreeSet.from_plr_resources(cast(Any, mount_resource)).dump()
+        resource = ResourceTreeSet.from_plr_resources(resource).dump()
+        mount_resource = ResourceTreeSet.from_plr_resources(mount_resource).dump()
         kwargs.update(locals())
         kwargs.pop("kwargs")
         kwargs.pop("self")
-        kwargs["resource"] = resource_tree
-        kwargs["mount_resource"] = mount_resource_tree
-        kwargs.pop("resource_tree")
-        kwargs.pop("mount_resource_tree")
         return kwargs
 
     @action(
         description="转移物料",
         handles=[
-            ActionInputHandle(
-                key="target_device",
-                data_type="device_id",
-                label="目标设备",
-                data_key="target_device",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="resource",
-                data_type="resource",
-                label="待转移资源",
-                data_key="resource",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="mount_resource",
-                data_type="resource",
-                label="目标孔位",
-                data_key="mount_resource",
-                data_source=DataSource.HANDLE,
-            ),
-        ],
+            ActionInputHandle(key="target_device", data_type="device_id",
+                              label="目标设备", data_key="target_device", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="resource", data_type="resource",
+                               label="待转移资源", data_key="resource", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="mount_resource", data_type="resource",
+                               label="目标孔位", data_key="mount_resource", data_source=DataSource.HANDLE),
+        ]
     )
-    async def transfer(
-        self,
-        resource: List[ResourceSlot],
-        target_device: DeviceSlot,
-        mount_resource: List[ResourceSlot],
-    ):
-        """
-        转移资源到目标设备。
-
-        Args:
-            resource[待转移资源]: 待转移的资源列表。
-            target_device[目标设备]: 接收资源的目标设备 ID。
-            mount_resource[目标孔位]: 目标设备上的挂载孔位列表。
-        """
-        future = ROS2DeviceNode.run_async_func(
-            self._ros_node.transfer_resource_to_another,
-            True,
+    async def transfer(self, resource: List[ResourceSlot], target_device: DeviceSlot, mount_resource: List[ResourceSlot]):
+        future = ROS2DeviceNode.run_async_func(self._ros_node.transfer_resource_to_another, True,
             **{
                 "plr_resources": resource,
                 "target_device_id": target_device,
                 "target_resources": mount_resource,
                 "sites": [None] * len(mount_resource),
-            },
-        )
+            })
         result = await future
         return result
 
+
     @action(
         description="扣电测试启动",
         handles=[
-            ActionInputHandle(
-                key="resource",
-                data_type="resource",
-                label="待转移资源",
-                data_key="resource",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="mount_resource",
-                data_type="resource",
-                label="目标孔位",
-                data_key="mount_resource",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="collector_mass",
-                data_type="collector_mass",
-                label="极流体质量",
-                data_key="collector_mass",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="active_material",
-                data_type="active_material",
-                label="活性物质含量",
-                data_key="active_material",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="capacity",
-                data_type="capacity",
-                label="克容量",
-                data_key="capacity",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="battery_system",
-                data_type="battery_system",
-                label="电池体系",
-                data_key="battery_system",
-                data_source=DataSource.HANDLE,
-            ),
-        ],
+            ActionInputHandle(key="resource", data_type="resource",
+                              label="待转移资源", data_key="resource", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="mount_resource", data_type="resource",
+                              label="目标孔位", data_key="mount_resource", data_source=DataSource.HANDLE),
+
+            ActionInputHandle(key="collector_mass", data_type="collector_mass",
+                              label="极流体质量", data_key="collector_mass", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="active_material", data_type="active_material",
+                              label="活性物质含量", data_key="active_material", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="capacity", data_type="capacity",
+                              label="克容量", data_key="capacity", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="battery_system", data_type="battery_system",
+                              label="电池体系", data_key="battery_system", data_source=DataSource.HANDLE),
+        ]
     )
     async def test(
-        self,
-        resource: List[ResourceSlot],
-        mount_resource: List[ResourceSlot],
-        collector_mass: List[float],
-        active_material: List[float],
-        capacity: List[float],
-        battery_system: list[str],
+        self, resource: List[ResourceSlot], mount_resource: List[ResourceSlot],  collector_mass: List[float], active_material: List[float], capacity: List[float], battery_system: list[str]
     ):
-        """
-        启动扣电测试。
-
-        Args:
-            resource[待测试资源]: 需要进行扣电测试的资源列表。
-            mount_resource[测试孔位]: 扣电测试使用的目标孔位列表。
-            collector_mass[极流体质量]: 每个样品对应的极流体质量。
-            active_material[活性物质含量]: 每个样品对应的活性物质含量。
-            capacity[克容量]: 每个样品对应的克容量，单位 mAh/g。
-            battery_system[电池体系]: 每个样品对应的电池体系名称。
-        """
         print(resource)
         print(mount_resource)
         print(collector_mass)
@@ -600,11 +415,16 @@ class VirtualWorkbench:
         auto_prefix=True,
         description="批量准备物料 - 虚拟起始节点, 生成A1-A5物料, 输出5个handle供后续节点使用",
         handles=[
-            ActionOutputHandle(key="channel_1", data_type="workbench_material", label="实验1", data_key="material_1", data_source=DataSource.EXECUTOR),  # noqa: E501
-            ActionOutputHandle(key="channel_2", data_type="workbench_material", label="实验2", data_key="material_2", data_source=DataSource.EXECUTOR),  # noqa: E501
-            ActionOutputHandle(key="channel_3", data_type="workbench_material", label="实验3", data_key="material_3", data_source=DataSource.EXECUTOR),  # noqa: E501
-            ActionOutputHandle(key="channel_4", data_type="workbench_material", label="实验4", data_key="material_4", data_source=DataSource.EXECUTOR),  # noqa: E501
-            ActionOutputHandle(key="channel_5", data_type="workbench_material", label="实验5", data_key="material_5", data_source=DataSource.EXECUTOR),  # noqa: E501
+            ActionOutputHandle(key="channel_1", data_type="workbench_material",
+                         label="实验1", data_key="material_1", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="channel_2", data_type="workbench_material",
+                         label="实验2", data_key="material_2", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="channel_3", data_type="workbench_material",
+                         label="实验3", data_key="material_3", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="channel_4", data_type="workbench_material",
+                         label="实验4", data_key="material_4", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="channel_5", data_type="workbench_material",
+                         label="实验5", data_key="material_5", data_source=DataSource.EXECUTOR),
         ],
     )
     def prepare_materials(
@@ -617,9 +437,6 @@ class VirtualWorkbench:
 
         作为工作流的起始节点, 生成指定数量的物料编号供后续节点使用。
         输出5个handle (material_1 ~ material_5), 分别对应实验1~5。
-
-        Args:
-            count[物料数量]: 要生成的物料数量，默认生成 5 个。
         """
         materials = [i for i in range(1, count + 1)]
 
@@ -640,11 +457,7 @@ class VirtualWorkbench:
                 LabSample(
                     sample_uuid=sample_uuid,
                     oss_path="",
-                    extra=(
-                        {"material_uuid": content}
-                        if isinstance(content, str)
-                        else (content.serialize() if content else {})
-                    ),
+                    extra={"material_uuid": content} if isinstance(content, str) else (content.serialize() if content else {}),
                 )
                 for sample_uuid, content in sample_uuids.items()
             ],
@@ -654,27 +467,12 @@ class VirtualWorkbench:
         auto_prefix=True,
         description="将物料从An位置移动到空闲加热台, 返回分配的加热台ID",
         handles=[
-            ActionInputHandle(
-                key="material_input",
-                data_type="workbench_material",
-                label="物料编号",
-                data_key="material_number",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionOutputHandle(
-                key="heating_station_output",
-                data_type="workbench_station",
-                label="加热台ID",
-                data_key="station_id",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="material_number_output",
-                data_type="workbench_material",
-                label="物料编号",
-                data_key="material_number",
-                data_source=DataSource.EXECUTOR,
-            ),
+            ActionInputHandle(key="material_input", data_type="workbench_material",
+                        label="物料编号", data_key="material_number", data_source=DataSource.HANDLE),
+            ActionOutputHandle(key="heating_station_output", data_type="workbench_station",
+                         label="加热台ID", data_key="station_id", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="material_number_output", data_type="workbench_material",
+                         label="物料编号", data_key="material_number", data_source=DataSource.EXECUTOR),
         ],
     )
     def move_to_heating_station(
@@ -686,9 +484,6 @@ class VirtualWorkbench:
         将物料从An位置移动到加热台
 
         多线程并发调用时, 会竞争机械臂使用权, 并自动查找空闲加热台
-
-        Args:
-            material_number[物料编号]: 要移动的物料编号，对应 A1、A2 等起始位置。
         """
         material_id = f"A{material_number}"
         task_desc = f"移动{material_id}到加热台"
@@ -751,8 +546,7 @@ class VirtualWorkbench:
                         oss_path="",
                         extra=(
                             {"material_uuid": content}
-                            if isinstance(content, str)
-                            else (content.serialize() if content else {})
+                            if isinstance(content, str) else (content.serialize() if content else {})
                         ),
                     )
                     for sample_uuid, content in sample_uuids.items()
@@ -775,8 +569,7 @@ class VirtualWorkbench:
                         oss_path="",
                         extra=(
                             {"material_uuid": content}
-                            if isinstance(content, str)
-                            else (content.serialize() if content else {})
+                            if isinstance(content, str) else (content.serialize() if content else {})
                         ),
                     )
                     for sample_uuid, content in sample_uuids.items()
@@ -788,34 +581,14 @@ class VirtualWorkbench:
         always_free=True,
         description="启动指定加热台的加热程序",
         handles=[
-            ActionInputHandle(
-                key="station_id_input",
-                data_type="workbench_station",
-                label="加热台ID",
-                data_key="station_id",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="material_number_input",
-                data_type="workbench_material",
-                label="物料编号",
-                data_key="material_number",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionOutputHandle(
-                key="heating_done_station",
-                data_type="workbench_station",
-                label="加热完成-加热台ID",
-                data_key="station_id",
-                data_source=DataSource.EXECUTOR,
-            ),
-            ActionOutputHandle(
-                key="heating_done_material",
-                data_type="workbench_material",
-                label="加热完成-物料编号",
-                data_key="material_number",
-                data_source=DataSource.EXECUTOR,
-            ),
+            ActionInputHandle(key="station_id_input", data_type="workbench_station",
+                        label="加热台ID", data_key="station_id", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="material_number_input", data_type="workbench_material",
+                        label="物料编号", data_key="material_number", data_source=DataSource.HANDLE),
+            ActionOutputHandle(key="heating_done_station", data_type="workbench_station",
+                         label="加热完成-加热台ID", data_key="station_id", data_source=DataSource.EXECUTOR),
+            ActionOutputHandle(key="heating_done_material", data_type="workbench_material",
+                         label="加热完成-物料编号", data_key="material_number", data_source=DataSource.EXECUTOR),
         ],
     )
     def start_heating(
@@ -826,10 +599,6 @@ class VirtualWorkbench:
     ) -> StartHeatingResult:
         """
         启动指定加热台的加热程序
-
-        Args:
-            station_id[加热台ID]: 要启动加热的加热台编号。
-            material_number[物料编号]: 当前加热台上的物料编号。
         """
         self.logger.info(f"[加热台{station_id}] 开始加热")
 
@@ -846,8 +615,7 @@ class VirtualWorkbench:
                         oss_path="",
                         extra=(
                             {"material_uuid": content}
-                            if isinstance(content, str)
-                            else (content.serialize() if content else {})
+                            if isinstance(content, str) else (content.serialize() if content else {})
                         ),
                     )
                     for sample_uuid, content in sample_uuids.items()
@@ -870,8 +638,7 @@ class VirtualWorkbench:
                             oss_path="",
                             extra=(
                                 {"material_uuid": content}
-                                if isinstance(content, str)
-                                else (content.serialize() if content else {})
+                                if isinstance(content, str) else (content.serialize() if content else {})
                             ),
                         )
                         for sample_uuid, content in sample_uuids.items()
@@ -891,8 +658,7 @@ class VirtualWorkbench:
                             oss_path="",
                             extra=(
                                 {"material_uuid": content}
-                                if isinstance(content, str)
-                                else (content.serialize() if content else {})
+                                if isinstance(content, str) else (content.serialize() if content else {})
                             ),
                         )
                         for sample_uuid, content in sample_uuids.items()
@@ -932,9 +698,7 @@ class VirtualWorkbench:
             self._update_data_status(f"加热台{station_id}加热中: {progress:.1f}%")
 
             if time.time() - last_countdown_log >= 5.0:
-                self.logger.info(
-                    f"[加热台{station_id}] {material_id} 剩余 {remaining:.1f}s"
-                )
+                self.logger.info(f"[加热台{station_id}] {material_id} 剩余 {remaining:.1f}s")
                 last_countdown_log = time.time()
 
             if elapsed >= self.HEATING_TIME:
@@ -951,9 +715,7 @@ class VirtualWorkbench:
                 self._active_tasks[material_id]["status"] = "heating_completed"
 
         self._update_data_status(f"加热台{station_id}加热完成")
-        self.logger.info(
-            f"[加热台{station_id}] {material_id}加热完成 (用时{self.HEATING_TIME}s)"
-        )
+        self.logger.info(f"[加热台{station_id}] {material_id}加热完成 (用时{self.HEATING_TIME}s)")
 
         return {
             "success": True,
@@ -967,8 +729,7 @@ class VirtualWorkbench:
                     oss_path="",
                     extra=(
                         {"material_uuid": content}
-                        if isinstance(content, str)
-                        else (content.serialize() if content else {})
+                        if isinstance(content, str) else (content.serialize() if content else {})
                     ),
                 )
                 for sample_uuid, content in sample_uuids.items()
@@ -979,20 +740,10 @@ class VirtualWorkbench:
         auto_prefix=True,
         description="将物料从加热台移动到输出位置Cn",
         handles=[
-            ActionInputHandle(
-                key="output_station_input",
-                data_type="workbench_station",
-                label="加热台ID",
-                data_key="station_id",
-                data_source=DataSource.HANDLE,
-            ),
-            ActionInputHandle(
-                key="output_material_input",
-                data_type="workbench_material",
-                label="物料编号",
-                data_key="material_number",
-                data_source=DataSource.HANDLE,
-            ),
+            ActionInputHandle(key="output_station_input", data_type="workbench_station",
+                        label="加热台ID", data_key="station_id", data_source=DataSource.HANDLE),
+            ActionInputHandle(key="output_material_input", data_type="workbench_material",
+                        label="物料编号", data_key="material_number", data_source=DataSource.HANDLE),
         ],
     )
     def move_to_output(
@@ -1003,10 +754,6 @@ class VirtualWorkbench:
     ) -> MoveToOutputResult:
         """
         将物料从加热台移动到输出位置Cn
-
-        Args:
-            station_id[加热台ID]: 已完成加热的加热台编号。
-            material_number[物料编号]: 要移动到输出位置的物料编号，对应 Cn。
         """
         output_number = material_number
 
@@ -1023,8 +770,7 @@ class VirtualWorkbench:
                         oss_path="",
                         extra=(
                             {"material_uuid": content}
-                            if isinstance(content, str)
-                            else (content.serialize() if content else {})
+                            if isinstance(content, str) else (content.serialize() if content else {})
                         ),
                     )
                     for sample_uuid, content in sample_uuids.items()
@@ -1048,8 +794,7 @@ class VirtualWorkbench:
                             oss_path="",
                             extra=(
                                 {"material_uuid": content}
-                                if isinstance(content, str)
-                                else (content.serialize() if content else {})
+                                if isinstance(content, str) else (content.serialize() if content else {})
                             ),
                         )
                         for sample_uuid, content in sample_uuids.items()
@@ -1069,8 +814,7 @@ class VirtualWorkbench:
                             oss_path="",
                             extra=(
                                 {"material_uuid": content}
-                                if isinstance(content, str)
-                                else (content.serialize() if content else {})
+                                if isinstance(content, str) else (content.serialize() if content else {})
                             ),
                         )
                         for sample_uuid, content in sample_uuids.items()
@@ -1152,8 +896,7 @@ class VirtualWorkbench:
                         oss_path="",
                         extra=(
                             {"material_uuid": content}
-                            if isinstance(content, str)
-                            else (content.serialize() if content else {})
+                            if isinstance(content, str) else (content.serialize() if content else {})
                         ),
                     )
                     for sample_uuid, content in sample_uuids.items()

unilabos/devices/workstation/README.md

@@ -1,9 +1,5 @@
 # 工作站抽象基类物料系统架构说明
 
-## 设计理念
-
-基于用户需求"请你帮我系统思考一下，工作站抽象基类的物料系统基类该如何构建"，我们最终确定了一个**PyLabRobot Deck为中心**的简化架构。
-
 ### 核心原则
 
 1. **PyLabRobot为物料管理核心**：使用PyLabRobot的Deck系统作为物料管理的基础，利用其成熟的Resource体系

unilabos/devices/workstation/bioyond_studio/bioyond_cell/20251229_多订单返回说明.md

@@ -0,0 +1,113 @@
+# Bioyond Cell 工作站 - 多订单返回示例
+
+本文档说明了 `create_orders` 函数如何收集并返回所有订单的完成报文。
+
+## 问题描述
+
+之前的实现只会等待并返回第一个订单的完成报文，如果有多个订单（例如从 Excel 解析出 3 个订单），只能得到第一个订单的推送信息。
+
+## 解决方案
+
+修改后的 `create_orders` 函数现在会：
+
+1. **提取所有 orderCode**：从 LIMS 接口返回的 `data` 列表中提取所有订单编号
+2. **逐个等待完成**：遍历所有 orderCode，调用 `wait_for_order_finish` 等待每个订单完成
+3. **收集所有报文**：将每个订单的完成报文存入 `all_reports` 列表
+4. **统一返回**：返回包含所有订单报文的 JSON 格式数据
+
+## 返回格式
+
+```json
+{
+    "status": "all_completed",
+    "total_orders": 3,
+    "reports": [
+        {
+            "token": "",
+            "request_time": "2025-12-24T15:32:09.2148671+08:00",
+            "data": {
+                "orderId": "3a1e614d-a082-c44a-60be-68647a35e6f1",
+                "orderCode": "BSO2025122400024",
+                "orderName": "DP20251224001",
+                "status": "30",
+                "workflowStatus": "completed",
+                "usedMaterials": [...]
+            }
+        },
+        {
+            "token": "",
+            "request_time": "2025-12-24T15:32:09.9999039+08:00",
+            "data": {
+                "orderId": "3a1e614d-a0a2-f7a9-9360-610021c9479d",
+                "orderCode": "BSO2025122400025",
+                "orderName": "DP20251224002",
+                "status": "30",
+                "workflowStatus": "completed",
+                "usedMaterials": [...]
+            }
+        },
+        {
+            "token": "",
+            "request_time": "2025-12-24T15:34:00.4139986+08:00",
+            "data": {
+                "orderId": "3a1e614d-a0cd-81ca-9f7f-2f4e93af01cd",
+                "orderCode": "BSO2025122400026",
+                "orderName": "DP20251224003",
+                "status": "30",
+                "workflowStatus": "completed",
+                "usedMaterials": [...]
+            }
+        }
+    ],
+    "original_response": {...}
+}
+```
+
+## 使用示例
+
+```python
+# 调用 create_orders
+result = workstation.create_orders("20251224.xlsx")
+
+# 访问返回数据
+print(f"总订单数: {result['total_orders']}")
+print(f"状态: {result['status']}")
+
+# 遍历所有订单的报文
+for i, report in enumerate(result['reports'], 1):
+    order_data = report.get('data', {})
+    print(f"\n订单 {i}:")
+    print(f"  orderCode: {order_data.get('orderCode')}")
+    print(f"  orderName: {order_data.get('orderName')}")
+    print(f"  status: {order_data.get('status')}")
+    print(f"  使用物料数: {len(order_data.get('usedMaterials', []))}")
+```
+
+## 控制台输出示例
+
+```
+[create_orders] 即将提交订单数量: 3
+[create_orders] 接口返回: {...}
+[create_orders] 等待 3 个订单完成: ['BSO2025122400024', 'BSO2025122400025', 'BSO2025122400026']
+[create_orders] 正在等待第 1/3 个订单: BSO2025122400024
+[create_orders] ✓ 订单 BSO2025122400024 完成
+[create_orders] 正在等待第 2/3 个订单: BSO2025122400025
+[create_orders] ✓ 订单 BSO2025122400025 完成
+[create_orders] 正在等待第 3/3 个订单: BSO2025122400026
+[create_orders] ✓ 订单 BSO2025122400026 完成
+[create_orders] 所有订单已完成，共收集 3 个报文
+实验记录本========================create_orders========================
+返回报文数量: 3
+报文 1: orderCode=BSO2025122400024, status=30
+报文 2: orderCode=BSO2025122400025, status=30
+报文 3: orderCode=BSO2025122400026, status=30
+========================
+```
+
+## 关键改进
+
+1. ✅ **等待所有订单**：不再只等待第一个订单，而是遍历所有 orderCode
+2. ✅ **收集完整报文**：每个订单的完整推送报文都被保存在 `reports` 数组中
+3. ✅ **详细日志**：清晰显示正在等待哪个订单，以及完成情况
+4. ✅ **错误处理**：即使某个订单失败，也会记录其状态信息
+5. ✅ **统一格式**：返回的 JSON 格式便于后续处理和分析

unilabos/devices/workstation/bioyond_studio/bioyond_cell/20260113_JSON配置迁移经验.md

@@ -0,0 +1,204 @@
+# BioyondCellWorkstation JSON 配置迁移经验总结
+
+**日期**: 2026-01-13  
+**目的**: 从 `config.py` 迁移到 JSON 配置文件
+
+---
+
+## 问题背景
+
+原系统通过 `config.py` 管理配置，导致：
+1. HTTP 服务重复启动（父类 `BioyondWorkstation` 和子类都启动）
+2. 配置分散在代码中，不便于管理
+3. 无法通过 JSON 统一配置所有参数
+
+---
+
+## 解决方案：嵌套配置结构
+
+### JSON 结构设计
+
+**正确示例** (嵌套在 `config` 中):
+```json
+{
+  "nodes": [{
+    "id": "bioyond_cell_workstation",
+    "config": {
+      "deck": {...},
+      "protocol_type": [],
+      "bioyond_config": {
+        "api_host": "http://172.16.11.219:44388",
+        "api_key": "8A819E5C",
+        "timeout": 30,
+        "HTTP_host": "172.16.11.206",
+        "HTTP_port": 8080,
+        "debug_mode": false,
+        "material_type_mappings": {...},
+        "warehouse_mapping": {...},
+        "solid_liquid_mappings": {...}
+      }
+    },
+    "data": {}
+  }]
+}
+```
+
+**关键点**：
+- ✅ `bioyond_config` 放在 `config` 中（会传递到 `__init__`）
+- ❌ **不要**放在 `data` 中（`data` 是运行时状态，不会传递）
+
+---
+
+## Python 代码适配
+
+### 1. 修改 `BioyondCellWorkstation.__init__` 签名
+
+**文件**: `bioyond_cell_workstation.py`
+
+```python
+def __init__(self, bioyond_config: dict = None, deck=None, protocol_type=None, **kwargs):
+    """
+    Args:
+        bioyond_config: 从 JSON 加载的配置字典
+        deck: Deck 配置
+        protocol_type: 协议类型
+    """
+    # 验证配置
+    if bioyond_config is None:
+        raise ValueError("需要 bioyond_config 参数")
+    
+    # 保存配置
+    self.bioyond_config = bioyond_config
+    
+    # 设置 HTTP 服务去重标志
+    self.bioyond_config["_disable_auto_http_service"] = True
+    
+    # 调用父类
+    super().__init__(bioyond_config=self.bioyond_config, deck=deck, **kwargs)
+```
+
+### 2. 替换全局变量引用
+
+**修改前**（使用全局变量）:
+```python
+from config import MATERIAL_TYPE_MAPPINGS, WAREHOUSE_MAPPING
+
+def create_sample(self, board_type, ...):
+    carrier_type_id = MATERIAL_TYPE_MAPPINGS[board_type][1]
+    location_id = WAREHOUSE_MAPPING[warehouse_name]["site_uuids"][location_code]
+```
+
+**修改后**（从配置读取）:
+```python
+def create_sample(self, board_type, ...):
+    carrier_type_id = self.bioyond_config['material_type_mappings'][board_type][1]
+    location_id = self.bioyond_config['warehouse_mapping'][warehouse_name]["site_uuids"][location_code]
+```
+
+### 3. 修复父类配置访问
+
+在 `station.py` 中安全访问配置默认值：
+
+```python
+# 修改前（会 KeyError）
+self._http_service_config = {
+    "host": bioyond_config.get("http_service_host", HTTP_SERVICE_CONFIG["http_service_host"])
+}
+
+# 修改后（安全访问）
+self._http_service_config = {
+    "host": bioyond_config.get("http_service_host", HTTP_SERVICE_CONFIG.get("http_service_host", ""))
+}
+```
+
+---
+
+## 常见陷阱
+
+### ❌ 错误1：将配置放在 `data` 字段
+```json
+"config": {"deck": {...}},
+"data": {"bioyond_config": {...}}  // ❌ 不会传递到 __init__
+```
+
+### ❌ 错误2：扁平化配置（已废弃方案）
+虽然扁平化也能工作，但不推荐：
+```json
+"config": {
+  "deck": {...},
+  "api_host": "...",     // ❌ 不够清晰
+  "api_key": "...",
+  "HTTP_host": "..."
+}
+```
+
+### ❌ 错误3：忘记替换全局变量引用
+代码中直接使用 `MATERIAL_TYPE_MAPPINGS` 等全局变量会导致 `NameError`。
+
+---
+
+## 云端同步注意事项
+
+使用 `--upload_registry` 时，云端配置可能覆盖本地配置：
+- 首次上传时确保 JSON 完整
+- 或使用新的 `ak/sk` 避免旧配置干扰
+- 调试时可暂时移除 `--upload_registry` 参数
+
+---
+
+## 验证清单
+
+启动成功后应看到：
+```
+✅ 从 JSON 配置加载 bioyond_config 成功
+   API Host: http://...
+   HTTP Service: ...
+✅ BioyondCellWorkstation 初始化完成
+Loaded ResourceTreeSet with ... nodes
+```
+
+运行时不应出现：
+- ❌ `NameError: name 'MATERIAL_TYPE_MAPPINGS' is not defined`
+- ❌ `KeyError: 'http_service_host'`
+- ❌ `bioyond_config 缺少必需参数`
+
+---
+
+## 调试经验
+
+1. **添加调试日志**查看参数传递链路：
+   - `graphio.py`: JSON 加载后的 config 内容
+   - `initialize_device.py`: `device_config.res_content.config` 的键
+   - `bioyond_cell_workstation.py`: `__init__` 接收到的参数
+
+2. **config vs data 区别**：
+   - `config`: 初始化参数，传递给 `__init__`
+   - `data`: 运行时状态，不传递给 `__init__`
+
+3. **参数名必须匹配**：
+   - JSON 中的键名必须与 `__init__` 参数名完全一致
+
+4. **调试代码清理**：完成后记得删除调试日志（🔍 DEBUG 标记）
+
+---
+
+## 修改文件清单
+
+| 文件 | 修改内容 |
+|------|----------|
+| `yibin_electrolyte_config.json` | 创建嵌套 `config.bioyond_config` 结构 |
+| `bioyond_cell_workstation.py` | 修改 `__init__` 接收 `bioyond_config`，替换所有全局变量引用 |
+| `station.py` | 安全访问 `HTTP_SERVICE_CONFIG` 默认值 |
+
+---
+
+## 参考代码位置
+
+- JSON 配置示例: `yibin_electrolyte_config.json` L12-L353
+- `__init__` 实现: `bioyond_cell_workstation.py` L39-L94
+- 全局变量替换示例: `bioyond_cell_workstation.py` L2005, L1863, L1966
+- HTTP 服务配置: `station.py` L629-L634
+
+---
+
+**总结**: 使用嵌套结构将所有配置放在 `config.bioyond_config` 中，修改 `__init__` 直接接收该参数，并替换所有全局变量引用为 `self.bioyond_config` 访问。

unilabos/devices/workstation/bioyond_studio/bioyond_cell/20260113_配置迁移修改总结.md

@@ -0,0 +1,312 @@
+# BioyondCell 配置迁移修改总结
+
+**日期**: 2026-01-13  
+**目标**: 从 `config.py` 完全迁移到 JSON 配置，消除所有全局变量依赖
+
+---
+
+## 📋 修改概览
+
+本次修改完成了 BioyondCell 模块从 Python 配置文件到 JSON 配置的完整迁移，并清理了所有对 `config.py` 全局变量的依赖。
+
+### 核心成果
+
+- ✅ 完全移除对 `config.py` 的导入依赖
+- ✅ 使用嵌套 JSON 结构 `config.bioyond_config`
+- ✅ 修复 7 处 `bioyond_cell_workstation.py` 中的全局变量引用
+- ✅ 修复 3 处其他文件中的全局变量引用
+- ✅ HTTP 服务去重机制完善
+- ✅ 系统成功启动并正常运行
+
+---
+
+## 🔧 修改文件清单
+
+### 1. JSON 配置文件
+
+**文件**: `yibin_electrolyte_config.json`
+
+**修改**:
+- 采用嵌套结构将所有配置放在 `config.bioyond_config` 中
+- 包含：`api_host`, `api_key`, `HTTP_host`, `HTTP_port`, `material_type_mappings`, `warehouse_mapping`, `solid_liquid_mappings` 等
+
+**示例结构**:
+```json
+{
+  "nodes": [{
+    "id": "bioyond_cell_workstation",
+    "config": {
+      "deck": {...},
+      "protocol_type": [],
+      "bioyond_config": {
+        "api_host": "http://172.16.11.219:44388",
+        "api_key": "8A819E5C",
+        "HTTP_host": "172.16.11.206",
+        "HTTP_port": 8080,
+        "material_type_mappings": {...},
+        "warehouse_mapping": {...},
+        "solid_liquid_mappings": {...}
+      }
+    }
+  }]
+}
+```
+
+---
+
+### 2. bioyond_cell_workstation.py
+
+**位置**: `unilabos/devices/workstation/bioyond_studio/bioyond_cell/bioyond_cell_workstation.py`
+
+#### 修改 A: `__init__` 方法签名 (L39-99)
+
+**修改前**:
+```python
+def __init__(self, deck=None, protocol_type=None, **kwargs):
+    # 从 kwargs 收集配置字段
+    self.bioyond_config = {}
+    for field in bioyond_field_names:
+        if field in kwargs:
+            self.bioyond_config[field] = kwargs.pop(field)
+```
+
+**修改后**:
+```python
+def __init__(self, bioyond_config: dict = None, deck=None, protocol_type=None, **kwargs):
+    """直接接收 bioyond_config 参数"""
+    if bioyond_config is None:
+        raise ValueError("需要 bioyond_config 参数")
+    
+    self.bioyond_config = bioyond_config
+    
+    # 设置 HTTP 服务去重标志
+    self.bioyond_config["_disable_auto_http_service"] = True
+    
+    super().__init__(bioyond_config=self.bioyond_config, deck=deck, **kwargs)
+```
+
+#### 修改 B: 替换全局变量引用 (7 处)
+
+| 位置 | 原代码 | 修改后 |
+|------|--------|--------|
+| L2005 | `MATERIAL_TYPE_MAPPINGS[board_type][1]` | `self.bioyond_config['material_type_mappings'][board_type][1]` |
+| L2006 | `MATERIAL_TYPE_MAPPINGS[bottle_type][1]` | `self.bioyond_config['material_type_mappings'][bottle_type][1]` |
+| L2009 | `WAREHOUSE_MAPPING` | `self.bioyond_config['warehouse_mapping']` |
+| L2013 | `WAREHOUSE_MAPPING[warehouse_name]` | `self.bioyond_config['warehouse_mapping'][warehouse_name]` |
+| L2017 | `WAREHOUSE_MAPPING[warehouse_name]["site_uuids"]` | `self.bioyond_config['warehouse_mapping'][warehouse_name]["site_uuids"]` |
+| L1863 | `SOLID_LIQUID_MAPPINGS.get(material_name)` | `self.bioyond_config.get('solid_liquid_mappings', {}).get(material_name)` |
+| L1966, L1976 | `MATERIAL_TYPE_MAPPINGS.items()` | `self.bioyond_config['material_type_mappings'].items()` |
+
+---
+
+### 3. station.py
+
+**位置**: `unilabos/devices/workstation/bioyond_studio/station.py`
+
+#### 修改 A: 删除 config 导入 (L26-28)
+
+**修改前**:
+```python
+from unilabos.devices.workstation.bioyond_studio.config import (
+    API_CONFIG, WORKFLOW_MAPPINGS, MATERIAL_TYPE_MAPPINGS, WAREHOUSE_MAPPING, HTTP_SERVICE_CONFIG
+)
+```
+
+**修改后**:
+```python
+# 已删除此导入
+```
+
+#### 修改 B: `_create_communication_module` 方法 (L691-702)
+
+**修改前**:
+```python
+def _create_communication_module(self, config: Optional[Dict[str, Any]] = None) -> None:
+    default_config = {
+        **API_CONFIG,
+        "workflow_mappings": WORKFLOW_MAPPINGS,
+        "material_type_mappings": MATERIAL_TYPE_MAPPINGS,
+        "warehouse_mapping": WAREHOUSE_MAPPING
+    }
+    if config:
+        self.bioyond_config = {**default_config, **config}
+    else:
+        self.bioyond_config = default_config
+```
+
+**修改后**:
+```python
+def _create_communication_module(self, config: Optional[Dict[str, Any]] = None) -> None:
+    """创建Bioyond通信模块"""
+    # 使用传入的 config 参数（来自 bioyond_config）
+    # 不再依赖全局变量 API_CONFIG 等
+    if config:
+        self.bioyond_config = config
+    else:
+        # 如果没有传入配置，创建空配置（用于测试或兼容性）
+        self.bioyond_config = {}
+    
+    self.hardware_interface = BioyondV1RPC(self.bioyond_config)
+```
+
+#### 修改 C: HTTP 服务配置 (L627-632)
+
+**修改前**:
+```python
+self._http_service_config = {
+    "host": bioyond_config.get("http_service_host", HTTP_SERVICE_CONFIG.get("http_service_host", "")),
+    "port": bioyond_config.get("http_service_port", HTTP_SERVICE_CONFIG.get("http_service_port", 0))
+}
+```
+
+**修改后**:
+```python
+self._http_service_config = {
+    "host": bioyond_config.get("http_service_host", bioyond_config.get("HTTP_host", "")),
+    "port": bioyond_config.get("http_service_port", bioyond_config.get("HTTP_port", 0))
+}
+```
+
+---
+
+### 4. bioyond_rpc.py
+
+**位置**: `unilabos/devices/workstation/bioyond_studio/bioyond_rpc.py`
+
+#### 修改 A: 删除 config 导入 (L12)
+
+**修改前**:
+```python
+from unilabos.devices.workstation.bioyond_studio.config import LOCATION_MAPPING
+```
+
+**修改后**:
+```python
+# 已删除此导入
+```
+
+#### 修改 B: `material_outbound` 方法 (L278-280)
+
+**修改前**:
+```python
+def material_outbound(self, material_id: str, location_name: str, quantity: int) -> dict:
+    """指定库位出库物料（通过库位名称）"""
+    location_id = LOCATION_MAPPING.get(location_name, location_name)
+```
+
+**修改后**:
+```python
+def material_outbound(self, material_id: str, location_name: str, quantity: int) -> dict:
+    """指定库位出库物料（通过库位名称）"""
+    # location_name 参数实际上应该直接是 location_id (UUID)
+    location_id = location_name
+```
+
+**说明**: `LOCATION_MAPPING` 在 `config-0113.py` 中本来就是空字典 `{}`，所以直接使用 `location_name` 逻辑等价。
+
+---
+
+## 🎯 关键设计决策
+
+### 1. 嵌套 vs 扁平配置
+
+**选择**: 嵌套结构 `config.bioyond_config`
+
+**理由**:
+- ✅ 语义清晰，配置分组明确
+- ✅ 参数传递直观，直接对应 `__init__` 参数
+- ✅ 易于维护，不需要硬编码字段列表
+- ✅ 符合 UniLab 设计模式
+
+### 2. HTTP 服务去重
+
+**实现**: 子类设置 `_disable_auto_http_service` 标志
+
+```python
+# bioyond_cell_workstation.py
+self.bioyond_config["_disable_auto_http_service"] = True
+
+# station.py (post_init)
+if self.bioyond_config.get("_disable_auto_http_service"):
+    logger.info("子类已自行管理HTTP服务，跳过自动启动")
+    return
+```
+
+### 3. 全局变量替换策略
+
+**原则**: 所有配置从 `self.bioyond_config` 获取
+
+**模式**:
+```python
+# 修改前
+from config import MATERIAL_TYPE_MAPPINGS
+carrier_type_id = MATERIAL_TYPE_MAPPINGS[board_type][1]
+
+# 修改后
+carrier_type_id = self.bioyond_config['material_type_mappings'][board_type][1]
+```
+
+---
+
+## ✅ 验证结果
+
+### 启动成功日志
+```
+✅ 从 JSON 配置加载 bioyond_config 成功
+   API Host: http://172.16.11.219:44388
+   HTTP Service: 172.16.11.206:8080
+🔧 已设置 _disable_auto_http_service 标志，防止 HTTP 服务重复启动
+✅ BioyondCellWorkstation 初始化完成
+Loaded ResourceTreeSet with 1 trees, 1785 total nodes
+```
+
+### 功能验证
+- ✅ 订单创建 (`create_orders_v2`)
+- ✅ 质量比计算
+- ✅ 物料转移 (`transfer_3_to_2_to_1`)
+- ✅ HTTP 报送接收 (step_finish, sample_finish, order_finish)
+- ✅ 等待机制 (`wait_for_order_finish`)
+- ✅ 仓库 UUID 映射
+- ✅ 物料类型映射
+
+---
+
+## 📚 相关文档
+
+- **配置迁移经验**: `2026-01-13_JSON配置迁移经验.md`
+- **任务清单**: `C:\Users\AndyXie\.gemini\antigravity\brain\...\task.md`
+- **实施计划**: `C:\Users\AndyXie\.gemini\antigravity\brain\...\implementation_plan.md`
+
+---
+
+## ⚠️ 注意事项
+
+### 其他工作站模块
+
+以下文件仍在使用 `config.py` 全局变量（未包含在本次修改中）:
+- `reaction_station.py` - 使用 `API_CONFIG`
+- `experiment.py` - 使用 `API_CONFIG`, `WORKFLOW_MAPPINGS`, `MATERIAL_TYPE_MAPPINGS`
+- `dispensing_station.py` - 使用 `API_CONFIG`, `WAREHOUSE_MAPPING`
+- `station.py` L176, L177, L529, L530 - 动态导入 `WAREHOUSE_MAPPING`
+
+**建议**: 后续可以统一迁移这些模块到 JSON 配置。
+
+### config.py 文件
+
+`config.py` 文件已恢复但**不再被 bioyond_cell 使用**。可以：
+- 保留作为其他模块的参考
+- 或者完全删除（如果其他模块也迁移完成）
+
+---
+
+## 🚀 下一步建议
+
+1. **清理调试代码** ✅ (已完成)
+2. **提交代码到 Git**
+3. **迁移其他工作站模块** (可选)
+4. **更新文档和启动脚本**
+
+---
+
+**修改完成日期**: 2026-01-13  
+**系统状态**: ✅ 稳定运行

unilabos/devices/workstation/bioyond_studio/bioyond_cell/批量出库模板使用说明.md

@@ -0,0 +1,157 @@
+# 批量出库 Excel 模板使用说明
+
+**文件**: `outbound_template.xlsx`  
+**用途**: 配合 `auto_batch_outbound_from_xlsx()` 方法进行批量出库操作  
+**API 端点**: `/api/lims/storage/auto-batch-out-bound`
+
+---
+
+## 📋 Excel 列说明
+
+| 列名 | 说明 | 示例 | 必填 |
+|------|------|------|------|
+| `locationId` | **库位 ID（UUID）** | `3a19da43-57b5-294f-d663-154a1cc32270` | ✅ 是 |
+| `warehouseId` | **仓库 ID 或名称** | `配液站内试剂仓库` | ✅ 是 |
+| `quantity` | **出库数量** | `1.0`, `2.0` | ✅ 是 |
+| `x` | **X 坐标（库位横向位置）** | `1`, `2`, `3` | ✅ 是 |
+| `y` | **Y 坐标（库位纵向位置）** | `1`, `2`, `3` | ✅ 是 |
+| `z` | **Z 坐标（库位层数/高度）** | `1`, `2`, `3` | ✅ 是 |
+| `备注说明` | 可选备注信息 | `配液站内试剂仓库-A01` | ❌ 否 |
+
+### 📐 坐标说明
+
+**x, y, z** 是库位在仓库内的**三维坐标**：
+
+```
+仓库（例如 WH4）
+├── Z=1（第1层/加样头面）
+│   ├── X=1, Y=1（位置 A）
+│   ├── X=2, Y=1（位置 B）
+│   ├── X=3, Y=1（位置 C）
+│   └── ...
+│
+└── Z=2（第2层/原液瓶面）
+    ├── X=1, Y=1（位置 A）
+    ├── X=2, Y=1（位置 B）
+    └── ...
+```
+
+- **warehouseId**: 指定哪个仓库（WH3, WH4, 配液站等）
+- **x, y, z**: 在该仓库内的三维坐标
+- **locationId**: 该坐标位置的唯一 UUID
+
+### 🎯 起点与终点
+
+**重要说明**：批量出库模板**只规定了出库的"起点"**（从哪里取物料），**没有指定"终点"**（放到哪里）。
+
+```
+出库流程：
+起点（Excel 指定） → ？终点（LIMS/工作流决定）
+    ↓
+locationId, x, y, z    → 由 LIMS 系统或当前工作流自动分配
+```
+
+**终点由以下方式确定：**
+- **LIMS 系统自动分配**：根据当前任务自动规划目标位置
+- **工作流预定义**：在创建出库任务时已绑定目标位置
+- **暂存区**：默认放到出库暂存区，等待下一步操作
+
+💡 **对比**：上料操作（`auto_feeding4to3`）则有 `targetWH` 参数可以指定目标仓库
+
+---
+
+## 🔍 如何获取 UUID？
+
+### 方法 1：从配置文件获取
+
+参考 `yibin_electrolyte_config.json` 中的 `warehouse_mapping`：
+
+```json
+{
+  "warehouse_mapping": {
+    "配液站内试剂仓库": {
+      "site_uuids": {
+        "A01": "3a19da43-57b5-294f-d663-154a1cc32270",
+        "B01": "3a19da43-57b5-7394-5f49-54efe2c9bef2",
+        "C01": "3a19da43-57b5-5e75-552f-8dbd0ad1075f"
+      }
+    },
+    "手动堆栈": {
+      "site_uuids": {
+        "A01": "3a19deae-2c7a-36f5-5e41-02c5b66feaea",
+        "A02": "3a19deae-2c7a-dc6d-c41e-ef285d946cfe"
+      }
+    }
+  }
+}
+```
+
+### 方法 2：通过 API 查询
+
+```python
+material_info = hardware_interface.material_id_query(workflow_id)
+locations = material_info.get("locations", [])
+```
+
+---
+
+## 📝 填写示例
+
+### 示例 1：从配液站内试剂仓库出库
+
+| locationId | warehouseId | quantity | x | y | z | 备注说明 |
+|------------|-------------|----------|---|---|---|----------|
+| `3a19da43-57b5-294f-d663-154a1cc32270` | 配液站内试剂仓库 | 1 | 1 | 1 | 1 | A01 位置 |
+| `3a19da43-57b5-7394-5f49-54efe2c9bef2` | 配液站内试剂仓库 | 2 | 2 | 1 | 1 | B01 位置 |
+
+### 示例 2：从手动堆栈出库
+
+| locationId | warehouseId | quantity | x | y | z | 备注说明 |
+|------------|-------------|----------|---|---|---|----------|
+| `3a19deae-2c7a-36f5-5e41-02c5b66feaea` | 手动堆栈 | 1 | 1 | 1 | 1 | A01 |
+| `3a19deae-2c7a-dc6d-c41e-ef285d946cfe` | 手动堆栈 | 1 | 1 | 2 | 1 | A02 |
+
+---
+
+## 💻 使用方法
+
+```python
+from bioyond_cell_workstation import BioyondCellWorkstation
+
+# 初始化工作站
+workstation = BioyondCellWorkstation(config=config, deck=deck)
+
+# 调用批量出库方法
+result = workstation.auto_batch_outbound_from_xlsx(
+    xlsx_path="outbound_template.xlsx"
+)
+```
+
+---
+
+## ⚠️ 注意事项
+
+1. **locationId 必须是有效的 UUID**，不能使用库位名称
+2. **x, y, z 坐标必须与 locationId 对应**，表示该库位在仓库内的位置
+3. **quantity 必须是数字**，可以是整数或浮点数
+4. Excel 文件必须包含表头行
+5. 空行会被自动跳过
+6. 确保 UUID 与实际库位对应，否则 API 会报错
+
+---
+
+## 📚 相关文件
+
+- **配置文件**: `yibin_electrolyte_config.json`
+- **Python 代码**: `bioyond_cell_workstation.py` (L630-695)
+- **生成脚本**: `create_outbound_template.py`
+- **上料模板**: `material_template.xlsx`
+
+---
+
+## 🔄 重新生成模板
+
+```bash
+conda activate newunilab
+python create_outbound_template.py
+```

unilabos/devices/workstation/bioyond_studio/bioyond_rpc.py

@@ -9,7 +9,7 @@ from datetime import datetime, timezone
 from unilabos.device_comms.rpc import BaseRequest
 from typing import Optional, List, Dict, Any
 import json
-from unilabos.devices.workstation.bioyond_studio.config import LOCATION_MAPPING
+
 
 
 class SimpleLogger:
@@ -49,6 +49,14 @@ class BioyondV1RPC(BaseRequest):
         self.config = config
         self.api_key = config["api_key"]
         self.host = config["api_host"]
+
+        # 初始化 location_mapping
+        # 直接从 warehouse_mapping 构建，确保数据源所谓的单一和结构化
+        self.location_mapping = {}
+        warehouse_mapping = self.config.get("warehouse_mapping", {})
+        for warehouse_name, warehouse_config in warehouse_mapping.items():
+            if "site_uuids" in warehouse_config:
+                self.location_mapping.update(warehouse_config["site_uuids"])
         self._logger = SimpleLogger()
         self.material_cache = {}
         self._load_material_cache()
@@ -176,7 +184,40 @@ class BioyondV1RPC(BaseRequest):
             return {}
 
         print(f"add material data: {response['data']}")
-        return response.get("data", {})
+
+        # 自动更新缓存
+        data = response.get("data", {})
+        if data:
+            if isinstance(data, str):
+                # 如果返回的是字符串，通常是ID
+                mat_id = data
+                name = params.get("name")
+            else:
+                # 如果返回的是字典，尝试获取name和id
+                name = data.get("name") or params.get("name")
+                mat_id = data.get("id")
+
+            if name and mat_id:
+                self.material_cache[name] = mat_id
+                print(f"已自动更新缓存: {name} -> {mat_id}")
+
+            # 处理返回数据中的 details (如果有)
+            # 有些 API 返回结构可能直接包含 details，或者在 data 字段中
+            details = data.get("details", []) if isinstance(data, dict) else []
+            if not details and isinstance(data, dict):
+                 details = data.get("detail", [])
+
+            if details:
+                for detail in details:
+                    d_name = detail.get("name")
+                    # 尝试从不同字段获取 ID
+                    d_id = detail.get("id") or detail.get("detailMaterialId")
+
+                    if d_name and d_id:
+                        self.material_cache[d_name] = d_id
+                        print(f"已自动更新 detail 缓存: {d_name} -> {d_id}")
+
+        return data
 
     def query_matial_type_id(self, data) -> list:
         """查找物料typeid"""
@@ -203,7 +244,7 @@ class BioyondV1RPC(BaseRequest):
             params={
                 "apiKey": self.api_key,
                 "requestTime": self.get_current_time_iso8601(),
-                "data": {},
+                "data": 0,
             })
         if not response or response['code'] != 1:
             return []
@@ -273,11 +314,19 @@ class BioyondV1RPC(BaseRequest):
 
         if not response or response['code'] != 1:
             return {}
+
+        # 自动更新缓存 - 移除被删除的物料
+        for name, mid in list(self.material_cache.items()):
+            if mid == material_id:
+                del self.material_cache[name]
+                print(f"已从缓存移除物料: {name}")
+                break
+
         return response.get("data", {})
 
     def material_outbound(self, material_id: str, location_name: str, quantity: int) -> dict:
         """指定库位出库物料（通过库位名称）"""
-        location_id = LOCATION_MAPPING.get(location_name, location_name)
+        location_id = self.location_mapping.get(location_name, location_name)
 
         params = {
             "materialId": material_id,
@@ -1103,6 +1152,10 @@ class BioyondV1RPC(BaseRequest):
                     for detail_material in detail_materials:
                         detail_name = detail_material.get("name")
                         detail_id = detail_material.get("detailMaterialId")
+                        if not detail_id:
+                            # 尝试其他可能的字段
+                            detail_id = detail_material.get("id")
+
                         if detail_name and detail_id:
                             self.material_cache[detail_name] = detail_id
                             print(f"加载detail材料: {detail_name} -> ID: {detail_id}")
@@ -1123,6 +1176,14 @@ class BioyondV1RPC(BaseRequest):
             print(f"从缓存找到材料: {material_name_or_id} -> ID: {material_id}")
             return material_id
 
+        # 如果缓存中没有，尝试刷新缓存
+        print(f"缓存中未找到材料 '{material_name_or_id}'，尝试刷新缓存...")
+        self.refresh_material_cache()
+        if material_name_or_id in self.material_cache:
+            material_id = self.material_cache[material_name_or_id]
+            print(f"刷新缓存后找到材料: {material_name_or_id} -> ID: {material_id}")
+            return material_id
+
         print(f"警告: 未在缓存中找到材料名称 '{material_name_or_id}'，将使用原值")
         return material_name_or_id
 

unilabos/devices/workstation/bioyond_studio/config.py

@@ -1,142 +0,0 @@
-# config.py
-"""
-配置文件 - 包含所有配置信息和映射关系
-"""
-
-# API配置
-API_CONFIG = {
-    "api_key": "",
-    "api_host": ""
-}
-
-# 工作流映射配置
-WORKFLOW_MAPPINGS = {
-    "reactor_taken_out": "",
-    "reactor_taken_in": "",
-    "Solid_feeding_vials": "",
-    "Liquid_feeding_vials(non-titration)": "",
-    "Liquid_feeding_solvents": "",
-    "Liquid_feeding(titration)": "",
-    "liquid_feeding_beaker": "",
-    "Drip_back": "",
-}
-
-# 工作流名称到DisplaySectionName的映射
-WORKFLOW_TO_SECTION_MAP = {
-    'reactor_taken_in': '反应器放入',
-    'liquid_feeding_beaker': '液体投料-烧杯',
-    'Liquid_feeding_vials(non-titration)': '液体投料-小瓶（非滴定）',
-    'Liquid_feeding_solvents': '液体投料-溶剂',
-    'Solid_feeding_vials': '固体投料-小瓶',
-    'Liquid_feeding(titration)': '液体投料-滴定',
-    'reactor_taken_out': '反应器取出'
-}
-
-# 库位映射配置
-WAREHOUSE_MAPPING = {
-    "粉末堆栈": {
-        "uuid": "",
-        "site_uuids": {
-            # 样品板
-            "A1": "3a14198e-6929-31f0-8a22-0f98f72260df",
-            "A2": "3a14198e-6929-4379-affa-9a2935c17f99",
-            "A3": "3a14198e-6929-56da-9a1c-7f5fbd4ae8af",
-            "A4": "3a14198e-6929-5e99-2b79-80720f7cfb54",
-            "B1": "3a14198e-6929-f525-9a1b-1857552b28ee",
-            "B2": "3a14198e-6929-bf98-0fd5-26e1d68bf62d",
-            "B3": "3a14198e-6929-2d86-a468-602175a2b5aa",
-            "B4": "3a14198e-6929-1a98-ae57-e97660c489ad",
-            # 分装板
-            "C1": "3a14198e-6929-46fe-841e-03dd753f1e4a",
-            "C2": "3a14198e-6929-1bc9-a9bd-3b7ca66e7f95",
-            "C3": "3a14198e-6929-72ac-32ce-9b50245682b8",
-            "C4": "3a14198e-6929-3bd8-e6c7-4a9fd93be118",
-            "D1": "3a14198e-6929-8a0b-b686-6f4a2955c4e2",
-            "D2": "3a14198e-6929-dde1-fc78-34a84b71afdf",
-            "D3": "3a14198e-6929-a0ec-5f15-c0f9f339f963",
-            "D4": "3a14198e-6929-7ac8-915a-fea51cb2e884"
-        }
-    },
-    "溶液堆栈": {
-        "uuid": "",
-        "site_uuids": {
-            "A1": "3a14198e-d724-e036-afdc-2ae39a7f3383",
-            "A2": "3a14198e-d724-afa4-fc82-0ac8a9016791",
-            "A3": "3a14198e-d724-ca48-bb9e-7e85751e55b6",
-            "A4": "3a14198e-d724-df6d-5e32-5483b3cab583",
-            "B1": "3a14198e-d724-d818-6d4f-5725191a24b5",
-            "B2": "3a14198e-d724-be8a-5e0b-012675e195c6",
-            "B3": "3a14198e-d724-cc1e-5c2c-228a130f40a8",
-            "B4": "3a14198e-d724-1e28-c885-574c3df468d0",
-            "C1": "3a14198e-d724-b5bb-adf3-4c5a0da6fb31",
-            "C2": "3a14198e-d724-ab4e-48cb-817c3c146707",
-            "C3": "3a14198e-d724-7f18-1853-39d0c62e1d33",
-            "C4": "3a14198e-d724-28a2-a760-baa896f46b66",
-            "D1": "3a14198e-d724-d378-d266-2508a224a19f",
-            "D2": "3a14198e-d724-f56e-468b-0110a8feb36a",
-            "D3": "3a14198e-d724-0cf1-dea9-a1f40fe7e13c",
-            "D4": "3a14198e-d724-0ddd-9654-f9352a421de9"
-        }
-    },
-    "试剂堆栈": {
-        "uuid": "",
-        "site_uuids": {
-            "A1": "3a14198c-c2cf-8b40-af28-b467808f1c36",
-            "A2": "3a14198c-c2d0-f3e7-871a-e470d144296f",
-            "A3": "3a14198c-c2d0-dc7d-b8d0-e1d88cee3094",
-            "A4": "3a14198c-c2d0-2070-efc8-44e245f10c6f",
-            "B1": "3a14198c-c2d0-354f-39ad-642e1a72fcb8",
-            "B2": "3a14198c-c2d0-1559-105d-0ea30682cab4",
-            "B3": "3a14198c-c2d0-725e-523d-34c037ac2440",
-            "B4": "3a14198c-c2d0-efce-0939-69ca5a7dfd39"
-        }
-    }
-}
-
-# 物料类型配置
-MATERIAL_TYPE_MAPPINGS = {
-    "烧杯": ("BIOYOND_PolymerStation_1FlaskCarrier", "3a14196b-24f2-ca49-9081-0cab8021bf1a"),
-    "试剂瓶": ("BIOYOND_PolymerStation_1BottleCarrier", ""),
-    "样品板": ("BIOYOND_PolymerStation_6StockCarrier", "3a14196e-b7a0-a5da-1931-35f3000281e9"),
-    "分装板": ("BIOYOND_PolymerStation_6VialCarrier", "3a14196e-5dfe-6e21-0c79-fe2036d052c4"),
-    "样品瓶": ("BIOYOND_PolymerStation_Solid_Stock", "3a14196a-cf7d-8aea-48d8-b9662c7dba94"),
-    "90%分装小瓶": ("BIOYOND_PolymerStation_Solid_Vial", "3a14196c-cdcf-088d-dc7d-5cf38f0ad9ea"),
-    "10%分装小瓶": ("BIOYOND_PolymerStation_Liquid_Vial", "3a14196c-76be-2279-4e22-7310d69aed68"),
-}
-
-# 步骤参数配置（各工作流的步骤UUID）
-WORKFLOW_STEP_IDS = {
-    "reactor_taken_in": {
-        "config": ""
-    },
-    "liquid_feeding_beaker": {
-        "liquid": "",
-        "observe": ""
-    },
-    "liquid_feeding_vials_non_titration": {
-        "liquid": "",
-        "observe": ""
-    },
-    "liquid_feeding_solvents": {
-        "liquid": "",
-        "observe": ""
-    },
-    "solid_feeding_vials": {
-        "feeding": "",
-        "observe": ""
-    },
-    "liquid_feeding_titration": {
-        "liquid": "",
-        "observe": ""
-    },
-    "drip_back": {
-        "liquid": "",
-        "observe": ""
-    }
-}
-
-LOCATION_MAPPING = {}
-
-ACTION_NAMES = {}
-
-HTTP_SERVICE_CONFIG = {}

unilabos/devices/workstation/bioyond_studio/config.py.deprecated

@@ -0,0 +1,329 @@
+# config.py
+"""
+Bioyond工作站配置文件
+包含API配置、工作流映射、物料类型映射、仓库库位映射等所有配置信息
+"""
+
+from unilabos.resources.bioyond.decks import BIOYOND_PolymerReactionStation_Deck
+
+# ============================================================================
+# 基础配置
+# ============================================================================
+
+# API配置
+API_CONFIG = {
+    "api_key": "DE9BDDA0",
+    "api_host": "http://192.168.1.200:44402"
+}
+
+# HTTP 报送服务配置
+HTTP_SERVICE_CONFIG = {
+    "http_service_host": "127.0.0.1",  # 监听地址
+    "http_service_port": 8080,        # 监听端口
+}
+
+# Deck配置 - 反应站工作台配置
+DECK_CONFIG = BIOYOND_PolymerReactionStation_Deck(setup=True)
+
+# ============================================================================
+# 工作流配置
+# ============================================================================
+
+# 工作流ID映射
+WORKFLOW_MAPPINGS = {
+    "reactor_taken_out": "3a16081e-4788-ca37-eff4-ceed8d7019d1",
+    "reactor_taken_in": "3a160df6-76b3-0957-9eb0-cb496d5721c6",
+    "Solid_feeding_vials": "3a160877-87e7-7699-7bc6-ec72b05eb5e6",
+    "Liquid_feeding_vials(non-titration)": "3a167d99-6158-c6f0-15b5-eb030f7d8e47",
+    "Liquid_feeding_solvents": "3a160824-0665-01ed-285a-51ef817a9046",
+    "Liquid_feeding(titration)": "3a16082a-96ac-0449-446a-4ed39f3365b6",
+    "liquid_feeding_beaker": "3a16087e-124f-8ddb-8ec1-c2dff09ca784",
+    "Drip_back": "3a162cf9-6aac-565a-ddd7-682ba1796a4a",
+}
+
+# 工作流名称到显示名称的映射
+WORKFLOW_TO_SECTION_MAP = {
+    'reactor_taken_in': '反应器放入',
+    'reactor_taken_out': '反应器取出',
+    'Solid_feeding_vials': '固体投料-小瓶',
+    'Liquid_feeding_vials(non-titration)': '液体投料-小瓶（非滴定）',
+    'Liquid_feeding_solvents': '液体投料-溶剂',
+    'Liquid_feeding(titration)': '液体投料-滴定',
+    'liquid_feeding_beaker': '液体投料-烧杯',
+    'Drip_back': '液体回滴'
+}
+
+# 工作流步骤ID配置
+WORKFLOW_STEP_IDS = {
+    "reactor_taken_in": {
+        "config": "60a06f85-c5b3-29eb-180f-4f62dd7e2154"
+    },
+    "liquid_feeding_beaker": {
+        "liquid": "6808cda7-fee7-4092-97f0-5f9c2ffa60e3",
+        "observe": "1753c0de-dffc-4ee6-8458-805a2e227362"
+    },
+    "liquid_feeding_vials_non_titration": {
+        "liquid": "62ea6e95-3d5d-43db-bc1e-9a1802673861",
+        "observe": "3a167d99-6172-b67b-5f22-a7892197142e"
+    },
+    "liquid_feeding_solvents": {
+        "liquid": "1fcea355-2545-462b-b727-350b69a313bf",
+        "observe": "0553dfb3-9ac5-4ace-8e00-2f11029919a8"
+    },
+    "solid_feeding_vials": {
+        "feeding": "f7ae7448-4f20-4c1d-8096-df6fbadd787a",
+        "observe": "263c7ed5-7277-426b-bdff-d6fbf77bcc05"
+    },
+    "liquid_feeding_titration": {
+        "liquid": "a00ec41b-e666-4422-9c20-bfcd3cd15c54",
+        "observe": "ac738ff6-4c58-4155-87b1-d6f65a2c9ab5"
+    },
+    "drip_back": {
+        "liquid": "371be86a-ab77-4769-83e5-54580547c48a",
+        "observe": "ce024b9d-bd20-47b8-9f78-ca5ce7f44cf1"
+    }
+}
+
+# 工作流动作名称配置
+ACTION_NAMES = {
+    "reactor_taken_in": {
+        "config": "通量-配置",
+        "stirring": "反应模块-开始搅拌"
+    },
+    "solid_feeding_vials": {
+        "feeding": "粉末加样模块-投料",
+        "observe": "反应模块-观察搅拌结果"
+    },
+    "liquid_feeding_vials_non_titration": {
+        "liquid": "稀释液瓶加液位-液体投料",
+        "observe": "反应模块-滴定结果观察"
+    },
+    "liquid_feeding_solvents": {
+        "liquid": "试剂AB放置位-试剂吸液分液",
+        "observe": "反应模块-观察搅拌结果"
+    },
+    "liquid_feeding_titration": {
+        "liquid": "稀释液瓶加液位-稀释液吸液分液",
+        "observe": "反应模块-滴定结果观察"
+    },
+    "liquid_feeding_beaker": {
+        "liquid": "烧杯溶液放置位-烧杯吸液分液",
+        "observe": "反应模块-观察搅拌结果"
+    },
+    "drip_back": {
+        "liquid": "试剂AB放置位-试剂吸液分液",
+        "observe": "反应模块-向下滴定结果观察"
+    }
+}
+
+# ============================================================================
+# 仓库配置
+# ============================================================================
+# 说明:
+# - 出库和入库操作都需要UUID
+WAREHOUSE_MAPPING = {
+    # ========== 反应站仓库 ==========
+
+    # 堆栈1左 - 反应站左侧堆栈 (4行×4列=16个库位, A01～D04)
+    "堆栈1左": {
+        "uuid": "3a14aa17-0d49-dce4-486e-4b5c85c8b366",
+        "site_uuids": {
+            "A01": "3a14aa17-0d49-11d7-a6e1-f236b3e5e5a3",
+            "A02": "3a14aa17-0d49-4bc5-8836-517b75473f5f",
+            "A03": "3a14aa17-0d49-c2bc-6222-5cee8d2d94f8",
+            "A04": "3a14aa17-0d49-3ce2-8e9a-008c38d116fb",
+            "B01": "3a14aa17-0d49-f49c-6b66-b27f185a3b32",
+            "B02": "3a14aa17-0d49-cf46-df85-a979c9c9920c",
+            "B03": "3a14aa17-0d49-7698-4a23-f7ffb7d48ba3",
+            "B04": "3a14aa17-0d49-1231-99be-d5870e6478e9",
+            "C01": "3a14aa17-0d49-be34-6fae-4aed9d48b70b",
+            "C02": "3a14aa17-0d49-11d7-0897-34921dcf6b7c",
+            "C03": "3a14aa17-0d49-9840-0bd5-9c63c1bb2c29",
+            "C04": "3a14aa17-0d49-8335-3bff-01da69ea4911",
+            "D01": "3a14aa17-0d49-2bea-c8e5-2b32094935d5",
+            "D02": "3a14aa17-0d49-cff4-e9e8-5f5f0bc1ef32",
+            "D03": "3a14aa17-0d49-4948-cb0a-78f30d1ca9b8",
+            "D04": "3a14aa17-0d49-fd2f-9dfb-a29b11e84099",
+        },
+    },
+
+    # 堆栈1右 - 反应站右侧堆栈 (4行×4列=16个库位, A05～D08)
+    "堆栈1右": {
+        "uuid": "3a14aa17-0d49-dce4-486e-4b5c85c8b366",
+        "site_uuids": {
+            "A05": "3a14aa17-0d49-2c61-edc8-72a8ca7192dd",
+            "A06": "3a14aa17-0d49-60c8-2b00-40b17198f397",
+            "A07": "3a14aa17-0d49-ec5b-0b75-634dce8eed25",
+            "A08": "3a14aa17-0d49-3ec9-55b3-f3189c4ec53d",
+            "B05": "3a14aa17-0d49-6a4e-abcf-4c113eaaeaad",
+            "B06": "3a14aa17-0d49-e3f6-2dd6-28c2e8194fbe",
+            "B07": "3a14aa17-0d49-11a6-b861-ee895121bf52",
+            "B08": "3a14aa17-0d49-9c7d-1145-d554a6e482f0",
+            "C05": "3a14aa17-0d49-45c4-7a34-5105bc3e2368",
+            "C06": "3a14aa17-0d49-867e-39ab-31b3fe9014be",
+            "C07": "3a14aa17-0d49-ec56-c4b4-39fd9b2131e7",
+            "C08": "3a14aa17-0d49-1128-d7d9-ffb1231c98c0",
+            "D05": "3a14aa17-0d49-e843-f961-ea173326a14b",
+            "D06": "3a14aa17-0d49-4d26-a985-f188359c4f8b",
+            "D07": "3a14aa17-0d49-223a-b520-bc092bb42fe0",
+            "D08": "3a14aa17-0d49-4fa3-401a-6a444e1cca22",
+        },
+    },
+
+    # 站内试剂存放堆栈
+    "站内试剂存放堆栈": {
+        "uuid": "3a14aa3b-9fab-9d8e-d1a7-828f01f51f0c",
+        "site_uuids": {
+            "A01": "3a14aa3b-9fab-adac-7b9c-e1ee446b51d5",
+            "A02": "3a14aa3b-9fab-ca72-febc-b7c304476c78"
+        }
+    },
+
+
+    # 测量小瓶仓库（测密度）
+    "测量小瓶仓库": {
+        "uuid": "3a15012f-705b-c0de-3f9e-950c205f9921",
+        "site_uuids": {
+            "A01": "3a15012f-705e-0524-3161-c523b5aebc97",
+            "A02": "3a15012f-705e-7cd1-32ab-ad4fd1ab75c8",
+            "A03": "3a15012f-705e-a5d6-edac-bdbfec236260",
+            "B01": "3a15012f-705e-e0ee-80e0-10a6b3fc500d",
+            "B02": "3a15012f-705e-e499-180d-de06d60d0b21",
+            "B03": "3a15012f-705e-eff6-63f1-09f742096b26"
+        }
+    },
+
+    # 站内Tip盒堆栈 - 用于存放枪头盒 (耗材)
+    "站内Tip盒堆栈": {
+        "uuid": "3a14aa3a-2d3c-b5c1-9ddf-7c4a957d459a",
+        "site_uuids": {
+            "A01": "3a14aa3a-2d3d-e700-411a-0ddf85e1f18a",
+            "A02": "3a14aa3a-2d3d-a7ce-099a-d5632fdafa24",
+            "A03": "3a14aa3a-2d3d-bdf6-a702-c60b38b08501",
+            "B01": "3a14aa3a-2d3d-d704-f076-2a8d5bc72cb8",
+            "B02": "3a14aa3a-2d3d-c350-2526-0778d173a5ac",
+            "B03": "3a14aa3a-2d3d-bc38-b356-f0de2e44e0c7"
+        }
+    },
+    # ========== 配液站仓库 ==========
+    "粉末堆栈": {
+        "uuid": "3a14198e-6928-121f-7ca6-88ad3ae7e6a0",
+        "site_uuids": {
+            "A01": "3a14198e-6929-31f0-8a22-0f98f72260df",
+            "A02": "3a14198e-6929-4379-affa-9a2935c17f99",
+            "A03": "3a14198e-6929-56da-9a1c-7f5fbd4ae8af",
+            "A04": "3a14198e-6929-5e99-2b79-80720f7cfb54",
+            "B01": "3a14198e-6929-f525-9a1b-1857552b28ee",
+            "B02": "3a14198e-6929-bf98-0fd5-26e1d68bf62d",
+            "B03": "3a14198e-6929-2d86-a468-602175a2b5aa",
+            "B04": "3a14198e-6929-1a98-ae57-e97660c489ad",
+            "C01": "3a14198e-6929-46fe-841e-03dd753f1e4a",
+            "C02": "3a14198e-6929-72ac-32ce-9b50245682b8",
+            "C03": "3a14198e-6929-8a0b-b686-6f4a2955c4e2",
+            "C04": "3a14198e-6929-a0ec-5f15-c0f9f339f963",
+            "D01": "3a14198e-6929-1bc9-a9bd-3b7ca66e7f95",
+            "D02": "3a14198e-6929-3bd8-e6c7-4a9fd93be118",
+            "D03": "3a14198e-6929-dde1-fc78-34a84b71afdf",
+            "D04": "3a14198e-6929-7ac8-915a-fea51cb2e884"
+        }
+    },
+    "溶液堆栈": {
+        "uuid": "3a14198e-d723-2c13-7d12-50143e190a23",
+        "site_uuids": {
+            "A01": "3a14198e-d724-e036-afdc-2ae39a7f3383",
+            "A02": "3a14198e-d724-d818-6d4f-5725191a24b5",
+            "A03": "3a14198e-d724-b5bb-adf3-4c5a0da6fb31",
+            "A04": "3a14198e-d724-d378-d266-2508a224a19f",
+            "B01": "3a14198e-d724-afa4-fc82-0ac8a9016791",
+            "B02": "3a14198e-d724-be8a-5e0b-012675e195c6",
+            "B03": "3a14198e-d724-ab4e-48cb-817c3c146707",
+            "B04": "3a14198e-d724-f56e-468b-0110a8feb36a",
+            "C01": "3a14198e-d724-ca48-bb9e-7e85751e55b6",
+            "C02": "3a14198e-d724-cc1e-5c2c-228a130f40a8",
+            "C03": "3a14198e-d724-7f18-1853-39d0c62e1d33",
+            "C04": "3a14198e-d724-0cf1-dea9-a1f40fe7e13c",
+            "D01": "3a14198e-d724-df6d-5e32-5483b3cab583",
+            "D02": "3a14198e-d724-1e28-c885-574c3df468d0",
+            "D03": "3a14198e-d724-28a2-a760-baa896f46b66",
+            "D04": "3a14198e-d724-0ddd-9654-f9352a421de9"
+        }
+    },
+    "试剂堆栈": {
+        "uuid": "3a14198c-c2cc-0290-e086-44a428fba248",
+        "site_uuids": {
+            "A01": "3a14198c-c2cf-8b40-af28-b467808f1c36",  # x=1, y=1, code=0001-0001
+            "A02": "3a14198c-c2d0-dc7d-b8d0-e1d88cee3094",  # x=1, y=2, code=0001-0002
+            "A03": "3a14198c-c2d0-354f-39ad-642e1a72fcb8",  # x=1, y=3, code=0001-0003
+            "A04": "3a14198c-c2d0-725e-523d-34c037ac2440",  # x=1, y=4, code=0001-0004
+            "B01": "3a14198c-c2d0-f3e7-871a-e470d144296f",  # x=2, y=1, code=0001-0005
+            "B02": "3a14198c-c2d0-2070-efc8-44e245f10c6f",  # x=2, y=2, code=0001-0006
+            "B03": "3a14198c-c2d0-1559-105d-0ea30682cab4",  # x=2, y=3, code=0001-0007
+            "B04": "3a14198c-c2d0-efce-0939-69ca5a7dfd39"   # x=2, y=4, code=0001-0008
+        }
+    }
+}
+
+# ============================================================================
+# 物料类型配置
+# ============================================================================
+# 说明:
+# - 格式: PyLabRobot资源类型名称 → Bioyond系统typeId的UUID
+# - 这个映射基于 resource.model 属性 (不是显示名称!)
+# - UUID为空表示该类型暂未在Bioyond系统中定义
+MATERIAL_TYPE_MAPPINGS = {
+    # ================================================配液站资源============================================================
+    # ==================================================样品===============================================================
+    "BIOYOND_PolymerStation_1FlaskCarrier": ("烧杯", "3a14196b-24f2-ca49-9081-0cab8021bf1a"),  # 配液站-样品-烧杯
+    "BIOYOND_PolymerStation_1BottleCarrier": ("试剂瓶", "3a14196b-8bcf-a460-4f74-23f21ca79e72"),  # 配液站-样品-试剂瓶
+    "BIOYOND_PolymerStation_6StockCarrier": ("分装板", "3a14196e-5dfe-6e21-0c79-fe2036d052c4"),  # 配液站-样品-分装板
+    "BIOYOND_PolymerStation_Liquid_Vial": ("10%分装小瓶", "3a14196c-76be-2279-4e22-7310d69aed68"),  # 配液站-样品-分装板-第一排小瓶
+    "BIOYOND_PolymerStation_Solid_Vial": ("90%分装小瓶", "3a14196c-cdcf-088d-dc7d-5cf38f0ad9ea"),  # 配液站-样品-分装板-第二排小瓶
+    # ==================================================试剂===============================================================
+    "BIOYOND_PolymerStation_8StockCarrier": ("样品板", "3a14196e-b7a0-a5da-1931-35f3000281e9"),  # 配液站-试剂-样品板（8孔）
+    "BIOYOND_PolymerStation_Solid_Stock": ("样品瓶", "3a14196a-cf7d-8aea-48d8-b9662c7dba94"),  # 配液站-试剂-样品板-样品瓶
+
+}
+
+# ============================================================================
+# 动态生成的库位UUID映射（从WAREHOUSE_MAPPING中提取）
+# ============================================================================
+
+LOCATION_MAPPING = {}
+for warehouse_name, warehouse_config in WAREHOUSE_MAPPING.items():
+    if "site_uuids" in warehouse_config:
+        LOCATION_MAPPING.update(warehouse_config["site_uuids"])
+
+# ============================================================================
+# 物料默认参数配置
+# ============================================================================
+# 说明:
+# - 为特定物料名称自动添加默认参数（如密度、分子量、单位等）
+# - 格式: 物料名称 → {参数字典}
+# - 在创建或更新物料时，会自动合并这些参数到 Parameters 字段
+# - unit: 物料的计量单位（会用于 unit 字段）
+# - density/densityUnit: 密度信息（会添加到 Parameters 中）
+
+MATERIAL_DEFAULT_PARAMETERS = {
+    # 溶剂类
+    "NMP": {
+        "unit": "毫升",
+        "density": "1.03",
+        "densityUnit": "g/mL",
+        "description": "N-甲基吡咯烷酮 (N-Methyl-2-pyrrolidone)"
+    },
+    # 可以继续添加其他物料...
+}
+
+# ============================================================================
+# 物料类型默认参数配置
+# ============================================================================
+# 说明:
+# - 为特定物料类型（UUID）自动添加默认参数
+# - 格式: Bioyond类型UUID → {参数字典}
+# - 优先级低于按名称匹配的配置
+MATERIAL_TYPE_PARAMETERS = {
+    # 示例:
+    # "3a14196b-24f2-ca49-9081-0cab8021bf1a": {  # 烧杯
+    #     "unit": "个"
+    # }
+}

unilabos/devices/workstation/bioyond_studio/dispensing_station/dispensing_station.py

@@ -4,7 +4,8 @@ import time
 from typing import Optional, Dict, Any, List
 from typing_extensions import TypedDict
 import requests
-from unilabos.devices.workstation.bioyond_studio.config import API_CONFIG
+import pint
+
 
 from unilabos.devices.workstation.bioyond_studio.bioyond_rpc import BioyondException
 from unilabos.devices.workstation.bioyond_studio.station import BioyondWorkstation
@@ -25,13 +26,89 @@ class ComputeExperimentDesignReturn(TypedDict):
 class BioyondDispensingStation(BioyondWorkstation):
     def __init__(
         self,
-        config,
-            # 桌子
-        deck,
-        *args,
+        config: dict = None,
+        deck=None,
+        protocol_type=None,
         **kwargs,
-        ):
-        super().__init__(config, deck, *args, **kwargs)
+    ):
+        """初始化配液站
+
+        Args:
+            config: 配置字典,应包含material_type_mappings等配置
+            deck: Deck对象
+            protocol_type: 协议类型(由ROS系统传递,此处忽略)
+            **kwargs: 其他可能的参数
+        """
+        if config is None:
+            config = {}
+
+        # 将 kwargs 合并到 config 中 (处理扁平化配置如 api_key)
+        config.update(kwargs)
+
+        if deck is None and config:
+            deck = config.get('deck')
+
+        # 🔧 修复: 确保 Deck 上的 warehouses 具有正确的 UUID (必须在 super().__init__ 之前执行，因为父类会触发同步)
+        # 从配置中读取 warehouse_mapping，并应用到实际的 deck 资源上
+        if config and "warehouse_mapping" in config and deck:
+            warehouse_mapping = config["warehouse_mapping"]
+            print(f"正在根据配置更新 Deck warehouse UUIDs... (共有 {len(warehouse_mapping)} 个配置)")
+
+            user_deck = deck
+            # 初始化 warehouses 字典
+            if not hasattr(user_deck, "warehouses") or user_deck.warehouses is None:
+                user_deck.warehouses = {}
+
+            # 1. 尝试从 children 中查找匹配的资源
+            for child in user_deck.children:
+                # 简单判断: 如果名字在 mapping 中，就认为是 warehouse
+                if child.name in warehouse_mapping:
+                    user_deck.warehouses[child.name] = child
+                    print(f"  - 从子资源中找到 warehouse: {child.name}")
+
+            # 2. 如果还是没找到，且 Deck 类有 setup 方法，尝试调用 setup (针对 Deck 对象正确但未初始化的情况)
+            if not user_deck.warehouses and hasattr(user_deck, "setup"):
+                print("  - 尝试调用 deck.setup() 初始化仓库...")
+                try:
+                    user_deck.setup()
+                    # setup 后重新检查
+                    if hasattr(user_deck, "warehouses") and user_deck.warehouses:
+                            print(f"  - setup() 成功，找到 {len(user_deck.warehouses)} 个仓库")
+                except Exception as e:
+                    print(f"  - 调用 setup() 失败: {e}")
+
+            # 3. 如果仍然为空，可能需要手动创建 (仅针对特定已知的 Deck 类型进行补救，这里暂时只打印警告)
+            if not user_deck.warehouses:
+                    print("  - ⚠️ 仍然无法找到任何 warehouse 资源！")
+
+            for wh_name, wh_config in warehouse_mapping.items():
+                target_uuid = wh_config.get("uuid")
+
+                # 尝试在 deck.warehouses 中查找
+                wh_resource = None
+                if hasattr(user_deck, "warehouses") and wh_name in user_deck.warehouses:
+                    wh_resource = user_deck.warehouses[wh_name]
+
+                # 如果没找到，尝试在所有子资源中查找
+                if not wh_resource:
+                    wh_resource = user_deck.get_resource(wh_name)
+
+                if wh_resource:
+                    if target_uuid:
+                        current_uuid = getattr(wh_resource, "uuid", None)
+                        print(f"✅ 更新仓库 '{wh_name}' UUID: {current_uuid} -> {target_uuid}")
+
+                        # 动态添加 uuid 属性
+                        wh_resource.uuid = target_uuid
+                        # 同时也确保 category 正确，避免 graphio 识别错误
+                        # wh_resource.category = "warehouse"
+                    else:
+                            print(f"⚠️ 仓库 '{wh_name}' 在配置中没有 UUID")
+                else:
+                    print(f"❌ 在 Deck 中未找到配置的仓库: '{wh_name}'")
+
+        super().__init__(bioyond_config=config, deck=deck)
+
         # self.config = config
         # self.api_key = config["api_key"]
         # self.host = config["api_host"]
@@ -43,6 +120,41 @@ class BioyondDispensingStation(BioyondWorkstation):
         # 用于跟踪任务完成状态的字典: {orderCode: {status, order_id, timestamp}}
         self.order_completion_status = {}
 
+        # 初始化 pint 单位注册表
+        self.ureg = pint.UnitRegistry()
+
+        # 化合物信息
+        self.compound_info = {
+            "MolWt": {
+                "MDA": 108.14 * self.ureg.g / self.ureg.mol,
+                "TDA": 122.16 * self.ureg.g / self.ureg.mol,
+                "PAPP": 521.62 * self.ureg.g / self.ureg.mol,
+                "BTDA": 322.23 * self.ureg.g / self.ureg.mol,
+                "BPDA": 294.22 * self.ureg.g / self.ureg.mol,
+                "6FAP": 366.26 * self.ureg.g / self.ureg.mol,
+                "PMDA": 218.12 * self.ureg.g / self.ureg.mol,
+                "MPDA": 108.14 * self.ureg.g / self.ureg.mol,
+                "SIDA": 248.51 * self.ureg.g / self.ureg.mol,
+                "ODA": 200.236 * self.ureg.g / self.ureg.mol,
+                "4,4'-ODA": 200.236 * self.ureg.g / self.ureg.mol,
+                "134": 292.34 * self.ureg.g / self.ureg.mol,
+            },
+            "FuncGroup": {
+                "MDA": "Amine",
+                "TDA": "Amine",
+                "PAPP": "Amine",
+                "BTDA": "Anhydride",
+                "BPDA": "Anhydride",
+                "6FAP": "Amine",
+                "MPDA": "Amine",
+                "SIDA": "Amine",
+                "PMDA": "Anhydride",
+                "ODA": "Amine",
+                "4,4'-ODA": "Amine",
+                "134": "Amine",
+            }
+        }
+
     def _post_project_api(self, endpoint: str, data: Any) -> Dict[str, Any]:
         """项目接口通用POST调用
 
@@ -54,7 +166,7 @@ class BioyondDispensingStation(BioyondWorkstation):
             dict: 服务端响应，失败时返回 {code:0,message,...}
         """
         request_data = {
-            "apiKey": API_CONFIG["api_key"],
+            "apiKey": self.bioyond_config["api_key"],
             "requestTime": self.hardware_interface.get_current_time_iso8601(),
             "data": data
         }
@@ -85,7 +197,7 @@ class BioyondDispensingStation(BioyondWorkstation):
             dict: 服务端响应，失败时返回 {code:0,message,...}
         """
         request_data = {
-            "apiKey": API_CONFIG["api_key"],
+            "apiKey": self.bioyond_config["api_key"],
             "requestTime": self.hardware_interface.get_current_time_iso8601(),
             "data": data
         }
@@ -118,20 +230,22 @@ class BioyondDispensingStation(BioyondWorkstation):
                     ratio = json.loads(ratio)
                 except Exception:
                     ratio = {}
-            root = str(Path(__file__).resolve().parents[3])
-            if root not in sys.path:
-                sys.path.append(root)
-            try:
-                mod = importlib.import_module("tem.compute")
-            except Exception as e:
-                raise BioyondException(f"无法导入计算模块: {e}")
             try:
                 wp = float(wt_percent) if isinstance(wt_percent, str) else wt_percent
                 mt = float(m_tot) if isinstance(m_tot, str) else m_tot
                 tp = float(titration_percent) if isinstance(titration_percent, str) else titration_percent
             except Exception as e:
                 raise BioyondException(f"参数解析失败: {e}")
-            res = mod.generate_experiment_design(ratio=ratio, wt_percent=wp, m_tot=mt, titration_percent=tp)
+
+            # 2. 调用内部计算方法
+            res = self._generate_experiment_design(
+                ratio=ratio,
+                wt_percent=wp,
+                m_tot=mt,
+                titration_percent=tp
+            )
+
+            # 3. 构造返回结果
             out = {
                 "solutions": res.get("solutions", []),
                 "titration": res.get("titration", {}),
@@ -140,11 +254,248 @@ class BioyondDispensingStation(BioyondWorkstation):
                 "return_info": json.dumps(res, ensure_ascii=False)
             }
             return out
+
         except BioyondException:
             raise
         except Exception as e:
             raise BioyondException(str(e))
 
+    def _generate_experiment_design(
+        self,
+        ratio: dict,
+        wt_percent: float = 0.25,
+        m_tot: float = 70,
+        titration_percent: float = 0.03,
+    ) -> dict:
+        """内部方法：生成实验设计
+
+        根据FuncGroup自动区分二胺和二酐，每种二胺单独配溶液，严格按照ratio顺序投料。
+
+        参数:
+            ratio: 化合物配比字典，格式: {"compound_name": ratio_value}
+            wt_percent: 固体重量百分比
+            m_tot: 反应混合物总质量(g)
+            titration_percent: 滴定溶液百分比
+
+        返回:
+            包含实验设计详细参数的字典
+        """
+        # 溶剂密度
+        ρ_solvent = 1.03 * self.ureg.g / self.ureg.ml
+        # 二酐溶解度
+        solubility = 0.02 * self.ureg.g / self.ureg.ml
+        # 投入固体时最小溶剂体积
+        V_min = 30 * self.ureg.ml
+        m_tot = m_tot * self.ureg.g
+
+        # 保持ratio中的顺序
+        compound_names = list(ratio.keys())
+        compound_ratios = list(ratio.values())
+
+        # 验证所有化合物是否在 compound_info 中定义
+        undefined_compounds = [name for name in compound_names if name not in self.compound_info["MolWt"]]
+        if undefined_compounds:
+            available = list(self.compound_info["MolWt"].keys())
+            raise ValueError(
+                f"以下化合物未在 compound_info 中定义: {undefined_compounds}。"
+                f"可用的化合物: {available}"
+            )
+
+        # 获取各化合物的分子量和官能团类型
+        molecular_weights = [self.compound_info["MolWt"][name] for name in compound_names]
+        func_groups = [self.compound_info["FuncGroup"][name] for name in compound_names]
+
+        # 记录化合物信息用于调试
+        self.hardware_interface._logger.info(f"化合物名称: {compound_names}")
+        self.hardware_interface._logger.info(f"官能团类型: {func_groups}")
+
+        # 按原始顺序分离二胺和二酐
+        ordered_compounds = list(zip(compound_names, compound_ratios, molecular_weights, func_groups))
+        diamine_compounds = [(name, ratio_val, mw, i) for i, (name, ratio_val, mw, fg) in enumerate(ordered_compounds) if fg == "Amine"]
+        anhydride_compounds = [(name, ratio_val, mw, i) for i, (name, ratio_val, mw, fg) in enumerate(ordered_compounds) if fg == "Anhydride"]
+
+        if not diamine_compounds or not anhydride_compounds:
+            raise ValueError(
+                f"需要同时包含二胺(Amine)和二酐(Anhydride)化合物。"
+                f"当前二胺: {[c[0] for c in diamine_compounds]}, "
+                f"当前二酐: {[c[0] for c in anhydride_compounds]}"
+            )
+
+        # 计算加权平均分子量 (基于摩尔比)
+        total_molar_ratio = sum(compound_ratios)
+        weighted_molecular_weight = sum(ratio_val * mw for ratio_val, mw in zip(compound_ratios, molecular_weights))
+
+        # 取最后一个二酐用于滴定
+        titration_anhydride = anhydride_compounds[-1]
+        solid_anhydrides = anhydride_compounds[:-1] if len(anhydride_compounds) > 1 else []
+
+        # 二胺溶液配制参数 - 每种二胺单独配制
+        diamine_solutions = []
+        total_diamine_volume = 0 * self.ureg.ml
+
+        # 计算反应物的总摩尔量
+        n_reactant = m_tot * wt_percent / weighted_molecular_weight
+
+        for name, ratio_val, mw, order_index in diamine_compounds:
+            # 跳过 SIDA
+            if name == "SIDA":
+                continue
+
+            # 计算该二胺需要的摩尔数
+            n_diamine_needed = n_reactant * ratio_val
+
+            # 二胺溶液配制参数 (每种二胺固定配制参数)
+            m_diamine_solid = 5.0 * self.ureg.g  # 每种二胺固体质量
+            V_solvent_for_this = 20 * self.ureg.ml  # 每种二胺溶剂体积
+            m_solvent_for_this = ρ_solvent * V_solvent_for_this
+
+            # 计算该二胺溶液的浓度
+            c_diamine = (m_diamine_solid / mw) / V_solvent_for_this
+
+            # 计算需要移取的溶液体积
+            V_diamine_needed = n_diamine_needed / c_diamine
+
+            diamine_solutions.append({
+                "name": name,
+                "order": order_index,
+                "solid_mass": m_diamine_solid.magnitude,
+                "solvent_volume": V_solvent_for_this.magnitude,
+                "concentration": c_diamine.magnitude,
+                "volume_needed": V_diamine_needed.magnitude,
+                "molar_ratio": ratio_val
+            })
+
+            total_diamine_volume += V_diamine_needed
+
+        # 按原始顺序排序
+        diamine_solutions.sort(key=lambda x: x["order"])
+
+        # 计算滴定二酐的质量
+        titration_name, titration_ratio, titration_mw, _ = titration_anhydride
+        m_titration_anhydride = n_reactant * titration_ratio * titration_mw
+        m_titration_90 = m_titration_anhydride * (1 - titration_percent)
+        m_titration_10 = m_titration_anhydride * titration_percent
+
+        # 计算其他固体二酐的质量 (按顺序)
+        solid_anhydride_masses = []
+        for name, ratio_val, mw, order_index in solid_anhydrides:
+            mass = n_reactant * ratio_val * mw
+            solid_anhydride_masses.append({
+                "name": name,
+                "order": order_index,
+                "mass": mass.magnitude,
+                "molar_ratio": ratio_val
+            })
+
+        # 按原始顺序排序
+        solid_anhydride_masses.sort(key=lambda x: x["order"])
+
+        # 计算溶剂用量
+        total_diamine_solution_mass = sum(
+            sol["volume_needed"] * ρ_solvent for sol in diamine_solutions
+        ) * self.ureg.ml
+
+        # 预估滴定溶剂量、计算补加溶剂量
+        m_solvent_titration = m_titration_10 / solubility * ρ_solvent
+        m_solvent_add = m_tot * (1 - wt_percent) - total_diamine_solution_mass - m_solvent_titration
+
+        # 检查最小溶剂体积要求
+        total_liquid_volume = (total_diamine_solution_mass + m_solvent_add) / ρ_solvent
+        m_tot_min = V_min / total_liquid_volume * m_tot
+
+        # 如果需要，按比例放大
+        scale_factor = 1.0
+        if m_tot_min > m_tot:
+            scale_factor = (m_tot_min / m_tot).magnitude
+            m_titration_90 *= scale_factor
+            m_titration_10 *= scale_factor
+            m_solvent_add *= scale_factor
+            m_solvent_titration *= scale_factor
+
+            # 更新二胺溶液用量
+            for sol in diamine_solutions:
+                sol["volume_needed"] *= scale_factor
+
+            # 更新固体二酐用量
+            for anhydride in solid_anhydride_masses:
+                anhydride["mass"] *= scale_factor
+
+            m_tot = m_tot_min
+
+        # 生成投料顺序
+        feeding_order = []
+
+        # 1. 固体二酐 (按顺序)
+        for anhydride in solid_anhydride_masses:
+            feeding_order.append({
+                "step": len(feeding_order) + 1,
+                "type": "solid_anhydride",
+                "name": anhydride["name"],
+                "amount": anhydride["mass"],
+                "order": anhydride["order"]
+            })
+
+        # 2. 二胺溶液 (按顺序)
+        for sol in diamine_solutions:
+            feeding_order.append({
+                "step": len(feeding_order) + 1,
+                "type": "diamine_solution",
+                "name": sol["name"],
+                "amount": sol["volume_needed"],
+                "order": sol["order"]
+            })
+
+        # 3. 主要二酐粉末
+        feeding_order.append({
+            "step": len(feeding_order) + 1,
+            "type": "main_anhydride",
+            "name": titration_name,
+            "amount": m_titration_90.magnitude,
+            "order": titration_anhydride[3]
+        })
+
+        # 4. 补加溶剂
+        if m_solvent_add > 0:
+            feeding_order.append({
+                "step": len(feeding_order) + 1,
+                "type": "additional_solvent",
+                "name": "溶剂",
+                "amount": m_solvent_add.magnitude,
+                "order": 999
+            })
+
+        # 5. 滴定二酐溶液
+        feeding_order.append({
+            "step": len(feeding_order) + 1,
+            "type": "titration_anhydride",
+            "name": f"{titration_name} 滴定液",
+            "amount": m_titration_10.magnitude,
+            "titration_solvent": m_solvent_titration.magnitude,
+            "order": titration_anhydride[3]
+        })
+
+        # 返回实验设计结果
+        results = {
+            "total_mass": m_tot.magnitude,
+            "scale_factor": scale_factor,
+            "solutions": diamine_solutions,
+            "solids": solid_anhydride_masses,
+            "titration": {
+                "name": titration_name,
+                "main_portion": m_titration_90.magnitude,
+                "titration_portion": m_titration_10.magnitude,
+                "titration_solvent": m_solvent_titration.magnitude,
+            },
+            "solvents": {
+                "additional_solvent": m_solvent_add.magnitude,
+                "total_liquid_volume": total_liquid_volume.magnitude
+            },
+            "feeding_order": feeding_order,
+            "minimum_required_mass": m_tot_min.magnitude
+        }
+
+        return results
+
     # 90%10%小瓶投料任务创建方法
     def create_90_10_vial_feeding_task(self,
                                        order_name: str = None,
@@ -961,6 +1312,108 @@ class BioyondDispensingStation(BioyondWorkstation):
             'actualVolume': actual_volume
         }
 
+    def _simplify_report(self, report) -> Dict[str, Any]:
+        """简化实验报告，只保留关键信息，去除冗余的工作流参数"""
+        if not isinstance(report, dict):
+            return report
+
+        data = report.get('data', {})
+        if not isinstance(data, dict):
+            return report
+
+        # 提取关键信息
+        simplified = {
+            'name': data.get('name'),
+            'code': data.get('code'),
+            'requester': data.get('requester'),
+            'workflowName': data.get('workflowName'),
+            'workflowStep': data.get('workflowStep'),
+            'requestTime': data.get('requestTime'),
+            'startPreparationTime': data.get('startPreparationTime'),
+            'completeTime': data.get('completeTime'),
+            'useTime': data.get('useTime'),
+            'status': data.get('status'),
+            'statusName': data.get('statusName'),
+        }
+
+        # 提取物料信息（简化版）
+        pre_intakes = data.get('preIntakes', [])
+        if pre_intakes and isinstance(pre_intakes, list):
+            first_intake = pre_intakes[0]
+            sample_materials = first_intake.get('sampleMaterials', [])
+
+            # 简化物料信息
+            simplified_materials = []
+            for material in sample_materials:
+                if isinstance(material, dict):
+                    mat_info = {
+                        'materialName': material.get('materialName'),
+                        'materialTypeName': material.get('materialTypeName'),
+                        'materialCode': material.get('materialCode'),
+                        'materialLocation': material.get('materialLocation'),
+                    }
+
+                    # 解析parameters中的关键信息（如密度、加料历史等）
+                    params_str = material.get('parameters', '{}')
+                    try:
+                        params = json.loads(params_str) if isinstance(params_str, str) else params_str
+                        if isinstance(params, dict):
+                            # 只保留关键参数
+                            if 'density' in params:
+                                mat_info['density'] = params['density']
+                            if 'feedingHistory' in params:
+                                mat_info['feedingHistory'] = params['feedingHistory']
+                            if 'liquidVolume' in params:
+                                mat_info['liquidVolume'] = params['liquidVolume']
+                            if 'm_diamine_tot' in params:
+                                mat_info['m_diamine_tot'] = params['m_diamine_tot']
+                            if 'wt_diamine' in params:
+                                mat_info['wt_diamine'] = params['wt_diamine']
+                    except:
+                        pass
+
+                    simplified_materials.append(mat_info)
+
+            simplified['sampleMaterials'] = simplified_materials
+
+            # 提取extraProperties中的实际值
+            extra_props = first_intake.get('extraProperties', {})
+            if isinstance(extra_props, dict):
+                simplified_extra = {}
+                for key, value in extra_props.items():
+                    try:
+                        parsed_value = json.loads(value) if isinstance(value, str) else value
+                        simplified_extra[key] = parsed_value
+                    except:
+                        simplified_extra[key] = value
+                simplified['extraProperties'] = simplified_extra
+
+        return {
+            'data': simplified,
+            'code': report.get('code'),
+            'message': report.get('message'),
+            'timestamp': report.get('timestamp')
+        }
+
+    def scheduler_start(self) -> dict:
+        """启动调度器 - 启动Bioyond工作站的任务调度器，开始执行队列中的任务
+
+        Returns:
+            dict: 包含return_info的字典，return_info为整型(1=成功)
+
+        Raises:
+            BioyondException: 调度器启动失败时抛出异常
+        """
+        result = self.hardware_interface.scheduler_start()
+        self.hardware_interface._logger.info(f"调度器启动结果: {result}")
+
+        if result != 1:
+            error_msg = "启动调度器失败: 有未处理错误，调度无法启动。请检查Bioyond系统状态。"
+            self.hardware_interface._logger.error(error_msg)
+            raise BioyondException(error_msg)
+
+        return {"return_info": result}
+
     # 等待多个任务完成并获取实验报告
     def wait_for_multiple_orders_and_get_reports(self,
                                                   batch_create_result: str = None,
@@ -1002,7 +1455,12 @@ class BioyondDispensingStation(BioyondWorkstation):
 
             # 验证batch_create_result参数
             if not batch_create_result or batch_create_result == "":
-                raise BioyondException("batch_create_result参数为空，请确保从batch_create节点正确连接handle")
+                raise BioyondException(
+                    "batch_create_result参数为空，请确保:\n"
+                    "1. batch_create节点与wait节点之间正确连接了handle\n"
+                    "2. batch_create节点成功执行并返回了结果\n"
+                    "3. 检查上游batch_create任务是否成功创建了订单"
+                )
 
             # 解析batch_create_result JSON对象
             try:
@@ -1031,7 +1489,17 @@ class BioyondDispensingStation(BioyondWorkstation):
 
             # 验证提取的数据
             if not order_codes:
-                raise BioyondException("batch_create_result中未找到order_codes字段或为空")
+                self.hardware_interface._logger.error(
+                    f"batch_create任务未生成任何订单。batch_create_result内容: {batch_create_result}"
+                )
+                raise BioyondException(
+                    "batch_create_result中未找到order_codes或为空。\n"
+                    "可能的原因:\n"
+                    "1. batch_create任务执行失败（检查任务是否报错）\n"
+                    "2. 物料配置问题（如'物料样品板分配失败'）\n"
+                    "3. Bioyond系统状态异常\n"
+                    f"请检查batch_create任务的执行结果"
+                )
             if not order_ids:
                 raise BioyondException("batch_create_result中未找到order_ids字段或为空")
 
@@ -1114,6 +1582,8 @@ class BioyondDispensingStation(BioyondWorkstation):
                                 self.hardware_interface._logger.info(
                                     f"成功获取任务 {order_code} 的实验报告"
                                 )
+                                # 简化报告，去除冗余信息
+                                report = self._simplify_report(report)
 
                             reports.append({
                                 "order_code": order_code,
@@ -1288,7 +1758,7 @@ class BioyondDispensingStation(BioyondWorkstation):
                 f"开始执行批量物料转移: {len(transfer_groups)}组任务 -> {target_device_id}"
             )
 
-            from .config import WAREHOUSE_MAPPING
+            warehouse_mapping = self.bioyond_config.get("warehouse_mapping", {})
             results = []
             successful_count = 0
             failed_count = 0

unilabos/devices/workstation/bioyond_studio/station.py

@@ -6,6 +6,7 @@ Bioyond Workstation Implementation
 """
 import time
 import traceback
+import threading
 from datetime import datetime
 from typing import Dict, Any, List, Optional, Union
 import json
@@ -23,12 +24,94 @@ from unilabos.ros.nodes.presets.workstation import ROS2WorkstationNode
 from unilabos.ros.msgs.message_converter import convert_to_ros_msg, Float64, String
 from pylabrobot.resources.resource import Resource as ResourcePLR
 
-from unilabos.devices.workstation.bioyond_studio.config import (
-    API_CONFIG, WORKFLOW_MAPPINGS, MATERIAL_TYPE_MAPPINGS, WAREHOUSE_MAPPING, HTTP_SERVICE_CONFIG
-)
+
 from unilabos.devices.workstation.workstation_http_service import WorkstationHTTPService
 
 
+class ConnectionMonitor:
+    """Bioyond连接监控器"""
+    def __init__(self, workstation, check_interval=30):
+        self.workstation = workstation
+        self.check_interval = check_interval
+        self._running = False
+        self._thread = None
+        self._last_status = "unknown"
+
+    def start(self):
+        if self._running:
+            return
+        self._running = True
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True, name="BioyondConnectionMonitor")
+        self._thread.start()
+        logger.info("Bioyond连接监控器已启动")
+
+    def stop(self):
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=2)
+            logger.info("Bioyond连接监控器已停止")
+
+    def _monitor_loop(self):
+        while self._running:
+            try:
+                # 使用 lightweight API 检查连接
+                # query_matial_type_list 是比较快的查询
+                start_time = time.time()
+                result = self.workstation.hardware_interface.material_type_list()
+
+                status = "online" if result else "offline"
+                msg = "Connection established" if status == "online" else "Failed to get material type list"
+
+                if status != self._last_status:
+                    logger.info(f"Bioyond连接状态变更: {self._last_status} -> {status}")
+                    self._publish_event(status, msg)
+                    self._last_status = status
+
+                # 发布心跳 (可选，或者只在状态变更时发布)
+                # self._publish_event(status, msg)
+
+            except Exception as e:
+                logger.error(f"Bioyond连接检查异常: {e}")
+                if self._last_status != "error":
+                    self._publish_event("error", str(e))
+                    self._last_status = "error"
+
+            time.sleep(self.check_interval)
+
+    def _publish_event(self, status, message):
+        try:
+            if hasattr(self.workstation, "_ros_node") and self.workstation._ros_node:
+                event_data = {
+                    "status": status,
+                    "message": message,
+                    "timestamp": datetime.now().isoformat()
+                }
+
+                # 动态发布消息，需要在 ROS2DeviceNode 中有对应支持
+                # 这里假设通用事件发布机制，使用 String 类型的 topic
+                # 话题: /<namespace>/events/device_status
+                ns = self.workstation._ros_node.namespace
+                topic = f"{ns}/events/device_status"
+
+                # 使用 ROS2DeviceNode 的发布功能
+                # 如果没有预定义的 publisher，需要动态创建
+                # 注意：workstation base node 可能没有自动创建 arbitrary publishers 的机制
+                # 这里我们先尝试用 String json 发布
+
+                # 在 ROS2DeviceNode 中通常需要先 create_publisher
+                # 为了简单起见，我们检查是否已有 publisher，没有则创建
+                if not hasattr(self.workstation, "_device_status_pub"):
+                    self.workstation._device_status_pub = self.workstation._ros_node.create_publisher(
+                        String, topic, 10
+                    )
+
+                self.workstation._device_status_pub.publish(
+                    convert_to_ros_msg(String, json.dumps(event_data, ensure_ascii=False))
+                )
+        except Exception as e:
+            logger.error(f"发布设备状态事件失败: {e}")
+
+
 class BioyondResourceSynchronizer(ResourceSynchronizer):
     """Bioyond资源同步器
 
@@ -174,9 +257,8 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
             else:
                 logger.info(f"[同步→Bioyond] ➕ 物料不存在于 Bioyond，将创建新物料并入库")
 
-            # 第1步：获取仓库配置
-            from .config import WAREHOUSE_MAPPING
-            warehouse_mapping = WAREHOUSE_MAPPING
+            # 第1步：从配置中获取仓库配置
+            warehouse_mapping = self.workstation.bioyond_config.get("warehouse_mapping", {})
 
             # 确定目标仓库名称
             parent_name = None
@@ -238,14 +320,20 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
             # 第2步：转换为 Bioyond 格式
             logger.info(f"[同步→Bioyond] 🔄 转换物料为 Bioyond 格式...")
 
-            # 导入物料默认参数配置
-            from .config import MATERIAL_DEFAULT_PARAMETERS
+            # 从配置中获取物料默认参数
+            material_default_params = self.workstation.bioyond_config.get("material_default_parameters", {})
+            material_type_params = self.workstation.bioyond_config.get("material_type_parameters", {})
+
+            # 合并参数配置：物料名称参数 + typeId参数（转换为 type:<uuid> 格式）
+            merged_params = material_default_params.copy()
+            for type_id, params in material_type_params.items():
+                merged_params[f"type:{type_id}"] = params
 
             bioyond_material = resource_plr_to_bioyond(
                 [resource],
                 type_mapping=self.workstation.bioyond_config["material_type_mappings"],
                 warehouse_mapping=self.workstation.bioyond_config["warehouse_mapping"],
-                material_params=MATERIAL_DEFAULT_PARAMETERS
+                material_params=merged_params
             )[0]
 
             logger.info(f"[同步→Bioyond] 🔧 准备覆盖locations字段，目标仓库: {parent_name}, 库位: {update_site}, UUID: {target_location_uuid[:8]}...")
@@ -468,13 +556,20 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
                 return material_bioyond_id
 
             # 转换为 Bioyond 格式
-            from .config import MATERIAL_DEFAULT_PARAMETERS
+            # 从配置中获取物料默认参数
+            material_default_params = self.workstation.bioyond_config.get("material_default_parameters", {})
+            material_type_params = self.workstation.bioyond_config.get("material_type_parameters", {})
+
+            # 合并参数配置：物料名称参数 + typeId参数（转换为 type:<uuid> 格式）
+            merged_params = material_default_params.copy()
+            for type_id, params in material_type_params.items():
+                merged_params[f"type:{type_id}"] = params
 
             bioyond_material = resource_plr_to_bioyond(
                 [resource],
                 type_mapping=self.workstation.bioyond_config["material_type_mappings"],
                 warehouse_mapping=self.workstation.bioyond_config["warehouse_mapping"],
-                material_params=MATERIAL_DEFAULT_PARAMETERS
+                material_params=merged_params
             )[0]
 
             # ⚠️ 关键：创建物料时不设置 locations，让 Bioyond 系统暂不分配库位
@@ -528,8 +623,7 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
             logger.info(f"[物料入库] 目标库位: {update_site}")
 
             # 获取仓库配置和目标库位 UUID
-            from .config import WAREHOUSE_MAPPING
-            warehouse_mapping = WAREHOUSE_MAPPING
+            warehouse_mapping = self.workstation.bioyond_config.get("warehouse_mapping", {})
 
             parent_name = None
             target_location_uuid = None
@@ -584,6 +678,44 @@ class BioyondWorkstation(WorkstationBase):
     集成Bioyond物料管理的工作站实现
     """
 
+    def _publish_task_status(
+        self,
+        task_id: str,
+        task_type: str,
+        status: str,
+        result: dict = None,
+        progress: float = 0.0,
+        task_code: str = None
+    ):
+        """发布任务状态事件"""
+        try:
+            if not getattr(self, "_ros_node", None):
+                return
+
+            event_data = {
+                "task_id": task_id,
+                "task_code": task_code,
+                "task_type": task_type,
+                "status": status,
+                "progress": progress,
+                "timestamp": datetime.now().isoformat()
+            }
+            if result:
+                event_data["result"] = result
+
+            topic = f"{self._ros_node.namespace}/events/task_status"
+
+            if not hasattr(self, "_task_status_pub"):
+                self._task_status_pub = self._ros_node.create_publisher(
+                    String, topic, 10
+                )
+
+            self._task_status_pub.publish(
+                convert_to_ros_msg(String, json.dumps(event_data, ensure_ascii=False))
+            )
+        except Exception as e:
+            logger.error(f"发布任务状态事件失败: {e}")
+
     def __init__(
         self,
         bioyond_config: Optional[Dict[str, Any]] = None,
@@ -605,10 +737,28 @@ class BioyondWorkstation(WorkstationBase):
             raise ValueError("Deck 配置不能为空，请在配置文件中添加正确的 deck 配置")
 
         # 初始化 warehouses 属性
-        self.deck.warehouses = {}
-        for resource in self.deck.children:
-            if isinstance(resource, WareHouse):
-                self.deck.warehouses[resource.name] = resource
+        if not hasattr(self.deck, "warehouses") or self.deck.warehouses is None:
+            self.deck.warehouses = {}
+
+        # 仅当 warehouses 为空时尝试重新扫描（避免覆盖子类的修复）
+        if not self.deck.warehouses:
+            for resource in self.deck.children:
+                # 兼容性增强: 只要是仓库类别或者是 WareHouse 实例均可
+                is_warehouse = isinstance(resource, WareHouse) or getattr(resource, "category", "") == "warehouse"
+
+                # 如果配置中有定义，也可以认定为 warehouse
+                if not is_warehouse and "warehouse_mapping" in bioyond_config:
+                    if resource.name in bioyond_config["warehouse_mapping"]:
+                        is_warehouse = True
+
+                if is_warehouse:
+                    self.deck.warehouses[resource.name] = resource
+                    # 确保 category 被正确设置，方便后续使用
+                    if getattr(resource, "category", "") != "warehouse":
+                        try:
+                            resource.category = "warehouse"
+                        except:
+                            pass
 
         # 创建通信模块
         self._create_communication_module(bioyond_config)
@@ -627,18 +777,22 @@ class BioyondWorkstation(WorkstationBase):
             self._set_workflow_mappings(bioyond_config["workflow_mappings"])
 
         # 准备 HTTP 报送接收服务配置（延迟到 post_init 启动）
-        # 从 bioyond_config 中获取，如果没有则使用 HTTP_SERVICE_CONFIG 的默认值
+        # 从 bioyond_config 中的 http_service_config 获取
+        http_service_cfg = bioyond_config.get("http_service_config", {})
         self._http_service_config = {
-            "host": bioyond_config.get("http_service_host", HTTP_SERVICE_CONFIG["http_service_host"]),
-            "port": bioyond_config.get("http_service_port", HTTP_SERVICE_CONFIG["http_service_port"])
+            "host": http_service_cfg.get("http_service_host", "127.0.0.1"),
+            "port": http_service_cfg.get("http_service_port", 8080)
         }
-        self.http_service = None  # 将在 post_init 中启动
+        self.http_service = None  # 将在 post_init 启动
+        self.connection_monitor = None # 将在 post_init 启动
 
         logger.info(f"Bioyond工作站初始化完成")
 
     def __del__(self):
         """析构函数：清理资源，停止 HTTP 服务"""
         try:
+            if hasattr(self, 'connection_monitor') and self.connection_monitor:
+                self.connection_monitor.stop()
             if hasattr(self, 'http_service') and self.http_service is not None:
                 logger.info("正在停止 HTTP 报送服务...")
                 self.http_service.stop()
@@ -648,8 +802,19 @@ class BioyondWorkstation(WorkstationBase):
     def post_init(self, ros_node: ROS2WorkstationNode):
         self._ros_node = ros_node
 
+        # 启动连接监控
+        try:
+            self.connection_monitor = ConnectionMonitor(self)
+            self.connection_monitor.start()
+        except Exception as e:
+            logger.error(f"启动连接监控失败: {e}")
+
         # 启动 HTTP 报送接收服务（现在 device_id 已可用）
-        if hasattr(self, '_http_service_config'):
+        # ⚠️ 检查子类是否已经自己管理 HTTP 服务
+        if self.bioyond_config.get("_disable_auto_http_service"):
+            logger.info("🔧 检测到 _disable_auto_http_service 标志，跳过自动启动 HTTP 服务")
+            logger.info("   子类（BioyondCellWorkstation）已自行管理 HTTP 服务")
+        elif hasattr(self, '_http_service_config'):
             try:
                 self.http_service = WorkstationHTTPService(
                     workstation_instance=self,
@@ -688,19 +853,14 @@ class BioyondWorkstation(WorkstationBase):
 
     def _create_communication_module(self, config: Optional[Dict[str, Any]] = None) -> None:
         """创建Bioyond通信模块"""
-        # 创建默认配置
-        default_config = {
-            **API_CONFIG,
-            "workflow_mappings": WORKFLOW_MAPPINGS,
-            "material_type_mappings": MATERIAL_TYPE_MAPPINGS,
-            "warehouse_mapping": WAREHOUSE_MAPPING
-        }
-
-        # 如果传入了 config，合并配置（config 中的值会覆盖默认值）
+        # 直接使用传入的配置，不再使用默认值
+        # 所有配置必须从 JSON 文件中提供
         if config:
-            self.bioyond_config = {**default_config, **config}
+            self.bioyond_config = config
         else:
-            self.bioyond_config = default_config
+            # 如果没有配置，使用空字典（会导致后续错误，但这是预期的）
+            self.bioyond_config = {}
+            print("警告: 未提供 bioyond_config，请确保在 JSON 配置文件中提供完整配置")
 
         self.hardware_interface = BioyondV1RPC(self.bioyond_config)
 
@@ -1014,7 +1174,15 @@ class BioyondWorkstation(WorkstationBase):
 
         workflow_id = self._get_workflow(actual_workflow_name)
         if workflow_id:
-            self.workflow_sequence.append(workflow_id)
+            # 兼容 BioyondReactionStation 中 workflow_sequence 被重写为 property 的情况
+            if isinstance(self.workflow_sequence, list):
+                self.workflow_sequence.append(workflow_id)
+            elif hasattr(self, "_cached_workflow_sequence") and isinstance(self._cached_workflow_sequence, list):
+                self._cached_workflow_sequence.append(workflow_id)
+            else:
+                print(f"❌ 无法添加工作流: workflow_sequence 类型错误 {type(self.workflow_sequence)}")
+                return False
+
             print(f"添加工作流到执行顺序: {actual_workflow_name} -> {workflow_id}")
             return True
         return False
@@ -1215,6 +1383,22 @@ class BioyondWorkstation(WorkstationBase):
             # TODO: 根据实际业务需求处理步骤完成逻辑
             # 例如：更新数据库、触发后续流程等
 
+            # 发布任务状态事件 (running/progress update)
+            self._publish_task_status(
+                task_id=data.get('orderCode'), # 使用 OrderCode 作为关联 ID
+                task_code=data.get('orderCode'),
+                task_type="bioyond_step",
+                status="running",
+                progress=0.5, # 步骤完成视为任务进行中
+                result={"step_name": data.get('stepName'), "step_id": data.get('stepId')}
+            )
+
+            # 更新物料信息
+            # 步骤完成后，物料状态可能发生变化（如位置、用量等），触发同步
+            logger.info(f"[步骤完成报送] 触发物料同步...")
+            self.resource_synchronizer.sync_from_external()
+
+
             return {
                 "processed": True,
                 "step_id": data.get('stepId'),
@@ -1249,6 +1433,17 @@ class BioyondWorkstation(WorkstationBase):
 
             # TODO: 根据实际业务需求处理通量完成逻辑
 
+            # 发布任务状态事件
+            self._publish_task_status(
+                task_id=data.get('orderCode'),
+                task_code=data.get('orderCode'),
+                task_type="bioyond_sample",
+                status="running",
+                progress=0.7,
+                result={"sample_id": data.get('sampleId'), "status": status_desc}
+            )
+
+
             return {
                 "processed": True,
                 "sample_id": data.get('sampleId'),
@@ -1288,6 +1483,32 @@ class BioyondWorkstation(WorkstationBase):
             # TODO: 根据实际业务需求处理任务完成逻辑
             # 例如：更新物料库存、生成报表等
 
+            # 映射状态到事件状态
+            event_status = "completed"
+            if str(data.get('status')) in ["-11", "-12"]:
+                event_status = "error"
+            elif str(data.get('status')) == "30":
+                event_status = "completed"
+            else:
+                event_status = "running" # 其他状态视为运行中（或根据实际定义）
+
+            # 发布任务状态事件
+            self._publish_task_status(
+                task_id=data.get('orderCode'),
+                task_code=data.get('orderCode'),
+                task_type="bioyond_order",
+                status=event_status,
+                progress=1.0 if event_status in ["completed", "error"] else 0.9,
+                result={"order_name": data.get('orderName'), "status": status_desc, "materials_count": len(used_materials)}
+            )
+
+            # 更新物料信息
+            # 任务完成后，且状态为完成时，触发同步以更新最终物料状态
+            if event_status == "completed":
+                logger.info(f"[任务完成报送] 触发物料同步...")
+                self.resource_synchronizer.sync_from_external()
+
+
             return {
                 "processed": True,
                 "order_code": data.get('orderCode'),

unilabos/devices/workstation/coin_cell_assembly/20251230_Modbus_CSV_Mapping_Guide.md

@@ -0,0 +1,84 @@
+# Modbus CSV 地址映射说明
+
+本文档说明 `coin_cell_assembly_a.csv` 文件如何将命名节点映射到实际的 Modbus 地址，以及如何在代码中使用它们。
+
+## 1. CSV 文件结构
+
+地址表文件位于同级目录下：`coin_cell_assembly_a.csv`
+
+每一行定义了一个 Modbus 节点，包含以下关键列：
+
+| 列名 | 说明 | 示例 |
+|------|------|------|
+| **Name** | **节点名称** (代码中引用的 Key) | `COIL_ALUMINUM_FOIL` |
+| **DataType** | 数据类型 (BOOL, INT16, FLOAT32, STRING) | `BOOL` |
+| **Comment** | 注释说明 | `使用铝箔垫` |
+| **Attribute** | 属性 (通常留空或用于额外标记) | |
+| **DeviceType** | Modbus 寄存器类型 (`coil`, `hold_register`) | `coil` |
+| **Address** | **Modbus 地址** (十进制) | `8340` |
+
+### 示例行 (铝箔垫片)
+
+```csv
+COIL_ALUMINUM_FOIL,BOOL,,使用铝箔垫,,coil,8340,
+```
+
+- **名称**: `COIL_ALUMINUM_FOIL`
+- **类型**: `coil` (线圈，读写单个位)
+- **地址**: `8340`
+
+---
+
+## 2. 加载与注册流程
+
+在 `coin_cell_assembly.py` 的初始化代码中：
+
+1. **加载 CSV**: `BaseClient.load_csv()` 读取 CSV 并解析每行定义。
+2. **注册节点**: `modbus_client.register_node_list()` 将解析后的节点注册到 Modbus 客户端实例中。
+
+```python
+# 代码位置: coin_cell_assembly.py (L174-175)
+self.nodes = BaseClient.load_csv(os.path.join(os.path.dirname(__file__), 'coin_cell_assembly_a.csv'))                            
+self.client = modbus_client.register_node_list(self.nodes)
+```
+
+---
+
+## 3. 代码中的使用方式
+
+注册后，通过 `self.client.use_node('节点名称')` 即可获取该节点对象并进行读写操作，无需关心具体地址。
+
+### 控制铝箔垫片 (COIL_ALUMINUM_FOIL)
+
+```python
+# 代码位置: qiming_coin_cell_code 函数 (L1048)
+self.client.use_node('COIL_ALUMINUM_FOIL').write(not lvbodian)
+```
+
+- **写入 True**: 对应 Modbus 功能码 05 (Write Single Coil)，向地址 `8340` 写入 `1` (ON)。
+- **写入 False**: 向地址 `8340` 写入 `0` (OFF)。
+
+> **注意**: 代码中使用了 `not lvbodian`，这意味着逻辑是反转的。如果 `lvbodian` 参数为 `True` (默认)，写入的是 `False` (不使用铝箔垫)。
+
+---
+
+## 4. 地址转换注意事项 (Modbus vs PLC)
+
+CSV 中的 `Address` 列（如 `8340`）是 **Modbus 协议地址**。
+
+如果使用 InoProShop (汇川 PLC 编程软件)，看到的可能是 **PLC 内部地址** (如 `%QX...` 或 `%MW...`)。这两者之间通常需要转换。
+
+### 常见的转换规则 (示例)
+
+- **Coil (线圈) %QX**: 
+  - `Modbus地址 = 字节地址 * 8 + 位偏移`
+  - *例子*: `%QX834.0` -> `834 * 8 + 0` = `6672`
+  - *注意*: 如果 CSV 中配置的是 `8340`，这可能是一个自定义映射，或者是基于不同规则（如直接对应 Word 地址的某种映射，或者可能就是地址写错了/使用了非标准映射）。
+
+- **Register (寄存器) %MW**:
+  - 通常直接对应，或者有偏移量 (如 Modbus 40001 = PLC MW0)。
+
+### 验证方法
+由于 `test_unilab_interact.py` 中发现 `8450` (CSV风格) 不工作，而 `6760` (%QX845.0 计算值) 工作正常，**建议对 CSV 中的其他地址也进行核实**，特别是像 `8340` 这样以 0 结尾看起来像是 "字节地址+0" 的数值，可能实际上应该是 `%QX834.0` 对应的 `6672`。
+
+如果发现设备控制无反应，请尝试按照标准的 Modbus 计算方式转换 PLC 地址。

unilabos/devices/workstation/coin_cell_assembly/20260113_物料搜寻确认弹窗自动处理功能.md

@@ -0,0 +1,352 @@
+# 2026-01-13 物料搜寻确认弹窗自动处理功能
+
+## 概述
+
+本次更新为设备初始化流程添加了**物料搜寻确认弹窗自动检测与处理功能**。在设备初始化过程中，PLC 会弹出物料搜寻确认对话框，现在系统可以根据用户参数自动点击"是"或"否"按钮，无需手动干预。
+
+## 背景问题
+
+### 原有流程
+1. 调用 `func_pack_device_init_auto_start_combined()` 初始化设备
+2. PLC 在初始化过程中弹出物料搜寻确认对话框
+3. **需要人工手动点击**"是"或"否"按钮
+4. PLC 继续完成初始化并启动
+
+### 存在的问题
+- 需要人工干预，无法实现全自动化
+- 影响批量生产效率
+- 容易遗忘点击导致流程卡住
+
+## 解决方案
+
+### 新增 Modbus 地址配置
+
+在 `coin_cell_assembly_b.csv` 第 69-71 行添加三个 coil：
+
+| Name | DeviceType | Address | 说明 |
+|------|-----------|---------|------|
+| COIL_MATERIAL_SEARCH_DIALOG_APPEAR | coil | 6470 | 物料搜寻确认弹窗画面是否出现 |
+| COIL_MATERIAL_SEARCH_CONFIRM_YES | coil | 6480 | 初始化物料搜寻确认按钮"是" |
+| COIL_MATERIAL_SEARCH_CONFIRM_NO | coil | 6490 | 初始化物料搜寻确认按钮"否" |
+
+**Modbus 地址转换：**
+- CSV 6470 → Modbus 5176 (弹窗出现)
+- CSV 6480 → Modbus 5184 (按钮"是")
+- CSV 6490 → Modbus 5192 (按钮"否")
+
+## 代码修改详情
+
+### 1. coin_cell_assembly.py
+
+#### 1.1 新增辅助方法 `_handle_material_search_dialog()`
+
+**位置：** 第 799-901 行
+
+**功能：**
+- 监测物料搜寻确认弹窗是否出现（Coil 5176）
+- 根据 `enable_search` 参数自动点击对应按钮
+- 使用**脉冲模式**模拟真实按钮操作：`True` → 保持 0.5 秒 → `False`
+
+**参数：**
+- `enable_search: bool` - True=点击"是"(启用物料搜寻), False=点击"否"(不启用)
+- `timeout: int = 30` - 等待弹窗出现的最大时间（秒）
+
+**逻辑流程：**
+```python
+1. 监测 COIL_MATERIAL_SEARCH_DIALOG_APPEAR (每 0.5 秒检查一次)
+2. 检测到弹窗出现 (Coil = True)
+3. 选择按钮：
+   - enable_search=True  → COIL_MATERIAL_SEARCH_CONFIRM_YES
+   - enable_search=False → COIL_MATERIAL_SEARCH_CONFIRM_NO
+4. 执行脉冲操作：
+   - 写入 True (按下按钮)
+   - 等待 0.5 秒
+   - 写入 False (释放按钮)
+   - 验证状态
+```
+
+#### 1.2 修改 `func_pack_device_init_auto_start_combined()`
+
+**位置：** 第 904-1115 行
+
+**主要改动：**
+
+1. **添加新参数**
+   ```python
+   def func_pack_device_init_auto_start_combined(
+       self, 
+       material_search_enable: bool = False  # 新增参数
+   ) -> bool:
+   ```
+
+2. **内联初始化逻辑并集成弹窗检测**
+   - 不再调用 `self.func_pack_device_init()`
+   - 将初始化逻辑直接实现在函数内
+   - **在等待初始化完成的循环中实时检测弹窗**
+   - 避免死锁：PLC 等待弹窗确认 ↔ 代码等待初始化完成
+
+3. **关键代码片段**
+   ```python
+   # 等待初始化完成，同时检测物料搜寻弹窗
+   while (self._sys_init_status()) == False:
+       # 检查超时
+       if time.time() - start_wait > max_wait_time:
+           raise RuntimeError(f"初始化超时")
+       
+       # 如果还没处理弹窗，检测弹窗是否出现
+       if not dialog_handled:
+           dialog_state = self.client.use_node('COIL_MATERIAL_SEARCH_DIALOG_APPEAR').read(1)
+           if dialog_actual:  # 弹窗出现
+               # 执行脉冲按钮点击
+               button_node.write(True)   # 按下
+               time.sleep(0.5)            # 保持
+               button_node.write(False)   # 释放
+               dialog_handled = True
+       
+       time.sleep(1)
+   ```
+
+4. **步骤调整**
+   - 步骤 0: 前置条件检查
+   - 步骤 1: 设备初始化（**包含弹窗检测**）
+   - 步骤 1.5: 已在步骤 1 中完成
+   - 步骤 2: 切换自动模式
+   - 步骤 3: 启动设备
+
+### 2. coin_cell_workstation.yaml
+
+**位置：** 第 292-312 行
+
+**修改内容：**
+
+```yaml
+auto-func_pack_device_init_auto_start_combined:
+  goal_default:
+    material_search_enable: false  # 新增默认值
+  
+  schema:
+    description: 组合函数:设备初始化 + 物料搜寻确认 + 切换自动模式 + 启动。初始化过程中会自动检测物料搜寻确认弹窗，并根据参数自动点击"是"或"否"按钮
+    
+    goal:
+      properties:
+        material_search_enable:  # 新增参数配置
+          default: false
+          description: 是否启用物料搜寻功能。设备初始化后会弹出物料搜寻确认弹窗，此参数控制自动点击"是"(启用)或"否"(不启用)。默认为false(不启用物料搜寻)
+          type: boolean
+```
+
+### 3. 测试脚本（已创建，用户已删除）
+
+#### 3.1 test_material_search_dialog.py
+- 从 CSV 动态加载 Modbus 地址
+- 支持 4 种测试模式：
+  - `query` - 查询所有状态
+  - `dialog <0|1>` - 设置弹窗出现/消失
+  - `yes` - 脉冲点击"是"按钮
+  - `no` - 脉冲点击"否"按钮
+- 兼容 pymodbus 3.x API
+
+#### 3.2 更新其他测试脚本
+- `test_coin_cell_reset.py` - 更新为 pymodbus 3.x API
+- `test_unilab_interact.py` - 更新为 pymodbus 3.x API
+
+## 使用方法
+
+### 参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `material_search_enable` | boolean | `false` | 是否启用物料搜寻功能 |
+
+### 调用示例
+
+#### 1. 不启用物料搜寻（默认）
+```python
+# 默认参数，点击"否"按钮
+await device.func_pack_device_init_auto_start_combined()
+```
+
+或在 YAML workflow 中：
+```yaml
+# 使用默认值 false，不启用物料搜寻
+- BatteryStation/auto-func_pack_device_init_auto_start_combined: {}
+```
+
+#### 2. 启用物料搜寻
+```python
+# 显式设置为 True，点击"是"按钮
+await device.func_pack_device_init_auto_start_combined(
+    material_search_enable=True
+)
+```
+
+或在 YAML workflow 中：
+```yaml
+- BatteryStation/auto-func_pack_device_init_auto_start_combined:
+    goal:
+      material_search_enable: true  # 启用物料搜寻
+```
+
+## 执行日志示例
+
+```
+26-01-13 [21:32:44] [INFO] 开始组合操作：设备初始化 → 物料搜寻确认 → 自动模式 → 启动
+26-01-13 [21:32:44] [INFO] 【步骤 0/4】前置条件检查...
+26-01-13 [21:32:44] [INFO]   ✓ REG_UNILAB_INTERACT 检查通过
+26-01-13 [21:32:44] [INFO]   ✓ COIL_GB_L_IGNORE_CMD 检查通过
+26-01-13 [21:32:44] [INFO] 【步骤 1/4】设备初始化...
+26-01-13 [21:32:44] [INFO] 切换手动模式...
+26-01-13 [21:32:46] [INFO] 发送初始化命令...
+26-01-13 [21:32:47] [INFO] 等待初始化完成（同时监测物料搜寻弹窗）...
+26-01-13 [21:33:05] [INFO] ✓ 在初始化过程中检测到物料搜寻确认弹窗！
+26-01-13 [21:33:05] [INFO] 用户选择: 不启用物料搜寻（点击否）
+26-01-13 [21:33:05] [INFO]   → 按下按钮 '否'
+26-01-13 [21:33:06] [INFO]   → 释放按钮 '否'
+26-01-13 [21:33:07] [INFO] ✓ 成功处理物料搜寻确认弹窗（选择: 否）
+26-01-13 [21:33:08] [INFO] ✓ 初始化状态完成
+26-01-13 [21:33:12] [INFO] ✓ 设备初始化完成
+26-01-13 [21:33:12] [INFO] 【步骤 1.5/4】物料搜寻确认已在初始化过程中完成
+26-01-13 [21:33:12] [INFO] 【步骤 2/4】切换自动模式...
+26-01-13 [21:33:15] [INFO] ✓ 切换自动模式完成
+26-01-13 [21:33:15] [INFO] 【步骤 3/4】启动设备...
+26-01-13 [21:33:18] [INFO] ✓ 启动设备完成
+26-01-13 [21:33:18] [INFO] 组合操作完成：设备已成功初始化、确认物料搜寻、切换自动模式并启动
+```
+
+## 技术要点
+
+### 1. 脉冲模式按钮操作
+模拟真实按钮按压过程：
+1. 写入 `True` (按下)
+2. 保持 0.5 秒
+3. 写入 `False` (释放)
+4. 验证状态
+
+### 2. 避免死锁
+**问题：** PLC 在初始化过程中等待弹窗确认，而代码等待初始化完成  
+**解决：** 在初始化等待循环中实时检测弹窗，一旦出现立即处理
+
+### 3. 超时保护
+- 弹窗检测超时：30 秒（在 `_handle_material_search_dialog` 中）
+- 初始化超时：120 秒（在 `func_pack_device_init_auto_start_combined` 中）
+
+### 4. PyModbus 3.x API 兼容
+所有 Modbus 操作使用 keyword arguments：
+```python
+# 读取
+client.read_coils(address=5176, count=1)
+
+# 写入
+client.write_coil(address=5184, value=True)
+```
+
+## 向后兼容性
+
+### 保留的原有函数
+- `func_pack_device_init()` - 单独的初始化函数，不包含弹窗处理
+- 仍可在 YAML 中通过 `auto-func_pack_device_init` 调用
+- 用于不需要自动处理弹窗的场景
+
+### 新增的功能
+- 在 `func_pack_device_init_auto_start_combined()` 中集成弹窗处理
+- 通过参数控制，默认行为与之前兼容（点击"否"）
+
+## 验证测试
+
+### 测试场景
+
+#### 场景 1：默认参数（不启用物料搜寻）
+```bash
+# 调用时不传参数
+BatteryStation/auto-func_pack_device_init_auto_start_combined: {}
+```
+**预期结果：**
+- ✅ 检测到弹窗
+- ✅ 自动点击"否"按钮
+- ✅ 初始化完成并启动成功
+
+#### 场景 2：启用物料搜寻
+```bash
+# 设置 material_search_enable=true
+BatteryStation/auto-func_pack_device_init_auto_start_combined:
+  goal:
+    material_search_enable: true
+```
+**预期结果：**
+- ✅ 检测到弹窗
+- ✅ 自动点击"是"按钮
+- ✅ 初始化完成并启动成功
+
+### 实际测试结果
+
+**测试时间：** 2026-01-13 21:32:43  
+**测试参数：** `material_search_enable: false`  
+**测试结果：** ✅ 成功
+
+**关键时间节点：**
+- 21:33:05 - 检测到弹窗
+- 21:33:05 - 按下"否"按钮
+- 21:33:06 - 释放"否"按钮  
+- 21:33:07 - 弹窗处理完成
+- 21:33:08 - 初始化状态完成
+- 21:33:18 - 整个流程完成
+
+**总耗时：** 约 35 秒（包含初始化全过程）
+
+## 注意事项
+
+1. **CSV 配置依赖**
+   - 确保 `coin_cell_assembly_b.csv` 包含 69-71 行的 coil 配置
+   - 地址转换逻辑：`modbus_addr = (csv_addr // 10) * 8 + (csv_addr % 10)`
+
+2. **默认行为**
+   - 默认 `material_search_enable=false`，即不启用物料搜寻
+   - 如需启用，必须显式设置为 `true`
+
+3. **日志级别**
+   - 弹窗检测过程中的 `waiting for init_cmd` 使用 DEBUG 级别
+   - 关键操作（检测到弹窗、按钮操作）使用 INFO 级别
+
+4. **原有函数保留**
+   - `func_pack_device_init()` 仍然可用，但不包含弹窗处理
+   - 如果单独调用此函数，仍需手动处理弹窗
+
+## 文件清单
+
+### 修改的文件
+1. `d:\UniLabdev\Uni-Lab-OS\unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly.py`
+   - 新增 `_handle_material_search_dialog()` 方法
+   - 修改 `func_pack_device_init_auto_start_combined()` 函数
+
+2. `d:\UniLabdev\Uni-Lab-OS\unilabos\registry\devices\coin_cell_workstation.yaml`
+   - 更新 `auto-func_pack_device_init_auto_start_combined` 配置
+   - 添加 `material_search_enable` 参数说明
+
+3. `d:\UniLabdev\Uni-Lab-OS\unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly_b.csv`
+   - 第 69-71 行添加三个 coil 配置
+
+### 创建的测试文件（已删除）
+1. `test_material_search_dialog.py` - 物料搜寻弹窗测试脚本
+2. `test_coin_cell_reset.py` - 复位功能测试（更新为 pymodbus 3.x）
+3. `test_unilab_interact.py` - Unilab 交互测试（更新为 pymodbus 3.x）
+
+## 总结
+
+本次更新成功实现了设备初始化过程中物料搜寻确认弹窗的自动化处理，主要优势：
+
+✅ **全自动化** - 无需人工干预  
+✅ **参数可配** - 灵活控制是否启用物料搜寻  
+✅ **实时检测** - 在初始化等待循环中检测，避免死锁  
+✅ **脉冲模式** - 模拟真实按钮操作  
+✅ **向后兼容** - 保留原有函数，不影响现有流程  
+✅ **完整日志** - 详细记录每一步操作  
+✅ **超时保护** - 防止无限等待  
+
+该功能已通过实际测试验证，可投入生产使用。
+
+---
+
+**文档版本：** 1.0  
+**创建日期：** 2026-01-13  
+**作者：** Antigravity AI Assistant  
+**最后更新：** 2026-01-13 21:36

unilabos/devices/workstation/coin_cell_assembly/YB_YH_materials.py

@@ -0,0 +1,645 @@
+"""
+纽扣电池组装工作站物料类定义
+Button Battery Assembly Station Resource Classes
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Any, Dict, List, Optional, TypedDict, Union, cast
+
+from pylabrobot.resources.coordinate import Coordinate
+from pylabrobot.resources.container import Container
+from pylabrobot.resources.deck import Deck
+from pylabrobot.resources.itemized_resource import ItemizedResource
+from pylabrobot.resources.resource import Resource
+from pylabrobot.resources.resource_stack import ResourceStack
+from pylabrobot.resources.tip_rack import TipRack, TipSpot
+from pylabrobot.resources.trash import Trash
+from pylabrobot.resources.utils import create_ordered_items_2d
+
+from unilabos.resources.battery.magazine import MagazineHolder_4_Cathode, MagazineHolder_6_Cathode, MagazineHolder_6_Anode, MagazineHolder_6_Battery
+from unilabos.resources.battery.bottle_carriers import YIHUA_Electrolyte_12VialCarrier
+from unilabos.resources.battery.electrode_sheet import ElectrodeSheet
+
+
+
+# TODO: 这个应该只能放一个极片
+class MaterialHoleState(TypedDict):
+    diameter: int
+    depth: int
+    max_sheets: int
+    info: Optional[str]  # 附加信息
+
+class MaterialHole(Resource):
+    """料板洞位类"""
+    children: List[ElectrodeSheet] = []
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "material_hole",
+        **kwargs
+    ):
+        super().__init__(
+            name=name,
+            size_x=size_x,
+            size_y=size_y,
+            size_z=size_z,
+            category=category,
+        )
+        self._unilabos_state: MaterialHoleState = MaterialHoleState(
+            diameter=20,
+            depth=10,
+            max_sheets=1,
+            info=None
+        )
+
+    def get_all_sheet_info(self):
+        info_list = []
+        for sheet in self.children:
+            info_list.append(sheet._unilabos_state["info"])
+        return info_list
+    
+    #这个函数函数好像没用，一般不会集中赋值质量
+    def set_all_sheet_mass(self):
+        for sheet in self.children:
+            sheet._unilabos_state["mass"] = 0.5  # 示例：设置质量为0.5g
+
+    def load_state(self, state: Dict[str, Any]) -> None:
+        """格式不变"""
+        super().load_state(state)
+        self._unilabos_state = state
+
+    def serialize_state(self) -> Dict[str, Dict[str, Any]]:
+        """格式不变"""
+        data = super().serialize_state()
+        data.update(self._unilabos_state)  # Container自身的信息，云端物料将保存这一data，本地也通过这里的data进行读写，当前类用来表示这个物料的长宽高大小的属性，而data（state用来表示物料的内容，细节等）
+        return data
+    #移动极片前先取出对象
+    def get_sheet_with_name(self, name: str) -> Optional[ElectrodeSheet]:
+        for sheet in self.children:
+            if sheet.name == name:
+                return sheet
+        return None
+
+    def has_electrode_sheet(self) -> bool:
+        """检查洞位是否有极片"""
+        return len(self.children) > 0
+
+    def assign_child_resource(
+        self,
+        resource: ElectrodeSheet,
+        location: Optional[Coordinate],
+        reassign: bool = True,
+    ):
+        """放置极片"""
+        # TODO: 这里要改，diameter找不到，加入._unilabos_state后应该没问题
+        #if resource._unilabos_state["diameter"] > self._unilabos_state["diameter"]:
+        #    raise ValueError(f"极片直径 {resource._unilabos_state['diameter']} 超过洞位直径 {self._unilabos_state['diameter']}")
+        #if len(self.children) >= self._unilabos_state["max_sheets"]:
+        #    raise ValueError(f"洞位已满，无法放置更多极片")
+        super().assign_child_resource(resource, location, reassign)
+
+    # 根据children的编号取物料对象。
+    def get_electrode_sheet_info(self, index: int) -> ElectrodeSheet:
+        return self.children[index]
+
+
+class MaterialPlateState(TypedDict):
+    hole_spacing_x: float
+    hole_spacing_y: float
+    hole_diameter: float
+    info: Optional[str]  # 附加信息
+
+class MaterialPlate(ItemizedResource[MaterialHole]):
+    """料板类 - 4x4个洞位，每个洞位放1个极片"""
+    
+    children: List[MaterialHole]
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        ordered_items: Optional[Dict[str, MaterialHole]] = None,
+        ordering: Optional[OrderedDict[str, str]] = None,
+        category: str = "material_plate",
+        model: Optional[str] = None,
+        fill: bool = False
+    ):
+        """初始化料板
+
+        Args:
+            name: 料板名称
+            size_x: 长度 (mm)
+            size_y: 宽度 (mm)
+            size_z: 高度 (mm)
+            hole_diameter: 洞直径 (mm)
+            hole_depth: 洞深度 (mm)
+            hole_spacing_x: X方向洞位间距 (mm)
+            hole_spacing_y: Y方向洞位间距 (mm)
+            number: 编号
+            category: 类别
+            model: 型号
+        """
+        self._unilabos_state: MaterialPlateState = MaterialPlateState(
+            hole_spacing_x=24.0,
+            hole_spacing_y=24.0,
+            hole_diameter=20.0,
+            info="",
+        )
+        # 创建4x4的洞位
+        # TODO: 这里要改，对应不同形状
+        holes = create_ordered_items_2d(
+            klass=MaterialHole,
+            num_items_x=4,
+            num_items_y=4,
+            dx=(size_x - 4 * self._unilabos_state["hole_spacing_x"]) / 2,  # 居中
+            dy=(size_y - 4 * self._unilabos_state["hole_spacing_y"]) / 2,  # 居中
+            dz=size_z,
+            item_dx=self._unilabos_state["hole_spacing_x"],
+            item_dy=self._unilabos_state["hole_spacing_y"],
+            size_x = 16,
+            size_y = 16,
+            size_z = 16,
+        )
+        if fill:
+            super().__init__(
+                name=name,
+                size_x=size_x,
+                size_y=size_y,
+                size_z=size_z,
+                ordered_items=holes,
+                category=category,
+                model=model,
+            )
+        else:
+            super().__init__(
+                name=name,
+                size_x=size_x,
+                size_y=size_y,
+                size_z=size_z,
+                ordered_items=ordered_items,
+                ordering=ordering,
+                category=category,
+                model=model,
+            )
+
+    def update_locations(self):
+        # TODO:调多次相加
+        holes = create_ordered_items_2d(
+            klass=MaterialHole,
+            num_items_x=4,
+            num_items_y=4,
+            dx=(self._size_x - 3 * self._unilabos_state["hole_spacing_x"]) / 2,  # 居中
+            dy=(self._size_y - 3 * self._unilabos_state["hole_spacing_y"]) / 2,  # 居中
+            dz=self._size_z,
+            item_dx=self._unilabos_state["hole_spacing_x"],
+            item_dy=self._unilabos_state["hole_spacing_y"],
+            size_x = 1,
+            size_y = 1,
+            size_z = 1,
+        )
+        for item, original_item in zip(holes.items(), self.children):
+            original_item.location = item[1].location
+
+
+class PlateSlot(ResourceStack):
+    """板槽位类 - 1个槽上能堆放8个板，移板只能操作最上方的板"""
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        max_plates: int = 8,
+        category: str = "plate_slot",
+        model: Optional[str] = None
+    ):
+        """初始化板槽位
+
+        Args:
+            name: 槽位名称
+            max_plates: 最大板数量
+            category: 类别
+        """
+        super().__init__(
+            name=name,
+            direction="z",  # Z方向堆叠
+            resources=[],
+        )
+        self.max_plates = max_plates
+        self.category = category
+
+    def can_add_plate(self) -> bool:
+        """检查是否可以添加板"""
+        return len(self.children) < self.max_plates
+
+    def add_plate(self, plate: MaterialPlate) -> None:
+        """添加料板"""
+        if not self.can_add_plate():
+            raise ValueError(f"槽位 {self.name} 已满，无法添加更多板")
+        self.assign_child_resource(plate)
+
+    def get_top_plate(self) -> MaterialPlate:
+        """获取最上方的板"""
+        if len(self.children) == 0:
+            raise ValueError(f"槽位 {self.name} 为空")
+        return cast(MaterialPlate, self.get_top_item())
+
+    def take_top_plate(self) -> MaterialPlate:
+        """取出最上方的板"""
+        top_plate = self.get_top_plate()
+        self.unassign_child_resource(top_plate)
+        return top_plate
+
+    def can_access_for_picking(self) -> bool:
+        """检查是否可以进行取料操作（只有最上方的板能进行取料操作）"""
+        return len(self.children) > 0
+
+    def serialize(self) -> dict:
+        return {
+            **super().serialize(),
+            "max_plates": self.max_plates,
+        }
+
+
+#是一种类型注解，不用self
+class BatteryState(TypedDict):
+    """电池状态字典"""
+    diameter: float
+    height: float
+    assembly_pressure: float
+    electrolyte_volume: float
+    electrolyte_name: str
+
+class Battery(Resource):
+    """电池类 - 可容纳极片"""
+    children: List[ElectrodeSheet] = []
+
+    def __init__(
+        self,
+        name: str,
+        size_x=1,
+        size_y=1,
+        size_z=1,
+        category: str = "battery",
+    ):
+        """初始化电池
+
+        Args:
+            name: 电池名称
+            diameter: 直径 (mm)
+            height: 高度 (mm)
+            max_volume: 最大容量 (μL)
+            barcode: 二维码编号
+            category: 类别
+            model: 型号
+        """
+        super().__init__(
+            name=name,
+            size_x=1,
+            size_y=1,
+            size_z=1,
+            category=category,
+        )
+        self._unilabos_state: BatteryState = BatteryState(
+                                 diameter = 1.0,
+                                 height = 1.0,
+                                 assembly_pressure = 1.0,
+                                 electrolyte_volume = 1.0,
+                                 electrolyte_name = "DP001"
+                                 )
+
+    def add_electrolyte_with_bottle(self, bottle: Bottle) -> bool:
+        to_add_name = bottle._unilabos_state["electrolyte_name"]
+        if bottle.aspirate_electrolyte(10):
+            if self.add_electrolyte(to_add_name, 10):
+                pass
+            else:
+                bottle._unilabos_state["electrolyte_volume"] += 10
+
+    def set_electrolyte(self, name: str, volume: float) -> None:
+        """设置电解液信息"""
+        self._unilabos_state["electrolyte_name"] = name
+        self._unilabos_state["electrolyte_volume"] = volume
+    #这个应该没用，不会有加了后再加的事情
+    def add_electrolyte(self, name: str, volume: float) -> bool:
+        """添加电解液信息"""
+        if name != self._unilabos_state["electrolyte_name"]:
+            return False
+        self._unilabos_state["electrolyte_volume"] += volume
+
+    def load_state(self, state: Dict[str, Any]) -> None:
+        """格式不变"""
+        super().load_state(state)
+        self._unilabos_state = state
+
+    def serialize_state(self) -> Dict[str, Dict[str, Any]]:
+        """格式不变"""
+        data = super().serialize_state()
+        data.update(self._unilabos_state)  # Container自身的信息，云端物料将保存这一data，本地也通过这里的data进行读写，当前类用来表示这个物料的长宽高大小的属性，而data（state用来表示物料的内容，细节等）
+        return data
+
+# 电解液作为属性放进去
+
+class BatteryPressSlotState(TypedDict):
+    """电池状态字典"""
+    diameter: float =20.0
+    depth: float = 4.0
+
+class BatteryPressSlot(Resource):
+    """电池压制槽类 - 设备，可容纳一个电池"""
+    children: List[Battery] = []
+
+    def __init__(
+        self,
+        name: str = "BatteryPressSlot",
+        category: str = "battery_press_slot",
+    ):
+        """初始化电池压制槽
+
+        Args:
+            name: 压制槽名称
+            diameter: 直径 (mm)
+            depth: 深度 (mm)
+            category: 类别
+            model: 型号
+        """
+        super().__init__(
+            name=name,
+            size_x=10,
+            size_y=12,
+            size_z=13,
+            category=category,
+        )
+        self._unilabos_state: BatteryPressSlotState = BatteryPressSlotState()
+
+    def has_battery(self) -> bool:
+        """检查是否有电池"""
+        return len(self.children) > 0
+
+    def load_state(self, state: Dict[str, Any]) -> None:
+        """格式不变"""
+        super().load_state(state)
+        self._unilabos_state = state
+
+    def serialize_state(self) -> Dict[str, Dict[str, Any]]:
+        """格式不变"""
+        data = super().serialize_state()
+        data.update(self._unilabos_state)  # Container自身的信息，云端物料将保存这一data，本地也通过这里的data进行读写，当前类用来表示这个物料的长宽高大小的属性，而data（state用来表示物料的内容，细节等）
+        return data
+    
+    def assign_child_resource(
+        self,
+        resource: Battery,
+        location: Optional[Coordinate],
+        reassign: bool = True,
+    ):
+        """放置极片"""
+        # TODO: 让高京看下槽位只有一个电池时是否这么写。
+        if self.has_battery():
+            raise ValueError(f"槽位已含有一个电池，无法再放置其他电池")
+        super().assign_child_resource(resource, location, reassign)
+
+    # 根据children的编号取物料对象。
+    def get_battery_info(self, index: int) -> Battery:
+        return self.children[0]
+
+
+def TipBox64(
+        name: str,
+        size_x: float = 127.8,
+        size_y: float = 85.5,
+        size_z: float = 60.0,
+        category: str = "tip_rack",
+        model: Optional[str] = None,
+):
+    """64孔枪头盒类"""
+    from pylabrobot.resources.tip import Tip
+
+    # 创建12x8=96个枪头位
+    def make_tip():
+        return Tip(
+            has_filter=False,
+            total_tip_length=20.0,
+            maximal_volume=1000,  # 1mL
+            fitting_depth=8.0,
+        )
+
+    tip_spots = create_ordered_items_2d(
+        klass=TipSpot,
+        num_items_x=12,
+        num_items_y=8,
+        dx=8.0,
+        dy=8.0,
+        dz=0.0,
+        item_dx=9.0,
+        item_dy=9.0,
+        size_x=10,
+        size_y=10,
+        size_z=0.0,
+        make_tip=make_tip,
+    )
+    idx_available = list(range(0, 32)) + list(range(64, 96))
+    tip_spots_available = {k: v for i, (k, v) in enumerate(tip_spots.items()) if i in idx_available}
+    tip_rack = TipRack(
+        name=name,
+        size_x=size_x,
+        size_y=size_y,
+        size_z=size_z,
+        # ordered_items=tip_spots_available,
+        ordered_items=tip_spots,
+        category=category,
+        model=model,
+        with_tips=False,
+    )
+    tip_rack.set_tip_state([True]*32 + [False]*32 + [True]*32)  # 前32和后32个有枪头，中间32个无枪头
+    return tip_rack
+
+
+class WasteTipBoxstate(TypedDict):
+    """"废枪头盒状态字典"""
+    max_tips: int = 100
+    tip_count: int = 0
+
+#枪头不是一次性的（同一溶液则反复使用），根据寄存器判断
+class WasteTipBox(Trash):
+    """废枪头盒类 - 100个枪头容量"""
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float = 127.8,
+        size_y: float = 85.5,
+        size_z: float = 60.0,
+        material_z_thickness=0,
+        max_volume=float("inf"),
+        category="trash",
+        model=None,
+        compute_volume_from_height=None,
+        compute_height_from_volume=None,
+    ):
+        """初始化废枪头盒
+
+        Args:
+            name: 废枪头盒名称
+            size_x: 长度 (mm)
+            size_y: 宽度 (mm)
+            size_z: 高度 (mm)
+            max_tips: 最大枪头容量
+            category: 类别
+            model: 型号
+        """
+        super().__init__(
+            name=name,
+            size_x=size_x,
+            size_y=size_y,
+            size_z=size_z,
+            category=category,
+            model=model,
+        )
+        self._unilabos_state: WasteTipBoxstate = WasteTipBoxstate()
+
+    def add_tip(self) -> None:
+        """添加废枪头"""
+        if self._unilabos_state["tip_count"] >= self._unilabos_state["max_tips"]:
+            raise ValueError(f"废枪头盒 {self.name} 已满")
+        self._unilabos_state["tip_count"] += 1
+
+    def get_tip_count(self) -> int:
+        """获取枪头数量"""
+        return self._unilabos_state["tip_count"]
+
+    def empty(self) -> None:
+        """清空废枪头盒"""
+        self._unilabos_state["tip_count"] = 0
+
+
+    def load_state(self, state: Dict[str, Any]) -> None:
+        """格式不变"""
+        super().load_state(state)
+        self._unilabos_state = state
+
+    def serialize_state(self) -> Dict[str, Dict[str, Any]]:
+        """格式不变"""
+        data = super().serialize_state()
+        data.update(self._unilabos_state)  # Container自身的信息，云端物料将保存这一data，本地也通过这里的data进行读写，当前类用来表示这个物料的长宽高大小的属性，而data（state用来表示物料的内容，细节等）
+        return data
+
+
+class CoincellDeck(Deck):
+    """纽扣电池组装工作站台面类"""
+
+    def __init__(
+        self,
+        name: str = "coin_cell_deck",
+        size_x: float = 1450.0,  # 1m
+        size_y: float = 1450.0,  # 1m
+        size_z: float = 100.0,   # 0.9m
+        origin: Coordinate = Coordinate(-2200, 0, 0),
+        category: str = "coin_cell_deck",
+        setup: bool = False,  # 是否自动执行 setup
+    ):
+        """初始化纽扣电池组装工作站台面
+
+        Args:
+            name: 台面名称
+            size_x: 长度 (mm) - 1m
+            size_y: 宽度 (mm) - 1m
+            size_z: 高度 (mm) - 0.9m
+            origin: 原点坐标
+            category: 类别
+            setup: 是否自动执行 setup 配置标准布局
+        """
+        super().__init__(
+            name=name,
+            size_x=1450.0,
+            size_y=1450.0,
+            size_z=100.0,
+            origin=origin,
+        )
+        if setup:
+            self.setup()
+
+    def setup(self) -> None:
+        """设置工作站的标准布局 - 包含子弹夹、料盘、瓶架等完整配置"""
+        # ====================================== 子弹夹 ============================================
+        
+        # 正极片（4个洞位，2x2布局）
+        zhengji_zip = MagazineHolder_4_Cathode("正极&铝箔弹夹")
+        self.assign_child_resource(zhengji_zip, Coordinate(x=402.0, y=830.0, z=0))
+        
+        # 正极壳、平垫片（6个洞位，2x2+2布局）
+        zhengjike_zip = MagazineHolder_6_Cathode("正极壳&平垫片弹夹")
+        self.assign_child_resource(zhengjike_zip, Coordinate(x=566.0, y=272.0, z=0))
+        
+        # 负极壳、弹垫片（6个洞位，2x2+2布局）
+        fujike_zip = MagazineHolder_6_Anode("负极壳&弹垫片弹夹")
+        self.assign_child_resource(fujike_zip, Coordinate(x=474.0, y=276.0, z=0))
+        
+        # 成品弹夹（6个洞位，3x2布局）
+        chengpindanjia_zip = MagazineHolder_6_Battery("成品弹夹")
+        self.assign_child_resource(chengpindanjia_zip, Coordinate(x=260.0, y=156.0, z=0))
+        
+        # ====================================== 物料板 ============================================
+        # 创建物料板（料盘carrier）- 4x4布局
+        # 负极料盘
+        fujiliaopan = MaterialPlate(name="负极料盘", size_x=120, size_y=100, size_z=10.0, fill=True)
+        self.assign_child_resource(fujiliaopan, Coordinate(x=708.0, y=794.0, z=0))
+        # for i in range(16):
+        #     fujipian = ElectrodeSheet(name=f"{fujiliaopan.name}_jipian_{i}", size_x=12, size_y=12, size_z=0.1)
+        #     fujiliaopan.children[i].assign_child_resource(fujipian, location=None)
+
+        # 隔膜料盘
+        gemoliaopan = MaterialPlate(name="隔膜料盘", size_x=120, size_y=100, size_z=10.0, fill=True)
+        self.assign_child_resource(gemoliaopan, Coordinate(x=718.0, y=918.0, z=0))
+        # for i in range(16):
+        #     gemopian = ElectrodeSheet(name=f"{gemoliaopan.name}_jipian_{i}", size_x=12, size_y=12, size_z=0.1)
+        #     gemoliaopan.children[i].assign_child_resource(gemopian, location=None)
+
+        # ====================================== 瓶架、移液枪 ============================================
+        # 在台面上放置 3x4 瓶架、6x2 瓶架 与 64孔移液枪头盒
+        # 奔耀上料5ml分液瓶小板 - 由奔曜跨站转运而来，不单独写，但是这里应该有一个堆栈用于摆放分液瓶小板
+        
+        # bottle_rack_3x4 = BottleRack(
+        #     name="bottle_rack_3x4",
+        #     size_x=210.0,
+        #     size_y=140.0,
+        #     size_z=100.0,
+        #     num_items_x=2,
+        #     num_items_y=4,
+        #     position_spacing=35.0,
+        #     orientation="vertical",
+        # )
+        # self.assign_child_resource(bottle_rack_3x4, Coordinate(x=1542.0, y=717.0, z=0))
+        
+        # 电解液缓存位 - 6x2布局
+        bottle_rack_6x2 = YIHUA_Electrolyte_12VialCarrier(name="bottle_rack_6x2")
+        self.assign_child_resource(bottle_rack_6x2, Coordinate(x=1050.0, y=358.0, z=0))
+        # 电解液回收位6x2
+        bottle_rack_6x2_2 = YIHUA_Electrolyte_12VialCarrier(name="bottle_rack_6x2_2")
+        self.assign_child_resource(bottle_rack_6x2_2, Coordinate(x=914.0, y=358.0, z=0))
+
+        tip_box = TipBox64(name="tip_box_64")
+        self.assign_child_resource(tip_box, Coordinate(x=782.0, y=514.0, z=0))
+
+        waste_tip_box = WasteTipBox(name="waste_tip_box")
+        self.assign_child_resource(waste_tip_box, Coordinate(x=778.0, y=622.0, z=0))
+
+
+def YH_Deck(name=""):
+    cd = CoincellDeck(name=name)
+    cd.setup()
+    return cd
+
+
+if __name__ == "__main__":
+    deck = create_coin_cell_deck()
+    print(deck)

unilabos/devices/workstation/coin_cell_assembly/coin_cell_assembly_b.csv

@@ -0,0 +1,133 @@
+Name,DataType,InitValue,Comment,Attribute,DeviceType,Address,
+COIL_SYS_START_CMD,BOOL,,,,coil,8010,
+COIL_SYS_STOP_CMD,BOOL,,,,coil,8020,
+COIL_SYS_RESET_CMD,BOOL,,,,coil,8030,
+COIL_SYS_HAND_CMD,BOOL,,,,coil,8040,
+COIL_SYS_AUTO_CMD,BOOL,,,,coil,8050,
+COIL_SYS_INIT_CMD,BOOL,,,,coil,8060,
+COIL_UNILAB_SEND_MSG_SUCC_CMD,BOOL,,,,coil,8700,
+COIL_UNILAB_REC_MSG_SUCC_CMD,BOOL,,,,coil,8710,unilab_rec_msg_succ_cmd
+COIL_SYS_START_STATUS,BOOL,,,,coil,8210,
+COIL_SYS_STOP_STATUS,BOOL,,,,coil,8220,
+COIL_SYS_RESET_STATUS,BOOL,,,,coil,8230,
+COIL_SYS_HAND_STATUS,BOOL,,,,coil,8240,
+COIL_SYS_AUTO_STATUS,BOOL,,,,coil,8250,
+COIL_SYS_INIT_STATUS,BOOL,,,,coil,8260,
+COIL_REQUEST_REC_MSG_STATUS,BOOL,,,,coil,8500,
+COIL_REQUEST_SEND_MSG_STATUS,BOOL,,,,coil,8510,request_send_msg_status
+REG_MSG_ELECTROLYTE_USE_NUM,INT16,,,,hold_register,11000,
+REG_MSG_ELECTROLYTE_NUM,INT16,,,,hold_register,11002,unilab_send_msg_electrolyte_num
+REG_MSG_ELECTROLYTE_VOLUME,INT16,,,,hold_register,11004,unilab_send_msg_electrolyte_vol
+REG_MSG_ASSEMBLY_TYPE,INT16,,,,hold_register,11006,unilab_send_msg_assembly_type
+REG_MSG_ASSEMBLY_PRESSURE,INT16,,,,hold_register,11008,unilab_send_msg_assembly_pressure
+REG_DATA_ASSEMBLY_COIN_CELL_NUM,INT16,,,,hold_register,10000,data_assembly_coin_cell_num
+REG_DATA_OPEN_CIRCUIT_VOLTAGE,FLOAT32,,,,hold_register,10002,data_open_circuit_voltage
+REG_DATA_AXIS_X_POS,FLOAT32,,,,hold_register,10004,
+REG_DATA_AXIS_Y_POS,FLOAT32,,,,hold_register,10006,
+REG_DATA_AXIS_Z_POS,FLOAT32,,,,hold_register,10008,
+REG_DATA_POLE_WEIGHT,FLOAT32,,,,hold_register,10010,data_pole_weight
+REG_DATA_ASSEMBLY_PER_TIME,FLOAT32,,,,hold_register,10012,data_assembly_time
+REG_DATA_ASSEMBLY_PRESSURE,INT16,,,,hold_register,10014,data_assembly_pressure
+REG_DATA_ELECTROLYTE_VOLUME,INT16,,,,hold_register,10016,data_electrolyte_volume
+REG_DATA_COIN_NUM,INT16,,,,hold_register,10018,data_coin_num
+REG_DATA_ELECTROLYTE_CODE,STRING,,,,hold_register,10020,data_electrolyte_code()
+REG_DATA_COIN_CELL_CODE,STRING,,,,hold_register,10030,data_coin_cell_code()
+REG_DATA_STACK_VISON_CODE,STRING,,,,hold_register,12004,data_stack_vision_code()
+REG_DATA_GLOVE_BOX_PRESSURE,FLOAT32,,,,hold_register,10050,data_glove_box_pressure
+REG_DATA_GLOVE_BOX_WATER_CONTENT,FLOAT32,,,,hold_register,10052,data_glove_box_water_content
+REG_DATA_GLOVE_BOX_O2_CONTENT,FLOAT32,,,,hold_register,10054,data_glove_box_o2_content
+UNILAB_SEND_ELECTROLYTE_BOTTLE_NUM,BOOL,,,,coil,8720,
+UNILAB_RECE_ELECTROLYTE_BOTTLE_NUM,BOOL,,,,coil,8520,
+REG_MSG_ELECTROLYTE_NUM_USED,INT16,,,,hold_register,496,
+REG_DATA_ELECTROLYTE_USE_NUM,INT16,,,,hold_register,10000,
+UNILAB_SEND_FINISHED_CMD,BOOL,,,,coil,8730,
+UNILAB_RECE_FINISHED_CMD,BOOL,,,,coil,8530,
+REG_DATA_ASSEMBLY_TYPE,INT16,,,,hold_register,10018,ASSEMBLY_TYPE7or8
+REG_UNILAB_INTERACT,BOOL,,,,coil,8450,
+,,,,,coil,8320,
+COIL_ALUMINUM_FOIL,BOOL,,,,coil,8340,
+REG_MSG_NE_PLATE_MATRIX,INT16,,,,hold_register,440,
+REG_MSG_SEPARATOR_PLATE_MATRIX,INT16,,,,hold_register,450,
+REG_MSG_TIP_BOX_MATRIX,INT16,,,,hold_register,480,
+REG_MSG_NE_PLATE_NUM,INT16,,,,hold_register,443,
+REG_MSG_SEPARATOR_PLATE_NUM,INT16,,,,hold_register,453,
+REG_MSG_PRESS_MODE,BOOL,,,,coil,8360,
+,BOOL,,,,coil,8300,
+,BOOL,,,,coil,8310,
+COIL_GB_L_IGNORE_CMD,BOOL,,,,coil,8320,
+COIL_GB_R_IGNORE_CMD,BOOL,,,,coil,8420,
+,BOOL,,,,coil,8350,
+COIL_ELECTROLYTE_DUAL_DROP_MODE,BOOL,,,,coil,8370,
+,BOOL,,,,coil,8380,
+,BOOL,,,,coil,8390,
+,BOOL,,,,coil,8400,
+,BOOL,,,,coil,8410,
+REG_MSG_DUAL_DROP_FIRST_VOLUME,INT16,,,,hold_register,4001,
+COIL_DUAL_DROP_SUCTION_TIMING,BOOL,,,,coil,8430,
+COIL_DUAL_DROP_START_TIMING,BOOL,,,,coil,8470,
+REG_MSG_BATTERY_CLEAN_IGNORE,BOOL,,,,coil,8460,
+COIL_MATERIAL_SEARCH_DIALOG_APPEAR,BOOL,,,,coil,6470,
+COIL_MATERIAL_SEARCH_CONFIRM_YES,BOOL,,,,coil,6480,
+COIL_MATERIAL_SEARCH_CONFIRM_NO,BOOL,,,,coil,6490,
+COIL_ALARM_100_SYSTEM_ERROR,BOOL,,,,coil,1000,异常100-系统异常
+COIL_ALARM_101_EMERGENCY_STOP,BOOL,,,,coil,1010,异常101-急停
+COIL_ALARM_111_GLOVEBOX_EMERGENCY_STOP,BOOL,,,,coil,1110,异常111-手套箱急停
+COIL_ALARM_112_GLOVEBOX_GRATING_BLOCKED,BOOL,,,,coil,1120,异常112-手套箱内光栅遮挡
+COIL_ALARM_160_PIPETTE_TIP_SHORTAGE,BOOL,,,,coil,1600,异常160-移液枪头缺料
+COIL_ALARM_161_POSITIVE_SHELL_SHORTAGE,BOOL,,,,coil,1610,异常161-正极壳缺料
+COIL_ALARM_162_ALUMINUM_FOIL_SHORTAGE,BOOL,,,,coil,1620,异常162-铝箔垫缺料
+COIL_ALARM_163_POSITIVE_PLATE_SHORTAGE,BOOL,,,,coil,1630,异常163-正极片缺料
+COIL_ALARM_164_SEPARATOR_SHORTAGE,BOOL,,,,coil,1640,异常164-隔膜缺料
+COIL_ALARM_165_NEGATIVE_PLATE_SHORTAGE,BOOL,,,,coil,1650,异常165-负极片缺料
+COIL_ALARM_166_FLAT_WASHER_SHORTAGE,BOOL,,,,coil,1660,异常166-平垫缺料
+COIL_ALARM_167_SPRING_WASHER_SHORTAGE,BOOL,,,,coil,1670,异常167-弹垫缺料
+COIL_ALARM_168_NEGATIVE_SHELL_SHORTAGE,BOOL,,,,coil,1680,异常168-负极壳缺料
+COIL_ALARM_169_FINISHED_BATTERY_FULL,BOOL,,,,coil,1690,异常169-成品电池满料
+COIL_ALARM_201_SERVO_AXIS_01_ERROR,BOOL,,,,coil,2010,异常201-伺服轴01异常
+COIL_ALARM_202_SERVO_AXIS_02_ERROR,BOOL,,,,coil,2020,异常202-伺服轴02异常
+COIL_ALARM_203_SERVO_AXIS_03_ERROR,BOOL,,,,coil,2030,异常203-伺服轴03异常
+COIL_ALARM_204_SERVO_AXIS_04_ERROR,BOOL,,,,coil,2040,异常204-伺服轴04异常
+COIL_ALARM_205_SERVO_AXIS_05_ERROR,BOOL,,,,coil,2050,异常205-伺服轴05异常
+COIL_ALARM_206_SERVO_AXIS_06_ERROR,BOOL,,,,coil,2060,异常206-伺服轴06异常
+COIL_ALARM_207_SERVO_AXIS_07_ERROR,BOOL,,,,coil,2070,异常207-伺服轴07异常
+COIL_ALARM_208_SERVO_AXIS_08_ERROR,BOOL,,,,coil,2080,异常208-伺服轴08异常
+COIL_ALARM_209_SERVO_AXIS_09_ERROR,BOOL,,,,coil,2090,异常209-伺服轴09异常
+COIL_ALARM_210_SERVO_AXIS_10_ERROR,BOOL,,,,coil,2100,异常210-伺服轴10异常
+COIL_ALARM_211_SERVO_AXIS_11_ERROR,BOOL,,,,coil,2110,异常211-伺服轴11异常
+COIL_ALARM_212_SERVO_AXIS_12_ERROR,BOOL,,,,coil,2120,异常212-伺服轴12异常
+COIL_ALARM_213_SERVO_AXIS_13_ERROR,BOOL,,,,coil,2130,异常213-伺服轴13异常
+COIL_ALARM_214_SERVO_AXIS_14_ERROR,BOOL,,,,coil,2140,异常214-伺服轴14异常
+COIL_ALARM_250_OTHER_COMPONENT_ERROR,BOOL,,,,coil,2500,异常250-其他元件异常
+COIL_ALARM_251_PIPETTE_COMM_ERROR,BOOL,,,,coil,2510,异常251-移液枪通讯异常
+COIL_ALARM_252_PIPETTE_ALARM,BOOL,,,,coil,2520,异常252-移液枪报警
+COIL_ALARM_256_ELECTRIC_GRIPPER_ERROR,BOOL,,,,coil,2560,异常256-电爪异常
+COIL_ALARM_262_RB_UNKNOWN_POSITION_ERROR,BOOL,,,,coil,2620,异常262-RB报警：未知点位错误
+COIL_ALARM_263_RB_XYZ_PARAM_LIMIT_ERROR,BOOL,,,,coil,2630,异常263-RB报警：X、Y、Z参数超限制
+COIL_ALARM_264_RB_VISION_PARAM_ERROR,BOOL,,,,coil,2640,异常264-RB报警：视觉参数误差过大
+COIL_ALARM_265_RB_NOZZLE_1_PICK_FAIL,BOOL,,,,coil,2650,异常265-RB报警：1#吸嘴取料失败
+COIL_ALARM_266_RB_NOZZLE_2_PICK_FAIL,BOOL,,,,coil,2660,异常266-RB报警：2#吸嘴取料失败
+COIL_ALARM_267_RB_NOZZLE_3_PICK_FAIL,BOOL,,,,coil,2670,异常267-RB报警：3#吸嘴取料失败
+COIL_ALARM_268_RB_NOZZLE_4_PICK_FAIL,BOOL,,,,coil,2680,异常268-RB报警：4#吸嘴取料失败
+COIL_ALARM_269_RB_TRAY_PICK_FAIL,BOOL,,,,coil,2690,异常269-RB报警：取物料盘失败
+COIL_ALARM_280_RB_COLLISION_ERROR,BOOL,,,,coil,2800,异常280-RB碰撞异常
+COIL_ALARM_290_VISION_SYSTEM_COMM_ERROR,BOOL,,,,coil,2900,异常290-视觉系统通讯异常
+COIL_ALARM_291_VISION_ALIGNMENT_NG,BOOL,,,,coil,2910,异常291-视觉对位NG异常
+COIL_ALARM_292_BARCODE_SCANNER_COMM_ERROR,BOOL,,,,coil,2920,异常292-扫码枪通讯异常
+COIL_ALARM_310_OCV_TRANSFER_NOZZLE_SUCTION_ERROR,BOOL,,,,coil,3100,异常310-开电移载吸嘴吸真空异常
+COIL_ALARM_311_OCV_TRANSFER_NOZZLE_BREAK_ERROR,BOOL,,,,coil,3110,异常311-开电移载吸嘴破真空异常
+COIL_ALARM_312_WEIGHT_TRANSFER_NOZZLE_SUCTION_ERROR,BOOL,,,,coil,3120,异常312-称重移载吸嘴吸真空异常
+COIL_ALARM_313_WEIGHT_TRANSFER_NOZZLE_BREAK_ERROR,BOOL,,,,coil,3130,异常313-称重移载吸嘴破真空异常
+COIL_ALARM_340_OCV_NOZZLE_TRANSFER_CYLINDER_ERROR,BOOL,,,,coil,3400,异常340-开路电压吸嘴移载气缸异常
+COIL_ALARM_342_OCV_NOZZLE_LIFT_CYLINDER_ERROR,BOOL,,,,coil,3420,异常342-开路电压吸嘴升降气缸异常
+COIL_ALARM_344_OCV_CRIMPING_CYLINDER_ERROR,BOOL,,,,coil,3440,异常344-开路电压旋压气缸异常
+COIL_ALARM_350_WEIGHT_NOZZLE_TRANSFER_CYLINDER_ERROR,BOOL,,,,coil,3500,异常350-称重吸嘴移载气缸异常
+COIL_ALARM_352_WEIGHT_NOZZLE_LIFT_CYLINDER_ERROR,BOOL,,,,coil,3520,异常352-称重吸嘴升降气缸异常
+COIL_ALARM_354_CLEANING_CLOTH_TRANSFER_CYLINDER_ERROR,BOOL,,,,coil,3540,异常354-清洗无尘布移载气缸异常
+COIL_ALARM_356_CLEANING_CLOTH_PRESS_CYLINDER_ERROR,BOOL,,,,coil,3560,异常356-清洗无尘布压紧气缸异常
+COIL_ALARM_360_ELECTROLYTE_BOTTLE_POSITION_CYLINDER_ERROR,BOOL,,,,coil,3600,异常360-电解液瓶定位气缸异常
+COIL_ALARM_362_PIPETTE_TIP_BOX_POSITION_CYLINDER_ERROR,BOOL,,,,coil,3620,异常362-移液枪头盒定位气缸异常
+COIL_ALARM_364_REAGENT_BOTTLE_GRIPPER_LIFT_CYLINDER_ERROR,BOOL,,,,coil,3640,异常364-试剂瓶夹爪升降气缸异常
+COIL_ALARM_366_REAGENT_BOTTLE_GRIPPER_CYLINDER_ERROR,BOOL,,,,coil,3660,异常366-试剂瓶夹爪气缸异常
+COIL_ALARM_370_PRESS_MODULE_BLOW_CYLINDER_ERROR,BOOL,,,,coil,3700,异常370-压制模块吹气气缸异常
+COIL_ALARM_151_ELECTROLYTE_BOTTLE_POSITION_ERROR,BOOL,,,,coil,1510,异常151-电解液瓶定位在籍异常
+COIL_ALARM_152_ELECTROLYTE_BOTTLE_CAP_ERROR,BOOL,,,,coil,1520,异常152-电解液瓶盖在籍异常

unilabos/devices/workstation/workstation_http_service.py

@@ -459,12 +459,12 @@ class WorkstationHTTPHandler(BaseHTTPRequestHandler):
             # 验证必需字段
             if 'brand' in request_data:
                 if request_data['brand'] == "bioyond":  # 奔曜
-                    error_msg = request_data["text"]
-                    logger.info(f"收到奔曜错误处理报送: {error_msg}")
+                    material_data = request_data["text"]
+                    logger.info(f"收到奔曜物料变更报送: {material_data}")
                     return HttpResponse(
                         success=True,
-                        message=f"错误处理报送已收到: {error_msg}",
-                        acknowledgment_id=f"ERROR_{int(time.time() * 1000)}_{error_msg.get('action_id', 'unknown')}",
+                        message=f"物料变更报送已收到: {material_data}",
+                        acknowledgment_id=f"MATERIAL_{int(time.time() * 1000)}_{material_data.get('id', 'unknown')}",
                         data=None
                     )
             else:

unilabos/labware_manager/__init__.py

@@ -1 +0,0 @@
-# PRCXI 耗材管理 Web 应用

unilabos/labware_manager/__main__.py

@@ -1,4 +0,0 @@
-"""启动入口: python -m unilabos.labware_manager"""
-from unilabos.labware_manager.app import main
-
-main()

unilabos/labware_manager/app.py

@@ -1,196 +0,0 @@
-"""FastAPI 应用 + CRUD API + 启动入口。
-
-用法: python -m unilabos.labware_manager.app
-"""
-
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-from typing import List, Optional
-
-from fastapi import FastAPI, HTTPException, Query, Request
-from fastapi.responses import HTMLResponse, JSONResponse
-from fastapi.staticfiles import StaticFiles
-from fastapi.templating import Jinja2Templates
-
-from unilabos.labware_manager.models import LabwareDB, LabwareItem
-
-_HERE = Path(__file__).resolve().parent
-_DB_PATH = _HERE / "labware_db.json"
-
-app = FastAPI(title="PRCXI 耗材管理", version="1.0")
-
-# 静态文件 + 模板
-app.mount("/static", StaticFiles(directory=str(_HERE / "static")), name="static")
-templates = Jinja2Templates(directory=str(_HERE / "templates"))
-
-
-# ---------- DB 读写 ----------
-
-def _load_db() -> LabwareDB:
-    if not _DB_PATH.exists():
-        return LabwareDB()
-    with open(_DB_PATH, "r", encoding="utf-8") as f:
-        return LabwareDB(**json.load(f))
-
-
-def _save_db(db: LabwareDB) -> None:
-    with open(_DB_PATH, "w", encoding="utf-8") as f:
-        json.dump(db.model_dump(), f, ensure_ascii=False, indent=2)
-
-
-# ---------- 页面路由 ----------
-
-@app.get("/", response_class=HTMLResponse)
-async def index_page(request: Request):
-    db = _load_db()
-    # 按 type 分组
-    groups = {}
-    for item in db.items:
-        groups.setdefault(item.type, []).append(item)
-    return templates.TemplateResponse("index.html", {
-        "request": request,
-        "groups": groups,
-        "total": len(db.items),
-    })
-
-
-@app.get("/labware/new", response_class=HTMLResponse)
-async def new_page(request: Request, type: str = "plate"):
-    return templates.TemplateResponse("edit.html", {
-        "request": request,
-        "item": None,
-        "labware_type": type,
-        "is_new": True,
-    })
-
-
-@app.get("/labware/{item_id}", response_class=HTMLResponse)
-async def detail_page(request: Request, item_id: str):
-    db = _load_db()
-    item = _find_item(db, item_id)
-    if not item:
-        raise HTTPException(404, "耗材不存在")
-    return templates.TemplateResponse("detail.html", {
-        "request": request,
-        "item": item,
-    })
-
-
-@app.get("/labware/{item_id}/edit", response_class=HTMLResponse)
-async def edit_page(request: Request, item_id: str):
-    db = _load_db()
-    item = _find_item(db, item_id)
-    if not item:
-        raise HTTPException(404, "耗材不存在")
-    return templates.TemplateResponse("edit.html", {
-        "request": request,
-        "item": item,
-        "labware_type": item.type,
-        "is_new": False,
-    })
-
-
-# ---------- API 端点 ----------
-
-@app.get("/api/labware")
-async def api_list_labware():
-    db = _load_db()
-    return {"items": [item.model_dump() for item in db.items]}
-
-
-@app.post("/api/labware")
-async def api_create_labware(request: Request):
-    data = await request.json()
-    db = _load_db()
-    item = LabwareItem(**data)
-    # 确保 id 唯一
-    existing_ids = {it.id for it in db.items}
-    while item.id in existing_ids:
-        import uuid
-        item.id = uuid.uuid4().hex[:8]
-    db.items.append(item)
-    _save_db(db)
-    return {"status": "ok", "id": item.id}
-
-
-@app.put("/api/labware/{item_id}")
-async def api_update_labware(item_id: str, request: Request):
-    data = await request.json()
-    db = _load_db()
-    for i, it in enumerate(db.items):
-        if it.id == item_id or it.function_name == item_id:
-            updated = LabwareItem(**{**it.model_dump(), **data, "id": it.id})
-            db.items[i] = updated
-            _save_db(db)
-            return {"status": "ok", "id": it.id}
-    raise HTTPException(404, "耗材不存在")
-
-
-@app.delete("/api/labware/{item_id}")
-async def api_delete_labware(item_id: str):
-    db = _load_db()
-    original_len = len(db.items)
-    db.items = [it for it in db.items if it.id != item_id and it.function_name != item_id]
-    if len(db.items) == original_len:
-        raise HTTPException(404, "耗材不存在")
-    _save_db(db)
-    return {"status": "ok"}
-
-
-@app.post("/api/generate-code")
-async def api_generate_code(request: Request):
-    body = await request.json() if await request.body() else {}
-    test_mode = body.get("test_mode", True)
-    db = _load_db()
-    if not db.items:
-        raise HTTPException(400, "数据库为空，请先导入")
-
-    from unilabos.labware_manager.codegen import generate_code
-    from unilabos.labware_manager.yaml_gen import generate_yaml
-
-    py_path = generate_code(db, test_mode=test_mode)
-    yaml_paths = generate_yaml(db, test_mode=test_mode)
-
-    return {
-        "status": "ok",
-        "python_file": str(py_path),
-        "yaml_files": [str(p) for p in yaml_paths],
-        "test_mode": test_mode,
-    }
-
-
-@app.post("/api/import-from-code")
-async def api_import_from_code():
-    from unilabos.labware_manager.importer import import_from_code, save_db
-    db = import_from_code()
-    save_db(db)
-    return {
-        "status": "ok",
-        "count": len(db.items),
-        "items": [{"function_name": it.function_name, "type": it.type} for it in db.items],
-    }
-
-
-# ---------- 辅助函数 ----------
-
-def _find_item(db: LabwareDB, item_id: str) -> Optional[LabwareItem]:
-    for item in db.items:
-        if item.id == item_id or item.function_name == item_id:
-            return item
-    return None
-
-
-# ---------- 启动入口 ----------
-
-def main():
-    import uvicorn
-    port = int(os.environ.get("LABWARE_PORT", "8010"))
-    print(f"PRCXI 耗材管理 → http://localhost:{port}")
-    uvicorn.run(app, host="0.0.0.0", port=port)
-
-
-if __name__ == "__main__":
-    main()

unilabos/labware_manager/codegen.py

@@ -1,451 +0,0 @@
-"""JSON → prcxi_labware.py 代码生成。
-
-读取 labware_db.json，输出完整的 prcxi_labware.py（或 prcxi_labware_test.py）。
-"""
-
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-from typing import List, Optional
-
-from unilabos.labware_manager.models import LabwareDB, LabwareItem
-
-_TARGET_DIR = Path(__file__).resolve().parents[1] / "devices" / "liquid_handling" / "prcxi"
-
-# ---------- 固定头部 ----------
-_HEADER = '''\
-from typing import Any, Callable, Dict, List, Optional, Tuple
-from pylabrobot.resources import Tube, Coordinate
-from pylabrobot.resources.well import Well, WellBottomType, CrossSectionType
-from pylabrobot.resources.tip import Tip, TipCreator
-from pylabrobot.resources.tip_rack import TipRack, TipSpot
-from pylabrobot.resources.utils import create_ordered_items_2d
-from pylabrobot.resources.height_volume_functions import (
-    compute_height_from_volume_rectangle,
-    compute_volume_from_height_rectangle,
-)
-
-from .prcxi import PRCXI9300Plate, PRCXI9300TipRack, PRCXI9300Trash, PRCXI9300TubeRack, PRCXI9300PlateAdapter
-
-def _make_tip_helper(volume: float, length: float, depth: float) -> Tip:
-    """
-    PLR 的 Tip 类参数名为: maximal_volume, total_tip_length, fitting_depth
-    """
-    return Tip(
-        has_filter=False, # 默认无滤芯
-        maximal_volume=volume,
-        total_tip_length=length,
-        fitting_depth=depth
-    )
-
-'''
-
-
-def _gen_plate(item: LabwareItem) -> str:
-    """生成 Plate 类型的工厂函数代码。"""
-    lines = []
-    fn = item.function_name
-    doc = item.docstring or f"Code: {item.material_info.Code}"
-
-    has_vf = item.volume_functions is not None
-
-    if has_vf:
-        # 有 volume_functions 时需要 well_kwargs 方式
-        vf = item.volume_functions
-        well = item.well
-        grid = item.grid
-
-        lines.append(f'def {fn}(name: str) -> PRCXI9300Plate:')
-        lines.append(f'    """')
-        for dl in doc.split('\n'):
-            lines.append(f'    {dl}')
-        lines.append(f'    """')
-
-        # 计算 well_size 变量
-        lines.append(f'    well_size_x = {well.size_x}')
-        lines.append(f'    well_size_y = {well.size_y}')
-
-        lines.append(f'    well_kwargs = {{')
-        lines.append(f'        "size_x": well_size_x,')
-        lines.append(f'        "size_y": well_size_y,')
-        lines.append(f'        "size_z": {well.size_z},')
-        lines.append(f'        "bottom_type": WellBottomType.{well.bottom_type},')
-        if well.cross_section_type and well.cross_section_type != "CIRCLE":
-            lines.append(f'        "cross_section_type": CrossSectionType.{well.cross_section_type},')
-        lines.append(f'        "compute_height_from_volume": lambda liquid_volume: compute_height_from_volume_rectangle(')
-        lines.append(f'            liquid_volume=liquid_volume, well_length=well_size_x, well_width=well_size_y')
-        lines.append(f'        ),')
-        lines.append(f'        "compute_volume_from_height": lambda liquid_height: compute_volume_from_height_rectangle(')
-        lines.append(f'            liquid_height=liquid_height, well_length=well_size_x, well_width=well_size_y')
-        lines.append(f'        ),')
-        if well.material_z_thickness is not None:
-            lines.append(f'        "material_z_thickness": {well.material_z_thickness},')
-        lines.append(f'    }}')
-        lines.append(f'')
-        lines.append(f'    return PRCXI9300Plate(')
-        lines.append(f'        name=name,')
-        lines.append(f'        size_x={item.size_x},')
-        lines.append(f'        size_y={item.size_y},')
-        lines.append(f'        size_z={item.size_z},')
-        lines.append(f'        lid=None,')
-        lines.append(f'        model="{item.model}",')
-        lines.append(f'        category="plate",')
-        lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))},')
-        lines.append(f'        ordered_items=create_ordered_items_2d(')
-        lines.append(f'            Well,')
-        lines.append(f'            num_items_x={grid.num_items_x},')
-        lines.append(f'            num_items_y={grid.num_items_y},')
-        lines.append(f'            dx={grid.dx},')
-        lines.append(f'            dy={grid.dy},')
-        lines.append(f'            dz={grid.dz},')
-        lines.append(f'            item_dx={grid.item_dx},')
-        lines.append(f'            item_dy={grid.item_dy},')
-        lines.append(f'            **well_kwargs,')
-        lines.append(f'        ),')
-        lines.append(f'    )')
-    else:
-        # 普通 plate
-        well = item.well
-        grid = item.grid
-
-        lines.append(f'def {fn}(name: str) -> PRCXI9300Plate:')
-        lines.append(f'    """')
-        for dl in doc.split('\n'):
-            lines.append(f'    {dl}')
-        lines.append(f'    """')
-        lines.append(f'    return PRCXI9300Plate(')
-        lines.append(f'        name=name,')
-        lines.append(f'        size_x={item.size_x},')
-        lines.append(f'        size_y={item.size_y},')
-        lines.append(f'        size_z={item.size_z},')
-        if item.plate_type:
-            lines.append(f'        plate_type="{item.plate_type}",')
-        lines.append(f'        model="{item.model}",')
-        lines.append(f'        category="plate",')
-        lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))},')
-        if grid and well:
-            lines.append(f'        ordered_items=create_ordered_items_2d(')
-            lines.append(f'            Well,')
-            lines.append(f'            num_items_x={grid.num_items_x},')
-            lines.append(f'            num_items_y={grid.num_items_y},')
-            lines.append(f'            dx={grid.dx},')
-            lines.append(f'            dy={grid.dy},')
-            lines.append(f'            dz={grid.dz},')
-            lines.append(f'            item_dx={grid.item_dx},')
-            lines.append(f'            item_dy={grid.item_dy},')
-            lines.append(f'            size_x={well.size_x},')
-            lines.append(f'            size_y={well.size_y},')
-            lines.append(f'            size_z={well.size_z},')
-            if well.max_volume is not None:
-                lines.append(f'            max_volume={well.max_volume},')
-            if well.material_z_thickness is not None:
-                lines.append(f'            material_z_thickness={well.material_z_thickness},')
-            if well.bottom_type and well.bottom_type != "FLAT":
-                lines.append(f'            bottom_type=WellBottomType.{well.bottom_type},')
-            if well.cross_section_type:
-                lines.append(f'            cross_section_type=CrossSectionType.{well.cross_section_type},')
-            lines.append(f'        ),')
-        lines.append(f'    )')
-
-    return '\n'.join(lines)
-
-
-def _gen_tip_rack(item: LabwareItem) -> str:
-    """生成 TipRack 工厂函数代码。"""
-    lines = []
-    fn = item.function_name
-    doc = item.docstring or f"Code: {item.material_info.Code}"
-    grid = item.grid
-    tip = item.tip
-
-    lines.append(f'def {fn}(name: str) -> PRCXI9300TipRack:')
-    lines.append(f'    """')
-    for dl in doc.split('\n'):
-        lines.append(f'    {dl}')
-    lines.append(f'    """')
-    lines.append(f'    return PRCXI9300TipRack(')
-    lines.append(f'        name=name,')
-    lines.append(f'        size_x={item.size_x},')
-    lines.append(f'        size_y={item.size_y},')
-    lines.append(f'        size_z={item.size_z},')
-    lines.append(f'        model="{item.model}",')
-    lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))},')
-    if grid and tip:
-        lines.append(f'        ordered_items=create_ordered_items_2d(')
-        lines.append(f'            TipSpot,')
-        lines.append(f'            num_items_x={grid.num_items_x},')
-        lines.append(f'            num_items_y={grid.num_items_y},')
-        lines.append(f'            dx={grid.dx},')
-        lines.append(f'            dy={grid.dy},')
-        lines.append(f'            dz={grid.dz},')
-        lines.append(f'            item_dx={grid.item_dx},')
-        lines.append(f'            item_dy={grid.item_dy},')
-        lines.append(f'            size_x={tip.spot_size_x},')
-        lines.append(f'            size_y={tip.spot_size_y},')
-        lines.append(f'            size_z={tip.spot_size_z},')
-        lines.append(f'            make_tip=lambda: _make_tip_helper(volume={tip.tip_volume}, length={tip.tip_length}, depth={tip.tip_fitting_depth})')
-        lines.append(f'        )')
-    lines.append(f'    )')
-
-    return '\n'.join(lines)
-
-
-def _gen_trash(item: LabwareItem) -> str:
-    """生成 Trash 工厂函数代码。"""
-    lines = []
-    fn = item.function_name
-    doc = item.docstring or f"Code: {item.material_info.Code}"
-
-    lines.append(f'def {fn}(name: str = "trash") -> PRCXI9300Trash:')
-    lines.append(f'    """')
-    for dl in doc.split('\n'):
-        lines.append(f'    {dl}')
-    lines.append(f'    """')
-    lines.append(f'    return PRCXI9300Trash(')
-    lines.append(f'        name="trash",')
-    lines.append(f'        size_x={item.size_x},')
-    lines.append(f'        size_y={item.size_y},')
-    lines.append(f'        size_z={item.size_z},')
-    lines.append(f'        category="trash",')
-    lines.append(f'        model="{item.model}",')
-    lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))}')
-    lines.append(f'    )')
-
-    return '\n'.join(lines)
-
-
-def _gen_tube_rack(item: LabwareItem) -> str:
-    """生成 TubeRack 工厂函数代码。"""
-    lines = []
-    fn = item.function_name
-    doc = item.docstring or f"Code: {item.material_info.Code}"
-    grid = item.grid
-    tube = item.tube
-
-    lines.append(f'def {fn}(name: str) -> PRCXI9300TubeRack:')
-    lines.append(f'    """')
-    for dl in doc.split('\n'):
-        lines.append(f'    {dl}')
-    lines.append(f'    """')
-    lines.append(f'    return PRCXI9300TubeRack(')
-    lines.append(f'        name=name,')
-    lines.append(f'        size_x={item.size_x},')
-    lines.append(f'        size_y={item.size_y},')
-    lines.append(f'        size_z={item.size_z},')
-    lines.append(f'        model="{item.model}",')
-    lines.append(f'        category="tube_rack",')
-    lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))},')
-    if grid and tube:
-        lines.append(f'        ordered_items=create_ordered_items_2d(')
-        lines.append(f'            Tube,')
-        lines.append(f'            num_items_x={grid.num_items_x},')
-        lines.append(f'            num_items_y={grid.num_items_y},')
-        lines.append(f'            dx={grid.dx},')
-        lines.append(f'            dy={grid.dy},')
-        lines.append(f'            dz={grid.dz},')
-        lines.append(f'            item_dx={grid.item_dx},')
-        lines.append(f'            item_dy={grid.item_dy},')
-        lines.append(f'            size_x={tube.size_x},')
-        lines.append(f'            size_y={tube.size_y},')
-        lines.append(f'            size_z={tube.size_z},')
-        lines.append(f'            max_volume={tube.max_volume}')
-        lines.append(f'        )')
-    lines.append(f'    )')
-
-    return '\n'.join(lines)
-
-
-def _gen_plate_adapter(item: LabwareItem) -> str:
-    """生成 PlateAdapter 工厂函数代码。"""
-    lines = []
-    fn = item.function_name
-    doc = item.docstring or f"Code: {item.material_info.Code}"
-
-    lines.append(f'def {fn}(name: str) -> PRCXI9300PlateAdapter:')
-    lines.append(f'    """ {doc} """')
-    lines.append(f'    return PRCXI9300PlateAdapter(')
-    lines.append(f'        name=name,')
-    lines.append(f'        size_x={item.size_x},')
-    lines.append(f'        size_y={item.size_y},')
-    lines.append(f'        size_z={item.size_z},')
-    if item.model:
-        lines.append(f'        model="{item.model}",')
-    lines.append(f'        material_info={_fmt_dict(item.material_info.model_dump(exclude_none=True))}')
-    lines.append(f'    )')
-
-    return '\n'.join(lines)
-
-
-def _fmt_dict(d: dict) -> str:
-    """格式化字典为 Python 代码片段。"""
-    parts = []
-    for k, v in d.items():
-        if isinstance(v, str):
-            parts.append(f'"{k}": "{v}"')
-        elif v is None:
-            continue
-        else:
-            parts.append(f'"{k}": {v}')
-    return '{' + ', '.join(parts) + '}'
-
-
-def _gen_template_factory_kinds(items: List[LabwareItem]) -> str:
-    """生成 PRCXI_TEMPLATE_FACTORY_KINDS 列表。"""
-    lines = ['PRCXI_TEMPLATE_FACTORY_KINDS: List[Tuple[Callable[..., Any], str]] = [']
-    for item in items:
-        if item.include_in_template_matching and item.template_kind:
-            lines.append(f'    ({item.function_name}, "{item.template_kind}"),')
-    lines.append(']')
-    return '\n'.join(lines)
-
-
-def _gen_footer() -> str:
-    """生成文件尾部的模板相关代码。"""
-    return '''
-
-# ---------------------------------------------------------------------------
-# 协议上传 / workflow 用：与设备端耗材字典字段对齐的模板描述（供 common 自动匹配）
-# ---------------------------------------------------------------------------
-
-_PRCXI_TEMPLATE_SPECS_CACHE: Optional[List[Dict[str, Any]]] = None
-
-
-def _probe_prcxi_resource(factory: Callable[..., Any]) -> Any:
-    probe = "__unilab_template_probe__"
-    if factory.__name__ == "PRCXI_trash":
-        return factory()
-    return factory(probe)
-
-
-def _first_child_capacity_for_match(resource: Any) -> float:
-    """Well max_volume 或 Tip 的 maximal_volume，用于与设备端 Volume 类似的打分。"""
-    ch = getattr(resource, "children", None) or []
-    if not ch:
-        return 0.0
-    c0 = ch[0]
-    mv = getattr(c0, "max_volume", None)
-    if mv is not None:
-        return float(mv)
-    tip = getattr(c0, "tip", None)
-    if tip is not None:
-        mv2 = getattr(tip, "maximal_volume", None)
-        if mv2 is not None:
-            return float(mv2)
-    return 0.0
-
-
-def get_prcxi_labware_template_specs() -> List[Dict[str, Any]]:
-    """返回与 ``prcxi._match_and_create_matrix`` 中耗材字段兼容的模板列表，用于按孔数+容量打分。"""
-    global _PRCXI_TEMPLATE_SPECS_CACHE
-    if _PRCXI_TEMPLATE_SPECS_CACHE is not None:
-        return _PRCXI_TEMPLATE_SPECS_CACHE
-
-    out: List[Dict[str, Any]] = []
-    for factory, kind in PRCXI_TEMPLATE_FACTORY_KINDS:
-        try:
-            r = _probe_prcxi_resource(factory)
-        except Exception:
-            continue
-        nx = int(getattr(r, "num_items_x", None) or 0)
-        ny = int(getattr(r, "num_items_y", None) or 0)
-        nchild = len(getattr(r, "children", []) or [])
-        hole_count = nx * ny if nx > 0 and ny > 0 else nchild
-        hole_row = ny if nx > 0 and ny > 0 else 0
-        hole_col = nx if nx > 0 and ny > 0 else 0
-        mi = getattr(r, "material_info", None) or {}
-        vol = _first_child_capacity_for_match(r)
-        menum = mi.get("materialEnum")
-        if menum is None and kind == "tip_rack":
-            menum = 1
-        elif menum is None and kind == "trash":
-            menum = 6
-        out.append(
-            {
-                "class_name": factory.__name__,
-                "kind": kind,
-                "materialEnum": menum,
-                "HoleRow": hole_row,
-                "HoleColum": hole_col,
-                "Volume": vol,
-                "hole_count": hole_count,
-                "material_uuid": mi.get("uuid"),
-                "material_code": mi.get("Code"),
-            }
-        )
-
-    _PRCXI_TEMPLATE_SPECS_CACHE = out
-    return out
-'''
-
-
-def generate_code(db: LabwareDB, test_mode: bool = True) -> Path:
-    """生成 prcxi_labware.py (或 _test.py)，返回输出文件路径。"""
-    suffix = "_test" if test_mode else ""
-    out_path = _TARGET_DIR / f"prcxi_labware{suffix}.py"
-
-    # 备份
-    if out_path.exists():
-        bak = out_path.with_suffix(".py.bak")
-        shutil.copy2(out_path, bak)
-
-    # 按类型分组的生成器
-    generators = {
-        "plate": _gen_plate,
-        "tip_rack": _gen_tip_rack,
-        "trash": _gen_trash,
-        "tube_rack": _gen_tube_rack,
-        "plate_adapter": _gen_plate_adapter,
-    }
-
-    # 按 type 分段
-    sections = {
-        "plate": [],
-        "tip_rack": [],
-        "trash": [],
-        "tube_rack": [],
-        "plate_adapter": [],
-    }
-
-    for item in db.items:
-        gen = generators.get(item.type)
-        if gen:
-            sections[item.type].append(gen(item))
-
-    # 组装完整文件
-    parts = [_HEADER]
-
-    section_titles = {
-        "plate": "# =========================================================================\n# Plates\n# =========================================================================",
-        "tip_rack": "# =========================================================================\n# Tip Racks\n# =========================================================================",
-        "trash": "# =========================================================================\n# Trash\n# =========================================================================",
-        "tube_rack": "# =========================================================================\n# Tube Racks\n# =========================================================================",
-        "plate_adapter": "# =========================================================================\n# Plate Adapters\n# =========================================================================",
-    }
-
-    for type_key in ["plate", "tip_rack", "trash", "tube_rack", "plate_adapter"]:
-        if sections[type_key]:
-            parts.append(section_titles[type_key])
-            for code in sections[type_key]:
-                parts.append(code)
-
-    # Template factory kinds
-    parts.append("")
-    parts.append(_gen_template_factory_kinds(db.items))
-
-    # Footer
-    parts.append(_gen_footer())
-
-    content = '\n'.join(parts)
-    out_path.write_text(content, encoding="utf-8")
-    return out_path
-
-
-if __name__ == "__main__":
-    from unilabos.labware_manager.importer import load_db
-    db = load_db()
-    if not db.items:
-        print("labware_db.json 为空，请先运行 importer.py")
-    else:
-        out = generate_code(db, test_mode=True)
-        print(f"已生成 {out} ({len(db.items)} 个工厂函数)")

unilabos/labware_manager/importer.py

@@ -1,474 +0,0 @@
-"""从现有 prcxi_labware.py + registry YAML 导入耗材数据到 labware_db.json。
-
-策略：
-1. 实例化每个工厂函数 → 提取物理尺寸、material_info、children
-2. AST 解析源码 → 提取 docstring、volume_function 参数、plate_type
-3. 从 children[0].location 反推 dx/dy/dz，相邻位置差推 item_dx/item_dy
-4. 同时读取现有 YAML → 提取 registry_category / description
-"""
-
-from __future__ import annotations
-
-import ast
-import json
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-import yaml
-
-# 将项目根目录加入 sys.path 以便 import
-_PROJECT_ROOT = Path(__file__).resolve().parents[2]
-if str(_PROJECT_ROOT) not in sys.path:
-    sys.path.insert(0, str(_PROJECT_ROOT))
-
-from unilabos.labware_manager.models import (
-    AdapterInfo,
-    GridInfo,
-    LabwareDB,
-    LabwareItem,
-    MaterialInfo,
-    TipInfo,
-    TubeInfo,
-    VolumeFunctions,
-    WellInfo,
-)
-
-# ---------- 路径常量 ----------
-_LABWARE_PY = Path(__file__).resolve().parents[1] / "devices" / "liquid_handling" / "prcxi" / "prcxi_labware.py"
-_REGISTRY_DIR = Path(__file__).resolve().parents[1] / "registry" / "resources" / "prcxi"
-_DB_PATH = Path(__file__).resolve().parent / "labware_db.json"
-
-# YAML 文件名 → type 映射
-_YAML_MAP: Dict[str, str] = {
-    "plates.yaml": "plate",
-    "tip_racks.yaml": "tip_rack",
-    "trash.yaml": "trash",
-    "tube_racks.yaml": "tube_rack",
-    "plate_adapters.yaml": "plate_adapter",
-}
-
-# PRCXI_TEMPLATE_FACTORY_KINDS 中列出的函数名（include_in_template_matching=True）
-_TEMPLATE_FACTORY_NAMES = {
-    "PRCXI_BioER_96_wellplate", "PRCXI_nest_1_troughplate",
-    "PRCXI_BioRad_384_wellplate", "PRCXI_AGenBio_4_troughplate",
-    "PRCXI_nest_12_troughplate", "PRCXI_CellTreat_96_wellplate",
-    "PRCXI_10ul_eTips", "PRCXI_300ul_Tips",
-    "PRCXI_PCR_Plate_200uL_nonskirted", "PRCXI_PCR_Plate_200uL_semiskirted",
-    "PRCXI_PCR_Plate_200uL_skirted", "PRCXI_trash",
-    "PRCXI_96_DeepWell", "PRCXI_EP_Adapter",
-    "PRCXI_1250uL_Tips", "PRCXI_10uL_Tips",
-    "PRCXI_1000uL_Tips", "PRCXI_200uL_Tips",
-    "PRCXI_48_DeepWell",
-}
-
-# template_kind 对应
-_TEMPLATE_KINDS: Dict[str, str] = {
-    "PRCXI_BioER_96_wellplate": "plate",
-    "PRCXI_nest_1_troughplate": "plate",
-    "PRCXI_BioRad_384_wellplate": "plate",
-    "PRCXI_AGenBio_4_troughplate": "plate",
-    "PRCXI_nest_12_troughplate": "plate",
-    "PRCXI_CellTreat_96_wellplate": "plate",
-    "PRCXI_10ul_eTips": "tip_rack",
-    "PRCXI_300ul_Tips": "tip_rack",
-    "PRCXI_PCR_Plate_200uL_nonskirted": "plate",
-    "PRCXI_PCR_Plate_200uL_semiskirted": "plate",
-    "PRCXI_PCR_Plate_200uL_skirted": "plate",
-    "PRCXI_trash": "trash",
-    "PRCXI_96_DeepWell": "plate",
-    "PRCXI_EP_Adapter": "tube_rack",
-    "PRCXI_1250uL_Tips": "tip_rack",
-    "PRCXI_10uL_Tips": "tip_rack",
-    "PRCXI_1000uL_Tips": "tip_rack",
-    "PRCXI_200uL_Tips": "tip_rack",
-    "PRCXI_48_DeepWell": "plate",
-}
-
-
-def _load_registry_info() -> Dict[str, Dict[str, Any]]:
-    """读取所有 registry YAML 文件，返回 {function_name: {category, description}} 映射。"""
-    info: Dict[str, Dict[str, Any]] = {}
-    for fname, ltype in _YAML_MAP.items():
-        fpath = _REGISTRY_DIR / fname
-        if not fpath.exists():
-            continue
-        with open(fpath, "r", encoding="utf-8") as f:
-            data = yaml.safe_load(f) or {}
-        for func_name, entry in data.items():
-            info[func_name] = {
-                "registry_category": entry.get("category", ["prcxi", ltype.replace("plate_adapter", "plate_adapters")]),
-                "registry_description": entry.get("description", ""),
-            }
-    return info
-
-
-def _parse_ast_info() -> Dict[str, Dict[str, Any]]:
-    """AST 解析 prcxi_labware.py，提取每个工厂函数的 docstring 和 volume_function 参数。"""
-    source = _LABWARE_PY.read_text(encoding="utf-8")
-    tree = ast.parse(source)
-    result: Dict[str, Dict[str, Any]] = {}
-
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.FunctionDef):
-            continue
-        fname = node.name
-        if not fname.startswith("PRCXI_"):
-            continue
-        if fname.startswith("_"):
-            continue
-
-        info: Dict[str, Any] = {"docstring": "", "volume_functions": None, "plate_type": None}
-
-        # docstring
-        doc = ast.get_docstring(node)
-        if doc:
-            info["docstring"] = doc.strip()
-
-        # 搜索函数体中的 plate_type 赋值和 volume_function 参数
-        func_source = ast.get_source_segment(source, node) or ""
-
-        # plate_type
-        m = re.search(r'plate_type\s*=\s*["\']([^"\']+)["\']', func_source)
-        if m:
-            info["plate_type"] = m.group(1)
-
-        # volume_functions: 检查 compute_height_from_volume_rectangle
-        if "compute_height_from_volume_rectangle" in func_source:
-            # 提取 well_length 和 well_width
-            vf: Dict[str, Any] = {"type": "rectangle"}
-            # 尝试从 lambda 中提取
-            wl_match = re.search(r'well_length\s*=\s*([\w_.]+)', func_source)
-            ww_match = re.search(r'well_width\s*=\s*([\w_.]+)', func_source)
-            if wl_match:
-                vf["well_length_var"] = wl_match.group(1)
-            if ww_match:
-                vf["well_width_var"] = ww_match.group(1)
-            info["volume_functions"] = vf
-
-        result[fname] = info
-
-    return result
-
-
-def _probe_factory(factory_func) -> Any:
-    """实例化工厂函数获取 resource 对象。"""
-    if factory_func.__name__ == "PRCXI_trash":
-        return factory_func()
-    return factory_func("__probe__")
-
-
-def _get_size(resource, attr: str) -> float:
-    """获取 PLR Resource 的尺寸（兼容 size_x 和 _size_x）。"""
-    val = getattr(resource, attr, None)
-    if val is None:
-        val = getattr(resource, f"_{attr}", None)
-    if val is None:
-        val = getattr(resource, f"get_{attr}", lambda: 0)()
-    return float(val or 0)
-
-
-def _extract_grid_from_children(resource) -> Optional[Dict[str, Any]]:
-    """从 resource.children 提取网格信息。"""
-    children = getattr(resource, "children", None) or []
-    if not children:
-        return None
-
-    # 获取 num_items_x, num_items_y
-    num_x = getattr(resource, "num_items_x", None)
-    num_y = getattr(resource, "num_items_y", None)
-    if num_x is None or num_y is None:
-        return None
-
-    c0 = children[0]
-    loc0 = getattr(c0, "location", None)
-    dx = loc0.x if loc0 else 0.0
-    dy_raw = loc0.y if loc0 else 0.0  # 这是 PLR 布局后的位置，不是输入参数
-    dz = loc0.z if loc0 else 0.0
-
-    # 推算 item_dx, item_dy
-    item_dx = 9.0
-    item_dy = 9.0
-    if len(children) > 1:
-        c1 = children[1]
-        loc1 = getattr(c1, "location", None)
-        if loc1 and loc0:
-            diff_x = abs(loc1.x - loc0.x)
-            diff_y = abs(loc1.y - loc0.y)
-            if diff_x > 0.1:
-                item_dx = diff_x
-            if diff_y > 0.1:
-                item_dy = diff_y
-
-    # 如果 num_items_y > 1 且 num_items_x > 1, 找列间距
-    if int(num_y) > 1 and int(num_x) > 1 and len(children) >= int(num_y) + 1:
-        cn = children[int(num_y)]
-        locn = getattr(cn, "location", None)
-        if locn and loc0:
-            col_diff = abs(locn.x - loc0.x)
-            row_diff = abs(children[1].location.y - loc0.y) if len(children) > 1 else item_dy
-            if col_diff > 0.1:
-                item_dx = col_diff
-            if row_diff > 0.1:
-                item_dy = row_diff
-
-    # PLR create_ordered_items_2d 的 Y 轴排列是倒序的：
-    # child[0].y = dy_param + (num_y - 1) * item_dy  (最上面一行)
-    # 因此反推原始 dy 参数：
-    dy = dy_raw - (int(num_y) - 1) * item_dy
-
-    return {
-        "num_items_x": int(num_x),
-        "num_items_y": int(num_y),
-        "dx": round(dx, 4),
-        "dy": round(dy, 4),
-        "dz": round(dz, 4),
-        "item_dx": round(item_dx, 4),
-        "item_dy": round(item_dy, 4),
-    }
-
-
-def _extract_well_info(child) -> Dict[str, Any]:
-    """从 Well/TipSpot/Tube 子对象提取信息。"""
-    # material_z_thickness 在 PLR 中如果未设置会抛 NotImplementedError
-    mzt = None
-    try:
-        mzt = child.material_z_thickness
-    except (NotImplementedError, AttributeError):
-        mzt = getattr(child, "_material_z_thickness", None)
-
-    return {
-        "size_x": round(_get_size(child, "size_x"), 4),
-        "size_y": round(_get_size(child, "size_y"), 4),
-        "size_z": round(_get_size(child, "size_z"), 4),
-        "max_volume": getattr(child, "max_volume", None),
-        "bottom_type": getattr(child, "bottom_type", None),
-        "cross_section_type": getattr(child, "cross_section_type", None),
-        "material_z_thickness": mzt,
-    }
-
-
-def import_from_code() -> LabwareDB:
-    """执行完整的导入流程，返回 LabwareDB 对象。"""
-    # 1. 加载 registry 信息
-    reg_info = _load_registry_info()
-
-    # 2. AST 解析源码
-    ast_info = _parse_ast_info()
-
-    # 3. 导入工厂模块（通过包路径避免 relative import 问题）
-    import importlib
-    mod = importlib.import_module("unilabos.devices.liquid_handling.prcxi.prcxi_labware")
-
-    # 4. 获取 PRCXI_TEMPLATE_FACTORY_KINDS 列出的函数
-    factory_kinds = getattr(mod, "PRCXI_TEMPLATE_FACTORY_KINDS", [])
-    template_func_names = {f.__name__ for f, _k in factory_kinds}
-
-    # 5. 收集所有 PRCXI_ 开头的工厂函数
-    all_factories: List[Tuple[str, Any]] = []
-    for attr_name in dir(mod):
-        if attr_name.startswith("PRCXI_") and not attr_name.startswith("_"):
-            obj = getattr(mod, attr_name)
-            if callable(obj) and not isinstance(obj, type):
-                all_factories.append((attr_name, obj))
-
-    # 按源码行号排序
-    all_factories.sort(key=lambda x: getattr(x[1], "__code__", None) and x[1].__code__.co_firstlineno or 0)
-
-    items: List[LabwareItem] = []
-
-    for func_name, factory in all_factories:
-        try:
-            resource = _probe_factory(factory)
-        except Exception as e:
-            print(f"跳过 {func_name}: {e}")
-            continue
-
-        # 确定类型
-        type_name = "plate"
-        class_name = type(resource).__name__
-        if "TipRack" in class_name:
-            type_name = "tip_rack"
-        elif "Trash" in class_name:
-            type_name = "trash"
-        elif "TubeRack" in class_name:
-            type_name = "tube_rack"
-        elif "PlateAdapter" in class_name:
-            type_name = "plate_adapter"
-
-        # material_info
-        state = getattr(resource, "_unilabos_state", {}) or {}
-        mat = state.get("Material", {})
-        mat_info = MaterialInfo(
-            uuid=mat.get("uuid", ""),
-            Code=mat.get("Code", ""),
-            Name=mat.get("Name", ""),
-            materialEnum=mat.get("materialEnum"),
-            SupplyType=mat.get("SupplyType"),
-        )
-
-        # AST 信息
-        ast_data = ast_info.get(func_name, {})
-        docstring = ast_data.get("docstring", "")
-        plate_type = ast_data.get("plate_type")
-
-        # Registry 信息
-        reg = reg_info.get(func_name, {})
-        registry_category = reg.get("registry_category", ["prcxi", _type_to_yaml_subcategory(type_name)])
-        registry_description = reg.get("registry_description", f'{mat_info.Name} (Code: {mat_info.Code})')
-
-        # 构建 item
-        item = LabwareItem(
-            id=func_name.lower().replace("prcxi_", "")[:8] or func_name[:8],
-            type=type_name,
-            function_name=func_name,
-            docstring=docstring,
-            size_x=round(_get_size(resource, "size_x"), 4),
-            size_y=round(_get_size(resource, "size_y"), 4),
-            size_z=round(_get_size(resource, "size_z"), 4),
-            model=getattr(resource, "model", None),
-            category=getattr(resource, "category", type_name),
-            plate_type=plate_type,
-            material_info=mat_info,
-            registry_category=registry_category,
-            registry_description=registry_description,
-            include_in_template_matching=func_name in template_func_names,
-            template_kind=_TEMPLATE_KINDS.get(func_name),
-        )
-
-        # 提取子项信息
-        children = getattr(resource, "children", None) or []
-        grid_data = _extract_grid_from_children(resource)
-
-        if type_name == "plate" and children:
-            if grid_data:
-                item.grid = GridInfo(**grid_data)
-            c0 = children[0]
-            well_data = _extract_well_info(c0)
-            bt = well_data.get("bottom_type")
-            if bt is not None:
-                bt = bt.name if hasattr(bt, "name") else str(bt)
-            else:
-                bt = "FLAT"
-            cst = well_data.get("cross_section_type")
-            if cst is not None:
-                cst = cst.name if hasattr(cst, "name") else str(cst)
-            else:
-                cst = "CIRCLE"
-            item.well = WellInfo(
-                size_x=well_data["size_x"],
-                size_y=well_data["size_y"],
-                size_z=well_data["size_z"],
-                max_volume=well_data.get("max_volume"),
-                bottom_type=bt,
-                cross_section_type=cst,
-                material_z_thickness=well_data.get("material_z_thickness"),
-            )
-            # volume_functions
-            vf = ast_data.get("volume_functions")
-            if vf:
-                # 需要实际获取 well 尺寸作为 volume_function 参数
-                item.volume_functions = VolumeFunctions(
-                    type="rectangle",
-                    well_length=well_data["size_x"],
-                    well_width=well_data["size_y"],
-                )
-
-        elif type_name == "tip_rack" and children:
-            if grid_data:
-                item.grid = GridInfo(**grid_data)
-            c0 = children[0]
-            tip_obj = getattr(c0, "tip", None)
-            tip_volume = 300.0
-            tip_length = 60.0
-            tip_depth = 51.0
-            tip_filter = False
-            if tip_obj:
-                tip_volume = getattr(tip_obj, "maximal_volume", 300.0)
-                tip_length = getattr(tip_obj, "total_tip_length", 60.0)
-                tip_depth = getattr(tip_obj, "fitting_depth", 51.0)
-                tip_filter = getattr(tip_obj, "has_filter", False)
-            item.tip = TipInfo(
-                spot_size_x=round(_get_size(c0, "size_x"), 4),
-                spot_size_y=round(_get_size(c0, "size_y"), 4),
-                spot_size_z=round(_get_size(c0, "size_z"), 4),
-                tip_volume=tip_volume,
-                tip_length=tip_length,
-                tip_fitting_depth=tip_depth,
-                has_filter=tip_filter,
-            )
-            # 计算 tip_above_rack_length = tip_length - (size_z - dz)
-            if grid_data:
-                _dz = grid_data.get("dz", 0.0)
-                _above = tip_length - (item.size_z - _dz)
-                item.tip.tip_above_rack_length = round(_above, 4) if _above > 0 else None
-
-        elif type_name == "tube_rack" and children:
-            if grid_data:
-                item.grid = GridInfo(**grid_data)
-            c0 = children[0]
-            item.tube = TubeInfo(
-                size_x=round(_get_size(c0, "size_x"), 4),
-                size_y=round(_get_size(c0, "size_y"), 4),
-                size_z=round(_get_size(c0, "size_z"), 4),
-                max_volume=getattr(c0, "max_volume", 1500.0) or 1500.0,
-            )
-
-        elif type_name == "plate_adapter":
-            # 提取 adapter 参数
-            ahx = getattr(resource, "adapter_hole_size_x", 127.76)
-            ahy = getattr(resource, "adapter_hole_size_y", 85.48)
-            ahz = getattr(resource, "adapter_hole_size_z", 10.0)
-            adx = getattr(resource, "dx", None)
-            ady = getattr(resource, "dy", None)
-            adz = getattr(resource, "dz", 0.0)
-            item.adapter = AdapterInfo(
-                adapter_hole_size_x=ahx,
-                adapter_hole_size_y=ahy,
-                adapter_hole_size_z=ahz,
-                dx=adx,
-                dy=ady,
-                dz=adz,
-            )
-
-        items.append(item)
-
-    return LabwareDB(items=items)
-
-
-def _type_to_yaml_subcategory(type_name: str) -> str:
-    mapping = {
-        "plate": "plates",
-        "tip_rack": "tip_racks",
-        "trash": "trash",
-        "tube_rack": "tube_racks",
-        "plate_adapter": "plate_adapters",
-    }
-    return mapping.get(type_name, type_name)
-
-
-def save_db(db: LabwareDB, path: Optional[Path] = None) -> Path:
-    """保存 LabwareDB 到 JSON 文件。"""
-    out = path or _DB_PATH
-    with open(out, "w", encoding="utf-8") as f:
-        json.dump(db.model_dump(), f, ensure_ascii=False, indent=2)
-    return out
-
-
-def load_db(path: Optional[Path] = None) -> LabwareDB:
-    """从 JSON 文件加载 LabwareDB。"""
-    src = path or _DB_PATH
-    if not src.exists():
-        return LabwareDB()
-    with open(src, "r", encoding="utf-8") as f:
-        return LabwareDB(**json.load(f))
-
-
-if __name__ == "__main__":
-    db = import_from_code()
-    out = save_db(db)
-    print(f"已导入 {len(db.items)} 个耗材 → {out}")
-    for item in db.items:
-        print(f"  [{item.type:14s}] {item.function_name}")

unilabos/labware_manager/models.py

@@ -1,126 +0,0 @@
-"""Pydantic 数据模型，描述所有 PRCXI 耗材类型的 JSON 结构。"""
-
-from __future__ import annotations
-
-import uuid as _uuid
-from typing import Any, Dict, List, Literal, Optional
-
-from pydantic import BaseModel, Field
-
-
-class MaterialInfo(BaseModel):
-    uuid: str = ""
-    Code: str = ""
-    Name: str = ""
-    materialEnum: Optional[int] = None
-    SupplyType: Optional[int] = None
-
-
-class GridInfo(BaseModel):
-    """孔位网格排列参数"""
-    num_items_x: int = 12
-    num_items_y: int = 8
-    dx: float = 0.0
-    dy: float = 0.0
-    dz: float = 0.0
-    item_dx: float = 9.0
-    item_dy: float = 9.0
-
-
-class WellInfo(BaseModel):
-    """孔参数 (Plate)"""
-    size_x: float = 8.0
-    size_y: float = 8.0
-    size_z: float = 10.0
-    max_volume: Optional[float] = None
-    bottom_type: str = "FLAT"          # V / U / FLAT
-    cross_section_type: str = "CIRCLE"  # CIRCLE / RECTANGLE
-    material_z_thickness: Optional[float] = None
-
-
-class VolumeFunctions(BaseModel):
-    """体积-高度计算函数参数 (矩形 well)"""
-    type: str = "rectangle"
-    well_length: float = 0.0
-    well_width: float = 0.0
-
-
-class TipInfo(BaseModel):
-    """枪头参数 (TipRack)"""
-    spot_size_x: float = 7.0
-    spot_size_y: float = 7.0
-    spot_size_z: float = 0.0
-    tip_volume: float = 300.0
-    tip_length: float = 60.0
-    tip_fitting_depth: float = 51.0
-    tip_above_rack_length: Optional[float] = None
-    has_filter: bool = False
-
-
-class TubeInfo(BaseModel):
-    """管参数 (TubeRack)"""
-    size_x: float = 10.6
-    size_y: float = 10.6
-    size_z: float = 40.0
-    max_volume: float = 1500.0
-
-
-class AdapterInfo(BaseModel):
-    """适配器参数 (PlateAdapter)"""
-    adapter_hole_size_x: float = 127.76
-    adapter_hole_size_y: float = 85.48
-    adapter_hole_size_z: float = 10.0
-    dx: Optional[float] = None
-    dy: Optional[float] = None
-    dz: float = 0.0
-
-
-LabwareType = Literal["plate", "tip_rack", "trash", "tube_rack", "plate_adapter"]
-
-
-class LabwareItem(BaseModel):
-    """一个耗材条目的完整 JSON 表示"""
-
-    id: str = Field(default_factory=lambda: _uuid.uuid4().hex[:8])
-    type: LabwareType = "plate"
-    function_name: str = ""
-    docstring: str = ""
-
-    # 物理尺寸
-    size_x: float = 127.0
-    size_y: float = 85.0
-    size_z: float = 20.0
-    model: Optional[str] = None
-    category: Optional[str] = None
-    plate_type: Optional[str] = None  # non-skirted / semi-skirted / skirted
-
-    # 材料信息
-    material_info: MaterialInfo = Field(default_factory=MaterialInfo)
-
-    # Registry 字段
-    registry_category: List[str] = Field(default_factory=lambda: ["prcxi", "plates"])
-    registry_description: str = ""
-
-    # Plate 特有
-    grid: Optional[GridInfo] = None
-    well: Optional[WellInfo] = None
-    volume_functions: Optional[VolumeFunctions] = None
-
-    # TipRack 特有
-    tip: Optional[TipInfo] = None
-
-    # TubeRack 特有
-    tube: Optional[TubeInfo] = None
-
-    # PlateAdapter 特有
-    adapter: Optional[AdapterInfo] = None
-
-    # 模板匹配
-    include_in_template_matching: bool = False
-    template_kind: Optional[str] = None
-
-
-class LabwareDB(BaseModel):
-    """整个 labware_db.json 的结构"""
-    version: str = "1.0"
-    items: List[LabwareItem] = Field(default_factory=list)

unilabos/labware_manager/static/form_handler.js

@@ -1,292 +0,0 @@
-/**
- * form_handler.js — 动态表单逻辑 + 实时预览
- */
-
-// 根据类型显示/隐藏对应的表单段
-function onTypeChange() {
-    const type = document.getElementById('f-type').value;
-    const sections = {
-        grid: ['plate', 'tip_rack', 'tube_rack'],
-        well: ['plate'],
-        tip: ['tip_rack'],
-        tube: ['tube_rack'],
-        adapter: ['plate_adapter'],
-    };
-
-    for (const [sec, types] of Object.entries(sections)) {
-        const el = document.getElementById('section-' + sec);
-        if (el) el.style.display = types.includes(type) ? 'block' : 'none';
-    }
-
-    // plate_type 行只对 plate 显示
-    const ptRow = document.getElementById('row-plate_type');
-    if (ptRow) ptRow.style.display = type === 'plate' ? 'block' : 'none';
-
-    updatePreview();
-}
-
-// 从表单收集数据
-function collectFormData() {
-    const g = id => {
-        const el = document.getElementById(id);
-        if (!el) return null;
-        if (el.type === 'checkbox') return el.checked;
-        if (el.type === 'number') return el.value === '' ? null : parseFloat(el.value);
-        return el.value || null;
-    };
-
-    const type = g('f-type');
-
-    const data = {
-        type: type,
-        function_name: g('f-function_name') || 'PRCXI_new',
-        model: g('f-model'),
-        docstring: g('f-docstring') || '',
-        plate_type: type === 'plate' ? g('f-plate_type') : null,
-        size_x: g('f-size_x') || 127,
-        size_y: g('f-size_y') || 85,
-        size_z: g('f-size_z') || 20,
-        material_info: {
-            uuid: g('f-mi_uuid') || '',
-            Code: g('f-mi_code') || '',
-            Name: g('f-mi_name') || '',
-            materialEnum: g('f-mi_menum'),
-            SupplyType: g('f-mi_stype'),
-        },
-        registry_category: (g('f-reg_cat') || 'prcxi,plates').split(',').map(s => s.trim()),
-        registry_description: g('f-reg_desc') || '',
-        include_in_template_matching: g('f-in_tpl') || false,
-        template_kind: g('f-tpl_kind') || null,
-        grid: null,
-        well: null,
-        tip: null,
-        tube: null,
-        adapter: null,
-        volume_functions: null,
-    };
-
-    // Grid
-    if (['plate', 'tip_rack', 'tube_rack'].includes(type)) {
-        data.grid = {
-            num_items_x: g('f-grid_nx') || 12,
-            num_items_y: g('f-grid_ny') || 8,
-            dx: g('f-grid_dx') || 0,
-            dy: g('f-grid_dy') || 0,
-            dz: g('f-grid_dz') || 0,
-            item_dx: g('f-grid_idx') || 9,
-            item_dy: g('f-grid_idy') || 9,
-        };
-    }
-
-    // Well
-    if (type === 'plate') {
-        data.well = {
-            size_x: g('f-well_sx') || 8,
-            size_y: g('f-well_sy') || 8,
-            size_z: g('f-well_sz') || 10,
-            max_volume: g('f-well_vol'),
-            material_z_thickness: g('f-well_mzt'),
-            bottom_type: g('f-well_bt') || 'FLAT',
-            cross_section_type: g('f-well_cs') || 'CIRCLE',
-        };
-        if (g('f-has_vf')) {
-            data.volume_functions = {
-                type: 'rectangle',
-                well_length: data.well.size_x,
-                well_width: data.well.size_y,
-            };
-        }
-    }
-
-    // Tip
-    if (type === 'tip_rack') {
-        data.tip = {
-            spot_size_x: g('f-tip_sx') || 7,
-            spot_size_y: g('f-tip_sy') || 7,
-            spot_size_z: g('f-tip_sz') || 0,
-            tip_volume: g('f-tip_vol') || 300,
-            tip_length: g('f-tip_len') || 60,
-            tip_fitting_depth: g('f-tip_dep') || 51,
-            tip_above_rack_length: g('f-tip_above'),
-            has_filter: g('f-tip_filter') || false,
-        };
-    }
-
-    // Tube
-    if (type === 'tube_rack') {
-        data.tube = {
-            size_x: g('f-tube_sx') || 10.6,
-            size_y: g('f-tube_sy') || 10.6,
-            size_z: g('f-tube_sz') || 40,
-            max_volume: g('f-tube_vol') || 1500,
-        };
-    }
-
-    // Adapter
-    if (type === 'plate_adapter') {
-        data.adapter = {
-            adapter_hole_size_x: g('f-adp_hsx') || 127.76,
-            adapter_hole_size_y: g('f-adp_hsy') || 85.48,
-            adapter_hole_size_z: g('f-adp_hsz') || 10,
-            dx: g('f-adp_dx'),
-            dy: g('f-adp_dy'),
-            dz: g('f-adp_dz') || 0,
-        };
-    }
-
-    return data;
-}
-
-// 实时预览 (debounce)
-let _previewTimer = null;
-function updatePreview() {
-    if (_previewTimer) clearTimeout(_previewTimer);
-    _previewTimer = setTimeout(() => {
-        const data = collectFormData();
-        const topEl = document.getElementById('svg-topdown');
-        const sideEl = document.getElementById('svg-side');
-        if (topEl) renderTopDown(topEl, data);
-        if (sideEl) renderSideProfile(sideEl, data);
-    }, 200);
-}
-
-// 给所有表单元素绑定 input 事件
-document.addEventListener('DOMContentLoaded', () => {
-    const form = document.getElementById('labware-form');
-    if (!form) return;
-    form.addEventListener('input', updatePreview);
-    form.addEventListener('change', updatePreview);
-
-    // tip_above_rack_length 与 dz 互算
-    // 公式: tip_length = tip_above_rack_length + size_z - dz
-    // 规则: 填 tip_above → 自动算 dz；填 dz → 自动算 tip_above
-    //       改 size_z / tip_length → 优先重算 tip_above（若有值），否则算 dz
-
-    function _getVal(id) {
-        const el = document.getElementById(id);
-        return (el && el.value !== '') ? parseFloat(el.value) : null;
-    }
-    function _setVal(id, v) {
-        const el = document.getElementById(id);
-        if (el) el.value = Math.round(v * 1000) / 1000;
-    }
-
-    function autoCalcTipAbove(changedId) {
-        const typeEl = document.getElementById('f-type');
-        if (!typeEl || typeEl.value !== 'tip_rack') return;
-
-        const tipLen = _getVal('f-tip_len');
-        const sizeZ  = _getVal('f-size_z');
-        const dz     = _getVal('f-grid_dz');
-        const above  = _getVal('f-tip_above');
-
-        // 需要 tip_length 和 size_z 才能计算
-        if (tipLen == null || sizeZ == null) return;
-
-        if (changedId === 'f-tip_above') {
-            // 用户填了 tip_above → 算 dz
-            if (above != null) _setVal('f-grid_dz', above + sizeZ - tipLen);
-        } else if (changedId === 'f-grid_dz') {
-            // 用户填了 dz → 算 tip_above
-            if (dz != null) _setVal('f-tip_above', tipLen - sizeZ + dz);
-        } else {
-            // size_z 或 tip_length 变了 → 优先重算 tip_above（若已有值或 dz 已有值）
-            if (dz != null) {
-                _setVal('f-tip_above', tipLen - sizeZ + dz);
-            } else if (above != null) {
-                _setVal('f-grid_dz', above + sizeZ - tipLen);
-            }
-        }
-    }
-
-    // 绑定 input 事件
-    for (const id of ['f-tip_len', 'f-size_z', 'f-grid_dz', 'f-tip_above']) {
-        const el = document.getElementById(id);
-        if (el) el.addEventListener('input', () => autoCalcTipAbove(id));
-    }
-
-    // 编辑已有 tip_rack 条目时自动补算 tip_above_rack_length
-    const typeEl = document.getElementById('f-type');
-    if (typeEl && typeEl.value === 'tip_rack') {
-        autoCalcTipAbove('f-grid_dz');
-    }
-});
-
-// 自动居中：根据板尺寸和孔阵列参数计算 dx/dy
-function autoCenter() {
-    const g = id => { const el = document.getElementById(id); return el && el.value !== '' ? parseFloat(el.value) : 0; };
-
-    const sizeX = g('f-size_x') || 127;
-    const sizeY = g('f-size_y') || 85;
-    const nx = g('f-grid_nx') || 1;
-    const ny = g('f-grid_ny') || 1;
-    const itemDx = g('f-grid_idx') || 9;
-    const itemDy = g('f-grid_idy') || 9;
-
-    // 根据当前耗材类型确定子元素尺寸
-    const type = document.getElementById('f-type').value;
-    let childSx = 0, childSy = 0;
-    if (type === 'plate') {
-        childSx = g('f-well_sx') || 8;
-        childSy = g('f-well_sy') || 8;
-    } else if (type === 'tip_rack') {
-        childSx = g('f-tip_sx') || 7;
-        childSy = g('f-tip_sy') || 7;
-    } else if (type === 'tube_rack') {
-        childSx = g('f-tube_sx') || 10.6;
-        childSy = g('f-tube_sy') || 10.6;
-    }
-
-    // dx = (板宽 - 孔阵列总占宽) / 2
-    const dx = (sizeX - (nx - 1) * itemDx - childSx) / 2;
-    const dy = (sizeY - (ny - 1) * itemDy - childSy) / 2;
-
-    const elDx = document.getElementById('f-grid_dx');
-    const elDy = document.getElementById('f-grid_dy');
-    if (elDx) elDx.value = Math.round(dx * 100) / 100;
-    if (elDy) elDy.value = Math.round(dy * 100) / 100;
-
-    updatePreview();
-}
-
-// 保存
-function showMsg(text, ok) {
-    const el = document.getElementById('status-msg');
-    if (!el) return;
-    el.textContent = text;
-    el.className = 'status-msg ' + (ok ? 'msg-ok' : 'msg-err');
-    el.style.display = 'block';
-    setTimeout(() => el.style.display = 'none', 4000);
-}
-
-async function saveForm() {
-    const data = collectFormData();
-
-    let url, method;
-    if (typeof IS_NEW !== 'undefined' && IS_NEW) {
-        url = '/api/labware';
-        method = 'POST';
-    } else {
-        url = '/api/labware/' + (typeof ITEM_ID !== 'undefined' ? ITEM_ID : '');
-        method = 'PUT';
-    }
-
-    try {
-        const r = await fetch(url, {
-            method: method,
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(data),
-        });
-        const d = await r.json();
-        if (d.status === 'ok') {
-            showMsg('保存成功', true);
-            if (IS_NEW) {
-                setTimeout(() => location.href = '/labware/' + data.function_name, 500);
-            }
-        } else {
-            showMsg('保存失败: ' + JSON.stringify(d), false);
-        }
-    } catch (e) {
-        showMsg('请求错误: ' + e.message, false);
-    }
-}

unilabos/labware_manager/static/labware_viz.js

@@ -1,450 +0,0 @@
-/**
- * labware_viz.js — PRCXI 耗材 SVG 2D 可视化渲染引擎
- *
- * renderTopDown(container, itemData)  — 俯视图
- * renderSideProfile(container, itemData) — 侧面截面图
- */
-
-const TYPE_COLORS = {
-    plate: '#3b82f6',
-    tip_rack: '#10b981',
-    tube_rack: '#f59e0b',
-    trash: '#ef4444',
-    plate_adapter: '#8b5cf6',
-};
-
-function _svgNS() { return 'http://www.w3.org/2000/svg'; }
-
-function _makeSVG(w, h) {
-    const svg = document.createElementNS(_svgNS(), 'svg');
-    svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
-    svg.setAttribute('width', '100%');
-    svg.setAttribute('preserveAspectRatio', 'xMidYMid meet');
-    svg.style.background = '#fff';
-    return svg;
-}
-
-function _rect(svg, x, y, w, h, fill, stroke, rx) {
-    const r = document.createElementNS(_svgNS(), 'rect');
-    r.setAttribute('x', x); r.setAttribute('y', y);
-    r.setAttribute('width', w); r.setAttribute('height', h);
-    r.setAttribute('fill', fill || 'none');
-    r.setAttribute('stroke', stroke || '#333');
-    r.setAttribute('stroke-width', '0.5');
-    if (rx) r.setAttribute('rx', rx);
-    svg.appendChild(r);
-    return r;
-}
-
-function _circle(svg, cx, cy, r, fill, stroke) {
-    const c = document.createElementNS(_svgNS(), 'circle');
-    c.setAttribute('cx', cx); c.setAttribute('cy', cy);
-    c.setAttribute('r', r);
-    c.setAttribute('fill', fill || 'none');
-    c.setAttribute('stroke', stroke || '#333');
-    c.setAttribute('stroke-width', '0.4');
-    svg.appendChild(c);
-    return c;
-}
-
-function _text(svg, x, y, txt, size, anchor, fill) {
-    const t = document.createElementNS(_svgNS(), 'text');
-    t.setAttribute('x', x); t.setAttribute('y', y);
-    t.setAttribute('font-size', size || '3');
-    t.setAttribute('text-anchor', anchor || 'middle');
-    t.setAttribute('fill', fill || '#666');
-    t.setAttribute('font-family', 'sans-serif');
-    t.textContent = txt;
-    svg.appendChild(t);
-    return t;
-}
-
-function _line(svg, x1, y1, x2, y2, stroke, dash) {
-    const l = document.createElementNS(_svgNS(), 'line');
-    l.setAttribute('x1', x1); l.setAttribute('y1', y1);
-    l.setAttribute('x2', x2); l.setAttribute('y2', y2);
-    l.setAttribute('stroke', stroke || '#999');
-    l.setAttribute('stroke-width', '0.3');
-    if (dash) l.setAttribute('stroke-dasharray', dash);
-    svg.appendChild(l);
-    return l;
-}
-
-function _title(el, txt) {
-    const t = document.createElementNS(_svgNS(), 'title');
-    t.textContent = txt;
-    el.appendChild(t);
-}
-
-// ==================== 俯视图 ====================
-function renderTopDown(container, data) {
-    container.innerHTML = '';
-    if (!data) return;
-
-    const pad = 18;
-    const sx = data.size_x || 127;
-    const sy = data.size_y || 85;
-    const w = sx + pad * 2;
-    const h = sy + pad * 2;
-    const svg = _makeSVG(w, h);
-
-    const color = TYPE_COLORS[data.type] || '#3b82f6';
-    const lightColor = color + '22';
-
-    // 板子外轮廓
-    _rect(svg, pad, pad, sx, sy, lightColor, color, 3);
-
-    // 尺寸标注
-    _text(svg, pad + sx / 2, pad - 4, `${sx} mm`, '3.5', 'middle', '#333');
-    // Y 尺寸 (竖直)
-    const yt = document.createElementNS(_svgNS(), 'text');
-    yt.setAttribute('x', pad - 5);
-    yt.setAttribute('y', pad + sy / 2);
-    yt.setAttribute('font-size', '3.5');
-    yt.setAttribute('text-anchor', 'middle');
-    yt.setAttribute('fill', '#333');
-    yt.setAttribute('font-family', 'sans-serif');
-    yt.setAttribute('transform', `rotate(-90, ${pad - 5}, ${pad + sy / 2})`);
-    yt.textContent = `${sy} mm`;
-    svg.appendChild(yt);
-
-    const grid = data.grid;
-    const well = data.well;
-    const tip = data.tip;
-    const tube = data.tube;
-
-    if (grid && (well || tip || tube)) {
-        const nx = grid.num_items_x || 1;
-        const ny = grid.num_items_y || 1;
-        const dx = grid.dx || 0;
-        const dy = grid.dy || 0;
-        const idx = grid.item_dx || 9;
-        const idy = grid.item_dy || 9;
-
-        const child = well || tip || tube;
-        const csx = child.size_x || child.spot_size_x || 8;
-        const csy = child.size_y || child.spot_size_y || 8;
-
-        const isCircle = well ? (well.cross_section_type === 'CIRCLE') : (!!tip);
-
-        // 行列标签
-        for (let col = 0; col < nx; col++) {
-            const cx = pad + dx + csx / 2 + col * idx;
-            _text(svg, cx, pad + sy + 5, String(col + 1), '2.5', 'middle', '#999');
-        }
-        const rowLabels = 'ABCDEFGHIJKLMNOP';
-        for (let row = 0; row < ny; row++) {
-            const cy = pad + dy + csy / 2 + row * idy;
-            _text(svg, pad - 4, cy + 1, rowLabels[row] || String(row), '2.5', 'middle', '#999');
-        }
-
-        // 绘制孔位
-        for (let col = 0; col < nx; col++) {
-            for (let row = 0; row < ny; row++) {
-                const cx = pad + dx + csx / 2 + col * idx;
-                const cy = pad + dy + csy / 2 + row * idy;
-
-                let el;
-                if (isCircle) {
-                    const r = Math.min(csx, csy) / 2;
-                    el = _circle(svg, cx, cy, r, '#fff', color);
-                } else {
-                    el = _rect(svg, cx - csx / 2, cy - csy / 2, csx, csy, '#fff', color);
-                }
-
-                const label = (rowLabels[row] || '') + String(col + 1);
-                _title(el, `${label}: ${csx}x${csy} mm`);
-
-                // hover 效果
-                el.style.cursor = 'pointer';
-                el.addEventListener('mouseenter', () => el.setAttribute('fill', color + '44'));
-                el.addEventListener('mouseleave', () => el.setAttribute('fill', '#fff'));
-            }
-        }
-
-        // dx / dy 标注（板边到首个子元素左上角）
-        const dimColor = '#e67e22';
-        const firstLeft = pad + dx;        // 首列子元素左边 X
-        const firstTop  = pad + dy;        // 首行子元素上边 Y
-        if (dx > 0.1) {
-            // dx: 板左边 → 首列子元素左边，画在第一行子元素中心高度
-            const annY = firstTop + csy / 2;
-            _line(svg, pad, annY, firstLeft, annY, dimColor, '1,1');
-            _line(svg, pad, annY - 2, pad, annY + 2, dimColor);
-            _line(svg, firstLeft, annY - 2, firstLeft, annY + 2, dimColor);
-            _text(svg, pad + dx / 2, annY - 2, `dx=${dx}`, '2.5', 'middle', dimColor);
-        }
-        if (dy > 0.1) {
-            // dy: 板上边 → 首行子元素上边，画在第一列子元素中心宽度
-            const annX = firstLeft + csx / 2;
-            _line(svg, annX, pad, annX, firstTop, dimColor, '1,1');
-            _line(svg, annX - 2, pad, annX + 2, pad, dimColor);
-            _line(svg, annX - 2, firstTop, annX + 2, firstTop, dimColor);
-            _text(svg, annX + 4, pad + dy / 2 + 1, `dy=${dy}`, '2.5', 'start', dimColor);
-        }
-    } else if (data.type === 'plate_adapter' && data.adapter) {
-        // 绘制适配器凹槽
-        const adp = data.adapter;
-        const ahx = adp.adapter_hole_size_x || 127;
-        const ahy = adp.adapter_hole_size_y || 85;
-        const adx = adp.dx != null ? adp.dx : (sx - ahx) / 2;
-        const ady = adp.dy != null ? adp.dy : (sy - ahy) / 2;
-        _rect(svg, pad + adx, pad + ady, ahx, ahy, '#f0f0ff', '#8b5cf6', 2);
-        _text(svg, pad + adx + ahx / 2, pad + ady + ahy / 2, `${ahx}x${ahy}`, '4', 'middle', '#8b5cf6');
-    } else if (data.type === 'trash') {
-        // 简单标记
-        _text(svg, pad + sx / 2, pad + sy / 2, 'TRASH', '8', 'middle', '#ef4444');
-    }
-
-    container.appendChild(svg);
-    _enableZoomPan(svg, `0 0 ${w} ${h}`);
-}
-
-// ==================== 侧面截面图 ====================
-function renderSideProfile(container, data) {
-    container.innerHTML = '';
-    if (!data) return;
-
-    const pad = 20;
-    const sx = data.size_x || 127;
-    const sz = data.size_z || 20;
-
-    // 按比例缩放，侧面以 X-Z 面
-    const scaleH = Math.max(1, sz / 60); // 让较矮的板子不会太小
-
-    // 计算枪头露出高度（仅 tip_rack）
-    const tip = data.tip;
-    const grid = data.grid;
-    let tipAbove = 0;
-    if (data.type === 'tip_rack' && tip) {
-        if (tip.tip_above_rack_length != null && tip.tip_above_rack_length > 0) {
-            tipAbove = tip.tip_above_rack_length;
-        } else if (tip.tip_length && grid) {
-            const dz = grid.dz || 0;
-            const calc = tip.tip_length - (sz - dz);
-            if (calc > 0) tipAbove = calc;
-        }
-    }
-
-    const drawW = sx;
-    const drawH = sz;
-    const w = drawW + pad * 2 + 30; // 额外空间给标注
-    const h = drawH + tipAbove + pad * 2 + 10;
-    const svg = _makeSVG(w, h);
-
-    const color = TYPE_COLORS[data.type] || '#3b82f6';
-    const baseY = pad + tipAbove + drawH; // 底部 Y
-    const rackTopY = pad + tipAbove; // rack 顶部 Y
-
-    // 板壳矩形
-    _rect(svg, pad, rackTopY, drawW, drawH, color + '15', color);
-
-    // 尺寸标注
-    // X 方向
-    _line(svg, pad, baseY + 5, pad + drawW, baseY + 5, '#333');
-    _text(svg, pad + drawW / 2, baseY + 12, `${sx} mm`, '3.5', 'middle', '#333');
-
-    // Z 方向
-    _line(svg, pad + drawW + 5, rackTopY, pad + drawW + 5, baseY, '#333');
-    const zt = document.createElementNS(_svgNS(), 'text');
-    zt.setAttribute('x', pad + drawW + 12);
-    zt.setAttribute('y', rackTopY + drawH / 2);
-    zt.setAttribute('font-size', '3.5');
-    zt.setAttribute('text-anchor', 'middle');
-    zt.setAttribute('fill', '#333');
-    zt.setAttribute('font-family', 'sans-serif');
-    zt.setAttribute('transform', `rotate(-90, ${pad + drawW + 12}, ${rackTopY + drawH / 2})`);
-    zt.textContent = `${sz} mm`;
-    svg.appendChild(zt);
-
-    const well = data.well;
-    const tube = data.tube;
-
-    if (grid && (well || tip || tube)) {
-        const dx = grid.dx || 0;
-        const dz = grid.dz || 0;
-        const idx = grid.item_dx || 9;
-        const nx = Math.min(grid.num_items_x || 1, 24); // 最多画24列
-        const dimColor = '#e67e22';
-
-        const child = well || tube;
-        const childTip = tip;
-
-        if (child) {
-            const csx = child.size_x || 8;
-            const csz = child.size_z || 10;
-            const bt = well ? (well.bottom_type || 'FLAT') : 'FLAT';
-
-            // 画几个代表性的孔截面
-            const nDraw = Math.min(nx, 12);
-            for (let i = 0; i < nDraw; i++) {
-                const cx = pad + dx + csx / 2 + i * idx;
-                const topZ = baseY - dz - csz;
-                const botZ = baseY - dz;
-
-                // 孔壁
-                _rect(svg, cx - csx / 2, topZ, csx, csz, '#e0e8ff', color, 0.5);
-
-                // 底部形状
-                if (bt === 'V') {
-                    // V 底 三角
-                    const triH = Math.min(csx / 2, csz * 0.3);
-                    const p = document.createElementNS(_svgNS(), 'polygon');
-                    p.setAttribute('points',
-                        `${cx - csx / 2},${botZ - triH} ${cx},${botZ} ${cx + csx / 2},${botZ - triH}`);
-                    p.setAttribute('fill', color + '33');
-                    p.setAttribute('stroke', color);
-                    p.setAttribute('stroke-width', '0.3');
-                    svg.appendChild(p);
-                } else if (bt === 'U') {
-                    // U 底 圆弧
-                    const arcR = csx / 2;
-                    const p = document.createElementNS(_svgNS(), 'path');
-                    p.setAttribute('d', `M ${cx - csx / 2} ${botZ - arcR} A ${arcR} ${arcR} 0 0 0 ${cx + csx / 2} ${botZ - arcR}`);
-                    p.setAttribute('fill', color + '33');
-                    p.setAttribute('stroke', color);
-                    p.setAttribute('stroke-width', '0.3');
-                    svg.appendChild(p);
-                }
-            }
-
-            // dz 标注
-            if (dz > 0) {
-                const lx = pad + dx + 0.5 * idx * nDraw + csx / 2 + 5;
-                _line(svg, lx, baseY, lx, baseY - dz, dimColor, '1,1');
-                _line(svg, lx - 2, baseY, lx + 2, baseY, dimColor);
-                _line(svg, lx - 2, baseY - dz, lx + 2, baseY - dz, dimColor);
-                _text(svg, lx + 4, baseY - dz / 2 + 1, `dz=${dz}`, '2.5', 'start', dimColor);
-            }
-            // dx 标注
-            if (dx > 0.1) {
-                const annY = rackTopY + 4;
-                _line(svg, pad, annY, pad + dx, annY, dimColor, '1,1');
-                _line(svg, pad, annY - 2, pad, annY + 2, dimColor);
-                _line(svg, pad + dx, annY - 2, pad + dx, annY + 2, dimColor);
-                _text(svg, pad + dx / 2, annY - 2, `dx=${dx}`, '2.5', 'middle', dimColor);
-            }
-        }
-
-        if (childTip) {
-            // 枪头截面
-            const tipLen = childTip.tip_length || 50;
-            const nDraw = Math.min(nx, 12);
-            for (let i = 0; i < nDraw; i++) {
-                const cx = pad + dx + 3.5 + i * idx;
-                // 枪头顶部 = rack顶部 - 露出长度
-                const tipTopZ = rackTopY - tipAbove;
-                const drawLen = Math.min(tipLen, sz - dz + tipAbove);
-
-                // 枪头轮廓 (梯形)
-                const topW = 4;
-                const botW = 1.5;
-                const p = document.createElementNS(_svgNS(), 'polygon');
-                p.setAttribute('points',
-                    `${cx - topW / 2},${tipTopZ} ${cx + topW / 2},${tipTopZ} ${cx + botW / 2},${tipTopZ + drawLen} ${cx - botW / 2},${tipTopZ + drawLen}`);
-                p.setAttribute('fill', '#10b98133');
-                p.setAttribute('stroke', '#10b981');
-                p.setAttribute('stroke-width', '0.3');
-                svg.appendChild(p);
-            }
-
-            // dz 标注
-            if (dz > 0) {
-                const lx = pad + dx + nDraw * idx + 5;
-                _line(svg, lx, baseY, lx, baseY - dz, dimColor, '1,1');
-                _line(svg, lx - 2, baseY, lx + 2, baseY, dimColor);
-                _line(svg, lx - 2, baseY - dz, lx + 2, baseY - dz, dimColor);
-                _text(svg, lx + 4, baseY - dz / 2 + 1, `dz=${dz}`, '2.5', 'start', dimColor);
-            }
-            // dx 标注
-            if (dx > 0.1) {
-                const annY = rackTopY + 4;
-                _line(svg, pad, annY, pad + dx, annY, dimColor, '1,1');
-                _line(svg, pad, annY - 2, pad, annY + 2, dimColor);
-                _line(svg, pad + dx, annY - 2, pad + dx, annY + 2, dimColor);
-                _text(svg, pad + dx / 2, annY - 2, `dx=${dx}`, '2.5', 'middle', dimColor);
-            }
-
-            // 露出长度标注线
-            if (tipAbove > 0) {
-                const annotX = pad + dx + nDraw * idx + 8;
-                // rack 顶部水平参考线
-                _line(svg, annotX - 3, rackTopY, annotX + 3, rackTopY, '#10b981');
-                // 枪头顶部水平参考线
-                _line(svg, annotX - 3, rackTopY - tipAbove, annotX + 3, rackTopY - tipAbove, '#10b981');
-                // 竖直标注线
-                _line(svg, annotX, rackTopY - tipAbove, annotX, rackTopY, '#10b981', '1,1');
-                _text(svg, annotX + 2, rackTopY - tipAbove / 2 + 1, `露出=${Math.round(tipAbove * 100) / 100}mm`, '2.5', 'start', '#10b981');
-            }
-        }
-    } else if (data.type === 'plate_adapter' && data.adapter) {
-        const adp = data.adapter;
-        const ahz = adp.adapter_hole_size_z || 10;
-        const adz = adp.dz || 0;
-        const adx_val = adp.dx != null ? adp.dx : (sx - (adp.adapter_hole_size_x || 127)) / 2;
-        const ahx = adp.adapter_hole_size_x || 127;
-
-        // 凹槽截面
-        _rect(svg, pad + adx_val, rackTopY + adz, ahx, ahz, '#ede9fe', '#8b5cf6');
-        _text(svg, pad + adx_val + ahx / 2, rackTopY + adz + ahz / 2 + 1, `hole: ${ahz}mm deep`, '3', 'middle', '#8b5cf6');
-    } else if (data.type === 'trash') {
-        _text(svg, pad + drawW / 2, rackTopY + drawH / 2, 'TRASH', '8', 'middle', '#ef4444');
-    }
-
-    container.appendChild(svg);
-    _enableZoomPan(svg, `0 0 ${w} ${h}`);
-}
-
-// ==================== 缩放 & 平移 ====================
-function _enableZoomPan(svgEl, origViewBox) {
-    const parts = origViewBox.split(' ').map(Number);
-    let vx = parts[0], vy = parts[1], vw = parts[2], vh = parts[3];
-    const origVx = vx, origVy = vy, origW = vw, origH = vh;
-    const MIN_SCALE = 0.5, MAX_SCALE = 5;
-
-    function applyViewBox() {
-        svgEl.setAttribute('viewBox', `${vx} ${vy} ${vw} ${vh}`);
-    }
-
-    function resetView() {
-        vx = origVx; vy = origVy; vw = origW; vh = origH;
-        applyViewBox();
-    }
-
-    // 将 resetView 挂到 svg 元素上，方便外部调用
-    svgEl._resetView = resetView;
-
-    svgEl.addEventListener('wheel', function (e) {
-        e.preventDefault();
-        if (e.ctrlKey) {
-            // pinch / ctrl+scroll → 缩放
-            const factor = e.deltaY > 0 ? 1.08 : 1 / 1.08;
-            const newW = vw * factor;
-            const newH = vh * factor;
-            // 限制缩放范围
-            if (newW < origW / MAX_SCALE || newW > origW * (1 / MIN_SCALE)) return;
-            // 以鼠标位置为缩放中心
-            const rect = svgEl.getBoundingClientRect();
-            const mx = (e.clientX - rect.left) / rect.width;
-            const my = (e.clientY - rect.top) / rect.height;
-            vx += (vw - newW) * mx;
-            vy += (vh - newH) * my;
-            vw = newW;
-            vh = newH;
-        } else {
-            // 普通滚轮 → 平移
-            const panSpeed = vw * 0.002;
-            vx += e.deltaX * panSpeed;
-            vy += e.deltaY * panSpeed;
-        }
-        applyViewBox();
-    }, { passive: false });
-}
-
-// 回中按钮：重置指定容器内 SVG 的 viewBox
-function resetSvgView(containerId) {
-    const container = document.getElementById(containerId);
-    if (!container) return;
-    const svg = container.querySelector('svg');
-    if (svg && svg._resetView) svg._resetView();
-}

unilabos/labware_manager/static/style.css

@@ -1,295 +0,0 @@
-/* PRCXI 耗材管理 - 全局样式 */
-
-:root {
-    --c-primary: #3b82f6;
-    --c-primary-dark: #2563eb;
-    --c-danger: #ef4444;
-    --c-warning: #f59e0b;
-    --c-success: #10b981;
-    --c-gray-50: #f9fafb;
-    --c-gray-100: #f3f4f6;
-    --c-gray-200: #e5e7eb;
-    --c-gray-300: #d1d5db;
-    --c-gray-500: #6b7280;
-    --c-gray-700: #374151;
-    --c-gray-900: #111827;
-    --radius: 8px;
-    --shadow: 0 1px 3px rgba(0,0,0,0.1);
-}
-
-* { box-sizing: border-box; margin: 0; padding: 0; }
-
-body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-    background: var(--c-gray-50);
-    color: var(--c-gray-900);
-    line-height: 1.5;
-}
-
-/* 顶部导航 */
-.topbar {
-    background: #fff;
-    border-bottom: 1px solid var(--c-gray-200);
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 0 24px;
-    height: 56px;
-    position: sticky;
-    top: 0;
-    z-index: 100;
-}
-.topbar .logo {
-    font-weight: 700;
-    font-size: 1.1rem;
-    color: var(--c-gray-900);
-    text-decoration: none;
-}
-
-/* 容器 */
-.container {
-    max-width: 1400px;
-    margin: 0 auto;
-    padding: 24px;
-}
-
-/* 页头 */
-.page-header {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    margin-bottom: 24px;
-    flex-wrap: wrap;
-    gap: 12px;
-}
-.page-header h1 { font-size: 1.5rem; }
-.header-actions { display: flex; gap: 8px; flex-wrap: wrap; }
-
-/* 按钮 */
-.btn {
-    display: inline-flex;
-    align-items: center;
-    padding: 8px 16px;
-    border-radius: 6px;
-    font-size: 0.875rem;
-    font-weight: 500;
-    cursor: pointer;
-    border: 1px solid transparent;
-    text-decoration: none;
-    transition: all 0.15s;
-    white-space: nowrap;
-}
-.btn-sm { padding: 4px 10px; font-size: 0.8rem; }
-.btn-primary { background: var(--c-primary); color: #fff; }
-.btn-primary:hover { background: var(--c-primary-dark); }
-.btn-outline { background: #fff; color: var(--c-gray-700); border-color: var(--c-gray-300); }
-.btn-outline:hover { background: var(--c-gray-100); }
-.btn-danger { background: var(--c-danger); color: #fff; }
-.btn-danger:hover { background: #dc2626; }
-.btn-warning { background: var(--c-warning); color: #fff; }
-.btn-warning:hover { background: #d97706; }
-
-/* 徽章 */
-.badge {
-    background: var(--c-gray-200);
-    color: var(--c-gray-700);
-    font-size: 0.8rem;
-    padding: 2px 8px;
-    border-radius: 12px;
-    font-weight: 500;
-    margin-left: 4px;
-}
-
-/* 状态消息 */
-.status-msg {
-    padding: 12px 16px;
-    border-radius: var(--radius);
-    margin-bottom: 16px;
-    font-size: 0.9rem;
-}
-.msg-ok { background: #d1fae5; color: #065f46; }
-.msg-err { background: #fee2e2; color: #991b1b; }
-
-/* 类型分段 */
-.type-section { margin-bottom: 32px; }
-.type-section h2 {
-    font-size: 1.1rem;
-    margin-bottom: 12px;
-    display: flex;
-    align-items: center;
-    gap: 8px;
-}
-.type-dot {
-    width: 12px;
-    height: 12px;
-    border-radius: 50%;
-    display: inline-block;
-}
-
-/* 卡片网格 */
-.card-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-    gap: 12px;
-}
-
-/* 耗材卡片 */
-.labware-card {
-    background: #fff;
-    border: 1px solid var(--c-gray-200);
-    border-radius: var(--radius);
-    padding: 16px;
-    cursor: pointer;
-    transition: box-shadow 0.2s, border-color 0.2s;
-}
-.labware-card:hover {
-    border-color: var(--c-primary);
-    box-shadow: 0 4px 12px rgba(59,130,246,0.15);
-}
-.card-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    margin-bottom: 8px;
-}
-.card-title {
-    font-weight: 600;
-    font-size: 0.9rem;
-    color: var(--c-gray-900);
-    word-break: break-all;
-}
-.card-body { font-size: 0.85rem; color: var(--c-gray-500); }
-.card-info { margin-bottom: 2px; }
-.card-info .label { color: var(--c-gray-700); font-weight: 500; }
-.card-footer {
-    margin-top: 12px;
-    display: flex;
-    gap: 8px;
-    border-top: 1px solid var(--c-gray-100);
-    padding-top: 10px;
-}
-
-/* 标签 */
-.tag {
-    font-size: 0.7rem;
-    padding: 2px 6px;
-    border-radius: 4px;
-    font-weight: 600;
-    text-transform: uppercase;
-}
-.tag-tpl { background: #dbeafe; color: #1e40af; }
-.tag-plate { background: #dbeafe; color: #1e40af; }
-.tag-tip_rack { background: #d1fae5; color: #065f46; }
-.tag-trash { background: #fee2e2; color: #991b1b; }
-.tag-tube_rack { background: #fef3c7; color: #92400e; }
-.tag-plate_adapter { background: #ede9fe; color: #5b21b6; }
-
-/* 详情页布局 */
-.detail-layout {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 24px;
-}
-@media (max-width: 900px) {
-    .detail-layout { grid-template-columns: 1fr; }
-}
-.detail-info, .detail-viz { display: flex; flex-direction: column; gap: 16px; }
-
-.info-card, .viz-card {
-    background: #fff;
-    border: 1px solid var(--c-gray-200);
-    border-radius: var(--radius);
-    padding: 16px;
-}
-.info-card h3, .viz-card h3 {
-    font-size: 0.95rem;
-    margin-bottom: 12px;
-    color: var(--c-gray-700);
-    border-bottom: 1px solid var(--c-gray-100);
-    padding-bottom: 8px;
-}
-
-.info-table { width: 100%; font-size: 0.85rem; }
-.info-table td { padding: 4px 8px; border-bottom: 1px solid var(--c-gray-100); }
-.info-table .label { color: var(--c-gray-500); font-weight: 500; width: 140px; }
-.info-table code { background: var(--c-gray-100); padding: 1px 4px; border-radius: 3px; font-size: 0.8rem; }
-.info-table code.small { font-size: 0.7rem; }
-
-/* SVG 容器 */
-#svg-topdown, #svg-side {
-    width: 100%;
-    min-height: 200px;
-    overflow: hidden;
-}
-#svg-topdown svg, #svg-side svg {
-    display: block;
-    width: 100%;
-    height: auto;
-    touch-action: none;
-}
-
-/* 编辑页布局 */
-.edit-layout {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 24px;
-}
-@media (max-width: 900px) {
-    .edit-layout { grid-template-columns: 1fr; }
-}
-.edit-form { display: flex; flex-direction: column; gap: 16px; }
-.edit-preview { display: flex; flex-direction: column; gap: 16px; position: sticky; top: 72px; align-self: start; }
-
-/* 表单 */
-.form-section {
-    background: #fff;
-    border: 1px solid var(--c-gray-200);
-    border-radius: var(--radius);
-    padding: 16px;
-}
-.form-section h3 {
-    font-size: 0.95rem;
-    margin-bottom: 12px;
-    color: var(--c-gray-700);
-}
-.form-row { margin-bottom: 10px; }
-.form-row label { display: block; font-size: 0.8rem; color: var(--c-gray-500); margin-bottom: 4px; font-weight: 500; }
-.form-row input, .form-row select, .form-row textarea {
-    width: 100%;
-    padding: 8px 10px;
-    border: 1px solid var(--c-gray-300);
-    border-radius: 6px;
-    font-size: 0.85rem;
-    font-family: inherit;
-}
-.form-row input:focus, .form-row select:focus, .form-row textarea:focus {
-    outline: none;
-    border-color: var(--c-primary);
-    box-shadow: 0 0 0 3px rgba(59,130,246,0.1);
-}
-.form-row-2, .form-row-3 { display: grid; gap: 12px; margin-bottom: 10px; }
-.form-row-2 { grid-template-columns: 1fr 1fr; }
-.form-row-3 { grid-template-columns: 1fr 1fr 1fr; }
-.form-row-2 label, .form-row-3 label { display: block; font-size: 0.8rem; color: var(--c-gray-500); margin-bottom: 4px; font-weight: 500; }
-.form-row-2 input, .form-row-2 select,
-.form-row-3 input, .form-row-3 select {
-    width: 100%;
-    padding: 8px 10px;
-    border: 1px solid var(--c-gray-300);
-    border-radius: 6px;
-    font-size: 0.85rem;
-}
-.form-row-2 input:focus, .form-row-3 input:focus {
-    outline: none;
-    border-color: var(--c-primary);
-    box-shadow: 0 0 0 3px rgba(59,130,246,0.1);
-}
-
-.form-actions {
-    display: flex;
-    gap: 10px;
-    margin-top: 8px;
-}
-
-/* 双语标签中文部分 */
-.label-cn { color: var(--c-gray-400, #9ca3af); font-weight: 400; margin-left: 4px; }

unilabos/labware_manager/templates/base.html

@@ -1,24 +0,0 @@
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>{% block title %}PRCXI 耗材管理{% endblock %}</title>
-    <link rel="stylesheet" href="/static/style.css">
-    {% block head_extra %}{% endblock %}
-</head>
-<body>
-    <nav class="topbar">
-        <a href="/" class="logo">PRCXI 耗材管理</a>
-        <div class="nav-actions">
-            <a href="/labware/new" class="btn btn-primary btn-sm">+ 新建耗材</a>
-        </div>
-    </nav>
-
-    <main class="container">
-        {% block content %}{% endblock %}
-    </main>
-
-    {% block scripts %}{% endblock %}
-</body>
-</html>

unilabos/labware_manager/templates/detail.html

@@ -1,159 +0,0 @@
-{% extends "base.html" %}
-{% block title %}{{ item.function_name }} - PRCXI{% endblock %}
-
-{% block content %}
-<div class="page-header">
-    <h1>{{ item.function_name }}</h1>
-    <div class="header-actions">
-        <a href="/labware/{{ item.function_name }}/edit" class="btn btn-primary">编辑</a>
-        <a href="/" class="btn btn-outline">返回列表</a>
-    </div>
-</div>
-
-<div class="detail-layout">
-    <!-- 左侧: 信息 -->
-    <div class="detail-info">
-        <div class="info-card">
-            <h3>基本信息</h3>
-            <table class="info-table">
-                <tr><td class="label">类型</td><td><span class="tag tag-{{ item.type }}">{{ item.type }}</span></td></tr>
-                <tr><td class="label">函数名</td><td><code>{{ item.function_name }}</code></td></tr>
-                <tr><td class="label">Model</td><td>{{ item.model or '-' }}</td></tr>
-                {% if item.plate_type %}
-                <tr><td class="label">Plate Type</td><td>{{ item.plate_type }}</td></tr>
-                {% endif %}
-                <tr><td class="label">Docstring</td><td>{{ item.docstring or '-' }}</td></tr>
-            </table>
-        </div>
-
-        <div class="info-card">
-            <h3>物理尺寸 (mm)</h3>
-            <table class="info-table">
-                <tr><td class="label">X</td><td>{{ item.size_x }}</td></tr>
-                <tr><td class="label">Y</td><td>{{ item.size_y }}</td></tr>
-                <tr><td class="label">Z</td><td>{{ item.size_z }}</td></tr>
-            </table>
-        </div>
-
-        <div class="info-card">
-            <h3>材料信息</h3>
-            <table class="info-table">
-                <tr><td class="label">UUID</td><td><code class="small">{{ item.material_info.uuid }}</code></td></tr>
-                <tr><td class="label">Code</td><td>{{ item.material_info.Code }}</td></tr>
-                <tr><td class="label">Name</td><td>{{ item.material_info.Name }}</td></tr>
-                {% if item.material_info.materialEnum is not none %}
-                <tr><td class="label">materialEnum</td><td>{{ item.material_info.materialEnum }}</td></tr>
-                {% endif %}
-                {% if item.material_info.SupplyType is not none %}
-                <tr><td class="label">SupplyType</td><td>{{ item.material_info.SupplyType }}</td></tr>
-                {% endif %}
-            </table>
-        </div>
-
-        {% if item.grid %}
-        <div class="info-card">
-            <h3>网格排列</h3>
-            <table class="info-table">
-                <tr><td class="label">列 x 行</td><td>{{ item.grid.num_items_x }} x {{ item.grid.num_items_y }}</td></tr>
-                <tr><td class="label">dx, dy, dz</td><td>{{ item.grid.dx }}, {{ item.grid.dy }}, {{ item.grid.dz }}</td></tr>
-                <tr><td class="label">item_dx, item_dy</td><td>{{ item.grid.item_dx }}, {{ item.grid.item_dy }}</td></tr>
-            </table>
-        </div>
-        {% endif %}
-
-        {% if item.well %}
-        <div class="info-card">
-            <h3>孔参数 (Well)</h3>
-            <table class="info-table">
-                <tr><td class="label">尺寸</td><td>{{ item.well.size_x }} x {{ item.well.size_y }} x {{ item.well.size_z }}</td></tr>
-                {% if item.well.max_volume is not none %}
-                <tr><td class="label">最大体积</td><td>{{ item.well.max_volume }} uL</td></tr>
-                {% endif %}
-                <tr><td class="label">底部类型</td><td>{{ item.well.bottom_type }}</td></tr>
-                <tr><td class="label">截面类型</td><td>{{ item.well.cross_section_type }}</td></tr>
-                {% if item.well.material_z_thickness is not none %}
-                <tr><td class="label">材料Z厚度</td><td>{{ item.well.material_z_thickness }}</td></tr>
-                {% endif %}
-            </table>
-        </div>
-        {% endif %}
-
-        {% if item.tip %}
-        <div class="info-card">
-            <h3>枪头参数 (Tip)</h3>
-            <table class="info-table">
-                <tr><td class="label">Spot 尺寸</td><td>{{ item.tip.spot_size_x }} x {{ item.tip.spot_size_y }} x {{ item.tip.spot_size_z }}</td></tr>
-                <tr><td class="label">容量</td><td>{{ item.tip.tip_volume }} uL</td></tr>
-                <tr><td class="label">长度</td><td>{{ item.tip.tip_length }} mm</td></tr>
-                <tr><td class="label">取枪头插入深度</td><td>{{ item.tip.tip_fitting_depth }} mm</td></tr>
-                {% if item.tip.tip_above_rack_length is not none %}
-                <tr><td class="label">枪头露出枪头盒长度</td><td>{{ item.tip.tip_above_rack_length }} mm</td></tr>
-                {% endif %}
-                <tr><td class="label">有滤芯</td><td>{{ item.tip.has_filter }}</td></tr>
-            </table>
-        </div>
-        {% endif %}
-
-        {% if item.tube %}
-        <div class="info-card">
-            <h3>管参数 (Tube)</h3>
-            <table class="info-table">
-                <tr><td class="label">尺寸</td><td>{{ item.tube.size_x }} x {{ item.tube.size_y }} x {{ item.tube.size_z }}</td></tr>
-                <tr><td class="label">最大体积</td><td>{{ item.tube.max_volume }} uL</td></tr>
-            </table>
-        </div>
-        {% endif %}
-
-        {% if item.adapter %}
-        <div class="info-card">
-            <h3>适配器参数</h3>
-            <table class="info-table">
-                <tr><td class="label">Hole 尺寸</td><td>{{ item.adapter.adapter_hole_size_x }} x {{ item.adapter.adapter_hole_size_y }} x {{ item.adapter.adapter_hole_size_z }}</td></tr>
-                <tr><td class="label">dx, dy, dz</td><td>{{ item.adapter.dx }}, {{ item.adapter.dy }}, {{ item.adapter.dz }}</td></tr>
-            </table>
-        </div>
-        {% endif %}
-
-        <div class="info-card">
-            <h3>Registry</h3>
-            <table class="info-table">
-                <tr><td class="label">分类</td><td>{{ item.registry_category | join(' / ') }}</td></tr>
-                <tr><td class="label">描述</td><td>{{ item.registry_description }}</td></tr>
-                <tr><td class="label">模板匹配</td><td>{{ item.include_in_template_matching }}</td></tr>
-                {% if item.template_kind %}
-                <tr><td class="label">模板类型</td><td>{{ item.template_kind }}</td></tr>
-                {% endif %}
-            </table>
-        </div>
-    </div>
-
-    <!-- 右侧: 可视化 -->
-    <div class="detail-viz">
-        <div class="viz-card">
-            <h3 style="display:flex;align-items:center;justify-content:space-between;">
-                俯视图 (Top-Down)
-                <button type="button" class="btn btn-sm btn-outline" onclick="resetSvgView('svg-topdown')">回中</button>
-            </h3>
-            <div id="svg-topdown"></div>
-        </div>
-        <div class="viz-card">
-            <h3 style="display:flex;align-items:center;justify-content:space-between;">
-                侧面截面图 (Side Profile)
-                <button type="button" class="btn btn-sm btn-outline" onclick="resetSvgView('svg-side')">回中</button>
-            </h3>
-            <div id="svg-side"></div>
-        </div>
-    </div>
-</div>
-{% endblock %}
-
-{% block scripts %}
-<script src="/static/labware_viz.js"></script>
-<script>
-    const itemData = {{ item.model_dump() | tojson }};
-    document.addEventListener('DOMContentLoaded', () => {
-        renderTopDown(document.getElementById('svg-topdown'), itemData);
-        renderSideProfile(document.getElementById('svg-side'), itemData);
-    });
-</script>
-{% endblock %}

unilabos/labware_manager/templates/edit.html

@@ -1,257 +0,0 @@
-{% extends "base.html" %}
-{% block title %}{% if is_new %}新建耗材{% else %}编辑 {{ item.function_name }}{% endif %} - PRCXI{% endblock %}
-
-{% block content %}
-<div class="page-header">
-    <h1>{% if is_new %}新建耗材{% else %}编辑 {{ item.function_name }}{% endif %}</h1>
-    <div class="header-actions">
-        <a href="/" class="btn btn-outline">返回列表</a>
-    </div>
-</div>
-
-<div id="status-msg" class="status-msg" style="display:none;"></div>
-
-<div class="edit-layout">
-    <!-- 左侧: 表单 -->
-    <div class="edit-form">
-        <form id="labware-form" onsubmit="return false;">
-            <!-- 基本信息 -->
-            <div class="form-section">
-                <h3>基本信息</h3>
-                <div class="form-row">
-                    <label>类型</label>
-                    <select name="type" id="f-type" onchange="onTypeChange()">
-                        <option value="plate" {% if labware_type == 'plate' %}selected{% endif %}>Plate (孔板)</option>
-                        <option value="tip_rack" {% if labware_type == 'tip_rack' %}selected{% endif %}>TipRack (吸头盒)</option>
-                        <option value="trash" {% if labware_type == 'trash' %}selected{% endif %}>Trash (废弃槽)</option>
-                        <option value="tube_rack" {% if labware_type == 'tube_rack' %}selected{% endif %}>TubeRack (管架)</option>
-                        <option value="plate_adapter" {% if labware_type == 'plate_adapter' %}selected{% endif %}>PlateAdapter (适配器)</option>
-                    </select>
-                </div>
-                <div class="form-row">
-                    <label>函数名</label>
-                    <input type="text" name="function_name" id="f-function_name"
-                           value="{{ item.function_name if item else 'PRCXI_new_labware' }}"
-                           placeholder="PRCXI_xxx">
-                </div>
-                <div class="form-row">
-                    <label>Model</label>
-                    <input type="text" name="model" id="f-model"
-                           value="{{ item.model if item and item.model else '' }}">
-                </div>
-                <div class="form-row">
-                    <label>Docstring</label>
-                    <textarea name="docstring" id="f-docstring" rows="2">{{ item.docstring if item else '' }}</textarea>
-                </div>
-                <div class="form-row" id="row-plate_type" style="display:none;">
-                    <label>Plate Type</label>
-                    <select name="plate_type" id="f-plate_type">
-                        <option value="">-</option>
-                        <option value="skirted" {% if item and item.plate_type == 'skirted' %}selected{% endif %}>skirted</option>
-                        <option value="semi-skirted" {% if item and item.plate_type == 'semi-skirted' %}selected{% endif %}>semi-skirted</option>
-                        <option value="non-skirted" {% if item and item.plate_type == 'non-skirted' %}selected{% endif %}>non-skirted</option>
-                    </select>
-                </div>
-            </div>
-
-            <!-- 物理尺寸 -->
-            <div class="form-section">
-                <h3>物理尺寸 Physical Dimensions (mm)</h3>
-                <div class="form-row-3">
-                    <div><label>size_x <span class="label-cn">板长</span></label><input type="number" step="any" name="size_x" id="f-size_x" value="{{ item.size_x if item else 127 }}"></div>
-                    <div><label>size_y <span class="label-cn">板宽</span></label><input type="number" step="any" name="size_y" id="f-size_y" value="{{ item.size_y if item else 85 }}"></div>
-                    <div><label>size_z <span class="label-cn">板高</span></label><input type="number" step="any" name="size_z" id="f-size_z" value="{{ item.size_z if item else 20 }}"></div>
-                </div>
-            </div>
-
-            <!-- 材料信息 -->
-            <div class="form-section">
-                <h3>材料信息</h3>
-                <div class="form-row">
-                    <label>UUID</label>
-                    <input type="text" name="mi_uuid" id="f-mi_uuid"
-                           value="{{ item.material_info.uuid if item else '' }}">
-                </div>
-                <div class="form-row-2">
-                    <div><label>Code</label><input type="text" name="mi_code" id="f-mi_code" value="{{ item.material_info.Code if item else '' }}"></div>
-                    <div><label>Name</label><input type="text" name="mi_name" id="f-mi_name" value="{{ item.material_info.Name if item else '' }}"></div>
-                </div>
-                <div class="form-row-2">
-                    <div><label>materialEnum</label><input type="number" name="mi_menum" id="f-mi_menum" value="{{ item.material_info.materialEnum if item and item.material_info.materialEnum is not none else '' }}"></div>
-                    <div><label>SupplyType</label><input type="number" name="mi_stype" id="f-mi_stype" value="{{ item.material_info.SupplyType if item and item.material_info.SupplyType is not none else '' }}"></div>
-                </div>
-            </div>
-
-            <!-- 网格排列 (plate/tip_rack/tube_rack) -->
-            <div class="form-section" id="section-grid" style="display:none;">
-                <h3 style="display:flex;align-items:center;justify-content:space-between;">
-                    网格排列 Grid Layout
-                    <button type="button" class="btn btn-sm btn-outline" onclick="autoCenter()">自动居中 Auto-Center</button>
-                </h3>
-                <div class="form-row-2">
-                    <div><label>num_items_x <span class="label-cn">列数</span></label><input type="number" name="grid_nx" id="f-grid_nx" value="{{ item.grid.num_items_x if item and item.grid else 12 }}"></div>
-                    <div><label>num_items_y <span class="label-cn">行数</span></label><input type="number" name="grid_ny" id="f-grid_ny" value="{{ item.grid.num_items_y if item and item.grid else 8 }}"></div>
-                </div>
-                <div class="form-row-3">
-                    <div><label>dx <span class="label-cn">首孔X偏移</span></label><input type="number" step="any" name="grid_dx" id="f-grid_dx" value="{{ item.grid.dx if item and item.grid else 0 }}"></div>
-                    <div><label>dy <span class="label-cn">首孔Y偏移</span></label><input type="number" step="any" name="grid_dy" id="f-grid_dy" value="{{ item.grid.dy if item and item.grid else 0 }}"></div>
-                    <div><label>dz <span class="label-cn">孔底Z偏移</span></label><input type="number" step="any" name="grid_dz" id="f-grid_dz" value="{{ item.grid.dz if item and item.grid else 0 }}"></div>
-                </div>
-                <div class="form-row-2">
-                    <div><label>item_dx <span class="label-cn">列间距</span></label><input type="number" step="any" name="grid_idx" id="f-grid_idx" value="{{ item.grid.item_dx if item and item.grid else 9 }}"></div>
-                    <div><label>item_dy <span class="label-cn">行间距</span></label><input type="number" step="any" name="grid_idy" id="f-grid_idy" value="{{ item.grid.item_dy if item and item.grid else 9 }}"></div>
-                </div>
-            </div>
-
-            <!-- Well 参数 (plate) -->
-            <div class="form-section" id="section-well" style="display:none;">
-                <h3>孔参数 Well</h3>
-                <div class="form-row-3">
-                    <div><label>size_x <span class="label-cn">孔长</span></label><input type="number" step="any" name="well_sx" id="f-well_sx" value="{{ item.well.size_x if item and item.well else 8 }}"></div>
-                    <div><label>size_y <span class="label-cn">孔宽</span></label><input type="number" step="any" name="well_sy" id="f-well_sy" value="{{ item.well.size_y if item and item.well else 8 }}"></div>
-                    <div><label>size_z <span class="label-cn">孔深</span></label><input type="number" step="any" name="well_sz" id="f-well_sz" value="{{ item.well.size_z if item and item.well else 10 }}"></div>
-                </div>
-                <div class="form-row-2">
-                    <div><label>max_volume <span class="label-cn">最大容量 (uL)</span></label><input type="number" step="any" name="well_vol" id="f-well_vol" value="{{ item.well.max_volume if item and item.well and item.well.max_volume is not none else '' }}"></div>
-                    <div><label>material_z_thickness <span class="label-cn">底壁厚度</span></label><input type="number" step="any" name="well_mzt" id="f-well_mzt" value="{{ item.well.material_z_thickness if item and item.well and item.well.material_z_thickness is not none else '' }}"></div>
-                </div>
-                <div class="form-row-2">
-                    <div>
-                        <label>bottom_type <span class="label-cn">底部形状</span></label>
-                        <select name="well_bt" id="f-well_bt">
-                            <option value="FLAT" {% if item and item.well and item.well.bottom_type == 'FLAT' %}selected{% endif %}>FLAT</option>
-                            <option value="V" {% if item and item.well and item.well.bottom_type == 'V' %}selected{% endif %}>V</option>
-                            <option value="U" {% if item and item.well and item.well.bottom_type == 'U' %}selected{% endif %}>U</option>
-                        </select>
-                    </div>
-                    <div>
-                        <label>cross_section_type <span class="label-cn">截面形状</span></label>
-                        <select name="well_cs" id="f-well_cs">
-                            <option value="CIRCLE" {% if item and item.well and item.well.cross_section_type == 'CIRCLE' %}selected{% endif %}>CIRCLE</option>
-                            <option value="RECTANGLE" {% if item and item.well and item.well.cross_section_type == 'RECTANGLE' %}selected{% endif %}>RECTANGLE</option>
-                        </select>
-                    </div>
-                </div>
-                <div class="form-row">
-                    <label><input type="checkbox" name="has_vf" id="f-has_vf" {% if item and item.volume_functions %}checked{% endif %}> 使用 volume_functions (rectangle)</label>
-                </div>
-            </div>
-
-            <!-- Tip 参数 (tip_rack) -->
-            <div class="form-section" id="section-tip" style="display:none;">
-                <h3>枪头参数 Tip</h3>
-                <div class="form-row-3">
-                    <div><label>spot_size_x <span class="label-cn">卡槽长</span></label><input type="number" step="any" name="tip_sx" id="f-tip_sx" value="{{ item.tip.spot_size_x if item and item.tip else 7 }}"></div>
-                    <div><label>spot_size_y <span class="label-cn">卡槽宽</span></label><input type="number" step="any" name="tip_sy" id="f-tip_sy" value="{{ item.tip.spot_size_y if item and item.tip else 7 }}"></div>
-                    <div><label>spot_size_z <span class="label-cn">卡槽高</span></label><input type="number" step="any" name="tip_sz" id="f-tip_sz" value="{{ item.tip.spot_size_z if item and item.tip else 0 }}"></div>
-                </div>
-                <div class="form-row-3">
-                    <div><label>tip_volume <span class="label-cn">枪头容量 (uL)</span></label><input type="number" step="any" name="tip_vol" id="f-tip_vol" value="{{ item.tip.tip_volume if item and item.tip else 300 }}"></div>
-                    <div><label>tip_length <span class="label-cn">枪头总长度 (mm)</span></label><input type="number" step="any" name="tip_len" id="f-tip_len" value="{{ item.tip.tip_length if item and item.tip else 60 }}"></div>
-                    <div><label>fitting_depth <span class="label-cn">取枪头时插入的长度 (mm)</span></label><input type="number" step="any" name="tip_dep" id="f-tip_dep" value="{{ item.tip.tip_fitting_depth if item and item.tip else 51 }}"></div>
-                </div>
-                <div class="form-row">
-                    <label>tip_above_rack_length <span class="label-cn">枪头在枪头盒上方的部分的长度 (mm)</span></label>
-                    <input type="number" step="any" name="tip_above" id="f-tip_above"
-                           value="{{ item.tip.tip_above_rack_length if item and item.tip and item.tip.tip_above_rack_length is not none else '' }}"
-                           placeholder="tip_length - (size_z - dz)">
-                    <small style="color:#888;margin-top:2px;">公式: tip_length = tip_above + size_z - dz；填 tip_above 自动算 dz，填 dz 自动算 tip_above</small>
-                </div>
-                <div class="form-row">
-                    <label><input type="checkbox" name="tip_filter" id="f-tip_filter" {% if item and item.tip and item.tip.has_filter %}checked{% endif %}> has_filter</label>
-                </div>
-            </div>
-
-            <!-- Tube 参数 (tube_rack) -->
-            <div class="form-section" id="section-tube" style="display:none;">
-                <h3>管参数 Tube</h3>
-                <div class="form-row-3">
-                    <div><label>size_x <span class="label-cn">管径X</span></label><input type="number" step="any" name="tube_sx" id="f-tube_sx" value="{{ item.tube.size_x if item and item.tube else 10.6 }}"></div>
-                    <div><label>size_y <span class="label-cn">管径Y</span></label><input type="number" step="any" name="tube_sy" id="f-tube_sy" value="{{ item.tube.size_y if item and item.tube else 10.6 }}"></div>
-                    <div><label>size_z <span class="label-cn">管高</span></label><input type="number" step="any" name="tube_sz" id="f-tube_sz" value="{{ item.tube.size_z if item and item.tube else 40 }}"></div>
-                </div>
-                <div class="form-row">
-                    <label>max_volume <span class="label-cn">最大容量 (uL)</span></label>
-                    <input type="number" step="any" name="tube_vol" id="f-tube_vol" value="{{ item.tube.max_volume if item and item.tube else 1500 }}">
-                </div>
-            </div>
-
-            <!-- Adapter 参数 (plate_adapter) -->
-            <div class="form-section" id="section-adapter" style="display:none;">
-                <h3>适配器参数 Adapter</h3>
-                <div class="form-row-3">
-                    <div><label>hole_size_x <span class="label-cn">凹槽长</span></label><input type="number" step="any" name="adp_hsx" id="f-adp_hsx" value="{{ item.adapter.adapter_hole_size_x if item and item.adapter else 127.76 }}"></div>
-                    <div><label>hole_size_y <span class="label-cn">凹槽宽</span></label><input type="number" step="any" name="adp_hsy" id="f-adp_hsy" value="{{ item.adapter.adapter_hole_size_y if item and item.adapter else 85.48 }}"></div>
-                    <div><label>hole_size_z <span class="label-cn">凹槽深</span></label><input type="number" step="any" name="adp_hsz" id="f-adp_hsz" value="{{ item.adapter.adapter_hole_size_z if item and item.adapter else 10 }}"></div>
-                </div>
-                <div class="form-row-3">
-                    <div><label>dx <span class="label-cn">X偏移</span></label><input type="number" step="any" name="adp_dx" id="f-adp_dx" value="{{ item.adapter.dx if item and item.adapter and item.adapter.dx is not none else '' }}"></div>
-                    <div><label>dy <span class="label-cn">Y偏移</span></label><input type="number" step="any" name="adp_dy" id="f-adp_dy" value="{{ item.adapter.dy if item and item.adapter and item.adapter.dy is not none else '' }}"></div>
-                    <div><label>dz <span class="label-cn">Z偏移</span></label><input type="number" step="any" name="adp_dz" id="f-adp_dz" value="{{ item.adapter.dz if item and item.adapter else 0 }}"></div>
-                </div>
-            </div>
-
-            <!-- Registry -->
-            <div class="form-section">
-                <h3>Registry / Template</h3>
-                <div class="form-row">
-                    <label>registry_category (逗号分隔)</label>
-                    <input type="text" name="reg_cat" id="f-reg_cat"
-                           value="{{ item.registry_category | join(',') if item else 'prcxi,plates' }}">
-                </div>
-                <div class="form-row">
-                    <label>registry_description</label>
-                    <input type="text" name="reg_desc" id="f-reg_desc"
-                           value="{{ item.registry_description if item else '' }}">
-                </div>
-                <div class="form-row">
-                    <label><input type="checkbox" name="in_tpl" id="f-in_tpl" {% if item and item.include_in_template_matching %}checked{% endif %}> include_in_template_matching</label>
-                </div>
-                <div class="form-row" id="row-tpl_kind">
-                    <label>template_kind</label>
-                    <input type="text" name="tpl_kind" id="f-tpl_kind"
-                           value="{{ item.template_kind if item and item.template_kind else '' }}">
-                </div>
-            </div>
-
-            <div class="form-actions">
-                <button type="button" class="btn btn-primary" onclick="saveForm()">
-                    {% if is_new %}创建{% else %}保存{% endif %}
-                </button>
-                <a href="/" class="btn btn-outline">取消</a>
-            </div>
-        </form>
-    </div>
-
-    <!-- 右侧: 实时预览 -->
-    <div class="edit-preview">
-        <div class="viz-card">
-            <h3 style="display:flex;align-items:center;justify-content:space-between;">
-                预览: 俯视图
-                <button type="button" class="btn btn-sm btn-outline" onclick="resetSvgView('svg-topdown')">回中</button>
-            </h3>
-            <div id="svg-topdown"></div>
-        </div>
-        <div class="viz-card">
-            <h3 style="display:flex;align-items:center;justify-content:space-between;">
-                预览: 侧面截面图
-                <button type="button" class="btn btn-sm btn-outline" onclick="resetSvgView('svg-side')">回中</button>
-            </h3>
-            <div id="svg-side"></div>
-        </div>
-    </div>
-</div>
-{% endblock %}
-
-{% block scripts %}
-<script src="/static/labware_viz.js"></script>
-<script src="/static/form_handler.js"></script>
-<script>
-    const IS_NEW = {{ 'true' if is_new else 'false' }};
-    const ITEM_ID = "{{ item.function_name if item else '' }}";
-    document.addEventListener('DOMContentLoaded', () => {
-        onTypeChange();
-        updatePreview();
-    });
-</script>
-{% endblock %}