v0.10.18

no opcua installation on macos
fix possible crash fix deck & host_node set liquid with tube add test_resource_schema fix test resource schema registry update & workflow update add test mode support description & tags upload fix config load fix log add registry name & add always free correct config organic synthesis Adapt to new scheduler, sampels, and edge upload format (#230) * add sample_material * adapt to new samples sys * fix pump transfer. fix resource update when protocol & ros callback * Adapt to new scheduler. Feat/samples (#229) * add sample_material * adapt to new samples sys adapt to new samples sys adapt to new edge format workflow upload & prcxi transfer liquid lh liquid speed up registry load workflow upload & set liquid fix & add set liquid with plate fix upload workflow json
2026-03-24 14:29:19 +00:00 · 2026-02-28 09:53:31 +08:00 · 2026-02-28 09:46:46 +08:00 · 2026-02-02 18:26:41 +08:00 · 2026-01-28 11:46:54 +08:00 · 2026-01-27 19:59:22 +08:00
52 changed files with 1431 additions and 8842 deletions
--- a/.cursor/rules/device-drivers.mdc
+++ b/.cursor/rules/device-drivers.mdc
@@ -1,328 +0,0 @@
 ---
 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
--- a/.cursor/rules/protocol-development.mdc
+++ b/.cursor/rules/protocol-development.mdc
@@ -1,240 +0,0 @@
 ---
 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` - 蒸发操作
--- a/.cursor/rules/registry-config.mdc
+++ b/.cursor/rules/registry-config.mdc
@@ -1,319 +0,0 @@
 ---
 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
 ```
--- a/.cursor/rules/ros-integration.mdc
+++ b/.cursor/rules/ros-integration.mdc
@@ -1,233 +0,0 @@
 ---
 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 方法中正确清理资源
--- a/.cursor/rules/testing-patterns.mdc
+++ b/.cursor/rules/testing-patterns.mdc
@@ -1,357 +0,0 @@
 ---
 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. **断言清晰**: 每个断言只验证一件事
--- a/.cursor/rules/unilabos-project.mdc
+++ b/.cursor/rules/unilabos-project.mdc
@@ -1,353 +0,0 @@
 ---
 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类
 - 支持定时搅拌和持续搅拌模式
 - 添加速度验证逻辑
 ```
--- a/.cursor/skills/add-device/SKILL.md
+++ b/.cursor/skills/add-device/SKILL.md
@@ -1,24 +0,0 @@
 ---
 name: add-device
 description: Guide for adding new devices to Uni-Lab-OS (接入新设备). Walks through device category selection (thing model), communication protocol, command protocol collection, driver creation, registry YAML, and graph file setup. Use when the user wants to add/integrate a new device, create a device driver, write a device class, configure device registry, or mentions 接入设备/添加设备/设备驱动/物模型.
 ---
 # 添加新设备到 Uni-Lab-OS
 **第一步：** 使用 Read 工具读取 `docs/ai_guides/add_device.md`，获取完整的设备接入指南并严格遵循。
 该指南包含：
 - 8 步完整流程（设备类别、通信协议、指令收集、接口对齐、驱动创建、注册表、图文件、验证）
 - 所有物模型代码模板（注射泵、电磁阀、蠕动泵、温控、电机等）
 - 通信协议代码片段（Serial、Modbus、TCP、HTTP、OPC UA）
 - 现有设备接口快照（用于第四步对齐，包含参数名、status_types、方法签名）
 - 常见错误检查清单
 **Cursor 工具映射：**
 | 指南中的操作 | Cursor 中使用的工具 |
 |---|---|
 | 向用户确认设备类别、协议等信息 | 使用 AskQuestion 工具 |
 | 搜索已有设备注册表 | 使用 Grep 在 `unilabos/registry/devices/` 中搜索 |
 | 读取用户提供的协议文档/SDK 代码 | 使用 Read 工具 |
 | 第四步对齐：查找同类设备接口 | 优先使用 Grep 搜索仓库中的最新注册表；指南中的「现有设备接口快照」作为兜底参考 |
--- a/.cursor/skills/add-protocol/SKILL.md
+++ b/.cursor/skills/add-protocol/SKILL.md
@@ -1,323 +0,0 @@
 ---
 name: add-protocol
 description: Guide for adding new experiment protocols to Uni-Lab-OS (添加新实验操作协议). Walks through ROS Action definition, Pydantic model creation, protocol generator implementation, and registration. Use when the user wants to add a new protocol, create a compile function, implement an experiment operation, or mentions 协议/protocol/编译/compile/实验操作.
 ---
 # 添加新实验操作协议（Protocol）
 Protocol 是对实验有意义的完整动作（如泵转移、过滤、溶解），需要多设备协同。`compile/` 中的生成函数根据设备连接图将抽象操作"编译"为设备指令序列。
 添加一个 Protocol 需修改 **6 个文件**，按以下流程执行。
 ---
 ## 第一步：确认协议信息
 向用户确认：
 | 信息 | 示例 |
 |------|------|
 | 协议英文名 | `MyNewProtocol` |
 | 操作描述 | 将固体样品研磨至目标粒径 |
 | Goal 参数（必需 + 可选） | `vessel: dict`, `time: float = 300.0` |
 | Result 字段 | `success: bool`, `message: str` |
 | 需要哪些设备协同 | 研磨器、搅拌器 |
 ---
 ## 第二步：创建 ROS Action 定义
 路径：`unilabos_msgs/action/<ActionName>.action`
 三段式结构（Goal / Result / Feedback），用 `---` 分隔：
 ```
 # Goal
 Resource vessel
 float64 time
 string mode
 ---
 # Result
 bool success
 string return_info
 ---
 # Feedback
 string status
 string current_device
 builtin_interfaces/Duration time_spent
 builtin_interfaces/Duration time_remaining
 ```
 **类型映射：**
 | Python 类型 | ROS 类型 | 说明 |
 |------------|----------|------|
 | `dict` | `Resource` | 容器/设备引用，自定义消息类型 |
 | `float` | `float64` | |
 | `int` | `int32` | |
 | `str` | `string` | |
 | `bool` | `bool` | |
 > `Resource` 是 `unilabos_msgs/msg/Resource.msg` 中定义的自定义消息类型。
 ---
 ## 第三步：注册 Action 到 CMakeLists
 在 `unilabos_msgs/CMakeLists.txt` 的 `set(action_files ...)` 块中添加：
 ```cmake
 "action/MyNewAction.action"
 ```
 > 调试时需编译：`cd unilabos_msgs && colcon build && source ./install/local_setup.sh && cd ..`
 > PR 合并后 CI/CD 自动发布，`mamba update ros-humble-unilabos-msgs` 即可。
 ---
 ## 第四步：创建 Pydantic 模型
 在 `unilabos/messages/__init__.py` 中添加（位于 `# Start Protocols` 和 `# End Protocols` 之间）：
 ```python
 class MyNewProtocol(BaseModel):
    # === 必需参数 ===
    vessel: dict = Field(..., description="目标容器")
    # === 可选参数 ===
    time: float = Field(300.0, description="操作时间 (秒)")
    mode: str = Field("default", description="操作模式")
    def model_post_init(self, __context):
        """参数验证和修正"""
        if self.time <= 0:
            self.time = 300.0
 ```
 **规则：**
 - 参数名必须与 `.action` 文件中 Goal 字段完全一致
 - `dict` 类型对应 `.action` 中的 `Resource`
 - 将类名加入文件末尾的 `__all__` 列表
 ---
 ## 第五步：实现协议生成函数
 路径：`unilabos/compile/<protocol_name>_protocol.py`
 ```python
 import networkx as nx
 from typing import List, Dict, Any
 def generate_my_new_protocol(
    G: nx.DiGraph,
    vessel: dict,
    time: float = 300.0,
    mode: str = "default",
    **kwargs,
 ) -> List[Dict[str, Any]]:
    """将 MyNewProtocol 编译为设备动作序列。
    Args:
        G: 设备连接图（NetworkX），节点为设备/容器，边为物理连接
        vessel: 目标容器 {"id": "reactor_1"}
        time: 操作时间（秒）
        mode: 操作模式
    Returns:
        动作列表，每个元素为:
        - dict: 单步动作
        - list[dict]: 并行动作
    """
    from unilabos.compile.utils.vessel_parser import get_vessel
    vessel_id, vessel_data = get_vessel(vessel)
    actions = []
    # 查找相关设备（通过图的连接关系）
    # 生成动作序列
    actions.append({
        "device_id": "target_device_id",
        "action_name": "some_action",
        "action_kwargs": {"param": "value"}
    })
    # 等待
    actions.append({
        "action_name": "wait",
        "action_kwargs": {"time": time}
    })
    return actions
 ```
 ### 动作字典格式
 ```python
 # 单步动作（发给子设备）
 {"device_id": "pump_1", "action_name": "set_position", "action_kwargs": {"position": 10.0}}
 # 发给工作站自身
 {"device_id": "self", "action_name": "my_action", "action_kwargs": {...}}
 # 等待
 {"action_name": "wait", "action_kwargs": {"time": 5.0}}
 # 并行动作（列表嵌套）
 [
    {"device_id": "pump_1", "action_name": "set_position", "action_kwargs": {"position": 10.0}},
    {"device_id": "stirrer_1", "action_name": "start_stir", "action_kwargs": {"stir_speed": 300}}
 ]
 ```
 ### 关于 `vessel` 参数类型
 现有协议的 `vessel` 参数类型不统一：
 - 新协议趋势：使用 `dict`（如 `{"id": "reactor_1"}`）
 - 旧协议：使用 `str`（如 `"reactor_1"`）
 - 兼容写法：`Union[str, dict]`
 **建议新协议统一使用 `dict` 类型**，通过 `get_vessel()` 兼容两种输入。
 ### 公共工具函数（`unilabos/compile/utils/`）
 | 函数 | 用途 |
 |------|------|
 | `get_vessel(vessel)` | 解析容器参数为 `(vessel_id, vessel_data)`，兼容 dict 和 str |
 | `find_solvent_vessel(G, solvent)` | 根据溶剂名查找容器（精确→命名规则→模糊→液体类型） |
 | `find_reagent_vessel(G, reagent)` | 根据试剂名查找容器（支持固体和液体） |
 | `find_connected_stirrer(G, vessel)` | 查找与容器相连的搅拌器 |
 | `find_solid_dispenser(G)` | 查找固体加样器 |
 ### 协议内专属查找函数
 许多协议在自己的文件内定义了专属的 `find_*` 函数（不在 `utils/` 中）。编写新协议时，优先复用 `utils/` 中的公共函数；如需特殊查找逻辑，在协议文件内部定义即可：
 ```python
 def find_my_special_device(G: nx.DiGraph, vessel: str) -> str:
    """查找与容器相关的特殊设备"""
    for node in G.nodes():
        if 'my_device_type' in G.nodes[node].get('class', '').lower():
            return node
    raise ValueError("未找到特殊设备")
 ```
 ### 复用已有协议
 复杂协议通常组合已有协议：
 ```python
 from unilabos.compile.pump_protocol import generate_pump_protocol_with_rinsing
 actions.extend(generate_pump_protocol_with_rinsing(
    G, from_vessel=solvent_vessel, to_vessel=vessel, volume=volume
 ))
 ```
 ### 图查询模式
 ```python
 # 查找与容器相连的特定类型设备
 for neighbor in G.neighbors(vessel_id):
    node_data = G.nodes[neighbor]
    if "heater" in node_data.get("class", ""):
        heater_id = neighbor
        break
 # 查找最短路径（泵转移）
 path = nx.shortest_path(G, source=from_vessel_id, target=to_vessel_id)
 ```
 ---
 ## 第六步：注册协议生成函数
 在 `unilabos/compile/__init__.py` 中：
 1. 顶部添加导入：
 ```python
 from .my_new_protocol import generate_my_new_protocol
 ```
 2. 在 `action_protocol_generators` 字典中添加映射：
 ```python
 action_protocol_generators = {
    # ... 已有协议
    MyNewProtocol: generate_my_new_protocol,
 }
 ```
 ---
 ## 第七步：配置图文件
 在工作站的图文件中，将协议名加入 `protocol_type`：
 ```json
 {
    "id": "my_station",
    "class": "workstation",
    "config": {
        "protocol_type": ["PumpTransferProtocol", "MyNewProtocol"]
    }
 }
 ```
 ---
 ## 第八步：验证
 ```bash
 # 1. 模块可导入
 python -c "from unilabos.messages import MyNewProtocol; print(MyNewProtocol.model_fields)"
 # 2. 生成函数可导入
 python -c "from unilabos.compile import action_protocol_generators; print(list(action_protocol_generators.keys()))"
 # 3. 启动测试（可选）
 unilab -g <graph>.json --complete_registry
 ```
 ---
 ## 工作流清单
 ```
 协议接入进度：
 - [ ] 1. 确认协议名、参数、涉及设备
 - [ ] 2. 创建 .action 文件 (unilabos_msgs/action/<Name>.action)
 - [ ] 3. 注册到 CMakeLists.txt
 - [ ] 4. 创建 Pydantic 模型 (unilabos/messages/__init__.py) + 更新 __all__
 - [ ] 5. 实现生成函数 (unilabos/compile/<name>_protocol.py)
 - [ ] 6. 注册到 compile/__init__.py
 - [ ] 7. 配置图文件 protocol_type
 - [ ] 8. 验证
 ```
 ---
 ## 高级模式
 实现复杂协议时，详见 [reference.md](reference.md)：协议运行时数据流、mock graph 测试模式、单位解析工具（`unit_parser.py`）、复杂协议组合模式（以 dissolve 为例）。
 ---
 ## 现有协议速查
 | 协议 | Pydantic 类 | 生成函数 | 核心参数 |
 |------|-------------|---------|---------|
 | 泵转移 | `PumpTransferProtocol` | `generate_pump_protocol_with_rinsing` | `from_vessel, to_vessel, volume` |
 | 简单转移 | `TransferProtocol` | `generate_pump_protocol` | `from_vessel, to_vessel, volume` |
 | 加样 | `AddProtocol` | `generate_add_protocol` | `vessel, reagent, volume` |
 | 过滤 | `FilterProtocol` | `generate_filter_protocol` | `vessel, filtrate_vessel` |
 | 溶解 | `DissolveProtocol` | `generate_dissolve_protocol` | `vessel, solvent, volume` |
 | 加热/冷却 | `HeatChillProtocol` | `generate_heat_chill_protocol` | `vessel, temp, time` |
 | 搅拌 | `StirProtocol` | `generate_stir_protocol` | `vessel, time` |
 | 分离 | `SeparateProtocol` | `generate_separate_protocol` | `from_vessel, separation_vessel, solvent` |
 | 蒸发 | `EvaporateProtocol` | `generate_evaporate_protocol` | `vessel, pressure, temp, time` |
 | 清洗 | `CleanProtocol` | `generate_clean_protocol` | `vessel, solvent, volume` |
 | 离心 | `CentrifugeProtocol` | `generate_centrifuge_protocol` | `vessel, speed, time` |
 | 抽气充气 | `EvacuateAndRefillProtocol` | `generate_evacuateandrefill_protocol` | `vessel, gas` |
--- a/.cursor/skills/add-protocol/reference.md
+++ b/.cursor/skills/add-protocol/reference.md
@@ -1,207 +0,0 @@
 # 协议高级参考
 本文件是 SKILL.md 的补充，包含协议运行时数据流、测试模式、单位解析工具和复杂协议组合模式。Agent 在需要实现这些功能时按需阅读。
 ---
 ## 1. 协议运行时数据流
 从图文件到协议执行的完整链路：
 ```
 实验图 JSON
    ↓  graphio.read_node_link_json()
 physical_setup_graph (NetworkX DiGraph)
    ↓  ROS2WorkstationNode._setup_protocol_names(protocol_type)
 为每个 protocol_name 创建 ActionServer
    ↓  收到 Action Goal
 _create_protocol_execute_callback()
    ↓  convert_from_ros_msg_with_mapping(goal, mapping)
 protocol_kwargs (Python dict)
    ↓  向 Host 查询 Resource 类型参数的当前状态
 protocol_kwargs 更新（vessel 带上 children、data 等）
    ↓  protocol_steps_generator(G=physical_setup_graph, **protocol_kwargs)
 List[Dict] 动作序列
    ↓  逐步 execute_single_action / 并行 create_task
 子设备 ActionClient 执行
 ```
 ### `_setup_protocol_names` 核心逻辑
 ```python
 def _setup_protocol_names(self, protocol_type):
    if isinstance(protocol_type, str):
        self.protocol_names = [p.strip() for p in protocol_type.split(",")]
    else:
        self.protocol_names = protocol_type
    self.protocol_action_mappings = {}
    for protocol_name in self.protocol_names:
        protocol_type = globals()[protocol_name]  # 从 messages 模块取 Pydantic 类
        self.protocol_action_mappings[protocol_name] = get_action_type(protocol_type)
 ```
 ### `_create_protocol_execute_callback` 关键步骤
 1. `convert_from_ros_msg_with_mapping(goal, action_value_mapping["goal"])` — ROS Goal → Python dict
 2. 对 `Resource` 类型字段，通过 `resource_get` Service 查询 Host 的最新资源状态
 3. `protocol_steps_generator(G=physical_setup_graph, **protocol_kwargs)` — 调用编译函数
 4. 遍历 steps：`dict` 串行执行，`list` 并行执行
 5. `execute_single_action` 通过 `_action_clients[device_id]` 向子设备发送 Action Goal
 6. 执行完毕后通过 `resource_update` Service 更新资源状态
 ---
 ## 2. 测试模式
 ### 2.1 协议文件内测试函数
 许多协议文件末尾有 `test_*` 函数，主要测试参数解析工具：
 ```python
 def test_dissolve_protocol():
    """测试溶解协议的各种参数解析"""
    volumes = ["10 mL", "?", 10.0, "1 L", "500 μL"]
    for vol in volumes:
        result = parse_volume_input(vol)
        print(f"体积解析: {vol} → {result}mL")
    masses = ["2.9 g", "?", 2.5, "500 mg"]
    for mass in masses:
        result = parse_mass_input(mass)
        print(f"质量解析: {mass} → {result}g")
 ```
 ### 2.2 使用 mock graph 测试协议生成器
 推荐的端到端测试模式：
 ```python
 import pytest
 import networkx as nx
 from unilabos.compile.stir_protocol import generate_stir_protocol
@pytest.fixture
 def topology_graph():
    """创建测试拓扑图"""
    G = nx.DiGraph()
    G.add_node("flask_1", **{"class": "flask", "type": "container"})
    G.add_node("stirrer_1", **{"class": "virtual_stirrer", "type": "device"})
    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"
 ```
 **要点：**
 - 用 `nx.DiGraph()` 构建最小拓扑
 - `add_node(id, **attrs)` 设置 `class`、`type`、`data` 等
 - `add_edge(src, dst)` 建立物理连接
 - 协议内的 `find_*` 函数依赖这些节点和边
 ---
 ## 3. 单位解析工具
 路径：`unilabos/compile/utils/unit_parser.py`
 | 函数 | 输入 | 返回 | 默认值 |
 |------|------|------|--------|
 | `parse_volume_input(input, default_unit)` | `"100 mL"`, `"2.5 L"`, `"500 μL"`, `10.0`, `"?"` | mL (float) | 50.0 |
 | `parse_mass_input(input)` | `"19.3 g"`, `"500 mg"`, `2.5`, `"?"` | g (float) | 1.0 |
 | `parse_time_input(input)` | `"30 min"`, `"1 h"`, `"300"`, `60.0`, `"?"` | 秒 (float) | 60.0 |
 支持的单位：
 - **体积**: mL, L, μL/uL, milliliter, liter, microliter
 - **质量**: g, mg, kg, gram, milligram, kilogram
 - **时间**: s/sec/second, min/minute, h/hr/hour, d/day
 特殊值 `"?"`、`"unknown"`、`"tbd"` 返回默认值。
 ---
 ## 4. 复杂协议组合模式
 以 `dissolve_protocol` 为例，展示如何组合多个子操作：
 ### 整体流程
 ```
 1. 解析参数 (parse_volume_input, parse_mass_input, parse_time_input)
 2. 设备发现 (find_connected_heatchill, find_connected_stirrer, find_solid_dispenser)
 3. 判断溶解类型 (液体 vs 固体)
 4. 组合动作序列:
   a. heat_chill_start / start_stir  (启动加热/搅拌)
   b. wait                           (等待温度稳定)
   c. pump_protocol_with_rinsing     (液体转移, 通过 extend 拼接)
      或 add_solid                   (固体加样)
   d. heat_chill / stir / wait       (溶解等待)
   e. heat_chill_stop                (停止加热)
 ```
 ### 关键代码模式
 **设备发现 → 条件组合：**
 ```python
 heatchill_id = find_connected_heatchill(G, vessel_id)
 stirrer_id = find_connected_stirrer(G, vessel_id)
 solid_dispenser_id = find_solid_dispenser(G)
 actions = []
 # 启动阶段
 if heatchill_id and temp > 25.0:
    actions.append({
        "device_id": heatchill_id,
        "action_name": "heat_chill_start",
        "action_kwargs": {"vessel": {"id": vessel_id}, "temp": temp}
    })
    actions.append({"action_name": "wait", "action_kwargs": {"time": 30}})
 elif stirrer_id:
    actions.append({
        "device_id": stirrer_id,
        "action_name": "start_stir",
        "action_kwargs": {"vessel": {"id": vessel_id}, "stir_speed": stir_speed}
    })
 # 转移阶段（复用已有协议）
 pump_actions = generate_pump_protocol_with_rinsing(
    G=G, from_vessel=solvent_vessel, to_vessel=vessel_id, volume=volume
 )
 actions.extend(pump_actions)
 # 等待阶段
 if heatchill_id:
    actions.append({
        "device_id": heatchill_id,
        "action_name": "heat_chill",
        "action_kwargs": {"vessel": {"id": vessel_id}, "temp": temp, "time": time}
    })
 else:
    actions.append({"action_name": "wait", "action_kwargs": {"time": time}})
 ```
 ---
 ## 5. 关键路径
 | 内容 | 路径 |
 |------|------|
 | 协议执行回调 | `unilabos/ros/nodes/presets/workstation.py` |
 | ROS 消息映射 | `unilabos/ros/msgs/message_converter.py` |
 | 物理拓扑图 | `unilabos/resources/graphio.py` (`physical_setup_graph`) |
 | 单位解析 | `unilabos/compile/utils/unit_parser.py` |
 | 容器解析 | `unilabos/compile/utils/vessel_parser.py` |
 | 溶解协议（组合示例） | `unilabos/compile/dissolve_protocol.py` |
--- a/.cursor/skills/add-resource/SKILL.md
+++ b/.cursor/skills/add-resource/SKILL.md
@@ -1,371 +0,0 @@
 ---
 name: add-resource
 description: Guide for adding new resources (materials, bottles, carriers, decks, warehouses) to Uni-Lab-OS (添加新物料/资源). Covers Bottle, Carrier, Deck, WareHouse definitions and registry YAML. Use when the user wants to add resources, define materials, create a deck layout, add bottles/carriers/plates, or mentions 物料/资源/resource/bottle/carrier/deck/plate/warehouse.
 ---
 # 添加新物料资源
 Uni-Lab-OS 的资源体系基于 PyLabRobot，通过扩展实现 Bottle、Carrier、WareHouse、Deck 等实验室物料管理。
 ---
 ## 第一步：确认资源类型
 向用户确认需要添加的资源类型：
 | 类型 | 基类 | 用途 | 示例 |
 |------|------|------|------|
 | **Bottle** | `Well` (PyLabRobot) | 单个容器（瓶、小瓶、烧杯、反应器） | 试剂瓶、粉末瓶 |
 | **BottleCarrier** | `ItemizedCarrier` | 多槽位载架（放多个 Bottle） | 6 位试剂架、枪头盒 |
 | **WareHouse** | `ItemizedCarrier` | 堆栈/仓库（放多个 Carrier） | 4x4 堆栈 |
 | **Deck** | `Deck` (PyLabRobot) | 工作站台面（放多个 WareHouse） | 反应站 Deck |
 **层级关系：** `Deck` → `WareHouse` → `BottleCarrier` → `Bottle`
 还需确认：
 - 资源所属的项目/场景（如 bioyond、battery、通用）
 - 尺寸参数（直径、高度、最大容积等）
 - 布局参数（行列数、间距等）
 ---
 ## 第二步：创建资源定义
 ### 文件位置
 ```
 unilabos/resources/
 ├── <project>/          # 按项目分组
 │   ├── bottles.py      # Bottle 工厂函数
 │   ├── bottle_carriers.py  # Carrier 工厂函数
 │   ├── warehouses.py   # WareHouse 工厂函数
 │   └── decks.py        # Deck 类定义
 ├── itemized_carrier.py # Bottle, BottleCarrier, ItemizedCarrier 基类
 ├── warehouse.py        # WareHouse 基类
 └── container.py        # 通用容器
 ```
 ### 2A. 添加 Bottle（工厂函数）
 ```python
 from unilabos.resources.itemized_carrier import Bottle
 def My_Reagent_Bottle(
    name: str,
    diameter: float = 70.0,     # 瓶体直径 (mm)
    height: float = 120.0,      # 瓶体高度 (mm)
    max_volume: float = 500000.0,  # 最大容积 (μL)
    barcode: str = None,
 ) -> Bottle:
    """创建试剂瓶"""
    return Bottle(
        name=name,
        diameter=diameter,
        height=height,
        max_volume=max_volume,
        barcode=barcode,
        model="My_Reagent_Bottle",  # 唯一标识，用于注册表和物料映射
    )
 ```
 **Bottle 参数：**
 - `name`: 实例名称（运行时唯一）
 - `diameter`: 瓶体直径 (mm)
 - `height`: 瓶体高度 (mm)
 - `max_volume`: 最大容积 (**μL**，注意单位！500mL = 500000)
 - `barcode`: 条形码（可选）
 - `model`: 模型标识，与注册表 key 一致
 ### 2B. 添加 BottleCarrier（工厂函数）
 ```python
 from pylabrobot.resources import ResourceHolder
 from pylabrobot.resources.carrier import create_ordered_items_2d
 from unilabos.resources.itemized_carrier import BottleCarrier
 def My_6SlotCarrier(name: str) -> BottleCarrier:
    """创建 3x2 六槽位载架"""
    sites = create_ordered_items_2d(
        klass=ResourceHolder,
        num_items_x=3,       # 列数
        num_items_y=2,       # 行数
        dx=10.0,             # X 起始偏移
        dy=10.0,             # Y 起始偏移
        dz=5.0,              # Z 偏移
        item_dx=42.0,        # X 间距
        item_dy=35.0,        # Y 间距
        size_x=20.0,         # 槽位宽
        size_y=20.0,         # 槽位深
        size_z=50.0,         # 槽位高
    )
    carrier = BottleCarrier(
        name=name,
        size_x=146.0,        # 载架总宽
        size_y=80.0,         # 载架总深
        size_z=55.0,         # 载架总高
        sites=sites,
        model="My_6SlotCarrier",
    )
    carrier.num_items_x = 3
    carrier.num_items_y = 2
    carrier.num_items_z = 1
    # 预装 Bottle（可选）
    ordering = ["A01", "A02", "A03", "B01", "B02", "B03"]
    for i in range(6):
        carrier[i] = My_Reagent_Bottle(f"{ordering[i]}")
    return carrier
 ```
 ### 2C. 添加 WareHouse（工厂函数）
 ```python
 from unilabos.resources.warehouse import warehouse_factory
 def my_warehouse_4x4(name: str) -> "WareHouse":
    """创建 4行x4列 堆栈仓库"""
    return warehouse_factory(
        name=name,
        num_items_x=4,            # 列数
        num_items_y=4,            # 行数
        num_items_z=1,            # 层数（通常为 1）
        dx=137.0,                 # X 起始偏移
        dy=96.0,                  # Y 起始偏移
        dz=120.0,                 # Z 起始偏移
        item_dx=137.0,            # X 间距
        item_dy=125.0,            # Y 间距
        item_dz=10.0,             # Z 间距（多层时用）
        resource_size_x=127.0,    # 槽位宽
        resource_size_y=85.0,     # 槽位深
        resource_size_z=100.0,    # 槽位高
        model="my_warehouse_4x4",
    )
 ```
 **`warehouse_factory` 参数说明：**
 | 参数 | 说明 |
 |------|------|
 | `num_items_x/y/z` | 列数/行数/层数 |
 | `dx, dy, dz` | 第一个槽位的起始坐标偏移 |
 | `item_dx, item_dy, item_dz` | 相邻槽位间距 |
 | `resource_size_x/y/z` | 单个槽位的物理尺寸 |
 | `col_offset` | 列命名偏移（如设 4 则从 A05 开始） |
 | `row_offset` | 行命名偏移（如设 5 则从 F 行开始） |
 | `layout` | 排序方式：`"col-major"`（列优先，默认）/ `"row-major"`（行优先） |
 | `removed_positions` | 要移除的位置索引列表 |
 自动生成 `ResourceHolder` 槽位，命名规则为 `A01, B01, C01, D01, A02, ...`（列优先）或 `A01, A02, A03, A04, B01, ...`（行优先）。
 ### 2D. 添加 Deck（类定义）
 ```python
 from pylabrobot.resources import Deck, Coordinate
 class MyStation_Deck(Deck):
    def __init__(
        self,
        name: str = "MyStation_Deck",
        size_x: float = 2700.0,
        size_y: float = 1080.0,
        size_z: float = 1500.0,
        category: str = "deck",
        setup: bool = False,
    ) -> None:
        super().__init__(name=name, size_x=size_x, size_y=size_y, size_z=size_z)
        if setup:
            self.setup()
    def setup(self) -> None:
        self.warehouses = {
            "仓库A": my_warehouse_4x4("仓库A"),
            "仓库B": my_warehouse_4x4("仓库B"),
        }
        self.warehouse_locations = {
            "仓库A": Coordinate(-200.0, 400.0, 0.0),
            "仓库B": Coordinate(2350.0, 400.0, 0.0),
        }
        for wh_name, wh in self.warehouses.items():
            self.assign_child_resource(wh, location=self.warehouse_locations[wh_name])
 ```
 **Deck 要点：**
 - 继承 `pylabrobot.resources.Deck`
 - `setup()` 创建 WareHouse 并通过 `assign_child_resource` 放置到指定坐标
 - `setup` 参数控制是否在构造时自动调用 `setup()`（图文件中通过 `config.setup: true` 触发）
 ---
 ## 第三步：创建注册表 YAML
 路径：`unilabos/registry/resources/<project>/<type>.yaml`
 ### Bottle 注册
 ```yaml
 My_Reagent_Bottle:
  category:
  - bottles
  class:
    module: unilabos.resources.my_project.bottles:My_Reagent_Bottle
    type: pylabrobot
  description: 我的试剂瓶
  handles: []
  icon: ''
  init_param_schema: {}
  version: 1.0.0
 ```
 ### Carrier 注册
 ```yaml
 My_6SlotCarrier:
  category:
  - bottle_carriers
  class:
    module: unilabos.resources.my_project.bottle_carriers:My_6SlotCarrier
    type: pylabrobot
  handles: []
  icon: ''
  init_param_schema: {}
  version: 1.0.0
 ```
 ### Deck 注册
 ```yaml
 MyStation_Deck:
  category:
  - deck
  class:
    module: unilabos.resources.my_project.decks:MyStation_Deck
    type: pylabrobot
  description: 我的工作站 Deck
  handles: []
  icon: ''
  init_param_schema: {}
  registry_type: resource
  version: 1.0.0
 ```
 **注册表规则：**
 - `class.module` 格式为 `python.module.path:ClassName_or_FunctionName`
 - `class.type` 固定为 `pylabrobot`
 - Key（如 `My_Reagent_Bottle`）必须与工厂函数名 / 类名一致
 - `category` 按类型标注（`bottles`, `bottle_carriers`, `deck` 等）
 ---
 ## 第四步：在图文件中引用
 ### Deck 在工作站中的引用
 工作站节点通过 `deck` 字段引用，Deck 作为子节点：
 ```json
 {
    "id": "my_station",
    "children": ["my_deck"],
    "deck": {
        "data": {
            "_resource_child_name": "my_deck",
            "_resource_type": "unilabos.resources.my_project.decks:MyStation_Deck"
        }
    }
 },
 {
    "id": "my_deck",
    "parent": "my_station",
    "type": "deck",
    "class": "MyStation_Deck",
    "config": {"type": "MyStation_Deck", "setup": true}
 }
 ```
 ### 物料类型映射（外部系统对接时）
 如果工作站需要与外部系统同步物料，在 config 中配置 `material_type_mappings`：
 ```json
 "material_type_mappings": {
    "My_Reagent_Bottle": ["试剂瓶", "external-type-uuid"],
    "My_6SlotCarrier": ["六槽载架", "external-type-uuid"]
 }
 ```
 ---
 ## 第五步：注册 PLR 扩展（如需要）
 如果添加了新的 Deck 类，需要在 `unilabos/resources/plr_additional_res_reg.py` 中导入，使 `find_subclass` 能发现它：
 ```python
 def register():
    from unilabos.resources.my_project.decks import MyStation_Deck
 ```
 ---
 ## 第六步：验证
 ```bash
 # 1. 资源可导入
 python -c "from unilabos.resources.my_project.bottles import My_Reagent_Bottle; print(My_Reagent_Bottle('test'))"
 # 2. Deck 可创建
 python -c "
 from unilabos.resources.my_project.decks import MyStation_Deck
 d = MyStation_Deck('test', setup=True)
 print(d.children)
 "
 # 3. 启动测试
 unilab -g <graph>.json --complete_registry
 ```
 ---
 ## 工作流清单
 ```
 资源接入进度：
 - [ ] 1. 确定资源类型（Bottle / Carrier / WareHouse / Deck）
 - [ ] 2. 创建资源定义（工厂函数/类）
 - [ ] 3. 创建注册表 YAML (unilabos/registry/resources/<project>/<type>.yaml)
 - [ ] 4. 在图文件中引用（如需要）
 - [ ] 5. 注册 PLR 扩展（Deck 类需要）
 - [ ] 6. 验证
 ```
 ---
 ## 高级模式
 实现复杂资源系统时，详见 [reference.md](reference.md)：类继承体系完整图、序列化/反序列化流程、Bioyond 物料双向同步、非瓶类资源（ElectrodeSheet / Magazine）、仓库工厂 layout 模式。
 ---
 ## 现有资源参考
 | 项目 | Bottles | Carriers | WareHouses | Decks |
 |------|---------|----------|------------|-------|
 | bioyond | `bioyond/bottles.py` | `bioyond/bottle_carriers.py` | `bioyond/warehouses.py`, `YB_warehouses.py` | `bioyond/decks.py` |
 | battery | — | `battery/bottle_carriers.py` | — | — |
 | 通用 | — | — | `warehouse.py` | — |
 ### 关键路径
 | 内容 | 路径 |
 |------|------|
 | Bottle/Carrier 基类 | `unilabos/resources/itemized_carrier.py` |
 | WareHouse 基类 + 工厂 | `unilabos/resources/warehouse.py` |
 | PLR 注册 | `unilabos/resources/plr_additional_res_reg.py` |
 | 资源注册表 | `unilabos/registry/resources/` |
 | 图文件加载 | `unilabos/resources/graphio.py` |
 | 资源跟踪器 | `unilabos/resources/resource_tracker.py` |
--- a/.cursor/skills/add-resource/reference.md
+++ b/.cursor/skills/add-resource/reference.md
@@ -1,292 +0,0 @@
 # 资源高级参考
 本文件是 SKILL.md 的补充，包含类继承体系、序列化/反序列化、Bioyond 物料同步、非瓶类资源和仓库工厂模式。Agent 在需要实现这些功能时按需阅读。
 ---
 ## 1. 类继承体系
 ```
 PyLabRobot
 ├── Resource (PLR 基类)
 │   ├── Well
 │   │   └── Bottle (unilabos)        → 瓶/小瓶/烧杯/反应器
 │   ├── Deck
 │   │   └── 自定义 Deck 类 (unilabos) → 工作站台面
 │   ├── ResourceHolder               → 槽位占位符
 │   └── Container
 │       └── Battery (unilabos)       → 组装好的电池
 │
 ├── ItemizedCarrier (unilabos, 继承 Resource)
 │   ├── BottleCarrier (unilabos)     → 瓶载架
 │   └── WareHouse (unilabos)         → 堆栈仓库
 │
 ├── ItemizedResource (PLR)
 │   └── MagazineHolder (unilabos)    → 子弹夹载架
 │
 └── ResourceStack (PLR)
    └── Magazine (unilabos)          → 子弹夹洞位
 ```
 ### Bottle 类细节
 ```python
 class Bottle(Well):
    def __init__(self, name, diameter, height, max_volume,
                 size_x=0.0, size_y=0.0, size_z=0.0,
                 barcode=None, category="container", model=None, **kwargs):
        super().__init__(
            name=name,
            size_x=diameter,    # PLR 用 diameter 作为 size_x/size_y
            size_y=diameter,
            size_z=height,      # PLR 用 height 作为 size_z
            max_volume=max_volume,
            category=category,
            model=model,
            bottom_type="flat",
            cross_section_type="circle"
        )
 ```
 注意 `size_x = size_y = diameter`，`size_z = height`。
 ### ItemizedCarrier 核心方法
 | 方法 | 说明 |
 |------|------|
 | `__getitem__(identifier)` | 通过索引或 Excel 标识（如 `"A01"`）访问槽位 |
 | `__setitem__(identifier, resource)` | 向槽位放入资源 |
 | `get_child_identifier(child)` | 获取子资源的标识符 |
 | `capacity` | 总槽位数 |
 | `sites` | 所有槽位字典 |
 ---
 ## 2. 序列化与反序列化
 ### PLR ↔ UniLab 转换
 | 函数 | 位置 | 方向 |
 |------|------|------|
 | `ResourceTreeSet.from_plr_resources(resources)` | `resource_tracker.py` | PLR → UniLab |
 | `ResourceTreeSet.to_plr_resources()` | `resource_tracker.py` | UniLab → PLR |
 ### `from_plr_resources` 流程
 ```
 PLR Resource
    ↓ build_uuid_mapping (递归生成 UUID)
    ↓ resource.serialize() → dict
    ↓ resource.serialize_all_state() → states
    ↓ resource_plr_inner (递归构建 ResourceDictInstance)
 ResourceTreeSet
 ```
 关键：每个 PLR 资源通过 `unilabos_uuid` 属性携带 UUID，`unilabos_extra` 携带扩展数据（如 `class` 名）。
 ### `to_plr_resources` 流程
 ```
 ResourceTreeSet
    ↓ collect_node_data (收集 UUID、状态、扩展数据)
    ↓ node_to_plr_dict (转为 PLR 字典格式)
    ↓ find_subclass(type_name, PLRResource) (查找 PLR 子类)
    ↓ sub_cls.deserialize(plr_dict) (反序列化)
    ↓ loop_set_uuid, loop_set_extra (递归设置 UUID 和扩展)
 PLR Resource
 ```
 ### Bottle 序列化
 ```python
 class Bottle(Well):
    def serialize(self) -> dict:
        data = super().serialize()
        return {**data, "diameter": self.diameter, "height": self.height}
    @classmethod
    def deserialize(cls, data: dict, allow_marshal=False):
        barcode_data = data.pop("barcode", None)
        instance = super().deserialize(data, allow_marshal=allow_marshal)
        if barcode_data and isinstance(barcode_data, str):
            instance.barcode = barcode_data
        return instance
 ```
 ---
 ## 3. Bioyond 物料同步
 ### 双向转换函数
 | 函数 | 位置 | 方向 |
 |------|------|------|
 | `resource_bioyond_to_plr(materials, type_mapping, deck)` | `graphio.py` | Bioyond → PLR |
 | `resource_plr_to_bioyond(resources, type_mapping, warehouse_mapping)` | `graphio.py` | PLR → Bioyond |
 ### `resource_bioyond_to_plr` 流程
 ```
 Bioyond 物料列表
    ↓ reverse_type_mapping: {typeName → (model, UUID)}
    ↓ 对每个物料:
       typeName → 查映射 → model (如 "BIOYOND_PolymerStation_Reactor")
       initialize_resource({"name": unique_name, "class": model})
    ↓ 设置 unilabos_extra (material_bioyond_id, material_bioyond_name 等)
    ↓ 处理 detail (子物料/坐标)
    ↓ 按 locationName 放入 deck.warehouses 对应槽位
 PLR 资源列表
 ```
 ### `resource_plr_to_bioyond` 流程
 ```
 PLR 资源列表
    ↓ 遍历每个资源:
       载架(capacity > 1): 生成 details 子物料 + 坐标
       单瓶: 直接映射
    ↓ type_mapping 查找 typeId
    ↓ warehouse_mapping 查找位置 UUID
    ↓ 组装 Bioyond 格式 (name, typeName, typeId, quantity, Parameters, locations)
 Bioyond 物料列表
 ```
 ### BioyondResourceSynchronizer
 工作站通过 `ResourceSynchronizer` 自动同步物料：
 ```python
 class BioyondResourceSynchronizer(ResourceSynchronizer):
    def sync_from_external(self) -> bool:
        all_data = []
        all_data.extend(api_client.stock_material('{"typeMode": 0}'))  # 耗材
        all_data.extend(api_client.stock_material('{"typeMode": 1}'))  # 样品
        all_data.extend(api_client.stock_material('{"typeMode": 2}'))  # 试剂
        unilab_resources = resource_bioyond_to_plr(
            all_data,
            type_mapping=self.workstation.bioyond_config["material_type_mappings"],
            deck=self.workstation.deck
        )
        # 更新 deck 上的资源
 ```
 ---
 ## 4. 非瓶类资源
 ### ElectrodeSheet（极片）
 路径：`unilabos/resources/battery/electrode_sheet.py`
 ```python
 class ElectrodeSheet(ResourcePLR):
    """片状材料（极片、隔膜、弹片、垫片等）"""
    _unilabos_state = {
        "diameter": 0.0,
        "thickness": 0.0,
        "mass": 0.0,
        "material_type": "",
        "color": "",
        "info": "",
    }
 ```
 工厂函数：`PositiveCan`, `PositiveElectrode`, `NegativeCan`, `NegativeElectrode`, `SpringWasher`, `FlatWasher`, `AluminumFoil`
 ### Battery（电池）
 ```python
 class Battery(Container):
    """组装好的电池"""
    _unilabos_state = {
        "color": "",
        "electrolyte_name": "",
        "open_circuit_voltage": 0.0,
    }
 ```
 ### Magazine / MagazineHolder（子弹夹）
 ```python
 class Magazine(ResourceStack):
    """子弹夹洞位，可堆叠 ElectrodeSheet"""
    # direction, max_sheets
 class MagazineHolder(ItemizedResource):
    """多洞位子弹夹"""
    # hole_diameter, hole_depth, max_sheets_per_hole
 ```
 工厂函数 `magazine_factory()` 用 `create_homogeneous_resources` 生成洞位，可选预填 `ElectrodeSheet` 或 `Battery`。
 ---
 ## 5. 仓库工厂模式参考
 ### 实际 warehouse 工厂函数示例
 ```python
 # 行优先 4x4 仓库
 def bioyond_warehouse_1x4x4(name: str) -> WareHouse:
    return warehouse_factory(
        name=name,
        num_items_x=4, num_items_y=4, num_items_z=1,
        dx=10.0, dy=10.0, dz=10.0,
        item_dx=147.0, item_dy=106.0, item_dz=130.0,
        layout="row-major",  # A01,A02,A03,A04, B01,...
    )
 # 右侧 4x4 仓库（列名偏移）
 def bioyond_warehouse_1x4x4_right(name: str) -> WareHouse:
    return warehouse_factory(
        name=name,
        num_items_x=4, num_items_y=4, num_items_z=1,
        dx=10.0, dy=10.0, dz=10.0,
        item_dx=147.0, item_dy=106.0, item_dz=130.0,
        col_offset=4,      # A05,A06,A07,A08
        layout="row-major",
    )
 # 竖向仓库（站内试剂存放）
 def bioyond_warehouse_reagent_storage(name: str) -> WareHouse:
    return warehouse_factory(
        name=name,
        num_items_x=1, num_items_y=2, num_items_z=1,
        dx=10.0, dy=10.0, dz=10.0,
        item_dx=147.0, item_dy=106.0, item_dz=130.0,
        layout="vertical-col-major",
    )
 # 行偏移（F 行开始）
 def bioyond_warehouse_5x3x1(name: str, row_offset: int = 0) -> WareHouse:
    return warehouse_factory(
        name=name,
        num_items_x=3, num_items_y=5, num_items_z=1,
        dx=10.0, dy=10.0, dz=10.0,
        item_dx=159.0, item_dy=183.0, item_dz=130.0,
        row_offset=row_offset,  # 0→A行起，5→F行起
        layout="row-major",
    )
 ```
 ### layout 类型说明
 | layout | 命名顺序 | 适用场景 |
 |--------|---------|---------|
 | `col-major` (默认) | A01,B01,C01,D01, A02,B02,... | 列优先，标准堆栈 |
 | `row-major` | A01,A02,A03,A04, B01,B02,... | 行优先，Bioyond 前端展示 |
 | `vertical-col-major` | 竖向排列，标签从底部开始 | 竖向仓库（试剂存放、测密度） |
 ---
 ## 6. 关键路径
 | 内容 | 路径 |
 |------|------|
 | Bottle/Carrier 基类 | `unilabos/resources/itemized_carrier.py` |
 | WareHouse 类 + 工厂 | `unilabos/resources/warehouse.py` |
 | ResourceTreeSet 转换 | `unilabos/resources/resource_tracker.py` |
 | Bioyond 物料转换 | `unilabos/resources/graphio.py` |
 | Bioyond 仓库定义 | `unilabos/resources/bioyond/warehouses.py` |
 | 电池资源 | `unilabos/resources/battery/` |
 | PLR 注册 | `unilabos/resources/plr_additional_res_reg.py` |
--- a/.cursor/skills/add-workstation/SKILL.md
+++ b/.cursor/skills/add-workstation/SKILL.md
@@ -1,500 +0,0 @@
 ---
 name: add-workstation
 description: Guide for adding new workstations to Uni-Lab-OS (接入新工作站). Walks through workstation type selection, sub-device composition, external system integration, driver creation, registry YAML, deck setup, and graph file configuration. Use when the user wants to add/integrate a new workstation, create a workstation driver, configure a station with sub-devices, set up deck and materials, or mentions 工作站/工站/station/workstation.
 ---
 # Uni-Lab-OS 工作站接入指南
 工作站（workstation）是组合多个子设备的大型设备，拥有独立的物料管理系统（PLR Deck）和工作流引擎。本指南覆盖从需求分析到验证的全流程。
 > **前置知识**：工作站接入基于 `docs/ai_guides/add_device.md` 的通用设备接入框架，但有显著差异。阅读本指南前无需先读通用指南。
 ## 第一步：确定工作站类型
 向用户确认以下信息：
 **Q1: 工作站的业务场景？**
 | 类型 | 基类 | 适用场景 | 示例 |
 |------|------|----------|------|
 | **Protocol 工作站** | `ProtocolNode` | 标准化学操作协议（过滤、转移、加热等） | FilterProtocolStation |
 | **外部系统工作站** | `WorkstationBase` | 与外部 LIMS/MES 系统对接，有专属 API | BioyondStation |
 | **硬件控制工作站** | `WorkstationBase` | 直接控制 PLC/硬件，无外部系统 | CoinCellAssembly |
 **Q2: 工作站英文名称？**（如 `my_reaction_station`）
 **Q3: 与外部系统的交互方式？**
 | 方式 | 适用场景 | 需要的配置 |
 |------|----------|-----------|
 | 无外部系统 | Protocol 工作站、纯硬件控制 | 无 |
 | HTTP API | LIMS/MES 系统（如 Bioyond） | `api_host`, `api_key` |
 | Modbus TCP | PLC 控制 | `address`, `port` |
 | OPC UA | 工业设备 | `url` |
 **Q4: 子设备组成？**
 - 列出所有子设备（如反应器、泵、阀、传感器等）
 - 哪些是已有设备类型？哪些需要新增？
 - 子设备之间的硬件代理关系（如泵通过串口设备通信）
 **Q5: 物料管理需求？**
 - 是否需要 Deck（物料面板）？
 - 物料类型（plate、tip_rack、bottle 等）
 - 是否需要与外部物料系统同步？
 ---
 ## 第二步：理解工作站架构
 工作站与普通设备的核心差异：
 | 维度 | 普通设备 | 工作站 |
 |------|---------|--------|
 | 基类 | 无（纯 Python 类） | `WorkstationBase` 或 `ProtocolNode` |
 | ROS 节点 | `BaseROS2DeviceNode` | `ROS2WorkstationNode` |
 | 状态管理 | `self.data` 字典 | 通常不用 `self.data`，用 `@property` 直接访问 |
 | 子设备 | 无 | `children` 列表，通过 `self._children` 访问 |
 | 物料 | 无 | `self.deck`（PLR Deck） |
 | 图文件角色 | `parent: null` 或 `parent: "<station>"` | `parent: null`，含 `children` 和 `deck` |
 ### 继承体系
 `WorkstationBase` (ABC) → `ProtocolNode` (通用协议) / `BioyondWorkstation` (→ ReactionStation, DispensingStation) / `CoinCellAssemblyWorkstation` (硬件控制)
 ### ROS 层
 `ROS2WorkstationNode` 额外负责：初始化 children 子设备节点、为子设备创建 ActionClient、配置硬件代理、为 protocol_type 创建协议 ActionServer。
 ---
 ## 第三步：创建驱动文件
 文件路径：`unilabos/devices/workstation/<station_name>/<station_name>.py`
 ### 模板 A：基于外部系统的工作站
 适用于与 LIMS/MES 等外部系统对接的场景。
 ```python
 import logging
 from typing import Dict, Any, Optional, List
 from pylabrobot.resources import Deck
 from unilabos.devices.workstation.workstation_base import WorkstationBase
 try:
    from unilabos.ros.nodes.presets.workstation import ROS2WorkstationNode
 except ImportError:
    ROS2WorkstationNode = None
 class MyWorkstation(WorkstationBase):
    """工作站描述"""
    _ros_node: "ROS2WorkstationNode"
    def __init__(
        self,
        config: dict = None,
        deck: Optional[Deck] = None,
        protocol_type: list = None,
        **kwargs,
    ):
        super().__init__(deck=deck, **kwargs)
        self.config = config or {}
        self.logger = logging.getLogger(f"MyWorkstation")
        # 外部系统连接配置
        self.api_host = self.config.get("api_host", "")
        self.api_key = self.config.get("api_key", "")
        # 工作站业务状态（不同于 self.data 模式）
        self._status = "Idle"
    def post_init(self, ros_node: "ROS2WorkstationNode") -> None:
        super().post_init(ros_node)
        # 在这里启动后台服务、连接监控等
    # ============ 子设备访问 ============
    def _get_child_device(self, device_id: str):
        """通过 ID 获取子设备节点"""
        return self._children.get(device_id)
    # ============ 动作方法 ============
    async def scheduler_start(self, **kwargs) -> Dict[str, Any]:
        """启动调度器"""
        return {"success": True}
    async def create_order(self, json_str: str, **kwargs) -> Dict[str, Any]:
        """创建工单"""
        return {"success": True}
    # ============ 属性 ============
    @property
    def workflow_sequence(self) -> str:
        return "[]"
    @property
    def material_info(self) -> str:
        return "{}"
 ```
 ### 模板 B：基于硬件控制的工作站
 适用于直接与 PLC/硬件通信的场景。
 ```python
 import logging
 from typing import Dict, Any, Optional
 from pylabrobot.resources import Deck
 from unilabos.devices.workstation.workstation_base import WorkstationBase
 try:
    from unilabos.ros.nodes.presets.workstation import ROS2WorkstationNode
 except ImportError:
    ROS2WorkstationNode = None
 class MyHardwareWorkstation(WorkstationBase):
    """硬件控制工作站"""
    _ros_node: "ROS2WorkstationNode"
    def __init__(
        self,
        config: dict = None,
        deck: Optional[Deck] = None,
        address: str = "192.168.1.100",
        port: str = "502",
        debug_mode: bool = False,
        *args,
        **kwargs,
    ):
        super().__init__(deck=deck, *args, **kwargs)
        self.config = config or {}
        self.address = address
        self.port = int(port)
        self.debug_mode = debug_mode
        self.logger = logging.getLogger("MyHardwareWorkstation")
        # 初始化通信客户端
        if not debug_mode:
            from unilabos.device_comms.modbus_plc.client import ModbusTcpClient
            self.client = ModbusTcpClient(host=self.address, port=self.port)
        else:
            self.client = None
    def post_init(self, ros_node: "ROS2WorkstationNode") -> None:
        super().post_init(ros_node)
    # ============ 硬件读写 ============
    def _read_register(self, name: str):
        """读取 Modbus 寄存器"""
        if self.debug_mode:
            return 0
        # 实际读取逻辑
        pass
    # ============ 动作方法 ============
    async def start_process(self, **kwargs) -> Dict[str, Any]:
        """启动加工流程"""
        return {"success": True}
    async def stop_process(self, **kwargs) -> Dict[str, Any]:
        """停止加工流程"""
        return {"success": True}
    # ============ 属性（从硬件实时读取）============
    @property
    def sys_status(self) -> str:
        return str(self._read_register("SYS_STATUS"))
 ```
 ### 模板 C：Protocol 工作站
 适用于标准化学操作协议的场景，直接使用 `ProtocolNode`。
 ```python
 from typing import List, Optional
 from pylabrobot.resources import Resource as PLRResource
 from unilabos.devices.workstation.workstation_base import ProtocolNode
 class MyProtocolStation(ProtocolNode):
    """Protocol 工作站 — 使用标准化学操作协议"""
    def __init__(
        self,
        protocol_type: List[str],
        deck: Optional[PLRResource] = None,
        *args,
        **kwargs,
    ):
        super().__init__(protocol_type=protocol_type, deck=deck, *args, **kwargs)
 ```
 > Protocol 工作站通常不需要自定义驱动类，直接使用 `ProtocolNode` 并在注册表和图文件中配置 `protocol_type` 即可。
 ---
 ## 第四步：创建子设备驱动（如需要）
 工作站的子设备本身是独立设备。按 `docs/ai_guides/add_device.md` 的标准流程创建。
 子设备的关键约束：
 - 在图文件中 `parent` 指向工作站 ID
 - 图文件中在工作站的 `children` 数组里列出
 - 如需硬件代理，在子设备的 `config.hardware_interface.name` 指向通信设备 ID
 ---
 ## 第五步：创建注册表 YAML
 路径：`unilabos/registry/devices/<station_name>.yaml`
 ### 最小配置
 ```yaml
 my_workstation:
  category:
    - workstation
  class:
    module: unilabos.devices.workstation.my_station.my_station:MyWorkstation
    type: python
 ```
 启动时 `--complete_registry` 自动补全 `status_types` 和 `action_value_mappings`。
 ### 完整配置参考
 ```yaml
 my_workstation:
  description: "我的工作站"
  version: "1.0.0"
  category:
    - workstation
    - my_category
  class:
    module: unilabos.devices.workstation.my_station.my_station:MyWorkstation
    type: python
    status_types:
      workflow_sequence: String
      material_info: String
    action_value_mappings:
      scheduler_start:
        type: UniLabJsonCommandAsync
        goal: {}
        result:
          success: success
      create_order:
        type: UniLabJsonCommandAsync
        goal:
          json_str: json_str
        result:
          success: success
  init_param_schema:
    config:
      type: object
    deck:
      type: object
    protocol_type:
      type: array
 ```
 ### 子设备注册表
 子设备有独立的注册表文件，需要在 `category` 中包含工作站标识：
 ```yaml
 my_reactor:
  category:
    - reactor
    - my_workstation
  class:
    module: unilabos.devices.workstation.my_station.my_reactor:MyReactor
    type: python
 ```
 ---
 ## 第六步：配置 Deck 资源（如需要）
 如果工作站有物料管理需求，需要定义 Deck 类。
 ### 使用已有 Deck 类
 查看 `unilabos/resources/` 目录下是否有适用的 Deck 类。
 ### 创建自定义 Deck
 在 `unilabos/resources/<category>/decks.py` 中定义：
 ```python
 from pylabrobot.resources import Deck
 from pylabrobot.resources.coordinate import Coordinate
 def MyStation_Deck(name: str = "MyStation_Deck") -> Deck:
    deck = Deck(name=name, size_x=2700.0, size_y=1080.0, size_z=1500.0)
    # 在 deck 上定义子资源位置（carrier、plate 等）
    return deck
 ```
 在 `unilabos/resources/<category>/` 下注册或通过注册表引用。
 ---
 ## 第七步：配置图文件
 图文件路径：`unilabos/test/experiments/<station_name>.json`
 ### 完整结构
 ```json
 {
    "nodes": [
        {
            "id": "my_station",
            "name": "my_station",
            "children": ["my_deck", "sub_device_1", "sub_device_2"],
            "parent": null,
            "type": "device",
            "class": "my_workstation",
            "position": {"x": 0, "y": 0, "z": 0},
            "config": {
                "api_host": "http://192.168.1.100:8080",
                "api_key": "YOUR_KEY"
            },
            "deck": {
                "data": {
                    "_resource_child_name": "my_deck",
                    "_resource_type": "unilabos.resources.my_module.decks:MyStation_Deck"
                }
            },
            "size_x": 2700.0,
            "size_y": 1080.0,
            "size_z": 1500.0,
            "protocol_type": [],
            "data": {}
        },
        {
            "id": "my_deck",
            "name": "my_deck",
            "children": [],
            "parent": "my_station",
            "type": "deck",
            "class": "MyStation_Deck",
            "position": {"x": 0, "y": 0, "z": 0},
            "config": {
                "type": "MyStation_Deck",
                "setup": true,
                "rotation": {"x": 0, "y": 0, "z": 0, "type": "Rotation"}
            },
            "data": {}
        },
        {
            "id": "sub_device_1",
            "name": "sub_device_1",
            "children": [],
            "parent": "my_station",
            "type": "device",
            "class": "sub_device_registry_name",
            "position": {"x": 100, "y": 0, "z": 0},
            "config": {},
            "data": {}
        }
    ]
 }
 ```
 ### 图文件规则
 | 字段 | 说明 |
 |------|------|
 | `id` | 节点唯一标识，与 `children` 数组中的引用一致 |
 | `children` | 包含 deck ID 和所有子设备 ID |
 | `parent` | 工作站节点为 `null`；子设备/deck 指向工作站 ID |
 | `type` | 工作站和子设备为 `"device"`；deck 为 `"deck"` |
 | `class` | 对应注册表中的设备名 |
 | `deck.data._resource_child_name` | 必须与 deck 节点的 `id` 一致 |
 | `deck.data._resource_type` | Deck 工厂函数的完整 Python 路径 |
 | `protocol_type` | Protocol 工作站填入协议名列表；否则为 `[]` |
 | `config` | 传入驱动 `__init__` 的 `config` 参数 |
 ---
 ## 第八步：验证
 ```bash
 # 1. 模块可导入
 python -c "from unilabos.devices.workstation.<name>.<name> import <ClassName>"
 # 2. 注册表补全
 unilab -g <graph>.json --complete_registry
 # 3. 启动测试
 unilab -g <graph>.json
 ```
 ---
 ## 高级模式
 实现外部系统对接型工作站时，详见 [reference.md](reference.md)：RPC 客户端、HTTP 回调服务、连接监控、Config 结构模式（material_type_mappings / warehouse_mapping / workflow_mappings）、ResourceSynchronizer、update_resource、工作流序列、站间物料转移、post_init 完整模式。
 ---
 ## 关键规则
 1. **`__init__` 必须接受 `deck` 和 `**kwargs`** — `WorkstationBase.__init__` 需要 `deck` 参数
 2. **通过 `self._children` 访问子设备** — 不要自行维护子设备引用
 3. **`post_init` 中启动后台服务** — 不要在 `__init__` 中启动网络连接
 4. **异步方法使用 `await self._ros_node.sleep()`** — 禁止 `time.sleep()` 和 `asyncio.sleep()`
 5. **子设备在图文件中声明** — 不在驱动代码中创建子设备实例
 6. **`deck` 配置中的 `_resource_child_name` 必须与 deck 节点 ID 一致**
 7. **Protocol 工作站优先使用 `ProtocolNode`** — 不需要自定义类
 ---
 ## 工作流清单
 ```
 工作站接入进度：
 - [ ] 1. 确定工作站类型（Protocol / 外部系统 / 硬件控制）
 - [ ] 2. 确认子设备组成和物料需求
 - [ ] 3. 创建工作站驱动 unilabos/devices/workstation/<name>/<name>.py
 - [ ] 4. 创建子设备驱动（如需要，按 add_device.md 流程）
 - [ ] 5. 创建注册表 unilabos/registry/devices/<name>.yaml
 - [ ] 6. 创建/选择 Deck 资源类（如需要）
 - [ ] 7. 配置图文件 unilabos/test/experiments/<name>.json
 - [ ] 8. 验证：可导入 + 注册表补全 + 启动测试
 ```
 ---
 ## 现有工作站参考
 | 工作站 | 注册表名 | 驱动类 | 类型 |
 |--------|----------|--------|------|
 | Protocol 通用 | `workstation` | `ProtocolNode` | Protocol |
 | Bioyond 反应站 | `reaction_station.bioyond` | `BioyondReactionStation` | 外部系统 |
 | Bioyond 配液站 | `bioyond_dispensing_station` | `BioyondDispensingStation` | 外部系统 |
 | 纽扣电池组装 | `coincellassemblyworkstation_device` | `CoinCellAssemblyWorkstation` | 硬件控制 |
 ### 参考文件路径
 - 基类: `unilabos/devices/workstation/workstation_base.py`
 - Bioyond 基类: `unilabos/devices/workstation/bioyond_studio/station.py`
 - 反应站: `unilabos/devices/workstation/bioyond_studio/reaction_station/reaction_station.py`
 - 配液站: `unilabos/devices/workstation/bioyond_studio/dispensing_station/dispensing_station.py`
 - 纽扣电池: `unilabos/devices/workstation/coin_cell_assembly/coin_cell_assembly.py`
 - ROS 节点: `unilabos/ros/nodes/presets/workstation.py`
 - 图文件: `unilabos/test/experiments/reaction_station_bioyond.json`, `dispensing_station_bioyond.json`
--- a/.cursor/skills/add-workstation/reference.md
+++ b/.cursor/skills/add-workstation/reference.md
@@ -1,371 +0,0 @@
 # 工作站高级模式参考
 本文件是 SKILL.md 的补充，包含外部系统集成、物料同步、配置结构等高级模式。
 Agent 在需要实现这些功能时按需阅读。
 ---
 ## 1. 外部系统集成模式
 ### 1.1 RPC 客户端
 与外部 LIMS/MES 系统通信的标准模式。继承 `BaseRequest`，所有接口统一用 POST。
 ```python
 from unilabos.device_comms.rpc import BaseRequest
 class MySystemRPC(BaseRequest):
    """外部系统 RPC 客户端"""
    def __init__(self, host: str, api_key: str):
        super().__init__(host)
        self.api_key = api_key
    def _request(self, endpoint: str, data: dict = None) -> dict:
        return self.post(
            url=f"{self.host}/api/{endpoint}",
            params={
                "apiKey": self.api_key,
                "requestTime": self.get_current_time_iso8601(),
                "data": data or {},
            },
        )
    def query_status(self) -> dict:
        return self._request("status/query")
    def create_order(self, order_data: dict) -> dict:
        return self._request("order/create", order_data)
 ```
 参考：`unilabos/devices/workstation/bioyond_studio/bioyond_rpc.py`（`BioyondV1RPC`）
 ### 1.2 HTTP 回调服务
 接收外部系统报送的标准模式。使用 `WorkstationHTTPService`，在 `post_init` 中启动。
 ```python
 from unilabos.devices.workstation.workstation_http_service import WorkstationHTTPService
 class MyWorkstation(WorkstationBase):
    def __init__(self, config=None, deck=None, **kwargs):
        super().__init__(deck=deck, **kwargs)
        self.config = config or {}
        http_cfg = self.config.get("http_service_config", {})
        self._http_service_config = {
            "host": http_cfg.get("http_service_host", "127.0.0.1"),
            "port": http_cfg.get("http_service_port", 8080),
        }
        self.http_service = None
    def post_init(self, ros_node):
        super().post_init(ros_node)
        self.http_service = WorkstationHTTPService(
            workstation_instance=self,
            host=self._http_service_config["host"],
            port=self._http_service_config["port"],
        )
        self.http_service.start()
 ```
 **HTTP 服务路由**（固定端点，由 `WorkstationHTTPHandler` 自动分发）：
 | 端点 | 调用的工作站方法 |
 |------|-----------------|
 | `/report/step_finish` | `process_step_finish_report(report_request)` |
 | `/report/sample_finish` | `process_sample_finish_report(report_request)` |
 | `/report/order_finish` | `process_order_finish_report(report_request, used_materials)` |
 | `/report/material_change` | `process_material_change_report(report_data)` |
 | `/report/error_handling` | `handle_external_error(error_data)` |
 实现对应方法即可接收回调：
 ```python
 def process_step_finish_report(self, report_request) -> Dict[str, Any]:
    """处理步骤完成报告"""
    step_name = report_request.data.get("stepName")
    return {"success": True, "message": f"步骤 {step_name} 已处理"}
 def process_order_finish_report(self, report_request, used_materials) -> Dict[str, Any]:
    """处理订单完成报告"""
    order_code = report_request.data.get("orderCode")
    return {"success": True}
 ```
 参考：`unilabos/devices/workstation/workstation_http_service.py`
 ### 1.3 连接监控
 独立线程周期性检测外部系统连接状态，状态变化时发布 ROS 事件。
 ```python
 class ConnectionMonitor:
    def __init__(self, workstation, check_interval=30):
        self.workstation = workstation
        self.check_interval = check_interval
        self._running = False
        self._thread = None
    def start(self):
        self._running = True
        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
        self._thread.start()
    def _monitor_loop(self):
        while self._running:
            try:
                # 调用外部系统接口检测连接
                self.workstation.hardware_interface.ping()
                status = "online"
            except Exception:
                status = "offline"
            time.sleep(self.check_interval)
 ```
 参考：`unilabos/devices/workstation/bioyond_studio/station.py`（`ConnectionMonitor`）
 ---
 ## 2. Config 结构模式
 工作站的 `config` 在图文件中定义，传入 `__init__`。以下是常见字段模式：
 ### 2.1 外部系统连接
 ```json
 {
    "api_host": "http://192.168.1.100:8080",
    "api_key": "YOUR_API_KEY"
 }
 ```
 ### 2.2 HTTP 回调服务
 ```json
 {
    "http_service_config": {
        "http_service_host": "127.0.0.1",
        "http_service_port": 8080
    }
 }
 ```
 ### 2.3 物料类型映射
 将 PLR 资源类名映射到外部系统的物料类型（名称 + UUID）。用于双向物料转换。
 ```json
 {
    "material_type_mappings": {
        "PLR_ResourceClassName": ["外部系统显示名", "external-type-uuid"],
        "BIOYOND_PolymerStation_Reactor": ["反应器", "3a14233b-902d-0d7b-..."]
    }
 }
 ```
 ### 2.4 仓库映射
 将仓库名映射到外部系统的仓库 UUID 和库位 UUID。用于入库/出库操作。
 ```json
 {
    "warehouse_mapping": {
        "仓库名": {
            "uuid": "warehouse-uuid",
            "site_uuids": {
                "A01": "site-uuid-A01",
                "A02": "site-uuid-A02"
            }
        }
    }
 }
 ```
 ### 2.5 工作流映射
 将内部工作流名映射到外部系统的工作流 ID。
 ```json
 {
    "workflow_mappings": {
        "internal_workflow_name": "external-workflow-uuid"
    }
 }
 ```
 ### 2.6 物料默认参数
 ```json
 {
    "material_default_parameters": {
        "NMP": {
            "unit": "毫升",
            "density": "1.03",
            "densityUnit": "g/mL",
            "description": "N-甲基吡咯烷酮"
        }
    }
 }
 ```
 ---
 ## 3. 资源同步机制
 ### 3.1 ResourceSynchronizer
 抽象基类，用于与外部物料系统双向同步。定义在 `workstation_base.py`。
 ```python
 from unilabos.devices.workstation.workstation_base import ResourceSynchronizer
 class MyResourceSynchronizer(ResourceSynchronizer):
    def __init__(self, workstation, api_client):
        super().__init__(workstation)
        self.api_client = api_client
    def sync_from_external(self) -> bool:
        """从外部系统拉取物料到 deck"""
        external_materials = self.api_client.list_materials()
        for material in external_materials:
            plr_resource = self._convert_to_plr(material)
            self.workstation.deck.assign_child_resource(plr_resource, coordinate)
        return True
    def sync_to_external(self, plr_resource) -> bool:
        """将 deck 中的物料变更推送到外部系统"""
        external_data = self._convert_from_plr(plr_resource)
        self.api_client.update_material(external_data)
        return True
    def handle_external_change(self, change_info) -> bool:
        """处理外部系统推送的物料变更"""
        return True
 ```
 ### 3.2 update_resource — 上传资源树到云端
 将 PLR Deck 序列化后通过 ROS 服务上传。典型使用场景：
 ```python
 # 在 post_init 中上传初始 deck
 from unilabos.ros.nodes.base_device_node import ROS2DeviceNode
 ROS2DeviceNode.run_async_func(
    self._ros_node.update_resource, True,
    **{"resources": [self.deck]}
 )
 # 在动作方法中更新特定资源
 ROS2DeviceNode.run_async_func(
    self._ros_node.update_resource, True,
    **{"resources": [updated_plate]}
 )
 ```
 ---
 ## 4. 工作流序列管理
 工作站通过 `workflow_sequence` 属性管理任务队列（JSON 字符串形式）。
 ```python
 class MyWorkstation(WorkstationBase):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._workflow_sequence = []
    @property
    def workflow_sequence(self) -> str:
        """返回 JSON 字符串，ROS 自动发布"""
        import json
        return json.dumps(self._workflow_sequence)
    async def append_to_workflow_sequence(self, workflow_name: str) -> Dict[str, Any]:
        """添加工作流到队列"""
        self._workflow_sequence.append({
            "name": workflow_name,
            "status": "pending",
            "created_at": time.time(),
        })
        return {"success": True}
    async def clear_workflows(self) -> Dict[str, Any]:
        """清空工作流队列"""
        self._workflow_sequence = []
        return {"success": True}
 ```
 ---
 ## 5. 站间物料转移
 工作站之间转移物料的模式。通过 ROS ActionClient 调用目标站的动作。
 ```python
 async def transfer_materials_to_another_station(
    self,
    target_device_id: str,
    transfer_groups: list,
    **kwargs,
 ) -> Dict[str, Any]:
    """将物料转移到另一个工作站"""
    target_node = self._children.get(target_device_id)
    if not target_node:
        # 通过 ROS 节点查找非子设备的目标站
        pass
    for group in transfer_groups:
        resource = self.find_resource_by_name(group["resource_name"])
        # 从本站 deck 移除
        resource.unassign()
        # 调用目标站的接收方法
        # ...
    return {"success": True, "transferred": len(transfer_groups)}
 ```
 参考：`BioyondDispensingStation.transfer_materials_to_reaction_station`
 ---
 ## 6. post_init 完整模式
 `post_init` 是工作站初始化的关键阶段，此时 ROS 节点和子设备已就绪。
 ```python
 def post_init(self, ros_node):
    super().post_init(ros_node)
    # 1. 初始化外部系统客户端（此时 config 已可用）
    self.rpc_client = MySystemRPC(
        host=self.config.get("api_host"),
        api_key=self.config.get("api_key"),
    )
    self.hardware_interface = self.rpc_client
    # 2. 启动连接监控
    self.connection_monitor = ConnectionMonitor(self)
    self.connection_monitor.start()
    # 3. 启动 HTTP 回调服务
    if hasattr(self, '_http_service_config'):
        self.http_service = WorkstationHTTPService(
            workstation_instance=self,
            host=self._http_service_config["host"],
            port=self._http_service_config["port"],
        )
        self.http_service.start()
    # 4. 上传 deck 到云端
    ROS2DeviceNode.run_async_func(
        self._ros_node.update_resource, True,
        **{"resources": [self.deck]}
    )
    # 5. 初始化资源同步器（可选）
    self.resource_synchronizer = MyResourceSynchronizer(self, self.rpc_client)
 ```
--- a/.cursor/skills/edit-experiment-graph/SKILL.md
+++ b/.cursor/skills/edit-experiment-graph/SKILL.md
@@ -1,381 +0,0 @@
 ---
 name: edit-experiment-graph
 description: Guide for creating and editing experiment graph files in Uni-Lab-OS (创建/编辑实验组态图). Covers node types, link types, parent-child relationships, deck configuration, and common graph patterns. Use when the user wants to create a graph file, edit an experiment configuration, set up device topology, or mentions 图文件/graph/组态/拓扑/实验图/experiment JSON.
 ---
 # 创建/编辑实验组态图
 实验图（Graph File）定义设备拓扑、物理连接和物料配置。系统启动时加载图文件，初始化所有设备和连接关系。
 路径：`unilabos/test/experiments/<name>.json`
 ---
 ## 第一步：确认需求
 向用户确认：
 | 信息 | 说明 |
 |------|------|
 | 场景类型 | 单设备调试 / 多设备联调 / 工作站完整图 |
 | 包含的设备 | 设备 ID、注册表 class 名、配置参数 |
 | 连接关系 | 物理连接（管道）/ 通信连接（串口）/ 无连接 |
 | 父子关系 | 是否有工作站包含子设备 |
 | 物料需求 | 是否需要 Deck、容器、试剂瓶 |
 ---
 ## 第二步：JSON 顶层结构
 ```json
 {
    "nodes": [],
    "links": []
 }
 ```
 > `links` 也可写作 `edges`，加载时两者等效。
 ---
 ## 第三步：定义 Nodes
 ### 节点字段
 | 字段 | 类型 | 必需 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | `id` | string | **是** | — | 节点唯一标识，links 和 children 中引用此值 |
 | `class` | string | **是** | — | 对应注册表名（设备/资源 YAML 的 key），容器可为 `null` |
 | `name` | string | 否 | 同 `id` | 显示名称，缺省时自动用 `id` |
 | `type` | string | 否 | `"device"` | 节点类型（见下表），缺省时自动设为 `"device"` |
 | `children` | string[] | 否 | `[]` | 子节点 ID 列表 |
 | `parent` | string\|null | 否 | `null` | 父节点 ID，顶层设备为 `null` |
 | `position` | object | 否 | `{x:0,y:0,z:0}` | 空间坐标 |
 | `config` | object | 否 | `{}` | 传给驱动 `__init__` 的参数 |
 | `data` | object | 否 | `{}` | 初始运行状态 |
 | `size_x/y/z` | float | 否 | — | 节点物理尺寸（工作站节点常用） |
 > 非标准字段（如 `api_host`）会自动移入 `config`。
 ### 节点类型
 | `type` | 用途 | `class` 要求 |
 |--------|------|-------------|
 | `device` | 设备（默认） | 注册表中的设备名 |
 | `deck` | 工作台面 | Deck 工厂函数/类名 |
 | `container` | 容器（烧瓶、反应釜） | `null` 或具体容器类名 |
 ### 设备节点模板
 ```json
 {
    "id": "my_device",
    "name": "我的设备",
    "children": [],
    "parent": null,
    "type": "device",
    "class": "registry_device_name",
    "position": {"x": 0, "y": 0, "z": 0},
    "config": {
        "port": "/dev/ttyUSB0",
        "baudrate": 115200
    },
    "data": {
        "status": "Idle"
    }
 }
 ```
 ### 容器节点模板
 容器用于协议系统中表示试剂瓶、反应釜等，`class` 通常为 `null`：
 ```json
 {
    "id": "flask_DMF",
    "name": "DMF试剂瓶",
    "children": [],
    "parent": "my_station",
    "type": "container",
    "class": null,
    "position": {"x": 200, "y": 500, "z": 0},
    "config": {"max_volume": 1000.0},
    "data": {
        "liquid": [{"liquid_type": "DMF", "liquid_volume": 800.0}]
    }
 }
 ```
 ### Deck 节点模板
 ```json
 {
    "id": "my_deck",
    "name": "my_deck",
    "children": [],
    "parent": "my_station",
    "type": "deck",
    "class": "MyStation_Deck",
    "position": {"x": 0, "y": 0, "z": 0},
    "config": {
        "type": "MyStation_Deck",
        "setup": true,
        "rotation": {"x": 0, "y": 0, "z": 0, "type": "Rotation"}
    },
    "data": {}
 }
 ```
 ---
 ## 第四步：定义 Links
 ### Link 字段
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `source` | string | 源节点 ID |
 | `target` | string | 目标节点 ID |
 | `type` | string | `"physical"` / `"fluid"` / `"communication"` |
 | `port` | object | 端口映射 `{source_id: "port_name", target_id: "port_name"}` |
 ### 物理/流体连接
 设备间的管道连接，协议系统用此查找路径：
 ```json
 {
    "source": "multiway_valve_1",
    "target": "flask_DMF",
    "type": "fluid",
    "port": {
        "multiway_valve_1": "2",
        "flask_DMF": "outlet"
    }
 }
 ```
 ### 通信连接
 设备间的串口/IO 通信代理，加载时自动将端口信息写入目标设备 config：
 ```json
 {
    "source": "pump_1",
    "target": "serial_device",
    "type": "communication",
    "port": {
        "pump_1": "port",
        "serial_device": "port"
    }
 }
 ```
 ---
 ## 第五步：父子关系与工作站配置
 ### 工作站 + 子设备
 工作站节点的 `children` 列出所有子节点 ID，子节点的 `parent` 指向工作站：
 ```json
 {
    "id": "my_station",
    "children": ["my_deck", "pump_1", "valve_1", "reactor_1"],
    "parent": null,
    "type": "device",
    "class": "workstation",
    "config": {
        "protocol_type": ["PumpTransferProtocol", "CleanProtocol"]
    }
 }
 ```
 ### 工作站 + Deck 引用
 工作站节点中通过 `deck` 字段引用 Deck：
 ```json
 {
    "id": "my_station",
    "children": ["my_deck", "sub_device_1"],
    "deck": {
        "data": {
            "_resource_child_name": "my_deck",
            "_resource_type": "unilabos.resources.my_module.decks:MyDeck"
        }
    }
 }
 ```
 **关键约束：**
 - `_resource_child_name` 必须与 Deck 节点的 `id` 一致
 - `_resource_type` 为 Deck 类/工厂函数的完整 Python 路径
 ---
 ## 常见图模式
 ### 模式 A：单设备调试
 最简形式，一个设备节点，无连接：
 ```json
 {
    "nodes": [
        {
            "id": "my_device",
            "name": "my_device",
            "children": [],
            "parent": null,
            "type": "device",
            "class": "motor.zdt_x42",
            "position": {"x": 0, "y": 0, "z": 0},
            "config": {"port": "/dev/ttyUSB0", "baudrate": 115200},
            "data": {"status": "idle"}
        }
    ],
    "links": []
 }
 ```
 ### 模式 B：Protocol 工作站（泵+阀+容器）
 工作站配合泵、阀、容器和物理连接，用于协议编译：
 ```json
 {
    "nodes": [
        {
            "id": "station", "name": "协议工作站",
            "class": "workstation", "type": "device", "parent": null,
            "children": ["pump", "valve", "flask_solvent", "reactor", "waste"],
            "config": {"protocol_type": ["PumpTransferProtocol"]}
        },
        {"id": "pump", "name": "转移泵", "class": "virtual_transfer_pump",
         "type": "device", "parent": "station",
         "config": {"port": "VIRTUAL", "max_volume": 25.0},
         "data": {"status": "Idle", "position": 0.0, "valve_position": "0"}},
        {"id": "valve", "name": "多通阀", "class": "virtual_multiway_valve",
         "type": "device", "parent": "station",
         "config": {"port": "VIRTUAL", "positions": 8}},
        {"id": "flask_solvent", "name": "溶剂瓶", "type": "container",
         "class": null, "parent": "station",
         "config": {"max_volume": 1000.0},
         "data": {"liquid": [{"liquid_type": "DMF", "liquid_volume": 500}]}},
        {"id": "reactor", "name": "反应器", "type": "container",
         "class": null, "parent": "station"},
        {"id": "waste", "name": "废液瓶", "type": "container",
         "class": null, "parent": "station"}
    ],
    "links": [
        {"source": "pump", "target": "valve", "type": "fluid",
         "port": {"pump": "transferpump", "valve": "transferpump"}},
        {"source": "valve", "target": "flask_solvent", "type": "fluid",
         "port": {"valve": "1", "flask_solvent": "outlet"}},
        {"source": "valve", "target": "reactor", "type": "fluid",
         "port": {"valve": "2", "reactor": "inlet"}},
        {"source": "valve", "target": "waste", "type": "fluid",
         "port": {"valve": "3", "waste": "inlet"}}
    ]
 }
 ```
 ### 模式 C：外部系统工作站 + Deck
 ```json
 {
    "nodes": [
        {
            "id": "bioyond_station", "class": "reaction_station.bioyond",
            "parent": null, "children": ["bioyond_deck"],
            "config": {
                "api_host": "http://192.168.1.100:8080",
                "api_key": "YOUR_KEY",
                "material_type_mappings": {},
                "warehouse_mapping": {}
            },
            "deck": {
                "data": {
                    "_resource_child_name": "bioyond_deck",
                    "_resource_type": "unilabos.resources.bioyond.decks:BIOYOND_PolymerReactionStation_Deck"
                }
            }
        },
        {
            "id": "bioyond_deck", "class": "BIOYOND_PolymerReactionStation_Deck",
            "parent": "bioyond_station", "type": "deck",
            "config": {"type": "BIOYOND_PolymerReactionStation_Deck", "setup": true}
        }
    ],
    "links": []
 }
 ```
 ### 模式 D：通信代理（串口设备）
 泵通过串口设备通信，使用 `communication` 类型的 link。加载时系统会自动将串口端口信息写入泵的 `config`：
 ```json
 {
    "nodes": [
        {"id": "station", "name": "工作站", "type": "device",
         "class": "workstation", "parent": null,
         "children": ["serial_1", "pump_1"]},
        {"id": "serial_1", "name": "串口", "type": "device",
         "class": "serial", "parent": "station",
         "config": {"port": "COM7", "baudrate": 9600}},
        {"id": "pump_1", "name": "注射泵", "type": "device",
         "class": "syringe_pump_with_valve.runze.SY03B-T08", "parent": "station"}
    ],
    "links": [
        {"source": "pump_1", "target": "serial_1", "type": "communication",
         "port": {"pump_1": "port", "serial_1": "port"}}
    ]
 }
 ```
 ---
 ## 验证
 ```bash
 # 启动测试
 unilab -g unilabos/test/experiments/<name>.json --complete_registry
 # 仅检查注册表
 python -m unilabos --check_mode --skip_env_check
 ```
 ---
 ## 高级模式
 处理复杂图文件时，详见 [reference.md](reference.md)：ResourceDict 完整字段 schema、Pose 标准化规则、Handle 验证机制、GraphML 格式支持、外部系统工作站完整 config 结构。
 ---
 ## 常见错误
 | 错误 | 原因 | 修复 |
 |------|------|------|
 | `class` 找不到 | 注册表中无此设备名 | 在 `unilabos/registry/devices/` 或 `resources/` 中搜索正确名称 |
 | children/parent 不一致 | 子节点 `parent` 与父节点 `children` 不匹配 | 确保双向一致 |
 | `_resource_child_name` 不匹配 | Deck 引用名与 Deck 节点 `id` 不同 | 保持一致 |
 | Link 端口错误 | `port` 中的 key 不是 source/target 的 `id` | key 必须是对应节点的 `id` |
 | 重复 UUID | 多个节点有相同 `uuid` | 删除或修改 UUID |
 ---
 ## 参考路径
 | 内容 | 路径 |
 |------|------|
 | 图文件目录 | `unilabos/test/experiments/` |
 | 协议测试站 | `unilabos/test/experiments/Protocol_Test_Station/` |
 | 图加载代码 | `unilabos/resources/graphio.py` |
 | 节点模型 | `unilabos/resources/resource_tracker.py` |
 | 设备注册表 | `unilabos/registry/devices/` |
 | 资源注册表 | `unilabos/registry/resources/` |
 | 用户文档 | `docs/user_guide/graph_files.md` |
--- a/.cursor/skills/edit-experiment-graph/reference.md
+++ b/.cursor/skills/edit-experiment-graph/reference.md
@@ -1,255 +0,0 @@
 # 实验图高级参考
 本文件是 SKILL.md 的补充，包含 ResourceDict 完整 schema、Handle 验证、GraphML 格式、Pose 标准化规则和复杂图文件结构。Agent 在需要处理这些场景时按需阅读。
 ---
 ## 1. ResourceDict 完整字段
 `unilabos/resources/resource_tracker.py` 中定义的节点数据模型：
 | 字段 | 类型 | 别名 | 说明 |
 |------|------|------|------|
 | `id` | `str` | — | 节点唯一标识 |
 | `uuid` | `str` | — | 全局唯一标识 |
 | `name` | `str` | — | 显示名称 |
 | `description` | `str` | — | 描述（默认 `""` ） |
 | `resource_schema` | `Dict[str, Any]` | `schema` | 资源 schema |
 | `model` | `Dict[str, Any]` | — | 3D 模型信息 |
 | `icon` | `str` | — | 图标（默认 `""` ） |
 | `parent_uuid` | `Optional[str]` | — | 父节点 UUID |
 | `parent` | `Optional[ResourceDict]` | — | 父节点引用（序列化时 exclude） |
 | `type` | `Union[Literal["device"], str]` | — | 节点类型 |
 | `klass` | `str` | `class` | 注册表类名 |
 | `pose` | `ResourceDictPosition` | — | 位姿信息 |
 | `config` | `Dict[str, Any]` | — | 配置参数 |
 | `data` | `Dict[str, Any]` | — | 运行时数据 |
 | `extra` | `Dict[str, Any]` | — | 扩展数据 |
 ### Pose 完整结构（ResourceDictPosition）
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `size` | `{width, height, depth}` | `{0,0,0}` | 节点尺寸 |
 | `scale` | `{x, y, z}` | `{1,1,1}` | 缩放比例 |
 | `layout` | `"2d"/"x-y"/"z-y"/"x-z"` | `"x-y"` | 布局方向 |
 | `position` | `{x, y, z}` | `{0,0,0}` | 2D 位置 |
 | `position3d` | `{x, y, z}` | `{0,0,0}` | 3D 位置 |
 | `rotation` | `{x, y, z}` | `{0,0,0}` | 旋转角度 |
 | `cross_section_type` | `"rectangle"/"circle"/"rounded_rectangle"` | `"rectangle"` | 横截面形状 |
 ---
 ## 2. Position / Pose 标准化规则
 图文件中的 `position` 有多种写法，加载时自动标准化。
 ### 输入格式兼容
 ```json
 // 格式 A: 直接 {x, y, z}（最常用）
 "position": {"x": 100, "y": 200, "z": 0}
 // 格式 B: 嵌套 position
 "position": {"position": {"x": 100, "y": 200, "z": 0}}
 // 格式 C: 使用 pose 字段
 "pose": {"position": {"x": 100, "y": 200, "z": 0}}
 // 格式 D: 顶层 x, y, z（无 position 字段）
 "x": 100, "y": 200, "z": 0
 ```
 ### 标准化流程
 1. **graphio.py `canonicalize_nodes_data`**：若 `position` 不是 dict，从节点顶层提取 `x/y/z` 填入 `pose.position`
 2. **resource_tracker.py `get_resource_instance_from_dict`**：若 `position.x` 存在（旧格式），转为 `{"position": {"x":..., "y":..., "z":...}}`
 3. `pose.size` 从 `config.size_x/size_y/size_z` 自动填充
 ---
 ## 3. Handle 验证
 启动时系统验证 link 中的 `sourceHandle` / `targetHandle` 是否在注册表的 `handles` 中定义。
 ```python
 # unilabos/app/main.py (约 449-481 行)
 source_handler_keys = [
    h["handler_key"] for h in materials[source_node.klass]["handles"]
    if h["io_type"] == "source"
 ]
 target_handler_keys = [
    h["handler_key"] for h in materials[target_node.klass]["handles"]
    if h["io_type"] == "target"
 ]
 if source_handle not in source_handler_keys:
    print_status(f"节点 {source_node.id} 的source端点 {source_handle} 不存在", "error")
    resource_edge_info.pop(...)  # 移除非法 link
 ```
 **Handle 定义在注册表 YAML 中：**
 ```yaml
 my_device:
  handles:
  - handler_key: access
    io_type: target
    data_type: fluid
    side: NORTH
    label: access
 ```
 > 大多数简单设备不定义 handles，此验证仅对有 `sourceHandle`/`targetHandle` 的 link 生效。
 ---
 ## 4. GraphML 格式支持
 除 JSON 外，系统也支持 GraphML 格式（`unilabos/resources/graphio.py::read_graphml`）。
 ### 与 JSON 的关键差异
 | 特性 | JSON | GraphML |
 |------|------|---------|
 | 父子关系 | `parent`/`children` 字段 | `::` 分隔的节点 ID（如 `station::pump_1`） |
 | 加载后 | 直接解析 | 先 `nx.read_graphml` 再转 JSON 格式 |
 | 输出 | 不生成副本 | 自动生成等价的 `.json` 文件 |
 ### GraphML 转换流程
 ```
 nx.read_graphml(file)
    ↓ 用 label 重映射节点名
    ↓ 从 "::" 推断 parent_relation
 nx.relabel_nodes + nx.node_link_data
    ↓ canonicalize_nodes_data + canonicalize_links_ports
    ↓ 写出等价 JSON 文件
 physical_setup_graph + handle_communications
 ```
 ---
 ## 5. 复杂图文件结构示例
 ### 外部系统工作站完整 config
 以 `reaction_station_bioyond.json` 为例，工作站 `config` 中的关键字段：
 ```json
 {
    "config": {
        "api_key": "DE9BDDA0",
        "api_host": "http://172.21.103.36:45388",
        "workflow_mappings": {
            "scheduler_start": {"workflow": "start", "params": {}},
            "create_order": {"workflow": "create_order", "params": {}}
        },
        "material_type_mappings": {
            "BIOYOND_PolymerStation_Reactor": ["反应器", "type-uuid-here"],
            "BIOYOND_PolymerStation_1BottleCarrier": ["试剂瓶", "type-uuid-here"]
        },
        "warehouse_mapping": {
            "堆栈1左": {
                "uuid": "warehouse-uuid-here",
                "site_uuids": {
                    "A01": "site-uuid-1",
                    "A02": "site-uuid-2"
                }
            }
        },
        "http_service_config": {
            "enabled": true,
            "host": "0.0.0.0",
            "port": 45399,
            "routes": ["/callback/workflow", "/callback/material"]
        },
        "deck": {
            "data": {
                "_resource_child_name": "Bioyond_Deck",
                "_resource_type": "unilabos.resources.bioyond.decks:BIOYOND_PolymerReactionStation_Deck"
            }
        },
        "size_x": 2700.0,
        "size_y": 1080.0,
        "size_z": 2500.0,
        "protocol_type": [],
        "data": {}
    }
 }
 ```
 ### 子设备 Reactor 节点
 ```json
 {
    "id": "reactor_1",
    "name": "reactor_1",
    "parent": "reaction_station_bioyond",
    "type": "device",
    "class": "bioyond_reactor",
    "position": {"x": 1150, "y": 300, "z": 0},
    "config": {
        "reactor_index": 0,
        "bioyond_workflow_key": "reactor_1"
    },
    "data": {}
 }
 ```
 ### Deck 节点
 ```json
 {
    "id": "Bioyond_Deck",
    "name": "Bioyond_Deck",
    "parent": "reaction_station_bioyond",
    "type": "deck",
    "class": "BIOYOND_PolymerReactionStation_Deck",
    "position": {"x": 0, "y": 0, "z": 0},
    "config": {
        "type": "BIOYOND_PolymerReactionStation_Deck",
        "setup": true,
        "rotation": {"x": 0, "y": 0, "z": 0, "type": "Rotation"}
    },
    "data": {}
 }
 ```
 ---
 ## 6. Link 端口标准化
 `graphio.py::canonicalize_links_ports` 处理 `port` 字段的多种格式：
 ```python
 # 输入: 字符串格式 "(A,B)"
 "port": "(pump_1, valve_1)"
 # 输出: 字典格式
 "port": {"source_id": "pump_1", "target_id": "valve_1"}
 # 输入: 已是字典
 "port": {"pump_1": "port", "serial_1": "port"}
 # 保持不变
 # 输入: 无 port 字段
 # 自动补充空 port
 ```
 ---
 ## 7. 关键路径
 | 内容 | 路径 |
 |------|------|
 | ResourceDict 模型 | `unilabos/resources/resource_tracker.py` |
 | 图加载 + 标准化 | `unilabos/resources/graphio.py` |
 | Handle 验证 | `unilabos/app/main.py` (449-481 行) |
 | 反应站图文件 | `unilabos/test/experiments/reaction_station_bioyond.json` |
 | 配液站图文件 | `unilabos/test/experiments/dispensing_station_bioyond.json` |
 | 用户文档 | `docs/user_guide/graph_files.md` |
--- a/.cursorignore
+++ b/.cursorignore
@@ -1,188 +0,0 @@
 # ============================================================
 # 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-*
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,11 +0,0 @@
 ## 设备接入
 当被要求添加设备驱动时，参考 `docs/ai_guides/add_device.md`。
 该指南包含完整的模板和已有设备接口参考。
 ## 关键规则
 - 动作方法的参数名是接口契约，不可重命名
 - `status` 字符串必须与同类已有设备一致
 - `self.data` 必须在 `__init__` 中预填充所有属性字段
 - 异步方法中使用 `await self._ros_node.sleep()`，禁止 `time.sleep()`
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,21 +0,0 @@
 # Uni-Lab-OS AI Agent 指南
 ## 设备接入
 当用户要求添加/接入新设备时，读取 `docs/ai_guides/add_device.md` 并按其流程执行。
 该指南完全自包含，包含物模型模板、现有设备接口快照、常见错误和验证清单。
 ## 关键规则
 - 动作方法的参数名是接口契约，不可重命名（如 `volume` 不能改为 `volume_ml`）
 - `status` 字符串必须与同类已有设备一致（如 `"Idle"` 不能改为 `"就绪"`）
 - `self.data` 必须在 `__init__` 中预填充所有属性字段
 - 异步方法中使用 `await self._ros_node.sleep()`，禁止 `time.sleep()` 和 `asyncio.sleep()`
 ## 项目结构
 - 设备驱动：`unilabos/devices/<category>/<device_name>.py`
 - 设备注册表：`unilabos/registry/devices/<device_name>.yaml`
 - 实验图文件：`unilabos/test/experiments/*.json`
 - 人类开发文档：`docs/developer_guide/`
 - AI 专用指南：`docs/ai_guides/`
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,14 +0,0 @@
 # Uni-Lab-OS
 ## 设备接入
 读取 `docs/ai_guides/add_device.md` 获取完整的自包含指南。
 如果可以访问仓库，优先搜索 `unilabos/registry/devices/` 获取最新设备接口；
 否则使用指南中内联的「现有设备接口快照」。
 ## 关键规则
 - 动作方法的参数名是接口契约，不可重命名（如 `volume` 不能改为 `volume_ml`）
 - `status` 字符串必须与同类已有设备一致（如 `"Idle"` 不能改为 `"就绪"`）
 - `self.data` 必须在 `__init__` 中预填充所有属性字段
 - 异步方法中使用 `await self._ros_node.sleep()`，禁止 `time.sleep()` 和 `asyncio.sleep()`
--- a/docs/ai_guides/add_device.md
+++ b/docs/ai_guides/add_device.md
--- a/docs/ai_guides/agent_prompt_template.md
+++ b/docs/ai_guides/agent_prompt_template.md
@@ -1,344 +0,0 @@
 # 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 行为，指南提供领域知识。两者独立维护
--- a/scripts/workflow.py
+++ b/scripts/workflow.py
@@ -2,6 +2,7 @@ import json
 import logging
 import traceback
 import uuid
 import xml.etree.ElementTree as ET
 from typing import Any, Dict, List
 import networkx as nx
@@ -24,15 +25,7 @@ class SimpleGraph:
    def add_edge(self, source, target, **attrs):
        """添加边"""
-        # edge = {"source": source, "target": target, **attrs}
+        edge = {"source": source, "target": target, **attrs}
        edge = {
            "source": source, "target": target,
            "source_node_uuid": source,
            "target_node_uuid": target,
            "source_handle_io": "source",
            "target_handle_io": "target",
            **attrs
        }
        self.edges.append(edge)
    def to_dict(self):
@@ -49,7 +42,6 @@ class SimpleGraph:
            "multigraph": False,
            "graph": {},
            "nodes": nodes_list,
            "edges": self.edges,
            "links": self.edges,
        }
