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/base/recipe.yaml

@@ -3,7 +3,7 @@
 
 package:
   name: unilabos
-  version: 0.11.3
+  version: 0.11.1
 
 source:
   path: ../../unilabos
@@ -54,7 +54,7 @@ requirements:
   - pymodbus
   - matplotlib
   - pylibftdi
-  - uni-lab::unilabos-env ==0.11.3
+  - uni-lab::unilabos-env ==0.11.1
 
 about:
   repository: https://github.com/deepmodeling/Uni-Lab-OS

.conda/environment/recipe.yaml

@@ -2,7 +2,7 @@
 
 package:
   name: unilabos-env
-  version: 0.11.3
+  version: 0.11.1
 
 build:
   noarch: generic

.conda/full/recipe.yaml

@@ -3,7 +3,7 @@
 
 package:
   name: unilabos-full
-  version: 0.11.3
+  version: 0.11.1
 
 build:
   noarch: generic
@@ -11,7 +11,7 @@ build:
 requirements:
   run:
   # Base unilabos package (includes unilabos-env)
-  - uni-lab::unilabos ==0.11.3
+  - uni-lab::unilabos ==0.11.1
   # Documentation tools
   - sphinx
   - sphinx_rtd_theme

.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

@@ -5,98 +5,9 @@ description: Guide for adding new devices to Uni-Lab-OS (接入新设备). Uses
 
 # 添加新设备到 Uni-Lab-OS
 
-本 Skill 是自包含的设备接入指南，不依赖外部文档。迁移给别人时，只复制 `.cursor/skills/add-device/SKILL.md` 即可获得核心规则、模板、验证方式和常见错误清单。
+**第一步：** 使用 Read 工具读取 `docs/ai_guides/add_device.md`，获取完整的设备接入指南。
 
-开始实现前，仍应搜索 `unilabos/devices/` 获取同类别已有设备的接口、参数名、状态字符串和返回值风格作为参考。
-
----
-
-## 接入工作流
-
-按下面顺序推进，并在工作中维护进度：
-
-```text
-设备接入进度：
-- [ ] 1. 确定设备类别（物模型）和对外单位
-- [ ] 2. 确定通信协议
-- [ ] 3. 收集指令协议（SDK、厂商文档、寄存器表、HTTP API、用户口述）
-- [ ] 4. 对齐同类设备接口（搜索 unilabos/devices/）
-- [ ] 5. 创建驱动 unilabos/devices/<category>/<file>.py
-- [ ] 6. 验证可导入、注册表扫描、启动测试
-- [ ] 7. 如需要，配置实验图文件
-```
-
-## 设备类别（物模型）
-
-优先使用已有类别。只有确实无法归类时才使用 `custom`。
-
-| 类别 ID | 说明 | 标准属性 | 标准动作 |
-|---|---|---|---|
-| `temperature` | 加热、冷却、温控 | `temp`, `temp_target`, `status` | `set_temperature`, `stop` |
-| `pump_and_valve` | 泵、阀门、注射器 | 见子类型表 | 见子类型表 |
-| `motor` | 电机、步进马达 | `position`, `status` | `enable`, `move_position`, `move_speed`, `stop` |
-| `heaterstirrer` | 加热搅拌一体机 | `temp`, `stir_speed`, `status` | `set_temperature`, `stir`, `stop` |
-| `balance` | 天平、称重 | `weight`, `unit`, `status` | `tare`, `read_weight` |
-| `sensor` | 传感器（液位、温度等） | `value`, `level`, `status` | `read_value`, `set_threshold` |
-| `liquid_handling` | 液体处理机器人 | `status`, `deck_state` | `transfer_liquid`, `aspirate`, `dispense` |
-| `robot_arm` | 机械臂 | `arm_pose`, `arm_status` | `moveit_task`, `pick_and_place` |
-| `workstation` | 工作站、组合设备 | `workflow_sequence`, `material_info` | `create_order`, `scheduler_start`, `scheduler_stop` |
-| `virtual` | 虚拟、模拟设备 | 按模拟的真实设备定义 | 按模拟的真实设备定义 |
-| `custom` | 不属于以上类别 | 用户自定义 | 用户自定义 |
-
-`pump_and_valve` 子类型：
-
-| 子类型 | 最小通用属性 | 最小通用动作 | 单位约定 |
-|---|---|---|---|
-| 注射泵（syringe pump） | `status`, `valve_position`, `position` | `initialize`, `set_valve_position`, `set_position`, `pull_plunger`, `push_plunger`, `stop_operation` | 体积=mL, 速度=mL/s |
-| 电磁阀（solenoid valve） | `status`, `valve_position` | `open`, `close`, `set_valve_position` | 无 |
-| 蠕动泵（peristaltic pump） | `status`, `speed` | `start`, `stop`, `set_speed` | 流速=mL/min |
-
-对外暴露的属性和动作参数必须使用用户友好的物理单位（mL、ul、degC、RPM 等），硬件原始值转换放在驱动内部。
-
-## 通信协议和指令来源
-
-先确认通信方式，再确认具体指令协议。物模型只定义设备“应该做什么”，不会告诉你硬件“具体发什么字节/请求”。
-
-| 协议 | 常用 config 参数 | 常用依赖 | 现有抽象 |
-|---|---|---|---|
-| Serial (RS232/RS485) | `port`, `baudrate`, `timeout` | `pyserial` | 直接使用 `serial.Serial` |
-| Modbus RTU | `port`, `baudrate`, `slave_id` | `pymodbus` | `device_comms/modbus_plc/` |
-| Modbus TCP | `host`, `port`, `slave_id` | `pymodbus` | `device_comms/modbus_plc/` |
-| TCP Socket | `host`, `port`, `timeout` | stdlib | 直接使用 `socket` |
-| HTTP API | `url`, `token`, `timeout` | `requests` | `device_comms/rpc.py` |
-| OPC UA | `url` | `opcua` | `device_comms/opcua_client/` |
-| 无通信（虚拟） | 无 | 无 | 在动作中模拟行为 |
-
-必须从以下来源之一获得指令细节：
-
-| 来源 | 处理方式 |
-|---|---|
-| 现成 SDK/驱动代码 | 读取代码，提取指令逻辑，包装进 Uni-Lab-OS 类 |
-| 协议文档/手册 | 解析命令、响应、校验、寄存器、错误码 |
-| 用户口述 | 按描述实现指令编解码，标出不确定点 |
-| 标准协议 | 使用标准实现，例如 Modbus 寄存器表、SCPI |
-| 虚拟设备 | 跳过硬件通信，在动作方法中维护模拟状态 |
-
-## 对齐已有实现（强制）
-
-实现前必须搜索 `unilabos/devices/` 中同类别设备：
-
-- 参数名必须与已有设备保持一致；动作方法参数名是接口契约，不要随意改成 `volume_ml`、`target_temp_c` 这类新名字。
-- `status` 字符串值要和同类设备一致，优先使用英文稳定值，例如 `Idle`、`Running`、`Error`。
-- 状态属性用 `@property` + `@topic_config()` 明确声明。
-- 返回值使用结构化 dict，至少包含 `success`，需要给前端展示的信息放在 `message`、`data`、`error` 等字段。
-
-## 架构选择
-
-| 场景 | 推荐方式 |
-|---|---|
-| 简单设备 | 纯 Python 类 + `@device` |
-| 工作站/组合设备 | `WorkstationBase` 或项目内已有工作站模式 |
-| 液体处理 | `LiquidHandlerAbstract` / PyLabRobot 相关模式 |
-| Modbus 设备 | 复用 `device_comms/modbus_plc/` 或项目内 Modbus 示例 |
-| OPC UA 设备 | 复用 `device_comms/opcua_client/` |
-| 外部独立包 | 使用 `create-device-package` skill |
+该指南包含设备类别（物模型）列表、通信协议模板、常见错误检查清单等。搜索 `unilabos/devices/` 获取已有设备的实现参考。
 
 ---
 
@@ -160,45 +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=""`，但新设备应优先写清楚显示名和说明。
-
-### 特殊参数类型：ResourceSlot / DeviceSlot
-
-需要前端选择资源或设备时，用特殊类型注解，registry 会自动生成 `placeholder_keys`：
-
-```python
-from typing import List
-from unilabos.registry.placeholder_type import DeviceSlot, ResourceSlot
-
-@action(description="转移液体")
-def transfer(self, source: ResourceSlot, target: ResourceSlot, volume_ul: float) -> dict:
-    """
-    Args:
-        source[源资源]: 源容器或孔位。
-        target[目标资源]: 目标容器或孔位。
-        volume_ul[体积(ul)]: 转移体积。
-    """
-    return {"success": True}
-
-@action(description="同步设备")
-def sync_devices(self, devices: List[DeviceSlot]) -> dict:
-    return {"success": True, "count": len(devices)}
-```
-
 ### @topic_config — 状态属性配置
 
 ```python
@@ -233,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}")
@@ -275,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]:
@@ -306,154 +158,3 @@ class MyDevice:
 - `post_init` 用 `@not_action` 标记，参数类型标注为 `BaseROS2DeviceNode`
 - 运行时状态存储在 `self.data` 字典中
 - 设备文件放在 `unilabos/devices/<category>/` 目录下
-
----
-
-## 通信实现片段
-
-Serial 文本指令：
-
-```python
-def _send_command(self, cmd: str) -> str:
-    self.ser.write(f"{cmd}\r\n".encode())
-    return self.ser.readline().decode().strip()
-```
-
-RS-485 响应解析要先定位帧头，不要用硬编码索引直接解析原始响应：
-
-```python
-def _normalize_response(self, raw: str, start_marker: str = "/") -> str:
-    pos = raw.find(start_marker)
-    return raw[pos:] if pos >= 0 else raw
-```
-
-自定义二进制帧：
-
-```python
-def _build_frame(self, func_code: int, data: bytes) -> bytes:
-    frame = bytearray([0xFE, func_code]) + bytearray(data)
-    checksum = sum(frame[1:]) % 256
-    frame.append(checksum)
-    return bytes(frame)
-```
-
-Modbus 寄存器映射：
-
-```python
-REGISTER_MAP = {
-    "temp_target": {"addr": 0x000B, "scale": 10},
-}
-
-def set_temperature(self, temp: float, **kwargs) -> bool:
-    reg = REGISTER_MAP["temp_target"]
-    value = int(float(temp) * reg["scale"]) & 0xFFFF
-    self.client.write_register(reg["addr"], value, slave=self.slave_id)
-    self.data["temp_target"] = temp
-    return True
-```
-
-HTTP API 映射：
-
-```python
-API_MAP = {
-    "set_temperature": {
-        "method": "POST",
-        "endpoint": "/api/temperature",
-        "body_key": "target",
-    },
-}
-```
-
-SDK 封装：
-
-```python
-from my_device_sdk import DeviceController
-
-class MyDevice:
-    def __init__(self, device_id=None, config=None, **kwargs):
-        self.config = config or {}
-        self.controller = DeviceController(port=self.config.get("port", "COM1"))
-```
-
----
-
-## 验证
-
-无需手写注册表 YAML。`@device` 装饰器 + AST 扫描会在启动或检查时生成注册表条目。
-
-```bash
-# 1. 模块可导入
-python -c "from unilabos.devices.<category>.<file> import <ClassName>"
-
-# 2. 启动测试
-unilab -g <graph>.json
-
-# 3. 仅检查注册表
-unilab --check_mode --skip_env_check
-```
-
-仅在旧代码无 `@device`、需要覆盖特殊字段、或做 `--complete_registry` 旧设备补全时，才考虑 YAML。新设备默认不要手写 YAML。
-
-## 图文件节点模板
-
-实验图 JSON 中的 `class` 对应 `@device(id=...)`，`config` 会传入 `__init__` 的 `config` 字典：
-
-```json
-{
-  "id": "my_device_1",
-  "name": "我的设备",
-  "children": [],
-  "parent": null,
-  "type": "device",
-  "class": "my_device",
-  "position": {"x": 0, "y": 0, "z": 0},
-  "config": {
-    "port": "/dev/ttyUSB0",
-    "baudrate": 9600
-  },
-  "data": {}
-}
-```
-
-工作站需要同时配置 `deck` 和 `children`：
-
-```json
-{
-  "nodes": [
-    {
-      "id": "my_station",
-      "type": "device",
-      "class": "my_workstation",
-      "children": ["my_deck"],
-      "config": {},
-      "deck": {
-        "data": {
-          "_resource_child_name": "my_deck",
-          "_resource_type": "unilabos.resources.my_module:MyDeck"
-        }
-      }
-    },
-    {
-      "id": "my_deck",
-      "type": "deck",
-      "class": "MyDeckClass",
-      "parent": "my_station",
-      "config": {"type": "MyDeckClass", "setup": true}
-    }
-  ]
-}
-```
-
----
-
-## 常见错误清单
-
-- 缺少 `@device`：设备不会被 AST 扫描发现。
-- 只有 `@property` 没有 `@topic_config()`：属性不会稳定广播到 `status_types`。
-- `post_init` 没有 `@not_action`：会被误暴露为动作。
-- `self.data = {}`：空字典会导致属性读取和 schema 初始数据不稳定，必须预填充每个状态键。
-- 动作参数重命名：不要把同类设备已有的 `volume` 改成 `volume_ml`，参数名是接口契约。
-- `status` 使用中文或临时文本：前端和工作流依赖稳定英文状态值。
-- async 方法中使用 `time.sleep()`：应使用 `await self._ros_node.sleep(seconds)`。
-- 硬编码串口响应索引：RS-485 响应前可能有噪声字节，应先定位帧头。
-- 把硬件寄存器单位暴露给用户：对外使用物理单位，驱动内部做 scale 转换。

.cursor/skills/filter-workflow-by-tags/SKILL.md