@@ -66,8 +58,495 @@ def extract_json_from_markdown(text: str) -> str:
    return text
 def convert_to_type(val: str) -> Any:
    """将字符串值转换为适当的数据类型"""
    if val == "True":
        return True
    if val == "False":
        return False
    if val == "?":
        return None
    if val.endswith(" g"):
        return float(val.split(" ")[0])
    if val.endswith("mg"):
        return float(val.split("mg")[0])
    elif val.endswith("mmol"):
        return float(val.split("mmol")[0]) / 1000
    elif val.endswith("mol"):
        return float(val.split("mol")[0])
    elif val.endswith("ml"):
        return float(val.split("ml")[0])
    elif val.endswith("RPM"):
        return float(val.split("RPM")[0])
    elif val.endswith(" °C"):
        return float(val.split(" ")[0])
    elif val.endswith(" %"):
        return float(val.split(" ")[0])
    return val
 def refactor_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """统一的数据重构函数，根据操作类型自动选择模板"""
    refactored_data = []
    # 定义操作映射，包含生物实验和有机化学的所有操作
    OPERATION_MAPPING = {
        # 生物实验操作
        "transfer_liquid": "SynBioFactory-liquid_handler.prcxi-transfer_liquid",
        "transfer": "SynBioFactory-liquid_handler.biomek-transfer",
        "incubation": "SynBioFactory-liquid_handler.biomek-incubation",
        "move_labware": "SynBioFactory-liquid_handler.biomek-move_labware",
        "oscillation": "SynBioFactory-liquid_handler.biomek-oscillation",
        # 有机化学操作
        "HeatChillToTemp": "SynBioFactory-workstation-HeatChillProtocol",
        "StopHeatChill": "SynBioFactory-workstation-HeatChillStopProtocol",
        "StartHeatChill": "SynBioFactory-workstation-HeatChillStartProtocol",
        "HeatChill": "SynBioFactory-workstation-HeatChillProtocol",
        "Dissolve": "SynBioFactory-workstation-DissolveProtocol",
        "Transfer": "SynBioFactory-workstation-TransferProtocol",
        "Evaporate": "SynBioFactory-workstation-EvaporateProtocol",
        "Recrystallize": "SynBioFactory-workstation-RecrystallizeProtocol",
        "Filter": "SynBioFactory-workstation-FilterProtocol",
        "Dry": "SynBioFactory-workstation-DryProtocol",
        "Add": "SynBioFactory-workstation-AddProtocol",
    }
    UNSUPPORTED_OPERATIONS = ["Purge", "Wait", "Stir", "ResetHandling"]
    for step in data:
        operation = step.get("action")
        if not operation or operation in UNSUPPORTED_OPERATIONS:
            continue
        # 处理重复操作
        if operation == "Repeat":
            times = step.get("times", step.get("parameters", {}).get("times", 1))
            sub_steps = step.get("steps", step.get("parameters", {}).get("steps", []))
            for i in range(int(times)):
                sub_data = refactor_data(sub_steps)
                refactored_data.extend(sub_data)
            continue
        # 获取模板名称
        template = OPERATION_MAPPING.get(operation)
        if not template:
            # 自动推断模板类型
            if operation.lower() in ["transfer", "incubation", "move_labware", "oscillation"]:
                template = f"SynBioFactory-liquid_handler.biomek-{operation}"
            else:
                template = f"SynBioFactory-workstation-{operation}Protocol"
        # 创建步骤数据
        step_data = {
            "template": template,
            "description": step.get("description", step.get("purpose", f"{operation} operation")),
            "lab_node_type": "Device",
            "parameters": step.get("parameters", step.get("action_args", {})),
        }
        refactored_data.append(step_data)
    return refactored_data
 def build_protocol_graph(
    labware_info: List[Dict[str, Any]], protocol_steps: List[Dict[str, Any]], workstation_name: str
 ) -> SimpleGraph:
    """统一的协议图构建函数，根据设备类型自动选择构建逻辑"""
    G = SimpleGraph()
    resource_last_writer = {}
    LAB_NAME = "SynBioFactory"
    protocol_steps = refactor_data(protocol_steps)
    # 检查协议步骤中的模板来判断协议类型
    has_biomek_template = any(
        ("biomek" in step.get("template", "")) or ("prcxi" in step.get("template", ""))
        for step in protocol_steps
    )
    if has_biomek_template:
        # 生物实验协议图构建
        for labware_id, labware in labware_info.items():
            node_id = str(uuid.uuid4())
            labware_attrs = labware.copy()
            labware_id = labware_attrs.pop("id", labware_attrs.get("name", f"labware_{uuid.uuid4()}"))
            labware_attrs["description"] = labware_id
            labware_attrs["lab_node_type"] = (
                "Reagent" if "Plate" in str(labware_id) else "Labware" if "Rack" in str(labware_id) else "Sample"
            )
            labware_attrs["device_id"] = workstation_name
            G.add_node(node_id, template=f"{LAB_NAME}-host_node-create_resource", **labware_attrs)
            resource_last_writer[labware_id] = f"{node_id}:labware"
        # 处理协议步骤
        prev_node = None
        for i, step in enumerate(protocol_steps):
            node_id = str(uuid.uuid4())
            G.add_node(node_id, **step)
            # 添加控制流边
            if prev_node is not None:
                G.add_edge(prev_node, node_id, source_port="ready", target_port="ready")
            prev_node = node_id
            # 处理物料流
            params = step.get("parameters", {})
            if "sources" in params and params["sources"] in resource_last_writer:
                source_node, source_port = resource_last_writer[params["sources"]].split(":")
                G.add_edge(source_node, node_id, source_port=source_port, target_port="labware")
            if "targets" in params:
                resource_last_writer[params["targets"]] = f"{node_id}:labware"
        # 添加协议结束节点
        end_id = str(uuid.uuid4())
        G.add_node(end_id, template=f"{LAB_NAME}-liquid_handler.biomek-run_protocol")
        if prev_node is not None:
            G.add_edge(prev_node, end_id, source_port="ready", target_port="ready")
    else:
        # 有机化学协议图构建
        WORKSTATION_ID = workstation_name
        # 为所有labware创建资源节点
        for item_id, item in labware_info.items():
            # item_id = item.get("id") or item.get("name", f"item_{uuid.uuid4()}")
            node_id = str(uuid.uuid4())
            # 判断节点类型
            if item.get("type") == "hardware" or "reactor" in str(item_id).lower():
                if "reactor" not in str(item_id).lower():
                    continue
                lab_node_type = "Sample"
                description = f"Prepare Reactor: {item_id}"
                liquid_type = []
                liquid_volume = []
            else:
                lab_node_type = "Reagent"
                description = f"Add Reagent to Flask: {item_id}"
                liquid_type = [item_id]
                liquid_volume = [1e5]
            G.add_node(
                node_id,
                template=f"{LAB_NAME}-host_node-create_resource",
                description=description,
                lab_node_type=lab_node_type,
                res_id=item_id,
                device_id=WORKSTATION_ID,
                class_name="container",
                parent=WORKSTATION_ID,
                bind_locations={"x": 0.0, "y": 0.0, "z": 0.0},
                liquid_input_slot=[-1],
                liquid_type=liquid_type,
                liquid_volume=liquid_volume,
                slot_on_deck="",
                role=item.get("role", ""),
            )
            resource_last_writer[item_id] = f"{node_id}:labware"
        last_control_node_id = None
        # 处理协议步骤
        for step in protocol_steps:
            node_id = str(uuid.uuid4())
            G.add_node(node_id, **step)
            # 控制流
            if last_control_node_id is not None:
                G.add_edge(last_control_node_id, node_id, source_port="ready", target_port="ready")
            last_control_node_id = node_id
            # 物料流
            params = step.get("parameters", {})
            input_resources = {
                "Vessel": params.get("vessel"),
                "ToVessel": params.get("to_vessel"),
                "FromVessel": params.get("from_vessel"),
                "reagent": params.get("reagent"),
                "solvent": params.get("solvent"),
                "compound": params.get("compound"),
                "sources": params.get("sources"),
                "targets": params.get("targets"),
            }
            for target_port, resource_name in input_resources.items():
                if resource_name and resource_name in resource_last_writer:
                    source_node, source_port = resource_last_writer[resource_name].split(":")
                    G.add_edge(source_node, node_id, source_port=source_port, target_port=target_port)
            output_resources = {
                "VesselOut": params.get("vessel"),
                "FromVesselOut": params.get("from_vessel"),
                "ToVesselOut": params.get("to_vessel"),
                "FiltrateOut": params.get("filtrate_vessel"),
                "reagent": params.get("reagent"),
                "solvent": params.get("solvent"),
                "compound": params.get("compound"),
                "sources_out": params.get("sources"),
                "targets_out": params.get("targets"),
            }
            for source_port, resource_name in output_resources.items():
                if resource_name:
                    resource_last_writer[resource_name] = f"{node_id}:{source_port}"
    return G
 def draw_protocol_graph(protocol_graph: SimpleGraph, output_path: str):
    """
    (辅助功能) 使用 networkx 和 matplotlib 绘制协议工作流图，用于可视化。
    """
    if not protocol_graph:
        print("Cannot draw graph: Graph object is empty.")
        return
    G = nx.DiGraph()
    for node_id, attrs in protocol_graph.nodes.items():
        label = attrs.get("description", attrs.get("template", node_id[:8]))
        G.add_node(node_id, label=label, **attrs)
    for edge in protocol_graph.edges:
        G.add_edge(edge["source"], edge["target"])
    plt.figure(figsize=(20, 15))
    try:
        pos = nx.nx_agraph.graphviz_layout(G, prog="dot")
    except Exception:
        pos = nx.shell_layout(G)  # Fallback layout
    node_labels = {node: data["label"] for node, data in G.nodes(data=True)}
    nx.draw(
        G,
        pos,
        with_labels=False,
        node_size=2500,
        node_color="skyblue",
        node_shape="o",
        edge_color="gray",
        width=1.5,
        arrowsize=15,
    )
    nx.draw_networkx_labels(G, pos, labels=node_labels, font_size=8, font_weight="bold")
    plt.title("Chemical Protocol Workflow Graph", size=15)
    plt.savefig(output_path, dpi=300, bbox_inches="tight")
    plt.close()
    print(f"  - Visualization saved to '{output_path}'")
 from networkx.drawing.nx_agraph import to_agraph
 import re
 COMPASS = {"n","e","s","w","ne","nw","se","sw","c"}
 def _is_compass(port: str) -> bool:
    return isinstance(port, str) and port.lower() in COMPASS
 def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: str = "LR"):
    """
    使用 Graphviz 端口语法绘制协议工作流图。
    - 若边上的 source_port/target_port 是 compass（n/e/s/w/...），直接用 compass。
    - 否则自动为节点创建 record 形状并定义命名端口 <portname>。
    最终由 PyGraphviz 渲染并输出到 output_path（后缀决定格式，如 .png/.svg/.pdf）。
    """
    if not protocol_graph:
        print("Cannot draw graph: Graph object is empty.")
        return
    # 1) 先用 networkx 搭建有向图，保留端口属性
    G = nx.DiGraph()
    for node_id, attrs in protocol_graph.nodes.items():
        label = attrs.get("description", attrs.get("template", node_id[:8]))
        # 保留一个干净的“中心标签”，用于放在 record 的中间槽
        G.add_node(node_id, _core_label=str(label), **{k:v for k,v in attrs.items() if k not in ("label",)})
    edges_data = []
    in_ports_by_node  = {}  # 收集命名输入端口
    out_ports_by_node = {}  # 收集命名输出端口
    for edge in protocol_graph.edges:
        u = edge["source"]
        v = edge["target"]
        sp = edge.get("source_port")
        tp = edge.get("target_port")
        # 记录到图里（保留原始端口信息）
        G.add_edge(u, v, source_port=sp, target_port=tp)
        edges_data.append((u, v, sp, tp))
        # 如果不是 compass，就按“命名端口”先归类，等会儿给节点造 record
        if sp and not _is_compass(sp):
            out_ports_by_node.setdefault(u, set()).add(str(sp))
        if tp and not _is_compass(tp):
            in_ports_by_node.setdefault(v, set()).add(str(tp))
    # 2) 转为 AGraph，使用 Graphviz 渲染
    A = to_agraph(G)
    A.graph_attr.update(rankdir=rankdir, splines="true", concentrate="false", fontsize="10")
    A.node_attr.update(shape="box", style="rounded,filled", fillcolor="lightyellow", color="#999999", fontname="Helvetica")
    A.edge_attr.update(arrowsize="0.8", color="#666666")
    # 3) 为需要命名端口的节点设置 record 形状与 label
    #    左列 = 输入端口；中间 = 核心标签；右列 = 输出端口
    for n in A.nodes():
        node = A.get_node(n)
        core = G.nodes[n].get("_core_label", n)
        in_ports  = sorted(in_ports_by_node.get(n, []))
        out_ports = sorted(out_ports_by_node.get(n, []))
        # 如果该节点涉及命名端口，则用 record；否则保留原 box
        if in_ports or out_ports:
            def port_fields(ports):
                if not ports:
                    return " "  # 必须留一个空槽占位
                # 每个端口一个小格子，<p> name
                return "|".join(f"<{re.sub(r'[^A-Za-z0-9_:.|-]', '_', p)}> {p}" for p in ports)
            left  = port_fields(in_ports)
            right = port_fields(out_ports)
            # 三栏：左(入) | 中(节点名) | 右(出)
            record_label = f"{{ {left} | {core} | {right} }}"
            node.attr.update(shape="record", label=record_label)
        else:
            # 没有命名端口：普通盒子，显示核心标签
            node.attr.update(label=str(core))
    # 4) 给边设置 headport / tailport
    #    - 若端口为 compass：直接用 compass（e.g., headport="e"）
    #    - 若端口为命名端口：使用在 record 中定义的 <port> 名（同名即可）
    for (u, v, sp, tp) in edges_data:
        e = A.get_edge(u, v)
        # Graphviz 属性：tail 是源，head 是目标
        if sp:
            if _is_compass(sp):
                e.attr["tailport"] = sp.lower()
            else:
                # 与 record label 中 <port> 名一致；特殊字符已在 label 中做了清洗
                e.attr["tailport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(sp))
        if tp:
            if _is_compass(tp):
                e.attr["headport"] = tp.lower()
            else:
                e.attr["headport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(tp))
        # 可选：若想让边更贴边缘，可设置 constraint/spline 等
        # e.attr["arrowhead"] = "vee"
    # 5) 输出
    A.draw(output_path, prog="dot")
    print(f"  - Port-aware workflow rendered to '{output_path}'")
 def flatten_xdl_procedure(procedure_elem: ET.Element) -> List[ET.Element]:
    """展平嵌套的XDL程序结构"""
    flattened_operations = []
    TEMP_UNSUPPORTED_PROTOCOL = ["Purge", "Wait", "Stir", "ResetHandling"]
    def extract_operations(element: ET.Element):
        if element.tag not in ["Prep", "Reaction", "Workup", "Purification", "Procedure"]:
            if element.tag not in TEMP_UNSUPPORTED_PROTOCOL:
                flattened_operations.append(element)
        for child in element:
            extract_operations(child)
    for child in procedure_elem:
        extract_operations(child)
    return flattened_operations
 def parse_xdl_content(xdl_content: str) -> tuple:
    """解析XDL内容"""
    try:
        xdl_content_cleaned = "".join(c for c in xdl_content if c.isprintable())
        root = ET.fromstring(xdl_content_cleaned)
        synthesis_elem = root.find("Synthesis")
        if synthesis_elem is None:
            return None, None, None
        # 解析硬件组件
        hardware_elem = synthesis_elem.find("Hardware")
        hardware = []
        if hardware_elem is not None:
            hardware = [{"id": c.get("id"), "type": c.get("type")} for c in hardware_elem.findall("Component")]
        # 解析试剂
        reagents_elem = synthesis_elem.find("Reagents")
        reagents = []
        if reagents_elem is not None:
            reagents = [{"name": r.get("name"), "role": r.get("role", "")} for r in reagents_elem.findall("Reagent")]
        # 解析程序
        procedure_elem = synthesis_elem.find("Procedure")
        if procedure_elem is None:
            return None, None, None
        flattened_operations = flatten_xdl_procedure(procedure_elem)
        return hardware, reagents, flattened_operations
    except ET.ParseError as e:
        raise ValueError(f"Invalid XDL format: {e}")
 def convert_xdl_to_dict(xdl_content: str) -> Dict[str, Any]:
    """
    将XDL XML格式转换为标准的字典格式
    Args:
        xdl_content: XDL XML内容
    Returns:
        转换结果，包含步骤和器材信息
    """
    try:
        hardware, reagents, flattened_operations = parse_xdl_content(xdl_content)
        if hardware is None:
            return {"error": "Failed to parse XDL content", "success": False}
        # 将XDL元素转换为字典格式
        steps_data = []
        for elem in flattened_operations:
            # 转换参数类型
            parameters = {}
            for key, val in elem.attrib.items():
                converted_val = convert_to_type(val)
                if converted_val is not None:
                    parameters[key] = converted_val
            step_dict = {
                "operation": elem.tag,
                "parameters": parameters,
                "description": elem.get("purpose", f"Operation: {elem.tag}"),
            }
            steps_data.append(step_dict)
        # 合并硬件和试剂为统一的labware_info格式
        labware_data = []
        labware_data.extend({"id": hw["id"], "type": "hardware", **hw} for hw in hardware)
        labware_data.extend({"name": reagent["name"], "type": "reagent", **reagent} for reagent in reagents)
        return {
            "success": True,
            "steps": steps_data,
            "labware": labware_data,
            "message": f"Successfully converted XDL to dict format. Found {len(steps_data)} steps and {len(labware_data)} labware items.",
        }
    except Exception as e:
        error_msg = f"XDL conversion failed: {str(e)}"
        logger.error(error_msg)
        return {"error": error_msg, "success": False}
 def create_workflow(
--- a/unilabos/app/main.py
+++ b/unilabos/app/main.py
@@ -1,7 +1,6 @@
 import argparse
 import asyncio
 import os
 import platform
 import shutil
 import signal
 import sys
@@ -359,7 +358,7 @@ def main():
    if BasicConfig.test_mode:
        print_status("启用测试模式：所有动作将模拟执行，不调用真实硬件", "warning")
    BasicConfig.communication_protocol = "websocket"
-    machine_name = platform.node()
+    machine_name = os.popen("hostname").read().strip()
    machine_name = "".join([c if c.isalnum() or c == "_" else "_" for c in machine_name])
    BasicConfig.machine_name = machine_name
    BasicConfig.vis_2d_enable = args_dict["2d_vis"]
--- a/unilabos/app/web/client.py
+++ b/unilabos/app/web/client.py
@@ -3,7 +3,7 @@ HTTP客户端模块
 提供与远程服务器通信的客户端功能，只有host需要用
 """
-import gzip
+
 import json
 import os
 from typing import List, Dict, Any, Optional
@@ -290,17 +290,10 @@ class HTTPClient:
        Returns:
            Response: API响应对象
        """
        compressed_body = gzip.compress(
            json.dumps(registry_data, ensure_ascii=False, default=str).encode("utf-8")
        )
        response = requests.post(
            f"{self.remote_addr}/lab/resource",
-            data=compressed_body,
+            json=registry_data,
-            headers={
+            headers={"Authorization": f"Lab {self.auth}"},
                "Authorization": f"Lab {self.auth}",
                "Content-Type": "application/json",
                "Content-Encoding": "gzip",
            },
            timeout=30,
        )
        if response.status_code not in [200, 201]:
--- a/unilabos/app/ws_client.py
+++ b/unilabos/app/ws_client.py
@@ -466,7 +466,6 @@ class MessageProcessor:
                async with websockets.connect(
                    self.websocket_url,
                    ssl=ssl_context,
                    open_timeout=20,
                    ping_interval=WSConfig.ping_interval,
                    ping_timeout=10,
                    additional_headers={
@@ -479,7 +478,7 @@ class MessageProcessor:
                    self.connected = True
                    self.reconnect_count = 0
-                    logger.trace(f"[MessageProcessor] Connected to {self.websocket_url}")
+                    logger.info(f"[MessageProcessor] Connected to {self.websocket_url}")
                    # 启动发送协程
                    send_task = asyncio.create_task(self._send_handler())
@@ -498,18 +497,6 @@ class MessageProcessor:
            except websockets.exceptions.ConnectionClosed:
                logger.warning("[MessageProcessor] Connection closed")
                self.connected = False
            except TimeoutError:
                logger.warning(
                    f"[MessageProcessor] Connection timeout (attempt {self.reconnect_count + 1}), "
                    f"server may be temporarily unavailable"
                )
                self.connected = False
            except websockets.exceptions.InvalidStatus as e:
                logger.warning(
                    f"[MessageProcessor] Server returned unexpected HTTP status {e.response.status_code}, "
                    f"WebSocket endpoint may not be ready yet"
                )
                self.connected = False
            except Exception as e:
                logger.error(f"[MessageProcessor] Connection error: {str(e)}")
                logger.error(traceback.format_exc())
@@ -518,19 +505,18 @@ class MessageProcessor:
                self.websocket = None
            # 重连逻辑
-            if not self.is_running:
+            if self.is_running and self.reconnect_count < WSConfig.max_reconnect_attempts:
                break
            if self.reconnect_count < WSConfig.max_reconnect_attempts:
                self.reconnect_count += 1
                backoff = min(WSConfig.reconnect_interval * (2 ** (self.reconnect_count - 1)), 60)
                logger.info(
-                    f"[MessageProcessor] Reconnecting in {backoff}s "
+                    f"[MessageProcessor] Reconnecting in {WSConfig.reconnect_interval}s "
                    f"(attempt {self.reconnect_count}/{WSConfig.max_reconnect_attempts})"
                )
-                await asyncio.sleep(backoff)
+                await asyncio.sleep(WSConfig.reconnect_interval)
-            else:
+            elif self.reconnect_count >= WSConfig.max_reconnect_attempts:
                logger.error("[MessageProcessor] Max reconnection attempts reached")
                break
            else:
                self.reconnect_count -= 1
    async def _message_handler(self):
        """处理接收到的消息"""
@@ -570,7 +556,7 @@ class MessageProcessor:
    async def _send_handler(self):
        """处理发送队列中的消息"""
-        logger.trace("[MessageProcessor] Send handler started")
+        logger.debug("[MessageProcessor] Send handler started")
        try:
            while self.connected and self.websocket:
@@ -1104,7 +1090,7 @@ class QueueProcessor:
    def _run(self):
        """运行队列处理主循环"""
-        logger.trace("[QueueProcessor] Queue processor started")
+        logger.debug("[QueueProcessor] Queue processor started")
        while self.is_running:
            try:
@@ -1319,6 +1305,7 @@ class WebSocketClient(BaseCommunicationClient):
        else:
            url = f"{scheme}://{parsed.netloc}/api/v1/ws/schedule"
        logger.debug(f"[WebSocketClient] URL: {url}")
        return url
    def start(self) -> None:
@@ -1331,11 +1318,13 @@ class WebSocketClient(BaseCommunicationClient):
            logger.error("[WebSocketClient] WebSocket URL not configured")
            return
        logger.info(f"[WebSocketClient] Starting connection to {self.websocket_url}")
        # 启动两个核心线程
        self.message_processor.start()
        self.queue_processor.start()
-        logger.trace("[WebSocketClient] All threads started")
+        logger.info("[WebSocketClient] All threads started")
    def stop(self) -> None:
        """停止WebSocket客户端"""
--- a/unilabos/devices/liquid_handling/liquid_handler_abstract.py
+++ b/unilabos/devices/liquid_handling/liquid_handler_abstract.py
@@ -57,18 +57,6 @@ 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
--- a/unilabos/devices/liquid_handling/prcxi/prcxi.py
+++ b/unilabos/devices/liquid_handling/prcxi/prcxi.py
@@ -55,7 +55,6 @@ from unilabos.devices.liquid_handling.liquid_handler_abstract import (
    TransferLiquidReturn,
 )
 from unilabos.registry.placeholder_type import ResourceSlot
 from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
@@ -91,103 +90,20 @@ class PRCXI9300Deck(Deck):
    该类定义了 PRCXI 9300 的工作台布局和槽位信息。
    """
-    # T1-T16 默认位置 (4列×4行)
+    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, **kwargs):
    _DEFAULT_SITE_POSITIONS = [
        (0, 0, 0), (138, 0, 0), (276, 0, 0), (414, 0, 0),         # T1-T4
        (0, 96, 0), (138, 96, 0), (276, 96, 0), (414, 96, 0),     # T5-T8
        (0, 192, 0), (138, 192, 0), (276, 192, 0), (414, 192, 0), # T9-T12
        (0, 288, 0), (138, 288, 0), (276, 288, 0), (414, 288, 0), # T13-T16
    ]
    _DEFAULT_SITE_SIZE = {"width": 128.0, "height": 86, "depth": 0}
    _DEFAULT_CONTENT_TYPE = ["plate", "tip_rack", "plates", "tip_racks", "tube_rack", "adaptor"]
    def __init__(self, name: str, size_x: float, size_y: float, size_z: float,
                 sites: Optional[List[Dict[str, Any]]] = None, **kwargs):
        super().__init__(size_x, size_y, size_z, name)
-        if sites is not None:
+        self.slots = [None] * 16  # PRCXI 9300/9320 最大有 16 个槽位
-            self.sites: List[Dict[str, Any]] = [dict(s) for s in sites]
+        self.slot_locations = [Coordinate(0, 0, 0)] * 16
        else:
            self.sites = []
            for i, (x, y, z) in enumerate(self._DEFAULT_SITE_POSITIONS):
                self.sites.append({
                    "label": f"T{i + 1}",
                    "visible": True,
                    "position": {"x": x, "y": y, "z": z},
                    "size": dict(self._DEFAULT_SITE_SIZE),
                    "content_type": list(self._DEFAULT_CONTENT_TYPE),
                })
        # _ordering: label -> None, 用于外部通过 list(keys()).index(site) 将 Tn 转换为 spot index
        self._ordering = collections.OrderedDict(
            (site["label"], None) for site in self.sites
        )
    def _get_site_location(self, idx: int) -> Coordinate:
        pos = self.sites[idx]["position"]
        return Coordinate(pos["x"], pos["y"], pos["z"])
    def _get_site_resource(self, idx: int) -> Optional[Resource]:
        site_loc = self._get_site_location(idx)
        for child in self.children:
            if child.location == site_loc:
                return child
        return None
    def assign_child_resource(
        self,
        resource: Resource,
        location: Optional[Coordinate] = None,
        reassign: bool = True,
        spot: Optional[int] = None,
    ):
        idx = spot
        if spot is not None:
            idx = spot
        else:
            for i, site in enumerate(self.sites):
                site_loc = self._get_site_location(i)
                if site.get("label") == resource.name:
                    idx = i
                    break
                if location is not None and site_loc == location:
                    idx = i
                    break
        if idx is None:
            for i in range(len(self.sites)):
                if self._get_site_resource(i) is None:
                    idx = i
                    break
        if idx is None:
            raise ValueError(f"No available site on deck '{self.name}' for resource '{resource.name}'")
        if not reassign and self._get_site_resource(idx) is not None:
            raise ValueError(f"Site {idx} ('{self.sites[idx]['label']}') is already occupied")
        loc = self._get_site_location(idx)
        super().assign_child_resource(resource, location=loc, reassign=reassign)
    def assign_child_at_slot(self, resource: Resource, slot: int, reassign: bool = False) -> None:
-        self.assign_child_resource(resource, spot=slot - 1, reassign=reassign)
+        if self.slots[slot - 1] is not None and not reassign:
            raise ValueError(f"Spot {slot} is already occupied")
-    def serialize(self) -> dict:
+        self.slots[slot - 1] = resource
-        data = super().serialize()
+        super().assign_child_resource(resource, location=self.slot_locations[slot - 1])
        sites_out = []
        for i, site in enumerate(self.sites):
            occupied = self._get_site_resource(i)
            sites_out.append({
                "label": site["label"],
                "visible": site.get("visible", True),
                "occupied_by": occupied.name if occupied is not None else None,
                "position": site["position"],
                "size": site["size"],
                "content_type": site["content_type"],
            })
        data["sites"] = sites_out
        return data
-class PRCXI9300Container(Container):
+class PRCXI9300Container(Plate):
    """PRCXI 9300 的专用 Container 类，继承自 Plate，用于槽位定位和未知模块。
    该类定义了 PRCXI 9300 的工作台布局和槽位信息。
@@ -200,10 +116,11 @@ class PRCXI9300Container(Container):
        size_y: float,
        size_z: float,
        category: str,
        ordering: collections.OrderedDict,
        model: Optional[str] = None,
        **kwargs,
    ):
-        super().__init__(name, size_x, size_y, size_z, category=category, model=model)
+        super().__init__(name, size_x, size_y, size_z, category=category, ordering=ordering, model=model)
        self._unilabos_state = {}
    def load_state(self, state: Dict[str, Any]) -> None:
@@ -650,14 +567,14 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
        tablets_info = []
        count = 0
        for child in deck.children:
-            # 如果放其他类型的物料，是不可以的
+            if child.children:
-            if hasattr(child, "_unilabos_state") and "Material" in child._unilabos_state:
+                if "Material" in child.children[0]._unilabos_state:
-                number = int(child.name.replace("T", ""))
+                    number = int(child.name.replace("T", ""))
-                tablets_info.append(
+                    tablets_info.append(
-                    WorkTablets(
+                        WorkTablets(
-                        Number=number, Code=f"T{number}", Material=child._unilabos_state["Material"]
+                            Number=number, Code=f"T{number}", Material=child.children[0]._unilabos_state["Material"]
                        )
                    )
                )
        if is_9320:
            print("当前设备是9320")
        # 始终初始化 step_mode 属性
--- a/unilabos/devices/motor/ZDT_X42.py
+++ b/unilabos/devices/motor/ZDT_X42.py
@@ -1,376 +0,0 @@
 # -*- 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()
--- a/unilabos/devices/separator/chinwe.py
+++ b/unilabos/devices/separator/chinwe.py
@@ -623,119 +623,6 @@ 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)
--- a/unilabos/devices/separator/xkc_sensor.py
+++ b/unilabos/devices/separator/xkc_sensor.py
@@ -1,379 +0,0 @@
 # -*- 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")
--- a/unilabos/devices/workstation/bioyond_studio/station.py
+++ b/unilabos/devices/workstation/bioyond_studio/station.py
@@ -258,7 +258,7 @@ class BioyondResourceSynchronizer(ResourceSynchronizer):
                logger.info(f"[同步→Bioyond] ➕ 物料不存在于 Bioyond，将创建新物料并入库")
            # 第1步：从配置中获取仓库配置
-            warehouse_mapping = self.workstation.bioyond_config.get("warehouse_mapping", {})
+            warehouse_mapping = self.bioyond_config.get("warehouse_mapping", {})
            # 确定目标仓库名称
            parent_name = None
--- a/unilabos/registry/devices/chinwe.yaml
+++ b/unilabos/registry/devices/chinwe.yaml
@@ -317,47 +317,6 @@ separator.chinwe:
              - port
              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:
        goal:
          target_state: 有液
--- a/unilabos/registry/devices/motor.yaml
+++ b/unilabos/registry/devices/motor.yaml
@@ -1,286 +0,0 @@
 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
--- a/unilabos/registry/devices/sensor.yaml
+++ b/unilabos/registry/devices/sensor.yaml
@@ -1,148 +0,0 @@
 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
--- a/unilabos/registry/registry.py
+++ b/unilabos/registry/registry.py
@@ -175,8 +175,7 @@ class Registry:
                                    "res_id": "unilabos_resources",  # 将当前实验室的全部物料id作为下拉框可选择
                                    "device_id": "unilabos_devices",  # 将当前实验室的全部设备id作为下拉框可选择
                                    "parent": "unilabos_nodes",  # 将当前实验室的设备/物料作为下拉框可选择
-                                    "class_name": "unilabos_class",  # 当前实验室物料的class name
+                                    "class_name": "unilabos_class",
                                    "slot_on_deck": "unilabos_resource_slot:parent",  # 勾选的parent的config中的sites的name，展示name，参数对应slot（index）
                                },
                            },
                            "test_latency": {
--- a/unilabos/registry/resources/bioyond/bottle_carriers.yaml
+++ b/unilabos/registry/resources/bioyond/bottle_carriers.yaml
@@ -46,16 +46,3 @@ BIOYOND_PolymerStation_8StockCarrier:
  init_param_schema: {}
  registry_type: resource
  version: 1.0.0
 BIOYOND_PolymerStation_TipBox:
  category:
  - bottle_carriers
  - tip_racks
  class:
    module: unilabos.resources.bioyond.bottle_carriers:BIOYOND_PolymerStation_TipBox
    type: pylabrobot
  description: BIOYOND_PolymerStation_TipBox (4x6布局，24个枪头孔位)
  handles: []
  icon: ''
  init_param_schema: {}
  registry_type: resource
  version: 1.0.0
--- a/unilabos/registry/resources/bioyond/bottles.yaml
+++ b/unilabos/registry/resources/bioyond/bottles.yaml
@@ -82,3 +82,14 @@ BIOYOND_PolymerStation_Solution_Beaker:
  icon: ''
  init_param_schema: {}
  version: 1.0.0
 BIOYOND_PolymerStation_TipBox:
  category:
  - bottles
  - tip_boxes
  class:
    module: unilabos.resources.bioyond.bottles:BIOYOND_PolymerStation_TipBox
    type: pylabrobot
  handles: []
  icon: ''
  init_param_schema: {}
  version: 1.0.0
--- a/unilabos/resources/bioyond/bottle_carriers.py
+++ b/unilabos/resources/bioyond/bottle_carriers.py
@@ -1,4 +1,4 @@
-from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d, Container
+from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d
 from unilabos.resources.itemized_carrier import BottleCarrier
 from unilabos.resources.bioyond.bottles import (
@@ -9,28 +9,6 @@ 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
@@ -344,88 +322,3 @@ 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
--- a/unilabos/resources/bioyond/bottles.py
+++ b/unilabos/resources/bioyond/bottles.py
@@ -116,9 +116,7 @@ def BIOYOND_PolymerStation_TipBox(
    size_z: float = 100.0,   # 枪头盒高度
    barcode: str = None,
 ):
-    """创建4×6枪头盒 (24个枪头) - 使用 BottleCarrier 结构
+    """创建4×6枪头盒 (24个枪头)
    注意：此函数已弃用，请使用 bottle_carriers.py 中的版本
    Args:
        name: 枪头盒名称
@@ -128,11 +126,55 @@ def BIOYOND_PolymerStation_TipBox(
        barcode: 条形码
    Returns:
-        BottleCarrier: 包含24个枪头孔位的枪头盒载架
+        TipBoxCarrier: 包含24个枪头孔位的枪头盒
    """
-    # 重定向到 bottle_carriers.py 中的实现
+    from pylabrobot.resources import Container, Coordinate
-    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)
+    # 创建枪头盒容器
    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
 def BIOYOND_PolymerStation_Flask(
--- a/unilabos/resources/container.py
+++ b/unilabos/resources/container.py
@@ -1,6 +1,10 @@
 import json
 from typing import Dict, Any
 from pylabrobot.resources import Container
 from unilabos_msgs.msg import Resource
 from unilabos.ros.msgs.message_converter import convert_from_ros_msg
 class RegularContainer(Container):
@@ -12,12 +16,12 @@ class RegularContainer(Container):
            kwargs["size_y"] = 0
        if "size_z" not in kwargs:
            kwargs["size_z"] = 0
        self.kwargs = kwargs
        self.state = {}
        super().__init__(*args, category="container", **kwargs)
    def load_state(self, state: Dict[str, Any]):
-        super().load_state(state)
+        self.state = state
 def get_regular_container(name="container"):
@@ -25,6 +29,7 @@ def get_regular_container(name="container"):
    r.category = "container"
    return r
 #
 # class RegularContainer(object):
 #     # 第一个参数必须是id传入
 #     # noinspection PyShadowingBuiltins
@@ -84,4 +89,4 @@ def get_regular_container(name="container"):
 #         return to_dict
 #
 #     def __str__(self):
-#         return f"{self.id}"
+#         return f"{self.id}"
--- a/unilabos/resources/graphio.py
+++ b/unilabos/resources/graphio.py
@@ -42,7 +42,7 @@ def canonicalize_nodes_data(
    Returns:
        ResourceTreeSet: 标准化后的资源树集合
    """
-    print_status(f"{len(nodes)} Resources loaded", "info")
+    print_status(f"{len(nodes)} Resources loaded:", "info")
    # 第一步：基本预处理（处理graphml的label字段）
    outer_host_node_id = None
@@ -76,7 +76,7 @@ def canonicalize_nodes_data(
            if sample_id:
                logger.error(f"{node}的sample_id参数已弃用，sample_id: {sample_id}")
        for k in list(node.keys()):
-            if k not in ["id", "uuid", "name", "description", "schema", "model", "icon", "parent_uuid", "parent", "type", "class", "position", "config", "data", "children", "pose", "extra"]:
+            if k not in ["id", "uuid", "name", "description", "schema", "model", "icon", "parent_uuid", "parent", "type", "class", "position", "config", "data", "children", "pose"]:
                v = node.pop(k)
                node["config"][k] = v
    if outer_host_node_id is not None:
@@ -779,12 +779,9 @@ 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
                    )
-                    # 只有具有 tracker 属性的容器才设置液体信息（如 Bottle, Well）
+                    bottle.tracker.liquids = [
-                    # ResourceHolder 等不支持液体追踪的容器跳过
+                        (detail["name"], float(detail.get("quantity", 0)) if detail.get("quantity") else 0)
-                    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:
@@ -793,11 +790,9 @@ 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 属性才设置液体信息
+                bottle.tracker.liquids = [
-                if hasattr(bottle, "tracker"):
+                    (material["name"], float(material.get("quantity", 0)) if material.get("quantity") else 0)
-                    bottle.tracker.liquids = [
+                ]
                        (material["name"], float(material.get("quantity", 0)) if material.get("quantity") else 0)
                    ]
        plr_materials.append(plr_material)
@@ -826,29 +821,24 @@ 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右"
-                # 根据列号(y)判断: 1-4映射到左侧, 5-8映射到右侧
+                # 根据列号(x)判断: 1-4映射到左侧, 5-8映射到右侧
                if wh_name == "堆栈1":
-                    if 1 <= y <= 4:
+                    x_val = loc.get("x", 1)
                    if 1 <= x_val <= 4:
                        wh_name = "堆栈1左"
-                    elif 5 <= y <= 8:
+                    elif 5 <= x_val <= 8:
                        wh_name = "堆栈1右"
                        y = y - 4  # 调整列号: 5-8映射到1-4
                    else:
-                        logger.warning(f"物料 {material['name']} 的列号 y={y} 超出范围，无法映射到堆栈1左或堆栈1右")
+                        logger.warning(f"物料 {material['name']} 的列号 x={x_val} 超出范围，无法映射到堆栈1左或堆栈1右")
                        continue
                # 特殊处理: Bioyond的"站内Tip盒堆栈"也需要进行拆分映射
                if wh_name == "站内Tip盒堆栈":
-                    if y == 1:
+                    y_val = loc.get("y", 1)
                    if y_val == 1:
                        wh_name = "站内Tip盒堆栈(右)"
-                    elif y in [2, 3]:
+                    elif y_val in [2, 3]:
                        wh_name = "站内Tip盒堆栈(左)"
                        y = y - 1  # 调整列号，因为左侧仓库对应的 Bioyond y=2 实际上是它的第1列
@@ -856,6 +846,15 @@ 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 ["站内试剂存放堆栈", "测量小瓶仓库(测密度)"]:
--- a/unilabos/resources/plr_additional_res_reg.py
+++ b/unilabos/resources/plr_additional_res_reg.py
@@ -18,9 +18,3 @@ 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,
    )
--- a/unilabos/resources/resource_tracker.py
+++ b/unilabos/resources/resource_tracker.py
@@ -16,7 +16,6 @@ if TYPE_CHECKING:
 EXTRA_CLASS = "unilabos_resource_class"
 FRONTEND_POSE_EXTRA = "unilabos_frontend_pose_extra"
 EXTRA_SAMPLE_UUID = "sample_uuid"
 EXTRA_UNILABOS_SAMPLE_UUID = "unilabos_sample_uuid"
@@ -101,7 +100,6 @@ class ResourceDictPosition(BaseModel):
    cross_section_type: Literal["rectangle", "circle", "rounded_rectangle"] = Field(
        description="Cross section type", default="rectangle"
    )
    extra: Optional[Dict[str, Any]] = Field(description="Extra data", default=None)
 class ResourceDictType(TypedDict):
@@ -139,8 +137,8 @@ class ResourceDict(BaseModel):
    klass: str = Field(alias="class", description="Resource class name")
    pose: ResourceDictPosition = Field(description="Resource position", default_factory=ResourceDictPosition)
    config: Dict[str, Any] = Field(description="Resource configuration")
-    data: Dict[str, Any] = Field(description="Resource data, eg: container liquid data")
+    data: Dict[str, Any] = Field(description="Resource data")
-    extra: Dict[str, Any] = Field(description="Extra data, eg: slot index")
+    extra: Dict[str, Any] = Field(description="Extra data")
    @field_serializer("parent_uuid")
    def _serialize_parent(self, parent_uuid: Optional["ResourceDict"]):
@@ -411,18 +409,8 @@ 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",
                "container": "container",
                "material_plate": "material_plate",
                "electrode_sheet": "electrode_sheet",
                "warehouse": "warehouse",
                "magazine_holder": "magazine_holder",
                "resource_group": "resource_group",
                "trash": "trash",
                "plate_adapter": "plate_adapter",
            }
            if source in replace_info:
                return replace_info[source]
@@ -466,7 +454,6 @@ class ResourceTreeSet(object):
                "position3d": raw_pos,
                "rotation": d["rotation"],
                "cross_section_type": d.get("cross_section_type", "rectangle"),
                "extra": extra.get(FRONTEND_POSE_EXTRA)
            }
            # 先构建当前节点的字典（不包含children）
@@ -552,7 +539,6 @@ class ResourceTreeSet(object):
            name_to_uuid[node.res_content.name] = node.res_content.uuid
            all_states[node.res_content.name] = node.res_content.data
            name_to_extra[node.res_content.name] = node.res_content.extra
            name_to_extra[node.res_content.name][FRONTEND_POSE_EXTRA] = node.res_content.pose.extra
            name_to_extra[node.res_content.name][EXTRA_CLASS] = node.res_content.klass
            for child in node.children:
                collect_node_data(child, name_to_uuid, all_states, name_to_extra)
@@ -621,7 +607,7 @@ class ResourceTreeSet(object):
                plr_resources.append(plr_resource)
            except Exception as e:
-                logger.error(f"转换 PLR 资源失败: {e} {str(plr_dict)[:1000]}")
+                logger.error(f"转换 PLR 资源失败: {e}")
                import traceback
                logger.error(f"堆栈: {traceback.format_exc()}")
@@ -841,27 +827,14 @@ class ResourceTreeSet(object):
                                f"从远端同步了 {added_count} 个物料子树"
                            )
                    else:
-                        # 二级物料已存在，比较三级子节点是否缺失
+                        # 情况2: 二级是物料（不是 device）
-                        local_material = local_children_map[remote_child_name]
+                        if remote_child_name not in local_children_map:
-                        local_material_children_map = {child.res_content.name: child for child in
+                            # 引入整个子树
-                                                       local_material.children}
+                            remote_child.res_content.parent = local_device.res_content
-                        added_count = 0
+                            local_device.children.append(remote_child)
-                        for remote_sub in remote_child.children:
+                            logger.info(f"Device '{remote_root_id}': 从远端同步物料子树 '{remote_child_name}'")
-                            remote_sub_name = remote_sub.res_content.name
+                        else:
-                            if remote_sub_name not in local_material_children_map:
+                            logger.info(f"物料 '{remote_root_id}/{remote_child_name}' 已存在，跳过")
                                remote_sub.res_content.parent = local_material.res_content
                                local_material.children.append(remote_sub)
                                added_count += 1
                            else:
                                logger.info(
                                    f"物料 '{remote_root_id}/{remote_child_name}/{remote_sub_name}' "
                                    f"已存在，跳过"
                                )
                        if added_count > 0:
                            logger.info(
                                f"物料 '{remote_root_id}/{remote_child_name}': "
                                f"从远端同步了 {added_count} 个子物料"
                            )
            else:
                # 情况1: 一级节点是物料（不是 device）
                # 检查是否已存在
--- a/unilabos/ros/nodes/base_device_node.py
+++ b/unilabos/ros/nodes/base_device_node.py
@@ -915,24 +915,8 @@ class BaseROS2DeviceNode(Node, Generic[T]):
                        else []
                    )
                    if target_site is not None and sites is not None and site_names is not None:
-                        site_index = None
+                        site_index = sites.index(original_instance)
-                        try:
+                        site_name = site_names[site_index]
                            # sites 可能是 Resource 列表或 dict 列表 (如 PRCXI9300Deck)
                            # 只有itemized_carrier在使用，准备弃用
                            site_index = sites.index(original_instance)
                        except ValueError:
                            # dict 类型的 sites: 通过name匹配
                            for idx, site in enumerate(sites):
                                if original_instance.name == site["occupied_by"]:
                                    site_index = idx
                                    break
                                elif (original_instance.location.x == site["position"]["x"] and original_instance.location.y == site["position"]["y"] and original_instance.location.z == site["position"]["z"]):
                                    site_index = idx
                                    break
                        if site_index is None:
                            site_name = None
                        else:
                            site_name = site_names[site_index]
                        if site_name != target_site:
                            parent = self.transfer_to_new_resource(original_instance, tree, additional_add_params)
                            if parent is not None:
@@ -940,14 +924,6 @@ class BaseROS2DeviceNode(Node, Generic[T]):
                                parent_appended = True
                # 加载状态
                # noinspection PyProtectedMember
                original_instance._size_x = plr_resource._size_x
                # noinspection PyProtectedMember
                original_instance._size_y = plr_resource._size_y
                # noinspection PyProtectedMember
                original_instance._size_z = plr_resource._size_z
                # noinspection PyProtectedMember
                original_instance._local_size_z = plr_resource._local_size_z
                original_instance.location = plr_resource.location
                original_instance.rotation = plr_resource.rotation
                original_instance.barcode = plr_resource.barcode
@@ -1008,7 +984,7 @@ class BaseROS2DeviceNode(Node, Generic[T]):
                        ].call_async(
                            r
                        )  # type: ignore
-                        self.lab_logger().trace(f"确认资源云端 Add 结果: {response.response}")
+                        self.lab_logger().info(f"确认资源云端 Add 结果: {response.response}")
                        results.append(result)
                    elif action == "update":
                        if tree_set is None:
@@ -1034,7 +1010,7 @@ class BaseROS2DeviceNode(Node, Generic[T]):
                            ].call_async(
                                r
                            )  # type: ignore
-                            self.lab_logger().trace(f"确认资源云端 Update 结果: {response.response}")
+                            self.lab_logger().info(f"确认资源云端 Update 结果: {response.response}")
                        results.append(result)
                    elif action == "remove":
                        result = _handle_remove(resources_uuid)
--- a/unilabos/ros/nodes/presets/host_node.py
+++ b/unilabos/ros/nodes/presets/host_node.py
@@ -1195,7 +1195,7 @@ class HostNode(BaseROS2DeviceNode):
                self.lab_logger().info(f"[Host Node-Resource] UUID映射: {len(uuid_mapping)} 个节点")
            # 还需要加入到资源图中，暂不实现，考虑资源图新的获取方式
            response.response = json.dumps(uuid_mapping)
-            self.lab_logger().info(f"[Host Node-Resource] Resource tree update completed, success: {success}")
+            self.lab_logger().info(f"[Host Node-Resource] Resource tree add completed, success: {success}")
    async def _resource_tree_update_callback(self, request: SerialCommand_Request, response: SerialCommand_Response):
        """
--- a/unilabos/test/experiments/prcxi_9320_slim.json
+++ b/unilabos/test/experiments/prcxi_9320_slim.json
--- a/unilabos/test/experiments/xkc_sensor_test.json
+++ b/unilabos/test/experiments/xkc_sensor_test.json
@@ -1,29 +0,0 @@
 {
    "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": []
 }
--- a/unilabos/test/experiments/zdt_motor_test.json
+++ b/unilabos/test/experiments/zdt_motor_test.json
@@ -1,28 +0,0 @@
 {
    "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": []
 }
--- a/unilabos/workflow/init.py
+++ b/unilabos/workflow/init.py
--- a/unilabos/workflow/common.py
+++ b/unilabos/workflow/common.py
@@ -26,7 +26,7 @@
    res_id: plate_slot_{slot}
    device_id: /PRCXI
    class_name: PRCXI_BioER_96_wellplate
-    parent: /PRCXI/PRCXI_Deck
+    parent: /PRCXI/PRCXI_Deck/T{slot}
    slot_on_deck: "{slot}"
 - 输出端口: labware（用于连接 set_liquid_from_plate）
 - 控制流: create_resource 之间通过 ready 端口串联
@@ -122,7 +122,7 @@ NODE_TYPE_DEFAULT = "ILab"  # 所有节点的默认类型
 # create_resource 节点默认参数
 CREATE_RESOURCE_DEFAULTS = {
    "device_id": "/PRCXI",
-    "parent_template": "/PRCXI/PRCXI_Deck",
+    "parent_template": "/PRCXI/PRCXI_Deck/T{slot}",  # {slot} 会被替换为实际的 slot 值
    "class_name": "PRCXI_BioER_96_wellplate",
 }
@@ -424,7 +424,7 @@ def build_protocol_graph(
                "res_id": res_id,
                "device_id": CREATE_RESOURCE_DEFAULTS["device_id"],
                "class_name": lw_type,
-                "parent": CREATE_RESOURCE_DEFAULTS["parent_template"],
+                "parent": CREATE_RESOURCE_DEFAULTS["parent_template"].format(slot=slot),
                "bind_locations": {"x": 0.0, "y": 0.0, "z": 0.0},
                "slot_on_deck": slot,
            },
--- a/unilabos/workflow/from_python_script.py
+++ b/unilabos/workflow/from_python_script.py
@@ -1,241 +0,0 @@
 import ast
 import json
 from typing import Dict, List, Any, Tuple, Optional
 from .common import WorkflowGraph, RegistryAdapter
 Json = Dict[str, Any]
 # ---------------- Converter ----------------
 class DeviceMethodConverter:
    """
    - 字段统一：resource_name（原 device_class）、template_name（原 action_key）
    - params 单层；inputs 使用 'params.' 前缀
    - SimpleGraph.add_workflow_node 负责变量连线与边
    """
    def __init__(self, device_registry: Optional[Dict[str, Any]] = None):
        self.graph = WorkflowGraph()
        self.variable_sources: Dict[str, Dict[str, Any]] = {}        # var -> {node_id, output_name}
        self.instance_to_resource: Dict[str, Optional[str]] = {}     # 实例名 -> resource_name
        self.node_id_counter: int = 0
        self.registry = RegistryAdapter(device_registry or {})
    # ---- helpers ----
    def _new_node_id(self) -> int:
        nid = self.node_id_counter
        self.node_id_counter += 1
        return nid
    def _assign_targets(self, targets) -> List[str]:
        names: List[str] = []
        import ast
        if isinstance(targets, ast.Tuple):
            for elt in targets.elts:
                if isinstance(elt, ast.Name):
                    names.append(elt.id)
        elif isinstance(targets, ast.Name):
            names.append(targets.id)
        return names
    def _extract_device_instantiation(self, node) -> Optional[Tuple[str, str]]:
        import ast
        if not isinstance(node.value, ast.Call):
            return None
        callee = node.value.func
        if isinstance(callee, ast.Name):
            class_name = callee.id
        elif isinstance(callee, ast.Attribute) and isinstance(callee.value, ast.Name):
            class_name = callee.attr
        else:
            return None
        if isinstance(node.targets[0], ast.Name):
            instance = node.targets[0].id
            return instance, class_name
        return None
    def _extract_call(self, call) -> Tuple[str, str, Dict[str, Any], str]:
        import ast
        owner_name, method_name, call_kind = "", "", "func"
        if isinstance(call.func, ast.Attribute):
            method_name = call.func.attr
            if isinstance(call.func.value, ast.Name):
                owner_name = call.func.value.id
                call_kind = "instance" if owner_name in self.instance_to_resource else "class_or_module"
            elif isinstance(call.func.value, ast.Attribute) and isinstance(call.func.value.value, ast.Name):
                owner_name = call.func.value.attr
                call_kind = "class_or_module"
        elif isinstance(call.func, ast.Name):
            method_name = call.func.id
            call_kind = "func"
        def pack(node):
            if isinstance(node, ast.Name):
                return {"type": "variable", "value": node.id}
            if isinstance(node, ast.Constant):
                return {"type": "constant", "value": node.value}
            if isinstance(node, ast.Dict):
                return {"type": "dict", "value": self._parse_dict(node)}
            if isinstance(node, ast.List):
                return {"type": "list", "value": self._parse_list(node)}
            return {"type": "raw", "value": ast.unparse(node) if hasattr(ast, "unparse") else str(node)}
        args: Dict[str, Any] = {}
        pos: List[Any] = []
        for a in call.args:
            pos.append(pack(a))
        for kw in call.keywords:
            args[kw.arg] = pack(kw.value)
        if pos:
            args["_positional"] = pos
        return owner_name, method_name, args, call_kind
    def _parse_dict(self, node) -> Dict[str, Any]:
        import ast
        out: Dict[str, Any] = {}
        for k, v in zip(node.keys, node.values):
            if isinstance(k, ast.Constant):
                key = str(k.value)
                if isinstance(v, ast.Name):
                    out[key] = f"var:{v.id}"
                elif isinstance(v, ast.Constant):
                    out[key] = v.value
                elif isinstance(v, ast.Dict):
                    out[key] = self._parse_dict(v)
                elif isinstance(v, ast.List):
                    out[key] = self._parse_list(v)
        return out
    def _parse_list(self, node) -> List[Any]:
        import ast
        out: List[Any] = []
        for elt in node.elts:
            if isinstance(elt, ast.Name):
                out.append(f"var:{elt.id}")
            elif isinstance(elt, ast.Constant):
                out.append(elt.value)
            elif isinstance(elt, ast.Dict):
                out.append(self._parse_dict(elt))
            elif isinstance(elt, ast.List):
                out.append(self._parse_list(elt))
        return out
    def _normalize_var_tokens(self, x: Any) -> Any:
        if isinstance(x, str) and x.startswith("var:"):
            return {"__var__": x[4:]}
        if isinstance(x, list):
            return [self._normalize_var_tokens(i) for i in x]
        if isinstance(x, dict):
            return {k: self._normalize_var_tokens(v) for k, v in x.items()}
        return x
    def _make_params_payload(self, resource_name: Optional[str], template_name: str, call_args: Dict[str, Any]) -> Dict[str, Any]:
        input_keys = self.registry.get_action_input_keys(resource_name, template_name) if resource_name else []
        defaults = self.registry.get_action_goal_default(resource_name, template_name) if resource_name else {}
        params: Dict[str, Any] = dict(defaults)
        def unpack(p):
            t, v = p.get("type"), p.get("value")
            if t == "variable":
                return {"__var__": v}
            if t == "dict":
                return self._normalize_var_tokens(v)
            if t == "list":
                return self._normalize_var_tokens(v)
            return v
        for k, p in call_args.items():
            if k == "_positional":
                continue
            params[k] = unpack(p)
        pos = call_args.get("_positional", [])
        if pos:
            if input_keys:
                for i, p in enumerate(pos):
                    if i >= len(input_keys):
                        break
                    name = input_keys[i]
                    if name in params:
                        continue
                    params[name] = unpack(p)
            else:
                for i, p in enumerate(pos):
                    params[f"arg_{i}"] = unpack(p)
        return params
    # ---- handlers ----
    def _on_assign(self, stmt):
        import ast
        inst = self._extract_device_instantiation(stmt)
        if inst:
            instance, code_class = inst
            resource_name = self.registry.resolve_resource_by_classname(code_class)
            self.instance_to_resource[instance] = resource_name
            return
        if isinstance(stmt.value, ast.Call):
            owner, method, call_args, kind = self._extract_call(stmt.value)
            if kind == "instance":
                device_key = owner
                resource_name = self.instance_to_resource.get(owner)
            else:
                device_key = owner
                resource_name = self.registry.resolve_resource_by_classname(owner)
            module = self.registry.get_device_module(resource_name)
            params = self._make_params_payload(resource_name, method, call_args)
            nid = self._new_node_id()
            self.graph.add_workflow_node(
                nid,
                device_key=device_key,
                resource_name=resource_name,      # ✅
                module=module,
                template_name=method,             # ✅
                params=params,
                variable_sources=self.variable_sources,
                add_ready_if_no_vars=True,
                prev_node_id=(nid - 1) if nid > 0 else None,
            )
            out_vars = self._assign_targets(stmt.targets[0])
            for var in out_vars:
                self.variable_sources[var] = {"node_id": nid, "output_name": "result"}
    def _on_expr(self, stmt):
        import ast
        if not isinstance(stmt.value, ast.Call):
            return
        owner, method, call_args, kind = self._extract_call(stmt.value)
        if kind == "instance":
            device_key = owner
            resource_name = self.instance_to_resource.get(owner)
        else:
            device_key = owner
            resource_name = self.registry.resolve_resource_by_classname(owner)
        module = self.registry.get_device_module(resource_name)
        params = self._make_params_payload(resource_name, method, call_args)
        nid = self._new_node_id()
        self.graph.add_workflow_node(
            nid,
            device_key=device_key,
            resource_name=resource_name,      # ✅
            module=module,
            template_name=method,             # ✅
            params=params,
            variable_sources=self.variable_sources,
            add_ready_if_no_vars=True,
            prev_node_id=(nid - 1) if nid > 0 else None,
        )
    def convert(self, python_code: str):
        tree = ast.parse(python_code)
        for stmt in tree.body:
            if isinstance(stmt, ast.Assign):
                self._on_assign(stmt)
            elif isinstance(stmt, ast.Expr):
                self._on_expr(stmt)
        return self
--- a/unilabos/workflow/from_xdl.py
+++ b/unilabos/workflow/from_xdl.py
@@ -1,131 +0,0 @@
 from typing import List, Any, Dict
 import xml.etree.ElementTree as ET
 def convert_to_type(val: str) -> Any:
    """将字符串值转换为适当的数据类型"""
    if val == "True":
        return True
    if val == "False":
        return False
    if val == "?":
        return None
    if val.endswith(" g"):
        return float(val.split(" ")[0])
    if val.endswith("mg"):
        return float(val.split("mg")[0])
    elif val.endswith("mmol"):
        return float(val.split("mmol")[0]) / 1000
    elif val.endswith("mol"):
        return float(val.split("mol")[0])
    elif val.endswith("ml"):
        return float(val.split("ml")[0])
    elif val.endswith("RPM"):
        return float(val.split("RPM")[0])
    elif val.endswith(" °C"):
        return float(val.split(" ")[0])
    elif val.endswith(" %"):
        return float(val.split(" ")[0])
    return val
 def flatten_xdl_procedure(procedure_elem: ET.Element) -> List[ET.Element]:
    """展平嵌套的XDL程序结构"""
    flattened_operations = []
    TEMP_UNSUPPORTED_PROTOCOL = ["Purge", "Wait", "Stir", "ResetHandling"]
    def extract_operations(element: ET.Element):
        if element.tag not in ["Prep", "Reaction", "Workup", "Purification", "Procedure"]:
            if element.tag not in TEMP_UNSUPPORTED_PROTOCOL:
                flattened_operations.append(element)
        for child in element:
            extract_operations(child)
    for child in procedure_elem:
        extract_operations(child)
    return flattened_operations
 def parse_xdl_content(xdl_content: str) -> tuple:
    """解析XDL内容"""
    try:
        xdl_content_cleaned = "".join(c for c in xdl_content if c.isprintable())
        root = ET.fromstring(xdl_content_cleaned)
        synthesis_elem = root.find("Synthesis")
        if synthesis_elem is None:
            return None, None, None
        # 解析硬件组件
        hardware_elem = synthesis_elem.find("Hardware")
        hardware = []
        if hardware_elem is not None:
            hardware = [{"id": c.get("id"), "type": c.get("type")} for c in hardware_elem.findall("Component")]
        # 解析试剂
        reagents_elem = synthesis_elem.find("Reagents")
        reagents = []
        if reagents_elem is not None:
            reagents = [{"name": r.get("name"), "role": r.get("role", "")} for r in reagents_elem.findall("Reagent")]
        # 解析程序
        procedure_elem = synthesis_elem.find("Procedure")
        if procedure_elem is None:
            return None, None, None
        flattened_operations = flatten_xdl_procedure(procedure_elem)
        return hardware, reagents, flattened_operations
    except ET.ParseError as e:
        raise ValueError(f"Invalid XDL format: {e}")
 def convert_xdl_to_dict(xdl_content: str) -> Dict[str, Any]:
    """
    将XDL XML格式转换为标准的字典格式
    Args:
        xdl_content: XDL XML内容
    Returns:
        转换结果，包含步骤和器材信息
    """
    try:
        hardware, reagents, flattened_operations = parse_xdl_content(xdl_content)
        if hardware is None:
            return {"error": "Failed to parse XDL content", "success": False}
        # 将XDL元素转换为字典格式
        steps_data = []
        for elem in flattened_operations:
            # 转换参数类型
            parameters = {}
            for key, val in elem.attrib.items():
                converted_val = convert_to_type(val)
                if converted_val is not None:
                    parameters[key] = converted_val
            step_dict = {
                "operation": elem.tag,
                "parameters": parameters,
                "description": elem.get("purpose", f"Operation: {elem.tag}"),
            }
            steps_data.append(step_dict)
        # 合并硬件和试剂为统一的labware_info格式
        labware_data = []
        labware_data.extend({"id": hw["id"], "type": "hardware", **hw} for hw in hardware)
        labware_data.extend({"name": reagent["name"], "type": "reagent", **reagent} for reagent in reagents)
        return {
            "success": True,
            "steps": steps_data,
            "labware": labware_data,
            "message": f"Successfully converted XDL to dict format. Found {len(steps_data)} steps and {len(labware_data)} labware items.",
        }
    except Exception as e:
        error_msg = f"XDL conversion failed: {str(e)}"
        return {"error": error_msg, "success": False}