@@ -1,450 +0,0 @@
----
-name: filter-workflow-by-tags
-description: Query backend workflow list, aggregate all tags, and filter workflows by domain/scenario requirements using tags. Use when the user wants to search workflows, find workflows by tags, list available workflow tags, filter workflows by category/domain/scenario, or mentions 工作流筛选/标签查询/workflow tags/按领域查找工作流.
----
-# Uni-Lab 工作流标签筛选指南
-
-通过 Uni-Lab 云端 API 查询工作流列表，汇总所有可用标签（tags），并根据领域和场景要求筛选工作流。
-
-> **重要**：本指南中的 `Authorization: Lab <token>` 是 **Uni-Lab 平台专用的认证方式**，`Lab` 是 Uni-Lab 的 auth scheme 关键字，**不是** HTTP Basic 认证。请勿将其替换为 `Basic`。
-
-## 使用模式识别
-
-**用户可能一开始就给出场景目标**（如"我要做有机合成实验"、"找柱层析相关的 protocol"）。此时：
-
-1. **识别场景关键词** → 映射到可能的 tags（如 synthesis、organic、chromatography、purification）
-2. **直接执行完整流程**（获取 ak/sk/addr → 拉取所有工作流 → 汇总 tags → 按场景筛选）
-3. **展示筛选结果** → 引导用户从候选 workflow 中**选择明确的实验 protocol**
-4. **如果用户确认某个 workflow** → 记录 `workflow_uuid`，准备对接“与其他 Skill 的协作”
-
-**如果用户未给场景目标**，则按标准 checklist 询问筛选条件。
-
----
-
-## 前置条件
-
-使用本指南前，**必须**先确认以下信息。如果缺少任何一项，**立即向用户询问并终止**，等补齐后再继续。
-
-### 1. ak / sk → AUTH
-
-询问用户的启动参数，从 `--ak` `--sk` 或 config.py 中获取。
-
-生成 AUTH token：
-
-```bash
-python -c "import base64,sys; print('Authorization: Lab ' + base64.b64encode(f'{sys.argv[1]}:{sys.argv[2]}'.encode()).decode())" <ak> <sk>
-```
-
-### 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>"
-```
-
-### 3. lab_uuid（实验室 UUID）
-
-如果用户未提供 `lab_uuid`，通过以下 API 自动获取：
-
-```bash
-curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH"
-```
-
-返回 `data.uuid` 即为 `lab_uuid`。
-
-**三项全部就绪后才可开始。**
-
-## Session State
-
-在整个对话过程中，agent 需要记住以下状态：
-
-- `lab_uuid` — 实验室 UUID
-- `all_workflows` — 完整工作流列表（分页获取后缓存到内存或临时文件）
-- `all_tags` — 所有工作流的标签汇总
-
----
-
-## API 端点
-
-### 查询工作流列表（支持分页）
-
-```
-GET $BASE/api/v1/lab/workflow/owner/list?page=<page>&page_size=<page_size>&lab_uuid=$lab_uuid
-```
-
-**参数：**
-
-- `page` — 页码，从 1 开始
-- `page_size` — 每页数量，建议 1000
-- `lab_uuid` — 实验室 UUID
-
-**返回结构：**
-
-```json
-{
-  "code": 0,
-  "data": {
-    "has_more": true,
-    "data": [
-      {
-        "uuid": "9661bba2-1b9f-4687-a63d-910245df174b",
-        "name": "Untitled",
-        "description": "",
-        "user_id": "114211",
-        "published": false,
-        "tags": null
-      },
-      {
-        "uuid": "e0436638-190b-46bc-b1a1-2711d9602f6a",
-        "name": "Synthesis v2",
-        "user_id": "114211",
-        "published": true,
-        "tags": ["synthesis", "organic"]
-      }
-    ]
-  }
-}
-```
-
-**字段说明：**
-
-- `has_more` — 若为 `true`，需要继续请求 `page+1`
-- `tags` — 可能为 `null`、空数组或字符串数组；聚合时必须容忍 `null`
-
-### 启动工作流（直接运行）
-
-```
-POST $BASE/api/v1/lab/workflow/<workflow_uuid>/run
-```
-
-**用途：** 直接启动一个 workflow 的默认执行（使用模板中预设的参数），无需创建 notebook。适用于快速测试或无参数变化的重复执行。
-
-**请求体：** 空 JSON `{}` 或省略
-
-**返回：**
-
-```json
-{
-  "code": 0,
-  "data": "<run_uuid>"
-}
-```
-
-- `run_uuid` — 本次执行的唯一标识（不是 notebook UUID）
-
-**注意：**
-
-- 该接口会使用 workflow 模板中保存的默认参数直接执行
-- 如果 workflow 需要动态参数（如 CSV 路径、样品 UUID），应使用 `POST /lab/notebook` 创建 notebook 并传入 `node_params`
-- 返回的 `run_uuid` 可直接传入下方「查询任务状态」接口查询实时进度
-
-### 查询任务状态
-
-```
-GET $BASE/api/v1/lab/mcp/task/<task_uuid>
-```
-
-**用途：** 查询由 `POST /lab/workflow/<uuid>/run` 返回的 `run_uuid`（即 task_uuid）的实时执行状态，包括整体状态和每个节点（JOS：Job On Station）的执行详情。
-
-**路径参数：**
-
-- `task_uuid` — 等同于启动工作流接口返回的 `run_uuid`
-
-**返回：**
-
-```json
-{
-  "code": 0,
-  "data": {
-    "status": "running",
-    "jos_status": [
-      {
-        "uuid": "d0e24bfe-8d99-450e-b19d-f25849dfbaad",
-        "node_name": "PRCXI_BioER_96_wellplate_slot_1",
-        "action_name": "create_resource",
-        "status": "success",
-        "return_info": {
-          "suc": true,
-          "error": "",
-          "return_value": { ... }
-        }
-      },
-      {
-        "uuid": "...",
-        "node_name": "...",
-        "action_name": "transfer_liquid",
-        "status": "pending",
-        "return_info": null
-      }
-    ]
-  }
-}
-```
-
-**字段说明：**
-
-- `data.status` — 整体任务状态
-  - `running` — 正在执行（至少一个节点 pending 或 running）
-  - `success` — 全部节点成功
-  - `failed` — 有节点失败
-- `data.jos_status[]` — 节点级执行列表（按执行顺序）
-  - `uuid` — 节点执行实例 UUID
-  - `node_name` — 节点名称（资源/设备名或工位名）
-  - `action_name` — 动作类型（`create_resource`、`transfer_liquid`、`centrifuge`、等）
-  - `status` — 节点状态：`success`、`pending`、`running`、`failed`
-  - `return_info` — 执行返回，失败时 `suc=false` 且 `error` 有错误信息
-
-**注意：**
-
-- 此接口的 `task_uuid` **是** `POST /lab/workflow/<uuid>/run` 返回的 `run_uuid`，二者为同一个 ID 的不同称呼
-- **不要**把 notebook UUID（`POST /lab/notebook` 返回）传进来——那条路径用 `GET /lab/notebook/status` 查询
-- `jos_status` 数组按节点执行顺序给出；从 pending 数量可以估算剩余进度
-- 返回体可能较大（`return_info.return_value` 中可能包含完整 resource tree），可在脚本中只提取 `status` + `node_name` + `action_name` 做摘要
-
-**状态轮询示例：**
-
-```bash
-# 每 5 秒轮询一次直至完成
-TASK="b183d97e-d2b5-4b24-b14b-820df04d87c0"
-while :; do
-  st=$(curl -s -X GET "$BASE/api/v1/lab/mcp/task/$TASK" -H "$AUTH" \
-    | python3 -c "import json,sys; d=json.load(sys.stdin)['data']; \
-      print(d['status'], '|', sum(1 for j in d['jos_status'] if j['status']=='success'), '/', len(d['jos_status']))")
-  echo "$(date +%H:%M:%S) $st"
-  [[ "$st" == success* || "$st" == failed* ]] && break
-  sleep 5
-done
-```
-
----
-
-## 完整工作流 Checklist
-
-```
-Task Progress:
-- [ ] Step 0: 识别用户是否已给出场景目标（如"有机合成"、"柱层析"）
-       - 若已给出 → 记录场景关键词，自动进入后续步骤
-       - 若未给出 → 在 Step 6 询问用户
-- [ ] Step 1: 确认 ak/sk → 生成 AUTH token
-- [ ] Step 2: 确认 --addr → 设置 BASE URL
-- [ ] Step 3: GET /edge/lab/info → 获取 lab_uuid（如用户未提供）
-- [ ] Step 4: 分页获取所有工作流（从 page=1 开始直到 has_more=false）
-- [ ] Step 5: 汇总所有非空 tags → 生成 all_tags（去重、排序、附出现次数）
-- [ ] Step 6: 根据场景关键词（Step 0 或新询问）在 all_tags 中做语义映射 → 确定候选 tags
-       - 若语义映射不唯一，列出候选 tags 让用户确认
-- [ ] Step 7: 按候选 tags 筛选工作流（默认 any 模式，召回优先）
-- [ ] Step 8: 展示筛选结果（uuid、name、description、tags、published）
-- [ ] Step 9: 引导用户从结果中选择**明确的实验 protocol**
-       - 若结果只有 1 条 → 直接确认该 workflow_uuid
-       - 若结果 2–10 条 → 让用户按编号选择
-       - 若结果过多 → 提示收紧条件（加 tag、切换 all 模式、仅 published）
-       - 若结果为空 → 放宽条件（去掉最稀有 tag）或提示用户换关键词
-- [ ] Step 10: 记录用户选中的 workflow_uuid，并提示提交实验或查看详情
-```
-
----
-
-## 推荐路径：使用脚本
-
-同目录下提供 `scripts/filter_workflows.py`，一次完成分页抓取、标签聚合与筛选：
-
-```bash
-# 1. 仅汇总标签（不筛选）
-python scripts/filter_workflows.py \
-  --auth "<Lab base64token>" \
-  --base "$BASE" \
-  --lab-uuid "$lab_uuid" \
-  --summary-only
-
-# 2. 按标签筛选（ANY 模式：包含任一）
-python scripts/filter_workflows.py \
-  --auth "<Lab base64token>" \
-  --base "$BASE" \
-  --lab-uuid "$lab_uuid" \
-  --tags synthesis organic \
-  --mode any
-
-# 3. 按标签筛选（ALL 模式：必须同时包含）
-python scripts/filter_workflows.py \
-  --auth "<Lab base64token>" \
-  --base "$BASE" \
-  --lab-uuid "$lab_uuid" \
-  --tags synthesis organic \
-  --mode all \
-  --output filtered.json
-
-# 4. 仅筛选已发布
-python scripts/filter_workflows.py \
-  --auth "<Lab base64token>" \
-  --base "$BASE" \
-  --lab-uuid "$lab_uuid" \
-  --tags synthesis \
-  --published-only
-```
-
-**`--auth` 参数说明**：传入 `Authorization` 头中 `Lab` 之后的 base64 token（不带 `Lab ` 前缀），脚本内部会自动补上 scheme。
-
-**输出结构：**
-
-```json
-{
-  "total_workflows": 150,
-  "tag_counts": {"synthesis": 12, "organic": 8, "analysis": 5},
-  "all_tags": ["analysis", "organic", "synthesis"],
-  "filter": {"tags": ["synthesis", "organic"], "mode": "any"},
-  "filtered_workflows": [
-    {"uuid": "...", "name": "...", "description": "...", "tags": [...], "published": true}
-  ]
-}
-```
-
----
-
-## 手动路径：curl + jq
-
-如果脚本不可用或环境缺少 Python，可用 shell 实现。
-
-### 1. 分页抓取（写入 `all_workflows.json`）
-
-```bash
-page=1
-echo "[]" > all_workflows.json
-
-while :; do
-  resp=$(curl -s -X GET \
-    "$BASE/api/v1/lab/workflow/owner/list?page=$page&page_size=1000&lab_uuid=$lab_uuid" \
-    -H "$AUTH")
-
-  page_data=$(echo "$resp" | jq -c '.data.data // []')
-  jq -c --argjson p "$page_data" '. + $p' all_workflows.json > _tmp.json && mv _tmp.json all_workflows.json
-
-  has_more=$(echo "$resp" | jq -r '.data.has_more')
-  [ "$has_more" != "true" ] && break
-  page=$((page + 1))
-done
-
-echo "Total: $(jq 'length' all_workflows.json)"
-```
-
-### 2. 汇总所有标签（含出现次数）
-
-```bash
-jq '[.[].tags // [] | .[]] | group_by(.) | map({tag: .[0], count: length}) | sort_by(-.count)' \
-  all_workflows.json
-```
-
-### 3. 按标签筛选
-
-```bash
-# ANY：包含任一指定标签
-jq --argjson want '["synthesis","organic"]' \
-  '[.[] | select((.tags // []) | any(. as $t | $want | index($t)))]' \
-  all_workflows.json
-
-# ALL：同时包含所有指定标签
-jq --argjson want '["synthesis","organic"]' \
-  '[.[] | select(($want | all(. as $w | (.tags // []) | index($w))))]' \
-  all_workflows.json
-```
-
----
-
-## 筛选策略
-
-agent 拿到用户的「领域 + 场景」自然语言描述时，按如下顺序选择 tag：
-
-1. **优先用户显式指定的 tags**：若用户明确给出标签词，直接精确匹配。
-2. **从 all_tags 中做语义映射**：若用户描述是自然语言（如"有机合成、柱层析"），在 all_tags 中找语义相关项（如 `synthesis`、`organic`、`chromatography`）。必要时展示候选 tag 让用户确认。
-3. **模式选择**：
-   - 默认 `any`（更多召回），给出 tag 集合的并集匹配
-   - 用户强调"必须同时满足"时用 `all`
-4. **空结果兜底**：如果筛选为空，放宽条件（去掉最稀有 tag、切换 any 模式），并提醒用户。
-
----
-
-## 引导到明确的 Protocol
-
-筛选完成后，**最终目标是让用户确认一个具体的 workflow_uuid**，而不是停留在"一堆候选"上。按结果数量采取不同策略：
-
-| 结果数量  | 策略                                                                                                                               |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| 0 条      | 放宽筛选（去掉最稀有 tag → 切换 any 模式 → 去掉 `--published-only`）。仍为空则提示换关键词，或列出 `all_tags` 让用户重新选。 |
-| 1 条      | 直接确认："找到唯一匹配：`<name>` (uuid `<uuid>`)，是否用它？"用户确认后记录 `workflow_uuid`。                               |
-| 2–10 条  | 编号列表展示，让用户选编号。每项给出 name、tags、description 摘要、published 状态。                                                |
-| 10–30 条 | 先展示 tag 分布帮助用户进一步收紧：列出匹配结果中最常见的子标签，提示"加一个 tag 可将结果缩小到 N 条"。                            |
-| >30 条    | 强制要求用户补充条件：仅 published、指定具体 tag 组合、或按名称关键词过滤。                                                        |
-
-**确认 workflow 后**：
-
-1. 将 `workflow_uuid` 写入 session state
-2. 提示用户下一步可用的 skill：
-   - 提交实验 → 引导到“与其他 Skill 的协作”
-   - 查看 workflow 详细节点 → `GET /api/v1/lab/workflow/template/detail/<workflow_uuid>`
-3. 若用户想换一个，回到筛选步骤。
-
----
-
-## 展示结果
-
-推荐格式（表格 + 汇总统计）：
-
-```
-共 150 个工作流，其中 32 个匹配筛选条件 [tags: synthesis OR organic]
-
-| UUID (短) | 名称                     | Tags                         | 已发布 |
-|-----------|--------------------------|------------------------------|--------|
-| e0436638  | Synthesis v2             | synthesis, organic           | ✓      |
-| 5b60dbb8  | Grignard Protocol        | synthesis, organometallic    | ✓      |
-| ...       | ...                      | ...                          | ...    |
-
-所有可用标签（按频次）：
-  synthesis (12), organic (8), analysis (5), purification (4), ...
-```
-
-如果用户下一步想执行某工作流 → 引导到“与其他 Skill 的协作”。
-
----
-
-## 常见问题
-
-### Q: tags 为 null 的工作流要不要展示？
-
-默认**不展示**在筛选结果中（因为无法按 tag 匹配）。但在 `--summary-only` 或无筛选条件时，这些工作流仍会计入总数，并在输出中单独列出"未打标签"计数。
-
-### Q: 如何按名称/描述做模糊匹配？
-
-脚本未内置，但可在 jq 中组合：
-
-```bash
-jq '[.[] | select((.name + " " + (.description // "")) | test("organic"; "i"))]' all_workflows.json
-```
-
-### Q: `page_size=1000` 是否会被服务端限制？
-
-接口通常允许最大 1000；如果返回量少于 1000 且 `has_more=false`，说明已到末页。极端情况下若服务端返回错误，可降到 200 或 500 再试。
-
-### Q: 工作流数量极大（>10k）怎么办？
-
-1. 先跑 `--summary-only` 了解 tag 分布
-2. 提示用户先限定 `--published-only` 或指定 tag
-3. 考虑将 `all_workflows.json` 缓存到本地，下次直接复用
-
----
-
-## 与其他 Skill 的协作
-
-- 正常情况下，找到 workflow 之后可以直接用它提交实验（启动工作流的 api 端点 POST $BASE/api/v1/lab/workflow/<workflow_uuid>/run，不用别的 skill）
-- **仅当需要进行多次实验时，使用 batch-submit-experiment** — 筛选到目标工作流后，`workflow_uuid` 直接用于实验提交
-
-## 脚本依赖
-
-`scripts/filter_workflows.py` 仅使用 Python 标准库（`urllib`、`json`、`argparse`），无需额外安装。

.cursor/skills/filter-workflow-by-tags/scripts/filter_workflows.py

@@ -1,191 +0,0 @@
-#!/usr/bin/env python3
-"""分页拉取 Uni-Lab 工作流列表，汇总 tags 并按 tag 筛选。
-
-使用示例:
-    python filter_workflows.py \
-        --auth <base64token> \
-        --base https://leap-lab.test.bohrium.com \
-        --lab-uuid a9059772-... \
-        --tags synthesis organic --mode any
-
-仅依赖 Python 标准库。
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-from collections import Counter
-
-
-def fetch_all_workflows(base: str, auth_token: str, lab_uuid: str, page_size: int = 1000) -> list[dict]:
-    """分页拉取所有 owner 工作流，直到 has_more=false。"""
-    workflows: list[dict] = []
-    page = 1
-    while True:
-        query = urllib.parse.urlencode(
-            {"page": page, "page_size": page_size, "lab_uuid": lab_uuid}
-        )
-        url = f"{base.rstrip('/')}/api/v1/lab/workflow/owner/list?{query}"
-        req = urllib.request.Request(
-            url,
-            headers={
-                "Authorization": f"Lab {auth_token}",
-                "Accept": "application/json",
-            },
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=30) as resp:
-                payload = json.loads(resp.read().decode("utf-8"))
-        except urllib.error.HTTPError as e:
-            sys.exit(f"[ERROR] HTTP {e.code} on page {page}: {e.read().decode('utf-8', 'ignore')}")
-        except urllib.error.URLError as e:
-            sys.exit(f"[ERROR] URL error on page {page}: {e.reason}")
-
-        if payload.get("code") != 0:
-            sys.exit(f"[ERROR] API returned non-zero code: {payload}")
-
-        data = payload.get("data") or {}
-        page_items = data.get("data") or []
-        workflows.extend(page_items)
-
-        if not data.get("has_more"):
-            break
-        page += 1
-        # 防御性兜底，避免接口异常导致无限循环
-        if page > 1000:
-            print(f"[WARN] page count exceeded 1000, stopping early", file=sys.stderr)
-            break
-
-    return workflows
-
-
-def aggregate_tags(workflows: list[dict]) -> tuple[list[str], dict[str, int], int]:
-    """返回 (sorted_tags, tag_counts, untagged_count)。"""
-    counter: Counter[str] = Counter()
-    untagged = 0
-    for wf in workflows:
-        tags = wf.get("tags")
-        if not tags:
-            untagged += 1
-            continue
-        for t in tags:
-            if isinstance(t, str) and t.strip():
-                counter[t.strip()] += 1
-    return sorted(counter.keys()), dict(counter), untagged
-
-
-def filter_workflows(
-    workflows: list[dict],
-    want_tags: list[str],
-    mode: str,
-    published_only: bool,
-) -> list[dict]:
-    """按 tag 筛选。mode 取值 any / all。"""
-    want_set = {t.strip() for t in want_tags if t.strip()}
-    out: list[dict] = []
-    for wf in workflows:
-        if published_only and not wf.get("published"):
-            continue
-        if not want_set:
-            out.append(wf)
-            continue
-        tags = wf.get("tags") or []
-        tag_set = {t for t in tags if isinstance(t, str)}
-        if mode == "all":
-            if want_set.issubset(tag_set):
-                out.append(wf)
-        else:  # any
-            if want_set & tag_set:
-                out.append(wf)
-    return out
-
-
-def project_workflow(wf: dict) -> dict:
-    """精简输出字段。"""
-    return {
-        "uuid": wf.get("uuid"),
-        "name": wf.get("name"),
-        "description": wf.get("description", ""),
-        "tags": wf.get("tags") or [],
-        "published": bool(wf.get("published")),
-        "user_id": wf.get("user_id"),
-    }
-
-
-def parse_args() -> argparse.Namespace:
-    p = argparse.ArgumentParser(description="Fetch & filter Uni-Lab workflows by tags.")
-    p.add_argument("--auth", required=True, help="Base64 token (the part after `Lab `).")
-    p.add_argument("--base", required=True, help="Base URL, e.g. https://leap-lab.test.bohrium.com")
-    p.add_argument("--lab-uuid", required=True, help="Lab UUID.")
-    p.add_argument("--tags", nargs="*", default=[], help="Tags to filter by (space separated).")
-    p.add_argument(
-        "--mode",
-        choices=["any", "all"],
-        default="any",
-        help="any: workflow contains at least one tag; all: workflow contains every tag.",
-    )
-    p.add_argument("--published-only", action="store_true", help="Only include published workflows.")
-    p.add_argument("--page-size", type=int, default=1000, help="Page size, default 1000.")
-    p.add_argument(
-        "--summary-only",
-        action="store_true",
-        help="Print tag summary without applying filter (still fetches everything).",
-    )
-    p.add_argument("--output", help="Write JSON result to this path. If omitted, print to stdout.")
-    return p.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    workflows = fetch_all_workflows(
-        base=args.base,
-        auth_token=args.auth,
-        lab_uuid=args.lab_uuid,
-        page_size=args.page_size,
-    )
-    sorted_tags, tag_counts, untagged = aggregate_tags(workflows)
-
-    if args.summary_only:
-        result = {
-            "total_workflows": len(workflows),
-            "untagged_count": untagged,
-            "tag_counts": tag_counts,
-            "all_tags": sorted_tags,
-        }
-    else:
-        filtered = filter_workflows(
-            workflows,
-            want_tags=args.tags,
-            mode=args.mode,
-            published_only=args.published_only,
-        )
-        result = {
-            "total_workflows": len(workflows),
-            "untagged_count": untagged,
-            "tag_counts": tag_counts,
-            "all_tags": sorted_tags,
-            "filter": {
-                "tags": args.tags,
-                "mode": args.mode,
-                "published_only": args.published_only,
-            },
-            "matched_count": len(filtered),
-            "filtered_workflows": [project_workflow(wf) for wf in filtered],
-        }
-
-    payload = json.dumps(result, ensure_ascii=False, indent=2)
-    if args.output:
-        with open(args.output, "w", encoding="utf-8") as f:
-            f.write(payload)
-        print(f"Wrote {len(workflows)} workflows summary → {args.output}", file=sys.stderr)
-    else:
-        print(payload)
-
-
-if __name__ == "__main__":
-    main()

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

@@ -10,8 +10,7 @@ description: Operate Virtual Workbench via REST API — prepare materials, move
 - **device_id**: `virtual_workbench`
 - **Python 源码**: `unilabos/devices/virtual/workbench.py`
 - **设备类**: `VirtualWorkbench`
-- **当前纳入动作**: 5 个（`auto-prepare_materials`, `auto-move_to_heating_station`, `auto-start_heating`, `auto-move_to_output`, `transfer`）
-- **暂跳过动作**: `manual_confirm`、扣电测试 `test`（需要启用时先从最新注册表重新提取 schema）
+- **动作数**: 6（`auto-prepare_materials`, `auto-move_to_heating_station`, `auto-start_heating`, `auto-move_to_output`, `transfer`, `manual_confirm`）
 - **设备描述**: 模拟工作台，包含 1 个机械臂（每次操作 2s，独占锁）和 3 个加热台（每次加热 60s，可并行）
 
 ### 典型工作流程
@@ -152,8 +151,7 @@ curl -s -X POST "$BASE/api/v1/lab/mcp/run/action" \
 | `auto-start_heating` | `UniLabJsonCommand` |
 | `auto-move_to_output` | `UniLabJsonCommand` |
 | `transfer` | `UniLabJsonCommandAsync` |
-
-> `manual_confirm` 和扣电测试 `test` 当前不纳入本 skill 的推荐操作范围；不要基于历史 JSON 直接调用，需先重新生成并校验 schema。
+| `manual_confirm` | `UniLabJsonCommand` |
 
 ### 10. 查询任务状态
 
@@ -227,9 +225,11 @@ curl -s -X PUT "$BASE/api/v1/edge/material/node" \
 | `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 字段**，参数为纯数值/整数。
-> `manual_confirm` 先跳过，不维护其 Slot 字段表。
 
 ---
 
@@ -270,13 +270,3 @@ prepare_materials (count=5)
 ```
 
 创建节点时，`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`。
-
-`start_heating` 完成后还需要继续连接到 `move_to_output`，否则加热完成的物料不会移出加热台：
-
-| source action | source handle | target action | target handle | 传递参数 |
-| ------------- | ------------- | ------------- | ------------- | -------- |
-| `auto-prepare_materials` | `channel_N` | `auto-move_to_heating_station` | `material_input` | `material_number` |
-| `auto-move_to_heating_station` | `heating_station_output` | `auto-start_heating` | `station_id_input` | `station_id` |
-| `auto-move_to_heating_station` | `material_number_output` | `auto-start_heating` | `material_number_input` | `material_number` |
-| `auto-start_heating` | `heating_done_station` | `auto-move_to_output` | `output_station_input` | `station_id` |
-| `auto-start_heating` | `heating_done_material` | `auto-move_to_output` | `output_material_input` | `material_number` |

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

@@ -1,8 +1,6 @@
 # Action Index — virtual_workbench
 
-当前纳入 5 个动作，按功能分类。每个动作的完整 JSON Schema 在 `actions/<name>.json`。
-
-暂跳过：`manual_confirm`、扣电测试 `test`。这两个动作需要启用时，先从最新 `req_device_registry_upload.json` 重新提取 schema 并校验参数。
+6 个动作，按功能分类。每个动作的完整 JSON Schema 在 `actions/<name>.json`。
 
 ---
 
@@ -62,18 +60,17 @@
 
 ---
 
-## 暂跳过动作
+## 人工确认
 
 ### `manual_confirm`
 
-创建人工确认节点，等待用户手动确认后继续（含物料转移上下文）。当前先不纳入推荐操作范围。
+创建人工确认节点，等待用户手动确认后继续（含物料转移上下文）
 
 - **action_type**: `UniLabJsonCommand`
 - **Schema**: [`actions/manual_confirm.json`](actions/manual_confirm.json)
-- **状态**: 暂跳过。源码参数已包含扣电测试相关字段，历史 JSON 可能过期；需要启用时重新提取 schema。
-
-### `test`
-
-启动扣电测试。当前先不纳入本 skill。
-
-- **状态**: 暂跳过。需要启用时从注册表生成 `actions/test.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` 类型

.cursorignore

@@ -0,0 +1,188 @@
+# ============================================================
+# 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
+
+# ==================== 其他 ====================
+# 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/workflows/ci-check.yml

@@ -25,7 +25,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Miniforge
-        uses: conda-incubator/setup-miniconda@v4
+        uses: conda-incubator/setup-miniconda@v3
         with:
           miniforge-version: latest
           use-mamba: true
@@ -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:
@@ -43,7 +29,7 @@ jobs:
             platform: linux-64
             env_file: unilabos-linux-64.yaml
             script_ext: sh
-          - os: macos-15-intel # Intel x86_64
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
             env_file: unilabos-osx-64.yaml
             script_ext: sh
@@ -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,17 +65,17 @@ 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)
         if: steps.should_build.outputs.should_build == 'true'
-        uses: conda-incubator/setup-miniconda@v4
+        uses: conda-incubator/setup-miniconda@v3
         with:
           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

@@ -51,12 +51,12 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Miniforge (with mamba)
-        uses: conda-incubator/setup-miniconda@v4
+        uses: conda-incubator/setup-miniconda@v3
         with:
           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: |
@@ -84,7 +84,7 @@ jobs:
 
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@v5
         if: |
           github.event.workflow_run.head_branch == 'main' ||
           (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
@@ -105,7 +105,7 @@ jobs:
           test -f docs/_build/html/index.html && echo "✓ index.html exists" || echo "✗ index.html missing"
 
       - name: Upload build artifacts
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@v4
         if: |
           github.event.workflow_run.head_branch == 'main' ||
           (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
@@ -125,4 +125,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@v4

.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:
@@ -63,7 +60,7 @@ jobs:
           - os: ubuntu-latest
             platform: linux-64
             env_file: unilabos-linux-64.yaml
-          - os: macos-15-intel # Intel x86_64
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
             env_file: unilabos-osx-64.yaml
           - os: macos-latest # ARM64
@@ -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,14 +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@v4
+        uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-version: latest
-          use-mamba: true
-          python-version: '3.11.14'
-          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
@@ -115,22 +110,24 @@ jobs:
       - name: Install rattler-build and anaconda-client
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          mamba install -n build-env --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'
         run: |
           conda info
-          conda list -n build-env | grep -E "(rattler-build|anaconda-client)"
-          conda run -n build-env rattler-build --version
-          conda run -n build-env anaconda --version
+          conda list | grep -E "(rattler-build|anaconda-client)"
           echo "Platform: ${{ matrix.platform }}"
           echo "OS: ${{ matrix.os }}"
 
       - name: Build conda package
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          conda run -n build-env rattler-build build -r ./recipes/msgs/recipe.yaml --target-platform ${{ matrix.platform }} -c robostack -c robostack-staging -c conda-forge
+          if [[ "${{ matrix.platform }}" == "osx-arm64" ]]; then
+            rattler-build build -r ./recipes/msgs/recipe.yaml -c robostack -c robostack-staging -c conda-forge
+          else
+            rattler-build build -r ./recipes/msgs/recipe.yaml -c robostack -c robostack-staging -c conda-forge
+          fi
 
       - name: List built packages
         if: steps.should_build.outputs.should_build == 'true'
@@ -160,15 +157,9 @@ 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..."
-            conda run -n build-env anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
           done

.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,37 +33,37 @@ 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:
         include:
           - os: ubuntu-latest
             platform: linux-64
-          - os: macos-15-intel # Intel x86_64
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
           - os: macos-latest # ARM64
             platform: osx-arm64
@@ -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,14 +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@v4
+        uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-version: latest
-          use-mamba: true
-          python-version: '3.11.14'
-          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
@@ -108,22 +110,20 @@ jobs:
       - name: Install rattler-build and anaconda-client
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          mamba install -n build-env --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'
         run: |
           conda info
-          conda list -n build-env | grep -E "(rattler-build|anaconda-client)"
-          conda run -n build-env rattler-build --version
-          conda run -n build-env anaconda --version
+          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,19 +131,14 @@ jobs:
         if: steps.should_build.outputs.should_build == 'true'
         run: |
           echo "Building unilabos-env (conda environment dependencies)..."
-          conda run -n build-env rattler-build build -r .conda/environment/recipe.yaml --target-platform ${{ matrix.platform }} -c uni-lab -c robostack-staging -c conda-forge
+          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
-            conda run -n build-env anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
           done
 
       - name: Build unilabos (with pip package)
@@ -151,40 +146,33 @@ jobs:
         run: |
           echo "Building unilabos package..."
           # 如果已上传到 Anaconda，从 uni-lab channel 获取 unilabos-env；否则从本地 output 获取
-          conda run -n build-env rattler-build build -r .conda/base/recipe.yaml --target-platform ${{ matrix.platform }} -c uni-lab -c robostack-staging -c conda-forge --channel ./output
+          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
-            conda run -n build-env anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
           done
 
       - 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 }}..."
-          conda run -n build-env rattler-build build -r .conda/full/recipe.yaml --target-platform ${{ matrix.platform }} -c uni-lab -c robostack-staging -c conda-forge --channel ./output
+          rattler-build build -r .conda/full/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge --channel ./output
 
       - 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: |
           echo "Uploading unilabos-full to uni-lab organization..."
           for package in $(find ./output -name "unilabos-full*.conda"); do
-            conda run -n build-env anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
           done
 
       - name: List built packages

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_PLC.md

@@ -1,611 +0,0 @@
-# PLC 通信标准与设备驱动编写指南（基于 AI4M 工站）
-
-> 本文档以 `unilabos/devices/workstation/AI4M`（水凝胶检测工站）为参考实现，
-> 介绍如何将 PLC 控制的实验设备接入 Uni-Lab-OS：包含通信协议选型、节点表标准、
-> 通信基类、设备驱动、Registry 配置以及调试方法。
->
-> 阅读对象：负责现场调试与设备接入的同学。
-
----
-
-## 0. 总览：一台 PLC 设备从硬件到云端的链路
-
-```
-       PLC（西门子 / 倍福 / 三菱 / 汇川 / 国产 PLC ...）
-                   ▲
-                   │  各家 PLC 私有协议（S7 / Modbus / EtherCAT ...）
-                   │
-        ┌──────────┴──────────┐
-        │  OPC UA Server      │  ← 统一在 PLC 侧或独立网关上配置
-        │  （内置或 KEPServer）│
-        └──────────┬──────────┘
-                   │  OPC UA over TCP（标准协议）
-                   │
-        ┌──────────┴──────────┐
-        │  Uni-Lab 设备驱动    │  ← 本教程主体
-        │  AI4MDevice         │
-        │  ├─ base_opcua_client.py  通信基类
-        │  ├─ opcua_nodes_*.csv     节点表（标准）
-        │  └─ AI4M.py               动作函数
-        └──────────┬──────────┘
-                   │  ROS2 Action / 云端 HTTP
-                   ▼
-              实验记录本 / 云端调度
-```
-
-**统一约定**：所有 PLC 设备**只暴露 OPC UA 接口**给 Uni-Lab，PC 端不直接处理 S7 / Modbus 等底层协议。
-这是 Uni-Lab 在工站类设备上的 PLC 通信标准。
-
----
-
-## 1. 为什么选 OPC UA 作为标准？
-
-| 维度 | 自研 TCP/串口协议 | Modbus | **OPC UA** |
-|---|---|---|---|
-| 厂家无关 | ✗ | 部分 | **✓** |
-| 自带类型系统 | ✗ | ✗（裸寄存器） | **✓（Boolean/Int16/Float...）** |
-| 命名空间 / 节点树 | ✗ | ✗（地址=魔数） | **✓（带名字、可分组）** |
-| 订阅推送 | ✗ | ✗ | **✓（DataChange Notification）** |
-| 鉴权 / 加密 | 自己造 | ✗ | **✓** |
-| 与 PLC 工程师沟通成本 | 高 | 中 | **低（按变量名沟通）** |
-
-实际接入时，PLC 工程师只需要在 PLC 侧把约定的"上位通讯变量"暴露到 OPC UA Server，
-我们在 PC 侧就能用 `节点名 + 数据类型` 直接读写，不用管底层是 S7 还是 Modbus。
-
----
-
-## 2. 节点表标准：`opcua_nodes_xxx.csv`
-
-PLC 侧暴露的所有变量统一**用一张 CSV 表**描述，这是 PC 端和 PLC 端**唯一的接口契约**。
-位置示例：`unilabos/devices/workstation/AI4M/opcua_nodes_AI4M.csv`。
-
-### 2.1 列定义
-
-| 列名 | 是否必填 | 说明 |
-|---|---|---|
-| `Name` | ✅ | 节点名（PLC 工程师在 PLC 项目中真实使用的变量名，通常是中文/原始名） |
-| `EnglishName` | 推荐 | 英文别名，**PC 端代码全部用这个名字**调用 |
-| `NodeType` | ✅ | `VARIABLE`（变量）或 `METHOD`（方法），AI4M 全部用变量 |
-| `DataType` | ✅ | `BOOLEAN` / `INT16` / `INT32` / `FLOAT` / `DOUBLE` / `STRING` ... |
-| `NodeLanguage` | 推荐 | `Chinese` / `English`，配合 `EnglishName` 做映射 |
-| `NodeId` | ✅ | OPC UA 标准 NodeId，格式 `ns=<namespace>;s=<string>` 或 `ns=<n>;i=<int>` |
-
-### 2.2 真实样例（节选自 `opcua_nodes_AI4M.csv`）
-
-| Name | EnglishName | NodeType | DataType | NodeLanguage | NodeId |
-|---|---|---|---|---|---|
-| 机器人空闲 | `robot_ready` | VARIABLE | BOOLEAN | Chinese | `ns=4;s=上位通讯变量\|机器人空闲` |
-| 机器人取烧杯编号 | `robot_pick_beaker_id` | VARIABLE | INT16 | Chinese | `ns=4;s=上位通讯变量\|机器人取烧杯编号` |
-| 检测1请求参数 | `station_1_request_params` | VARIABLE | BOOLEAN | Chinese | `ns=4;s=上位通讯变量\|检测1请求参数` |
-| 检测1工艺完成 | `station_1_process_complete` | VARIABLE | BOOLEAN | Chinese | `ns=4;s=上位通讯变量\|检测1工艺完成` |
-| 磁力搅拌参数设置_C[0].搅拌速度 | `mag_stirrer_c0_stir_speed` | VARIABLE | INT16 | Chinese | `ns=4;s=上位通讯变量\|磁力搅拌参数设置_C[0].搅拌速度` |
-| 报警复位 | `alarm_reset` | VARIABLE | BOOLEAN | Chinese | `ns=4;s=上位通讯变量\|报警复位` |
-
-### 2.3 设计规范（必读）
-
-1. **命名按"角色-编号-属性"分层**，便于代码批量寻址：
-   - `mag_stirrer_c{0..4}_stir_speed`（搅拌仪 0~4 的搅拌速度）
-   - `station_{1..3}_process_complete`（检测站 1~3 的完成信号）
-   - `robot_rack_pick_beaker_{1..5}_complete`（取烧杯 1~5 的完成信号）
-
-   这样在驱动里可以直接 `f"mag_stirrer_c{idx}_stir_speed"` 拼出节点名。
-
-2. **数据类型与 PLC 侧严格一致**：
-   - `BOOL` → `BOOLEAN`，`INT/WORD` → `INT16/UINT16`，`DINT` → `INT32`，`REAL` → `FLOAT`。
-   - 类型不一致会触发 `BadTypeMismatch`，写入失败。
-
-3. **NodeId 必须从 PLC 工程或 OPC UA Server 中导出**，不要自己拼。
-   常见格式：
-   - 西门子 1500：`ns=4;s=上位通讯变量|<变量名>`
-   - 倍福 TwinCAT：`ns=4;s=PLC1.MAIN.<变量名>`
-   - KEPServerEX：`ns=2;s=Channel1.Device1.<Tag>`
-
-4. **每个工站一个独立 CSV**，不要共用。
-   AI4M 中真机用 `opcua_nodes_AI4M.csv`，仿真用 `opcua_nodes_AI4M_sim.csv`。
-
----
-
-## 3. 通信基类架构
-
-文件：`unilabos/devices/workstation/AI4M/base_opcua_client.py`
-
-整个通信层分两层：
-
-```
-BaseOpcUaClient                       # 最小可用：连接 + 节点注册 + 读写 + 方法调用
-        ▲
-        │ 继承
-        │
-OpcUaClientWithSubscription           # 生产可用：+ 订阅推送 + 缓存 + 自动重连
-        ▲
-        │ 继承
-        │
-AI4MDevice                            # 业务驱动：在它之上写设备动作函数
-```
-
-### 3.1 `BaseOpcUaClient` 核心能力
-
-```python
-class BaseOpcUaClient(UniversalDriver):
-    client: Optional[Client] = None
-    _node_registry: Dict[str, OpcUaNodeBase] = {}     # name -> Variable/Method
-    _name_mapping: Dict[str, str] = {}                # 英文名 -> 中文名
-    _reverse_mapping: Dict[str, str] = {}             # 中文名 -> 英文名
-    _found_node_objects: Dict[str, Any] = {}          # 缓存 ua.Node 用于订阅
-
-    @classmethod
-    def load_csv(cls, file_path) -> Tuple[List[OpcUaNode], dict, dict]: ...
-    def register_node_list(self, node_list) -> "BaseOpcUaClient": ...
-    def use_node(self, name) -> OpcUaNodeBase: ...
-    def read_node(self, node_name: str) -> str: ...   # 返回 JSON
-    def write_node(self, json_input: str) -> str: ...
-    def call_method(self, node_name, *args) -> Tuple[Any, bool]: ...
-```
-
-它做的事情可以归纳为四步：
-
-1. **`load_csv`**：读取节点表，建立 `Name ↔ EnglishName` 双向映射。
-2. **`register_node_list`**：把节点登记进 `_variables_to_find` 待查找列表。
-3. **`_connect` → `_find_nodes`**：连上 OPC UA 后，按 `NodeId` 把每个节点解析成 `Variable` / `Method` 对象，放进 `_node_registry`。
-4. **`use_node(name)`**：业务代码取节点的唯一入口，**支持中英文混用**，找不到会自动重试一次。
-
-### 3.2 `OpcUaClientWithSubscription` 增强能力
-
-在 `BaseOpcUaClient` 基础上提供三个生产环境必备的能力：
-
-#### a) 订阅缓存（高频读零开销）
-
-```python
-def _setup_subscriptions(self):
-    self._subscription = self.client.create_subscription(
-        self._subscription_interval,    # 默认 500ms
-        SubscriptionHandler(self),
-    )
-    for node_name, node in self._node_registry.items():
-        if node.type == NodeType.VARIABLE and node.node_id:
-            handle = self._subscription.subscribe_data_change(ua_node)
-            self._subscription_handles[node_name] = handle
-```
-
-当 PLC 侧变量变化时，`datachange_notification` 回调会把新值写进 `self._node_values[name]`，
-后续 `get_node_value` 优先读缓存——**业务代码可以放心地写 `while not self.get_node_value(...): time.sleep(1)` 而不用担心 OPC UA 频繁请求**。
-
-#### b) 智能缓存的 `get_node_value`
-
-```python
-def get_node_value(self, name, use_cache=True, force_read=False):
-    # 1. 中英文名归一化
-    chinese_name = self._name_mapping.get(name, name)
-
-    # 2. force_read=True 强制透传到 OPC UA Server
-    if force_read: ...
-
-    # 3. 命中订阅推送 → 直接返回缓存
-    # 4. 命中按需读 + 未过期（cache_timeout=5s）→ 返回缓存
-    # 5. 否则发起 read 并更新缓存
-```
-
-#### c) 连接监控 + 自动重连
-
-后台线程每 30s 调一次 `client.get_namespace_array()` 探活，断线则自动 `disconnect → connect → 重新订阅`，最多重试 5 次。
-
-### 3.3 数据类型 / 节点类型
-
-`unilabos/device_comms/opcua_client/node/uniopcua.py`：
-
-```python
-class DataType(Enum):
-    BOOLEAN = VariantType.Boolean
-    INT16   = VariantType.Int16
-    INT32   = VariantType.Int32
-    FLOAT   = VariantType.Float
-    STRING  = VariantType.String
-    # ...
-
-class NodeType(Enum):
-    VARIABLE = NodeClass.Variable
-    METHOD   = NodeClass.Method
-    OBJECT   = NodeClass.Object
-```
-
-`Variable.write()` 内部会按 `DataType` 做强制类型转换，
-所以 CSV 里的 `DataType` 列就是"PC 端转换写入值的类型说明书"。
-
----
-
-## 4. 编写设备驱动：以 `AI4MDevice` 为例
-
-文件：`unilabos/devices/workstation/AI4M/AI4M.py`
-
-### 4.1 继承通信基类，最小骨架
-
-```python
-from typing import Optional
-from unilabos.devices.workstation.AI4M.base_opcua_client import OpcUaClientWithSubscription
-
-class AI4MDevice(OpcUaClientWithSubscription):
-    def __init__(
-        self,
-        url: str,                              # opc.tcp://192.168.1.10:4840
-        deck: Optional[AI4M_deck] = None,      # 物料台面（资源树）
-        csv_path: str = None,                  # 节点表 CSV
-        username: str = None,
-        password: str = None,
-        use_subscription: bool = True,
-        cache_timeout: float = 5.0,
-        subscription_interval: int = 500,
-        *args, **kwargs,
-    ):
-        super().__init__(
-            url=url, username=username, password=password,
-            use_subscription=use_subscription,
-            cache_timeout=cache_timeout,
-            subscription_interval=subscription_interval,
-            *args, **kwargs,
-        )
-
-        # 物料台面初始化（见教程 4. 物料系统）
-        self.deck = deck or AI4M_deck(setup=True)
-        self._robot_lock = threading.Lock()
-
-        # 关键：加载节点表
-        if csv_path:
-            self.load_nodes_from_csv(csv_path)
-```
-
-`load_nodes_from_csv` 会一次性完成：解析 CSV → 注册节点 → 解析 NodeId → 建立订阅，
-**之后整个驱动都通过 `self.get_node_value(name)` / `self.set_node_value(name, value)` 操作 PLC**。
-
-### 4.2 PLC 通信的核心模式：握手协议（Handshake）
-
-PLC 编程的本质是"扫描周期 + 状态机"，PC 端**绝对不能用 fire-and-forget 的方式发指令**。
-和 PLC 配合的标准模式是 **"PC 写指令 → PC 等待 PLC 回执 → PC 复位指令"**。
-
-AI4M 中所有 `trigger_*` 函数都遵循以下三种握手范式之一：
-
-#### 范式 A：脉冲触发 + 完成信号（最常用）
-
-```python
-def trigger_init(self) -> dict:
-    # ① 复位上一轮残留
-    self.set_node_value("alarm_reset", True); time.sleep(1.0)
-    self.set_node_value("alarm_reset", False)
-    self.set_node_value("manual_auto_switch", False)
-
-    # ② 等待 PLC 退出自动模式
-    while self.get_node_value("auto_mode"):
-        time.sleep(1.0)
-
-    # ③ 发起初始化脉冲（True → False）
-    self.set_node_value("initialize", True); time.sleep(1.0)
-    self.set_node_value("initialize", False)
-
-    # ④ 等待 PLC 给出完成信号
-    while not self.get_node_value("init finished"):
-        time.sleep(1.0)
-
-    return {"message": "设备初始化完成"}
-```
-
-要点：
-- **"PC 写一个 BOOL 拉高再拉低"** 模拟脉冲，PLC 用上升沿触发动作。
-- **`get_node_value` 要在 while 循环里轮询**，配合订阅缓存基本无压力。
-- **每个动作必须有"开始"和"完成"两个独立的 BOOL 节点**，不能复用。
-
-#### 范式 B：参数下发 + 请求/已执行/完成 三步握手（带数据的工艺）
-
-```python
-def trigger_station_process(self, station_id: int, mag_stir_speed: int, ...):
-    request_node        = f"station_{station_id}_request_params"
-    params_received_node = f"station_{station_id}_params_received"
-    start_node          = f"station_{station_id}_start"
-    complete_node       = f"station_{station_id}_process_complete"
-
-    # ① PC 复位三个状态位（避免上一轮影响）
-    self._reset_station_process_flags(station_id)
-
-    # ② 等 PLC 主动请求参数（PLC 准备好了才接收）
-    while not self.get_node_value(request_node):
-        time.sleep(1.0)
-
-    # ③ PC 下发参数（注意：PLC 内部数组是 0-based，PC 暴露给用户是 1-based）
-    station_idx = station_id - 1
-    self.set_node_value(f"mag_stirrer_c{station_idx}_stir_speed", mag_stir_speed)
-    self.set_node_value(f"mag_stirrer_c{station_idx}_heat_temp",  mag_stir_heat_temp)
-    self.set_node_value(f"mag_stirrer_c{station_idx}_time_set",   mag_stir_time_set)
-    self.set_node_value(f"syringe_pump_{station_idx}_abs_position_set", syringe_pump_abs_pos)
-
-    # ④ PC 通知 PLC "参数已就绪"，等 PLC 回复"已执行"
-    self.set_node_value(start_node, True)
-    while not self.get_node_value(params_received_node):
-        time.sleep(1.0)
-
-    # ⑤ 等 PLC 完成整个工艺
-    while not self.get_node_value(complete_node):
-        time.sleep(5.0)
-
-    self.set_node_value(start_node, False)   # 复位，方便下一轮
-    return {"station_id": station_id, "message": "..."}
-```
-
-四个状态位的语义：
-
-| 信号 | 方向 | 含义 |
-|---|---|---|
-| `station_X_request_params` | **PLC → PC** | "我准备好了，把参数给我" |
-| `station_X_start` | **PC → PLC** | "参数我已经写好了，开干" |
-| `station_X_params_received` | **PLC → PC** | "参数我已经吃下了" |
-| `station_X_process_complete` | **PLC → PC** | "工艺已经做完" |
-
-**这是 PLC 通信教科书级别的标准范式**，所有带数据下发的动作都建议照抄。
-
-#### 范式 C：编号下发 + 编号对应的完成信号（多目标互锁）
-
-```python
-def trigger_robot_pick_beaker(self, pick_beaker_id: int, place_station_id: int = None, ...):
-    # ① 等机器人空闲（互锁）
-    while not self.get_node_value("robot_ready"):
-        time.sleep(1.0)
-
-    # ② 阶段一：下发"取哪一杯"编号 + 等"取这一杯完成"
-    pick_complete_node  = f"robot_rack_pick_beaker_{pick_beaker_id}_complete"
-    self.set_node_value("robot_pick_beaker_id", pick_beaker_id)
-    while not self.get_node_value(pick_complete_node):
-        time.sleep(1.0)
-
-    # ③ 阶段二：下发"放到哪个工站"编号 + 等"放完成"
-    place_complete_node = f"robot_place_station_{place_station_id}_complete"
-    self._reset_station_process_flags(place_station_id)
-    self.set_node_value("robot_place_station_id", place_station_id)
-    while not self.get_node_value(place_complete_node):
-        time.sleep(1.0)
-```
-
-要点：
-- **同一个动作的多个目标用"编号变量 + 编号对应的完成信号"实现**，不要每个目标都开一个开始位。
-- **配合 Python 端 `threading.Lock()` 做软互锁**，避免多个线程争抢机器人。
-- **每个阶段有独立的完成信号**，串行等待，不能合并。
-
-### 4.3 一些容易踩坑的细节
-
-1. **节点名映射**
-   `set_node_value("alarm_reset", True)` 实际写入的是 CSV 中文名 `报警复位`，
-   `get_node_value` 同理。**业务代码全部用 EnglishName**，不要直接用中文。
-
-2. **PLC 数组索引和 PC 不一致**
-   AI4M 里 PC 暴露 `station_id ∈ {1, 2, 3}`，但 PLC 内部数组是 `C[0..2]`，
-   驱动里要做 `station_idx = station_id - 1`，**这种映射只在驱动层做一次**，
-   不要让上层（registry / 实验记录本）感知。
-
-3. **订阅模式下 BOOL 节点的边沿同步**
-   订阅有 ~500ms 延迟。如果你刚 `set_node_value(x, True)` 就立刻 `get_node_value(x)`，
-   读到的可能还是 `False`（订阅还没推回来）。
-   解决方案：**写完后用 `force_read=True` 透传一次** 或加一段 `time.sleep`。
-
-4. **永远不要忘记复位**
-   `start` 拉 True 后必须有地方拉回 False，否则下一轮 PLC 上升沿不触发。
-   AI4M 在 `_reset_station_process_flags` 中统一做：
-
-   ```python
-   def _reset_station_process_flags(self, station_id: int) -> None:
-       self.set_node_value(f"station_{station_id}_process_complete", False)
-       self.set_node_value(f"station_{station_id}_start", False)
-       self.set_node_value(f"station_{station_id}_params_received", False)
-   ```
-
-5. **耗时长的等待 sleep 加大**
-   工艺等待用 `time.sleep(5.0)`，机器人等待用 `time.sleep(1.0)`，初始化等待 `time.sleep(1.0)`，
-   不要全部用 0.1s 轮询，会把日志刷爆。
-
----
-
-## 5. 把驱动接到 Uni-Lab：Registry + Graph
-
-### 5.1 Registry YAML（动作 schema）
-
-文件：`unilabos/registry/devices/AI4M_station.yaml`
-
-```yaml
-AI4M_station:
-  category: [AI4M_station]
-  class:
-    module: unilabos.devices.workstation.AI4M.AI4M:AI4MDevice    # ← 入口类
-    type: python
-    action_value_mappings:
-      auto-trigger_init:
-        schema:
-          description: 设备初始化...
-          properties:
-            goal:    { properties: {}, required: [], type: object }
-            result:
-              properties: { message: { type: string } }
-              required: [message]
-              type: object
-          type: object
-        type: UniLabJsonCommand
-
-      auto-trigger_station_process:
-        always_free: true
-        schema:
-          description: 执行检测工艺流程
-          properties:
-            goal:
-              properties:
-                station_id:                   { type: integer, description: 检测编号 1-3 }
-                mag_stir_stir_speed:          { type: integer }
-                mag_stir_heat_temp:           { type: integer }
-                mag_stir_time_set:            { type: integer }
-                syringe_pump_abs_position_set:{ type: integer }
-              required: [station_id, mag_stir_stir_speed, mag_stir_heat_temp,
-                         mag_stir_time_set, syringe_pump_abs_position_set]
-              type: object
-            result: { ... }
-        type: UniLabJsonCommand
-
-  init_param_schema:
-    config:
-      type: object
-      required: [url]
-      properties:
-        url:                   { type: string,  description: OPC UA 服务器地址 }
-        csv_path:              { type: string,  description: 节点配置 CSV 路径 }
-        deck:                  { type: string,  description: 资源树配置 }
-        username:              { type: string }
-        password:              { type: string }
-        use_subscription:      { type: boolean, default: true }
-        cache_timeout:         { type: number,  default: 5.0 }
-        subscription_interval: { type: integer, default: 500 }
-```
-
-规则总结：
-- `class.module` 指向驱动类（`module:ClassName`）。
-- `action_value_mappings` 中的 key 形如 `auto-<方法名>`，对应驱动里的同名 Python 方法。
-- `schema.goal` 自动转成 ROS2 Action 的 goal 消息，`schema.result` 转 result。
-- `init_param_schema.config` 对应 `__init__` 的入参，**所有需要现场改的参数都要列出来**（最重要的就是 `url` 和 `csv_path`）。
-- `always_free: true` 表示该动作不占用工站独占锁（多检测站可并发执行）。
-
-### 5.2 Graph JSON（实例化）
-
-文件：`unilabos/devices/workstation/AI4M/AI4M.json`
-
-```json
-{
-  "nodes": [
-    {
-      "id": "AI4M_station",
-      "name": "AI4M_station",
-      "type": "device",
-      "class": "AI4M_station",
-      "children": ["AI4M_deck"],
-      "parent": null,
-      "config": {
-        "url": "opc.tcp://192.168.1.10:4840",
-        "csv_path": "opcua_nodes_AI4M.csv",
-        "deck": {
-          "data": {
-            "_resource_child_name": "AI4M_deck",
-            "_resource_type": "unilabos.devices.workstation.AI4M.decks:AI4M_deck"
-          }
-        }
-      }
-    },
-    {
-      "id": "AI4M_deck",
-      "type": "deck",
-      "class": "AI4M_deck",
-      "parent": "AI4M_station",
-      "config": { "type": "AI4M_deck" }
-    }
-  ]
-}
-```
-
-要点：
-- `class` 必须和 Registry YAML 的顶层 key 完全一致（`AI4M_station`）。
-- `config` 字段**逐字传给驱动 `__init__`**，所以 Graph JSON = "现场参数表"。
-- 多套相同设备时拷贝一份，把 `id` / `url` 改掉即可（参考 `AI4M002_station`）。
-
-### 5.3 启动命令（来自 `start.md`）
-
-```cmd
-# 真机
-python unilabos/app/main.py -g unilabos/devices/workstation/AI4M/AI4M.json `
-  --ak <ak> --sk <sk> --upload_registry --addr <api_url> --disable_browser
-
-# 仿真（KEPServerEX 跑在本机 49320 端口）
-python unilabos/app/main.py -g unilabos/devices/workstation/AI4M/AI4Msim.json `
-  --ak <ak> --sk <sk> --upload_registry --disable_browser
-```
-
-`--upload_registry` 会把 `AI4M_station.yaml` 的 schema 上传到云端，
-之后实验记录本就能看到所有 `auto-*` 动作。
-
----
-
-## 6. 调试方法
-
-### 6.1 用 KEPServerEX 仿真 PLC
-
-不带 PLC 的开发机上，可以用 KEPServerEX（或 `python-opcua` 自建 server）模拟。
-AI4M 提供了一份仿真节点表 `opcua_nodes_AI4M_sim.csv`，**只改 NodeId 不改语义**，
-所以驱动代码无需任何改动即可在本机调试。
-
-### 6.2 单独跑驱动（不开 ROS）
-
-在驱动文件末尾的 `if __name__ == '__main__':` 段：
-
-```python
-if __name__ == '__main__':
-    A4 = AI4MDevice(
-        url="opc.tcp://192.168.1.10:4840",
-        csv_path="opcua_nodes_AI4M.csv",
-    )
-    A4.trigger_init()
-    print("初始化完成")
-    A4.trigger_robot_pick_beaker(1, 1)
-```
-
-**新动作上线前一定要在这里裸跑一遍**，确认握手时序正确，再往上接 ROS。
-
-### 6.3 看日志判断卡在哪
-
-`base_opcua_client.py` 的日志已经覆盖了所有关键节点：
-
-```
-✓ 客户端已连接!
-✓ 找到变量节点: 'robot_ready', NodeId: ns=4;s=...
-✓ 已订阅节点: robot_ready
-✓ 节点查找完成：所有 142 个节点均已找到
-```
-
-如果看到 `⚠ 以下 N 个节点未找到`，**99% 是 CSV 里的 NodeId 写错了**，回去对一下 PLC 工程导出的 NodeId。
-
-### 6.4 检查节点是否能直接读写
-
-```python
-# 透传读，绕过订阅缓存
-A4.get_node_value("robot_ready", force_read=True)
-
-# 直接读 JSON 形式（适合从 HTTP/调试面板调）
-A4.read_node("robot_ready")
-
-# 写
-A4.set_node_value("alarm_reset", True)
-A4.write_node('{"node_name": "alarm_reset", "value": false}')
-```
-
----
-
-## 7. 接入新 PLC 设备的 Checklist
-
-接到一台新工站时，按下面顺序做就能保证不漏：
-
-- [ ] 1. 让 PLC 工程师把上位通讯变量整理到 OPC UA Server，导出 NodeId 清单。
-- [ ] 2. 在 `unilabos/devices/workstation/<设备名>/` 下新建目录，复制 `AI4M/base_opcua_client.py` 不动。
-- [ ] 3. 整理 `opcua_nodes_<设备名>.csv`，6 列填齐，并补上 `EnglishName`。
-- [ ] 4. 在该目录写设备驱动 `<设备名>.py`，继承 `OpcUaClientWithSubscription`：
-  - [ ] `__init__` 调用 `super().__init__` + `self.load_nodes_from_csv(csv_path)`。
-  - [ ] 每个动作函数用范式 A/B/C 写握手协议。
-  - [ ] 每个动作函数都返回 `dict`，至少含 `message` 字段。
-- [ ] 5. 在 `unilabos/registry/devices/` 下新建 `<设备名>_station.yaml`，配置 `init_param_schema` 和 `action_value_mappings`。
-- [ ] 6. 在该目录新建 `<设备名>.json`（Graph），填好 `url` 和 `csv_path`。
-- [ ] 7. 用 `if __name__ == '__main__':` 单独跑驱动确认握手 OK。
-- [ ] 8. 用 `python unilabos/app/main.py -g <Graph> --upload_registry ...` 上线，到实验记录本下发动作回归。
-
----
-
-## 8. 参考实现速查
-
-| 关注点 | 在 AI4M 中看哪里 |
-|---|---|
-| OPC UA 通信基类 | `base_opcua_client.py` |
-| 节点定义类型系统 | `unilabos/device_comms/opcua_client/node/uniopcua.py` |
-| 节点表 CSV 标准 | `opcua_nodes_AI4M.csv` |
-| 设备驱动入口类 | `AI4M.py: AI4MDevice` |
-| 握手范式 A（脉冲+完成） | `AI4M.py: trigger_init` |
-| 握手范式 B（请求/参数/完成） | `AI4M.py: trigger_station_process` |
-| 握手范式 C（编号+完成） | `AI4M.py: trigger_robot_pick_beaker` |
-| 自动模式批量参数下发 | `AI4M.py: download_auto_params` |
-| Registry schema | `unilabos/registry/devices/AI4M_station.yaml` |
-| Graph 实例化 | `AI4M.json` / `AI4Msim.json` |
-| 启动命令 | `start.md` |

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'

recipes/msgs/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: ros-humble-unilabos-msgs
-  version: 0.11.3
+  version: 0.11.1
 source:
   path: ../../unilabos_msgs
   target_directory: src

recipes/unilabos/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: unilabos
-  version: "0.11.3"
+  version: "0.11.1"
 
 source:
   path: ../..

setup.py

@@ -4,7 +4,7 @@ package_name = 'unilabos'
 
 setup(
     name=package_name,
-    version='0.11.3',
+    version='0.11.1',
     packages=find_packages(),
     include_package_data=True,
     install_requires=['setuptools'],

unilabos/__init__.py

@@ -1 +1 @@
-__version__ = "0.11.3"
+__version__ = "0.11.1"

unilabos/app/model.py

@@ -59,7 +59,6 @@ class JobAddReq(BaseModel):
     task_id: str = Field(examples=["task_id"], description="task uuid (auto-generated if empty)", default="")
     job_id: str = Field(examples=["job_id"], description="goal uuid (auto-generated if empty)", default="")
     node_id: str = Field(examples=["node_id"], description="node uuid", default="")
-    notebook_id: str = Field(examples=["notebook_id"], description="notebook uuid", default="")
     server_info: dict = Field(
         examples=[{"send_timestamp": 1717000000.0}],
         description="server info (auto-generated if empty)",

unilabos/app/utils.py

@@ -10,170 +10,29 @@ import shutil
 import sys
 
 
-_PATCH_MARKER = "# UniLabOS DLL Patch"
-_PATCH_END_MARKER = "# End UniLabOS DLL Patch"
-
-# 75 = EX_TEMPFAIL: 临时失败、重试即可，避免与业务退出码冲突
-_RESTART_EXIT_CODE = 75
-
-
-def _build_dll_patch(lib_bin: str, preload_pyd: str = "") -> str:
-    """生成一段加在目标文件顶部的 DLL 加载补丁源码。
-
-    - 始终把 ``lib_bin`` 加入 DLL 搜索路径，并把 handle 挂在模块属性上，
-      防止 GC 清掉搜索路径（``os.add_dll_directory`` 的句柄被回收时
-      目录会被移除）。
-    - 可选地用 ``ctypes.CDLL`` 预加载一个 .pyd，把它的依赖 DLL 提前装入
-      进程内存，作为 ``rclpy._rclpy_pybind11`` 这类首次加载点的兜底。
-    """
-    # 用 repr() 序列化路径：Python 解析 repr 的结果会还原成原始字符串，
-    # 不需要也不能再叠加 raw-string 前缀（叠了反而会让 \\ 变成两个反斜杠）。
-    lines = [
-        _PATCH_MARKER,
-        "import os as _ulab_os",
-        f"_ulab_p = {lib_bin!r}",
-        'if hasattr(_ulab_os, "add_dll_directory") and _ulab_os.path.isdir(_ulab_p):',
-        "    try: _UNILAB_DLL_HANDLE = _ulab_os.add_dll_directory(_ulab_p)",
-        "    except Exception: _UNILAB_DLL_HANDLE = None",
-    ]
-    if preload_pyd:
-        lines.extend(
-            [
-                "import ctypes as _ulab_ctypes",
-                f"try: _ulab_ctypes.CDLL({preload_pyd!r})",
-                "except Exception: pass",
-            ]
-        )
-    lines.append(_PATCH_END_MARKER)
-    return "\n".join(lines) + "\n"
-
-
-def _apply_dll_patch(file_path: str, lib_bin: str, preload_pyd: str = "") -> bool:
-    """把 DLL 补丁前置到 ``file_path``。文件不存在或已打过补丁则返回 False。"""
-    if not os.path.isfile(file_path):
-        return False
-    with open(file_path, "r", encoding="utf-8") as f:
-        content = f.read()
-    if _PATCH_MARKER in content:
-        return False
-    shutil.copy2(file_path, file_path + ".bak")
-    with open(file_path, "w", encoding="utf-8") as f:
-        f.write(_build_dll_patch(lib_bin, preload_pyd) + content)
-    return True
-
-
-def _print_restart_banner(patched_files):
-    """打印重启提示并以 EX_TEMPFAIL 退出。
-
-    - 不使用 ANSI 颜色码：Windows 旧版 cmd / PowerShell 5 默认不开 VT 处理，
-      会把 ``\\033[1;33m`` 当做字面字符显示，反而让用户看不到正文。
-    - 同时写入 stderr 与 stdout：某些上层 launcher / supervisor 只重定向
-      其中一路，写两遍能保证用户至少看到一份。
-    - 写入前防御性把流切到 UTF-8 with replace：``main.py`` 里已经做过一次，
-      但本模块也可能被绕过 ``main.py`` 的代码路径直接 import；reconfigure
-      失败也只是退回 errors=replace，不影响整体流程。
-    """
-    if sys.platform == "win32":
-        for _stream in (sys.stdout, sys.stderr):
-            try:
-                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
-            except (AttributeError, OSError):
-                pass
-
-    bar = "#" * 78
-    files_lines = [f"[UniLabOS]   - {p}" for p in patched_files]
-    body = "\n".join(
-        [
-            "",
-            bar,
-            bar,
-            "##",
-            "##  [UniLabOS] Windows + conda 下检测到 DLL 加载失败，已自动打补丁。",
-            "##  [UniLabOS] DLL load failure detected on Windows + conda;",
-            "##  [UniLabOS] the following files have been auto-patched:",
-            "##",
-            *[f"##  {line}" for line in files_lines],
-            "##",
-            "##  [UniLabOS] 当前进程的 rclpy 状态已损坏，补丁需要在新进程才生效。",
-            "##  [UniLabOS] The current process is unusable; the patch only takes",
-            "##  [UniLabOS] effect on a fresh process.",
-            "##",
-            "##  >>> 请重新运行刚才的命令 / Please re-run the same command. <<<",
-            "##",
-            bar,
-            bar,
-            "",
-        ]
-    )
-
-    for stream in (sys.stderr, sys.stdout):
-        try:
-            stream.write(body)
-            stream.flush()
-        except Exception:
-            try:
-                print(body, file=stream)
-            except Exception:
-                pass
-
-    sys.exit(_RESTART_EXIT_CODE)
-
-
 def patch_rclpy_dll_windows():
-    """在 Windows + conda 环境下修复 rclpy / rosidl typesupport 的 DLL 加载。
-
-    背景：conda 安装的 ros 系列包，其原生扩展依赖 ``$CONDA_PREFIX/Library/bin``
-    下的 DLL；只有 conda 环境被正确激活、且 PATH 中含 ``Library/bin`` 时，
-    ``os.add_dll_directory`` 才能找到它们。当从快捷方式 / IDE / 子进程 /
-    没激活的 shell 启动 ``unilab`` 时，会出现 ``DLL load failed``。
-
-    本函数会:
-        1) 修补 ``rclpy/impl/implementation_singleton.py`` —— rclpy 自身的 C 扩展入口；
-        2) 修补 ``rpyutils/add_dll_directories.py`` —— 所有 ``*_s__rosidl_typesupport_c.pyd``
-           （``geometry_msgs`` / ``std_msgs`` / ``sensor_msgs`` 等）的统一加载入口。
-
-    打完补丁后**必须重启进程**才能生效（当前进程的 rclpy 已经发生过
-    ``ImportError``，子模块仍处于损坏状态）。因此函数会主动退出，并在
-    stdout/stderr 同时打印明显的重启提示，避免用户被后续报错淹没。
-    """
+    """在 Windows + conda 环境下为 rclpy 打 DLL 加载补丁"""
     if sys.platform != "win32" or not os.environ.get("CONDA_PREFIX"):
         return
-
     try:
-        import rclpy  # noqa: F401
+        import rclpy
 
         return
     except ImportError as e:
         if not str(e).startswith("DLL load failed"):
             return
-
     cp = os.environ["CONDA_PREFIX"]
-    lib_bin = os.path.join(cp, "Library", "bin")
-    site_packages = os.path.join(cp, "Lib", "site-packages")
-    if not os.path.isdir(lib_bin):
+    impl = os.path.join(cp, "Lib", "site-packages", "rclpy", "impl", "implementation_singleton.py")
+    pyd = glob.glob(os.path.join(cp, "Lib", "site-packages", "rclpy", "_rclpy_pybind11*.pyd"))
+    if not os.path.exists(impl) or not pyd:
         return
-
-    patched = []
-
-    # 1) rclpy 自身的入口
-    rclpy_impl = os.path.join(site_packages, "rclpy", "impl", "implementation_singleton.py")
-    rclpy_pyd_matches = glob.glob(os.path.join(site_packages, "rclpy", "_rclpy_pybind11*.pyd"))
-    rclpy_pyd = rclpy_pyd_matches[0] if rclpy_pyd_matches else ""
-    if rclpy_pyd and _apply_dll_patch(rclpy_impl, lib_bin, preload_pyd=rclpy_pyd):
-        patched.append(rclpy_impl)
-
-    # 2) rpyutils —— 所有 rosidl typesupport pyd 的加载点；放在 rclpy 之后
-    #    例：geometry_msgs/geometry_msgs_s__rosidl_typesupport_c.pyd
-    rpyutils_dll = os.path.join(site_packages, "rpyutils", "add_dll_directories.py")
-    if _apply_dll_patch(rpyutils_dll, lib_bin):
-        patched.append(rpyutils_dll)
-
-    if not patched:
-        # 已经打过补丁但 rclpy 仍然加载失败：原因不是缺 DLL 搜索路径，
-        # 不要再次打补丁污染文件，让上层看到真实的 ImportError。
-        return
-
-    _print_restart_banner(patched)
+    with open(impl, "r", encoding="utf-8") as f:
+        content = f.read()
+    lib_bin = os.path.join(cp, "Library", "bin").replace("\\", "/")
+    patch = f'# UniLabOS DLL Patch\nimport os,ctypes\nos.add_dll_directory("{lib_bin}") if hasattr(os,"add_dll_directory") else None\ntry: ctypes.CDLL("{pyd[0].replace(chr(92),"/")}")\nexcept: pass\n# End Patch\n'
+    shutil.copy2(impl, impl + ".bak")
+    with open(impl, "w", encoding="utf-8") as f:
+        f.write(patch + content)
 
 
 patch_rclpy_dll_windows()

unilabos/app/web/controller.py

@@ -320,7 +320,6 @@ def job_add(req: JobAddReq) -> JobData:
             action_name=action_name,
             task_id=task_id,
             job_id=job_id,
-            notebook_id=req.notebook_id,
             device_action_key=device_action_key,
         )
 

unilabos/app/ws_client.py

@@ -59,7 +59,6 @@ class QueueItem:
     action_name: str
     task_id: str
     job_id: str
-    notebook_id: str
     device_action_key: str
     next_run_time: float = 0  # 下次执行时间戳
     retry_count: int = 0  # 重试次数
@@ -72,7 +71,6 @@ class JobInfo:
     job_id: str
     task_id: str
     device_id: str
-    notebook_id: str
     action_name: str
     device_action_key: str
     status: JobStatus
@@ -541,10 +539,7 @@ class MessageProcessor:
                 self.reconnect_count += 1
                 backoff = WSConfig.reconnect_interval
                 logger.info(
-                    "[MessageProcessor] 即将在 %s 秒后重连 (已尝试 %s/%s)",
-                    backoff,
-                    self.reconnect_count,
-                    WSConfig.max_reconnect_attempts,
+                    f"[MessageProcessor] 即将在 {backoff} 秒后重连 (已尝试 {self.reconnect_count}/{WSConfig.max_reconnect_attempts})"
                 )
                 await asyncio.sleep(backoff)
             else:
@@ -708,7 +703,6 @@ class MessageProcessor:
         action_name = data.get("action_name", "")
         task_id = data.get("task_id", "")
         job_id = data.get("job_id", "")
-        notebook_id = data.get("notebook_id", "")
 
         if not all([device_id, action_name, task_id, job_id]):
             logger.error("[MessageProcessor] Missing required fields in query_action_state")
@@ -724,7 +718,6 @@ class MessageProcessor:
             job_id=job_id,
             task_id=task_id,
             device_id=device_id,
-            notebook_id=notebook_id,
             action_name=action_name,
             device_action_key=device_action_key,
             status=JobStatus.QUEUE,
@@ -739,27 +732,13 @@ class MessageProcessor:
         if can_start_immediately:
             # 可以立即开始
             await self._send_action_state_response(
-                device_id,
-                action_name,
-                task_id,
-                job_id,
-                "query_action_status",
-                True,
-                0,
-                notebook_id=notebook_id,
+                device_id, action_name, task_id, job_id, "query_action_status", True, 0
             )
             logger.trace(f"[MessageProcessor] Job {job_log} can start immediately")
         else:
             # 需要排队
             await self._send_action_state_response(
-                device_id,
-                action_name,
-                task_id,
-                job_id,
-                "query_action_status",
-                False,
-                10,
-                notebook_id=notebook_id,
+                device_id, action_name, task_id, job_id, "query_action_status", False, 10
             )
             logger.trace(f"[MessageProcessor] Job {job_log} queued")
 
@@ -789,7 +768,6 @@ class MessageProcessor:
                         job_id=req.job_id,
                         task_id=req.task_id,
                         device_id=req.device_id,
-                        notebook_id=req.notebook_id,
                         action_name=action_name,
                         device_action_key=device_action_key,
                         status=JobStatus.QUEUE,
@@ -797,16 +775,11 @@ class MessageProcessor:
                         always_free=True,
                     )
                     self.device_manager.add_queue_request(job_info)
-                    existing_job = job_info
                     logger.info(f"[MessageProcessor] Job {job_log} always_free, auto-registered from direct job_start")
                 else:
                     logger.error(f"[MessageProcessor] Job {job_log} not registered (missing query_action_state)")
                     return
 
-            if existing_job and req.notebook_id and not existing_job.notebook_id:
-                existing_job.notebook_id = req.notebook_id
-            notebook_id = req.notebook_id or (existing_job.notebook_id if existing_job else "")
-
             success = self.device_manager.start_job(req.job_id)
             if not success:
                 logger.error(f"[MessageProcessor] Failed to start job {job_log}")
@@ -822,7 +795,6 @@ class MessageProcessor:
                 action_name=req.action,
                 task_id=req.task_id,
                 job_id=req.job_id,
-                notebook_id=notebook_id,
                 device_action_key=device_action_key,
             )
 
@@ -862,7 +834,6 @@ class MessageProcessor:
                             "job_id": req.job_id,
                             "task_id": req.task_id,
                             "device_id": req.device_id,
-                            "notebook_id": queue_item.notebook_id,
                             "action_name": req.action,
                             "status": "failed",
                             "feedback_data": {},
@@ -884,7 +855,6 @@ class MessageProcessor:
                             "query_action_status",
                             True,
                             0,
-                            notebook_id=next_job.notebook_id,
                         )
                         next_job_log = format_job_log(
                             next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
@@ -1034,16 +1004,11 @@ class MessageProcessor:
 
                     success = host_node.notify_resource_tree_update(dev_id, act, item_list)
 
-                    if success is True:
+                    if success:
                         logger.info(
                             f"[MessageProcessor] Resource tree {act} completed for device {dev_id}, "
                             f"items: {len(item_list)}"
                         )
-                    elif success is None:
-                        logger.info(
-                            f"[MessageProcessor] Resource tree {act} skipped for device {dev_id}: "
-                            "在线增加设备暂不支持"
-                        )
                     else:
                         logger.warning(f"[MessageProcessor] Resource tree {act} failed for device {dev_id}")
 
@@ -1067,11 +1032,6 @@ class MessageProcessor:
 
         for item in device_list:
             target_node_id = item.get("target_node_id", "host_node")
-            if action == "add":
-                logger.info(
-                    f"[DeviceManage] 在线增加设备暂不支持，跳过 add_device: {item.get('id', '')}"
-                )
-                continue
 
             def _notify(target_id: str, act: str, cfg: ResourceDictType):
                 try:
@@ -1141,15 +1101,7 @@ class MessageProcessor:
         logger.info(f"[MessageProcessor] Restart cleanup scheduled")
 
     async def _send_action_state_response(
-        self,
-        device_id: str,
-        action_name: str,
-        task_id: str,
-        job_id: str,
-        typ: str,
-        free: bool,
-        need_more: int,
-        notebook_id: str = "",
+        self, device_id: str, action_name: str, task_id: str, job_id: str, typ: str, free: bool, need_more: int
     ):
         """发送动作状态响应"""
         message = {
@@ -1160,7 +1112,6 @@ class MessageProcessor:
                 "action_name": action_name,
                 "task_id": task_id,
                 "job_id": job_id,
-                "notebook_id": notebook_id,
                 "free": free,
                 "need_more": need_more + 1,
             },
@@ -1243,7 +1194,6 @@ class QueueProcessor:
                             action_name=timeout_job.action_name,
                             task_id=timeout_job.task_id,
                             job_id=timeout_job.job_id,
-                            notebook_id=timeout_job.notebook_id,
                             device_action_key=timeout_job.device_action_key,
                         )
                         # 发布超时失败状态，这会触发正常的job完成流程
@@ -1302,7 +1252,6 @@ class QueueProcessor:
                     "action_name": job_info.action_name,
                     "task_id": job_info.task_id,
                     "job_id": job_info.job_id,
-                    "notebook_id": job_info.notebook_id,
                     "free": False,
                     "need_more": 10 + 1,
                 },
@@ -1342,7 +1291,6 @@ class QueueProcessor:
                     "action_name": job_info.action_name,
                     "task_id": job_info.task_id,
                     "job_id": job_info.job_id,
-                    "notebook_id": job_info.notebook_id,
                     "free": False,
                     "need_more": 10 + 1,
                 },
@@ -1388,15 +1336,12 @@ class QueueProcessor:
                     "action_name": next_job.action_name,
                     "task_id": next_job.task_id,
                     "job_id": next_job.job_id,
-                    "notebook_id": next_job.notebook_id,
                     "free": True,
                     "need_more": 0,
                 },
             }
             self.message_processor.send_message(message)
-            # next_job_log = format_job_log(
-            #     next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
-            # )
+            # next_job_log = format_job_log(next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name)
             # logger.debug(f"[QueueProcessor] Notified next job {next_job_log} can start")
 
             # 立即触发下一轮状态检查
@@ -1565,7 +1510,6 @@ class WebSocketClient(BaseCommunicationClient):
                 "job_id": item.job_id,
                 "task_id": item.task_id,
                 "device_id": item.device_id,
-                "notebook_id": item.notebook_id,
                 "action_name": item.action_name,
                 "status": status,
                 "feedback_data": feedback_data,

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 @@
+"""LaiYu PLR 后端 — 对齐路径 B 硬件交互模式
 
-import json
+硬件初始化顺序与 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)
+        # 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,
+        )
 
-    if not res:
-        self.hardware_interface.logger.error("吸取失败，当前体积: {self.hardware_interface.current_volume}")
-        return
+        # 3. 回零 + 移液器初始化
+        self._xyz.home_all_axes()
+        self._pipette_ctrl.initialize()
 
-    self.hardware_interface.current_volume += volume 
+        logger.info("LaiYu 后端硬件初始化完成")
 
-  def pipette_dispense(self, volume: float, flow_rate: float):
+    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}")
 
-    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
+    # ------------------------------------------------------------------ helpers
 
-  @property
-  def num_channels(self) -> int:
-    return self._num_channels
+    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 assigned_resource_callback(self, resource: Resource):
-    print(f"Resource {resource.name} was assigned to 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 unassigned_resource_callback(self, name: str):
-    print(f"Resource {name} was unassigned from the liquid handler.")
+    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
 
-  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)
+    # ------------------------------------------------------------------ properties
 
-    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())
+    def serialize(self) -> dict:
+        return {**super().serialize(), "num_channels": self.num_channels}
 
-    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()
+    @property
+    def num_channels(self) -> int:
+        return self._num_channels
 
+    # ------------------------------------------------------------------ resource callbacks
 
+    async def assigned_resource_callback(self, resource: Resource):
+        logger.info(f"Resource {resource.name} was assigned to the liquid handler.")
 
+    async def unassigned_resource_callback(self, name: str):
+        logger.info(f"Resource {name} was unassigned from the liquid handler.")
 
-  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)
+    # ------------------------------------------------------------------ pick_up_tips
 
-    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 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)
 
-    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)  
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status == TipStatus.TIP_ATTACHED:
+            logger.warning("已有枪头，无需重复拾取")
+            return
 
-  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)
+        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
 
-    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")
+    # ------------------------------------------------------------------ drop_tips
 
-    # 判断枪头是否存在
-    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
+    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(x=x, y=-y, z=z,speed=200)
-    self.pipette_aspirate(volume=ops[0].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
 
-    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)
+    # ------------------------------------------------------------------ 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)
 
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status != TipStatus.TIP_ATTACHED:
+            raise RuntimeError("无枪头，无法吸液")
 
+        flow_rate = backend_kwargs.get("flow_rate", 500)
+        blow_out_air_volume = backend_kwargs.get("blow_out_air_volume", 0)
 
-  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)
+        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}"
+            )
 
-    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")
+        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.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
+        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)
 
+    # ------------------------------------------------------------------ dispense
 
-    # 移动到排液位置  
-    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)
+    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)
 
+        self._pipette_ctrl._update_tip_status()
+        if self._pipette_ctrl.tip_status != TipStatus.TIP_ATTACHED:
+            raise RuntimeError("无枪头，无法排液")
 
-    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)
+        flow_rate = backend_kwargs.get("flow_rate", 500)
+        blow_out_air_volume = backend_kwargs.get("blow_out_air_volume", 0)
 
-  async def pick_up_tips96(self, pickup: PickupTipRack, **backend_kwargs):
-    print(f"Picking up tips from {pickup.resource.name}.")
+        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 drop_tips96(self, drop: DropTipRack, **backend_kwargs):
-    print(f"Dropping tips to {drop.resource.name}.")
+        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 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}.")
+        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 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}.")
+    # ------------------------------------------------------------------ 96-channel stubs
 
-  async def pick_up_resource(self, pickup: ResourcePickup):
-    print(f"Picking up resource: {pickup}")
+    async def pick_up_tips96(self, pickup: PickupTipRack, **backend_kwargs):
+        logger.info(f"Picking up tips from {pickup.resource.name}.")
 
-  async def move_picked_up_resource(self, move: ResourceMove):
-    print(f"Moving picked up resource: {move}")
+    async def drop_tips96(self, drop: DropTipRack, **backend_kwargs):
+        logger.info(f"Dropping tips to {drop.resource.name}.")
 
-  async def drop_resource(self, drop: ResourceDrop):
-    print(f"Dropping resource: {drop}")
+    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}.")
 
-  def can_pick_up_tip(self, channel_idx: int, tip: Tip) -> bool:
-    return True
+    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
@@ -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,19 +231,21 @@ 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 轴移动的安全性
@@ -343,10 +378,9 @@ class PipetteController:
         """
         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}")

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/liquid_handler_abstract.py

@@ -57,6 +57,18 @@ class TransferLiquidReturn(TypedDict):
     targets: List[List[ResourceDict]]
 
 
+
+class SetLiquidReturn(TypedDict):
+    wells: list
+    volumes: list
+
+
+class SetLiquidFromPlateReturn(TypedDict):
+    plate: list
+    wells: list
+    volumes: list
+
+
 class LiquidHandlerMiddleware(LiquidHandler):
     def __init__(
         self, backend: LiquidHandlerBackend, deck: Deck, simulator: bool = False, channel_num: int = 8, **kwargs

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/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/bioyond_studio/station.py

@@ -258,7 +258,7 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
                 logger.info(f"[同步→Bioyond] ➕ 物料不存在于 Bioyond，将创建新物料并入库")
 
             # 第1步：从配置中获取仓库配置
-            warehouse_mapping = self.bioyond_config.get("warehouse_mapping", {})
+            warehouse_mapping = self.workstation.bioyond_config.get("warehouse_mapping", {})
 
             # 确定目标仓库名称
             parent_name = None

unilabos/registry/ast_registry_scanner.py

@@ -32,7 +32,7 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 
 MAX_SCAN_DEPTH = 10      # 最大目录递归深度
 MAX_SCAN_FILES = 1000    # 最大扫描文件数量
-_CACHE_VERSION = 2       # 缓存格式版本号，格式变更时递增
+_CACHE_VERSION = 1       # 缓存格式版本号，格式变更时递增
 
 # 合法的装饰器来源模块
 _REGISTRY_DECORATOR_MODULE = "unilabos.registry.decorators"
@@ -258,6 +258,8 @@ def scan_directory(
     }
 
 
+
+
 # ---------------------------------------------------------------------------
 # File-level parsing
 # ---------------------------------------------------------------------------
@@ -359,7 +361,6 @@ def _parse_file(
                     "actions": class_body.get("actions", {}),
                     "status_properties": class_body.get("status_properties", {}),
                     "init_params": class_body.get("init_params", []),
-                    "init_docstring": class_body.get("init_docstring"),
                     "auto_methods": class_body.get("auto_methods", {}),
                     "import_map": import_map,
                 }
@@ -496,6 +497,7 @@ def _collect_imports(tree: ast.Module, module_path: str = "") -> Dict[str, str]:
     return import_map
 
 
+
 # ---------------------------------------------------------------------------
 # Decorator finding & argument extraction
 # ---------------------------------------------------------------------------
@@ -766,7 +768,6 @@ def _extract_class_body(
         "actions": {},          # method_name -> action_info
         "status_properties": {},  # prop_name -> status_info
         "init_params": [],      # [{"name": ..., "type": ..., "default": ...}, ...]
-        "init_docstring": None,
         "auto_methods": {},     # method_name -> method_info (no @action decorator)
     }
 
@@ -779,7 +780,6 @@ def _extract_class_body(
         # --- __init__ ---
         if method_name == "__init__":
             result["init_params"] = _extract_method_params(item, import_map)
-            result["init_docstring"] = ast.get_docstring(item)
             continue
 
         # --- Skip private/dunder ---

unilabos/registry/devices/Qone_nmr.yaml

@@ -51,18 +51,14 @@ Qone_nmr:
               properties:
                 check_interval:
                   default: 60
-                  description: 检查间隔时间（秒），默认60秒
                   type: string
                 expected_count:
                   default: 1
-                  description: 期望生成的.nmr文件数量，默认1个
                   type: string
                 monitor_dir:
-                  description: 要监督的目录路径，如果未指定则使用self.monitor_directory
                   type: string
                 stability_checks:
                   default: 3
-                  description: 文件大小稳定性检查次数，默认3次
                   type: string
               required: []
               type: object
@@ -89,14 +85,11 @@ Qone_nmr:
             goal:
               properties:
                 output_dir:
-                  description: 输出目录（如果未指定，使用self.output_directory）
                   type: string
                 string_list:
-                  description: 字符串列表
                   type: string
                 txt_encoding:
                   default: utf-8
-                  description: 文件编码
                   type: string
               required:
               - string_list
@@ -158,13 +151,6 @@ Qone_nmr:
               additionalProperties: false
               properties:
                 string:
-                  description: '包含多个字符串的输入数据，支持两种格式：
-
-                    1. 逗号分隔：如 "A 1 B 2 C 3, X 10 Y 20 Z 30"
-
-                    2. 换行分隔：如 "A 1 B 2 C 3
-
-                    X 10 Y 20 Z 30"'
                   type: string
               title: StrSingleInput_Goal
               type: object

unilabos/registry/devices/bioyond_cell.yaml

@@ -491,17 +491,14 @@ bioyond_cell:
             goal:
               properties:
                 material_names:
-                  description: 物料名称列表；默认使用 [LiPF6, LiDFOB, DTD, LiFSI, LiPO2F2]
                   items:
                     type: string
                   type: array
                 type_id:
                   default: 3a190ca0-b2f6-9aeb-8067-547e72c11469
-                  description: 物料类型ID
                   type: string
                 warehouse_name:
                   default: 粉末加样头堆栈
-                  description: 目标仓库名（用于取位置信息）
                   type: string
               required: []
               type: object
@@ -530,16 +527,12 @@ bioyond_cell:
             goal:
               properties:
                 location_name_or_id:
-                  description: 具体库位名称（如 A01）或库位 UUID，由用户指定。
                   type: string
                 material_name:
-                  description: 物料名称（会优先匹配配置模板）。
                   type: string
                 type_id:
-                  description: 物料类型 ID（若为空则尝试从配置推断）。
                   type: string
                 warehouse_name:
-                  description: 需要入库的仓库名称；若为空则仅创建不入库。
                   type: string
               required:
               - material_name
@@ -668,20 +661,15 @@ bioyond_cell:
             goal:
               properties:
                 board_type:
-                  description: 板类型，如 "5ml分液瓶板"、"配液瓶(小)板"
                   type: string
                 bottle_type:
-                  description: 瓶类型，如 "5ml分液瓶"、"配液瓶(小)"
                   type: string
                 location_code:
-                  description: 库位编号，例如 "A01"
                   type: string
                 name:
-                  description: 物料名称
                   type: string
                 warehouse_name:
                   default: 手动堆栈
-                  description: 仓库名称，默认为 "手动堆栈"，支持 "自动堆栈-左"、"自动堆栈-右" 等
                   type: string
               required:
               - name
@@ -1968,19 +1956,19 @@ bioyond_cell:
               properties:
                 source_wh_id:
                   default: 3a19debc-84b4-0359-e2d4-b3beea49348b
-                  description: 来源仓库 Id (默认为3号仓库)
+                  description: 来源仓库ID
                   type: string
                 source_x:
                   default: 1
-                  description: 来源位置 X 坐标
+                  description: 来源位置X坐标
                   type: integer
                 source_y:
                   default: 1
-                  description: 来源位置 Y 坐标
+                  description: 来源位置Y坐标
                   type: integer
                 source_z:
                   default: 1
-                  description: 来源位置 Z 坐标
+                  description: 来源位置Z坐标
                   type: integer
               required: []
               type: object
@@ -2073,11 +2061,9 @@ bioyond_cell:
             goal:
               properties:
                 order_code:
-                  description: 任务编号
                   type: string
                 timeout:
                   default: 36000
-                  description: 超时时间（秒）
                   type: integer
               required:
               - order_code
@@ -2106,15 +2092,12 @@ bioyond_cell:
             goal:
               properties:
                 order_code:
-                  description: 任务编号
                   type: string
                 poll_interval:
                   default: 0.5
-                  description: 轮询间隔（秒），默认 0.5 秒
                   type: number
                 timeout:
                   default: 36000
-                  description: 超时时间（秒）
                   type: integer
               required:
               - order_code
@@ -2171,15 +2154,10 @@ bioyond_cell:
     config:
       properties:
         bioyond_config:
-          description: '从 JSON 文件加载的 bioyond 配置字典
-
-            包含 api_host, api_key, HTTP_host, HTTP_port 等配置'
           type: object
         deck:
-          description: Deck 配置（可选，会从 JSON 中自动处理）
           type: string
         protocol_type:
-          description: 协议类型（可选）
           type: string
       required: []
       type: object

unilabos/registry/devices/bioyond_dispensing_station.yaml

@@ -47,10 +47,8 @@ bioyond_dispensing_station:
             goal:
               properties:
                 report_request:
-                  description: WorkstationReportRequest 对象，包含任务完成信息
                   type: string
                 used_materials:
-                  description: 物料使用记录列表
                   type: string
               required:
               - report_request
@@ -104,7 +102,6 @@ bioyond_dispensing_station:
             goal:
               properties:
                 material_name:
-                  description: 物料名称
                   type: string
               required:
               - material_name
@@ -614,10 +611,10 @@ bioyond_dispensing_station:
             goal:
               properties:
                 target_device_id:
-                  description: 目标反应站设备ID(所有转移组使用同一个设备)
+                  description: 目标反应站设备ID（从设备列表中选择，所有转移组都使用同一个目标设备）
                   type: string
                 transfer_groups:
-                  description: '转移任务组列表,每组包含:'
+                  description: 转移任务组列表，每组包含物料名称、目标堆栈和目标库位，可以添加多组
                   type: array
               required:
               - target_device_id
@@ -697,13 +694,10 @@ bioyond_dispensing_station:
     config:
       properties:
         config:
-          description: 配置字典,应包含material_type_mappings等配置
           type: object
         deck:
-          description: Deck对象
           type: string
         protocol_type:
-          description: 协议类型(由ROS系统传递,此处忽略)
           type: string
       required: []
       type: object

unilabos/registry/devices/chinwe.yaml

@@ -336,6 +336,47 @@ separator.chinwe:
           title: pump_valve参数
           type: object
         type: UniLabJsonCommand
+      separation_step:
+        goal:
+          max_cycles: 0
+          motor_id: 5
+          pulses: 700
+          speed: 60
+          timeout: 300
+        handles: {}
+        schema:
+          description: 分液步骤 - 液位传感器与电机联动 (有液→顺时针, 无液→逆时针)
+          properties:
+            goal:
+              properties:
+                max_cycles:
+                  default: 0
+                  description: 最大循环次数 (0=无限制)
+                  type: integer
+                motor_id:
+                  default: '5'
+                  description: 选择电机
+                  enum:
+                  - '4'
+                  - '5'
+                  title: '注: 4=搅拌, 5=旋钮'
+                  type: string
+                pulses:
+                  default: 700
+                  description: 每次旋转脉冲数 (约1/4圈)
+                  type: integer
+                speed:
+                  default: 60
+                  description: 电机转速 (RPM)
+                  type: integer
+                timeout:
+                  default: 300
+                  description: 超时时间 (秒)
+                  type: integer
+              required:
+              - motor_id
+              type: object
+        type: UniLabJsonCommand
       wait_sensor_level:
         feedback: {}
         goal:

unilabos/registry/devices/coin_cell_workstation.yaml

@@ -150,15 +150,15 @@ coincellassemblyworkstation_device:
               properties:
                 assembly_pressure:
                   default: 4200
-                  description: 电池压制力 (N)
+                  description: 电池压制力(N)
                   type: integer
                 assembly_type:
                   default: 7
-                  description: 组装类型 (7=不用铝箔垫, 8=使用铝箔垫)
+                  description: 组装类型(7=不用铝箔垫, 8=使用铝箔垫)
                   type: integer
                 battery_clean_ignore:
                   default: false
-                  description: 是否忽略电池清洁
+                  description: 是否忽略电池清洁步骤
                   type: boolean
                 battery_pressure_mode:
                   default: true
@@ -166,29 +166,29 @@ coincellassemblyworkstation_device:
                   type: boolean
                 dual_drop_first_volume:
                   default: 25
-                  description: 二次滴液第一次排液体积 (μL)
+                  description: 二次滴液第一次排液体积(μL)
                   type: integer
                 dual_drop_mode:
                   default: false
-                  description: 电解液添加模式 (False=单次滴液, True=二次滴液)
+                  description: 电解液添加模式(false=单次滴液, true=二次滴液)
                   type: boolean
                 dual_drop_start_timing:
                   default: false
-                  description: 二次滴液开始滴液时机 (False=正极片前, True=正极片后)
+                  description: 二次滴液开始滴液时机(false=正极片前, true=正极片后)
                   type: boolean
                 dual_drop_suction_timing:
                   default: false
-                  description: 二次滴液吸液时机 (False=正常吸液, True=先吸液)
+                  description: 二次滴液吸液时机(false=正常吸液, true=先吸液)
                   type: boolean
                 elec_num:
                   description: 电解液瓶数
                   type: string
                 elec_use_num:
-                  description: 每瓶电解液组装的电池数
+                  description: 每瓶电解液组装电池数
                   type: string
                 elec_vol:
                   default: 50
-                  description: 电解液吸液量 (μL)
+                  description: 电解液吸液量(μL)
                   type: integer
                 file_path:
                   default: /Users/sml/work
@@ -196,7 +196,7 @@ coincellassemblyworkstation_device:
                   type: string
                 fujipian_juzhendianwei:
                   default: 0
-                  description: 负极片矩阵点位
+                  description: 负极片矩阵点位。盘位置从1开始计数，有效范围：1-8, 13-20 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
                 fujipian_panshu:
                   default: 0
@@ -204,7 +204,7 @@ coincellassemblyworkstation_device:
                   type: integer
                 gemo_juzhendianwei:
                   default: 0
-                  description: 隔膜矩阵点位
+                  description: 隔膜矩阵点位。盘位置从1开始计数，有效范围：1-8, 13-20 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
                 gemopanshu:
                   default: 0
@@ -216,7 +216,7 @@ coincellassemblyworkstation_device:
                   type: boolean
                 qiangtou_juzhendianwei:
                   default: 0
-                  description: 枪头盒矩阵点位
+                  description: 枪头盒矩阵点位。盘位置从1开始计数，有效范围：1-32, 64-96 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
               required:
               - elec_num
@@ -308,13 +308,7 @@ coincellassemblyworkstation_device:
               properties:
                 material_search_enable:
                   default: false
-                  description: '是否启用物料搜寻功能。
-
-                    设备初始化后会弹出物料搜寻确认弹窗，
-
-                    此参数控制自动点击''是''（启用）或''否''（不启用）。
-
-                    默认为False（不启用物料搜寻）。'
+                  description: 是否启用物料搜寻功能。设备初始化后会弹出物料搜寻确认弹窗，此参数控制自动点击"是"(启用)或"否"(不启用)。默认为false(不启用物料搜寻)
                   type: boolean
               required: []
               type: object
@@ -553,15 +547,15 @@ coincellassemblyworkstation_device:
               properties:
                 assembly_pressure:
                   default: 4200
-                  description: 电池压制力 (N)
+                  description: 电池压制力(N)
                   type: integer
                 assembly_type:
                   default: 7
-                  description: 组装类型 (7=不用铝箔垫, 8=使用铝箔垫)
+                  description: 组装类型(7=不用铝箔垫, 8=使用铝箔垫)
                   type: integer
                 battery_clean_ignore:
                   default: false
-                  description: 是否忽略电池清洁
+                  description: 是否忽略电池清洁步骤
                   type: boolean
                 battery_pressure_mode:
                   default: true
@@ -569,29 +563,29 @@ coincellassemblyworkstation_device:
                   type: boolean
                 dual_drop_first_volume:
                   default: 25
-                  description: 二次滴液第一次排液体积 (μL)
+                  description: 二次滴液第一次排液体积(μL)
                   type: integer
                 dual_drop_mode:
                   default: false
-                  description: 电解液添加模式 (False=单次滴液, True=二次滴液)
+                  description: 电解液添加模式(false=单次滴液, true=二次滴液)
                   type: boolean
                 dual_drop_start_timing:
                   default: false
-                  description: 二次滴液开始滴液时机 (False=正极片前, True=正极片后)
+                  description: 二次滴液开始滴液时机(false=正极片前, true=正极片后)
                   type: boolean
                 dual_drop_suction_timing:
                   default: false
-                  description: 二次滴液吸液时机 (False=正常吸液, True=先吸液)
+                  description: 二次滴液吸液时机(false=正常吸液, true=先吸液)
                   type: boolean
                 elec_num:
-                  description: 电解液瓶数
+                  description: 电解液瓶数，如果在workflow中已通过handles连接上游(create_orders的bottle_count输出)，则此参数会自动从上游获取，无需手动填写；如果单独使用此函数(没有上游连接)，则必须手动填写电解液瓶数
                   type: string
                 elec_use_num:
-                  description: 每瓶电解液组装的电池数
+                  description: 每瓶电解液组装电池数
                   type: string
                 elec_vol:
                   default: 50
-                  description: 电解液吸液量 (μL)
+                  description: 电解液吸液量(μL)
                   type: integer
                 file_path:
                   default: /Users/sml/work
@@ -599,7 +593,7 @@ coincellassemblyworkstation_device:
                   type: string
                 fujipian_juzhendianwei:
                   default: 0
-                  description: 负极片矩阵点位
+                  description: 负极片矩阵点位。盘位置从1开始计数，有效范围：1-8, 13-20 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
                 fujipian_panshu:
                   default: 0
@@ -607,7 +601,7 @@ coincellassemblyworkstation_device:
                   type: integer
                 gemo_juzhendianwei:
                   default: 0
-                  description: 隔膜矩阵点位
+                  description: 隔膜矩阵点位。盘位置从1开始计数，有效范围：1-8, 13-20 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
                 gemopanshu:
                   default: 0
@@ -619,7 +613,7 @@ coincellassemblyworkstation_device:
                   type: boolean
                 qiangtou_juzhendianwei:
                   default: 0
-                  description: 枪头盒矩阵点位
+                  description: 枪头盒矩阵点位。盘位置从1开始计数，有效范围：1-32, 64-96 (写入值比实际位置少1，例如：写0取盘位1，写1取盘位2)
                   type: integer
               required:
               - elec_num

unilabos/registry/devices/laiyu_liquid_test.yaml

@@ -18,7 +18,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 degrees:
-                  description: 角度值
                   type: number
               required:
               - degrees
@@ -45,7 +44,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 axis:
-                  description: 电机轴
                   type: object
               required:
               - axis
@@ -73,7 +71,6 @@ xyz_stepper_controller:
               properties:
                 enable:
                   default: true
-                  description: True为使能，False为失能
                   type: boolean
               required: []
               type: object
@@ -102,11 +99,9 @@ xyz_stepper_controller:
             goal:
               properties:
                 axis:
-                  description: 电机轴
                   type: object
                 enable:
                   default: true
-                  description: True为使能，False为失能
                   type: boolean
               required:
               - axis
@@ -157,7 +152,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 axis:
-                  description: 电机轴
                   type: object
               required:
               - axis
@@ -189,21 +183,16 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度(rpm/s)
                   type: integer
                 axis:
-                  description: 电机轴
                   type: object
                 position:
-                  description: 目标位置(步数)
                   type: integer
                 precision:
                   default: 100
-                  description: 到位精度
                   type: integer
                 speed:
                   default: 5000
-                  description: 运行速度(rpm)
                   type: integer
               required:
               - axis
@@ -236,21 +225,16 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度
                   type: integer
                 axis:
-                  description: 电机轴
                   type: object
                 degrees:
-                  description: 目标角度（度）
                   type: number
                 precision:
                   default: 100
-                  description: 精度
                   type: integer
                 speed:
                   default: 5000
-                  description: 移动速度
                   type: integer
               required:
               - axis
@@ -283,21 +267,16 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度
                   type: integer
                 axis:
-                  description: 电机轴
                   type: object
                 precision:
                   default: 100
-                  description: 精度
                   type: integer
                 revolutions:
-                  description: 目标圈数
                   type: number
                 speed:
                   default: 5000
-                  description: 移动速度
                   type: integer
               required:
               - axis
@@ -330,20 +309,15 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度
                   type: integer
                 speed:
                   default: 5000
-                  description: 运行速度
                   type: integer
                 x:
-                  description: X轴目标位置
                   type: integer
                 y:
-                  description: Y轴目标位置
                   type: integer
                 z:
-                  description: Z轴目标位置
                   type: integer
               required: []
               type: object
@@ -376,20 +350,15 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度
                   type: integer
                 speed:
                   default: 5000
-                  description: 移动速度
                   type: integer
                 x_deg:
-                  description: X轴目标角度（度）
                   type: number
                 y_deg:
-                  description: Y轴目标角度（度）
                   type: number
                 z_deg:
-                  description: Z轴目标角度（度）
                   type: number
               required: []
               type: object
@@ -422,20 +391,15 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度
                   type: integer
                 speed:
                   default: 5000
-                  description: 移动速度
                   type: integer
                 x_rev:
-                  description: X轴目标圈数
                   type: number
                 y_rev:
-                  description: Y轴目标圈数
                   type: number
                 z_rev:
-                  description: Z轴目标圈数
                   type: number
               required: []
               type: object
@@ -463,7 +427,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 revolutions:
-                  description: 圈数
                   type: number
               required:
               - revolutions
@@ -493,13 +456,10 @@ xyz_stepper_controller:
               properties:
                 acceleration:
                   default: 1000
-                  description: 加速度(rpm/s)
                   type: integer
                 axis:
-                  description: 电机轴
                   type: object
                 speed:
-                  description: 运行速度(rpm)，正值正转，负值反转
                   type: integer
               required:
               - axis
@@ -527,7 +487,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 steps:
-                  description: 步数
                   type: integer
               required:
               - steps
@@ -554,7 +513,6 @@ xyz_stepper_controller:
             goal:
               properties:
                 steps:
-                  description: 步数
                   type: integer
               required:
               - steps
@@ -606,11 +564,9 @@ xyz_stepper_controller:
             goal:
               properties:
                 axis:
-                  description: 电机轴
                   type: object
                 timeout:
                   default: 30.0
-                  description: 超时时间(秒)
                   type: number
               required:
               - axis
@@ -635,14 +591,11 @@ xyz_stepper_controller:
       properties:
         baudrate:
           default: 115200
-          description: 波特率
           type: integer
         port:
-          description: 串口端口名
           type: string
         timeout:
           default: 1.0
-          description: 通信超时时间
           type: number
       required:
       - port

unilabos/registry/devices/liquid_handler.yaml

@@ -510,11 +510,9 @@ liquid_handler:
             goal:
               properties:
                 msg:
-                  description: information to be printed
                   type: string
                 seconds:
                   default: 0
-                  description: seconds to wait
                   type: string
               required: []
               type: object
@@ -2965,22 +2963,15 @@ liquid_handler:
               additionalProperties: false
               properties:
                 channel:
-                  description: int
                   maximum: 2147483647
                   minimum: -2147483648
                   type: integer
                 dis_to_top:
-                  description: 'float
-
-                    Height in mm to move to relative to the well top.'
                   maximum: 1.7976931348623157e+308
                   minimum: -1.7976931348623157e+308
                   type: number
                 well:
                   additionalProperties: false
-                  description: 'Well
-
-                    The target well.'
                   properties:
                     category:
                       type: string
@@ -4838,13 +4829,11 @@ liquid_handler:
     config:
       properties:
         backend:
-          description: Backend to use.
           type: object
         channel_num:
           default: 8
           type: integer
         deck:
-          description: Deck to use.
           type: object
         simulator:
           default: false
@@ -4894,17 +4883,14 @@ liquid_handler.biomek:
                 bind_parent_id:
                   type: string
                 liquid_input_slot:
-                  description: 液体输入槽列表
                   items:
                     type: integer
                   type: array
                 liquid_type:
-                  description: 液体类型列表
                   items:
                     type: string
                   type: array
                 liquid_volume:
-                  description: 液体体积列表
                   items:
                     type: integer
                   type: array
@@ -4915,7 +4901,6 @@ liquid_handler.biomek:
                     type: object
                   type: array
                 slot_on_deck:
-                  description: 甲板上的槽位
                   type: integer
               required:
               - resource_tracker
@@ -5051,27 +5036,20 @@ liquid_handler.biomek:
               additionalProperties: false
               properties:
                 none_keys:
-                  description: 需要设置为None的键列表
                   items:
                     type: string
                   type: array
                 protocol_author:
-                  description: 协议作者
                   type: string
                 protocol_date:
-                  description: 协议日期
                   type: string
                 protocol_description:
-                  description: 协议描述
                   type: string
                 protocol_name:
-                  description: 协议名称
                   type: string
                 protocol_type:
-                  description: 协议类型
                   type: string
                 protocol_version:
-                  description: 协议版本
                   type: string
               title: LiquidHandlerProtocolCreation_Goal
               type: object
@@ -6995,7 +6973,7 @@ liquid_handler.laiyu:
       properties:
         channel_num:
           default: 1
-          type: string
+          type: integer
         deck:
           type: object
         host:
@@ -7006,10 +6984,25 @@ liquid_handler.laiyu:
           type: integer
         simulator:
           default: true
-          type: string
+          type: boolean
         timeout:
           default: 10.0
           type: number
+        serial_port:
+          default: /dev/ttyUSB0
+          description: 硬件串口端口（非 simulator 模式下使用）
+          type: string
+        baudrate:
+          default: 115200
+          type: integer
+        pipette_address:
+          default: 4
+          description: SOPA 移液器 RS485 地址
+          type: integer
+        total_height:
+          default: 310
+          description: 龙门架总高度 (mm)，用于坐标转换
+          type: number
       required:
       - deck
       type: object

unilabos/registry/devices/motor.yaml

@@ -0,0 +1,286 @@
+motor.zdt_x42:
+  category:
+  - motor
+  class:
+    action_value_mappings:
+      auto-enable:
+        feedback: {}
+        goal: {}
+        goal_default:
+          'on': true
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 使能或禁用电机。使能后电机进入锁轴状态，可接收运动指令；禁用后电机进入松轴状态。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                'on':
+                  default: true
+                  type: boolean
+              required: []
+              type: object
+            result: {}
+          required:
+          - goal
+          title: enable参数
+          type: object
+        type: UniLabJsonCommand
+      auto-get_position:
+        feedback: {}
+        goal: {}
+        goal_default: {}
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 获取当前电机脉冲位置。
+          properties:
+            feedback: {}
+            goal:
+              properties: {}
+              required: []
+              type: object
+            result:
+              properties:
+                position:
+                  type: integer
+              type: object
+          required:
+          - goal
+          title: get_position参数
+          type: object
+        type: UniLabJsonCommand
+      auto-move_position:
+        feedback: {}
+        goal: {}
+        goal_default:
+          absolute: false
+          acceleration: 10
+          direction: CW
+          pulses: 1000
+          speed_rpm: 60
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 位置模式运行。控制电机移动到指定脉冲位置或相对于当前位置移动指定脉冲数。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                absolute:
+                  default: false
+                  type: boolean
+                acceleration:
+                  default: 10
+                  maximum: 255
+                  minimum: 0
+                  type: integer
+                direction:
+                  default: CW
+                  enum:
+                  - CW
+                  - CCW
+                  type: string
+                pulses:
+                  default: 1000
+                  type: integer
+                speed_rpm:
+                  default: 60
+                  minimum: 0
+                  type: integer
+              required:
+              - pulses
+              - speed_rpm
+              type: object
+            result: {}
+          required:
+          - goal
+          title: move_position参数
+          type: object
+        type: UniLabJsonCommand
+      auto-move_speed:
+        feedback: {}
+        goal: {}
+        goal_default:
+          acceleration: 10
+          direction: CW
+          speed_rpm: 60
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 速度模式运行。控制电机以指定转速和方向持续转动。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                acceleration:
+                  default: 10
+                  maximum: 255
+                  minimum: 0
+                  type: integer
+                direction:
+                  default: CW
+                  enum:
+                  - CW
+                  - CCW
+                  type: string
+                speed_rpm:
+                  default: 60
+                  minimum: 0
+                  type: integer
+              required:
+              - speed_rpm
+              type: object
+            result: {}
+          required:
+          - goal
+          title: move_speed参数
+          type: object
+        type: UniLabJsonCommand
+      auto-rotate_quarter:
+        feedback: {}
+        goal: {}
+        goal_default:
+          direction: CW
+          speed_rpm: 60
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 电机旋转 1/4 圈 (阻塞式)。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                direction:
+                  default: CW
+                  enum:
+                  - CW
+                  - CCW
+                  type: string
+                speed_rpm:
+                  default: 60
+                  minimum: 1
+                  type: integer
+              required: []
+              type: object
+            result: {}
+          required:
+          - goal
+          title: rotate_quarter参数
+          type: object
+        type: UniLabJsonCommand
+      auto-set_zero:
+        feedback: {}
+        goal: {}
+        goal_default: {}
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 将当前电机位置设为零点。
+          properties:
+            feedback: {}
+            goal:
+              properties: {}
+              required: []
+              type: object
+            result: {}
+          required:
+          - goal
+          title: set_zero参数
+          type: object
+        type: UniLabJsonCommand
+      auto-stop:
+        feedback: {}
+        goal: {}
+        goal_default: {}
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 立即停止电机运动。
+          properties:
+            feedback: {}
+            goal:
+              properties: {}
+              required: []
+              type: object
+            result: {}
+          required:
+          - goal
+          title: stop参数
+          type: object
+        type: UniLabJsonCommand
+      auto-wait_time:
+        feedback: {}
+        goal: {}
+        goal_default:
+          duration_s: 1.0
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 等待指定时间 (秒)。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                duration_s:
+                  default: 1.0
+                  minimum: 0
+                  type: number
+              required:
+              - duration_s
+              type: object
+            result: {}
+          required:
+          - goal
+          title: wait_time参数
+          type: object
+        type: UniLabJsonCommand
+    module: unilabos.devices.motor.ZDT_X42:ZDTX42Driver
+    status_types:
+      position: int
+      status: str
+    type: python
+  config_info: []
+  description: ZDT X42 闭环步进电机驱动。支持速度运行、精确位置控制、位置查询和清零功能。适用于各种需要精确运动控制的实验室自动化场景。
+  handles: []
+  icon: ''
+  init_param_schema:
+    config:
+      properties:
+        baudrate:
+          default: 115200
+          type: integer
+        debug:
+          default: false
+          type: boolean
+        device_id:
+          default: 1
+          type: integer
+        port:
+          type: string
+        timeout:
+          default: 0.5
+          type: number
+      required:
+      - port
+      type: object
+    data:
+      properties:
+        position:
+          type: integer
+        status:
+          type: string
+      required:
+      - status
+      - position
+      type: object
+  version: 1.0.0

unilabos/registry/devices/neware_battery_test_system.yaml

@@ -87,7 +87,7 @@ neware_battery_test_system:
               properties:
                 filepath:
                   default: bts_status.json
-                  description: 输出文件路径
+                  description: 输出JSON文件路径
                   type: string
               required: []
               type: object
@@ -146,7 +146,7 @@ neware_battery_test_system:
             goal:
               properties:
                 plate_num:
-                  description: 盘号 (1 或 2)，如果为None则返回所有盘的状态
+                  description: 盘号 (1 或 2)，如果为null则返回所有盘的状态
                   type: integer
               required: []
               type: object
@@ -237,11 +237,11 @@ neware_battery_test_system:
             goal:
               properties:
                 csv_path:
-                  description: 输入CSV文件路径
+                  description: 输入CSV文件的绝对路径
                   type: string
                 output_dir:
                   default: .
-                  description: 输出目录，用于存储XML文件和备份，默认当前目录
+                  description: 输出目录（用于存储XML和备份文件），默认当前目录
                   type: string
               required:
               - csv_path
@@ -302,14 +302,14 @@ neware_battery_test_system:
             goal:
               properties:
                 backup_dir:
-                  description: 备份目录路径，默认使用最近一次 submit_from_csv 的 backup_dir
+                  description: 备份目录路径（默认使用最近一次submit_from_csv的backup_dir）
                   type: string
                 file_pattern:
                   default: '*'
-                  description: 文件通配符模式，默认 "*" 上传所有文件（例如 "*.csv" 仅上传 CSV 文件）
+                  description: 文件通配符模式，例如 *.csv 或 Battery_*.nda
                   type: string
                 oss_prefix:
-                  description: OSS 对象前缀，默认使用类初始化时的配置
+                  description: OSS对象路径前缀（默认使用self.oss_prefix）
                   type: string
               required: []
               type: object
@@ -336,25 +336,19 @@ neware_battery_test_system:
     config:
       properties:
         devtype:
-          description: 设备类型标识
           type: string
         ip:
-          description: TCP服务器IP地址
           type: string
         machine_id:
           default: 1
-          description: 机器ID
           type: integer
         oss_prefix:
           default: neware_backup
-          description: OSS对象路径前缀，默认"neware_backup"
           type: string
         oss_upload_enabled:
           default: false
-          description: 是否启用OSS上传功能，默认False
           type: boolean
         port:
-          description: TCP端口
           type: integer
         size_x:
           default: 50
@@ -366,7 +360,6 @@ neware_battery_test_system:
           default: 20
           type: number
         timeout:
-          description: 通信超时时间（秒）
           type: integer
       required: []
       type: object

unilabos/registry/devices/organic_miscellaneous.yaml

@@ -207,12 +207,8 @@ separator.homemade:
             goal:
               properties:
                 condition:
-                  description: The condition to be monitored, either 'delta' or 'time'.
                   type: string
                 value:
-                  description: 'The threshold value for the condition.
-
-                    `delta > 0.05`, `time > 60`'
                   type: string
               required:
               - condition
@@ -309,17 +305,12 @@ separator.homemade:
                 event:
                   type: string
                 settling_time:
-                  description: The duration for which to settle after stirring, in
-                    seconds. Defaults to 10.
                   type: string
                 stir_speed:
-                  description: The speed of stirring, in RPM. Defaults to 300.
                   maximum: 1.7976931348623157e+308
                   minimum: -1.7976931348623157e+308
                   type: number
                 stir_time:
-                  description: The duration for which to stir, in seconds. Defaults
-                    to 10.
                   maximum: 1.7976931348623157e+308
                   minimum: -1.7976931348623157e+308
                   type: number

unilabos/registry/devices/pump_and_valve.yaml

@@ -456,7 +456,6 @@ syringe_pump_with_valve.runze.SY03B-T06:
             goal:
               properties:
                 volume:
-                  description: 'absolute position of the plunger, unit: mL'
                   type: number
               required:
               - volume
@@ -482,7 +481,6 @@ syringe_pump_with_valve.runze.SY03B-T06:
             goal:
               properties:
                 volume:
-                  description: 'absolute position of the plunger, unit: mL'
                   type: number
               required:
               - volume
@@ -689,10 +687,8 @@ syringe_pump_with_valve.runze.SY03B-T06:
             goal:
               properties:
                 max_velocity:
-                  description: 'maximum velocity of the plunger, unit: ml/s'
                   type: number
                 position:
-                  description: 'absolute position of the plunger, unit: ml'
                   type: number
               required:
               - position
@@ -1007,7 +1003,6 @@ syringe_pump_with_valve.runze.SY03B-T08:
             goal:
               properties:
                 volume:
-                  description: 'absolute position of the plunger, unit: mL'
                   type: number
               required:
               - volume
@@ -1033,7 +1028,6 @@ syringe_pump_with_valve.runze.SY03B-T08:
             goal:
               properties:
                 volume:
-                  description: 'absolute position of the plunger, unit: mL'
                   type: number
               required:
               - volume
@@ -1240,10 +1234,8 @@ syringe_pump_with_valve.runze.SY03B-T08:
             goal:
               properties:
                 max_velocity:
-                  description: 'maximum velocity of the plunger, unit: ml/s'
                   type: number
                 position:
-                  description: 'absolute position of the plunger, unit: ml'
                   type: number
               required:
               - position

unilabos/registry/devices/reaction_station_bioyond.yaml

@@ -32,7 +32,7 @@ reaction_station.bioyond:
                   type: integer
                 end_point:
                   default: 0
-                  description: 终点计时点 (Start=0, End=1)
+                  description: 终点计时点 (Start=开始前, End=结束后)
                   type: integer
                 end_step_key:
                   default: ''
@@ -40,11 +40,11 @@ reaction_station.bioyond:
                   type: string
                 start_point:
                   default: 0
-                  description: 起点计时点 (Start=0, End=1)
+                  description: 起点计时点 (Start=开始前, End=结束后)
                   type: integer
                 start_step_key:
                   default: ''
-                  description: 起点步骤Key (可选, 默认为空则自动选择)
+                  description: 起点步骤Key (例如 "feeding", "liquid", 可选, 默认为空则自动选择)
                   type: string
               required:
               - duration
@@ -91,7 +91,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 json_str:
-                  description: 订单参数的JSON字符串
                   type: string
               required:
               - json_str
@@ -118,7 +117,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 workflow_ids:
-                  description: 要删除的工作流ID数组
                   items:
                     type: string
                   type: array
@@ -147,7 +145,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 json_str:
-                  description: 'JSON格式的字符串,包含:'
                   type: string
               required:
               - json_str
@@ -200,7 +197,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 web_workflow_json:
-                  description: JSON 格式的网页工作流列表
                   type: string
               required:
               - web_workflow_json
@@ -232,10 +228,8 @@ reaction_station.bioyond:
             goal:
               properties:
                 reactor_id:
-                  description: 反应器编号 (1-5)
                   type: integer
                 temperature:
-                  description: 目标温度 (°C)
                   type: number
               required:
               - reactor_id
@@ -263,7 +257,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 preintake_id:
-                  description: 通量ID
                   type: string
               required:
               - preintake_id
@@ -345,7 +338,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 value:
-                  description: 工作流 ID 列表
                   items:
                     type: string
                   type: array
@@ -373,7 +365,6 @@ reaction_station.bioyond:
             goal:
               properties:
                 workflow_id:
-                  description: 工作流ID
                   type: string
               required:
               - workflow_id
@@ -433,11 +424,11 @@ reaction_station.bioyond:
             goal:
               properties:
                 assign_material_name:
-                  description: 物料名称(液体种类)
+                  description: 物料名称（不能为空）
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度(C)
+                  description: 温度设定(°C)
                   type: number
                 time:
                   default: '90'
@@ -445,14 +436,14 @@ reaction_station.bioyond:
                   type: string
                 titration_type:
                   default: '1'
-                  description: 是否滴定(NO=1, YES=2)
+                  description: 是否滴定(NO=否, YES=是)
                   type: string
                 torque_variation:
                   default: 2
-                  description: 是否观察(NO=1, YES=2)
+                  description: 是否观察 (NO=否, YES=是)
                   type: integer
                 volume:
-                  description: 分液量(μL)
+                  description: 分液公式(mL)
                   type: string
               required:
               - assign_material_name
@@ -534,11 +525,11 @@ reaction_station.bioyond:
               properties:
                 assign_material_name:
                   default: BAPP
-                  description: 物料名称(试剂瓶位)
+                  description: 物料名称
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度设定(C)
+                  description: 温度设定(°C)
                   type: number
                 time:
                   default: '0'
@@ -546,15 +537,15 @@ reaction_station.bioyond:
                   type: string
                 titration_type:
                   default: '1'
-                  description: 是否滴定(NO=1, YES=2)
+                  description: 是否滴定(NO=否, YES=是)
                   type: string
                 torque_variation:
                   default: 1
-                  description: 是否观察(int类型, 1=否, 2=是)
+                  description: 是否观察 (NO=否, YES=是)
                   type: integer
                 volume:
                   default: '350'
-                  description: 分液质量(g)
+                  description: 分液公式(mL)
                   type: string
               required: []
               type: object
@@ -602,28 +593,26 @@ reaction_station.bioyond:
                   description: 物料名称
                   type: string
                 solvents:
-                  description: '溶剂信息的字典或JSON字符串(可选),格式如下:
-
-                    {'
+                  description: '溶剂信息对象(可选),包含: additional_solvent(溶剂体积mL), total_liquid_volume(总液体体积mL)。如果提供,将自动计算volume'
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度设定(C)
+                  description: 温度设定(°C),默认25.00
                   type: number
                 time:
                   default: '360'
-                  description: 观察时间(分钟)
+                  description: 观察时间(分钟),默认360
                   type: string
                 titration_type:
                   default: '1'
-                  description: 是否滴定(NO=1, YES=2)
+                  description: 是否滴定(NO=否, YES=是),默认NO
                   type: string
                 torque_variation:
                   default: 2
-                  description: 是否观察(NO=1, YES=2)
+                  description: 是否观察 (NO=否, YES=是),默认YES
                   type: integer
                 volume:
-                  description: 分液量(μL),直接指定体积(可选,如果提供solvents则自动计算)
+                  description: 分液量(mL)。可直接提供,或通过solvents参数自动计算
                   type: string
               required:
               - assign_material_name
@@ -682,32 +671,33 @@ reaction_station.bioyond:
                   description: 物料名称
                   type: string
                 extracted_actuals:
-                  description: 从报告提取的实际加料量JSON字符串,包含actualTargetWeigh和actualVolume
+                  description: 从报告提取的实际加料量JSON字符串,包含actualTargetWeigh(m二酐滴定)和actualVolume(V二酐滴定)
                   type: string
                 feeding_order_data:
-                  description: feeding_order JSON字符串或对象,用于获取m二酐值
+                  description: 'feeding_order JSON对象,用于获取m二酐值(type为main_anhydride的amount)。示例:
+                    {"feeding_order": [{"type": "main_anhydride", "amount": 1.915}]}'
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度(C)
+                  description: 温度设定(°C),默认25.00
                   type: number
                 time:
                   default: '90'
-                  description: 观察时间(分钟)
+                  description: 观察时间(分钟),默认90
                   type: string
                 titration_type:
                   default: '2'
-                  description: 是否滴定(NO=1, YES=2),默认2
+                  description: 是否滴定(NO=否, YES=是),默认YES
                   type: string
                 torque_variation:
                   default: 2
-                  description: 是否观察(NO=1, YES=2)
+                  description: 是否观察 (NO=否, YES=是),默认YES
                   type: integer
                 volume_formula:
-                  description: 分液公式(μL),如果提供则直接使用,否则自动计算
+                  description: 分液公式(mL)。可直接提供固定公式,或留空由系统根据x_value、feeding_order_data、extracted_actuals自动生成
                   type: string
                 x_value:
-                  description: 手工输入的x值,格式如 "1-2-3"
+                  description: 公式中的x值,手工输入,格式为"{{1-2-3}}"(包含双花括号)。用于自动公式计算
                   type: string
               required:
               - assign_material_name
@@ -748,7 +738,7 @@ reaction_station.bioyond:
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度(C)
+                  description: 温度设定(°C)
                   type: number
                 time:
                   default: '0'
@@ -756,14 +746,14 @@ reaction_station.bioyond:
                   type: string
                 titration_type:
                   default: '1'
-                  description: 是否滴定(NO=1, YES=2)
+                  description: 是否滴定(NO=否, YES=是)
                   type: string
                 torque_variation:
                   default: 1
-                  description: 是否观察(NO=1, YES=2)
+                  description: 是否观察 (NO=否, YES=是)
                   type: integer
                 volume_formula:
-                  description: 分液公式(μL)
+                  description: 分液公式(mL)
                   type: string
               required:
               - volume_formula
@@ -796,7 +786,7 @@ reaction_station.bioyond:
                   description: 任务名称
                   type: string
                 workflow_name:
-                  description: 合并后的工作流名称
+                  description: 工作流名称
                   type: string
               required:
               - workflow_name
@@ -829,15 +819,15 @@ reaction_station.bioyond:
             goal:
               properties:
                 assign_material_name:
-                  description: 物料名称(不能为空)
+                  description: 物料名称
                   type: string
                 cutoff:
                   default: '900000'
-                  description: 粘度上限(需为有效数字字符串,默认 "900000")
+                  description: 粘度上限
                   type: string
                 temperature:
                   default: -10.0
-                  description: 温度设定(C,范围:-50.00 至 100.00)
+                  description: 温度设定(°C)
                   type: number
               required:
               - assign_material_name
@@ -919,11 +909,11 @@ reaction_station.bioyond:
                   description: 物料名称(用于获取试剂瓶位ID)
                   type: string
                 material_id:
-                  description: 粉末类型ID, Salt=1, Flour=2, BTDA=3
+                  description: 粉末类型ID，Salt=盐（21分钟），Flour=面粉（27分钟），BTDA=BTDA（38分钟）
                   type: string
                 temperature:
                   default: 25.0
-                  description: 温度设定(C)
+                  description: 温度设定(°C)
                   type: number
                 time:
                   default: '0'
@@ -931,7 +921,7 @@ reaction_station.bioyond:
                   type: string
                 torque_variation:
                   default: 1
-                  description: 是否观察(NO=1, YES=2)
+                  description: 是否观察 (NO=否, YES=是)
                   type: integer
               required:
               - material_id
@@ -955,13 +945,10 @@ reaction_station.bioyond:
     config:
       properties:
         config:
-          description: 配置字典,应包含workflow_mappings等配置
           type: object
         deck:
-          description: Deck对象
           type: string
         protocol_type:
-          description: 协议类型(由ROS系统传递,此处忽略)
           type: string
       required: []
       type: object

unilabos/registry/devices/robot_arm.yaml

@@ -198,8 +198,6 @@ robotic_arm.SCARA_with_slider.moveit.virtual:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes option, target,
-                    speed, lift_height, mt_height
                   type: string
               title: SendCmd_Goal
               type: object
@@ -243,8 +241,6 @@ robotic_arm.SCARA_with_slider.moveit.virtual:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes quaternion, speed,
-                    position
                   type: string
               title: SendCmd_Goal
               type: object
@@ -288,7 +284,6 @@ robotic_arm.SCARA_with_slider.moveit.virtual:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes speed
                   type: string
               title: SendCmd_Goal
               type: object

unilabos/registry/devices/robot_linear_motion.yaml

@@ -709,8 +709,6 @@ linear_motion.toyo_xyz.sim:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes option, target,
-                    speed, lift_height, mt_height
                   type: string
               title: SendCmd_Goal
               type: object
@@ -754,8 +752,6 @@ linear_motion.toyo_xyz.sim:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes quaternion, speed,
-                    position
                   type: string
               title: SendCmd_Goal
               type: object
@@ -799,7 +795,6 @@ linear_motion.toyo_xyz.sim:
               additionalProperties: false
               properties:
                 command:
-                  description: A JSON-formatted string that includes speed
                   type: string
               title: SendCmd_Goal
               type: object

unilabos/registry/devices/sensor.yaml

@@ -0,0 +1,148 @@
+sensor.xkc_rs485:
+  category:
+  - sensor
+  - separator
+  class:
+    action_value_mappings:
+      auto-change_baudrate:
+        goal:
+          baud_code: 7
+        handles: {}
+        schema:
+          description: '更改通讯波特率 (设置成功后无返回，且需手动切换波特率重连)。代码表 (16进制): 05=2400, 06=4800,
+            07=9600, 08=14400, 09=19200, 0A=28800, 0C=57600, 0D=115200, 0E=128000,
+            0F=256000'
+          properties:
+            goal:
+              properties:
+                baud_code:
+                  description: '波特率代码 (例如: 7 为 9600, 13 即 0x0D 为 115200)'
+                  type: integer
+              required:
+              - baud_code
+              type: object
+        type: UniLabJsonCommand
+      auto-change_device_id:
+        goal:
+          new_id: 1
+        handles: {}
+        schema:
+          description: 修改传感器的 Modbus 从站地址
+          properties:
+            goal:
+              properties:
+                new_id:
+                  description: 新的从站地址 (1-254)
+                  maximum: 254
+                  minimum: 1
+                  type: integer
+              required:
+              - new_id
+              type: object
+        type: UniLabJsonCommand
+      auto-factory_reset:
+        goal: {}
+        handles: {}
+        schema:
+          description: 恢复出厂设置 (地址重置为 01)
+          properties:
+            goal:
+              type: object
+        type: UniLabJsonCommand
+      auto-read_level:
+        goal: {}
+        handles: {}
+        schema:
+          description: 直接读取当前液位及信号强度
+          properties:
+            goal:
+              type: object
+          type: object
+        type: UniLabJsonCommand
+      auto-set_threshold:
+        goal:
+          threshold: 300
+        handles: {}
+        schema:
+          description: 设置液位判定阈值
+          properties:
+            goal:
+              properties:
+                threshold:
+                  type: integer
+              required:
+              - threshold
+              type: object
+        type: UniLabJsonCommand
+      auto-wait_for_liquid:
+        goal:
+          target_state: true
+          timeout: 120
+        handles: {}
+        schema:
+          description: 实时检测电导率(RSSI)并等待用户指定的状态
+          properties:
+            goal:
+              properties:
+                target_state:
+                  default: true
+                  description: 目标状态 (True=有液, False=无液)
+                  type: boolean
+                timeout:
+                  default: 120
+                  description: 超时时间 (秒)
+              required:
+              - target_state
+              type: object
+        type: UniLabJsonCommand
+      auto-wait_level:
+        goal:
+          level: true
+          timeout: 10
+        handles: {}
+        schema:
+          description: 等待液位达到目标状态
+          properties:
+            goal:
+              properties:
+                level:
+                  type: boolean
+                timeout:
+                  type: number
+              required:
+              - level
+              type: object
+        type: UniLabJsonCommand
+    module: unilabos.devices.separator.xkc_sensor:XKCSensorDriver
+    status_types:
+      level: bool
+      rssi: int
+    type: python
+  config_info: []
+  description: XKC RS485 非接触式液位传感器 (Modbus RTU)
+  handles: []
+  icon: ''
+  init_param_schema:
+    config:
+      properties:
+        baudrate:
+          default: 9600
+          type: integer
+        debug:
+          default: false
+          type: boolean
+        device_id:
+          default: 1
+          type: integer
+        port:
+          type: string
+        threshold:
+          default: 300
+          type: integer
+        timeout:
+          default: 3.0
+          type: number
+      required:
+      - port
+      type: object
+  version: 1.0.0

unilabos/registry/devices/virtual_device.yaml

@@ -2179,7 +2179,6 @@ virtual_multiway_valve:
             goal:
               properties:
                 port_number:
-                  description: 端口号 (1-8)
                   type: integer
               required:
               - port_number
@@ -2226,7 +2225,6 @@ virtual_multiway_valve:
             goal:
               properties:
                 port_number:
-                  description: 目标端口号 (1-8)
                   type: integer
               required:
               - port_number
@@ -2263,7 +2261,6 @@ virtual_multiway_valve:
               additionalProperties: false
               properties:
                 command:
-                  description: 目标位置 (0-8) 或位置字符串
                   type: string
               title: SendCmd_Goal
               type: object
@@ -2307,7 +2304,6 @@ virtual_multiway_valve:
               additionalProperties: false
               properties:
                 command:
-                  description: 目标位置 (0-8) 或位置字符串
                   type: string
               title: SendCmd_Goal
               type: object
@@ -4219,7 +4215,6 @@ virtual_solenoid_valve:
               additionalProperties: false
               properties:
                 string:
-                  description: '"ON"/"OFF" 或 "OPEN"/"CLOSED"'
                   type: string
               title: StrSingleInput_Goal
               type: object
@@ -4263,7 +4258,6 @@ virtual_solenoid_valve:
               additionalProperties: false
               properties:
                 command:
-                  description: '"OPEN"/"CLOSED" 或其他控制命令'
                   type: string
               title: SendCmd_Goal
               type: object
@@ -4424,20 +4418,16 @@ virtual_solid_dispenser:
                 event:
                   type: string
                 mass:
-                  description: 质量字符串 (如 "2.9 g")
                   type: string
                 mol:
-                  description: 摩尔数字符串 (如 "0.12 mol")
                   type: string
                 purpose:
-                  description: 添加目的
                   type: string
                 rate_spec:
                   type: string
                 ratio:
                   type: string
                 reagent:
-                  description: 试剂名称
                   type: string
                 stir:
                   type: boolean
@@ -4449,7 +4439,6 @@ virtual_solid_dispenser:
                   type: string
                 vessel:
                   additionalProperties: false
-                  description: 目标容器
                   properties:
                     category:
                       type: string
@@ -5579,10 +5568,8 @@ virtual_transfer_pump:
             goal:
               properties:
                 velocity:
-                  description: 拉取速度 (ml/s)
                   type: number
                 volume:
-                  description: 要拉取的体积 (ml)
                   type: number
               required:
               - volume
@@ -5609,10 +5596,8 @@ virtual_transfer_pump:
             goal:
               properties:
                 velocity:
-                  description: 推出速度 (ml/s)
                   type: number
                 volume:
-                  description: 要推出的体积 (ml)
                   type: number
               required:
               - volume
@@ -5708,12 +5693,10 @@ virtual_transfer_pump:
               additionalProperties: false
               properties:
                 max_velocity:
-                  description: 移动速度 (ml/s)
                   maximum: 1.7976931348623157e+308
                   minimum: -1.7976931348623157e+308
                   type: number
                 position:
-                  description: 目标位置 (ml)
                   maximum: 1.7976931348623157e+308
                   minimum: -1.7976931348623157e+308
                   type: number
@@ -5862,10 +5845,8 @@ virtual_transfer_pump:
     config:
       properties:
         config:
-          description: 配置字典，包含max_volume, port等参数
           type: object
         device_id:
-          description: 设备ID
           type: string
       required: []
       type: object

unilabos/registry/devices/xrd_d7mate.yaml

@@ -409,11 +409,11 @@ xrd_d7mate:
               properties:
                 end_theta:
                   default: 80.0
-                  description: 结束角度（≥5.5°，且必须大于 start_theta）
+                  description: 结束角度（≥5.5°，且必须大于start_theta）
                   type: number
                 exp_time:
                   default: 0.1
-                  description: 曝光时间（0.1-5.0 秒）
+                  description: 曝光时间（0.1-5.0秒）
                   type: number
                 increment:
                   default: 0.05
@@ -421,7 +421,7 @@ xrd_d7mate:
                   type: number
                 sample_id:
                   default: ''
-                  description: 样品名称
+                  description: 样品标识符
                   type: string
                 start_theta:
                   default: 10.0
@@ -433,7 +433,7 @@ xrd_d7mate:
                   type: string
                 wait_minutes:
                   default: 3.0
-                  description: 在允许上样后、发送样品准备完成前的等待分钟数（默认 3 分钟）
+                  description: 允许上样后等待分钟数
                   type: number
               required: []
               title: StartWorkflow_Goal
@@ -492,15 +492,12 @@ xrd_d7mate:
       properties:
         host:
           default: 127.0.0.1
-          description: 设备IP地址
           type: string
         port:
           default: 6001
-          description: 通信端口，默认6001
           type: string
         timeout:
           default: 10.0
-          description: 超时时间，单位秒
           type: string
       required: []
       type: object

unilabos/registry/devices/zhida_gcms.yaml

@@ -217,7 +217,6 @@ zhida_gcms:
               additionalProperties: false
               properties:
                 string:
-                  description: Base64编码的CSV数据（ROS2参数名）
                   type: string
               title: StrSingleInput_Goal
               type: object
@@ -258,7 +257,6 @@ zhida_gcms:
               additionalProperties: false
               properties:
                 string:
-                  description: CSV文件路径（ROS2参数名）
                   type: string
               title: StrSingleInput_Goal
               type: object
@@ -291,15 +289,12 @@ zhida_gcms:
       properties:
         host:
           default: 192.168.3.184
-          description: 设备IP地址，本地部署时可使用'127.0.0.1'
           type: string
         port:
           default: 5792
-          description: 通信端口，默认5792
           type: string
         timeout:
           default: 10.0
-          description: 超时时间，单位秒
           type: string
       required: []
       type: object

unilabos/registry/registry.py

@@ -271,7 +271,6 @@ class Registry:
         registry_cache.pkl 一个文件中，删除即可完全重置。
         """
         import time as _time
-        from unilabos.registry.ast_registry_scanner import _CACHE_VERSION as AST_SCAN_CACHE_VERSION
         from unilabos.registry.ast_registry_scanner import scan_directory
 
         scan_t0 = _time.perf_counter()
@@ -287,10 +286,6 @@ class Registry:
         # ---- 统一缓存：一个 pkl 包含所有数据 ----
         unified_cache = self._load_config_cache()
         ast_cache = unified_cache.setdefault("_ast_scan", {"files": {}})
-        if ast_cache.get("version") != AST_SCAN_CACHE_VERSION:
-            ast_cache = {"version": AST_SCAN_CACHE_VERSION, "files": {}}
-            unified_cache["_ast_scan"] = ast_cache
-            unified_cache.pop("_build_results", None)
 
         # 默认：扫描 unilabos 包所在的父目录
         pkg_root = Path(__file__).resolve().parent.parent          # .../unilabos
@@ -566,47 +561,13 @@ class Registry:
 
         return prop_schema
 
-    @staticmethod
-    def _apply_docstring_param_metadata(
-        schema: Dict[str, Any],
-        doc_info: Dict[str, Any],
-        field_to_param: Optional[Dict[str, str]] = None,
-        apply_defaults: bool = False,
-    ) -> None:
-        """Apply parsed docstring display names and descriptions to schema properties."""
-        if not schema or not doc_info:
-            return
-
-        props = schema.get("properties", {})
-        if not isinstance(props, dict):
-            return
-
-        param_descs = doc_info.get("params", {}) or {}
-        param_display_names = doc_info.get("param_display_names", {}) or {}
-        for field_name, prop_schema in props.items():
-            if not isinstance(prop_schema, dict):
-                continue
-            param_name = field_to_param.get(field_name, field_name) if field_to_param else field_name
-            if not isinstance(param_name, str):
-                continue
-            param_name = param_name.removesuffix("[]")
-            if param_name in param_display_names:
-                prop_schema["title"] = param_display_names[param_name]
-            elif apply_defaults and not prop_schema.get("title"):
-                prop_schema["title"] = field_name
-
-            if param_name in param_descs:
-                prop_schema["description"] = param_descs[param_name]
-            elif apply_defaults and "description" not in prop_schema:
-                prop_schema["description"] = ""
-
     def _generate_unilab_json_command_schema(
         self, method_args: list, docstring: Optional[str] = None,
         import_map: Optional[Dict[str, str]] = None,
-        apply_doc_defaults: bool = False,
     ) -> Dict[str, Any]:
         """根据方法参数和 docstring 生成 UniLabJsonCommand schema"""
         doc_info = parse_docstring(docstring)
+        param_descs = doc_info.get("params", {})
 
         schema = {
             "type": "object",
@@ -637,10 +598,12 @@ class Registry:
                     param_name, param_type, param_default, import_map=import_map
                 )
 
+            if param_name in param_descs:
+                schema["properties"][param_name]["description"] = param_descs[param_name]
+
             if param_required:
                 schema["required"].append(param_name)
 
-        self._apply_docstring_param_metadata(schema, doc_info, apply_defaults=apply_doc_defaults)
         return schema
 
     def _generate_status_types_schema(self, status_methods: Dict[str, Any]) -> Dict[str, Any]:
@@ -836,7 +799,6 @@ class Registry:
             type_str = "UniLabJsonCommandAsync" if is_async else "UniLabJsonCommand"
             params = method_info.get("params", [])
             method_doc = method_info.get("docstring")
-            method_doc_info = parse_docstring(method_doc)
             goal_schema = self._generate_schema_from_ast_params(params, method_name, method_doc, imap)
 
             if action_args is not None:
@@ -866,11 +828,7 @@ class Registry:
 
             # action handles: 从 @action(handles=[...]) 提取并转换为标准格式
             raw_handles = (action_args or {}).get("handles")
-            handles = (
-                normalize_ast_action_handles(raw_handles)
-                if isinstance(raw_handles, list)
-                else (raw_handles or {})
-            )
+            handles = normalize_ast_action_handles(raw_handles) if isinstance(raw_handles, list) else (raw_handles or {})
 
             # placeholder_keys: 先从参数类型自动检测，再用装饰器显式配置覆盖/补充
             pk = detect_placeholder_keys(params)
@@ -889,12 +847,7 @@ class Registry:
                 "goal": goal,
                 "feedback": (action_args or {}).get("feedback") or {},
                 "result": (action_args or {}).get("result") or {},
-                "schema": wrap_action_schema(
-                    goal_schema,
-                    action_name,
-                    description=(action_args or {}).get("description") or method_doc_info.get("description", ""),
-                    result_schema=result_schema,
-                ),
+                "schema": wrap_action_schema(goal_schema, action_name, result_schema=result_schema),
                 "goal_default": goal_default,
                 "handles": handles,
                 "placeholder_keys": pk,
@@ -933,11 +886,7 @@ class Registry:
                 action_name = f"auto-{action_name}"
 
             raw_handles = action_args.get("handles")
-            handles = (
-                normalize_ast_action_handles(raw_handles)
-                if isinstance(raw_handles, list)
-                else (raw_handles or {})
-            )
+            handles = normalize_ast_action_handles(raw_handles) if isinstance(raw_handles, list) else (raw_handles or {})
 
             method_params = method_info.get("params", [])
 
@@ -1030,10 +979,7 @@ class Registry:
                 "schema": schema,
                 "goal_default": goal_default,
                 "handles": handles,
-                "placeholder_keys": {
-                    **detect_placeholder_keys(method_params),
-                    **(action_args.get("placeholder_keys") or {}),
-                },
+                "placeholder_keys": {**detect_placeholder_keys(method_params), **(action_args.get("placeholder_keys") or {})},
             }
             if action_args.get("always_free") or method_info.get("always_free"):
                 action_entry["always_free"] = True
@@ -1042,22 +988,13 @@ class Registry:
             nt = normalize_enum_value(action_args.get("node_type"), NodeType)
             if nt:
                 action_entry["node_type"] = nt
-            goal_schema_for_docs = action_entry.get("schema", {}).get("properties", {}).get("goal", {})
-            self._apply_docstring_param_metadata(
-                goal_schema_for_docs,
-                parse_docstring(method_info.get("docstring")),
-                goal,
-                apply_defaults=True,
-            )
             action_value_mappings[action_name] = action_entry
 
         action_value_mappings = dict(sorted(action_value_mappings.items()))
 
         # --- init_param_schema = { config: <init_params>, data: <status_types> } ---
         init_params = ast_meta.get("init_params", [])
-        config_schema = self._generate_schema_from_ast_params(
-            init_params, "__init__", ast_meta.get("init_docstring"), import_map=imap
-        )
+        config_schema = self._generate_schema_from_ast_params(init_params, "__init__", import_map=imap)
         data_schema = self._generate_status_schema_from_ast(
             ast_meta.get("status_properties", {}), imap
         )
@@ -1105,6 +1042,7 @@ class Registry:
     ) -> Dict[str, Any]:
         """Generate JSON Schema from AST-extracted parameter list."""
         doc_info = parse_docstring(docstring)
+        param_descs = doc_info.get("params", {})
 
         schema: Dict[str, Any] = {
             "type": "object",
@@ -1134,10 +1072,12 @@ class Registry:
                     pname, ptype, pdefault, import_map
                 )
 
+            if pname in param_descs:
+                schema["properties"][pname]["description"] = param_descs[pname]
+
             if prequired:
                 schema["required"].append(pname)
 
-        self._apply_docstring_param_metadata(schema, doc_info, apply_defaults=True)
         return schema
 
     def _generate_status_schema_from_ast(
@@ -1867,7 +1807,7 @@ class Registry:
                         else:
                             action_key = f"auto-{k}"
                         goal_schema = self._generate_unilab_json_command_schema(
-                            v["args"], docstring=v.get("docstring"), import_map=enhanced_import_map
+                            v["args"], import_map=enhanced_import_map
                         )
                         ret_type = v.get("return_type", "")
                         result_schema = None
@@ -1876,13 +1816,7 @@ class Registry:
                                 "result", ret_type, None, import_map=enhanced_import_map
                             )
                         old_cfg = old_action_configs.get(action_key) or old_action_configs.get(f"auto-{k}", {})
-                        doc_info = parse_docstring(v.get("docstring"))
-                        new_schema = wrap_action_schema(
-                            goal_schema,
-                            action_key,
-                            description=doc_info.get("description", ""),
-                            result_schema=result_schema,
-                        )
+                        new_schema = wrap_action_schema(goal_schema, action_key, result_schema=result_schema)
                         old_schema = old_cfg.get("schema", {})
                         if old_schema:
                             preserve_field_descriptions(new_schema, old_schema)
@@ -1948,12 +1882,6 @@ class Registry:
 
                         merged_pk = dict(old_cfg.get("placeholder_keys", {}))
                         merged_pk.update(detect_placeholder_keys(v["args"]))
-                        goal_schema_for_docs = (
-                            entry_schema.get("properties", {}).get("goal", {})
-                            if isinstance(entry_schema, dict)
-                            else {}
-                        )
-                        self._apply_docstring_param_metadata(goal_schema_for_docs, doc_info, entry_goal)
 
                         entry = {
                             "type": entry_type,
@@ -1974,8 +1902,7 @@ class Registry:
 
                     device_config["init_param_schema"] = {}
                     init_schema = self._generate_unilab_json_command_schema(
-                        enhanced_info["init_params"],
-                        docstring=enhanced_info.get("init_docstring"),
+                        enhanced_info["init_params"], "__init__",
                         import_map=enhanced_import_map,
                     )
                     device_config["init_param_schema"]["config"] = init_schema
@@ -2022,9 +1949,7 @@ class Registry:
                             action_str_type_mapping[action_type_str] = target_type
                             if target_type is not None:
                                 try:
-                                    action_config["goal_default"] = ROS2MessageInstance(
-                                        target_type.Goal()
-                                    ).get_python_dict()
+                                    action_config["goal_default"] = ROS2MessageInstance(target_type.Goal()).get_python_dict()
                                 except Exception:
                                     action_config["goal_default"] = {}
                                 prev_schema = action_config.get("schema", {})
@@ -2216,7 +2141,6 @@ class Registry:
                                 "unilabos_device_id": {
                                     "type": "string",
                                     "default": "",
-                                    "title": "设备ID",
                                     "description": "UniLabOS设备ID，用于指定执行动作的具体设备实例",
                                 },
                                 **schema["properties"]["goal"]["properties"],
@@ -2288,14 +2212,7 @@ class Registry:
 lab_registry = Registry()
 
 
-def build_registry(
-    registry_paths=None,
-    devices_dirs=None,
-    upload_registry=False,
-    check_mode=False,
-    complete_registry=False,
-    external_only=False,
-):
+def build_registry(registry_paths=None, devices_dirs=None, upload_registry=False, check_mode=False, complete_registry=False, external_only=False):
     """
     构建或获取Registry单例实例
     """
@@ -2309,12 +2226,7 @@ def build_registry(
             if path not in current_paths:
                 lab_registry.registry_paths.append(path)
 
-    lab_registry.setup(
-        devices_dirs=devices_dirs,
-        upload_registry=upload_registry,
-        complete_registry=complete_registry,
-        external_only=external_only,
-    )
+    lab_registry.setup(devices_dirs=devices_dirs, upload_registry=upload_registry, complete_registry=complete_registry, external_only=external_only)
 
     # 将 AST 扫描的字符串类型替换为实际 ROS2 消息类（仅查找 ROS2 类型，不 import 设备模块）
     lab_registry.resolve_all_types()

unilabos/registry/utils.py

@@ -36,40 +36,16 @@ class ROSMsgNotFound(Exception):
 # ---------------------------------------------------------------------------
 
 _SECTION_RE = re.compile(r"^(\w[\w\s]*):\s*$")
-_PARAM_HEADER_RE = re.compile(
-    r"^\s*(?P<name>\w[\w]*)\s*(?:\[(?P<display_name>[^\]]+)\])?(?:\s*\([^)]*\))?\s*$"
-)
-
-
-def _parse_docstring_param_header(param_part: str) -> Tuple[str, Optional[str]]:
-    """Parse ``name[display_name]`` or Google-style ``name (type)``."""
-    match = _PARAM_HEADER_RE.match(param_part.strip())
-    if not match:
-        return param_part.strip().split("(")[0].strip(), None
-
-    display_name = match.group("display_name")
-    if display_name is not None:
-        display_name = display_name.strip() or None
-    return match.group("name").strip(), display_name
 
 
 def parse_docstring(docstring: Optional[str]) -> Dict[str, Any]:
     """
-    解析 docstring，提取描述和参数说明。
-
-    支持:
-      - Google-style ``Args:`` / ``Parameters:`` 小节
-      - 直接参数行 ``field: desc``
-      - 带显示名参数行 ``field[Display Name]: desc``
+    解析 Google-style docstring，提取描述和参数说明。
 
     Returns:
-        {
-            "description": "短描述",
-            "params": {"param1": "参数1描述", ...},
-            "param_display_names": {"param1": "显示名", ...},
-        }
+        {"description": "短描述", "params": {"param1": "参数1描述", ...}}
     """
-    result: Dict[str, Any] = {"description": "", "params": {}, "param_display_names": {}}
+    result: Dict[str, Any] = {"description": "", "params": {}}
     if not docstring:
         return result
 
@@ -77,53 +53,33 @@ def parse_docstring(docstring: Optional[str]) -> Dict[str, Any]:
     if not lines:
         return result
 
+    result["description"] = lines[0].strip()
+
     in_args = False
-    current_section: Optional[str] = None
     current_param: Optional[str] = None
-    current_display_name: Optional[str] = None
     current_desc_parts: list = []
 
-    def flush_current_param() -> None:
-        nonlocal current_param, current_display_name, current_desc_parts
-        if current_param is None:
-            return
-        result["params"][current_param] = "\n".join(current_desc_parts).strip()
-        if current_display_name:
-            result["param_display_names"][current_param] = current_display_name
-        current_param = None
-        current_display_name = None
-        current_desc_parts = []
-
-    first_line = lines[0].strip()
-    start_index = 0
-    if not _SECTION_RE.match(first_line) and ":" not in first_line:
-        result["description"] = first_line
-        start_index = 1
-
-    for line in lines[start_index:]:
+    for line in lines[1:]:
         stripped = line.strip()
-        if not stripped:
-            if current_param is not None:
-                current_desc_parts.append("")
-            continue
-
         section_match = _SECTION_RE.match(stripped)
         if section_match:
-            flush_current_param()
-            current_section = section_match.group(1).lower()
-            in_args = current_section in ("args", "arguments", "parameters", "params")
+            if current_param is not None:
+                result["params"][current_param] = "\n".join(current_desc_parts).strip()
+                current_param = None
+                current_desc_parts = []
+            section_name = section_match.group(1).lower()
+            in_args = section_name in ("args", "arguments", "parameters", "params")
             continue
 
-        parse_as_param = in_args or current_section is None
-        if not parse_as_param:
+        if not in_args:
             continue
 
-        if ":" in stripped:
-            flush_current_param()
+        if ":" in stripped and not stripped.startswith(" "):
+            if current_param is not None:
+                result["params"][current_param] = "\n".join(current_desc_parts).strip()
             param_part, _, desc_part = stripped.partition(":")
-            param_name, display_name = _parse_docstring_param_header(param_part)
+            param_name = param_part.strip().split("(")[0].strip()
             current_param = param_name
-            current_display_name = display_name
             current_desc_parts = [desc_part.strip()]
         elif current_param is not None:
             aline = line
@@ -133,7 +89,8 @@ def parse_docstring(docstring: Optional[str]) -> Dict[str, Any]:
                 aline = aline[1:]
             current_desc_parts.append(aline.strip())
 
-    flush_current_param()
+    if current_param is not None:
+        result["params"][current_param] = "\n".join(current_desc_parts).strip()
 
     return result
 

unilabos/resources/bioyond/bottle_carriers.py

@@ -1,4 +1,4 @@
-from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d
+from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d, Container
 
 from unilabos.resources.itemized_carrier import BottleCarrier
 from unilabos.resources.bioyond.bottles import (
@@ -9,6 +9,28 @@ from unilabos.resources.bioyond.bottles import (
     BIOYOND_PolymerStation_Reagent_Bottle,
     BIOYOND_PolymerStation_Flask,
 )
+
+
+def BIOYOND_PolymerStation_Tip(name: str, size_x: float = 8.0, size_y: float = 8.0, size_z: float = 50.0) -> Container:
+    """创建单个枪头资源
+
+    Args:
+        name: 枪头名称
+        size_x: 枪头宽度 (mm)
+        size_y: 枪头长度 (mm)
+        size_z: 枪头高度 (mm)
+
+    Returns:
+        Container: 枪头容器
+    """
+    return Container(
+        name=name,
+        size_x=size_x,
+        size_y=size_y,
+        size_z=size_z,
+        category="tip",
+        model="BIOYOND_PolymerStation_Tip",
+    )
 # 命名约定：试剂瓶-Bottle，烧杯-Beaker，烧瓶-Flask,小瓶-Vial
 
 
@@ -322,3 +344,88 @@ def BIOYOND_Electrolyte_1BottleCarrier(name: str) -> BottleCarrier:
     carrier.num_items_z = 1
     carrier[0] = BIOYOND_PolymerStation_Solution_Beaker(f"{name}_beaker_1")
     return carrier
+
+
+def BIOYOND_PolymerStation_TipBox(
+    name: str,
+    size_x: float = 127.76,  # 枪头盒宽度
+    size_y: float = 85.48,   # 枪头盒长度
+    size_z: float = 100.0,   # 枪头盒高度
+    barcode: str = None,
+) -> BottleCarrier:
+    """创建4×6枪头盒 (24个枪头) - 使用 BottleCarrier 结构
+
+    Args:
+        name: 枪头盒名称
+        size_x: 枪头盒宽度 (mm)
+        size_y: 枪头盒长度 (mm)
+        size_z: 枪头盒高度 (mm)
+        barcode: 条形码
+
+    Returns:
+        BottleCarrier: 包含24个枪头孔位的枪头盒载架
+
+    布局说明:
+        - 4行×6列 (A-D, 1-6)
+        - 枪头孔位间距: 18mm (x方向) × 18mm (y方向)
+        - 起始位置居中对齐
+        - 索引顺序: 列优先 (0=A1, 1=B1, 2=C1, 3=D1, 4=A2, ...)
+    """
+    # 枪头孔位参数
+    num_cols = 6  # 1-6 (x方向)
+    num_rows = 4  # A-D (y方向)
+    tip_diameter = 8.0  # 枪头孔位直径
+    tip_spacing_x = 18.0  # 列间距 (增加到18mm，更宽松)
+    tip_spacing_y = 18.0  # 行间距 (增加到18mm，更宽松)
+
+    # 计算起始位置 (居中对齐)
+    total_width = (num_cols - 1) * tip_spacing_x + tip_diameter
+    total_height = (num_rows - 1) * tip_spacing_y + tip_diameter
+    start_x = (size_x - total_width) / 2
+    start_y = (size_y - total_height) / 2
+
+    # 使用 create_ordered_items_2d 创建孔位
+    # create_ordered_items_2d 返回的 key 是数字索引: 0, 1, 2, ...
+    # 顺序是列优先: 先y后x (即 0=A1, 1=B1, 2=C1, 3=D1, 4=A2, 5=B2, ...)
+    sites = create_ordered_items_2d(
+        klass=ResourceHolder,
+        num_items_x=num_cols,
+        num_items_y=num_rows,
+        dx=start_x,
+        dy=start_y,
+        dz=5.0,
+        item_dx=tip_spacing_x,
+        item_dy=tip_spacing_y,
+        size_x=tip_diameter,
+        size_y=tip_diameter,
+        size_z=50.0,  # 枪头深度
+    )
+
+    # 更新 sites 中每个 ResourceHolder 的名称
+    for k, v in sites.items():
+        v.name = f"{name}_{v.name}"
+
+    # 创建枪头盒载架
+    # 注意：不设置 category，使用默认的 "bottle_carrier"，这样前端会显示为完整的矩形载架
+    tip_box = BottleCarrier(
+        name=name,
+        size_x=size_x,
+        size_y=size_y,
+        size_z=size_z,
+        sites=sites,  # 直接使用数字索引的 sites
+        model="BIOYOND_PolymerStation_TipBox",
+    )
+
+    # 设置自定义属性
+    tip_box.barcode = barcode
+    tip_box.tip_count = 24  # 4行×6列
+    tip_box.num_items_x = num_cols
+    tip_box.num_items_y = num_rows
+    tip_box.num_items_z = 1
+
+    # ⭐ 枪头盒不需要放入子资源
+    # 与其他 carrier 不同，枪头盒在 Bioyond 中是一个整体
+    # 不需要追踪每个枪头的状态，保持为空的 ResourceHolder 即可
+    # 这样前端会显示24个空槽位，可以用于放置枪头
+
+    return tip_box

unilabos/resources/bioyond/bottles.py

@@ -116,7 +116,9 @@ def BIOYOND_PolymerStation_TipBox(
     size_z: float = 100.0,   # 枪头盒高度
     barcode: str = None,
 ):
-    """创建4×6枪头盒 (24个枪头)
+    """创建4×6枪头盒 (24个枪头) - 使用 BottleCarrier 结构
+
+    注意：此函数已弃用，请使用 bottle_carriers.py 中的版本
 
     Args:
         name: 枪头盒名称
@@ -126,55 +128,11 @@ def BIOYOND_PolymerStation_TipBox(
         barcode: 条形码
 
     Returns:
-        TipBoxCarrier: 包含24个枪头孔位的枪头盒
+        BottleCarrier: 包含24个枪头孔位的枪头盒载架
     """
-    from pylabrobot.resources import Container, Coordinate
-
-    # 创建枪头盒容器
-    tip_box = Container(
-        name=name,
-        size_x=size_x,
-        size_y=size_y,
-        size_z=size_z,
-        category="tip_rack",
-        model="BIOYOND_PolymerStation_TipBox_4x6",
-    )
-
-    # 设置自定义属性
-    tip_box.barcode = barcode
-    tip_box.tip_count = 24  # 4行×6列
-    tip_box.num_items_x = 6  # 6列
-    tip_box.num_items_y = 4  # 4行
-
-    # 创建24个枪头孔位 (4行×6列)
-    # 假设孔位间距为 9mm
-    tip_spacing_x = 9.0  # 列间距
-    tip_spacing_y = 9.0  # 行间距
-    start_x = 14.38  # 第一个孔位的x偏移
-    start_y = 11.24  # 第一个孔位的y偏移
-
-    for row in range(4):  # A, B, C, D
-        for col in range(6):  # 1-6
-            spot_name = f"{chr(65 + row)}{col + 1}"  # A1, A2, ..., D6
-            x = start_x + col * tip_spacing_x
-            y = start_y + row * tip_spacing_y
-
-            # 创建枪头孔位容器
-            tip_spot = Container(
-                name=spot_name,
-                size_x=8.0,  # 单个枪头孔位大小
-                size_y=8.0,
-                size_z=size_z - 10.0,  # 略低于盒子高度
-                category="tip_spot",
-            )
-
-            # 添加到枪头盒
-            tip_box.assign_child_resource(
-                tip_spot,
-                location=Coordinate(x=x, y=y, z=0)
-            )
-
-    return tip_box
+    # 重定向到 bottle_carriers.py 中的实现
+    from unilabos.resources.bioyond.bottle_carriers import BIOYOND_PolymerStation_TipBox as TipBox_Carrier
+    return TipBox_Carrier(name=name, size_x=size_x, size_y=size_y, size_z=size_z, barcode=barcode)
 
 
 def BIOYOND_PolymerStation_Flask(

unilabos/resources/graphio.py

@@ -797,9 +797,12 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
                     bottle = plr_material[number] = initialize_resource(
                         {"name": f'{detail["name"]}_{number}', "class": reverse_type_mapping[typeName][0]}, resource_type=ResourcePLR
                     )
-                    bottle.tracker.liquids = [
-                        (detail["name"], float(detail.get("quantity", 0)) if detail.get("quantity") else 0)
-                    ]
+                    # 只有具有 tracker 属性的容器才设置液体信息（如 Bottle, Well）
+                    # ResourceHolder 等不支持液体追踪的容器跳过
+                    if hasattr(bottle, "tracker"):
+                        bottle.tracker.liquids = [
+                            (detail["name"], float(detail.get("quantity", 0)) if detail.get("quantity") else 0)
+                        ]
                     bottle.code = detail.get("code", "")
                     logger.debug(f"  └─ [子物料] {detail['name']} → {plr_material.name}[{number}] (类型:{typeName})")
                 else:
@@ -808,9 +811,11 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
             # 只对有 capacity 属性的容器（液体容器）处理液体追踪
             if hasattr(plr_material, 'capacity'):
                 bottle = plr_material[0] if plr_material.capacity > 0 else plr_material
-                bottle.tracker.liquids = [
-                    (material["name"], float(material.get("quantity", 0)) if material.get("quantity") else 0)
-                ]
+                # 确保 bottle 有 tracker 属性才设置液体信息
+                if hasattr(bottle, "tracker"):
+                    bottle.tracker.liquids = [
+                        (material["name"], float(material.get("quantity", 0)) if material.get("quantity") else 0)
+                    ]
 
         plr_materials.append(plr_material)
 
@@ -839,24 +844,29 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
                 wh_name = loc.get("whName")
                 logger.debug(f"[物料位置] {unique_name} 尝试放置到 warehouse: {wh_name} (Bioyond坐标: x={loc.get('x')}, y={loc.get('y')}, z={loc.get('z')})")
 
+                # Bioyond坐标映射 (重要！): x→行(1=A,2=B...), y→列(1=01,2=02...), z→层(通常=1)
+                # 必须在warehouse映射之前先获取坐标，以便后续调整
+                x = loc.get("x", 1)  # 行号 (1-based: 1=A, 2=B, 3=C, 4=D)
+                y = loc.get("y", 1)  # 列号 (1-based: 1=01, 2=02, 3=03...)
+                z = loc.get("z", 1)  # 层号 (1-based, 通常为1)
+
                 # 特殊处理: Bioyond的"堆栈1"需要映射到"堆栈1左"或"堆栈1右"
-                # 根据列号(x)判断: 1-4映射到左侧, 5-8映射到右侧
+                # 根据列号(y)判断: 1-4映射到左侧, 5-8映射到右侧
                 if wh_name == "堆栈1":
-                    x_val = loc.get("x", 1)
-                    if 1 <= x_val <= 4:
+                    if 1 <= y <= 4:
                         wh_name = "堆栈1左"
-                    elif 5 <= x_val <= 8:
+                    elif 5 <= y <= 8:
                         wh_name = "堆栈1右"
+                        y = y - 4  # 调整列号: 5-8映射到1-4
                     else:
-                        logger.warning(f"物料 {material['name']} 的列号 x={x_val} 超出范围，无法映射到堆栈1左或堆栈1右")
+                        logger.warning(f"物料 {material['name']} 的列号 y={y} 超出范围，无法映射到堆栈1左或堆栈1右")
                         continue
 
                 # 特殊处理: Bioyond的"站内Tip盒堆栈"也需要进行拆分映射
                 if wh_name == "站内Tip盒堆栈":
-                    y_val = loc.get("y", 1)
-                    if y_val == 1:
+                    if y == 1:
                         wh_name = "站内Tip盒堆栈(右)"
-                    elif y_val in [2, 3]:
+                    elif y in [2, 3]:
                         wh_name = "站内Tip盒堆栈(左)"
                         y = y - 1  # 调整列号，因为左侧仓库对应的 Bioyond y=2 实际上是它的第1列
 
@@ -864,15 +874,6 @@ def resource_bioyond_to_plr(bioyond_materials: list[dict], type_mapping: Dict[st
                     warehouse = deck.warehouses[wh_name]
                     logger.debug(f"[Warehouse匹配] 找到warehouse: {wh_name} (容量: {warehouse.capacity}, 行×列: {warehouse.num_items_x}×{warehouse.num_items_y})")
 
-                    # Bioyond坐标映射 (重要！): x→行(1=A,2=B...), y→列(1=01,2=02...), z→层(通常=1)
-                    x = loc.get("x", 1)  # 行号 (1-based: 1=A, 2=B, 3=C, 4=D)
-                    y = loc.get("y", 1)  # 列号 (1-based: 1=01, 2=02, 3=03...)
-                    z = loc.get("z", 1)  # 层号 (1-based, 通常为1)
-
-                    # 如果是右侧堆栈，需要调整列号 (5→1, 6→2, 7→3, 8→4)
-                    if wh_name == "堆栈1右":
-                        y = y - 4  # 将5-8映射到1-4
-
                     # 特殊处理竖向warehouse（站内试剂存放堆栈、测量小瓶仓库）
                     # 这些warehouse使用 vertical-col-major 布局
                     if wh_name in ["站内试剂存放堆栈", "测量小瓶仓库(测密度)"]:

unilabos/resources/itemized_carrier.py

@@ -179,6 +179,11 @@ class ItemizedCarrier(ResourcePLR):
           idx = i
           break
 
+    if idx is None:
+      # 反序列化时无法匹配 site（名称或坐标均不符）。
+      # WareHouse 通过 sites 追踪占用，无需将子资源加入 PLR 子树，直接跳过避免命名冲突。
+      return
+
     if not reassign and self.sites[idx] is not None:
       raise ValueError(f"a site with index {idx} already exists")
     location = list(self.child_locations.values())[idx]

unilabos/resources/plr_additional_res_reg.py

@@ -18,3 +18,9 @@ def register():
     from unilabos.devices.liquid_handling.rviz_backend import UniLiquidHandlerRvizBackend
     from unilabos.devices.liquid_handling.laiyu.backend.laiyu_v_backend import UniLiquidHandlerLaiyuBackend
 
+    # noinspection PyUnresolvedReferences
+    from unilabos.resources.bioyond.decks import (
+        BIOYOND_PolymerReactionStation_Deck,
+        BIOYOND_PolymerPreparationStation_Deck,
+        BIOYOND_YB_Deck,
+    )

unilabos/resources/resource_tracker.py

@@ -423,6 +423,7 @@ class ResourceTreeSet(object):
                 "deck": "deck",
                 "tip_rack": "tip_rack",
                 "tip_spot": "tip_spot",
+                "tip": "tip",  # 添加 tip 类型支持
                 "tube": "tube",
                 "bottle_carrier": "bottle_carrier",
                 "material_hole": "material_hole",
@@ -605,11 +606,19 @@ class ResourceTreeSet(object):
                 },
                 "rotation": {"x": 0, "y": 0, "z": 0, "type": "Rotation"},
                 "category": res.config.get("category", plr_type),
-                "children": [node_to_plr_dict(child, has_model) for child in node.children],
+                # WareHouse 通过 sites 字符串追踪占位，不依赖 PLR children tree。
+                # 将 WareHouse 子节点排除在外，避免同名载架出现在多个 WareHouse 下时
+                # PLR _check_naming_conflicts 报命名冲突。
+                "children": [] if res.type == "warehouse" else [node_to_plr_dict(child, has_model) for child in node.children],
                 "parent_name": res.parent_instance_name,
             }
             if has_model:
                 d["model"] = res.config.get("model", None)
+            # 仅当 PLR dict 中含有子节点时才禁用 setup()，
+            # 防止 setup() 预分配子资源后 PLR deserialize 再次分配同名资源产生命名冲突。
+            # 若 children 为空，则保留 setup=True，依赖 setup() 来初始化仓库。
+            if "setup" in d and d.get("children"):
+                d["setup"] = False
             return d
 
         plr_resources = []
@@ -862,13 +871,34 @@ class ResourceTreeSet(object):
                                     f"已存在，跳过"
                                 )
 
+                        # 移除本地有但远端已不存在的物料（以远端为准）
+                        remote_material_names = {m.res_content.name for m in remote_child.children}
+                        removed_count = 0
+                        for child in list(local_sub_device.children):
+                            if child.res_content.name not in remote_material_names:
+                                local_sub_device.children.remove(child)
+                                removed_count += 1
+                                logger.info(
+                                    f"移除远端已不存在的物料: '{remote_root_id}/{remote_child_name}/{child.res_content.name}'"
+                                )
+
                         if added_count > 0:
                             logger.info(
                                 f"Device '{remote_root_id}/{remote_child_name}': "
                                 f"从远端同步了 {added_count} 个物料子树"
                             )
+                        if removed_count > 0:
+                            logger.info(
+                                f"Device '{remote_root_id}/{remote_child_name}': "
+                                f"移除了 {removed_count} 个远端已删除的物料"
+                            )
                     else:
                         # 二级物料已存在，比较三级子节点是否缺失
+                        if remote_child_name not in local_children_map:
+                            logger.warning(
+                                f"物料 '{remote_root_id}/{remote_child_name}' 在远端存在但本地不存在，跳过"
+                            )
+                            continue
                         local_material = local_children_map[remote_child_name]
                         local_material_children_map = {child.res_content.name: child for child in
                                                        local_material.children}
@@ -884,11 +914,28 @@ class ResourceTreeSet(object):
                                     f"物料 '{remote_root_id}/{remote_child_name}/{remote_sub_name}' "
                                     f"已存在，跳过"
                                 )
+
+                        # 移除本地有但远端已不存在的子物料（以远端为准）
+                        remote_sub_names = {s.res_content.name for s in remote_child.children}
+                        removed_count = 0
+                        for child in list(local_material.children):
+                            if child.res_content.name not in remote_sub_names:
+                                local_material.children.remove(child)
+                                removed_count += 1
+                                logger.info(
+                                    f"移除远端已不存在的子物料: '{remote_root_id}/{remote_child_name}/{child.res_content.name}'"
+                                )
+
                         if added_count > 0:
                             logger.info(
                                 f"物料 '{remote_root_id}/{remote_child_name}': "
                                 f"从远端同步了 {added_count} 个子物料"
                             )
+                        if removed_count > 0:
+                            logger.info(
+                                f"物料 '{remote_root_id}/{remote_child_name}': "
+                                f"移除了 {removed_count} 个远端已删除的子物料"
+                            )
             else:
                 # 情况1: 一级节点是物料（不是 device）
                 # 检查是否已存在
@@ -1329,6 +1376,16 @@ class DeviceNodeResourceTracker(object):
                 else:
                     res_list.extend(self.loop_find_resource(r, type(query_resource), "unilabos_uuid", res_uuid))
 
+            # 同一资源对象可能通过"直接注册"和"作为父资源子节点"被搜索到两次，按对象 id 去重
+            seen_ids: set = set()
+            deduped = []
+            for item in res_list:
+                oid = id(item[1])
+                if oid not in seen_ids:
+                    seen_ids.add(oid)
+                    deduped.append(item)
+            res_list = deduped
+
             if not try_mode:
                 assert len(res_list) > 0, f"没有找到资源 (uuid={res_uuid})，请检查资源是否存在"
                 assert len(res_list) == 1, f"通过uuid={res_uuid} 找到多个资源，请检查资源是否唯一: {res_list}"
@@ -1365,6 +1422,14 @@ class DeviceNodeResourceTracker(object):
                         r, resource_cls_type, identifier_key, getattr(query_resource, identifier_key)
                     )
                 )
+        seen_ids2: set = set()
+        deduped2 = []
+        for item in res_list:
+            oid = id(item[1])
+            if oid not in seen_ids2:
+                seen_ids2.add(oid)
+                deduped2.append(item)
+        res_list = deduped2
         if not try_mode:
             assert len(res_list) > 0, f"没有找到资源 {query_resource}，请检查资源是否存在"
             assert len(res_list) == 1, f"{query_resource} 找到多个资源，请检查资源是否唯一: {res_list}"

unilabos/ros/nodes/base_device_node.py

@@ -45,7 +45,6 @@ from unilabos.resources.graphio import (
 )
 from unilabos.resources.plr_additional_res_reg import register
 from unilabos.ros.msgs.message_converter import (
-    String,
     convert_to_ros_msg,
     convert_from_ros_msg_with_mapping,
     convert_to_ros_msg_with_mapping,
@@ -251,8 +250,7 @@ class PropertyPublisher:
     ):
         self.node = node
         self.name = name
-        self.msg_type = self._normalize_msg_type(msg_type)
-        self.original_msg_type = msg_type
+        self.msg_type = msg_type
         self.get_method = get_method
         self.timer_period = initial_period
         self.print_publish = print_publish
@@ -260,36 +258,16 @@ class PropertyPublisher:
 
         self._value = None
         try:
-            self.publisher_ = node.create_publisher(self.msg_type, f"{name}", qos)
+            self.publisher_ = node.create_publisher(msg_type, f"{name}", qos)
         except Exception as e:
             self.node.lab_logger().error(
-                f"StatusError, DeviceId: {self.node.device_id} 创建发布者 {name} 失败，"
-                f"可能由于注册表有误，类型: {msg_type}，错误: {e}"
+                f"StatusError, DeviceId: {self.node.device_id} 创建发布者 {name} 失败，可能由于注册表有误，类型: {msg_type}，错误: {e}"
             )
-            self.msg_type = String
-            try:
-                self.publisher_ = node.create_publisher(self.msg_type, f"{name}", qos)
-                self.node.lab_logger().warning(
-                    f"属性 {name} 的发布类型已降级为 String，原始类型: {msg_type}"
-                )
-            except Exception:
-                self.publisher_ = None
         self.timer = node.create_timer(self.timer_period, self.publish_property)
         self.__loop = ROS2DeviceNode.get_asyncio_loop()
-        str_msg_type = str(self.msg_type)[8:-2]
+        str_msg_type = str(msg_type)[8:-2]
         self.node.lab_logger().trace(f"发布属性: {name}, 类型: {str_msg_type}, 周期: {initial_period}秒, QoS: {qos}")
 
-    @staticmethod
-    def _normalize_msg_type(msg_type):
-        if msg_type in (dict, list, tuple, set) or msg_type in ("dict", "list", "tuple", "set"):
-            return String
-        return msg_type
-
-    def _normalize_value(self, value):
-        if self.msg_type is String and isinstance(value, (dict, list, tuple, set)):
-            return json.dumps(value, ensure_ascii=False, cls=TypeEncoder)
-        return value
-
     def get_property(self):
         if asyncio.iscoroutinefunction(self.get_method):
             # 如果是异步函数，运行事件循环并等待结果
@@ -324,16 +302,12 @@ class PropertyPublisher:
                 pass
                 # self.node.lab_logger().trace(f"【.publish_property】发布 {self.msg_type}: {value}")
             if value is not None:
-                if self.publisher_ is None:
-                    return
-                value = self._normalize_value(value)
                 msg = convert_to_ros_msg(self.msg_type, value)
                 self.publisher_.publish(msg)
                 # self.node.lab_logger().trace(f"【.publish_property】属性 {self.name} 发布成功")
         except Exception as e:
-            topic = getattr(self.publisher_, "topic", self.name)
             self.node.lab_logger().error(
-                f"【.publish_property】发布属性 {topic} 出错: {str(e)}\n{traceback.format_exc()}"
+                f"【.publish_property】发布属性 {self.publisher_.topic} 出错: {str(e)}\n{traceback.format_exc()}"
             )
 
     def change_frequency(self, period):

unilabos/ros/nodes/presets/host_node.py

@@ -1691,9 +1691,7 @@ class HostNode(BaseROS2DeviceNode):
         else:
             self.lab_logger().warning("⚠️ 收到无效的Pong响应（缺少ping_id）")
 
-    def notify_resource_tree_update(
-        self, device_id: str, action: str, resource_uuid_list: List[str]
-    ) -> Optional[bool]:
+    def notify_resource_tree_update(self, device_id: str, action: str, resource_uuid_list: List[str]) -> bool:
         """
         通知设备节点更新资源树
 
@@ -1703,14 +1701,13 @@ class HostNode(BaseROS2DeviceNode):
             resource_uuid_list: 资源UUIDs
 
         Returns:
-            True if the update completed, False if it failed, None if it was intentionally skipped.
+            bool: 操作是否成功
         """
         try:
+            # 检查设备是否存在
             if device_id not in self.devices_names:
-                self.lab_logger().info(
-                    f"[Host Node-Resource] 在线增加设备暂不支持，跳过设备 {device_id} 的资源树 {action} 更新"
-                )
-                return None
+                self.lab_logger().error(f"[Host Node-Resource] Device {device_id} not found in devices_names")
+                return False
 
             namespace = self.devices_names[device_id]
             device_key = f"{namespace}/{device_id}"

unilabos/test/experiments/dispensing_station_bioyond.json

@@ -15,92 +15,92 @@
                 "z": 0
             },
             "config": {
-                "api_key": "YOUR_API_KEY",
-                "api_host": "http://your-api-host:port",
+                "api_key": "<BIOYOND_API_KEY>",
+                "api_host": "http://<BIOYOND_HOST>:<BIOYOND_PORT>",
                 "material_type_mappings": {
                     "BIOYOND_PolymerStation_1FlaskCarrier": [
                         "烧杯",
-                        "uuid-placeholder-flask"
+                        "<UUID_FLASK_CARRIER_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_1BottleCarrier": [
                         "试剂瓶",
-                        "uuid-placeholder-bottle"
+                        "<UUID_BOTTLE_CARRIER_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_6StockCarrier": [
                         "分装板",
-                        "uuid-placeholder-stock-6"
+                        "<UUID_6STOCK_CARRIER_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_Liquid_Vial": [
                         "10%分装小瓶",
-                        "uuid-placeholder-liquid-vial"
+                        "<UUID_LIQUID_VIAL_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_Solid_Vial": [
                         "90%分装小瓶",
-                        "uuid-placeholder-solid-vial"
+                        "<UUID_SOLID_VIAL_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_8StockCarrier": [
                         "样品板",
-                        "uuid-placeholder-stock-8"
+                        "<UUID_8STOCK_CARRIER_TYPE>"
                     ],
                     "BIOYOND_PolymerStation_Solid_Stock": [
                         "样品瓶",
-                        "uuid-placeholder-solid-stock"
+                        "<UUID_SOLID_STOCK_TYPE>"
                     ]
                 },
                 "warehouse_mapping": {
                     "粉末堆栈": {
-                        "uuid": "uuid-placeholder-powder-stack",
+                        "uuid": "<UUID_POWDER_WAREHOUSE>",
                         "site_uuids": {
-                            "A01": "uuid-placeholder-powder-A01",
-                            "A02": "uuid-placeholder-powder-A02",
-                            "A03": "uuid-placeholder-powder-A03",
-                            "A04": "uuid-placeholder-powder-A04",
-                            "B01": "uuid-placeholder-powder-B01",
-                            "B02": "uuid-placeholder-powder-B02",
-                            "B03": "uuid-placeholder-powder-B03",
-                            "B04": "uuid-placeholder-powder-B04",
-                            "C01": "uuid-placeholder-powder-C01",
-                            "C02": "uuid-placeholder-powder-C02",
-                            "C03": "uuid-placeholder-powder-C03",
-                            "C04": "uuid-placeholder-powder-C04",
-                            "D01": "uuid-placeholder-powder-D01",
-                            "D02": "uuid-placeholder-powder-D02",
-                            "D03": "uuid-placeholder-powder-D03",
-                            "D04": "uuid-placeholder-powder-D04"
+                            "A01": "<UUID_POWDER_A01>",
+                            "A02": "<UUID_POWDER_A02>",
+                            "A03": "<UUID_POWDER_A03>",
+                            "A04": "<UUID_POWDER_A04>",
+                            "B01": "<UUID_POWDER_B01>",
+                            "B02": "<UUID_POWDER_B02>",
+                            "B03": "<UUID_POWDER_B03>",
+                            "B04": "<UUID_POWDER_B04>",
+                            "C01": "<UUID_POWDER_C01>",
+                            "C02": "<UUID_POWDER_C02>",
+                            "C03": "<UUID_POWDER_C03>",
+                            "C04": "<UUID_POWDER_C04>",
+                            "D01": "<UUID_POWDER_D01>",
+                            "D02": "<UUID_POWDER_D02>",
+                            "D03": "<UUID_POWDER_D03>",
+                            "D04": "<UUID_POWDER_D04>"
                         }
                     },
                     "溶液堆栈": {
-                        "uuid": "uuid-placeholder-liquid-stack",
+                        "uuid": "<UUID_SOLUTION_WAREHOUSE>",
                         "site_uuids": {
-                            "A01": "uuid-placeholder-liquid-A01",
-                            "A02": "uuid-placeholder-liquid-A02",
-                            "A03": "uuid-placeholder-liquid-A03",
-                            "A04": "uuid-placeholder-liquid-A04",
-                            "B01": "uuid-placeholder-liquid-B01",
-                            "B02": "uuid-placeholder-liquid-B02",
-                            "B03": "uuid-placeholder-liquid-B03",
-                            "B04": "uuid-placeholder-liquid-B04",
-                            "C01": "uuid-placeholder-liquid-C01",
-                            "C02": "uuid-placeholder-liquid-C02",
-                            "C03": "uuid-placeholder-liquid-C03",
-                            "C04": "uuid-placeholder-liquid-C04",
-                            "D01": "uuid-placeholder-liquid-D01",
-                            "D02": "uuid-placeholder-liquid-D02",
-                            "D03": "uuid-placeholder-liquid-D03",
-                            "D04": "uuid-placeholder-liquid-D04"
+                            "A01": "<UUID_SOLUTION_A01>",
+                            "A02": "<UUID_SOLUTION_A02>",
+                            "A03": "<UUID_SOLUTION_A03>",
+                            "A04": "<UUID_SOLUTION_A04>",
+                            "B01": "<UUID_SOLUTION_B01>",
+                            "B02": "<UUID_SOLUTION_B02>",
+                            "B03": "<UUID_SOLUTION_B03>",
+                            "B04": "<UUID_SOLUTION_B04>",
+                            "C01": "<UUID_SOLUTION_C01>",
+                            "C02": "<UUID_SOLUTION_C02>",
+                            "C03": "<UUID_SOLUTION_C03>",
+                            "C04": "<UUID_SOLUTION_C04>",
+                            "D01": "<UUID_SOLUTION_D01>",
+                            "D02": "<UUID_SOLUTION_D02>",
+                            "D03": "<UUID_SOLUTION_D03>",
+                            "D04": "<UUID_SOLUTION_D04>"
                         }
                     },
                     "试剂堆栈": {
-                        "uuid": "uuid-placeholder-reagent-stack",
+                        "uuid": "<UUID_REAGENT_WAREHOUSE>",
                         "site_uuids": {
-                            "A01": "uuid-placeholder-reagent-A01",
-                            "A02": "uuid-placeholder-reagent-A02",
-                            "A03": "uuid-placeholder-reagent-A03",
-                            "A04": "uuid-placeholder-reagent-A04",
-                            "B01": "uuid-placeholder-reagent-B01",
-                            "B02": "uuid-placeholder-reagent-B02",
-                            "B03": "uuid-placeholder-reagent-B03",
-                            "B04": "uuid-placeholder-reagent-B04"
+                            "A01": "<UUID_REAGENT_A01>",
+                            "A02": "<UUID_REAGENT_A02>",
+                            "A03": "<UUID_REAGENT_A03>",
+                            "A04": "<UUID_REAGENT_A04>",
+                            "B01": "<UUID_REAGENT_B01>",
+                            "B02": "<UUID_REAGENT_B02>",
+                            "B03": "<UUID_REAGENT_B03>",
+                            "B04": "<UUID_REAGENT_B04>"
                         }
                     }
                 },

unilabos/test/experiments/xkc_sensor_test.json

@@ -0,0 +1,29 @@
+{
+    "nodes": [
+        {
+            "id": "Liquid_Sensor_1",
+            "name": "XKC Sensor",
+            "children": [],
+            "parent": null,
+            "type": "device",
+            "class": "sensor.xkc_rs485",
+            "position": {
+                "x": 0,
+                "y": 0,
+                "z": 0
+            },
+            "config": {
+                "port": "/dev/tty.usbserial-3110",
+                "baudrate": 9600,
+                "device_id": 1,
+                "threshold": 300,
+                "timeout": 3.0
+            },
+            "data": {
+                "level": false,
+                "rssi": 0
+            }
+        }
+    ],
+    "links": []
+}

unilabos/test/experiments/zdt_motor_test.json

@@ -0,0 +1,28 @@
+{
+    "nodes": [
+        {
+            "id": "ZDT_Motor",
+            "name": "ZDT Motor",
+            "children": [],
+            "parent": null,
+            "type": "device",
+            "class": "motor.zdt_x42",
+            "position": {
+                "x": 0,
+                "y": 0,
+                "z": 0
+            },
+            "config": {
+                "port": "/dev/tty.usbserial-3110",
+                "baudrate": 115200,
+                "device_id": 1,
+                "debug": true
+            },
+            "data": {
+                "position": 0,
+                "status": "idle"
+            }
+        }
+    ],
+    "links": []
+}

unilabos/utils/environment_check.py

@@ -33,83 +33,10 @@ _USE_UV: Optional[bool] = None
 def _has_uv() -> bool:
     global _USE_UV
     if _USE_UV is None:
-        uv_path = shutil.which("uv")
-        if not uv_path:
-            _USE_UV = False
-        else:
-            try:
-                result = subprocess.run([uv_path, "--version"], capture_output=True, text=True, timeout=10)
-                _USE_UV = result.returncode == 0
-            except Exception:
-                _USE_UV = False
+        _USE_UV = shutil.which("uv") is not None
     return _USE_UV
 
 
-def _install_command(installer: str, package: str, upgrade: bool, is_chinese: bool) -> List[str]:
-    if installer == "uv":
-        # uv >= 0.5 默认要求虚拟环境，对 conda env 会报 "No virtual environment found"。
-        # 显式 --python sys.executable 让 uv 把当前解释器（conda/venv/system 都行）
-        # 视为目标环境，绕开 venv 检测。
-        cmd = ["uv", "pip", "install", "--python", sys.executable]
-        if upgrade:
-            cmd.append("--upgrade")
-        cmd.append(package)
-        if is_chinese:
-            cmd.extend(["--index-url", "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"])
-        return cmd
-
-    cmd = [sys.executable, "-m", "pip", "install", "--disable-pip-version-check"]
-    if upgrade:
-        cmd.append("--upgrade")
-    cmd.append(package)
-    if is_chinese:
-        cmd.extend(["-i", "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"])
-    return cmd
-
-
-def _installer_candidates() -> List[str]:
-    installers: List[str] = []
-    if _has_uv():
-        installers.append("uv")
-    installers.append("pip")
-    return installers
-
-
-def _git_url_from_requirement(requirement: str) -> Optional[str]:
-    if not requirement.startswith("git+"):
-        return None
-    return requirement[4:].split("#", 1)[0]
-
-
-def _repo_dir_name(git_url: str) -> str:
-    repo_name = git_url.rstrip("/").rsplit("/", 1)[-1]
-    return repo_name[:-4] if repo_name.endswith(".git") else repo_name
-
-
-def _print_manual_git_install_hint(requirement: str) -> None:
-    git_url = _git_url_from_requirement(requirement)
-    if not git_url:
-        return
-
-    repo_dir = _repo_dir_name(git_url)
-    install_cmd = (
-        f'uv pip install --python "{sys.executable}" -e .'
-        if _has_uv()
-        else f"{sys.executable} -m pip install -e ."
-    )
-    if _is_chinese_locale() and not _has_uv():
-        install_cmd += " -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
-
-    print_status("Git 依赖自动安装失败，通常是网络连接被重置或代码托管站点暂时不可达。", "warning")
-    print_status("可以手动拉取代码后在本地安装:", "warning")
-    print_status(f"  git clone {git_url}", "warning")
-    print_status(f"  cd {repo_dir}", "warning")
-    print_status("  git pull", "warning")
-    print_status(f"  {install_cmd}", "warning")
-    print_status(f"如果目录 {repo_dir} 已存在，直接进入该目录执行 git pull 后再安装。", "warning")
-    print_status("如果 git clone 仍失败，请切换网络/代理，或从浏览器下载源码后进入源码目录执行本地安装命令。", "warning")
-
-
 def _install_packages(
     packages: List[str],
     upgrade: bool = False,
@@ -126,7 +53,7 @@ def _install_packages(
         return True
 
     is_chinese = _is_chinese_locale()
-    installers = _installer_candidates()
+    use_uv = _has_uv()
     failed: List[str] = []
 
     for pkg in packages:
@@ -136,30 +63,35 @@ def _install_packages(
         else:
             print_status(f"正在{action_word} {pkg}...", "info")
 
-        pkg_installed = False
-        last_error = "unknown error"
+        if use_uv:
+            cmd = ["uv", "pip", "install"]
+            if upgrade:
+                cmd.append("--upgrade")
+            cmd.append(pkg)
+            if is_chinese:
+                cmd.extend(["--index-url", "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"])
+        else:
+            cmd = [sys.executable, "-m", "pip", "install"]
+            if upgrade:
+                cmd.append("--upgrade")
+            cmd.append(pkg)
+            if is_chinese:
+                cmd.extend(["-i", "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"])
 
-        for installer in installers:
-            cmd = _install_command(installer, pkg, upgrade, is_chinese)
-            try:
-                result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
-                if result.returncode == 0:
-                    print_status(f"✓ {pkg} {action_word}成功 (via {installer})", "success")
-                    pkg_installed = True
-                    break
-
-                last_error = result.stderr.strip().split("\n")[-1] if result.stderr else "unknown error"
-                print_status(f"× {pkg} {action_word}失败 (via {installer}): {last_error}", "warning")
-            except subprocess.TimeoutExpired:
-                last_error = "timeout after 300s"
-                print_status(f"× {pkg} {action_word}超时 (via {installer}, 300s)", "warning")
-            except Exception as e:
-                last_error = str(e)
-                print_status(f"× {pkg} {action_word}异常 (via {installer}): {e}", "warning")
-
-        if not pkg_installed:
-            print_status(f"× {pkg} {action_word}失败: {last_error}", "error")
-            _print_manual_git_install_hint(pkg)
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+            if result.returncode == 0:
+                installer = "uv" if use_uv else "pip"
+                print_status(f"✓ {pkg} {action_word}成功 (via {installer})", "success")
+            else:
+                stderr_short = result.stderr.strip().split("\n")[-1] if result.stderr else "unknown error"
+                print_status(f"× {pkg} {action_word}失败: {stderr_short}", "error")
+                failed.append(pkg)
+        except subprocess.TimeoutExpired:
+            print_status(f"× {pkg} {action_word}超时 (300s)", "error")
+            failed.append(pkg)
+        except Exception as e:
+            print_status(f"× {pkg} {action_word}异常: {e}", "error")
             failed.append(pkg)
 
     if failed:

unilabos/utils/import_manager.py

@@ -206,7 +206,6 @@ class ImportManager:
             "ast_analysis_success": False,
             "import_map": {},
             "init_params": [],
-            "init_docstring": None,
             "status_methods": {},
             "action_methods": {},
         }
@@ -252,7 +251,6 @@ class ImportManager:
 
         # 映射到统一字段名（与 registry.py complete_registry 消费端一致）
         result["init_params"] = body.get("init_params", [])
-        result["init_docstring"] = body.get("init_docstring")
         result["status_methods"] = body.get("status_properties", {})
         result["action_methods"] = {
             k: {

unilabos_msgs/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>unilabos_msgs</name>
-  <version>0.11.3</version>
+  <version>0.11.1</version>
   <description>ROS2 Messages package for unilabos devices</description>
   <maintainer email="changjh@pku.edu.cn">Junhan Chang</maintainer>
   <maintainer email="18435084+Xuwznln@users.noreply.github.com">Xuwznln</maintainer>