Merge remote-tracking branch 'origin/dev' into feature/organic-extraction

add open_timeout parameter to websocket connection
add TimeoutError and InvalidStatus exception handling
implement exponential backoff for reconnection attempts
simplify reconnection logic flow

.conda/base/recipe.yaml

@@ -0,0 +1,62 @@
+# unilabos: Production package (depends on unilabos-env + pip unilabos)
+# For production deployment
+
+package:
+  name: unilabos
+  version: 0.10.18
+
+source:
+  path: ../../unilabos
+  target_directory: unilabos
+
+build:
+  python:
+    entry_points:
+    - unilab = unilabos.app.main:main
+  script:
+  - set PIP_NO_INDEX=
+  - if: win
+    then:
+    - copy %RECIPE_DIR%\..\..\MANIFEST.in %SRC_DIR%
+    - copy %RECIPE_DIR%\..\..\setup.cfg %SRC_DIR%
+    - copy %RECIPE_DIR%\..\..\setup.py %SRC_DIR%
+    - pip install %SRC_DIR%
+  - if: unix
+    then:
+    - cp $RECIPE_DIR/../../MANIFEST.in $SRC_DIR
+    - cp $RECIPE_DIR/../../setup.cfg $SRC_DIR
+    - cp $RECIPE_DIR/../../setup.py $SRC_DIR
+    - pip install $SRC_DIR
+
+requirements:
+  host:
+  - python ==3.11.14
+  - pip
+  - setuptools
+  - zstd
+  - zstandard
+  run:
+  - zstd
+  - zstandard
+  - networkx
+  - typing_extensions
+  - websockets
+  - pint
+  - fastapi
+  - jinja2
+  - requests
+  - uvicorn
+  - if: not osx
+    then:
+    - opcua
+  - pyserial
+  - pandas
+  - pymodbus
+  - matplotlib
+  - pylibftdi
+  - uni-lab::unilabos-env ==0.10.18
+
+about:
+  repository: https://github.com/deepmodeling/Uni-Lab-OS
+  license: GPL-3.0-only
+  description: "UniLabOS - Production package with minimal ROS2 dependencies"

.conda/environment/recipe.yaml

@@ -0,0 +1,39 @@
+# unilabos-env: conda environment dependencies (ROS2 + conda packages)
+
+package:
+  name: unilabos-env
+  version: 0.10.18
+
+build:
+  noarch: generic
+
+requirements:
+  run:
+  # Python
+  - zstd
+  - zstandard
+  - conda-forge::python ==3.11.14
+  - conda-forge::opencv
+  # ROS2 dependencies (from ci-check.yml)
+  - robostack-staging::ros-humble-ros-core
+  - robostack-staging::ros-humble-action-msgs
+  - robostack-staging::ros-humble-std-msgs
+  - robostack-staging::ros-humble-geometry-msgs
+  - robostack-staging::ros-humble-control-msgs
+  - robostack-staging::ros-humble-nav2-msgs
+  - robostack-staging::ros-humble-cv-bridge
+  - robostack-staging::ros-humble-vision-opencv
+  - robostack-staging::ros-humble-tf-transformations
+  - robostack-staging::ros-humble-moveit-msgs
+  - robostack-staging::ros-humble-tf2-ros
+  - robostack-staging::ros-humble-tf2-ros-py
+  - conda-forge::transforms3d
+  - conda-forge::uv
+
+  # UniLabOS custom messages
+  - uni-lab::ros-humble-unilabos-msgs
+
+about:
+  repository: https://github.com/deepmodeling/Uni-Lab-OS
+  license: GPL-3.0-only
+  description: "UniLabOS Environment - ROS2 and conda dependencies"

.conda/full/recipe.yaml

@@ -0,0 +1,42 @@
+# unilabos-full: Full package with all features
+# Depends on unilabos + complete ROS2 desktop + dev tools
+
+package:
+  name: unilabos-full
+  version: 0.10.18
+
+build:
+  noarch: generic
+
+requirements:
+  run:
+  # Base unilabos package (includes unilabos-env)
+  - uni-lab::unilabos ==0.10.18
+  # Documentation tools
+  - sphinx
+  - sphinx_rtd_theme
+  # Web UI
+  - gradio
+  - flask
+  # Interactive development
+  - ipython
+  - jupyter
+  - jupyros
+  - colcon-common-extensions
+  # ROS2 full desktop (includes rviz2, gazebo, etc.)
+  - robostack-staging::ros-humble-desktop-full
+  # Navigation and motion control
+  - ros-humble-navigation2
+  - ros-humble-ros2-control
+  - ros-humble-robot-state-publisher
+  - ros-humble-joint-state-publisher
+  # MoveIt motion planning
+  - ros-humble-moveit
+  - ros-humble-moveit-servo
+  # Simulation
+  - ros-humble-simulation
+
+about:
+  repository: https://github.com/deepmodeling/Uni-Lab-OS
+  license: GPL-3.0-only
+  description: "UniLabOS Full - Complete package with ROS2 Desktop, MoveIt, Navigation2, Gazebo, Jupyter"

.conda/recipe.yaml

@@ -1,92 +0,0 @@
-package:
-  name: unilabos
-  version: 0.10.13
-
-source:
-  path: ../unilabos
-  target_directory: unilabos
-
-build:
-  python:
-    entry_points:
-     - unilab = unilabos.app.main:main
-  script:
-  - set PIP_NO_INDEX=
-  - if: win
-    then:
-    - copy %RECIPE_DIR%\..\MANIFEST.in %SRC_DIR%
-    - copy %RECIPE_DIR%\..\setup.cfg %SRC_DIR%
-    - copy %RECIPE_DIR%\..\setup.py %SRC_DIR%
-    - call %PYTHON% -m pip install %SRC_DIR%
-  - if: unix
-    then:
-    - cp $RECIPE_DIR/../MANIFEST.in $SRC_DIR
-    - cp $RECIPE_DIR/../setup.cfg $SRC_DIR
-    - cp $RECIPE_DIR/../setup.py $SRC_DIR
-    - $PYTHON -m pip install $SRC_DIR
-
-
-requirements:
-  host:
-  - python ==3.11.11
-  - pip
-  - setuptools
-  - zstd
-  - zstandard
-  run:
-  - conda-forge::python ==3.11.11
-  - compilers
-  - cmake
-  - zstd
-  - zstandard
-  - ninja
-  - if: unix
-    then:
-    - make
-  - sphinx
-  - sphinx_rtd_theme
-  - numpy
-  - scipy
-  - pandas
-  - networkx
-  - matplotlib
-  - pint
-  - pyserial
-  - pyusb
-  - pylibftdi
-  - pymodbus
-  - python-can
-  - pyvisa
-  - opencv
-  - pydantic
-  - fastapi
-  - uvicorn
-  - gradio
-  - flask
-  - websockets
-  - ipython
-  - jupyter
-  - jupyros
-  - colcon-common-extensions
-  - robostack-staging::ros-humble-desktop-full
-  - robostack-staging::ros-humble-control-msgs
-  - robostack-staging::ros-humble-sensor-msgs
-  - robostack-staging::ros-humble-trajectory-msgs
-  - ros-humble-navigation2
-  - ros-humble-ros2-control
-  - ros-humble-robot-state-publisher
-  - ros-humble-joint-state-publisher
-  - ros-humble-rosbridge-server
-  - ros-humble-cv-bridge
-  - ros-humble-tf2
-  - ros-humble-moveit
-  - ros-humble-moveit-servo
-  - ros-humble-simulation
-  - ros-humble-tf-transformations
-  - transforms3d
-  - uni-lab::ros-humble-unilabos-msgs
-
-about:
-  repository: https://github.com/dptech-corp/Uni-Lab-OS
-  license: GPL-3.0-only
-  description: "Uni-Lab-OS"

.conda/scripts/post-link.bat

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

.conda/scripts/post-link.sh

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

.cursor/rules/device-drivers.mdc

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

.cursor/rules/protocol-development.mdc

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

.cursor/rules/registry-config.mdc

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

.cursor/rules/ros-integration.mdc

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

.cursor/rules/testing-patterns.mdc

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

.cursor/rules/unilabos-project.mdc

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

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

@@ -0,0 +1,24 @@
+---
+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 搜索仓库中的最新注册表；指南中的「现有设备接口快照」作为兜底参考 |

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

@@ -0,0 +1,323 @@
+---
+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` |

.cursor/skills/add-protocol/reference.md

@@ -0,0 +1,207 @@
+# 协议高级参考
+
+本文件是 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` |

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

@@ -0,0 +1,371 @@
+---
+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` |

.cursor/skills/add-resource/reference.md

@@ -0,0 +1,292 @@
+# 资源高级参考
+
+本文件是 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` |

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

@@ -0,0 +1,500 @@
+---
+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`

.cursor/skills/add-workstation/reference.md

@@ -0,0 +1,371 @@
+# 工作站高级模式参考
+
+本文件是 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)
+```

.cursor/skills/edit-experiment-graph/SKILL.md

@@ -0,0 +1,381 @@
+---
+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` |

.cursor/skills/edit-experiment-graph/reference.md

@@ -0,0 +1,255 @@
+# 实验图高级参考
+
+本文件是 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` |

.cursorignore

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

.github/copilot-instructions.md

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

.github/dependabot.yml

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

.github/workflows/ci-check.yml

@@ -0,0 +1,67 @@
+name: CI Check
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  registry-check:
+    runs-on: windows-latest
+
+    env:
+      # Fix Unicode encoding issue on Windows runner (cp1252 -> utf-8)
+      PYTHONIOENCODING: utf-8
+      PYTHONUTF8: 1
+
+    defaults:
+      run:
+        shell: cmd
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Miniforge
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          use-mamba: true
+          channels: robostack-staging,conda-forge,uni-lab
+          channel-priority: flexible
+          activate-environment: check-env
+          auto-update-conda: false
+          show-channel-urls: true
+
+      - name: Install ROS dependencies, uv and unilabos-msgs
+        run: |
+          echo Installing ROS dependencies...
+          mamba install -n check-env conda-forge::uv conda-forge::opencv robostack-staging::ros-humble-ros-core robostack-staging::ros-humble-action-msgs robostack-staging::ros-humble-std-msgs robostack-staging::ros-humble-geometry-msgs robostack-staging::ros-humble-control-msgs robostack-staging::ros-humble-nav2-msgs uni-lab::ros-humble-unilabos-msgs robostack-staging::ros-humble-cv-bridge robostack-staging::ros-humble-vision-opencv robostack-staging::ros-humble-tf-transformations robostack-staging::ros-humble-moveit-msgs robostack-staging::ros-humble-tf2-ros robostack-staging::ros-humble-tf2-ros-py conda-forge::transforms3d -c robostack-staging -c conda-forge -c uni-lab -y
+
+      - name: Install pip dependencies and unilabos
+        run: |
+          call conda activate check-env
+          echo Installing pip dependencies...
+          uv pip install -r unilabos/utils/requirements.txt
+          uv pip install pywinauto git+https://github.com/Xuwznln/pylabrobot.git
+          uv pip uninstall enum34 || echo enum34 not installed, skipping
+          uv pip install .
+
+      - name: Run check mode (complete_registry)
+        run: |
+          call conda activate check-env
+          echo Running check mode...
+          python -m unilabos --check_mode --skip_env_check
+
+      - name: Check for uncommitted changes
+        shell: bash
+        run: |
+          if ! git diff --exit-code; then
+            echo "::error::检测到文件变化！请先在本地运行 'python -m unilabos --complete_registry' 并提交变更"
+            echo "变化的文件:"
+            git diff --name-only
+            exit 1
+          fi
+          echo "检查通过：无文件变化"

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

@@ -13,6 +13,11 @@ on:
         required: false
         default: 'win-64'
         type: string
+      build_full:
+        description: '是否构建完整版 unilabos-full (默认构建轻量版 unilabos)'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
   build-conda-pack:
@@ -24,7 +29,7 @@ jobs:
             platform: linux-64
             env_file: unilabos-linux-64.yaml
             script_ext: sh
-          - os: macos-13 # Intel
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
             env_file: unilabos-osx-64.yaml
             script_ext: sh
@@ -57,7 +62,7 @@ jobs:
             echo "should_build=false" >> $GITHUB_OUTPUT
           fi
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: steps.should_build.outputs.should_build == 'true'
         with:
           ref: ${{ github.event.inputs.branch }}
@@ -69,7 +74,7 @@ jobs:
         with:
           miniforge-version: latest
           use-mamba: true
-          python-version: '3.11.11'
+          python-version: '3.11.14'
           channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: flexible
           activate-environment: unilab
@@ -81,7 +86,14 @@ jobs:
         run: |
           echo Installing unilabos and dependencies to unilab environment...
           echo Using mamba for faster and more reliable dependency resolution...
-          mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          echo Build full: ${{ github.event.inputs.build_full }}
+          if "${{ github.event.inputs.build_full }}"=="true" (
+            echo Installing unilabos-full ^(complete package^)...
+            mamba install -n unilab uni-lab::unilabos-full conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          ) else (
+            echo Installing unilabos ^(minimal package^)...
+            mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          )
 
       - name: Install conda-pack, unilabos and dependencies (Unix)
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform != 'win-64'
@@ -89,7 +101,14 @@ jobs:
         run: |
           echo "Installing unilabos and dependencies to unilab environment..."
           echo "Using mamba for faster and more reliable dependency resolution..."
-          mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          echo "Build full: ${{ github.event.inputs.build_full }}"
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
+            echo "Installing unilabos-full (complete package)..."
+            mamba install -n unilab uni-lab::unilabos-full conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          else
+            echo "Installing unilabos (minimal package)..."
+            mamba install -n unilab uni-lab::unilabos conda-pack -c uni-lab -c robostack-staging -c conda-forge -y
+          fi
 
       - name: Get latest ros-humble-unilabos-msgs version (Windows)
         if: steps.should_build.outputs.should_build == 'true' && matrix.platform == 'win-64'
@@ -293,7 +312,7 @@ jobs:
 
       - name: Upload distribution package
         if: steps.should_build.outputs.should_build == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: unilab-pack-${{ matrix.platform }}-${{ github.event.inputs.branch }}
           path: dist-package/
@@ -308,7 +327,12 @@ jobs:
           echo ==========================================
           echo Platform: ${{ matrix.platform }}
           echo Branch: ${{ github.event.inputs.branch }}
-          echo Python version: 3.11.11
+          echo Python version: 3.11.14
+          if "${{ github.event.inputs.build_full }}"=="true" (
+            echo Package: unilabos-full ^(complete^)
+          ) else (
+            echo Package: unilabos ^(minimal^)
+          )
           echo.
           echo Distribution package contents:
           dir dist-package
@@ -328,7 +352,12 @@ jobs:
           echo "=========================================="
           echo "Platform: ${{ matrix.platform }}"
           echo "Branch: ${{ github.event.inputs.branch }}"
-          echo "Python version: 3.11.11"
+          echo "Python version: 3.11.14"
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
+            echo "Package: unilabos-full (complete)"
+          else
+            echo "Package: unilabos (minimal)"
+          fi
           echo ""
           echo "Distribution package contents:"
           ls -lh dist-package/

.github/workflows/deploy-docs.yml

@@ -1,10 +1,12 @@
 name: Deploy Docs
 
 on:
-  push:
-    branches: [main]
-  pull_request:
+  # 在 CI Check 成功后自动触发（仅 main 分支）
+  workflow_run:
+    workflows: ["CI Check"]
+    types: [completed]
     branches: [main]
+  # 手动触发
   workflow_dispatch:
     inputs:
       branch:
@@ -33,12 +35,19 @@ concurrency:
 jobs:
   # Build documentation
   build:
+    # 只在以下情况运行：
+    # 1. workflow_run 触发且 CI Check 成功
+    # 2. 手动触发
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.inputs.branch || github.ref }}
+          # workflow_run 时使用触发工作流的分支，手动触发时使用输入的分支
+          ref: ${{ github.event.workflow_run.head_branch || github.event.inputs.branch || github.ref }}
           fetch-depth: 0
 
       - name: Setup Miniforge (with mamba)
@@ -46,7 +55,7 @@ jobs:
         with:
           miniforge-version: latest
           use-mamba: true
-          python-version: '3.11.11'
+          python-version: '3.11.14'
           channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: flexible
           activate-environment: unilab
@@ -75,8 +84,10 @@ jobs:
 
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v4
-        if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+        uses: actions/configure-pages@v5
+        if: |
+          github.event.workflow_run.head_branch == 'main' ||
+          (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
 
       - name: Build Sphinx documentation
         run: |
@@ -94,14 +105,18 @@ jobs:
           test -f docs/_build/html/index.html && echo "✓ index.html exists" || echo "✗ index.html missing"
 
       - name: Upload build artifacts
-        uses: actions/upload-pages-artifact@v3
-        if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+        uses: actions/upload-pages-artifact@v4
+        if: |
+          github.event.workflow_run.head_branch == 'main' ||
+          (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
         with:
           path: docs/_build/html
 
   # Deploy to GitHub Pages
   deploy:
-    if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+    if: |
+      github.event.workflow_run.head_branch == 'main' ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

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

@@ -1,11 +1,16 @@
 name: Multi-Platform Conda Build
 
 on:
+  # 在 CI Check 工作流完成后触发（仅限 main/dev 分支）
+  workflow_run:
+    workflows: ["CI Check"]
+    types:
+      - completed
+    branches: [main, dev]
+  # 支持 tag 推送（不依赖 CI Check）
   push:
-    branches: [main, dev]
     tags: ['v*']
-  pull_request:
-    branches: [main, dev]
+  # 手动触发
   workflow_dispatch:
     inputs:
       platforms:
@@ -17,9 +22,37 @@ on:
         required: false
         default: false
         type: boolean
+      skip_ci_check:
+        description: '跳过等待 CI Check (手动触发时可选)'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
+  # 等待 CI Check 完成的 job (仅用于 workflow_run 触发)
+  wait-for-ci:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_run'
+    outputs:
+      should_continue: ${{ steps.check.outputs.should_continue }}
+    steps:
+      - name: Check CI status
+        id: check
+        run: |
+          if [[ "${{ github.event.workflow_run.conclusion }}" == "success" ]]; then
+            echo "should_continue=true" >> $GITHUB_OUTPUT
+            echo "CI Check passed, proceeding with build"
+          else
+            echo "should_continue=false" >> $GITHUB_OUTPUT
+            echo "CI Check did not succeed (status: ${{ github.event.workflow_run.conclusion }}), skipping build"
+          fi
+
   build:
+    needs: [wait-for-ci]
+    # 运行条件：workflow_run 触发且 CI 成功，或者其他触发方式
+    if: |
+      always() &&
+      (needs.wait-for-ci.result == 'skipped' || needs.wait-for-ci.outputs.should_continue == 'true')
     strategy:
       fail-fast: false
       matrix:
@@ -27,7 +60,7 @@ jobs:
           - os: ubuntu-latest
             platform: linux-64
             env_file: unilabos-linux-64.yaml
-          - os: macos-13 # Intel
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
             env_file: unilabos-osx-64.yaml
           - os: macos-latest # ARM64
@@ -44,8 +77,10 @@ jobs:
         shell: bash -l {0}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
+          # 如果是 workflow_run 触发，使用触发 CI Check 的 commit
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 0
 
       - name: Check if platform should be built
@@ -69,7 +104,6 @@ jobs:
           channels: conda-forge,robostack-staging,defaults
           channel-priority: strict
           activate-environment: build-env
-          auto-activate-base: false
           auto-update-conda: false
           show-channel-urls: true
 
@@ -115,7 +149,7 @@ jobs:
 
       - name: Upload conda package artifacts
         if: steps.should_build.outputs.should_build == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: conda-package-${{ matrix.platform }}
           path: conda-packages-temp

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

@@ -1,32 +1,69 @@
 name: UniLabOS Conda Build
 
 on:
+  # 在 CI Check 成功后自动触发
+  workflow_run:
+    workflows: ["CI Check"]
+    types: [completed]
+    branches: [main, dev]
+  # 标签推送时直接触发（发布版本）
   push:
-    branches: [main, dev]
     tags: ['v*']
-  pull_request:
-    branches: [main, dev]
+  # 手动触发
   workflow_dispatch:
     inputs:
       platforms:
         description: '选择构建平台 (逗号分隔): linux-64, osx-64, osx-arm64, win-64'
         required: false
         default: 'linux-64'
+      build_full:
+        description: '是否构建 unilabos-full 完整包 (默认只构建 unilabos 基础包)'
+        required: false
+        default: false
+        type: boolean
       upload_to_anaconda:
         description: '是否上传到Anaconda.org'
         required: false
         default: false
         type: boolean
+      skip_ci_check:
+        description: '跳过等待 CI Check (手动触发时可选)'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
+  # 等待 CI Check 完成的 job (仅用于 workflow_run 触发)
+  wait-for-ci:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_run'
+    outputs:
+      should_continue: ${{ steps.check.outputs.should_continue }}
+    steps:
+      - name: Check CI status
+        id: check
+        run: |
+          if [[ "${{ github.event.workflow_run.conclusion }}" == "success" ]]; then
+            echo "should_continue=true" >> $GITHUB_OUTPUT
+            echo "CI Check passed, proceeding with build"
+          else
+            echo "should_continue=false" >> $GITHUB_OUTPUT
+            echo "CI Check did not succeed (status: ${{ github.event.workflow_run.conclusion }}), skipping build"
+          fi
+
   build:
+    needs: [wait-for-ci]
+    # 运行条件：workflow_run 触发且 CI 成功，或者其他触发方式
+    if: |
+      always() &&
+      (needs.wait-for-ci.result == 'skipped' || needs.wait-for-ci.outputs.should_continue == 'true')
     strategy:
       fail-fast: false
       matrix:
         include:
           - os: ubuntu-latest
             platform: linux-64
-          - os: macos-13 # Intel
+          - os: macos-15 # Intel (via Rosetta)
             platform: osx-64
           - os: macos-latest # ARM64
             platform: osx-arm64
@@ -40,8 +77,10 @@ jobs:
         shell: bash -l {0}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
+          # 如果是 workflow_run 触发，使用触发 CI Check 的 commit
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 0
 
       - name: Check if platform should be built
@@ -65,7 +104,6 @@ jobs:
           channels: conda-forge,robostack-staging,uni-lab,defaults
           channel-priority: strict
           activate-environment: build-env
-          auto-activate-base: false
           auto-update-conda: false
           show-channel-urls: true
 
@@ -81,12 +119,61 @@ jobs:
           conda list | grep -E "(rattler-build|anaconda-client)"
           echo "Platform: ${{ matrix.platform }}"
           echo "OS: ${{ matrix.os }}"
-          echo "Building UniLabOS package"
+          echo "Build full package: ${{ github.event.inputs.build_full || 'false' }}"
+          echo "Building packages:"
+          echo "  - unilabos-env (environment dependencies)"
+          echo "  - unilabos (with pip package)"
+          if [[ "${{ github.event.inputs.build_full }}" == "true" ]]; then
+            echo "  - unilabos-full (complete package)"
+          fi
 
-      - name: Build conda package
+      - name: Build unilabos-env (conda environment only, noarch)
         if: steps.should_build.outputs.should_build == 'true'
         run: |
-          rattler-build build -r .conda/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge
+          echo "Building unilabos-env (conda environment dependencies)..."
+          rattler-build build -r .conda/environment/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge
+
+      - name: Upload unilabos-env to Anaconda.org (if enabled)
+        if: steps.should_build.outputs.should_build == 'true' && github.event.inputs.upload_to_anaconda == 'true'
+        run: |
+          echo "Uploading unilabos-env to uni-lab organization..."
+          for package in $(find ./output -name "unilabos-env*.conda"); do
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+          done
+
+      - name: Build unilabos (with pip package)
+        if: steps.should_build.outputs.should_build == 'true'
+        run: |
+          echo "Building unilabos package..."
+          # 如果已上传到 Anaconda，从 uni-lab channel 获取 unilabos-env；否则从本地 output 获取
+          rattler-build build -r .conda/base/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge --channel ./output
+
+      - name: Upload unilabos to Anaconda.org (if enabled)
+        if: steps.should_build.outputs.should_build == 'true' && github.event.inputs.upload_to_anaconda == 'true'
+        run: |
+          echo "Uploading unilabos to uni-lab organization..."
+          for package in $(find ./output -name "unilabos-0*.conda" -o -name "unilabos-[0-9]*.conda"); do
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+          done
+
+      - name: Build unilabos-full - Only when explicitly requested
+        if: |
+          steps.should_build.outputs.should_build == 'true' && 
+          github.event.inputs.build_full == 'true'
+        run: |
+          echo "Building unilabos-full package on ${{ matrix.platform }}..."
+          rattler-build build -r .conda/full/recipe.yaml -c uni-lab -c robostack-staging -c conda-forge --channel ./output
+
+      - name: Upload unilabos-full to Anaconda.org (if enabled)
+        if: |
+          steps.should_build.outputs.should_build == 'true' && 
+          github.event.inputs.build_full == 'true' &&
+          github.event.inputs.upload_to_anaconda == 'true'
+        run: |
+          echo "Uploading unilabos-full to uni-lab organization..."
+          for package in $(find ./output -name "unilabos-full*.conda"); do
+            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
+          done
 
       - name: List built packages
         if: steps.should_build.outputs.should_build == 'true'
@@ -108,17 +195,9 @@ jobs:
 
       - name: Upload conda package artifacts
         if: steps.should_build.outputs.should_build == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: conda-package-unilabos-${{ matrix.platform }}
           path: conda-packages-temp
           if-no-files-found: warn
           retention-days: 30
-
-      - name: Upload to Anaconda.org (uni-lab organization)
-        if: github.event.inputs.upload_to_anaconda == 'true'
-        run: |
-          for package in $(find ./output -name "*.conda"); do
-            echo "Uploading $package to uni-lab organization..."
-            anaconda -t ${{ secrets.ANACONDA_API_TOKEN }} upload --user uni-lab --force "$package"
-          done

.gitignore

@@ -1,8 +1,10 @@
+cursor_docs/
 configs/
 temp/
 output/
 unilabos_data/
 pyrightconfig.json
+.cursorignore
 ## Python
 
 # Byte-compiled / optimized / DLL files

AGENTS.md

@@ -0,0 +1,21 @@
+# 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/`

CLAUDE.md

@@ -0,0 +1,14 @@
+# 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()`

MANIFEST.in

@@ -1,4 +1,5 @@
 recursive-include unilabos/test *
+recursive-include unilabos/utils *
 recursive-include unilabos/registry *.yaml
 recursive-include unilabos/app/web/static *
 recursive-include unilabos/app/web/templates *

NOTICE

@@ -0,0 +1,17 @@
+# Uni-Lab-OS Licensing Notice
+
+This project uses a dual licensing structure:
+
+## 1. Main Framework - GPL-3.0
+
+- unilabos/ (except unilabos/devices/)
+- docs/
+- tests/
+
+See [LICENSE](LICENSE) for details.
+
+## 2. Device Drivers - DP Technology Proprietary License
+
+- unilabos/devices/
+
+See [unilabos/devices/LICENSE](unilabos/devices/LICENSE) for details.

README.md

@@ -8,17 +8,13 @@
 
 **English** | [中文](README_zh.md)
 
-[![GitHub Stars](https://img.shields.io/github/stars/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/stargazers)
-[![GitHub Forks](https://img.shields.io/github/forks/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/network/members)
-[![GitHub Issues](https://img.shields.io/github/issues/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/issues)
-[![GitHub License](https://img.shields.io/github/license/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/network/members)
+[![GitHub Issues](https://img.shields.io/github/issues/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/issues)
+[![GitHub License](https://img.shields.io/github/license/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/blob/main/LICENSE)
 
 Uni-Lab-OS is a platform for laboratory automation, designed to connect and control various experimental equipment, enabling automation and standardization of experimental workflows.
 
-## 🏆 Competition
-
-Join the [Intelligent Organic Chemistry Synthesis Competition](https://bohrium.dp.tech/competitions/1451645258) to explore automated synthesis with Uni-Lab-OS!
-
 ## Key Features
 
 - Multi-device integration management
@@ -31,41 +27,89 @@ Join the [Intelligent Organic Chemistry Synthesis Competition](https://bohrium.d
 
 Detailed documentation can be found at:
 
-- [Online Documentation](https://xuwznln.github.io/Uni-Lab-OS-Doc/)
+- [Online Documentation](https://deepmodeling.github.io/Uni-Lab-OS/)
 
 ## Quick Start
 
-Uni-Lab-OS recommends using `mamba` for environment management. Choose the appropriate environment file for your operating system:
+### 1. Setup Conda Environment
+
+Uni-Lab-OS recommends using `mamba` for environment management. Choose the package that fits your needs:
+
+| Package | Use Case | Contents |
+|---------|----------|----------|
+| `unilabos` | **Recommended for most users** | Complete package, ready to use |
+| `unilabos-env` | Developers (editable install) | Environment only, install unilabos via pip |
+| `unilabos-full` | Simulation/Visualization | unilabos + ROS2 Desktop + Gazebo + MoveIt |
 
 ```bash
 # Create new environment
-mamba create -n unilab python=3.11.11
+mamba create -n unilab python=3.11.14
 mamba activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# Option A: Standard installation (recommended for most users)
+mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# Option B: For developers (editable mode development)
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+# Then install unilabos and dependencies:
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git && cd Uni-Lab-OS
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+
+# Option C: Full installation (simulation/visualization)
+mamba install uni-lab::unilabos-full -c robostack-staging -c conda-forge
 ```
 
-## Install Dev Uni-Lab-OS
+**When to use which?**
+- **unilabos**: Standard installation for production deployment and general usage (recommended)
+- **unilabos-env**: For developers who need `pip install -e .` editable mode, modify source code
+- **unilabos-full**: For simulation (Gazebo), visualization (rviz2), and Jupyter notebooks
+
+### 2. Clone Repository (Optional, for developers)
 
 ```bash
-# Clone the repository
-git clone https://github.com/dptech-corp/Uni-Lab-OS.git
+# Clone the repository (only needed for development or examples)
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
 cd Uni-Lab-OS
-
-# Install Uni-Lab-OS
-pip install .
 ```
 
-3. Start Uni-Lab System:
+3. Start Uni-Lab System
 
-Please refer to [Documentation - Boot Examples](https://xuwznln.github.io/Uni-Lab-OS-Doc/boot_examples/index.html)
+Please refer to [Documentation - Boot Examples](https://deepmodeling.github.io/Uni-Lab-OS/boot_examples/index.html)
+
+4. Best Practice
+
+See [Best Practice Guide](https://deepmodeling.github.io/Uni-Lab-OS/user_guide/best_practice.html)
 
 ## Message Format
 
-Uni-Lab-OS uses pre-built `unilabos_msgs` for system communication. You can find the built versions on the [GitHub Releases](https://github.com/dptech-corp/Uni-Lab-OS/releases) page.
+Uni-Lab-OS uses pre-built `unilabos_msgs` for system communication. You can find the built versions on the [GitHub Releases](https://github.com/deepmodeling/Uni-Lab-OS/releases) page.
+
+## Citation
+
+If you use [Uni-Lab-OS](https://arxiv.org/abs/2512.21766) in academic research, please cite:
+
+```bibtex
+@article{gao2025unilabos,
+    title = {UniLabOS: An AI-Native Operating System for Autonomous Laboratories},
+    doi = {10.48550/arXiv.2512.21766},
+    publisher = {arXiv},
+    author = {Gao, Jing and Chang, Junhan and Que, Haohui and Xiong, Yanfei and
+              Zhang, Shixiang and Qi, Xianwei and Liu, Zhen and Wang, Jun-Jie and
+              Ding, Qianjun and Li, Xinyu and Pan, Ziwei and Xie, Qiming and
+              Yan, Zhuang and Yan, Junchi and Zhang, Linfeng},
+    year = {2025}
+}
+```
 
 ## License
 
-This project is licensed under GPL-3.0 - see the [LICENSE](LICENSE) file for details.
+This project uses a dual licensing structure:
+
+- **Main Framework**: GPL-3.0 - see [LICENSE](LICENSE)
+- **Device Drivers** (`unilabos/devices/`): DP Technology Proprietary License
+
+See [NOTICE](NOTICE) for complete licensing details.
 
 ## Project Statistics
 
@@ -77,4 +121,4 @@ This project is licensed under GPL-3.0 - see the [LICENSE](LICENSE) file for det
 
 ## Contact Us
 
-- GitHub Issues: [https://github.com/dptech-corp/Uni-Lab-OS/issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- GitHub Issues: [https://github.com/deepmodeling/Uni-Lab-OS/issues](https://github.com/deepmodeling/Uni-Lab-OS/issues)

README_zh.md

@@ -8,17 +8,13 @@
 
 [English](README.md) | **中文**
 
-[![GitHub Stars](https://img.shields.io/github/stars/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/stargazers)
-[![GitHub Forks](https://img.shields.io/github/forks/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/network/members)
-[![GitHub Issues](https://img.shields.io/github/issues/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/issues)
-[![GitHub License](https://img.shields.io/github/license/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/network/members)
+[![GitHub Issues](https://img.shields.io/github/issues/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/issues)
+[![GitHub License](https://img.shields.io/github/license/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/blob/main/LICENSE)
 
 Uni-Lab-OS 是一个用于实验室自动化的综合平台，旨在连接和控制各种实验设备，实现实验流程的自动化和标准化。
 
-## 🏆 比赛
-
-欢迎参加[有机化学合成智能实验大赛](https://bohrium.dp.tech/competitions/1451645258)，使用 Uni-Lab-OS 探索自动化合成！
-
 ## 核心特点
 
 - 多设备集成管理
@@ -31,43 +27,89 @@ Uni-Lab-OS 是一个用于实验室自动化的综合平台，旨在连接和控
 
 详细文档可在以下位置找到:
 
-- [在线文档](https://xuwznln.github.io/Uni-Lab-OS-Doc/)
+- [在线文档](https://deepmodeling.github.io/Uni-Lab-OS/)
 
 ## 快速开始
 
-1. 配置 Conda 环境
+### 1. 配置 Conda 环境
 
-Uni-Lab-OS 建议使用 `mamba` 管理环境。根据您的操作系统选择适当的环境文件:
+Uni-Lab-OS 建议使用 `mamba` 管理环境。根据您的需求选择合适的安装包：
+
+| 安装包 | 适用场景 | 包含内容 |
+|--------|----------|----------|
+| `unilabos` | **推荐大多数用户** | 完整安装包，开箱即用 |
+| `unilabos-env` | 开发者（可编辑安装） | 仅环境依赖，通过 pip 安装 unilabos |
+| `unilabos-full` | 仿真/可视化 | unilabos + ROS2 桌面版 + Gazebo + MoveIt |
 
 ```bash
 # 创建新环境
-mamba create -n unilab python=3.11.11
+mamba create -n unilab python=3.11.14
 mamba activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# 方案 A：标准安装（推荐大多数用户）
+mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# 方案 B：开发者环境（可编辑模式开发）
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+# 然后安装 unilabos 和依赖：
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git && cd Uni-Lab-OS
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+
+# 方案 C：完整安装（仿真/可视化）
+mamba install uni-lab::unilabos-full -c robostack-staging -c conda-forge
 ```
 
-2. 安装开发版 Uni-Lab-OS:
+**如何选择？**
+- **unilabos**：标准安装，适用于生产部署和日常使用（推荐）
+- **unilabos-env**：开发者使用，支持 `pip install -e .` 可编辑模式，可修改源代码
+- **unilabos-full**：需要仿真（Gazebo）、可视化（rviz2）或 Jupyter Notebook
+
+### 2. 克隆仓库（可选，供开发者使用）
 
 ```bash
-# 克隆仓库
-git clone https://github.com/dptech-corp/Uni-Lab-OS.git
+# 克隆仓库（仅开发或查看示例时需要）
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
 cd Uni-Lab-OS
-
-# 安装 Uni-Lab-OS
-pip install .
 ```
 
-3. 启动 Uni-Lab 系统:
+3. 启动 Uni-Lab 系统
 
-请见[文档-启动样例](https://xuwznln.github.io/Uni-Lab-OS-Doc/boot_examples/index.html)
+请见[文档-启动样例](https://deepmodeling.github.io/Uni-Lab-OS/boot_examples/index.html)
+
+4. 最佳实践
+
+请见[最佳实践指南](https://deepmodeling.github.io/Uni-Lab-OS/user_guide/best_practice.html)
 
 ## 消息格式
 
-Uni-Lab-OS 使用预构建的 `unilabos_msgs` 进行系统通信。您可以在 [GitHub Releases](https://github.com/dptech-corp/Uni-Lab-OS/releases) 页面找到已构建的版本。
+Uni-Lab-OS 使用预构建的 `unilabos_msgs` 进行系统通信。您可以在 [GitHub Releases](https://github.com/deepmodeling/Uni-Lab-OS/releases) 页面找到已构建的版本。
+
+## 引用
+
+如果您在学术研究中使用 [Uni-Lab-OS](https://arxiv.org/abs/2512.21766)，请引用：
+
+```bibtex
+@article{gao2025unilabos,
+    title = {UniLabOS: An AI-Native Operating System for Autonomous Laboratories},
+    doi = {10.48550/arXiv.2512.21766},
+    publisher = {arXiv},
+    author = {Gao, Jing and Chang, Junhan and Que, Haohui and Xiong, Yanfei and
+              Zhang, Shixiang and Qi, Xianwei and Liu, Zhen and Wang, Jun-Jie and
+              Ding, Qianjun and Li, Xinyu and Pan, Ziwei and Xie, Qiming and
+              Yan, Zhuang and Yan, Junchi and Zhang, Linfeng},
+    year = {2025}
+}
+```
 
 ## 许可证
 
-此项目采用 GPL-3.0 许可 - 详情请参阅 [LICENSE](LICENSE) 文件。
+本项目采用双许可证结构：
+
+- **主框架**：GPL-3.0 - 详见 [LICENSE](LICENSE)
+- **设备驱动** (`unilabos/devices/`)：深势科技专有许可证
+
+完整许可证说明请参阅 [NOTICE](NOTICE)。
 
 ## 项目统计
 
@@ -79,4 +121,4 @@ Uni-Lab-OS 使用预构建的 `unilabos_msgs` 进行系统通信。您可以在
 
 ## 联系我们
 
-- GitHub Issues: [https://github.com/dptech-corp/Uni-Lab-OS/issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- GitHub Issues: [https://github.com/deepmodeling/Uni-Lab-OS/issues](https://github.com/deepmodeling/Uni-Lab-OS/issues)

docs/ai_guides/agent_prompt_template.md

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

docs/conf.py

@@ -24,7 +24,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",  # 如果您使用 Google 或 NumPy 风格的 docstrings
     "sphinx_rtd_theme",
-    "sphinxcontrib.mermaid"
+    "sphinxcontrib.mermaid",
 ]
 
 source_suffix = {
@@ -58,7 +58,7 @@ html_theme = "sphinx_rtd_theme"
 
 # sphinx-book-theme 主题选项
 html_theme_options = {
-    "repository_url": "https://github.com/用户名/Uni-Lab",
+    "repository_url": "https://github.com/deepmodeling/Uni-Lab-OS",
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,

docs/requirements.txt

@@ -12,3 +12,7 @@ sphinx-copybutton>=0.5.0
 
 # 用于自动摘要生成
 sphinx-autobuild>=2024.2.4
+
+# 用于PDF导出 (rinohtype方案，纯Python无需LaTeX)
+rinohtype>=0.5.4
+sphinx-simplepdf>=1.6.0

docs/user_guide/best_practice.md

@@ -31,6 +31,14 @@
 
 详细的安装步骤请参考 [安装指南](installation.md)。
 
+**选择合适的安装包：**
+
+| 安装包 | 适用场景 | 包含组件 |
+|--------|----------|----------|
+| `unilabos` | **推荐大多数用户**，生产部署 | 完整安装包，开箱即用 |
+| `unilabos-env` | 开发者（可编辑安装） | 仅环境依赖，通过 pip 安装 unilabos |
+| `unilabos-full` | 仿真/可视化 | unilabos + 完整 ROS2 桌面版 + Gazebo + MoveIt |
+
 **关键步骤：**
 
 ```bash
@@ -38,15 +46,30 @@
 # 下载 Miniforge: https://github.com/conda-forge/miniforge/releases
 
 # 2. 创建 Conda 环境
-mamba create -n unilab python=3.11.11
+mamba create -n unilab python=3.11.14
 
 # 3. 激活环境
 mamba activate unilab
 
-# 4. 安装 Uni-Lab-OS
+# 4. 安装 Uni-Lab-OS（选择其一）
+
+# 方案 A：标准安装（推荐大多数用户）
 mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# 方案 B：开发者环境（可编辑模式开发）
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+pip install -e /path/to/Uni-Lab-OS  # 可编辑安装
+uv pip install -r unilabos/utils/requirements.txt  # 安装 pip 依赖
+
+# 方案 C：完整版（仿真/可视化）
+mamba install uni-lab::unilabos-full -c robostack-staging -c conda-forge
 ```
 
+**选择建议：**
+- **日常使用/生产部署**：使用 `unilabos`（推荐），完整功能，开箱即用
+- **开发者**：使用 `unilabos-env` + `pip install -e .` + `uv pip install -r unilabos/utils/requirements.txt`，代码修改立即生效
+- **仿真/可视化**：使用 `unilabos-full`，含 Gazebo、rviz2、MoveIt
+
 #### 1.2 验证安装
 
 ```bash
@@ -416,6 +439,9 @@ unilab --ak your_ak --sk your_sk -g test/experiments/mock_devices/mock_all.json
 1. 访问 Web 界面，进入"仪器耗材"模块
 2. 在"仪器设备"区域找到并添加上述设备
 3. 在"物料耗材"区域找到并添加容器
+4. 在workstation中配置protocol_type包含PumpTransferProtocol
+
+![添加Protocol类型](image/add_protocol.png)
 
 ![物料列表](image/material.png)
 
@@ -426,8 +452,9 @@ unilab --ak your_ak --sk your_sk -g test/experiments/mock_devices/mock_all.json
 **操作步骤：**
 
 1. 将两个 `container` 拖拽到 `workstation` 中
-2. 将 `virtual_transfer_pump` 拖拽到 `workstation` 中
-3. 在画布上连接它们（建立父子关系）
+2. 将 `virtual_multiway_valve` 拖拽到 `workstation` 中
+3. 将 `virtual_transfer_pump` 拖拽到 `workstation` 中
+4. 在画布上连接它们（建立父子关系）
 
 ![设备连接](image/links.png)
 
@@ -768,7 +795,43 @@ Waiting for host service...
 
 详细的设备驱动编写指南请参考 [添加设备驱动](../developer_guide/add_device.md)。
 
-#### 9.1 为什么需要自定义设备？
+#### 9.1 开发环境准备
+
+**推荐使用 `unilabos-env` + `pip install -e .` + `uv pip install`** 进行设备开发：
+
+```bash
+# 1. 创建环境并安装 unilabos-env（ROS2 + conda 依赖 + uv）
+mamba create -n unilab python=3.11.14
+conda activate unilab
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+
+# 2. 克隆代码
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
+cd Uni-Lab-OS
+
+# 3. 以可编辑模式安装（推荐使用脚本，自动检测中文环境）
+python scripts/dev_install.py
+
+# 或手动安装：
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+```
+
+**为什么使用这种方式？**
+- `unilabos-env` 提供 ROS2 核心组件和 uv（通过 conda 安装，避免编译）
+- `unilabos/utils/requirements.txt` 包含所有运行时需要的 pip 依赖
+- `dev_install.py` 自动检测中文环境，中文系统自动使用清华镜像
+- 使用 `uv` 替代 `pip`，安装速度更快
+- 可编辑模式：代码修改**立即生效**，无需重新安装
+
+**如果安装失败或速度太慢**，可以手动执行（使用清华镜像）：
+
+```bash
+pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+uv pip install -r unilabos/utils/requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+```
+
+#### 9.2 为什么需要自定义设备？
 
 Uni-Lab-OS 内置了常见设备，但您的实验室可能有特殊设备需要集成：
 
@@ -777,7 +840,7 @@ Uni-Lab-OS 内置了常见设备，但您的实验室可能有特殊设备需要
 - 特殊的实验流程
 - 第三方设备集成
 
-#### 9.2 创建 Python 包
+#### 9.3 创建 Python 包
 
 为了方便开发和管理，建议为您的实验室创建独立的 Python 包。
 
@@ -814,7 +877,7 @@ touch my_lab_devices/my_lab_devices/__init__.py
 touch my_lab_devices/my_lab_devices/devices/__init__.py
 ```
 
-#### 9.3 创建 setup.py
+#### 9.4 创建 setup.py
 
 ```python
 # my_lab_devices/setup.py
@@ -845,7 +908,7 @@ setup(
 )
 ```
 
-#### 9.4 开发安装
+#### 9.5 开发安装
 
 使用 `-e` 参数进行可编辑安装，这样代码修改后立即生效：
 
@@ -860,7 +923,7 @@ pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
 - 方便调试和测试
 - 支持版本控制（git）
 
-#### 9.5 编写设备驱动
+#### 9.6 编写设备驱动
 
 创建设备驱动文件：
 
@@ -1001,7 +1064,7 @@ class MyPump:
 - **返回 Dict**：所有动作方法返回字典类型
 - **文档字符串**：详细说明参数和功能
 
-#### 9.6 测试设备驱动
+#### 9.7 测试设备驱动
 
 创建简单的测试脚本：
 
@@ -1807,7 +1870,7 @@ unilab --ak your_ak --sk your_sk -g graph.json \
 
 #### 14.5 社区支持
 
-- **GitHub Issues**：[https://github.com/dptech-corp/Uni-Lab-OS/issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- **GitHub Issues**：[https://github.com/deepmodeling/Uni-Lab-OS/issues](https://github.com/deepmodeling/Uni-Lab-OS/issues)
 - **官方网站**：[https://uni-lab.bohrium.com](https://uni-lab.bohrium.com)
 
 ---

docs/user_guide/graph_files.md

@@ -463,7 +463,7 @@ Uni-Lab 使用 `ResourceDictInstance.get_resource_instance_from_dict()` 方法
 ### 使用示例
 
 ```python
-from unilabos.ros.nodes.resource_tracker import ResourceDictInstance
+from unilabos.resources.resource_tracker import ResourceDictInstance
 
 # 旧格式节点
 old_format_node = {
@@ -477,10 +477,10 @@ old_format_node = {
 instance = ResourceDictInstance.get_resource_instance_from_dict(old_format_node)
 
 # 访问标准化后的数据
-print(instance.res_content.id)      # "pump_1"
-print(instance.res_content.uuid)    # 自动生成的 UUID
+print(instance.res_content.id)  # "pump_1"
+print(instance.res_content.uuid)  # 自动生成的 UUID
 print(instance.res_content.config)  # {}
-print(instance.res_content.data)    # {}
+print(instance.res_content.data)  # {}
 ```
 
 ### 格式迁移建议
@@ -857,4 +857,4 @@ class ResourceDictPosition(BaseModel):
 - 在 Web 界面中使用模板创建
 - 参考示例文件：`test/experiments/` 目录
 - 查看 ResourceDict 源码了解完整定义
-- [GitHub 讨论区](https://github.com/dptech-corp/Uni-Lab-OS/discussions)
+- [GitHub 讨论区](https://github.com/deepmodeling/Uni-Lab-OS/discussions)

docs/user_guide/installation.md

@@ -13,15 +13,26 @@
   - 开发者需要 Git 和基本的 Python 开发知识
   - 自定义 msgs 需要 GitHub 账号
 
+## 安装包选择
+
+Uni-Lab-OS 提供三个安装包版本，根据您的需求选择：
+
+| 安装包 | 适用场景 | 包含组件 | 磁盘占用 |
+|--------|----------|----------|----------|
+| **unilabos** | **推荐大多数用户**，生产部署 | 完整安装包，开箱即用 | ~2-3 GB |
+| **unilabos-env** | 开发者环境（可编辑安装） | 仅环境依赖，通过 pip 安装 unilabos | ~2 GB |
+| **unilabos-full** | 仿真可视化、完整功能体验 | unilabos + 完整 ROS2 桌面版 + Gazebo + MoveIt | ~8-10 GB |
+
 ## 安装方式选择
 
 根据您的使用场景，选择合适的安装方式：
 
-| 安装方式               | 适用人群             | 特点                           | 安装时间                     |
-| ---------------------- | -------------------- | ------------------------------ | ---------------------------- |
-| **方式一：一键安装**   | 实验室用户、快速体验 | 预打包环境，离线可用，无需配置 | 5-10 分钟 (网络良好的情况下) |
-| **方式二：手动安装**   | 标准用户、生产环境   | 灵活配置，版本可控             | 10-20 分钟                   |
-| **方式三：开发者安装** | 开发者、需要修改源码 | 可编辑模式，支持自定义 msgs    | 20-30 分钟                   |
+| 安装方式               | 适用人群             | 推荐安装包        | 特点                           | 安装时间                     |
+| ---------------------- | -------------------- | ----------------- | ------------------------------ | ---------------------------- |
+| **方式一：一键安装**   | 快速体验、演示       | 预打包环境        | 离线可用，无需配置             | 5-10 分钟 (网络良好的情况下) |
+| **方式二：手动安装**   | **大多数用户**       | `unilabos`        | 完整功能，开箱即用             | 10-20 分钟                   |
+| **方式三：开发者安装** | 开发者、需要修改源码 | `unilabos-env`    | 可编辑模式，支持自定义开发     | 20-30 分钟                   |
+| **仿真/可视化**        | 仿真测试、可视化调试 | `unilabos-full`   | 含 Gazebo、rviz2、MoveIt       | 30-60 分钟                   |
 
 ---
 
@@ -37,7 +48,7 @@
 
 #### 第一步：下载预打包环境
 
-1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
+1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/deepmodeling/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
 
 2. 选择最新的成功构建记录（绿色勾号 ✓）
 
@@ -144,17 +155,38 @@ bash Miniforge3-$(uname)-$(uname -m).sh
 使用以下命令创建 Uni-Lab 专用环境：
 
 ```bash
-mamba create -n unilab python=3.11.11  # 目前ros2组件依赖版本大多为3.11.11
+mamba create -n unilab python=3.11.14  # 目前ros2组件依赖版本大多为3.11.14
 mamba activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# 选择安装包（三选一）：
+
+# 方案 A：标准安装（推荐大多数用户）
+mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# 方案 B：开发者环境（可编辑模式开发）
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+# 然后安装 unilabos 和 pip 依赖：
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git && cd Uni-Lab-OS
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+
+# 方案 C：完整版（含仿真和可视化工具）
+mamba install uni-lab::unilabos-full -c robostack-staging -c conda-forge
 ```
 
 **参数说明**:
 
 - `-n unilab`: 创建名为 "unilab" 的环境
-- `uni-lab::unilabos`: 从 uni-lab channel 安装 unilabos 包
+- `uni-lab::unilabos`: 安装 unilabos 完整包，开箱即用（推荐）
+- `uni-lab::unilabos-env`: 仅安装环境依赖，适合开发者使用 `pip install -e .`
+- `uni-lab::unilabos-full`: 安装完整包（含 ROS2 Desktop、Gazebo、MoveIt 等）
 - `-c robostack-staging -c conda-forge`: 添加额外的软件源
 
+**包选择建议**：
+- **日常使用/生产部署**：安装 `unilabos`（推荐，完整功能，开箱即用）
+- **开发者**：安装 `unilabos-env`，然后使用 `uv pip install -r unilabos/utils/requirements.txt` 安装依赖，再 `pip install -e .` 进行可编辑安装
+- **仿真/可视化**：安装 `unilabos-full`（Gazebo、rviz2、MoveIt）
+
 **如果遇到网络问题**，可以使用清华镜像源加速下载：
 
 ```bash
@@ -163,8 +195,14 @@ mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/m
 mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
 mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
 
-# 然后重新执行安装命令
+# 然后重新执行安装命令（推荐标准安装）
 mamba create -n unilab uni-lab::unilabos -c robostack-staging
+
+# 或完整版（仿真/可视化）
+mamba create -n unilab uni-lab::unilabos-full -c robostack-staging
+
+# pip 安装时使用清华镜像（开发者安装时使用）
+uv pip install -r unilabos/utils/requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
 ```
 
 ### 第三步：激活环境
@@ -189,13 +227,13 @@ conda activate unilab
 ### 第一步：克隆仓库
 
 ```bash
-git clone https://github.com/dptech-corp/Uni-Lab-OS.git
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
 cd Uni-Lab-OS
 ```
 
 如果您需要贡献代码，建议先 Fork 仓库：
 
-1. 访问 https://github.com/dptech-corp/Uni-Lab-OS
+1. 访问 https://github.com/deepmodeling/Uni-Lab-OS
 2. 点击右上角的 "Fork" 按钮
 3. Clone 您的 Fork 版本：
    ```bash
@@ -203,58 +241,87 @@ cd Uni-Lab-OS
    cd Uni-Lab-OS
    ```
 
-### 第二步：安装基础环境
+### 第二步：安装开发环境（unilabos-env）
 
-**推荐方式**：先通过**方式一（一键安装）**或**方式二（手动安装）**完成基础环境的安装，这将包含所有必需的依赖项（ROS2、msgs 等）。
-
-#### 选项 A：通过一键安装（推荐）
-
-参考上文"方式一：一键安装"，完成基础环境的安装后，激活环境：
+**重要**：开发者请使用 `unilabos-env` 包，它专为开发者设计：
+- 包含 ROS2 核心组件和消息包（ros-humble-ros-core、std-msgs、geometry-msgs 等）
+- 包含 transforms3d、cv-bridge、tf2 等 conda 依赖
+- 包含 `uv` 工具，用于快速安装 pip 依赖
+- **不包含** pip 依赖和 unilabos 包（由 `pip install -e .` 和 `uv pip install` 安装）
 
 ```bash
+# 创建并激活环境
+mamba create -n unilab python=3.11.14
 conda activate unilab
+
+# 安装开发者环境包（ROS2 + conda 依赖 + uv）
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
 ```
 
-#### 选项 B：通过手动安装
+### 第三步：安装 pip 依赖和可编辑模式安装
 
-参考上文"方式二：手动安装"，创建并安装环境：
-
-```bash
-mamba create -n unilab python=3.11.11
-conda activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
-```
-
-**说明**：这会安装包括 Python 3.11.11、ROS2 Humble、ros-humble-unilabos-msgs 和所有必需依赖
-
-### 第三步：切换到开发版本
-
-现在你已经有了一个完整可用的 Uni-Lab 环境，接下来将 unilabos 包切换为开发版本：
+克隆代码并安装依赖：
 
 ```bash
 # 确保环境已激活
 conda activate unilab
 
-# 卸载 pip 安装的 unilabos（保留所有 conda 依赖）
-pip uninstall unilabos -y
-
-# 克隆 dev 分支（如果还未克隆）
-cd /path/to/your/workspace
-git clone -b dev https://github.com/dptech-corp/Uni-Lab-OS.git
-# 或者如果已经克隆，切换到 dev 分支
+# 克隆仓库（如果还未克隆）
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
 cd Uni-Lab-OS
+
+# 切换到 dev 分支（可选）
 git checkout dev
 git pull
-
-# 以可编辑模式安装开发版 unilabos
-pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
 ```
 
-**参数说明**：
+**推荐：使用安装脚本**（自动检测中文环境，使用 uv 加速）：
 
-- `-e`: editable mode（可编辑模式），代码修改立即生效，无需重新安装
-- `-i`: 使用清华镜像源加速下载
-- `pip uninstall unilabos`: 只卸载 pip 安装的 unilabos 包，不影响 conda 安装的其他依赖（如 ROS2、msgs 等）
+```bash
+# 自动检测中文环境，如果是中文系统则使用清华镜像
+python scripts/dev_install.py
+
+# 或者手动指定：
+python scripts/dev_install.py --china     # 强制使用清华镜像
+python scripts/dev_install.py --no-mirror # 强制使用 PyPI
+python scripts/dev_install.py --skip-deps # 跳过 pip 依赖安装
+python scripts/dev_install.py --use-pip   # 使用 pip 而非 uv
+```
+
+**手动安装**（如果脚本安装失败或速度太慢）：
+
+```bash
+# 1. 安装 unilabos（可编辑模式）
+pip install -e .
+
+# 2. 使用 uv 安装 pip 依赖（推荐，速度更快）
+uv pip install -r unilabos/utils/requirements.txt
+
+# 国内用户使用清华镜像：
+pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+uv pip install -r unilabos/utils/requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+```
+
+**注意**：
+- `uv` 已包含在 `unilabos-env` 中，无需单独安装
+- `unilabos/utils/requirements.txt` 包含运行 unilabos 所需的所有 pip 依赖
+- 部分特殊包（如 pylabrobot）会在运行时由 unilabos 自动检测并安装
+
+**为什么使用可编辑模式？**
+
+- `-e` (editable mode)：代码修改**立即生效**，无需重新安装
+- 适合开发调试：修改代码后直接运行测试
+- 与 `unilabos-env` 配合：环境依赖由 conda 管理，unilabos 代码由 pip 管理
+
+**验证安装**：
+
+```bash
+# 检查 unilabos 版本
+python -c "import unilabos; print(unilabos.__version__)"
+
+# 检查安装位置（应该指向你的代码目录）
+pip show unilabos | grep Location
+```
 
 ### 第四步：安装或自定义 ros-humble-unilabos-msgs（可选）
 
@@ -464,7 +531,45 @@ cd $CONDA_PREFIX/envs/unilab
 
 ### 问题 8: 环境很大，有办法减小吗？
 
-**解决方案**: 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用方式二手动安装，只安装需要的组件。
+**解决方案**: 
+
+1. **使用 `unilabos` 标准版**（推荐大多数用户）：
+   ```bash
+   mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+   ```
+   标准版包含完整功能，环境大小约 2-3GB（相比完整版的 8-10GB）。
+
+2. **使用 `unilabos-env` 开发者版**（最小化）：
+   ```bash
+   mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+   # 然后手动安装依赖
+   pip install -e .
+   uv pip install -r unilabos/utils/requirements.txt
+   ```
+   开发者版只包含环境依赖，体积最小约 2GB。
+
+3. **按需安装额外组件**：
+   如果后续需要特定功能，可以单独安装：
+   ```bash
+   # 需要 Jupyter
+   mamba install jupyter jupyros
+   
+   # 需要可视化
+   mamba install matplotlib opencv
+   
+   # 需要仿真（注意：这会安装大量依赖）
+   mamba install ros-humble-gazebo-ros
+   ```
+
+4. **预打包环境问题**：
+   预打包环境（方式一）包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。
+
+**包选择建议**：
+| 需求 | 推荐包 | 预估大小 |
+|------|--------|----------|
+| 日常使用/生产部署 | `unilabos` | ~2-3 GB |
+| 开发调试（可编辑模式） | `unilabos-env` | ~2 GB |
+| 仿真/可视化 | `unilabos-full` | ~8-10 GB |
 
 ### 问题 9: 如何更新到最新版本？
 
@@ -503,14 +608,15 @@ mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-f
 ## 需要帮助？
 
 - **故障排查**: 查看更详细的故障排查信息
-- **GitHub Issues**: [报告问题](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- **GitHub Issues**: [报告问题](https://github.com/deepmodeling/Uni-Lab-OS/issues)
 - **开发者文档**: 查看开发者指南获取更多技术细节
-- **社区讨论**: [GitHub Discussions](https://github.com/dptech-corp/Uni-Lab-OS/discussions)
+- **社区讨论**: [GitHub Discussions](https://github.com/deepmodeling/Uni-Lab-OS/discussions)
 
 ---
 
 **提示**:
 
-- 生产环境推荐使用方式二（手动安装）的稳定版本
-- 开发和测试推荐使用方式三（开发者安装）
-- 快速体验和演示推荐使用方式一（一键安装）
+- **大多数用户**推荐使用方式二（手动安装）的 `unilabos` 标准版
+- **开发者**推荐使用方式三（开发者安装），安装 `unilabos-env` 后使用 `uv pip install -r unilabos/utils/requirements.txt` 安装依赖
+- **仿真/可视化**推荐安装 `unilabos-full` 完整版
+- **快速体验和演示**推荐使用方式一（一键安装）

recipes/msgs/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: ros-humble-unilabos-msgs
-  version: 0.10.13
+  version: 0.10.18
 source:
   path: ../../unilabos_msgs
   target_directory: src
@@ -17,7 +17,7 @@ build:
     - bash $SRC_DIR/build_ament_cmake.sh
 
 about:
-  repository: https://github.com/dptech-corp/Uni-Lab-OS
+  repository: https://github.com/deepmodeling/Uni-Lab-OS
   license: BSD-3-Clause
   description: "ros-humble-unilabos-msgs is a package that provides message definitions for Uni-Lab-OS."
 
@@ -25,7 +25,7 @@ requirements:
   build:
   - ${{ compiler('cxx') }}
   - ${{ compiler('c') }}
-  - python ==3.11.11
+  - python ==3.11.14
   - numpy
   - if: build_platform != target_platform
     then:
@@ -63,14 +63,14 @@ requirements:
   - robostack-staging::ros-humble-rosidl-default-generators
   - robostack-staging::ros-humble-std-msgs
   - robostack-staging::ros-humble-geometry-msgs
-  - robostack-staging::ros2-distro-mutex=0.6
+  - robostack-staging::ros2-distro-mutex=0.7
   run:
   - robostack-staging::ros-humble-action-msgs
   - robostack-staging::ros-humble-ros-workspace
   - robostack-staging::ros-humble-rosidl-default-runtime
   - robostack-staging::ros-humble-std-msgs
   - robostack-staging::ros-humble-geometry-msgs
-  - robostack-staging::ros2-distro-mutex=0.6
+  - robostack-staging::ros2-distro-mutex=0.7
   - if: osx and x86_64
     then:
     - __osx >=${{ MACOSX_DEPLOYMENT_TARGET|default('10.14') }}

recipes/unilabos/recipe.yaml

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

scripts/create_readme.py

@@ -85,7 +85,7 @@ Verification:
 -------------
 
 The verify_installation.py script will check:
-  - Python version (3.11.11)
+  - Python version (3.11.14)
   - ROS2 rclpy installation
   - UniLabOS installation and dependencies
 
@@ -104,7 +104,7 @@ Build Information:
 
   Branch:   {branch}
   Platform: {platform}
-  Python:   3.11.11
+  Python:   3.11.14
   Date:     {build_date}
 
 Troubleshooting:
@@ -126,7 +126,7 @@ If installation fails:
 For more help:
   - Documentation: docs/user_guide/installation.md
   - Quick Start: QUICK_START_CONDA_PACK.md
-  - Issues: https://github.com/dptech-corp/Uni-Lab-OS/issues
+  - Issues: https://github.com/deepmodeling/Uni-Lab-OS/issues
 
 License:
 --------
@@ -134,7 +134,7 @@ License:
 UniLabOS is licensed under GPL-3.0-only.
 See LICENSE file for details.
 
-Repository: https://github.com/dptech-corp/Uni-Lab-OS
+Repository: https://github.com/deepmodeling/Uni-Lab-OS
 """
 
     return readme

scripts/dev_install.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""
+Development installation script for UniLabOS.
+Auto-detects Chinese locale and uses appropriate mirror.
+
+Usage:
+    python scripts/dev_install.py
+    python scripts/dev_install.py --no-mirror  # Force no mirror
+    python scripts/dev_install.py --china      # Force China mirror
+    python scripts/dev_install.py --skip-deps  # Skip pip dependencies installation
+
+Flow:
+    1. pip install -e . (install unilabos in editable mode)
+    2. Detect Chinese locale
+    3. Use uv to install pip dependencies from requirements.txt
+    4. Special packages (like pylabrobot) are handled by environment_check.py at runtime
+"""
+
+import locale
+import subprocess
+import sys
+import argparse
+from pathlib import Path
+
+# Tsinghua mirror URL
+TSINGHUA_MIRROR = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
+
+
+def is_chinese_locale() -> bool:
+    """
+    Detect if system is in Chinese locale.
+    Same logic as EnvironmentChecker._is_chinese_locale()
+    """
+    try:
+        lang = locale.getdefaultlocale()[0]
+        if lang and ("zh" in lang.lower() or "chinese" in lang.lower()):
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def run_command(cmd: list, description: str, retry: int = 2) -> bool:
+    """Run command with retry support."""
+    print(f"[INFO] {description}")
+    print(f"[CMD] {' '.join(cmd)}")
+
+    for attempt in range(retry + 1):
+        try:
+            result = subprocess.run(cmd, check=True, timeout=600)
+            print(f"[OK] {description}")
+            return True
+        except subprocess.CalledProcessError as e:
+            if attempt < retry:
+                print(f"[WARN] Attempt {attempt + 1} failed, retrying...")
+            else:
+                print(f"[ERROR] {description} failed: {e}")
+                return False
+        except subprocess.TimeoutExpired:
+            print(f"[ERROR] {description} timed out")
+            return False
+    return False
+
+
+def install_editable(project_root: Path, use_mirror: bool) -> bool:
+    """Install unilabos in editable mode using pip."""
+    cmd = [sys.executable, "-m", "pip", "install", "-e", str(project_root)]
+    if use_mirror:
+        cmd.extend(["-i", TSINGHUA_MIRROR])
+
+    return run_command(cmd, "Installing unilabos in editable mode")
+
+
+def install_requirements_uv(requirements_file: Path, use_mirror: bool) -> bool:
+    """Install pip dependencies using uv (installed via conda-forge::uv)."""
+    cmd = ["uv", "pip", "install", "-r", str(requirements_file)]
+    if use_mirror:
+        cmd.extend(["-i", TSINGHUA_MIRROR])
+
+    return run_command(cmd, "Installing pip dependencies with uv", retry=2)
+
+
+def install_requirements_pip(requirements_file: Path, use_mirror: bool) -> bool:
+    """Fallback: Install pip dependencies using pip."""
+    cmd = [sys.executable, "-m", "pip", "install", "-r", str(requirements_file)]
+    if use_mirror:
+        cmd.extend(["-i", TSINGHUA_MIRROR])
+
+    return run_command(cmd, "Installing pip dependencies with pip", retry=2)
+
+
+def check_uv_available() -> bool:
+    """Check if uv is available (installed via conda-forge::uv)."""
+    try:
+        subprocess.run(["uv", "--version"], capture_output=True, check=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Development installation script for UniLabOS")
+    parser.add_argument("--china", action="store_true", help="Force use China mirror (Tsinghua)")
+    parser.add_argument("--no-mirror", action="store_true", help="Force use default PyPI (no mirror)")
+    parser.add_argument(
+        "--skip-deps", action="store_true", help="Skip pip dependencies installation (only install unilabos)"
+    )
+    parser.add_argument("--use-pip", action="store_true", help="Use pip instead of uv for dependencies")
+    args = parser.parse_args()
+
+    # Determine project root
+    script_dir = Path(__file__).parent
+    project_root = script_dir.parent
+    requirements_file = project_root / "unilabos" / "utils" / "requirements.txt"
+
+    if not (project_root / "setup.py").exists():
+        print(f"[ERROR] setup.py not found in {project_root}")
+        sys.exit(1)
+
+    print("=" * 60)
+    print("UniLabOS Development Installation")
+    print("=" * 60)
+    print(f"Project root: {project_root}")
+    print()
+
+    # Determine mirror usage based on locale
+    if args.no_mirror:
+        use_mirror = False
+        print("[INFO] Mirror disabled by --no-mirror flag")
+    elif args.china:
+        use_mirror = True
+        print("[INFO] China mirror enabled by --china flag")
+    else:
+        use_mirror = is_chinese_locale()
+        if use_mirror:
+            print("[INFO] Chinese locale detected, using Tsinghua mirror")
+        else:
+            print("[INFO] Non-Chinese locale detected, using default PyPI")
+
+    print()
+
+    # Step 1: Install unilabos in editable mode
+    print("[STEP 1] Installing unilabos in editable mode...")
+    if not install_editable(project_root, use_mirror):
+        print("[ERROR] Failed to install unilabos")
+        print()
+        print("Manual fallback:")
+        if use_mirror:
+            print(f"  pip install -e {project_root} -i {TSINGHUA_MIRROR}")
+        else:
+            print(f"  pip install -e {project_root}")
+        sys.exit(1)
+
+    print()
+
+    # Step 2: Install pip dependencies
+    if args.skip_deps:
+        print("[INFO] Skipping pip dependencies installation (--skip-deps)")
+    else:
+        print("[STEP 2] Installing pip dependencies...")
+
+        if not requirements_file.exists():
+            print(f"[WARN] Requirements file not found: {requirements_file}")
+            print("[INFO] Skipping dependencies installation")
+        else:
+            # Try uv first (faster), fallback to pip
+            if args.use_pip:
+                print("[INFO] Using pip (--use-pip flag)")
+                success = install_requirements_pip(requirements_file, use_mirror)
+            elif check_uv_available():
+                print("[INFO] Using uv (installed via conda-forge::uv)")
+                success = install_requirements_uv(requirements_file, use_mirror)
+                if not success:
+                    print("[WARN] uv failed, falling back to pip...")
+                    success = install_requirements_pip(requirements_file, use_mirror)
+            else:
+                print("[WARN] uv not available (should be installed via: mamba install conda-forge::uv)")
+                print("[INFO] Falling back to pip...")
+                success = install_requirements_pip(requirements_file, use_mirror)
+
+            if not success:
+                print()
+                print("[WARN] Failed to install some dependencies automatically.")
+                print("You can manually install them:")
+                if use_mirror:
+                    print(f"  uv pip install -r {requirements_file} -i {TSINGHUA_MIRROR}")
+                    print("  or:")
+                    print(f"  pip install -r {requirements_file} -i {TSINGHUA_MIRROR}")
+                else:
+                    print(f"  uv pip install -r {requirements_file}")
+                    print("  or:")
+                    print(f"  pip install -r {requirements_file}")
+
+    print()
+    print("=" * 60)
+    print("Installation complete!")
+    print("=" * 60)
+    print()
+    print("Note: Some special packages (like pylabrobot) are installed")
+    print("automatically at runtime by unilabos if needed.")
+    print()
+    print("Verify installation:")
+    print('  python -c "import unilabos; print(unilabos.__version__)"')
+    print()
+    print("If you encounter issues, you can manually install dependencies:")
+    if use_mirror:
+        print(f"  uv pip install -r unilabos/utils/requirements.txt -i {TSINGHUA_MIRROR}")
+    else:
+        print("  uv pip install -r unilabos/utils/requirements.txt")
+    print()
+
+
+if __name__ == "__main__":
+    main()

scripts/workflow.py

@@ -2,7 +2,6 @@ import json
 import logging
 import traceback
 import uuid
-import xml.etree.ElementTree as ET
 from typing import Any, Dict, List
 
 import networkx as nx
@@ -25,7 +24,15 @@ 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):
@@ -42,6 +49,7 @@ class SimpleGraph:
             "multigraph": False,
             "graph": {},
             "nodes": nodes_list,
+            "edges": self.edges,
             "links": self.edges,
         }
 
@@ -58,495 +66,8 @@ 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(

setup.py

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

tests/__init__.py

@@ -0,0 +1,7 @@
+"""
+测试包根目录。
+
+让 `tests.*` 模块可以被正常 import（例如给 `unilabos` 下的测试入口使用）。
+"""
+
+

tests/devices/__init__.py

@@ -0,0 +1 @@
+

tests/devices/liquid_handling/__init__.py

@@ -0,0 +1,5 @@
+"""
+液体处理设备相关测试。
+"""
+
+

tests/devices/liquid_handling/test_transfer_liquid.py

@@ -0,0 +1,505 @@
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Iterable, List, Optional, Sequence, Tuple
+
+import pytest
+
+from unilabos.devices.liquid_handling.liquid_handler_abstract import LiquidHandlerAbstract
+
+
+@dataclass(frozen=True)
+class DummyContainer:
+    name: str
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"DummyContainer({self.name})"
+
+
+@dataclass(frozen=True)
+class DummyTipSpot:
+    name: str
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"DummyTipSpot({self.name})"
+
+
+def make_tip_iter(n: int = 256) -> Iterable[List[DummyTipSpot]]:
+    """Yield lists so code can safely call `tip.extend(next(self.current_tip))`."""
+    for i in range(n):
+        yield [DummyTipSpot(f"tip_{i}")]
+
+
+class FakeLiquidHandler(LiquidHandlerAbstract):
+    """不初始化真实 backend/deck；仅用来记录 transfer_liquid 内部调用序列。"""
+
+    def __init__(self, channel_num: int = 8):
+        # 不调用 super().__init__，避免真实硬件/后端依赖
+        self.channel_num = channel_num
+        self.support_touch_tip = True
+        self.current_tip = iter(make_tip_iter())
+        self.calls: List[Tuple[str, Any]] = []
+
+    async def pick_up_tips(self, tip_spots, use_channels=None, offsets=None, **backend_kwargs):
+        self.calls.append(("pick_up_tips", {"tips": list(tip_spots), "use_channels": use_channels}))
+
+    async def aspirate(
+        self,
+        resources: Sequence[Any],
+        vols: List[float],
+        use_channels: Optional[List[int]] = None,
+        flow_rates: Optional[List[Optional[float]]] = None,
+        offsets: Any = None,
+        liquid_height: Any = None,
+        blow_out_air_volume: Any = None,
+        spread: str = "wide",
+        **backend_kwargs,
+    ):
+        self.calls.append(
+            (
+                "aspirate",
+                {
+                    "resources": list(resources),
+                    "vols": list(vols),
+                    "use_channels": list(use_channels) if use_channels is not None else None,
+                    "flow_rates": list(flow_rates) if flow_rates is not None else None,
+                    "offsets": list(offsets) if offsets is not None else None,
+                    "liquid_height": list(liquid_height) if liquid_height is not None else None,
+                    "blow_out_air_volume": list(blow_out_air_volume) if blow_out_air_volume is not None else None,
+                },
+            )
+        )
+
+    async def dispense(
+        self,
+        resources: Sequence[Any],
+        vols: List[float],
+        use_channels: Optional[List[int]] = None,
+        flow_rates: Optional[List[Optional[float]]] = None,
+        offsets: Any = None,
+        liquid_height: Any = None,
+        blow_out_air_volume: Any = None,
+        spread: str = "wide",
+        **backend_kwargs,
+    ):
+        self.calls.append(
+            (
+                "dispense",
+                {
+                    "resources": list(resources),
+                    "vols": list(vols),
+                    "use_channels": list(use_channels) if use_channels is not None else None,
+                    "flow_rates": list(flow_rates) if flow_rates is not None else None,
+                    "offsets": list(offsets) if offsets is not None else None,
+                    "liquid_height": list(liquid_height) if liquid_height is not None else None,
+                    "blow_out_air_volume": list(blow_out_air_volume) if blow_out_air_volume is not None else None,
+                },
+            )
+        )
+
+    async def discard_tips(self, use_channels=None, *args, **kwargs):
+        # 有的分支是 discard_tips(use_channels=[0])，有的分支是 discard_tips([0..7])（位置参数）
+        self.calls.append(("discard_tips", {"use_channels": list(use_channels) if use_channels is not None else None}))
+
+    async def custom_delay(self, seconds=0, msg=None):
+        self.calls.append(("custom_delay", {"seconds": seconds, "msg": msg}))
+
+    async def touch_tip(self, targets):
+        # 原实现会访问 targets.get_size_x() 等；测试里只记录调用
+        self.calls.append(("touch_tip", {"targets": targets}))
+
+    async def mix(self, targets, mix_time=None, mix_vol=None, height_to_bottom=None, offsets=None, mix_rate=None, none_keys=None):
+        self.calls.append(
+            (
+                "mix",
+                {
+                    "targets": targets,
+                    "mix_time": mix_time,
+                    "mix_vol": mix_vol,
+                },
+            )
+        )
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def test_one_to_one_single_channel_basic_calls():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(64))
+
+    sources = [DummyContainer(f"S{i}") for i in range(3)]
+    targets = [DummyContainer(f"T{i}") for i in range(3)]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=targets,
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=[1, 2, 3],
+            dis_vols=[4, 5, 6],
+            mix_times=None,  # 应该仍能执行（不 mix）
+        )
+    )
+
+    assert [c[0] for c in lh.calls].count("pick_up_tips") == 3
+    assert [c[0] for c in lh.calls].count("aspirate") == 3
+    assert [c[0] for c in lh.calls].count("dispense") == 3
+    assert [c[0] for c in lh.calls].count("discard_tips") == 3
+
+    # 每次 aspirate/dispense 都是单孔列表
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    assert aspirates[0]["resources"] == [sources[0]]
+    assert aspirates[0]["vols"] == [1.0]
+
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert dispenses[2]["resources"] == [targets[2]]
+    assert dispenses[2]["vols"] == [6.0]
+
+
+def test_one_to_one_single_channel_before_stage_mixes_prior_to_aspirate():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(16))
+
+    source = DummyContainer("S0")
+    target = DummyContainer("T0")
+
+    run(
+        lh.transfer_liquid(
+            sources=[source],
+            targets=[target],
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=[5],
+            dis_vols=[5],
+            mix_stage="before",
+            mix_times=1,
+            mix_vol=3,
+        )
+    )
+
+    names = [name for name, _ in lh.calls]
+    assert names.count("mix") == 1
+    assert names.index("mix") < names.index("aspirate")
+
+
+def test_one_to_one_eight_channel_groups_by_8():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(256))
+
+    sources = [DummyContainer(f"S{i}") for i in range(16)]
+    targets = [DummyContainer(f"T{i}") for i in range(16)]
+    asp_vols = list(range(1, 17))
+    dis_vols = list(range(101, 117))
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=targets,
+            tip_racks=[],
+            use_channels=list(range(8)),
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,
+            mix_times=0,  # 触发逻辑但不 mix
+        )
+    )
+
+    # 16 个任务 -> 2 组，每组 8 通道一起做
+    assert [c[0] for c in lh.calls].count("pick_up_tips") == 2
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert len(aspirates) == 2
+    assert len(dispenses) == 2
+
+    assert aspirates[0]["resources"] == sources[0:8]
+    assert aspirates[0]["vols"] == [float(v) for v in asp_vols[0:8]]
+    assert dispenses[1]["resources"] == targets[8:16]
+    assert dispenses[1]["vols"] == [float(v) for v in dis_vols[8:16]]
+
+
+def test_one_to_one_eight_channel_requires_multiple_of_8_targets():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(64))
+
+    sources = [DummyContainer(f"S{i}") for i in range(9)]
+    targets = [DummyContainer(f"T{i}") for i in range(9)]
+
+    with pytest.raises(ValueError, match="multiple of 8"):
+        run(
+            lh.transfer_liquid(
+                sources=sources,
+                targets=targets,
+                tip_racks=[],
+                use_channels=list(range(8)),
+                asp_vols=[1] * 9,
+                dis_vols=[1] * 9,
+                mix_times=0,
+            )
+        )
+
+
+def test_one_to_one_eight_channel_parameter_lists_are_chunked_per_8():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(512))
+
+    sources = [DummyContainer(f"S{i}") for i in range(16)]
+    targets = [DummyContainer(f"T{i}") for i in range(16)]
+    asp_vols = [i + 1 for i in range(16)]
+    dis_vols = [200 + i for i in range(16)]
+    asp_flow_rates = [0.1 * (i + 1) for i in range(16)]
+    dis_flow_rates = [0.2 * (i + 1) for i in range(16)]
+    offsets = [f"offset_{i}" for i in range(16)]
+    liquid_heights = [i * 0.5 for i in range(16)]
+    blow_out_air_volume = [i + 0.05 for i in range(16)]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=targets,
+            tip_racks=[],
+            use_channels=list(range(8)),
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,
+            asp_flow_rates=asp_flow_rates,
+            dis_flow_rates=dis_flow_rates,
+            offsets=offsets,
+            liquid_height=liquid_heights,
+            blow_out_air_volume=blow_out_air_volume,
+            mix_times=0,
+        )
+    )
+
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert len(aspirates) == len(dispenses) == 2
+
+    for batch_idx in range(2):
+        start = batch_idx * 8
+        end = start + 8
+        asp_call = aspirates[batch_idx]
+        dis_call = dispenses[batch_idx]
+        assert asp_call["resources"] == sources[start:end]
+        assert asp_call["flow_rates"] == asp_flow_rates[start:end]
+        assert asp_call["offsets"] == offsets[start:end]
+        assert asp_call["liquid_height"] == liquid_heights[start:end]
+        assert asp_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
+        assert dis_call["flow_rates"] == dis_flow_rates[start:end]
+        assert dis_call["offsets"] == offsets[start:end]
+        assert dis_call["liquid_height"] == liquid_heights[start:end]
+        assert dis_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
+
+
+def test_one_to_one_eight_channel_handles_32_tasks_four_batches():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(1024))
+
+    sources = [DummyContainer(f"S{i}") for i in range(32)]
+    targets = [DummyContainer(f"T{i}") for i in range(32)]
+    asp_vols = [i + 1 for i in range(32)]
+    dis_vols = [300 + i for i in range(32)]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=targets,
+            tip_racks=[],
+            use_channels=list(range(8)),
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,
+            mix_times=0,
+        )
+    )
+
+    pick_calls = [name for name, _ in lh.calls if name == "pick_up_tips"]
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert len(pick_calls) == 4
+    assert len(aspirates) == len(dispenses) == 4
+    assert aspirates[0]["resources"] == sources[0:8]
+    assert aspirates[-1]["resources"] == sources[24:32]
+    assert dispenses[0]["resources"] == targets[0:8]
+    assert dispenses[-1]["resources"] == targets[24:32]
+
+
+def test_one_to_many_single_channel_aspirates_total_when_asp_vol_too_small():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(64))
+
+    source = DummyContainer("SRC")
+    targets = [DummyContainer(f"T{i}") for i in range(3)]
+    dis_vols = [10, 20, 30]  # sum=60
+
+    run(
+        lh.transfer_liquid(
+            sources=[source],
+            targets=targets,
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=10,  # 小于 sum(dis_vols) -> 应吸 60
+            dis_vols=dis_vols,
+            mix_times=0,
+        )
+    )
+
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    assert len(aspirates) == 1
+    assert aspirates[0]["resources"] == [source]
+    assert aspirates[0]["vols"] == [60.0]
+    assert aspirates[0]["use_channels"] == [0]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert [d["vols"][0] for d in dispenses] == [10.0, 20.0, 30.0]
+
+
+def test_one_to_many_eight_channel_basic():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(128))
+
+    source = DummyContainer("SRC")
+    targets = [DummyContainer(f"T{i}") for i in range(8)]
+    dis_vols = [i + 1 for i in range(8)]
+
+    run(
+        lh.transfer_liquid(
+            sources=[source],
+            targets=targets,
+            tip_racks=[],
+            use_channels=list(range(8)),
+            asp_vols=999,  # one-to-many 8ch 会按 dis_vols 吸（每通道各自）
+            dis_vols=dis_vols,
+            mix_times=0,
+        )
+    )
+
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    assert aspirates[0]["resources"] == [source] * 8
+    assert aspirates[0]["vols"] == [float(v) for v in dis_vols]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert dispenses[0]["resources"] == targets
+    assert dispenses[0]["vols"] == [float(v) for v in dis_vols]
+
+
+def test_many_to_one_single_channel_standard_dispense_equals_asp_by_default():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(128))
+
+    sources = [DummyContainer(f"S{i}") for i in range(3)]
+    target = DummyContainer("T")
+    asp_vols = [5, 6, 7]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=[target],
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=asp_vols,
+            dis_vols=1,  # many-to-one 允许标量；非比例模式下实际每次分液=对应 asp_vol
+            mix_times=0,
+        )
+    )
+
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert [d["vols"][0] for d in dispenses] == [float(v) for v in asp_vols]
+    assert all(d["resources"] == [target] for d in dispenses)
+
+
+def test_many_to_one_single_channel_before_stage_mixes_target_once():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(128))
+
+    sources = [DummyContainer("S0"), DummyContainer("S1")]
+    target = DummyContainer("T")
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=[target],
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=[5, 6],
+            dis_vols=1,
+            mix_stage="before",
+            mix_times=2,
+            mix_vol=4,
+        )
+    )
+
+    names = [name for name, _ in lh.calls]
+    assert names[0] == "mix"
+    assert names.count("mix") == 1
+
+
+def test_many_to_one_single_channel_proportional_mixing_uses_dis_vols_per_source():
+    lh = FakeLiquidHandler(channel_num=1)
+    lh.current_tip = iter(make_tip_iter(128))
+
+    sources = [DummyContainer(f"S{i}") for i in range(3)]
+    target = DummyContainer("T")
+    asp_vols = [5, 6, 7]
+    dis_vols = [1, 2, 3]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=[target],
+            tip_racks=[],
+            use_channels=[0],
+            asp_vols=asp_vols,
+            dis_vols=dis_vols,  # 比例模式
+            mix_times=0,
+        )
+    )
+
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert [d["vols"][0] for d in dispenses] == [float(v) for v in dis_vols]
+
+
+def test_many_to_one_eight_channel_basic():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(256))
+
+    sources = [DummyContainer(f"S{i}") for i in range(8)]
+    target = DummyContainer("T")
+    asp_vols = [10 + i for i in range(8)]
+
+    run(
+        lh.transfer_liquid(
+            sources=sources,
+            targets=[target],
+            tip_racks=[],
+            use_channels=list(range(8)),
+            asp_vols=asp_vols,
+            dis_vols=999,  # 非比例模式下每通道分液=对应 asp_vol
+            mix_times=0,
+        )
+    )
+
+    aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+    dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+    assert aspirates[0]["resources"] == sources
+    assert aspirates[0]["vols"] == [float(v) for v in asp_vols]
+    assert dispenses[0]["resources"] == [target] * 8
+    assert dispenses[0]["vols"] == [float(v) for v in asp_vols]
+
+
+def test_transfer_liquid_mode_detection_unsupported_shape_raises():
+    lh = FakeLiquidHandler(channel_num=8)
+    lh.current_tip = iter(make_tip_iter(64))
+
+    sources = [DummyContainer("S0"), DummyContainer("S1")]
+    targets = [DummyContainer("T0"), DummyContainer("T1"), DummyContainer("T2")]
+
+    with pytest.raises(ValueError, match="Unsupported transfer mode"):
+        run(
+            lh.transfer_liquid(
+                sources=sources,
+                targets=targets,
+                tip_racks=[],
+                use_channels=[0],
+                asp_vols=[1, 1],
+                dis_vols=[1, 1, 1],
+                mix_times=0,
+            )
+        )
+

tests/resources/test_resourcetreeset.py

@@ -2,9 +2,8 @@ import pytest
 import json
 import os
 
-from pylabrobot.resources import Resource as ResourcePLR
 from unilabos.resources.graphio import resource_bioyond_to_plr
-from unilabos.ros.nodes.resource_tracker import ResourceTreeSet
+from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.registry.registry import lab_registry
 
 from unilabos.resources.bioyond.decks import BIOYOND_PolymerReactionStation_Deck

tests/ros/msgs/test_runner.py

@@ -11,10 +11,10 @@ import os
 # 添加项目根目录到路径
 sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))))
 
-# 导入测试模块
-from test.ros.msgs.test_basic import TestBasicFunctionality
-from test.ros.msgs.test_conversion import TestBasicConversion, TestMappingConversion
-from test.ros.msgs.test_mapping import TestTypeMapping, TestFieldMapping
+# 导入测试模块（统一从 tests 包获取）
+from tests.ros.msgs.test_basic import TestBasicFunctionality
+from tests.ros.msgs.test_conversion import TestBasicConversion, TestMappingConversion
+from tests.ros.msgs.test_mapping import TestTypeMapping, TestFieldMapping
 
 
 def run_tests():

tests/workflow/test.json

@@ -0,0 +1,213 @@
+{
+  "workflow": [
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines",
+        "targets": "Liquid_1",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines",
+        "targets": "Liquid_2",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines",
+        "targets": "Liquid_3",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_2",
+        "targets": "Liquid_4",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_2",
+        "targets": "Liquid_5",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_2",
+        "targets": "Liquid_6",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_3",
+        "targets": "dest_set",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_3",
+        "targets": "dest_set_2",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    },
+    {
+      "action": "transfer_liquid",
+      "action_args": {
+        "sources": "cell_lines_3",
+        "targets": "dest_set_3",
+        "asp_vol": 100.0,
+        "dis_vol": 74.75,
+        "asp_flow_rate": 94.0,
+        "dis_flow_rate": 95.5
+      }
+    }
+  ],
+  "reagent": {
+    "Liquid_1": {
+      "slot": 1,
+      "well": [
+        "A4",
+        "A7",
+        "A10"
+      ],
+      "labware": "rep 1"
+    },
+    "Liquid_4": {
+      "slot": 1,
+      "well": [
+        "A4",
+        "A7",
+        "A10"
+      ],
+      "labware": "rep 1"
+    },
+    "dest_set": {
+      "slot": 1,
+      "well": [
+        "A4",
+        "A7",
+        "A10"
+      ],
+      "labware": "rep 1"
+    },
+    "Liquid_2": {
+      "slot": 2,
+      "well": [
+        "A3",
+        "A5",
+        "A8"
+      ],
+      "labware": "rep 2"
+    },
+    "Liquid_5": {
+      "slot": 2,
+      "well": [
+        "A3",
+        "A5",
+        "A8"
+      ],
+      "labware": "rep 2"
+    },
+    "dest_set_2": {
+      "slot": 2,
+      "well": [
+        "A3",
+        "A5",
+        "A8"
+      ],
+      "labware": "rep 2"
+    },
+    "Liquid_3": {
+      "slot": 3,
+      "well": [
+        "A4",
+        "A6",
+        "A10"
+      ],
+      "labware": "rep 3"
+    },
+    "Liquid_6": {
+      "slot": 3,
+      "well": [
+        "A4",
+        "A6",
+        "A10"
+      ],
+      "labware": "rep 3"
+    },
+    "dest_set_3": {
+      "slot": 3,
+      "well": [
+        "A4",
+        "A6",
+        "A10"
+      ],
+      "labware": "rep 3"
+    },
+    "cell_lines": {
+      "slot": 4,
+      "well": [
+        "A1",
+        "A3",
+        "A5"
+      ],
+      "labware": "DRUG + YOYO-MEDIA"
+    },
+    "cell_lines_2": {
+      "slot": 4,
+      "well": [
+        "A1",
+        "A3",
+        "A5"
+      ],
+      "labware": "DRUG + YOYO-MEDIA"
+    },
+    "cell_lines_3": {
+      "slot": 4,
+      "well": [
+        "A1",
+        "A3",
+        "A5"
+      ],
+      "labware": "DRUG + YOYO-MEDIA"
+    }
+  }
+}

unilabos/__init__.py

@@ -1 +1 @@
-__version__ = "0.10.13"
+__version__ = "0.10.18"

unilabos/__main__.py

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

unilabos/app/backend.py

@@ -1,6 +1,6 @@
 import threading
 
-from unilabos.ros.nodes.resource_tracker import ResourceTreeSet
+from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.utils import logger
 
 

unilabos/app/main.py

@@ -1,13 +1,13 @@
 import argparse
 import asyncio
 import os
+import platform
 import shutil
 import signal
 import sys
 import threading
 import time
 from typing import Dict, Any, List
-
 import networkx as nx
 import yaml
 
@@ -17,9 +17,15 @@ unilabos_dir = os.path.dirname(os.path.dirname(current_dir))
 if unilabos_dir not in sys.path:
     sys.path.append(unilabos_dir)
 
+from unilabos.app.utils import cleanup_for_restart
 from unilabos.utils.banner_print import print_status, print_unilab_banner
 from unilabos.config.config import load_config, BasicConfig, HTTPConfig
 
+# Global restart flags (used by ws_client and web/server)
+_restart_requested: bool = False
+_restart_reason: str = ""
+
+
 def load_config_from_file(config_path):
     if config_path is None:
         config_path = os.environ.get("UNILABOS_BASICCONFIG_CONFIG_PATH", None)
@@ -41,7 +47,7 @@ def convert_argv_dashes_to_underscores(args: argparse.ArgumentParser):
     for i, arg in enumerate(sys.argv):
         for option_string in option_strings:
             if arg.startswith(option_string):
-                new_arg = arg[:2] + arg[2:len(option_string)].replace("-", "_") + arg[len(option_string):]
+                new_arg = arg[:2] + arg[2 : len(option_string)].replace("-", "_") + arg[len(option_string) :]
                 sys.argv[i] = new_arg
                 break
 
@@ -49,6 +55,8 @@ def convert_argv_dashes_to_underscores(args: argparse.ArgumentParser):
 def parse_args():
     """解析命令行参数"""
     parser = argparse.ArgumentParser(description="Start Uni-Lab Edge server.")
+    subparsers = parser.add_subparsers(title="Valid subcommands", dest="command")
+
     parser.add_argument("-g", "--graph", help="Physical setup graph file path.")
     parser.add_argument("-c", "--controllers", default=None, help="Controllers config file path.")
     parser.add_argument(
@@ -153,6 +161,62 @@ def parse_args():
         default=False,
         help="Complete registry information",
     )
+    parser.add_argument(
+        "--check_mode",
+        action="store_true",
+        default=False,
+        help="Run in check mode for CI: validates registry imports and ensures no file changes",
+    )
+    parser.add_argument(
+        "--no_update_feedback",
+        action="store_true",
+        help="Disable sending update feedback to server",
+    )
+    parser.add_argument(
+        "--test_mode",
+        action="store_true",
+        default=False,
+        help="Test mode: all actions simulate execution and return mock results without running real hardware",
+    )
+    # workflow upload subcommand
+    workflow_parser = subparsers.add_parser(
+        "workflow_upload",
+        aliases=["wf"],
+        help="Upload workflow from xdl/json/python files",
+    )
+    workflow_parser.add_argument(
+        "-f",
+        "--workflow_file",
+        type=str,
+        required=True,
+        help="Path to the workflow file (JSON format)",
+    )
+    workflow_parser.add_argument(
+        "-n",
+        "--workflow_name",
+        type=str,
+        default=None,
+        help="Workflow name, if not provided will use the name from file or filename",
+    )
+    workflow_parser.add_argument(
+        "--tags",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Tags for the workflow (space-separated)",
+    )
+    workflow_parser.add_argument(
+        "--published",
+        action="store_true",
+        default=False,
+        help="Whether to publish the workflow (default: False)",
+    )
+    workflow_parser.add_argument(
+        "--description",
+        type=str,
+        default="",
+        help="Workflow description, used when publishing the workflow",
+    )
     return parser
 
 
@@ -165,10 +229,12 @@ def main():
     args_dict = vars(args)
 
     # 环境检查 - 检查并自动安装必需的包 (可选)
-    if not args_dict.get("skip_env_check", False):
+    skip_env_check = args_dict.get("skip_env_check", False)
+    check_mode = args_dict.get("check_mode", False)
+
+    if not skip_env_check:
         from unilabos.utils.environment_check import check_environment
 
-        print_status("正在进行环境依赖检查...", "info")
         if not check_environment(auto_install=True):
             print_status("环境检查失败，程序退出", "error")
             os._exit(1)
@@ -177,49 +243,75 @@ def main():
 
     # 加载配置文件，优先加载config，然后从env读取
     config_path = args_dict.get("config")
-    if os.getcwd().endswith("unilabos_data"):
-        working_dir = os.path.abspath(os.getcwd())
-    else:
-        working_dir = os.path.abspath(os.path.join(os.getcwd(), "unilabos_data"))
 
-    if args_dict.get("working_dir"):
-        working_dir = args_dict.get("working_dir", "")
-        if config_path and not os.path.exists(config_path):
-            config_path = os.path.join(working_dir, "local_config.py")
-            if not os.path.exists(config_path):
-                print_status(
-                    f"当前工作目录 {working_dir} 未找到local_config.py，请通过 --config 传入 local_config.py 文件路径",
-                    "error",
-                )
-                os._exit(1)
+    # === 解析 working_dir ===
+    # 规则1: working_dir 传入 → 检测 unilabos_data 子目录，已是则不修改
+    # 规则2: 仅 config_path 传入 → 用其父目录作为 working_dir
+    # 规则4: 两者都传入 → 各用各的，但 working_dir 仍做 unilabos_data 子目录检测
+    raw_working_dir = args_dict.get("working_dir")
+    if raw_working_dir:
+        working_dir = os.path.abspath(raw_working_dir)
     elif config_path and os.path.exists(config_path):
-        working_dir = os.path.dirname(config_path)
-    elif os.path.exists(working_dir) and os.path.exists(os.path.join(working_dir, "local_config.py")):
-        config_path = os.path.join(working_dir, "local_config.py")
-    elif not config_path and (
-        not os.path.exists(working_dir) or not os.path.exists(os.path.join(working_dir, "local_config.py"))
-    ):
-        print_status(f"未指定config路径，可通过 --config 传入 local_config.py 文件路径", "info")
-        print_status(f"您是否为第一次使用？并将当前路径 {working_dir} 作为工作目录？ (Y/n)", "info")
-        if input() != "n":
-            os.makedirs(working_dir, exist_ok=True)
-            config_path = os.path.join(working_dir, "local_config.py")
-            shutil.copy(
-                os.path.join(os.path.dirname(os.path.dirname(__file__)), "config", "example_config.py"), config_path
-            )
-            print_status(f"已创建 local_config.py 路径： {config_path}", "info")
+        working_dir = os.path.dirname(os.path.abspath(config_path))
+    else:
+        working_dir = os.path.abspath(os.getcwd())
+
+    # unilabos_data 子目录自动检测
+    if os.path.basename(working_dir) != "unilabos_data":
+        unilabos_data_sub = os.path.join(working_dir, "unilabos_data")
+        if os.path.isdir(unilabos_data_sub):
+            working_dir = unilabos_data_sub
+        elif not raw_working_dir and not (config_path and os.path.exists(config_path)):
+            # 未显式指定路径，默认使用 cwd/unilabos_data
+            working_dir = os.path.abspath(os.path.join(os.getcwd(), "unilabos_data"))
+
+    # === 解析 config_path ===
+    if config_path and not os.path.exists(config_path):
+        # config_path 传入但不存在，尝试在 working_dir 中查找
+        candidate = os.path.join(working_dir, "local_config.py")
+        if os.path.exists(candidate):
+            config_path = candidate
+            print_status(f"在工作目录中发现配置文件: {config_path}", "info")
         else:
+            print_status(
+                f"配置文件 {config_path} 不存在，工作目录 {working_dir} 中也未找到 local_config.py，"
+                f"请通过 --config 传入 local_config.py 文件路径",
+                "error",
+            )
             os._exit(1)
-    # 加载配置文件
+    elif not config_path:
+        # 规则3: 未传入 config_path，尝试 working_dir/local_config.py
+        candidate = os.path.join(working_dir, "local_config.py")
+        if os.path.exists(candidate):
+            config_path = candidate
+            print_status(f"发现本地配置文件: {config_path}", "info")
+        else:
+            print_status(f"未指定config路径，可通过 --config 传入 local_config.py 文件路径", "info")
+            print_status(f"您是否为第一次使用？并将当前路径 {working_dir} 作为工作目录？ (Y/n)", "info")
+            if check_mode or input() != "n":
+                os.makedirs(working_dir, exist_ok=True)
+                config_path = os.path.join(working_dir, "local_config.py")
+                shutil.copy(
+                    os.path.join(os.path.dirname(os.path.dirname(__file__)), "config", "example_config.py"),
+                    config_path,
+                )
+                print_status(f"已创建 local_config.py 路径： {config_path}", "info")
+            else:
+                os._exit(1)
+
+    # 加载配置文件 (check_mode 跳过)
     print_status(f"当前工作目录为 {working_dir}", "info")
-    load_config_from_file(config_path)
+    if not check_mode:
+        load_config_from_file(config_path)
 
     # 根据配置重新设置日志级别
     from unilabos.utils.log import configure_logger, logger
 
     if hasattr(BasicConfig, "log_level"):
         logger.info(f"Log level set to '{BasicConfig.log_level}' from config file.")
-    configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
+    file_path = configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
+    if file_path is not None:
+        logger.info(f"[LOG_FILE] {file_path}")
 
     if args.addr != parser.get_default("addr"):
         if args.addr == "test":
@@ -241,9 +333,12 @@ def main():
     if args_dict.get("sk", ""):
         BasicConfig.sk = args_dict.get("sk", "")
         print_status("传入了sk参数，优先采用传入参数！", "info")
+    BasicConfig.working_dir = working_dir
+
+    workflow_upload = args_dict.get("command") in ("workflow_upload", "wf")
 
     # 使用远程资源启动
-    if args_dict["use_remote_resource"]:
+    if not workflow_upload and args_dict["use_remote_resource"]:
         print_status("使用远程资源启动", "info")
         from unilabos.app.web import http_client
 
@@ -256,15 +351,19 @@ def main():
 
     BasicConfig.port = args_dict["port"] if args_dict["port"] else BasicConfig.port
     BasicConfig.disable_browser = args_dict["disable_browser"] or BasicConfig.disable_browser
-    BasicConfig.working_dir = working_dir
     BasicConfig.is_host_mode = not args_dict.get("is_slave", False)
     BasicConfig.slave_no_host = args_dict.get("slave_no_host", False)
     BasicConfig.upload_registry = args_dict.get("upload_registry", False)
+    BasicConfig.no_update_feedback = args_dict.get("no_update_feedback", False)
+    BasicConfig.test_mode = args_dict.get("test_mode", False)
+    if BasicConfig.test_mode:
+        print_status("启用测试模式：所有动作将模拟执行，不调用真实硬件", "warning")
     BasicConfig.communication_protocol = "websocket"
-    machine_name = os.popen("hostname").read().strip()
+    machine_name = platform.node()
     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"]
+    BasicConfig.check_mode = check_mode
 
     from unilabos.resources.graphio import (
         read_node_link_json,
@@ -278,15 +377,41 @@ def main():
     from unilabos.app.web import start_server
     from unilabos.app.register import register_devices_and_resources
     from unilabos.resources.graphio import modify_to_backend_format
-    from unilabos.ros.nodes.resource_tracker import ResourceTreeSet, ResourceDict
+    from unilabos.resources.resource_tracker import ResourceTreeSet, ResourceDict
 
     # 显示启动横幅
     print_unilab_banner(args_dict)
 
-    # 注册表
-    lab_registry = build_registry(
-        args_dict["registry_path"], args_dict.get("complete_registry", False), args_dict["upload_registry"]
-    )
+    # 注册表 - check_mode 时强制启用 complete_registry
+    complete_registry = args_dict.get("complete_registry", False) or check_mode
+    lab_registry = build_registry(args_dict["registry_path"], complete_registry, BasicConfig.upload_registry)
+
+    # Check mode: complete_registry 完成后直接退出，git diff 检测由 CI workflow 执行
+    if check_mode:
+        print_status("Check mode: complete_registry 完成，退出", "info")
+        os._exit(0)
+
+    if BasicConfig.upload_registry:
+        # 设备注册到服务端 - 需要 ak 和 sk
+        if BasicConfig.ak and BasicConfig.sk:
+            print_status("开始注册设备到服务端...", "info")
+            try:
+                register_devices_and_resources(lab_registry)
+                print_status("设备注册完成", "info")
+            except Exception as e:
+                print_status(f"设备注册失败: {e}", "error")
+        else:
+            print_status("未提供 ak 和 sk，跳过设备注册", "info")
+    else:
+        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
+
+    # 处理 workflow_upload 子命令
+    if workflow_upload:
+        from unilabos.workflow.wf_utils import handle_workflow_upload_command
+
+        handle_workflow_upload_command(args_dict)
+        print_status("工作流上传完成，程序退出", "info")
+        os._exit(0)
 
     if not BasicConfig.ak or not BasicConfig.sk:
         print_status("后续运行必须拥有一个实验室，请前往 https://uni-lab.bohrium.com 注册实验室！", "warning")
@@ -359,7 +484,7 @@ def main():
     # 如果从远端获取了物料信息，则与本地物料进行同步
     if request_startup_json and "nodes" in request_startup_json:
         print_status("开始同步远端物料到本地...", "info")
-        remote_tree_set = ResourceTreeSet.from_raw_list(request_startup_json["nodes"])
+        remote_tree_set = ResourceTreeSet.from_raw_dict_list(request_startup_json["nodes"])
         resource_tree_set.merge_remote_resources(remote_tree_set)
         print_status("远端物料同步完成", "info")
 
@@ -368,20 +493,6 @@ def main():
     args_dict["devices_config"] = resource_tree_set
     args_dict["graph"] = graph_res.physical_setup_graph
 
-    if BasicConfig.upload_registry:
-        # 设备注册到服务端 - 需要 ak 和 sk
-        if BasicConfig.ak and BasicConfig.sk:
-            print_status("开始注册设备到服务端...", "info")
-            try:
-                register_devices_and_resources(lab_registry)
-                print_status("设备注册完成", "info")
-            except Exception as e:
-                print_status(f"设备注册失败: {e}", "error")
-        else:
-            print_status("未提供 ak 和 sk，跳过设备注册", "info")
-    else:
-        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
-
     if args_dict["controllers"] is not None:
         args_dict["controllers_config"] = yaml.safe_load(open(args_dict["controllers"], encoding="utf-8"))
     else:
@@ -396,6 +507,7 @@ def main():
         comm_client = get_communication_client()
         if "websocket" in args_dict["app_bridges"]:
             args_dict["bridges"].append(comm_client)
+
             def _exit(signum, frame):
                 comm_client.stop()
                 sys.exit(0)
@@ -437,16 +549,13 @@ def main():
                 resource_visualization.start()
             except OSError as e:
                 if "AMENT_PREFIX_PATH" in str(e):
-                    print_status(
-                        f"ROS 2环境未正确设置，跳过3D可视化启动。错误详情: {e}",
-                        "warning"
-                    )
+                    print_status(f"ROS 2环境未正确设置，跳过3D可视化启动。错误详情: {e}", "warning")
                     print_status(
                         "建议解决方案：\n"
                         "1. 激活Conda环境: conda activate unilab\n"
                         "2. 或使用 --backend simple 参数\n"
                         "3. 或使用 --visual disable 参数禁用可视化",
-                        "info"
+                        "info",
                     )
                 else:
                     raise
@@ -454,13 +563,19 @@ def main():
                 time.sleep(1)
         else:
             start_backend(**args_dict)
-            start_server(
+            restart_requested = start_server(
                 open_browser=not args_dict["disable_browser"],
                 port=BasicConfig.port,
             )
+            if restart_requested:
+                print_status("[Main] Restart requested, cleaning up...", "info")
+                cleanup_for_restart()
+                return
     else:
         start_backend(**args_dict)
-        start_server(
+
+        # 启动服务器（默认支持WebSocket触发重启）
+        restart_requested = start_server(
             open_browser=not args_dict["disable_browser"],
             port=BasicConfig.port,
         )

unilabos/app/model.py

@@ -54,6 +54,7 @@ class JobAddReq(BaseModel):
     action_type: str = Field(
         examples=["unilabos_msgs.action._str_single_input.StrSingleInput"], description="action type", default=""
     )
+    sample_material: dict = Field(examples=[{"string": "string"}], description="sample uuid to material uuid")
     action_args: dict = Field(examples=[{"string": "string"}], description="action arguments", default_factory=dict)
     task_id: str = Field(examples=["task_id"], description="task uuid (auto-generated if empty)", default="")
     job_id: str = Field(examples=["job_id"], description="goal uuid (auto-generated if empty)", default="")

unilabos/app/register.py

@@ -38,9 +38,9 @@ def register_devices_and_resources(lab_registry, gather_only=False) -> Optional[
             response = http_client.resource_registry({"resources": list(devices_to_register.values())})
             cost_time = time.time() - start_time
             if response.status_code in [200, 201]:
-                logger.info(f"[UniLab Register] 成功注册 {len(devices_to_register)} 个设备 {cost_time}ms")
+                logger.info(f"[UniLab Register] 成功注册 {len(devices_to_register)} 个设备 {cost_time}s")
             else:
-                logger.error(f"[UniLab Register] 设备注册失败: {response.status_code}, {response.text} {cost_time}ms")
+                logger.error(f"[UniLab Register] 设备注册失败: {response.status_code}, {response.text} {cost_time}s")
         except Exception as e:
             logger.error(f"[UniLab Register] 设备注册异常: {e}")
 
@@ -51,9 +51,9 @@ def register_devices_and_resources(lab_registry, gather_only=False) -> Optional[
             response = http_client.resource_registry({"resources": list(resources_to_register.values())})
             cost_time = time.time() - start_time
             if response.status_code in [200, 201]:
-                logger.info(f"[UniLab Register] 成功注册 {len(resources_to_register)} 个资源 {cost_time}ms")
+                logger.info(f"[UniLab Register] 成功注册 {len(resources_to_register)} 个资源 {cost_time}s")
             else:
-                logger.error(f"[UniLab Register] 资源注册失败: {response.status_code}, {response.text} {cost_time}ms")
+                logger.error(f"[UniLab Register] 资源注册失败: {response.status_code}, {response.text} {cost_time}s")
         except Exception as e:
             logger.error(f"[UniLab Register] 资源注册异常: {e}")
 

unilabos/app/utils.py

@@ -0,0 +1,176 @@
+"""
+UniLabOS 应用工具函数
+
+提供清理、重启等工具函数
+"""
+
+import glob
+import os
+import shutil
+import sys
+
+
+def patch_rclpy_dll_windows():
+    """在 Windows + conda 环境下为 rclpy 打 DLL 加载补丁"""
+    if sys.platform != "win32" or not os.environ.get("CONDA_PREFIX"):
+        return
+    try:
+        import rclpy
+
+        return
+    except ImportError as e:
+        if not str(e).startswith("DLL load failed"):
+            return
+    cp = os.environ["CONDA_PREFIX"]
+    impl = os.path.join(cp, "Lib", "site-packages", "rclpy", "impl", "implementation_singleton.py")
+    pyd = glob.glob(os.path.join(cp, "Lib", "site-packages", "rclpy", "_rclpy_pybind11*.pyd"))
+    if not os.path.exists(impl) or not pyd:
+        return
+    with open(impl, "r", encoding="utf-8") as f:
+        content = f.read()
+    lib_bin = os.path.join(cp, "Library", "bin").replace("\\", "/")
+    patch = f'# UniLabOS DLL Patch\nimport os,ctypes\nos.add_dll_directory("{lib_bin}") if hasattr(os,"add_dll_directory") else None\ntry: ctypes.CDLL("{pyd[0].replace(chr(92),"/")}")\nexcept: pass\n# End Patch\n'
+    shutil.copy2(impl, impl + ".bak")
+    with open(impl, "w", encoding="utf-8") as f:
+        f.write(patch + content)
+
+
+patch_rclpy_dll_windows()
+
+import gc
+import threading
+import time
+
+from unilabos.utils.banner_print import print_status
+
+
+def cleanup_for_restart() -> bool:
+    """
+    Clean up all resources for restart without exiting the process.
+
+    This function prepares the system for re-initialization by:
+    1. Stopping all communication clients
+    2. Destroying ROS nodes
+    3. Resetting singletons
+    4. Waiting for threads to finish
+
+    Returns:
+        bool: True if cleanup was successful, False otherwise
+    """
+    print_status("[Restart] Starting cleanup for restart...", "info")
+
+    # Step 1: Stop WebSocket communication client
+    print_status("[Restart] Step 1: Stopping WebSocket client...", "info")
+    try:
+        from unilabos.app.communication import get_communication_client
+
+        comm_client = get_communication_client()
+        if comm_client is not None:
+            comm_client.stop()
+            print_status("[Restart] WebSocket client stopped", "info")
+    except Exception as e:
+        print_status(f"[Restart] Error stopping WebSocket: {e}", "warning")
+
+    # Step 2: Get HostNode and cleanup ROS
+    print_status("[Restart] Step 2: Cleaning up ROS nodes...", "info")
+    try:
+        from unilabos.ros.nodes.presets.host_node import HostNode
+        import rclpy
+        from rclpy.timer import Timer
+
+        host_instance = HostNode.get_instance(timeout=5)
+        if host_instance is not None:
+            print_status(f"[Restart] Found HostNode: {host_instance.device_id}", "info")
+
+            # Gracefully shutdown background threads
+            print_status("[Restart] Shutting down background threads...", "info")
+            HostNode.shutdown_background_threads(timeout=5.0)
+            print_status("[Restart] Background threads shutdown complete", "info")
+
+            # Stop discovery timer
+            if hasattr(host_instance, "_discovery_timer") and isinstance(host_instance._discovery_timer, Timer):
+                host_instance._discovery_timer.cancel()
+                print_status("[Restart] Discovery timer cancelled", "info")
+
+            # Destroy device nodes
+            device_count = len(host_instance.devices_instances)
+            print_status(f"[Restart] Destroying {device_count} device instances...", "info")
+            for device_id, device_node in list(host_instance.devices_instances.items()):
+                try:
+                    if hasattr(device_node, "ros_node_instance") and device_node.ros_node_instance is not None:
+                        device_node.ros_node_instance.destroy_node()
+                        print_status(f"[Restart] Device {device_id} destroyed", "info")
+                except Exception as e:
+                    print_status(f"[Restart] Error destroying device {device_id}: {e}", "warning")
+
+            # Clear devices instances
+            host_instance.devices_instances.clear()
+            host_instance.devices_names.clear()
+
+            # Destroy host node
+            try:
+                host_instance.destroy_node()
+                print_status("[Restart] HostNode destroyed", "info")
+            except Exception as e:
+                print_status(f"[Restart] Error destroying HostNode: {e}", "warning")
+
+            # Reset HostNode state
+            HostNode.reset_state()
+            print_status("[Restart] HostNode state reset", "info")
+
+        # Shutdown executor first (to stop executor.spin() gracefully)
+        if hasattr(rclpy, "__executor") and rclpy.__executor is not None:
+            try:
+                rclpy.__executor.shutdown()
+                rclpy.__executor = None  # Clear for restart
+                print_status("[Restart] ROS executor shutdown complete", "info")
+            except Exception as e:
+                print_status(f"[Restart] Error shutting down executor: {e}", "warning")
+
+        # Shutdown rclpy
+        if rclpy.ok():
+            rclpy.shutdown()
+            print_status("[Restart] rclpy shutdown complete", "info")
+
+    except ImportError as e:
+        print_status(f"[Restart] ROS modules not available: {e}", "warning")
+    except Exception as e:
+        print_status(f"[Restart] Error in ROS cleanup: {e}", "warning")
+        return False
+
+    # Step 3: Reset communication client singleton
+    print_status("[Restart] Step 3: Resetting singletons...", "info")
+    try:
+        from unilabos.app import communication
+
+        if hasattr(communication, "_communication_client"):
+            communication._communication_client = None
+            print_status("[Restart] Communication client singleton reset", "info")
+    except Exception as e:
+        print_status(f"[Restart] Error resetting communication singleton: {e}", "warning")
+
+    # Step 4: Wait for threads to finish
+    print_status("[Restart] Step 4: Waiting for threads to finish...", "info")
+    time.sleep(3)  # Give threads time to finish
+
+    # Check remaining threads
+    remaining_threads = []
+    for t in threading.enumerate():
+        if t.name != "MainThread" and t.is_alive():
+            remaining_threads.append(t.name)
+
+    if remaining_threads:
+        print_status(
+            f"[Restart] Warning: {len(remaining_threads)} threads still running: {remaining_threads}", "warning"
+        )
+    else:
+        print_status("[Restart] All threads stopped", "info")
+
+    # Step 5: Force garbage collection
+    print_status("[Restart] Step 5: Running garbage collection...", "info")
+    gc.collect()
+    gc.collect()  # Run twice for weak references
+    print_status("[Restart] Garbage collection complete", "info")
+
+    print_status("[Restart] Cleanup complete. Ready for re-initialization.", "info")
+    return True

unilabos/app/web/client.py

@@ -3,15 +3,13 @@ HTTP客户端模块
 
 提供与远程服务器通信的客户端功能，只有host需要用
 """
-
+import gzip
 import json
 import os
-import time
-from threading import Thread
 from typing import List, Dict, Any, Optional
 
 import requests
-from unilabos.ros.nodes.resource_tracker import ResourceTreeSet
+from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.utils.log import info
 from unilabos.config.config import HTTPConfig, BasicConfig
 from unilabos.utils import logger
@@ -76,7 +74,8 @@ class HTTPClient:
             Dict[str, str]: 旧UUID到新UUID的映射关系 {old_uuid: new_uuid}
         """
         with open(os.path.join(BasicConfig.working_dir, "req_resource_tree_add.json"), "w", encoding="utf-8") as f:
-            f.write(json.dumps({"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}, indent=4))
+            payload = {"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}
+            f.write(json.dumps(payload, indent=4))
         # 从序列化数据中提取所有节点的UUID（保存旧UUID）
         old_uuids = {n.res_content.uuid: n for n in resources.all_nodes}
         if not self.initialized or first_add:
@@ -291,10 +290,17 @@ 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",
-            json=registry_data,
-            headers={"Authorization": f"Lab {self.auth}"},
+            data=compressed_body,
+            headers={
+                "Authorization": f"Lab {self.auth}",
+                "Content-Type": "application/json",
+                "Content-Encoding": "gzip",
+            },
             timeout=30,
         )
         if response.status_code not in [200, 201]:
@@ -335,6 +341,106 @@ class HTTPClient:
                 logger.error(f"响应内容: {response.text}")
         return None
 
+    def workflow_import(
+        self,
+        name: str,
+        workflow_uuid: str,
+        workflow_name: str,
+        nodes: List[Dict[str, Any]],
+        edges: List[Dict[str, Any]],
+        tags: Optional[List[str]] = None,
+        published: bool = False,
+        description: str = "",
+    ) -> Dict[str, Any]:
+        """
+        导入工作流到服务器，如果 published 为 True，则额外发起发布请求
+
+        Args:
+            name: 工作流名称（顶层）
+            workflow_uuid: 工作流UUID
+            workflow_name: 工作流名称（data内部）
+            nodes: 工作流节点列表
+            edges: 工作流边列表
+            tags: 工作流标签列表，默认为空列表
+            published: 是否发布工作流，默认为False
+            description: 工作流描述，发布时使用
+
+        Returns:
+            Dict: API响应数据，包含 code 和 data (uuid, name)
+        """
+        payload = {
+            "name": name,
+            "data": {
+                "workflow_uuid": workflow_uuid,
+                "workflow_name": workflow_name,
+                "nodes": nodes,
+                "edges": edges,
+                "tags": tags if tags is not None else [],
+            },
+        }
+        # 保存请求到文件
+        with open(os.path.join(BasicConfig.working_dir, "req_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(json.dumps(payload, indent=4, ensure_ascii=False))
+
+        response = requests.post(
+            f"{self.remote_addr}/lab/workflow/owner/import",
+            json=payload,
+            headers={"Authorization": f"Lab {self.auth}"},
+            timeout=60,
+        )
+        # 保存响应到文件
+        with open(os.path.join(BasicConfig.working_dir, "res_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(f"{response.status_code}" + "\n" + response.text)
+
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"导入工作流失败: {response.text}")
+                return res
+            # 导入成功后，如果需要发布则额外发起发布请求
+            if published:
+                imported_uuid = res.get("data", {}).get("uuid", workflow_uuid)
+                publish_res = self.workflow_publish(imported_uuid, description)
+                res["publish_result"] = publish_res
+            return res
+        else:
+            logger.error(f"导入工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+
+    def workflow_publish(self, workflow_uuid: str, description: str = "") -> Dict[str, Any]:
+        """
+        发布工作流
+
+        Args:
+            workflow_uuid: 工作流UUID
+            description: 工作流描述
+
+        Returns:
+            Dict: API响应数据
+        """
+        payload = {
+            "uuid": workflow_uuid,
+            "description": description,
+            "published": True,
+        }
+        logger.info(f"正在发布工作流: {workflow_uuid}")
+        response = requests.patch(
+            f"{self.remote_addr}/lab/workflow/owner",
+            json=payload,
+            headers={"Authorization": f"Lab {self.auth}"},
+            timeout=60,
+        )
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"发布工作流失败: {response.text}")
+            else:
+                logger.info(f"工作流发布成功: {workflow_uuid}")
+            return res
+        else:
+            logger.error(f"发布工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+
 
 # 创建默认客户端实例
 http_client = HTTPClient()

unilabos/app/web/controller.py

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

unilabos/app/web/server.py

@@ -6,7 +6,6 @@ Web服务器模块
 
 import webbrowser
 
-import uvicorn
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from starlette.responses import Response
@@ -96,7 +95,7 @@ def setup_server() -> FastAPI:
     return app
 
 
-def start_server(host: str = "0.0.0.0", port: int = 8002, open_browser: bool = True) -> None:
+def start_server(host: str = "0.0.0.0", port: int = 8002, open_browser: bool = True) -> bool:
     """
     启动服务器
 
@@ -104,7 +103,14 @@ def start_server(host: str = "0.0.0.0", port: int = 8002, open_browser: bool = T
         host: 服务器主机
         port: 服务器端口
         open_browser: 是否自动打开浏览器
+
+    Returns:
+        bool: True if restart was requested, False otherwise
     """
+    import threading
+    import time
+    from uvicorn import Config, Server
+
     # 设置服务器
     setup_server()
 
@@ -123,7 +129,37 @@ def start_server(host: str = "0.0.0.0", port: int = 8002, open_browser: bool = T
 
     # 启动服务器
     info(f"[Web] 启动FastAPI服务器: {host}:{port}")
-    uvicorn.run(app, host=host, port=port, log_config=log_config)
+
+    # 使用支持重启的模式
+    config = Config(app=app, host=host, port=port, log_config=log_config)
+    server = Server(config)
+
+    # 启动服务器线程
+    server_thread = threading.Thread(target=server.run, daemon=True, name="uvicorn_server")
+    server_thread.start()
+
+    info("[Web] Server started, monitoring for restart requests...")
+
+    # 监控重启标志
+    import unilabos.app.main as main_module
+
+    while server_thread.is_alive():
+        if hasattr(main_module, "_restart_requested") and main_module._restart_requested:
+            info(
+                f"[Web] Restart requested via WebSocket, reason: {getattr(main_module, '_restart_reason', 'unknown')}"
+            )
+            main_module._restart_requested = False
+
+            # 停止服务器
+            server.should_exit = True
+            server_thread.join(timeout=5)
+
+            info("[Web] Server stopped, ready for restart")
+            return True
+
+        time.sleep(1)
+
+    return False
 
 
 # 当脚本直接运行时启动服务器

unilabos/app/ws_client.py

@@ -23,7 +23,7 @@ from typing import Optional, Dict, Any, List
 from urllib.parse import urlparse
 from enum import Enum
 
-from jedi.inference.gradual.typing import TypedDict
+from typing_extensions import TypedDict
 
 from unilabos.app.model import JobAddReq
 from unilabos.ros.nodes.presets.host_node import HostNode
@@ -76,6 +76,7 @@ class JobInfo:
     start_time: float
     last_update_time: float = field(default_factory=time.time)
     ready_timeout: Optional[float] = None  # READY状态的超时时间
+    always_free: bool = False  # 是否为永久闲置动作(不受排队限制)
 
     def update_timestamp(self):
         """更新最后更新时间"""
@@ -127,6 +128,15 @@ class DeviceActionManager:
             # 总是将job添加到all_jobs中
             self.all_jobs[job_info.job_id] = job_info
 
+            # always_free的动作不受排队限制，直接设为READY
+            if job_info.always_free:
+                job_info.status = JobStatus.READY
+                job_info.update_timestamp()
+                job_info.set_ready_timeout(10)
+                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                logger.trace(f"[DeviceActionManager] Job {job_log} always_free, start immediately")
+                return True
+
             # 检查是否有正在执行或准备执行的任务
             if device_key in self.active_jobs:
                 # 有正在执行或准备执行的任务，加入队列
@@ -154,7 +164,7 @@ class DeviceActionManager:
             job_info.set_ready_timeout(10)  # 设置10秒超时
             self.active_jobs[device_key] = job_info
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-            logger.info(f"[DeviceActionManager] Job {job_log} can start immediately for {device_key}")
+            logger.trace(f"[DeviceActionManager] Job {job_log} can start immediately for {device_key}")
             return True
 
     def start_job(self, job_id: str) -> bool:
@@ -176,11 +186,15 @@ class DeviceActionManager:
                 logger.error(f"[DeviceActionManager] Job {job_log} is not in READY status, current: {job_info.status}")
                 return False
 
-            # 检查设备上是否是这个job
-            if device_key not in self.active_jobs or self.active_jobs[device_key].job_id != job_id:
-                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                logger.error(f"[DeviceActionManager] Job {job_log} is not the active job for {device_key}")
-                return False
+            # always_free的job不需要检查active_jobs
+            if not job_info.always_free:
+                # 检查设备上是否是这个job
+                if device_key not in self.active_jobs or self.active_jobs[device_key].job_id != job_id:
+                    job_log = format_job_log(
+                        job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name
+                    )
+                    logger.error(f"[DeviceActionManager] Job {job_log} is not the active job for {device_key}")
+                    return False
 
             # 开始执行任务，将状态从READY转换为STARTED
             job_info.status = JobStatus.STARTED
@@ -203,6 +217,13 @@ class DeviceActionManager:
             job_info = self.all_jobs[job_id]
             device_key = job_info.device_action_key
 
+            # always_free的job直接清理，不影响队列
+            if job_info.always_free:
+                job_info.status = JobStatus.ENDED
+                job_info.update_timestamp()
+                del self.all_jobs[job_id]
+                return None
+
             # 移除活跃任务
             if device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id:
                 del self.active_jobs[device_key]
@@ -210,8 +231,9 @@ class DeviceActionManager:
                 job_info.update_timestamp()
                 # 从all_jobs中移除已结束的job
                 del self.all_jobs[job_id]
-                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                logger.info(f"[DeviceActionManager] Job {job_log} ended for {device_key}")
+                # job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                # logger.debug(f"[DeviceActionManager] Job {job_log} ended for {device_key}")
+                pass
             else:
                 job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
                 logger.warning(f"[DeviceActionManager] Job {job_log} was not active for {device_key}")
@@ -227,15 +249,20 @@ class DeviceActionManager:
                 next_job_log = format_job_log(
                     next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
                 )
-                logger.info(f"[DeviceActionManager] Next job {next_job_log} can start for {device_key}")
+                logger.trace(f"[DeviceActionManager] Next job {next_job_log} can start for {device_key}")
                 return next_job
 
             return None
 
     def get_active_jobs(self) -> List[JobInfo]:
-        """获取所有正在执行的任务"""
+        """获取所有正在执行的任务(含active_jobs和always_free的STARTED job)"""
         with self.lock:
-            return list(self.active_jobs.values())
+            jobs = list(self.active_jobs.values())
+            # 补充 always_free 的 STARTED job(它们不在 active_jobs 中)
+            for job in self.all_jobs.values():
+                if job.always_free and job.status == JobStatus.STARTED and job not in jobs:
+                    jobs.append(job)
+            return jobs
 
     def get_queued_jobs(self) -> List[JobInfo]:
         """获取所有排队中的任务"""
@@ -260,6 +287,14 @@ class DeviceActionManager:
             job_info = self.all_jobs[job_id]
             device_key = job_info.device_action_key
 
+            # always_free的job直接清理
+            if job_info.always_free:
+                job_info.status = JobStatus.ENDED
+                del self.all_jobs[job_id]
+                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                logger.trace(f"[DeviceActionManager] Always-free job {job_log} cancelled")
+                return True
+
             # 如果是正在执行的任务
             if device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id:
                 # 清理active job状态
@@ -268,7 +303,7 @@ class DeviceActionManager:
                 # 从all_jobs中移除
                 del self.all_jobs[job_id]
                 job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                logger.info(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
+                logger.trace(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
 
                 # 启动下一个任务
                 if device_key in self.device_queues and self.device_queues[device_key]:
@@ -281,7 +316,7 @@ class DeviceActionManager:
                     next_job_log = format_job_log(
                         next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
                     )
-                    logger.info(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
+                    logger.trace(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
                 return True
 
             # 如果是排队中的任务
@@ -295,7 +330,7 @@ class DeviceActionManager:
                     job_log = format_job_log(
                         job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name
                     )
-                    logger.info(f"[DeviceActionManager] Queued job {job_log} cancelled for {device_key}")
+                    logger.trace(f"[DeviceActionManager] Queued job {job_log} cancelled for {device_key}")
                     return True
 
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
@@ -333,13 +368,18 @@ class DeviceActionManager:
         timeout_jobs = []
 
         with self.lock:
-            # 统计READY状态的任务数量
-            ready_jobs_count = sum(1 for job in self.active_jobs.values() if job.status == JobStatus.READY)
+            # 收集所有需要检查的 READY 任务(active_jobs + always_free READY jobs)
+            ready_candidates = list(self.active_jobs.values())
+            for job in self.all_jobs.values():
+                if job.always_free and job.status == JobStatus.READY and job not in ready_candidates:
+                    ready_candidates.append(job)
+
+            ready_jobs_count = sum(1 for job in ready_candidates if job.status == JobStatus.READY)
             if ready_jobs_count > 0:
                 logger.trace(f"[DeviceActionManager] Checking {ready_jobs_count} READY jobs for timeout")  # type: ignore  # noqa: E501
 
             # 找到所有超时的READY任务（只检测，不处理）
-            for job_info in self.active_jobs.values():
+            for job_info in ready_candidates:
                 if job_info.is_ready_timeout():
                     timeout_jobs.append(job_info)
                     job_log = format_job_log(
@@ -359,7 +399,7 @@ class MessageProcessor:
         self.device_manager = device_manager
         self.queue_processor = None  # 延迟设置
         self.websocket_client = None  # 延迟设置
-        self.session_id = ""
+        self.session_id = str(uuid.uuid4())[:6]  # 产生一个随机的session_id
 
         # WebSocket连接
         self.websocket = None
@@ -426,6 +466,7 @@ 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={
@@ -438,7 +479,7 @@ class MessageProcessor:
                     self.connected = True
                     self.reconnect_count = 0
 
-                    logger.info(f"[MessageProcessor] Connected to {self.websocket_url}")
+                    logger.trace(f"[MessageProcessor] Connected to {self.websocket_url}")
 
                     # 启动发送协程
                     send_task = asyncio.create_task(self._send_handler())
@@ -457,6 +498,18 @@ 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())
@@ -465,18 +518,19 @@ class MessageProcessor:
                 self.websocket = None
 
             # 重连逻辑
-            if self.is_running and self.reconnect_count < WSConfig.max_reconnect_attempts:
+            if not self.is_running:
+                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 {WSConfig.reconnect_interval}s "
+                    f"[MessageProcessor] Reconnecting in {backoff}s "
                     f"(attempt {self.reconnect_count}/{WSConfig.max_reconnect_attempts})"
                 )
-                await asyncio.sleep(WSConfig.reconnect_interval)
-            elif self.reconnect_count >= WSConfig.max_reconnect_attempts:
+                await asyncio.sleep(backoff)
+            else:
                 logger.error("[MessageProcessor] Max reconnection attempts reached")
                 break
-            else:
-                self.reconnect_count -= 1
 
     async def _message_handler(self):
         """处理接收到的消息"""
@@ -488,7 +542,20 @@ class MessageProcessor:
             async for message in self.websocket:
                 try:
                     data = json.loads(message)
-                    await self._process_message(data)
+                    message_type = data.get("action", "")
+                    message_data = data.get("data")
+                    if self.session_id and self.session_id == data.get("edge_session"):
+                        await self._process_message(message_type, message_data)
+                    else:
+                        if message_type.endswith("_material"):
+                            logger.trace(
+                                f"[MessageProcessor] 收到一条归属 {data.get('edge_session')} 的旧消息：{data}"
+                            )
+                            logger.debug(
+                                f"[MessageProcessor] 跳过了一条归属 {data.get('edge_session')} 的旧消息: {data.get('action')}"
+                            )
+                        else:
+                            await self._process_message(message_type, message_data)
                 except json.JSONDecodeError:
                     logger.error(f"[MessageProcessor] Invalid JSON received: {message}")
                 except Exception as e:
@@ -503,7 +570,7 @@ class MessageProcessor:
 
     async def _send_handler(self):
         """处理发送队列中的消息"""
-        logger.debug("[MessageProcessor] Send handler started")
+        logger.trace("[MessageProcessor] Send handler started")
 
         try:
             while self.connected and self.websocket:
@@ -531,7 +598,7 @@ class MessageProcessor:
                         try:
                             message_str = json.dumps(msg, ensure_ascii=False)
                             await self.websocket.send(message_str)
-                            logger.trace(f"[MessageProcessor] Message sent: {msg.get('action', 'unknown')}")  # type: ignore  # noqa: E501
+                            # logger.trace(f"[MessageProcessor] Message sent: {msg.get('action', 'unknown')}")  # type: ignore  # noqa: E501
                         except Exception as e:
                             logger.error(f"[MessageProcessor] Failed to send message: {str(e)}")
                             logger.error(traceback.format_exc())
@@ -554,12 +621,9 @@ class MessageProcessor:
         finally:
             logger.debug("[MessageProcessor] Send handler stopped")
 
-    async def _process_message(self, data: Dict[str, Any]):
+    async def _process_message(self, message_type: str, message_data: Dict[str, Any]):
         """处理收到的消息"""
-        message_type = data.get("action", "")
-        message_data = data.get("data")
-
-        logger.debug(f"[MessageProcessor] Processing message: {message_type}")
+        logger.trace(f"[MessageProcessor] Processing message: {message_type}")
 
         try:
             if message_type == "pong":
@@ -571,14 +635,19 @@ class MessageProcessor:
             elif message_type == "cancel_action" or message_type == "cancel_task":
                 await self._handle_cancel_action(message_data)
             elif message_type == "add_material":
+                # noinspection PyTypeChecker
                 await self._handle_resource_tree_update(message_data, "add")
             elif message_type == "update_material":
+                # noinspection PyTypeChecker
                 await self._handle_resource_tree_update(message_data, "update")
             elif message_type == "remove_material":
+                # noinspection PyTypeChecker
                 await self._handle_resource_tree_update(message_data, "remove")
-            elif message_type == "session_id":
-                self.session_id = message_data.get("session_id")
-                logger.info(f"[MessageProcessor] Session ID: {self.session_id}")
+            # elif message_type == "session_id":
+            #     self.session_id = message_data.get("session_id")
+            #     logger.info(f"[MessageProcessor] Session ID: {self.session_id}")
+            elif message_type == "request_restart":
+                await self._handle_request_restart(message_data)
             else:
                 logger.debug(f"[MessageProcessor] Unknown message type: {message_type}")
 
@@ -592,6 +661,24 @@ class MessageProcessor:
         if host_node:
             host_node.handle_pong_response(pong_data)
 
+    def _check_action_always_free(self, device_id: str, action_name: str) -> bool:
+        """检查该action是否标记为always_free，通过HostNode统一的_action_value_mappings查找"""
+        try:
+            host_node = HostNode.get_instance(0)
+            if not host_node:
+                return False
+            # noinspection PyProtectedMember
+            action_mappings = host_node._action_value_mappings.get(device_id)
+            if not action_mappings:
+                return False
+            # 尝试直接匹配或 auto- 前缀匹配
+            for key in [action_name, f"auto-{action_name}"]:
+                if key in action_mappings:
+                    return action_mappings[key].get("always_free", False)
+            return False
+        except Exception:
+            return False
+
     async def _handle_query_action_state(self, data: Dict[str, Any]):
         """处理query_action_state消息"""
         device_id = data.get("device_id", "")
@@ -606,6 +693,9 @@ class MessageProcessor:
 
         device_action_key = f"/devices/{device_id}/{action_name}"
 
+        # 检查action是否为always_free
+        action_always_free = self._check_action_always_free(device_id, action_name)
+
         # 创建任务信息
         job_info = JobInfo(
             job_id=job_id,
@@ -615,6 +705,7 @@ class MessageProcessor:
             device_action_key=device_action_key,
             status=JobStatus.QUEUE,
             start_time=time.time(),
+            always_free=action_always_free,
         )
 
         # 添加到设备管理器
@@ -626,13 +717,13 @@ class MessageProcessor:
             await self._send_action_state_response(
                 device_id, action_name, task_id, job_id, "query_action_status", True, 0
             )
-            logger.info(f"[MessageProcessor] Job {job_log} can start immediately")
+            logger.trace(f"[MessageProcessor] Job {job_log} can start immediately")
         else:
             # 需要排队
             await self._send_action_state_response(
                 device_id, action_name, task_id, job_id, "query_action_status", False, 10
             )
-            logger.info(f"[MessageProcessor] Job {job_log} queued")
+            logger.trace(f"[MessageProcessor] Job {job_log} queued")
 
             # 通知QueueProcessor有新的队列更新
             if self.queue_processor:
@@ -641,6 +732,8 @@ class MessageProcessor:
     async def _handle_job_start(self, data: Dict[str, Any]):
         """处理job_start消息"""
         try:
+            if not data.get("sample_material"):
+                data["sample_material"] = {}
             req = JobAddReq(**data)
 
             job_log = format_job_log(req.job_id, req.task_id, req.device_id, req.action)
@@ -672,6 +765,7 @@ class MessageProcessor:
                 queue_item,
                 action_type=req.action_type,
                 action_kwargs=req.action_args,
+                sample_material=req.sample_material,
                 server_info=req.server_info,
             )
 
@@ -836,9 +930,7 @@ class MessageProcessor:
                         device_action_groups[key_add] = []
                     device_action_groups[key_add].append(item["uuid"])
 
-                    logger.info(
-                        f"[MessageProcessor] Resource migrated: {item['uuid'][:8]} from {device_old_id} to {device_id}"
-                    )
+                    logger.info(f"[资源同步] 跨站Transfer: {item['uuid'][:8]} from {device_old_id} to {device_id}")
                 else:
                     # 正常update
                     key = (device_id, "update")
@@ -852,11 +944,13 @@ class MessageProcessor:
                     device_action_groups[key] = []
                 device_action_groups[key].append(item["uuid"])
 
-        logger.info(f"触发物料更新 {action} 分组数量: {len(device_action_groups)}, 总数量: {len(resource_uuid_list)}")
+        logger.trace(
+            f"[资源同步] 动作 {action} 分组数量: {len(device_action_groups)}, 总数量: {len(resource_uuid_list)}"
+        )
 
         # 为每个(device_id, action)创建独立的更新线程
         for (device_id, actual_action), items in device_action_groups.items():
-            logger.info(f"设备 {device_id} 物料更新 {actual_action} 数量: {len(items)}")
+            logger.trace(f"[资源同步] {device_id} 物料动作 {actual_action} 数量: {len(items)}")
 
             def _notify_resource_tree(dev_id, act, item_list):
                 try:
@@ -888,6 +982,51 @@ class MessageProcessor:
             )
             thread.start()
 
+    async def _handle_request_restart(self, data: Dict[str, Any]):
+        """
+        处理重启请求
+
+        当LabGo发送request_restart时，执行清理并触发重启
+        """
+        reason = data.get("reason", "unknown")
+        delay = data.get("delay", 2)  # 默认延迟2秒
+        logger.info(f"[MessageProcessor] Received restart request, reason: {reason}, delay: {delay}s")
+
+        # 发送确认消息
+        if self.websocket_client:
+            await self.websocket_client.send_message(
+                {"action": "restart_acknowledged", "data": {"reason": reason, "delay": delay}}
+            )
+
+        # 设置全局重启标志
+        import unilabos.app.main as main_module
+
+        main_module._restart_requested = True
+        main_module._restart_reason = reason
+
+        # 延迟后执行清理
+        await asyncio.sleep(delay)
+
+        # 在新线程中执行清理，避免阻塞当前事件循环
+        def do_cleanup():
+            import time
+
+            time.sleep(0.5)  # 给当前消息处理完成的时间
+            logger.info(f"[MessageProcessor] Starting cleanup for restart, reason: {reason}")
+            try:
+                from unilabos.app.utils import cleanup_for_restart
+
+                if cleanup_for_restart():
+                    logger.info("[MessageProcessor] Cleanup successful, main() will restart")
+                else:
+                    logger.error("[MessageProcessor] Cleanup failed")
+            except Exception as e:
+                logger.error(f"[MessageProcessor] Error during cleanup: {e}")
+
+        cleanup_thread = threading.Thread(target=do_cleanup, name="RestartCleanupThread", daemon=True)
+        cleanup_thread.start()
+        logger.info(f"[MessageProcessor] Restart cleanup scheduled")
+
     async def _send_action_state_response(
         self, device_id: str, action_name: str, task_id: str, job_id: str, typ: str, free: bool, need_more: int
     ):
@@ -965,7 +1104,7 @@ class QueueProcessor:
 
     def _run(self):
         """运行队列处理主循环"""
-        logger.debug("[QueueProcessor] Queue processor started")
+        logger.trace("[QueueProcessor] Queue processor started")
 
         while self.is_running:
             try:
@@ -1059,6 +1198,11 @@ class QueueProcessor:
         logger.debug(f"[QueueProcessor] Sending busy status for {len(queued_jobs)} queued jobs")
 
         for job_info in queued_jobs:
+            # 快照可能已过期：在遍历过程中 end_job() 可能已将此 job 移至 READY，
+            # 此时不应再发送 busy/need_more，否则会覆盖已发出的 free=True 通知
+            if job_info.status != JobStatus.QUEUE:
+                continue
+
             message = {
                 "action": "report_action_state",
                 "data": {
@@ -1074,7 +1218,7 @@ class QueueProcessor:
             success = self.message_processor.send_message(message)
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
             if success:
-                logger.debug(f"[QueueProcessor] Sent busy/need_more for queued job {job_log}")
+                logger.trace(f"[QueueProcessor] Sent busy/need_more for queued job {job_log}")
             else:
                 logger.warning(f"[QueueProcessor] Failed to send busy status for job {job_log}")
 
@@ -1097,7 +1241,7 @@ class QueueProcessor:
             job_info.action_name,
         )
 
-        logger.info(f"[QueueProcessor] Job {job_log} completed with status: {status}")
+        logger.trace(f"[QueueProcessor] Job {job_log} completed with status: {status}")
 
         # 结束任务，获取下一个可执行的任务
         next_job = self.device_manager.end_job(job_id)
@@ -1117,8 +1261,8 @@ class QueueProcessor:
                 },
             }
             self.message_processor.send_message(message)
-            next_job_log = format_job_log(next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name)
-            logger.info(f"[QueueProcessor] Notified next job {next_job_log} can start")
+            # next_job_log = format_job_log(next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name)
+            # logger.debug(f"[QueueProcessor] Notified next job {next_job_log} can start")
 
             # 立即触发下一轮状态检查
             self.notify_queue_update()
@@ -1175,7 +1319,6 @@ 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:
@@ -1188,13 +1331,11 @@ 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.info("[WebSocketClient] All threads started")
+        logger.trace("[WebSocketClient] All threads started")
 
     def stop(self) -> None:
         """停止WebSocket客户端"""
@@ -1243,7 +1384,7 @@ class WebSocketClient(BaseCommunicationClient):
             },
         }
         self.message_processor.send_message(message)
-        logger.debug(f"[WebSocketClient] Device status published: {device_id}.{property_name}")
+        # logger.trace(f"[WebSocketClient] Device status published: {device_id}.{property_name}")
 
     def publish_job_status(
         self, feedback_data: dict, item: QueueItem, status: str, return_info: Optional[dict] = None
@@ -1263,7 +1404,7 @@ class WebSocketClient(BaseCommunicationClient):
                 except (KeyError, AttributeError):
                     logger.warning(f"[WebSocketClient] Failed to remove job {item.job_id} from HostNode status")
 
-            logger.info(f"[WebSocketClient] Intercepting final status for job_id: {item.job_id} - {status}")
+            # logger.debug(f"[WebSocketClient] Intercepting final status for job_id: {item.job_id} - {status}")
 
             # 通知队列处理器job完成（包括timeout的job）
             self.queue_processor.handle_job_completed(item.job_id, status)
@@ -1285,7 +1426,7 @@ class WebSocketClient(BaseCommunicationClient):
         self.message_processor.send_message(message)
 
         job_log = format_job_log(item.job_id, item.task_id, item.device_id, item.action_name)
-        logger.debug(f"[WebSocketClient] Job status published: {job_log} - {status}")
+        logger.trace(f"[WebSocketClient] Job status published: {job_log} - {status}")
 
     def send_ping(self, ping_id: str, timestamp: float) -> None:
         """发送ping消息"""
@@ -1316,17 +1457,59 @@ class WebSocketClient(BaseCommunicationClient):
             logger.warning(f"[WebSocketClient] Failed to cancel job {job_log}")
 
     def publish_host_ready(self) -> None:
-        """发布host_node ready信号"""
+        """发布host_node ready信号，包含设备和动作信息"""
         if self.is_disabled or not self.is_connected():
             logger.debug("[WebSocketClient] Not connected, cannot publish host ready signal")
             return
 
+        # 收集设备信息
+        devices = []
+        machine_name = BasicConfig.machine_name
+
+        try:
+            host_node = HostNode.get_instance(0)
+            if host_node:
+                # 获取设备信息
+                for device_id, namespace in host_node.devices_names.items():
+                    device_key = (
+                        f"{namespace}/{device_id}" if namespace.startswith("/") else f"/{namespace}/{device_id}"
+                    )
+                    is_online = device_key in host_node._online_devices
+
+                    # 获取设备的动作信息
+                    actions = {}
+                    for action_id, client in host_node._action_clients.items():
+                        # action_id 格式: /namespace/device_id/action_name
+                        if device_id in action_id:
+                            action_name = action_id.split("/")[-1]
+                            actions[action_name] = {
+                                "action_path": action_id,
+                                "action_type": str(type(client).__name__),
+                            }
+
+                    devices.append(
+                        {
+                            "device_id": device_id,
+                            "namespace": namespace,
+                            "device_key": device_key,
+                            "is_online": is_online,
+                            "machine_name": host_node.device_machine_names.get(device_id, machine_name),
+                            "actions": actions,
+                        }
+                    )
+
+                logger.info(f"[WebSocketClient] Collected {len(devices)} devices for host_ready")
+        except Exception as e:
+            logger.warning(f"[WebSocketClient] Error collecting device info: {e}")
+
         message = {
             "action": "host_node_ready",
             "data": {
                 "status": "ready",
                 "timestamp": time.time(),
+                "machine_name": machine_name,
+                "devices": devices,
             },
         }
         self.message_processor.send_message(message)
-        logger.info("[WebSocketClient] Host node ready signal published")
+        logger.info(f"[WebSocketClient] Host node ready signal published with {len(devices)} devices")

unilabos/compile/pump_protocol.py

@@ -95,8 +95,29 @@ def get_vessel_liquid_volume(G: nx.DiGraph, vessel: str) -> float:
     return total_volume
 
 
-def is_integrated_pump(node_name):
-    return "pump" in node_name and "valve" in node_name
+def is_integrated_pump(node_class: str, node_name: str = "") -> bool:
+    """
+    判断是否为泵阀一体设备
+    """
+    class_lower = (node_class or "").lower()
+    name_lower = (node_name or "").lower()
+
+    if "pump" not in class_lower and "pump" not in name_lower:
+        return False
+
+    integrated_markers = [
+        "valve",
+        "pump_valve",
+        "pumpvalve",
+        "integrated",
+        "transfer_pump",
+    ]
+
+    for marker in integrated_markers:
+        if marker in class_lower or marker in name_lower:
+            return True
+
+    return False
 
 
 def find_connected_pump(G, valve_node):
@@ -186,7 +207,9 @@ def build_pump_valve_maps(G, pump_backbone):
     debug_print(f"🔧 过滤后的骨架: {filtered_backbone}")
 
     for node in filtered_backbone:
-        if is_integrated_pump(G.nodes[node]["class"]):
+        node_data = G.nodes.get(node, {})
+        node_class = node_data.get("class", "") or ""
+        if is_integrated_pump(node_class, node):
             pumps_from_node[node] = node
             valve_from_node[node] = node
             debug_print(f"  - 集成泵-阀: {node}")

unilabos/config/config.py

@@ -16,12 +16,16 @@ class BasicConfig:
     upload_registry = False
     machine_name = "undefined"
     vis_2d_enable = False
+    no_update_feedback = False
     enable_resource_load = True
     communication_protocol = "websocket"
     startup_json_path = None  # 填写绝对路径
     disable_browser = False  # 禁止浏览器自动打开
     port = 8002  # 本地HTTP服务
-    log_level: Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = "DEBUG"  # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    check_mode = False  # CI 检查模式，用于验证 registry 导入和文件一致性
+    test_mode = False  # 测试模式，所有动作不实际执行，返回模拟结果
+    # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    log_level: Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "DEBUG"
 
     @classmethod
     def auth_secret(cls):
@@ -65,13 +69,14 @@ def _update_config_from_module(module):
                     if not attr.startswith("_"):
                         setattr(obj, attr, getattr(getattr(module, name), attr))
 
+
 def _update_config_from_env():
     prefix = "UNILABOS_"
     for env_key, env_value in os.environ.items():
         if not env_key.startswith(prefix):
             continue
         try:
-            key_path = env_key[len(prefix):]  # Remove UNILAB_ prefix
+            key_path = env_key[len(prefix) :]  # Remove UNILAB_ prefix
             class_field = key_path.upper().split("_", 1)
             if len(class_field) != 2:
                 logger.warning(f"[ENV] 环境变量格式不正确：{env_key}")
@@ -141,5 +146,5 @@ def load_config(config_path=None):
             traceback.print_exc()
             exit(1)
     else:
-        config_path = os.path.join(os.path.dirname(__file__), "local_config.py")
+        config_path = os.path.join(os.path.dirname(__file__), "example_config.py")
         load_config(config_path)

unilabos/device_comms/coin_cell_assembly_workstation.py

@@ -6,7 +6,7 @@ Coin Cell Assembly Workstation
 """
 from typing import Dict, Any, List, Optional, Union
 
-from unilabos.ros.nodes.resource_tracker import DeviceNodeResourceTracker
+from unilabos.resources.resource_tracker import DeviceNodeResourceTracker
 from unilabos.device_comms.workstation_base import WorkstationBase, WorkflowInfo
 from unilabos.device_comms.workstation_communication import (
     WorkstationCommunicationBase, CommunicationConfig, CommunicationProtocol, CoinCellCommunication
@@ -61,7 +61,7 @@ class CoinCellAssemblyWorkstation(WorkstationBase):
         
         # 创建资源跟踪器（如果没有提供）
         if resource_tracker is None:
-            from unilabos.ros.nodes.resource_tracker import DeviceNodeResourceTracker
+            from unilabos.resources.resource_tracker import DeviceNodeResourceTracker
             resource_tracker = DeviceNodeResourceTracker()
         
         # 初始化基类

unilabos/device_comms/opcua_client/node/uniopcua.py

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

unilabos/devices/LICENSE

@@ -0,0 +1,73 @@
+Uni-Lab-OS软件许可使用准则
+
+
+本软件使用准则（以下简称"本准则"）旨在规范用户在使用Uni-Lab-OS软件（以下简称"本软件"）过程中的行为和义务。在下载、安装、使用或以任何方式访问本软件之前，请务必仔细阅读并理解以下条款和条件。若您不同意本准则的全部或部分内容，请您立即停止使用本软件。一旦您开始访问、下载、安装、使用本软件，即表示您已阅读、理解并同意接受本准则的约束。
+
+1、使用许可
+1.1 本软件的所有权及版权归北京深势科技有限公司（以下简称"深势科技"）所有。在遵守本准则的前提下，深势科技特此授予学术用户（以下简称"您"）一个全球范围内的、非排他性的、免版权费用的使用许可，可为了满足学术目的而使用本软件。
+
+1.2 本准则下授予的许可仅适用于本软件的二进制代码版本。您不对本软件源代码拥有任何权利。
+
+2、使用限制
+2.1 本准则仅授予学术用户出于学术目的使用本软件，任何商业组织、商业机构或其他非学术用户不得使用本软件，如果违反本条款，深势科技将保留一切追诉的权利。
+2.2 您将本软件用于任何商业行为，应取得深势科技的商业许可。
+2.3 您不得将本软件或任何形式的衍生作品用于任何商业目的，也不得将其出售、出租、转让、分发或以其他方式提供给任何第三方。您必须确保本软件的使用仅限于您个人学术研究，禁止您为任何其他实体的利益使用本软件（无论是否收费）。
+2.4 您不得以任何方式修改、破解、反编译、反汇编、反向工程、隔离、分离或以其他方式从任何程序或文档中提取源代码或试图发现本软件的源代码。您不得以任何方式去除、修改或屏蔽本软件中的任何版权、商标或其他专有权利声明。您不得使用本软件进行任何非法活动，包括但不限于侵犯他人的知识产权、隐私权等。
+2.5 您同意将本软件仅用于合法的学术目的，且遵守您所在国家或地区的法律法规，您将承担因违反法律法规而产生的一切法律责任。
+
+3、软件所有权
+本软件在此仅作使用许可，并非出售。本软件及与软件有关的全部文档的所有权及其他所有权利（包括但不限于知识产权和商业秘密），始终是深势科技的专有财产，您不拥有任何权利，但本准则下被明确授予的有限的使用许可权利除外。
+
+4、衍生作品传播规范
+若您传播基于Uni-Lab-OS程序修改形成的作品，须同时满足以下全部条件：
+4.1 作品必须包含显著声明，明确标注修改内容及修改日期；
+4.2 作品必须声明本作品依据本许可协议发布；
+4.3 必须将整个作品（包括修改部分）作为整体授予获取副本者本许可协议的保障，且该许可将自动延伸适用于作品全组件（无论其以何种形式打包）；
+4.4 若衍生作品含交互式用户界面：每个界面均须显示合规法律声明，若原始Uni-Lab-OS程序的交互界面未展示法律声明，您的衍生作品可免除此义务。
+
+5、提出建议
+您可以对本软件提出建议，前提是：
+（i）您声明并保证，该建议未侵害任何第三方的任何知识产权；
+（ii）您承认，深势科技有权使用该建议，但无使用该建议的义务；
+（iii）您授予深势科技一项非独占的、不可撤销的、可分许可的、无版权费的、全球范围的著作权许可，以复制、分发、传播、公开展示、公开表演、修改、翻译、基于其制作衍生作品、生产、制作、推销、销售、提供销售和/或以其他方式整体或部分地使用该建议和基于其的衍生作品，包括但不限于，通过将该建议整体或部分地纳入深势科技的软件和/或其他软件，以及在现存的或将来任何时候存在的任何媒介中或通过该媒介体现，以及为从事上述活动而授予多个分许可；
+（iv）您特此授予深势科技一项永久的、全球范围的、非独占性的、免费的、免特许权使用费的、不可撤销的专利许可，许可其制造、委托制造、使用、要约销售、销售、进口及以其他方式转让该建议和基于其的衍生专利。上述专利许可的适用范围仅限于以下专利权利要求：您有权许可的、且仅因您的建议本身，或因您的建议与所提交的本软件结合而必然构成侵权的专利权利要求。若任何实体针对您或其他实体提起专利诉讼（包括诉讼中的交叉诉讼或反诉），主张该建议或您所贡献的软件构成直接或间接专利侵权，则依据本协议授予的、针对该建议或软件的任何专利许可，自该诉讼提起之日起终止。
+（v）您放弃对该建议的任何权利或主张，深势科技无需承担任何义务、版税或基于知识产权或其他方面的限制。
+
+6、引用要求
+如您使用本软件获得的成果发表在出版物上，您应在成果中承认对Uni-Lab-OS软件的使用并标注权利人名称。引用 Uni-Lab-OS时请使用以下内容：
+@article{gao2025unilabos,
+	title = {UniLabOS: An AI-Native Operating System for Autonomous Laboratories},
+	doi = {10.48550/arXiv.2512.21766},
+	publisher = {arXiv},
+	author = {Gao, Jing and Chang, Junhan and Que, Haohui and Xiong, Yanfei and Zhang, Shixiang and Qi, Xianwei and Liu, Zhen and Wang, Jun-Jie and Ding, Qianjun and Li, Xinyu and Pan, Ziwei and Xie, Qiming and Yan, Zhuang and Yan, Junchi and Zhang, Linfeng},
+	year = {2025}
+}
+
+7、保留权利
+您认可，所有未被明确授予您的本软件的权利，无论是当前或今后存在的，均由深势科技予以保留，任何未经深势科技明确授权而使用本软件的行为将被视为侵权，深势科技有权追究侵权者的一切法律责任。
+
+8、保密信息
+您同意将本软件代码及相关文档视为深势科技的机密信息，您不会向任何第三方提供相关代码，并将采取合理审慎的使用态度来防止本软件代码及相关文档被泄露。
+
+9、无保证
+该软件是"按原样"提供的，没有任何明示或暗示的保证，不包含任何代码或规范没有缺陷、适销性、适用于特定目的或不侵犯第三方权利的保证。您同意您自主承担使用本软件或与本准则有关的全部风险。
+
+10、免责条款 
+在任何情况下，无论基于侵权（包括过失）、合同或其他法律理论，除非适用法律强制规定（如故意或重大过失行为）或另有书面协议，深势科技不对被许可人因软件许可、使用或无法使用软件所致损害承担责任（包括任何性质的直接、间接、特殊、偶发或后果性损害，例如但不限于商誉损失、停工损失、计算机故障或失灵造成的损害，以及其他一切商业损害或损失），即使深势科技已被告知发生此类损害的可能性亦不例外。
+被许可人在再分发软件或其衍生作品时，仅能以自身名义独立承担责任进行操作，不得代表深势科技或其他被许可人。
+
+11、终止
+如果您以任何方式违反本准则或未能遵守本准则的任何重要条款或条件，则您被授予的所有权利将自动终止。
+
+12、举报
+如果您认为有人违反了本准则，请向深势科技进行举报，深势科技将对您的身份进行严格保密，举报邮箱changjh@dp.tech。
+
+13、法律管辖
+本准则中的任何内容均不得解释为通过暗示、禁止反悔或其他方式授予本准则中授予的许可或权利以外的任何许可或权利。如果本准则的任何条款被认定为不可执行，则仅在必要的范围内对该条款进行修改，使其可执行。本准则应受中华人民共和国法律管辖，不适用法律冲突条款及《联合国国际货物销售合同公约》，因本准则产生的一切争议由北京市海淀区人民法院管辖。
+
+14、未来版本
+深势科技保留不经事先通知随时变更或停止本软件或本准则的权利。
+
+15、语言优先
+本准则同时具有中文版本和英文版本，如果英文版本和中文版本有冲突，以中文版本为准。
+

unilabos/devices/LICENSE_eng

@@ -0,0 +1,73 @@
+Uni-Lab-OS License Agreement
+
+Preamble
+This License Agreement (the "Agreement") is instituted to govern user conduct and obligations in relation to the utilization of the Uni-Lab-OS (the "Software"). By accessing, downloading, installing, or utilizing the Software in any manner, you hereby acknowledge that you have meticulously reviewed, comprehended, and consented to be legally bound by the terms herein. If you dissent from any provision of this Agreement, you must forthwith cease all interaction with the Software.
+
+1. Grant of License
+1.1 The proprietary rights to the Software are exclusively retained by Beijing DP Technology Co., Ltd. ("DP Technology"). Subject to full compliance with this Agreement, DP Technology hereby grants academic users ("Licensee") a worldwide, non-exclusive, royalty-free license to untilise the Software solely for non-commercial academic pursuits.
+
+1.2 The foregoing license applies exclusively to the Software's executable binary code. No rights whatsoever are conferred to the Software's source code.
+
+2. Usage Restrictions
+2.1 This license is restricted to academic users engaging in scholastic activities. Commercial entities, institutions, or any non-academic parties are expressly prohibited from utilizing the Software. Violations of this clause shall entitle DP Technology to pursue all available legal remedies.
+2.2 The Licensee shall obtain a commercial license from DP Technology for any commercial use of the Software.
+2.3 The Licensee shall not utilise the Software or any derivative works for commercial purposes, nor distribute, sublicense, lease, transfer, or otherwise disseminate the Software to third parties. The Licensee is strictly prohibited from utilizing the Software for the benefit of any third-party entity, whether gratuitously or otherwise.
+2.4 Reverse engineering, decompilation, disassembly, code isolation, or any attempt to derive source code from the Software is strictly prohibited. The Licensee shall not alter, circumvent, or remove copyright notices, trademarks, or proprietary legends embedded in the Software. Use of the Software for unlawful activities—including but not limited to intellectual property infringement or privacy violations—is categorically barred.
+2.5 The Licensee warrants that the Software shall be utilised solely for lawful academic purposes in compliance with applicable jurisdictional statutes. All legal liabilities arising from noncompliance shall be borne exclusively by the Licensee.
+
+3. Proprietary Rights
+This Agreement confers a license to utilise the Software, not a transfer of ownership. All intellectual property rights—including copyrights, patents, trade secrets, and documentation—remain the exclusive dominion of DP Technology. The Licensee acquires no entitlements beyond the limited usage privileges expressly delineated herein.
+
+4. Derivative Work
+You may convey a work based on the Software, or the modifications to produce it from the Software, provided that you meet all of these conditions:
+4.1 The work must carry prominent notices stating that you modified it, and giving a relevant date.
+4.2 The work must carry prominent notices stating that it is released under this License.
+4.3 You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+4.4 If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Software has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+5. Feedback and Proposals
+Licensees may submit proposals, suggestions, or improvements pertaining to the Software ("Feedback") under the following conditions:
+(a) Licensee represents and warrants that such Feedback does not infringe upon any third-party intellectual property rights;
+(b) Licensee acknowledges that DP Technology reserves the right, but assumes no obligation, to utilize such Feedback;
+(c) Licensee irrevocably grants DP Technology a non-exclusive, royalty-free, perpetual, worldwide, sublicensable copyright license to reproduce, distribute, modify, publicly perform or display, translate, create derivative works of, commercialize, and otherwise exploit the Feedback in any medium or format, whether now known or hereafter devised, including the right to grant multiple tiers of sublicenses to enable such activities;
+(d) Licensee hereby grants DP Technology a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Feedback and such Derivative Works, where such license applies only to those patent claimss licensable by Licensee that are necessarily infringed by the Feedback(s) alone or by comibination of the Feedback(s) with the Software to which such Feedback(s) were submitted. If any entity institutes patent litigation against Licensee or any other entity (including a cross-claim orcounterclaim in a lawsuit) alleging that the Feedback, or the Software to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted under this Agreement for the Feedback or Software shall terminate as of the date such litigation is filed.
+(e) Licensee hereby waives all claims, proprietary rights, or restrictions related to DP Technology's use of such Feedback.
+
+6. Citation Requirement
+If academic or research output generated using the Software is published, Licensee must explicitly acknowledge the use of Uni-Lab-OS and attribute ownership to DP Technology. The following citation must be included:
+@article{gao2025unilabos,
+	title = {UniLabOS: An AI-Native Operating System for Autonomous Laboratories},
+	doi = {10.48550/arXiv.2512.21766},
+	publisher = {arXiv},
+	author = {Gao, Jing and Chang, Junhan and Que, Haohui and Xiong, Yanfei and Zhang, Shixiang and Qi, Xianwei and Liu, Zhen and Wang, Jun-Jie and Ding, Qianjun and Li, Xinyu and Pan, Ziwei and Xie, Qiming and Yan, Zhuang and Yan, Junchi and Zhang, Linfeng},
+	year = {2025}
+}
+
+7. Reservation of Rights
+All rights not expressly granted herein, whether existing now or arising in the future, are exclusively reserved by DP Technology. Any unauthorized use of the Software beyond the scope of this Agreement constitutes infringement, and DP Technology reserves all legal rights to pursue remedies against violators.
+
+8. Confidentiality
+Licensee agrees to treat the Software's code, documentation, and related materials as confidential information. Licensee shall not disclose such materials to third parties and shall employ reasonable safeguards to prevent unauthorized access, dissemination, or misuse.
+
+9. Disclaimer of Warranties
+The software is provided "as is," without warranties of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, non-infringement, or error-free operation. Licensee accepts all risks associated with the use of the software.
+
+10. Limitation of Liability
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall DP Technology be liable to Licensee for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the software (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if DP Technology has been advised of the possibility of such damages.
+While redistributing the Software or Derivative Works thereof, Licensee may act only on Licensee's own behalf and on Licensee's sole responsibility, not on behalf of DP Technology or any other Licensee.
+
+11. Termination
+All rights granted herein shall terminate immediately and automatically if Licensee materially breaches any provision of this Agreement.
+
+12. Reporting Violations
+To report suspected violations of this Agreement, notify DP Technology via the designated email address: changjh@dp.tech. DP Technology shall maintain the confidentiality of the reporter's identity.
+
+13. Governing Law and Dispute Resolution
+This Agreement shall be governed by the laws of the People's Republic of China, excluding its conflict of laws principles and the United Nations Convention on Contracts for the International Sale of Goods. Any dispute arising from this Agreement shall be exclusively adjudicated by the Haidian District People's Court in Beijing.
+
+14. Amendments and Updates
+DP Technology reserves the right to modify, suspend, or terminate the Software or this Agreement at any time without prior notice.
+
+15. Language Priority
+This Agreement is provided in both Chinese and English. In the event of any discrepancy, the Chinese version shall prevail.
+

unilabos/devices/liquid_handling/biomek.py

@@ -13,7 +13,7 @@ from pylabrobot.resources import (
 import copy
 from unilabos_msgs.msg import Resource
 
-from unilabos.ros.nodes.resource_tracker import DeviceNodeResourceTracker  # type: ignore
+from unilabos.resources.resource_tracker import DeviceNodeResourceTracker  # type: ignore
 
 
 class LiquidHandlerBiomek:

unilabos/devices/liquid_handling/prcxi/prcxi.py

@@ -30,9 +30,32 @@ from pylabrobot.liquid_handling.standard import (
     ResourceMove,
     ResourceDrop,
 )
-from pylabrobot.resources import ResourceHolder, ResourceStack, Tip, Deck, Plate, Well, TipRack, Resource, Container, Coordinate, TipSpot, Trash, PlateAdapter, TubeRack
+from pylabrobot.resources import (
+    ResourceHolder,
+    ResourceStack,
+    Tip,
+    Deck,
+    Plate,
+    Well,
+    TipRack,
+    Resource,
+    Container,
+    Coordinate,
+    TipSpot,
+    Trash,
+    PlateAdapter,
+    TubeRack,
+)
 
-from unilabos.devices.liquid_handling.liquid_handler_abstract import LiquidHandlerAbstract, SimpleReturn
+from unilabos.devices.liquid_handling.liquid_handler_abstract import (
+    LiquidHandlerAbstract,
+    SimpleReturn,
+    SetLiquidReturn,
+    SetLiquidFromPlateReturn,
+    TransferLiquidReturn,
+)
+from unilabos.registry.placeholder_type import ResourceSlot
+from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
 
 
@@ -68,10 +91,103 @@ class PRCXI9300Deck(Deck):
     该类定义了 PRCXI 9300 的工作台布局和槽位信息。
     """
 
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, **kwargs):
-        super().__init__(name, size_x, size_y, size_z)
-        self.slots = [None] * 6  # PRCXI 9300 有 6 个槽位
-class PRCXI9300Container(Plate):
+    # T1-T16 默认位置 (4列×4行)
+    _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.sites: List[Dict[str, Any]] = [dict(s) for s in sites]
+        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)
+
+    def serialize(self) -> dict:
+        data = super().serialize()
+        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):
     """PRCXI 9300 的专用 Container 类，继承自 Plate，用于槽位定位和未知模块。
 
     该类定义了 PRCXI 9300 的工作台布局和槽位信息。
@@ -84,11 +200,10 @@ class PRCXI9300Container(Plate):
         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, ordering=ordering, model=model)
+        super().__init__(name, size_x, size_y, size_z, category=category, model=model)
         self._unilabos_state = {}
 
     def load_state(self, state: Dict[str, Any]) -> None:
@@ -99,74 +214,81 @@ class PRCXI9300Container(Plate):
     def serialize_state(self) -> Dict[str, Dict[str, Any]]:
         data = super().serialize_state()
         data.update(self._unilabos_state)
-        return data   
+        return data
+
+
 class PRCXI9300Plate(Plate):
-    """ 
+    """
     专用孔板类：
     1. 继承自 PLR 原生 Plate，保留所有物理特性。
     2. 增加 material_info 参数，用于在初始化时直接绑定 Unilab UUID。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "plate", 
-                 ordered_items: collections.OrderedDict = None, 
-                 ordering: Optional[collections.OrderedDict] = None,
-                 model: Optional[str] = None, 
-                 material_info: Optional[Dict[str, Any]] = None, 
-                 **kwargs):
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "plate",
+        ordered_items: collections.OrderedDict = None,
+        ordering: Optional[collections.OrderedDict] = None,
+        model: Optional[str] = None,
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
         # 如果 ordered_items 不为 None，直接使用
+        items = None
+        ordering_param = None
         if ordered_items is not None:
             items = ordered_items
         elif ordering is not None:
             # 检查 ordering 中的值是否是字符串（从 JSON 反序列化时的情况）
             # 如果是字符串，说明这是位置名称，需要让 Plate 自己创建 Well 对象
             # 我们只传递位置信息（键），不传递值，使用 ordering 参数
-            if ordering and isinstance(next(iter(ordering.values()), None), str):
-                # ordering 的值是字符串，只使用键（位置信息）创建新的 OrderedDict
-                # 传递 ordering 参数而不是 ordered_items，让 Plate 自己创建 Well 对象
-                items = None
-                # 使用 ordering 参数，只包含位置信息（键）
-                ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
+            if ordering:
+                values = list(ordering.values())
+                value = values[0]
+                if isinstance(value, str):
+                    # ordering 的值是字符串，只使用键（位置信息）创建新的 OrderedDict
+                    # 传递 ordering 参数而不是 ordered_items，让 Plate 自己创建 Well 对象
+                    items = None
+                    # 使用 ordering 参数，只包含位置信息（键）
+                    ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
+                elif value is None:
+                    ordering_param = ordering
             else:
                 # ordering 的值已经是对象，可以直接使用
                 items = ordering
                 ordering_param = None
-        else:
-            items = None
-            ordering_param = None
-        
+
         # 根据情况传递不同的参数
         if items is not None:
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordered_items=items,
-                             category=category,
-                             model=model, **kwargs)
+            super().__init__(
+                name, size_x, size_y, size_z, ordered_items=items, category=category, model=model, **kwargs
+            )
         elif ordering_param is not None:
             # 传递 ordering 参数，让 Plate 自己创建 Well 对象
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordering=ordering_param,
-                             category=category,
-                             model=model, **kwargs)
+            super().__init__(
+                name, size_x, size_y, size_z, ordering=ordering_param, category=category, model=model, **kwargs
+            )
         else:
-            super().__init__(name, size_x, size_y, size_z, 
-                             category=category,
-                             model=model, **kwargs)
-        
+            super().__init__(name, size_x, size_y, size_z, category=category, model=model, **kwargs)
+
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
-        
 
     def load_state(self, state: Dict[str, Any]) -> None:
         super().load_state(state)
         self._unilabos_state = state
 
-
     def serialize_state(self) -> Dict[str, Dict[str, Any]]:
         try:
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -179,35 +301,45 @@ class PRCXI9300Plate(Plate):
                         else:
                             # 打印日志提醒（可选）
                             # print(f"Warning: Removing non-serializable key {mk} from {self.name}")
-                            pass 
+                            pass
                     safe_state[k] = safe_material
                 # 其他顶层属性也进行类型检查
                 elif isinstance(v, (str, int, float, bool, list, dict, type(None))):
                     safe_state[k] = v
-            
+
             data.update(safe_state)
-        return data            # 其他顶层属性也进行类型检查
+        return data  # 其他顶层属性也进行类型检查
+
+
 class PRCXI9300TipRack(TipRack):
-    """ 专用吸头盒类 """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "tip_rack", 
-                 ordered_items: collections.OrderedDict = None, 
-                 ordering: Optional[collections.OrderedDict] = None,
-                 model: Optional[str] = None,
-                 material_info: Optional[Dict[str, Any]] = None,
-                 **kwargs):
+    """专用吸头盒类"""
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "tip_rack",
+        ordered_items: collections.OrderedDict = None,
+        ordering: Optional[collections.OrderedDict] = None,
+        model: Optional[str] = None,
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
         # 如果 ordered_items 不为 None，直接使用
         if ordered_items is not None:
             items = ordered_items
         elif ordering is not None:
-            # 检查 ordering 中的值是否是字符串（从 JSON 反序列化时的情况）
-            # 如果是字符串，说明这是位置名称，需要让 TipRack 自己创建 Tip 对象
-            # 我们只传递位置信息（键），不传递值，使用 ordering 参数
-            if ordering and isinstance(next(iter(ordering.values()), None), str):
-                # ordering 的值是字符串，只使用键（位置信息）创建新的 OrderedDict
+            # 检查 ordering 中的值类型来决定如何处理：
+            # - 字符串值（从 JSON 反序列化）: 只用键创建 ordering_param
+            # - None 值（从第二次往返序列化）: 同样只用键创建 ordering_param
+            # - 对象值（已经是实际的 Resource 对象）: 直接作为 ordered_items 使用
+            first_val = next(iter(ordering.values()), None) if ordering else None
+            if not ordering or first_val is None or isinstance(first_val, str):
+                # ordering 的值是字符串或 None，只使用键（位置信息）创建新的 OrderedDict
                 # 传递 ordering 参数而不是 ordered_items，让 TipRack 自己创建 Tip 对象
                 items = None
-                # 使用 ordering 参数，只包含位置信息（键）
                 ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
             else:
                 # ordering 的值已经是对象，可以直接使用
@@ -216,27 +348,23 @@ class PRCXI9300TipRack(TipRack):
         else:
             items = None
             ordering_param = None
-        
+
         # 根据情况传递不同的参数
         if items is not None:
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordered_items=items,
-                             category=category, 
-                             model=model, **kwargs)
+            super().__init__(
+                name, size_x, size_y, size_z, ordered_items=items, category=category, model=model, **kwargs
+            )
         elif ordering_param is not None:
             # 传递 ordering 参数，让 TipRack 自己创建 Tip 对象
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordering=ordering_param,
-                             category=category, 
-                             model=model, **kwargs)
+            super().__init__(
+                name, size_x, size_y, size_z, ordering=ordering_param, category=category, model=model, **kwargs
+            )
         else:
-            super().__init__(name, size_x, size_y, size_z, 
-                             category=category, 
-                             model=model, **kwargs)
+            super().__init__(name, size_x, size_y, size_z, category=category, model=model, **kwargs)
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
-            
+
     def load_state(self, state: Dict[str, Any]) -> None:
         super().load_state(state)
         self._unilabos_state = state
@@ -246,7 +374,7 @@ class PRCXI9300TipRack(TipRack):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -259,26 +387,33 @@ class PRCXI9300TipRack(TipRack):
                         else:
                             # 打印日志提醒（可选）
                             # print(f"Warning: Removing non-serializable key {mk} from {self.name}")
-                            pass 
+                            pass
                     safe_state[k] = safe_material
                 # 其他顶层属性也进行类型检查
                 elif isinstance(v, (str, int, float, bool, list, dict, type(None))):
                     safe_state[k] = v
-            
+
             data.update(safe_state)
         return data
-    
+
+
 class PRCXI9300Trash(Trash):
     """PRCXI 9300 的专用 Trash 类，继承自 Trash。
 
     该类定义了 PRCXI 9300 的工作台布局和槽位信息。
     """
 
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "trash", 
-                 material_info: Optional[Dict[str, Any]] = None,
-                 **kwargs):
-        
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "trash",
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+
         if name != "trash":
             print(f"Warning: PRCXI9300Trash usually expects name='trash' for backend logic, but got '{name}'.")
         super().__init__(name, size_x, size_y, size_z, **kwargs)
@@ -297,7 +432,7 @@ class PRCXI9300Trash(Trash):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -310,42 +445,51 @@ class PRCXI9300Trash(Trash):
                         else:
                             # 打印日志提醒（可选）
                             # print(f"Warning: Removing non-serializable key {mk} from {self.name}")
-                            pass 
+                            pass
                     safe_state[k] = safe_material
                 # 其他顶层属性也进行类型检查
                 elif isinstance(v, (str, int, float, bool, list, dict, type(None))):
                     safe_state[k] = v
-            
+
             data.update(safe_state)
         return data
 
+
 class PRCXI9300TubeRack(TubeRack):
     """
     专用管架类：用于 EP 管架、试管架等。
     继承自 PLR 的 TubeRack，并支持注入 material_info (UUID)。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "tube_rack", 
-                 items: Optional[Dict[str, Any]] = None,
-                 ordered_items: Optional[OrderedDict] = None,
-                 ordering: Optional[OrderedDict] = None,
-                 model: Optional[str] = None,
-                 material_info: Optional[Dict[str, Any]] = None, 
-                 **kwargs):
-        
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "tube_rack",
+        items: Optional[Dict[str, Any]] = None,
+        ordered_items: Optional[OrderedDict] = None,
+        ordering: Optional[OrderedDict] = None,
+        model: Optional[str] = None,
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+
         # 如果 ordered_items 不为 None，直接使用
         if ordered_items is not None:
             items_to_pass = ordered_items
             ordering_param = None
         elif ordering is not None:
-            # 检查 ordering 中的值是否是字符串（从 JSON 反序列化时的情况）
-            # 如果是字符串，说明这是位置名称，需要让 TubeRack 自己创建 Tube 对象
-            # 我们只传递位置信息（键），不传递值，使用 ordering 参数
-            if ordering and isinstance(next(iter(ordering.values()), None), str):
-                # ordering 的值是字符串，只使用键（位置信息）创建新的 OrderedDict
+            # 检查 ordering 中的值类型来决定如何处理：
+            # - 字符串值（从 JSON 反序列化）: 只用键创建 ordering_param
+            # - None 值（从第二次往返序列化）: 同样只用键创建 ordering_param
+            # - 对象值（已经是实际的 Resource 对象）: 直接作为 ordered_items 使用
+            first_val = next(iter(ordering.values()), None) if ordering else None
+            if not ordering or first_val is None or isinstance(first_val, str):
+                # ordering 的值是字符串或 None，只使用键（位置信息）创建新的 OrderedDict
                 # 传递 ordering 参数而不是 ordered_items，让 TubeRack 自己创建 Tube 对象
                 items_to_pass = None
-                # 使用 ordering 参数，只包含位置信息（键）
                 ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
             else:
                 # ordering 的值已经是对象，可以直接使用
@@ -358,24 +502,16 @@ class PRCXI9300TubeRack(TubeRack):
         else:
             items_to_pass = None
             ordering_param = None
-        
+
         # 根据情况传递不同的参数
         if items_to_pass is not None:
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordered_items=items_to_pass, 
-                             model=model, 
-                             **kwargs)
+            super().__init__(name, size_x, size_y, size_z, ordered_items=items_to_pass, model=model, **kwargs)
         elif ordering_param is not None:
             # 传递 ordering 参数，让 TubeRack 自己创建 Tube 对象
-            super().__init__(name, size_x, size_y, size_z, 
-                             ordering=ordering_param,
-                             model=model, 
-                             **kwargs)
+            super().__init__(name, size_x, size_y, size_z, ordering=ordering_param, model=model, **kwargs)
         else:
-            super().__init__(name, size_x, size_y, size_z, 
-                             model=model, 
-                             **kwargs)
-        
+            super().__init__(name, size_x, size_y, size_z, model=model, **kwargs)
+
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
@@ -385,7 +521,7 @@ class PRCXI9300TubeRack(TubeRack):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -398,33 +534,41 @@ class PRCXI9300TubeRack(TubeRack):
                         else:
                             # 打印日志提醒（可选）
                             # print(f"Warning: Removing non-serializable key {mk} from {self.name}")
-                            pass 
+                            pass
                     safe_state[k] = safe_material
                 # 其他顶层属性也进行类型检查
                 elif isinstance(v, (str, int, float, bool, list, dict, type(None))):
                     safe_state[k] = v
-            
+
             data.update(safe_state)
         return data
 
+
 class PRCXI9300PlateAdapter(PlateAdapter):
     """
     专用板式适配器类：用于承载 Plate 的底座（如 PCR 适配器、磁吸架等）。
     支持注入 material_info (UUID)。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "plate_adapter", 
-                 model: Optional[str] = None,
-                 material_info: Optional[Dict[str, Any]] = None, 
-                 # 参数给予默认值 (标准96孔板尺寸)
-                 adapter_hole_size_x: float = 127.76, 
-                 adapter_hole_size_y: float = 85.48, 
-                 adapter_hole_size_z: float = 10.0, # 假设凹槽深度或板子放置高度
-                 dx: Optional[float] = None,
-                 dy: Optional[float] = None,
-                 dz: float = 0.0, # 默认Z轴偏移
-                 **kwargs):
-        
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "plate_adapter",
+        model: Optional[str] = None,
+        material_info: Optional[Dict[str, Any]] = None,
+        # 参数给予默认值 (标准96孔板尺寸)
+        adapter_hole_size_x: float = 127.76,
+        adapter_hole_size_y: float = 85.48,
+        adapter_hole_size_z: float = 10.0,  # 假设凹槽深度或板子放置高度
+        dx: Optional[float] = None,
+        dy: Optional[float] = None,
+        dz: float = 0.0,  # 默认Z轴偏移
+        **kwargs,
+    ):
+
         # 自动居中计算：如果未指定 dx/dy，则根据适配器尺寸和孔尺寸计算居中位置
         if dx is None:
             dx = (size_x - adapter_hole_size_x) / 2
@@ -432,20 +576,20 @@ class PRCXI9300PlateAdapter(PlateAdapter):
             dy = (size_y - adapter_hole_size_y) / 2
 
         super().__init__(
-            name=name, 
-            size_x=size_x, 
-            size_y=size_y, 
-            size_z=size_z, 
+            name=name,
+            size_x=size_x,
+            size_y=size_y,
+            size_z=size_z,
             dx=dx,
             dy=dy,
             dz=dz,
             adapter_hole_size_x=adapter_hole_size_x,
             adapter_hole_size_y=adapter_hole_size_y,
             adapter_hole_size_z=adapter_hole_size_z,
-            model=model, 
-            **kwargs
+            model=model,
+            **kwargs,
         )
-        
+
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
@@ -455,7 +599,7 @@ class PRCXI9300PlateAdapter(PlateAdapter):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -468,15 +612,16 @@ class PRCXI9300PlateAdapter(PlateAdapter):
                         else:
                             # 打印日志提醒（可选）
                             # print(f"Warning: Removing non-serializable key {mk} from {self.name}")
-                            pass 
+                            pass
                     safe_state[k] = safe_material
                 # 其他顶层属性也进行类型检查
                 elif isinstance(v, (str, int, float, bool, list, dict, type(None))):
                     safe_state[k] = v
-            
+
             data.update(safe_state)
         return data
 
+
 class PRCXI9300Handler(LiquidHandlerAbstract):
     support_touch_tip = False
 
@@ -505,12 +650,14 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         tablets_info = []
         count = 0
         for child in deck.children:
-            if child.children:
-                if "Material" in child.children[0]._unilabos_state:
-                    number = int(child.name.replace("T", ""))
-                    tablets_info.append(
-                        WorkTablets(Number=number, Code=f"T{number}", Material=child.children[0]._unilabos_state["Material"])
+            # 如果放其他类型的物料，是不可以的
+            if hasattr(child, "_unilabos_state") and "Material" in child._unilabos_state:
+                number = int(child.name.replace("T", ""))
+                tablets_info.append(
+                    WorkTablets(
+                        Number=number, Code=f"T{number}", Material=child._unilabos_state["Material"]
                     )
+                )
         if is_9320:
             print("当前设备是9320")
         # 始终初始化 step_mode 属性
@@ -529,9 +676,14 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         super().post_init(ros_node)
         self._unilabos_backend.post_init(ros_node)
 
-    def set_liquid(self, wells: list[Well], liquid_names: list[str], volumes: list[float]) -> SimpleReturn:
+    def set_liquid(self, wells: list[Well], liquid_names: list[str], volumes: list[float]) -> SetLiquidReturn:
         return super().set_liquid(wells, liquid_names, volumes)
 
+    def set_liquid_from_plate(
+        self, plate: ResourceSlot, well_names: list[str], liquid_names: list[str], volumes: list[float]
+    ) -> SetLiquidFromPlateReturn:
+        return super().set_liquid_from_plate(plate, well_names, liquid_names, volumes)
+
     def set_group(self, group_name: str, wells: List[Well], volumes: List[float]):
         return super().set_group(group_name, wells, volumes)
 
@@ -651,7 +803,7 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         mix_liquid_height: Optional[float] = None,
         delays: Optional[List[int]] = None,
         none_keys: List[str] = [],
-    ):
+    ) -> TransferLiquidReturn:
         return await super().transfer_liquid(
             sources,
             targets,
@@ -790,7 +942,8 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         return await self._unilabos_backend.shaker_action(time, module_no, amplitude, is_wait)
 
     async def heater_action(self, temperature: float, time: int):
-        return await self._unilabos_backend.heater_action(temperature, time)  
+        return await self._unilabos_backend.heater_action(temperature, time)
+
     async def move_plate(
         self,
         plate: Plate,
@@ -813,10 +966,11 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
             drop_direction,
             pickup_direction,
             pickup_distance_from_top,
-            target_plate_number = to,
+            target_plate_number=to,
             **backend_kwargs,
         )
 
+
 class PRCXI9300Backend(LiquidHandlerBackend):
     """PRCXI 9300 的后端实现，继承自 LiquidHandlerBackend。
 
@@ -869,31 +1023,28 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         self.steps_todo_list.append(step)
         return step
 
-
     async def pick_up_resource(self, pickup: ResourcePickup, **backend_kwargs):
-        
-        resource=pickup.resource
-        offset=pickup.offset
-        pickup_distance_from_top=pickup.pickup_distance_from_top
-        direction=pickup.direction
+
+        resource = pickup.resource
+        offset = pickup.offset
+        pickup_distance_from_top = pickup.pickup_distance_from_top
+        direction = pickup.direction
 
         plate_number = int(resource.parent.name.replace("T", ""))
         is_whole_plate = True
         balance_height = 0
         step = self.api_client.clamp_jaw_pick_up(plate_number, is_whole_plate, balance_height)
-        
+
         self.steps_todo_list.append(step)
         return step
 
     async def drop_resource(self, drop: ResourceDrop, **backend_kwargs):
 
-
         plate_number = None
         target_plate_number = backend_kwargs.get("target_plate_number", None)
         if target_plate_number is not None:
             plate_number = int(target_plate_number.name.replace("T", ""))
 
-
         is_whole_plate = True
         balance_height = 0
         if plate_number is None:
@@ -902,7 +1053,6 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         self.steps_todo_list.append(step)
         return step
 
-
     async def heater_action(self, temperature: float, time: int):
         print(f"\n\nHeater action: temperature={temperature}, time={time}\n\n")
         # return await self.api_client.heater_action(temperature, time)
@@ -959,7 +1109,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
                 error_code = self.api_client.get_error_code()
                 if error_code:
                     print(f"PRCXI9300 error code detected: {error_code}")
-                
+
                 # 清除错误代码
                 self.api_client.clear_error_code()
                 print("PRCXI9300 error code cleared.")
@@ -967,11 +1117,11 @@ class PRCXI9300Backend(LiquidHandlerBackend):
                 # 执行重置
                 print("Starting PRCXI9300 reset...")
                 self.api_client.call("IAutomation", "Reset")
-                
+
                 # 检查重置状态并等待完成
                 while not self.is_reset_ok:
                     print("Waiting for PRCXI9300 to reset...")
-                    if hasattr(self, '_ros_node') and self._ros_node is not None:
+                    if hasattr(self, "_ros_node") and self._ros_node is not None:
                         await self._ros_node.sleep(1)
                     else:
                         await asyncio.sleep(1)
@@ -989,7 +1139,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         """Pick up tips from the specified resource."""
         # INSERT_YOUR_CODE
         # Ensure use_channels is converted to a list of ints if it's an array
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1043,7 +1193,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def drop_tips(self, ops: List[Drop], use_channels: List[int] = None):
         """Pick up tips from the specified resource."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1126,7 +1276,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         none_keys: List[str] = [],
     ):
         """Mix liquid in the specified resources."""
-        
+
         plate_indexes = []
         for op in targets:
             deck = op.parent.parent.parent
@@ -1169,7 +1319,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def aspirate(self, ops: List[SingleChannelAspiration], use_channels: List[int] = None):
         """Aspirate liquid from the specified resources."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1226,7 +1376,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def dispense(self, ops: List[SingleChannelDispense], use_channels: List[int] = None):
         """Dispense liquid into the specified resources."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1407,7 +1557,6 @@ class PRCXI9300Api:
                 time.sleep(1)
         return success
 
-
     def call(self, service: str, method: str, params: Optional[list] = None) -> Any:
         payload = json.dumps(
             {"ServiceName": service, "MethodName": method, "Paramters": params or []}, separators=(",", ":")
@@ -1534,7 +1683,7 @@ class PRCXI9300Api:
         assist_fun5: str = "",
         liquid_method: str = "NormalDispense",
         axis: str = "Left",
-        ) -> Dict[str, Any]:
+    ) -> Dict[str, Any]:
         return {
             "StepAxis": axis,
             "Function": "Imbibing",
@@ -1612,7 +1761,7 @@ class PRCXI9300Api:
         assist_fun5: str = "",
         liquid_method: str = "NormalDispense",
         axis: str = "Left",
-        ) -> Dict[str, Any]:
+    ) -> Dict[str, Any]:
         return {
             "StepAxis": axis,
             "Function": "Blending",
@@ -1672,11 +1821,11 @@ class PRCXI9300Api:
             "LiquidDispensingMethod": liquid_method,
         }
 
-    def clamp_jaw_pick_up(self,
+    def clamp_jaw_pick_up(
+        self,
         plate_no: int,
         is_whole_plate: bool,
         balance_height: int,
-
     ) -> Dict[str, Any]:
         return {
             "StepAxis": "ClampingJaw",
@@ -1686,7 +1835,7 @@ class PRCXI9300Api:
             "HoleRow": 1,
             "HoleCol": 1,
             "BalanceHeight": balance_height,
-            "PlateOrHoleNum": f"T{plate_no}"
+            "PlateOrHoleNum": f"T{plate_no}",
         }
 
     def clamp_jaw_drop(
@@ -1694,7 +1843,6 @@ class PRCXI9300Api:
         plate_no: int,
         is_whole_plate: bool,
         balance_height: int,
-
     ) -> Dict[str, Any]:
         return {
             "StepAxis": "ClampingJaw",
@@ -1704,7 +1852,7 @@ class PRCXI9300Api:
             "HoleRow": 1,
             "HoleCol": 1,
             "BalanceHeight": balance_height,
-            "PlateOrHoleNum": f"T{plate_no}"
+            "PlateOrHoleNum": f"T{plate_no}",
         }
 
     def shaker_action(self, time: int, module_no: int, amplitude: int, is_wait: bool):
@@ -1717,6 +1865,7 @@ class PRCXI9300Api:
             "AssistFun4": is_wait,
         }
 
+
 class DefaultLayout:
 
     def __init__(self, product_name: str = "PRCXI9300"):
@@ -2095,7 +2244,9 @@ if __name__ == "__main__":
             size_y=50,
             size_z=10,
             category="tip_rack",
-            ordered_items=collections.OrderedDict({k: f"{child_prefix}_{k}" for k, v in tip_racks["ordering"].items()}),
+            ordered_items=collections.OrderedDict(
+                {k: f"{child_prefix}_{k}" for k, v in tip_racks["ordering"].items()}
+            ),
         )
         tip_rack_serialized = tip_rack.serialize()
         tip_rack_serialized["parent_name"] = deck.name
@@ -2290,43 +2441,37 @@ if __name__ == "__main__":
 
     A = tree_to_list([resource_plr_to_ulab(deck)])
     with open("deck.json", "w", encoding="utf-8") as f:
-        A.insert(0, {
-            "id": "PRCXI",
-            "name": "PRCXI",
-            "parent": None,
-            "type": "device",
-            "class": "liquid_handler.prcxi",
-            "position": {
-                "x": 0,
-                "y": 0,
-                "z": 0
-            },
-            "config": {
-                "deck": {
-                    "_resource_child_name": "PRCXI_Deck",
-                    "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck"
+        A.insert(
+            0,
+            {
+                "id": "PRCXI",
+                "name": "PRCXI",
+                "parent": None,
+                "type": "device",
+                "class": "liquid_handler.prcxi",
+                "position": {"x": 0, "y": 0, "z": 0},
+                "config": {
+                    "deck": {
+                        "_resource_child_name": "PRCXI_Deck",
+                        "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck",
+                    },
+                    "host": "192.168.0.121",
+                    "port": 9999,
+                    "timeout": 10.0,
+                    "axis": "Right",
+                    "channel_num": 1,
+                    "setup": False,
+                    "debug": True,
+                    "simulator": True,
+                    "matrix_id": "5de524d0-3f95-406c-86dd-f83626ebc7cb",
+                    "is_9320": True,
                 },
-                "host": "192.168.0.121",
-                "port": 9999,
-                "timeout": 10.0,
-                "axis": "Right",
-                "channel_num": 1,
-                "setup": False,
-                "debug": True,
-                "simulator": True,
-                "matrix_id": "5de524d0-3f95-406c-86dd-f83626ebc7cb",
-                "is_9320": True
+                "data": {},
+                "children": ["PRCXI_Deck"],
             },
-            "data": {},
-            "children": [
-                "PRCXI_Deck"
-            ]
-        })
+        )
         A[1]["parent"] = "PRCXI"
-        json.dump({
-            "nodes": A,
-            "links": []
-        }, f, indent=4, ensure_ascii=False)
+        json.dump({"nodes": A, "links": []}, f, indent=4, ensure_ascii=False)
 
     handler = PRCXI9300Handler(
         deck=deck,
@@ -2368,7 +2513,6 @@ if __name__ == "__main__":
     time.sleep(5)
     os._exit(0)
 
-
     prcxi_api = PRCXI9300Api(host="192.168.0.121", port=9999)
     prcxi_api.list_matrices()
     prcxi_api.get_all_materials()

unilabos/devices/liquid_handling/test_transfer_liquid.py

@@ -0,0 +1,13 @@
+"""
+说明：
+这里放一个“入口文件”，方便在 `unilabos/devices/liquid_handling` 目录下直接找到
+`transfer_liquid` 的测试。
+
+实际测试用例实现放在仓库标准测试目录：
+`tests/devices/liquid_handling/test_transfer_liquid.py`
+"""
+
+# 让 pytest 能从这里发现同一套测试（避免复制两份测试代码）。
+from tests.devices.liquid_handling.test_transfer_liquid import *  # noqa: F401,F403
+
+

unilabos/devices/motor/ZDT_X42.py

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

unilabos/devices/ros_dev/liquid_handler_joint_publisher.py

@@ -19,10 +19,11 @@ from rclpy.node import Node
 import re
 
 class LiquidHandlerJointPublisher(BaseROS2DeviceNode):
-    def __init__(self,resources_config:list, resource_tracker, rate=50, device_id:str = "lh_joint_publisher", **kwargs):
+    def __init__(self,resources_config:list, resource_tracker, rate=50, device_id:str = "lh_joint_publisher", registry_name: str = "lh_joint_publisher", **kwargs):
         super().__init__(
             driver_instance=self,
             device_id=device_id,
+            registry_name=registry_name,
             status_types={},
             action_value_mappings={},
             hardware_interface={},

unilabos/devices/separator/chinwe.py

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

unilabos/devices/separator/xkc_sensor.py

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

unilabos/devices/virtual/virtual_transferpump.py

@@ -15,35 +15,35 @@ class VirtualPumpMode(Enum):
 
 class VirtualTransferPump:
     """虚拟转移泵类 - 模拟泵的基本功能，无需实际硬件 🚰"""
-    
+
     _ros_node: BaseROS2DeviceNode
-    
+
     def __init__(self, device_id: str = None, config: dict = None, **kwargs):
         """
         初始化虚拟转移泵
-        
+
         Args:
             device_id: 设备ID
             config: 配置字典，包含max_volume, port等参数
             **kwargs: 其他参数，确保兼容性
         """
         self.device_id = device_id or "virtual_transfer_pump"
-        
+
         # 从config或kwargs中获取参数，确保类型正确
         if config:
-            self.max_volume = float(config.get('max_volume', 25.0))
-            self.port = config.get('port', 'VIRTUAL')
+            self.max_volume = float(config.get("max_volume", 25.0))
+            self.port = config.get("port", "VIRTUAL")
         else:
-            self.max_volume = float(kwargs.get('max_volume', 25.0))
-            self.port = kwargs.get('port', 'VIRTUAL')
-        
-        self._transfer_rate = float(kwargs.get('transfer_rate', 0))
-        self.mode = kwargs.get('mode', VirtualPumpMode.Normal)
-        
+            self.max_volume = float(kwargs.get("max_volume", 25.0))
+            self.port = kwargs.get("port", "VIRTUAL")
+
+        self._transfer_rate = float(kwargs.get("transfer_rate", 0))
+        self.mode = kwargs.get("mode", VirtualPumpMode.Normal)
+
         # 状态变量 - 确保都是正确类型
         self._status = "Idle"
         self._position = 0.0  # float
-        self._max_velocity = 5.0  # float 
+        self._max_velocity = 5.0  # float
         self._current_volume = 0.0  # float
 
         # 🚀 新增：快速模式设置 - 大幅缩短执行时间
@@ -52,14 +52,16 @@ class VirtualTransferPump:
         self._fast_dispense_time = 1.0  # 快速喷射时间（秒）
 
         self.logger = logging.getLogger(f"VirtualTransferPump.{self.device_id}")
-        
+
         print(f"🚰 === 虚拟转移泵 {self.device_id} 已创建 === ✨")
-        print(f"💨 快速模式: {'启用' if self._fast_mode else '禁用'} | 移动时间: {self._fast_move_time}s | 喷射时间: {self._fast_dispense_time}s")
+        print(
+            f"💨 快速模式: {'启用' if self._fast_mode else '禁用'} | 移动时间: {self._fast_move_time}s | 喷射时间: {self._fast_dispense_time}s"
+        )
         print(f"📊 最大容量: {self.max_volume}mL | 端口: {self.port}")
-    
+
     def post_init(self, ros_node: BaseROS2DeviceNode):
         self._ros_node = ros_node
-    
+
     async def initialize(self) -> bool:
         """初始化虚拟泵 🚀"""
         self.logger.info(f"🔧 初始化虚拟转移泵 {self.device_id} ✨")
@@ -68,33 +70,33 @@ class VirtualTransferPump:
         self._current_volume = 0.0
         self.logger.info(f"✅ 转移泵 {self.device_id} 初始化完成 🚰")
         return True
-    
+
     async def cleanup(self) -> bool:
         """清理虚拟泵 🧹"""
         self.logger.info(f"🧹 清理虚拟转移泵 {self.device_id} 🔚")
         self._status = "Idle"
         self.logger.info(f"✅ 转移泵 {self.device_id} 清理完成 💤")
         return True
-    
+
     # 基本属性
     @property
     def status(self) -> str:
         return self._status
-    
+
     @property
     def position(self) -> float:
         """当前柱塞位置 (ml) 📍"""
         return self._position
-    
+
     @property
     def current_volume(self) -> float:
         """当前注射器中的体积 (ml) 💧"""
         return self._current_volume
-    
+
     @property
     def max_velocity(self) -> float:
         return self._max_velocity
-    
+
     @property
     def transfer_rate(self) -> float:
         return self._transfer_rate
@@ -103,17 +105,17 @@ class VirtualTransferPump:
         """设置最大速度 (ml/s) 🌊"""
         self._max_velocity = max(0.1, min(50.0, velocity))  # 限制在合理范围内
         self.logger.info(f"🌊 设置最大速度为 {self._max_velocity} mL/s")
-    
+
     def get_status(self) -> str:
         """获取泵状态 📋"""
         return self._status
-    
+
     async def _simulate_operation(self, duration: float):
         """模拟操作延时 ⏱️"""
         self._status = "Busy"
         await self._ros_node.sleep(duration)
         self._status = "Idle"
-    
+
     def _calculate_duration(self, volume: float, velocity: float = None) -> float:
         """
         计算操作持续时间 ⏰
@@ -121,10 +123,10 @@ class VirtualTransferPump:
         """
         if velocity is None:
             velocity = self._max_velocity
-        
+
         # 📊 计算理论时间（用于日志显示）
         theoretical_duration = abs(volume) / velocity
-        
+
         # 🚀 如果启用快速模式，使用固定的快速时间
         if self._fast_mode:
             # 根据操作类型选择快速时间
@@ -132,13 +134,13 @@ class VirtualTransferPump:
                 actual_duration = self._fast_move_time
             else:  # 很小的操作
                 actual_duration = 0.5
-            
+
             self.logger.debug(f"⚡ 快速模式: 理论时间 {theoretical_duration:.2f}s → 实际时间 {actual_duration:.2f}s")
             return actual_duration
         else:
             # 正常模式使用理论时间
             return theoretical_duration
-    
+
     def _calculate_display_duration(self, volume: float, velocity: float = None) -> float:
         """
         计算显示用的持续时间（用于日志） 📊
@@ -147,16 +149,16 @@ class VirtualTransferPump:
         if velocity is None:
             velocity = self._max_velocity
         return abs(volume) / velocity
-    
+
     # 新的set_position方法 - 专门用于SetPumpPosition动作
     async def set_position(self, position: float, max_velocity: float = None):
         """
         移动到绝对位置 - 专门用于SetPumpPosition动作 🎯
-        
+
         Args:
             position (float): 目标位置 (ml)
             max_velocity (float): 移动速度 (ml/s)
-        
+
         Returns:
             dict: 符合SetPumpPosition.action定义的结果
         """
@@ -164,19 +166,19 @@ class VirtualTransferPump:
             # 验证并转换参数
             target_position = float(position)
             velocity = float(max_velocity) if max_velocity is not None else self._max_velocity
-            
+
             # 限制位置在有效范围内
             target_position = max(0.0, min(float(self.max_volume), target_position))
-            
+
             # 计算移动距离
             volume_to_move = abs(target_position - self._position)
-            
+
             # 📊 计算显示用的时间（用于日志）
             display_duration = self._calculate_display_duration(volume_to_move, velocity)
-            
+
             # ⚡ 计算实际执行时间（快速模式）
             actual_duration = self._calculate_duration(volume_to_move, velocity)
-            
+
             # 🎯 确定操作类型和emoji
             if target_position > self._position:
                 operation_type = "吸液"
@@ -187,28 +189,34 @@ class VirtualTransferPump:
             else:
                 operation_type = "保持"
                 operation_emoji = "📍"
-            
+
             self.logger.info(f"🎯 SET_POSITION: {operation_type} {operation_emoji}")
-            self.logger.info(f"  📍 位置: {self._position:.2f}mL → {target_position:.2f}mL (移动 {volume_to_move:.2f}mL)")
+            self.logger.info(
+                f"  📍 位置: {self._position:.2f}mL → {target_position:.2f}mL (移动 {volume_to_move:.2f}mL)"
+            )
             self.logger.info(f"  🌊 速度: {velocity:.2f} mL/s")
             self.logger.info(f"  ⏰ 预计时间: {display_duration:.2f}s")
-            
+
             if self._fast_mode:
                 self.logger.info(f"  ⚡ 快速模式: 实际用时 {actual_duration:.2f}s")
-            
+
             # 🚀 模拟移动过程
             if volume_to_move > 0.01:  # 只有当移动距离足够大时才显示进度
                 start_position = self._position
                 steps = 5 if actual_duration > 0.5 else 2  # 根据实际时间调整步数
                 step_duration = actual_duration / steps
-                
+
                 self.logger.info(f"🚀 开始{operation_type}... {operation_emoji}")
-                
+
                 for i in range(steps + 1):
                     # 计算当前位置和进度
                     progress = (i / steps) * 100 if steps > 0 else 100
-                    current_pos = start_position + (target_position - start_position) * (i / steps) if steps > 0 else target_position
-                    
+                    current_pos = (
+                        start_position + (target_position - start_position) * (i / steps)
+                        if steps > 0
+                        else target_position
+                    )
+
                     # 更新状态
                     if i < steps:
                         self._status = f"{operation_type}中"
@@ -216,10 +224,10 @@ class VirtualTransferPump:
                     else:
                         self._status = "Idle"
                         status_emoji = "✅"
-                    
+
                     self._position = current_pos
                     self._current_volume = current_pos
-                    
+
                     # 显示进度（每25%或最后一步）
                     if i == 0:
                         self.logger.debug(f"  🔄 {operation_type}开始: {progress:.0f}%")
@@ -227,7 +235,7 @@ class VirtualTransferPump:
                         self.logger.debug(f"  🔄 {operation_type}进度: {progress:.0f}%")
                     elif i == steps:
                         self.logger.info(f"  ✅ {operation_type}完成: {progress:.0f}% | 当前位置: {current_pos:.2f}mL")
-                    
+
                     # 等待一小步时间
                     if i < steps and step_duration > 0:
                         await self._ros_node.sleep(step_duration)
@@ -236,25 +244,27 @@ class VirtualTransferPump:
                 self._position = target_position
                 self._current_volume = target_position
                 self.logger.info(f"  📍 微调完成: {target_position:.2f}mL")
-        
+
             # 确保最终位置准确
             self._position = target_position
             self._current_volume = target_position
             self._status = "Idle"
-            
+
             # 📊 最终状态日志
             if volume_to_move > 0.01:
-                self.logger.info(f"🎉 SET_POSITION 完成! 📍 最终位置: {self._position:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL")
-            
+                self.logger.info(
+                    f"🎉 SET_POSITION 完成! 📍 最终位置: {self._position:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL"
+                )
+
             # 返回符合action定义的结果
             return {
                 "success": True,
                 "message": f"✅ 成功移动到位置 {self._position:.2f}mL ({operation_type})",
                 "final_position": self._position,
                 "final_volume": self._current_volume,
-                "operation_type": operation_type
+                "operation_type": operation_type,
             }
-            
+
         except Exception as e:
             error_msg = f"❌ 设置位置失败: {str(e)}"
             self.logger.error(error_msg)
@@ -262,134 +272,136 @@ class VirtualTransferPump:
                 "success": False,
                 "message": error_msg,
                 "final_position": self._position,
-                "final_volume": self._current_volume
+                "final_volume": self._current_volume,
             }
-    
+
     # 其他泵操作方法
     async def pull_plunger(self, volume: float, velocity: float = None):
         """
         拉取柱塞（吸液） 📥
-        
+
         Args:
             volume (float): 要拉取的体积 (ml)
             velocity (float): 拉取速度 (ml/s)
         """
         new_position = min(self.max_volume, self._position + volume)
         actual_volume = new_position - self._position
-        
+
         if actual_volume <= 0:
             self.logger.warning("⚠️ 无法吸液 - 已达到最大容量")
             return
-        
+
         display_duration = self._calculate_display_duration(actual_volume, velocity)
         actual_duration = self._calculate_duration(actual_volume, velocity)
-        
+
         self.logger.info(f"📥 开始吸液: {actual_volume:.2f}mL")
         self.logger.info(f"  📍 位置: {self._position:.2f}mL → {new_position:.2f}mL")
         self.logger.info(f"  ⏰ 预计时间: {display_duration:.2f}s")
-        
+
         if self._fast_mode:
             self.logger.info(f"  ⚡ 快速模式: 实际用时 {actual_duration:.2f}s")
-        
+
         await self._simulate_operation(actual_duration)
-        
+
         self._position = new_position
         self._current_volume = new_position
-        
+
         self.logger.info(f"✅ 吸液完成: {actual_volume:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL")
 
     async def push_plunger(self, volume: float, velocity: float = None):
         """
         推出柱塞（排液） 📤
-        
+
         Args:
             volume (float): 要推出的体积 (ml)
             velocity (float): 推出速度 (ml/s)
         """
         new_position = max(0, self._position - volume)
         actual_volume = self._position - new_position
-        
+
         if actual_volume <= 0:
             self.logger.warning("⚠️ 无法排液 - 已达到最小容量")
             return
-        
+
         display_duration = self._calculate_display_duration(actual_volume, velocity)
         actual_duration = self._calculate_duration(actual_volume, velocity)
-        
+
         self.logger.info(f"📤 开始排液: {actual_volume:.2f}mL")
         self.logger.info(f"  📍 位置: {self._position:.2f}mL → {new_position:.2f}mL")
         self.logger.info(f"  ⏰ 预计时间: {display_duration:.2f}s")
-        
+
         if self._fast_mode:
             self.logger.info(f"  ⚡ 快速模式: 实际用时 {actual_duration:.2f}s")
-        
+
         await self._simulate_operation(actual_duration)
-        
+
         self._position = new_position
         self._current_volume = new_position
-        
+
         self.logger.info(f"✅ 排液完成: {actual_volume:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL")
 
     # 便捷操作方法
     async def aspirate(self, volume: float, velocity: float = None):
         """吸液操作 📥"""
         await self.pull_plunger(volume, velocity)
-    
+
     async def dispense(self, volume: float, velocity: float = None):
         """排液操作 📤"""
         await self.push_plunger(volume, velocity)
-    
+
     async def transfer(self, volume: float, aspirate_velocity: float = None, dispense_velocity: float = None):
         """转移操作（先吸后排） 🔄"""
         self.logger.info(f"🔄 开始转移操作: {volume:.2f}mL")
-        
+
         # 吸液
         await self.aspirate(volume, aspirate_velocity)
-        
+
         # 短暂停顿
         self.logger.debug("⏸️ 短暂停顿...")
         await self._ros_node.sleep(0.1)
-        
+
         # 排液
         await self.dispense(volume, dispense_velocity)
-    
+
     async def empty_syringe(self, velocity: float = None):
         """清空注射器"""
         await self.set_position(0, velocity)
-    
+
     async def fill_syringe(self, velocity: float = None):
         """充满注射器"""
         await self.set_position(self.max_volume, velocity)
-    
+
     async def stop_operation(self):
         """停止当前操作"""
         self._status = "Idle"
         self.logger.info("Operation stopped")
-    
+
     # 状态查询方法
     def get_position(self) -> float:
         """获取当前位置"""
         return self._position
-    
+
     def get_current_volume(self) -> float:
         """获取当前体积"""
         return self._current_volume
-    
+
     def get_remaining_capacity(self) -> float:
         """获取剩余容量"""
         return self.max_volume - self._current_volume
-    
+
     def is_empty(self) -> bool:
         """检查是否为空"""
         return self._current_volume <= 0.01  # 允许小量误差
-    
+
     def is_full(self) -> bool:
         """检查是否已满"""
         return self._current_volume >= (self.max_volume - 0.01)  # 允许小量误差
-    
+
     def __str__(self):
-        return f"VirtualTransferPump({self.device_id}: {self._current_volume:.2f}/{self.max_volume} ml, {self._status})"
-    
+        return (
+            f"VirtualTransferPump({self.device_id}: {self._current_volume:.2f}/{self.max_volume} ml, {self._status})"
+        )
+
     def __repr__(self):
         return self.__str__()
 
@@ -398,20 +410,20 @@ class VirtualTransferPump:
 async def demo():
     """虚拟泵使用示例"""
     pump = VirtualTransferPump("demo_pump", {"max_volume": 50.0})
-    
+
     await pump.initialize()
-    
+
     print(f"Initial state: {pump}")
-    
+
     # 测试set_position方法
     result = await pump.set_position(10.0, max_velocity=2.0)
     print(f"Set position result: {result}")
     print(f"After setting position to 10ml: {pump}")
-    
+
     # 吸液测试
     await pump.aspirate(5.0, velocity=2.0)
     print(f"After aspirating 5ml: {pump}")
-    
+
     # 清空测试
     result = await pump.set_position(0.0)
     print(f"Empty result: {result}")

unilabos/devices/virtual/workbench.py

@@ -0,0 +1,759 @@
+"""
+Virtual Workbench Device - 模拟工作台设备
+包含：
+- 1个机械臂 (每次操作3s, 独占锁)
+- 3个加热台 (每次加热10s, 可并行)
+
+工作流程：
+1. A1-A5 物料同时启动，竞争机械臂
+2. 机械臂将物料移动到空闲加热台
+3. 加热完成后，机械臂将物料移动到C1-C5
+
+注意：调用来自线程池，使用 threading.Lock 进行同步
+"""
+
+import logging
+import time
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+from enum import Enum
+from threading import Lock, RLock
+
+from typing_extensions import TypedDict
+
+from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
+from unilabos.utils.decorator import not_action, always_free
+from unilabos.resources.resource_tracker import SampleUUIDsType, LabSample, RETURN_UNILABOS_SAMPLES
+
+
+# ============ TypedDict 返回类型定义 ============
+
+
+class MoveToHeatingStationResult(TypedDict):
+    """move_to_heating_station 返回类型"""
+
+    success: bool
+    station_id: int
+    material_id: str
+    material_number: int
+    message: str
+    unilabos_samples: List[LabSample]
+
+
+class StartHeatingResult(TypedDict):
+    """start_heating 返回类型"""
+
+    success: bool
+    station_id: int
+    material_id: str
+    material_number: int
+    message: str
+    unilabos_samples: List[LabSample]
+
+
+class MoveToOutputResult(TypedDict):
+    """move_to_output 返回类型"""
+
+    success: bool
+    station_id: int
+    material_id: str
+    unilabos_samples: List[LabSample]
+
+
+class PrepareMaterialsResult(TypedDict):
+    """prepare_materials 返回类型 - 批量准备物料"""
+
+    success: bool
+    count: int
+    material_1: int  # 物料编号1
+    material_2: int  # 物料编号2
+    material_3: int  # 物料编号3
+    material_4: int  # 物料编号4
+    material_5: int  # 物料编号5
+    message: str
+    unilabos_samples: List[LabSample]
+
+
+# ============ 状态枚举 ============
+
+
+class HeatingStationState(Enum):
+    """加热台状态枚举"""
+
+    IDLE = "idle"  # 空闲
+    OCCUPIED = "occupied"  # 已放置物料，等待加热
+    HEATING = "heating"  # 加热中
+    COMPLETED = "completed"  # 加热完成，等待取走
+
+
+class ArmState(Enum):
+    """机械臂状态枚举"""
+
+    IDLE = "idle"  # 空闲
+    BUSY = "busy"  # 工作中
+
+
+@dataclass
+class HeatingStation:
+    """加热台数据结构"""
+
+    station_id: int
+    state: HeatingStationState = HeatingStationState.IDLE
+    current_material: Optional[str] = None  # 当前物料 (如 "A1", "A2")
+    material_number: Optional[int] = None  # 物料编号 (1-5)
+    heating_start_time: Optional[float] = None
+    heating_progress: float = 0.0
+
+
+class VirtualWorkbench:
+    """
+    Virtual Workbench Device - 虚拟工作台设备
+
+    模拟一个包含1个机械臂和3个加热台的工作站
+    - 机械臂操作耗时3秒，同一时间只能执行一个操作
+    - 加热台加热耗时10秒，3个加热台可并行工作
+
+    工作流:
+    1. 物料A1-A5并发启动（线程池），竞争机械臂使用权
+    2. 获取机械臂后，查找空闲加热台
+    3. 机械臂将物料放入加热台，开始加热
+    4. 加热完成后，机械臂将物料移动到目标位置Cn
+    """
+
+    _ros_node: BaseROS2DeviceNode
+
+    # 配置常量
+    ARM_OPERATION_TIME: float = 2  # 机械臂操作时间(秒)
+    HEATING_TIME: float = 60.0  # 加热时间(秒)
+    NUM_HEATING_STATIONS: int = 3  # 加热台数量
+
+    def __init__(self, device_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, **kwargs):
+        # 处理可能的不同调用方式
+        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 "virtual_workbench"
+        self.config = config or {}
+
+        self.logger = logging.getLogger(f"VirtualWorkbench.{self.device_id}")
+        self.data: Dict[str, Any] = {}
+
+        # 从config中获取可配置参数
+        self.ARM_OPERATION_TIME = float(self.config.get("arm_operation_time", self.ARM_OPERATION_TIME))
+        self.HEATING_TIME = float(self.config.get("heating_time", self.HEATING_TIME))
+        self.NUM_HEATING_STATIONS = int(self.config.get("num_heating_stations", self.NUM_HEATING_STATIONS))
+
+        # 机械臂状态和锁 (使用threading.Lock)
+        self._arm_lock = Lock()
+        self._arm_state = ArmState.IDLE
+        self._arm_current_task: Optional[str] = None
+
+        # 加热台状态 (station_id -> HeatingStation) - 立即初始化，不依赖initialize()
+        self._heating_stations: Dict[int, HeatingStation] = {
+            i: HeatingStation(station_id=i) for i in range(1, self.NUM_HEATING_STATIONS + 1)
+        }
+        self._stations_lock = RLock()  # 可重入锁，保护加热台状态
+
+        # 任务追踪
+        self._active_tasks: Dict[str, Dict[str, Any]] = {}  # material_id -> task_info
+        self._tasks_lock = Lock()
+
+        # 处理其他kwargs参数
+        skip_keys = {"arm_operation_time", "heating_time", "num_heating_stations"}
+        for key, value in kwargs.items():
+            if key not in skip_keys and not hasattr(self, key):
+                setattr(self, key, value)
+
+        self.logger.info(f"=== 虚拟工作台 {self.device_id} 已创建 ===")
+        self.logger.info(
+            f"机械臂操作时间: {self.ARM_OPERATION_TIME}s | "
+            f"加热时间: {self.HEATING_TIME}s | "
+            f"加热台数量: {self.NUM_HEATING_STATIONS}"
+        )
+
+    @not_action
+    def post_init(self, ros_node: BaseROS2DeviceNode):
+        """ROS节点初始化后回调"""
+        self._ros_node = ros_node
+
+    @not_action
+    def initialize(self) -> bool:
+        """初始化虚拟工作台"""
+        self.logger.info(f"初始化虚拟工作台 {self.device_id}")
+
+        # 重置加热台状态 (已在__init__中创建，这里重置为初始状态)
+        with self._stations_lock:
+            for station in self._heating_stations.values():
+                station.state = HeatingStationState.IDLE
+                station.current_material = None
+                station.material_number = None
+                station.heating_progress = 0.0
+
+        # 初始化状态
+        self.data.update(
+            {
+                "status": "Ready",
+                "arm_state": ArmState.IDLE.value,
+                "arm_current_task": None,
+                "heating_stations": self._get_stations_status(),
+                "active_tasks_count": 0,
+                "message": "工作台就绪",
+            }
+        )
+
+        self.logger.info(f"工作台初始化完成: {self.NUM_HEATING_STATIONS}个加热台就绪")
+        return True
+
+    @not_action
+    def cleanup(self) -> bool:
+        """清理虚拟工作台"""
+        self.logger.info(f"清理虚拟工作台 {self.device_id}")
+
+        self._arm_state = ArmState.IDLE
+        self._arm_current_task = None
+
+        with self._stations_lock:
+            self._heating_stations.clear()
+
+        with self._tasks_lock:
+            self._active_tasks.clear()
+
+        self.data.update(
+            {
+                "status": "Offline",
+                "arm_state": ArmState.IDLE.value,
+                "heating_stations": {},
+                "message": "工作台已关闭",
+            }
+        )
+        return True
+
+    def _get_stations_status(self) -> Dict[int, Dict[str, Any]]:
+        """获取所有加热台状态"""
+        with self._stations_lock:
+            return {
+                station_id: {
+                    "state": station.state.value,
+                    "current_material": station.current_material,
+                    "material_number": station.material_number,
+                    "heating_progress": station.heating_progress,
+                }
+                for station_id, station in self._heating_stations.items()
+            }
+
+    def _update_data_status(self, message: Optional[str] = None):
+        """更新状态数据"""
+        self.data.update(
+            {
+                "arm_state": self._arm_state.value,
+                "arm_current_task": self._arm_current_task,
+                "heating_stations": self._get_stations_status(),
+                "active_tasks_count": len(self._active_tasks),
+            }
+        )
+        if message:
+            self.data["message"] = message
+
+    def _find_available_heating_station(self) -> Optional[int]:
+        """查找空闲的加热台
+
+        Returns:
+            空闲加热台ID，如果没有则返回None
+        """
+        with self._stations_lock:
+            for station_id, station in self._heating_stations.items():
+                if station.state == HeatingStationState.IDLE:
+                    return station_id
+        return None
+
+    def _acquire_arm(self, task_description: str) -> bool:
+        """获取机械臂使用权（阻塞直到获取）
+
+        Args:
+            task_description: 任务描述，用于日志
+
+        Returns:
+            是否成功获取
+        """
+        self.logger.info(f"[{task_description}] 等待获取机械臂...")
+
+        # 阻塞等待获取锁
+        self._arm_lock.acquire()
+
+        self._arm_state = ArmState.BUSY
+        self._arm_current_task = task_description
+        self._update_data_status(f"机械臂执行: {task_description}")
+
+        self.logger.info(f"[{task_description}] 成功获取机械臂使用权")
+        return True
+
+    def _release_arm(self):
+        """释放机械臂"""
+        task = self._arm_current_task
+        self._arm_state = ArmState.IDLE
+        self._arm_current_task = None
+        self._arm_lock.release()
+        self._update_data_status(f"机械臂已释放 (完成: {task})")
+        self.logger.info(f"机械臂已释放 (完成: {task})")
+
+    def prepare_materials(
+        self,
+        sample_uuids: SampleUUIDsType,
+        count: int = 5,
+    ) -> PrepareMaterialsResult:
+        """
+        批量准备物料 - 虚拟起始节点
+
+        作为工作流的起始节点，生成指定数量的物料编号供后续节点使用。
+        输出5个handle (material_1 ~ material_5)，分别对应实验1~5。
+
+        Args:
+            count: 待生成的物料数量，默认5 (生成 A1-A5)
+
+        Returns:
+            PrepareMaterialsResult: 包含 material_1 ~ material_5 用于传递给 move_to_heating_station
+        """
+        # 生成物料列表 A1 - A{count}
+        materials = [i for i in range(1, count + 1)]
+
+        self.logger.info(f"[准备物料] 生成 {count} 个物料: " f"A1-A{count} -> material_1~material_{count}")
+
+        return {
+            "success": True,
+            "count": count,
+            "material_1": materials[0] if len(materials) > 0 else 0,
+            "material_2": materials[1] if len(materials) > 1 else 0,
+            "material_3": materials[2] if len(materials) > 2 else 0,
+            "material_4": materials[3] if len(materials) > 3 else 0,
+            "material_5": materials[4] if len(materials) > 4 else 0,
+            "message": f"已准备 {count} 个物料: A1-A{count}",
+            "unilabos_samples": [LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for sample_uuid, content in sample_uuids.items()]
+        }
+
+    def move_to_heating_station(
+        self,
+        sample_uuids: SampleUUIDsType,
+        material_number: int,
+    ) -> MoveToHeatingStationResult:
+        """
+        将物料从An位置移动到加热台
+
+        多线程并发调用时，会竞争机械臂使用权，并自动查找空闲加热台
+
+        Args:
+            material_number: 物料编号 (1-5)
+
+        Returns:
+            MoveToHeatingStationResult: 包含 station_id, material_number 等用于传递给下一个节点
+        """
+        # 根据物料编号生成物料ID
+        material_id = f"A{material_number}"
+        task_desc = f"移动{material_id}到加热台"
+        self.logger.info(f"[任务] {task_desc} - 开始执行")
+
+        # 记录任务
+        with self._tasks_lock:
+            self._active_tasks[material_id] = {
+                "status": "waiting_for_arm",
+                "start_time": time.time(),
+            }
+
+        try:
+            # 步骤1: 等待获取机械臂使用权(竞争)
+            with self._tasks_lock:
+                self._active_tasks[material_id]["status"] = "waiting_for_arm"
+            self._acquire_arm(task_desc)
+
+            # 步骤2: 查找空闲加热台
+            with self._tasks_lock:
+                self._active_tasks[material_id]["status"] = "finding_station"
+            station_id = None
+
+            # 循环等待直到找到空闲加热台
+            while station_id is None:
+                station_id = self._find_available_heating_station()
+                if station_id is None:
+                    self.logger.info(f"[{material_id}] 没有空闲加热台，等待中...")
+                    # 释放机械臂，等待后重试
+                    self._release_arm()
+                    time.sleep(0.5)
+                    self._acquire_arm(task_desc)
+
+            # 步骤3: 占用加热台 - 立即标记为OCCUPIED，防止其他任务选择同一加热台
+            with self._stations_lock:
+                self._heating_stations[station_id].state = HeatingStationState.OCCUPIED
+                self._heating_stations[station_id].current_material = material_id
+                self._heating_stations[station_id].material_number = material_number
+
+            # 步骤4: 模拟机械臂移动操作 (3秒)
+            with self._tasks_lock:
+                self._active_tasks[material_id]["status"] = "arm_moving"
+                self._active_tasks[material_id]["assigned_station"] = station_id
+            self.logger.info(f"[{material_id}] 机械臂正在移动到加热台{station_id}...")
+
+            time.sleep(self.ARM_OPERATION_TIME)
+
+            # 步骤5: 放入加热台完成
+            self._update_data_status(f"{material_id}已放入加热台{station_id}")
+            self.logger.info(f"[{material_id}] 已放入加热台{station_id} (用时{self.ARM_OPERATION_TIME}s)")
+
+            # 释放机械臂
+            self._release_arm()
+
+            with self._tasks_lock:
+                self._active_tasks[material_id]["status"] = "placed_on_station"
+
+            return {
+                "success": True,
+                "station_id": station_id,
+                "material_id": material_id,
+                "material_number": material_number,
+                "message": f"{material_id}已成功移动到加热台{station_id}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+        except Exception as e:
+            self.logger.error(f"[{material_id}] 移动失败: {str(e)}")
+            if self._arm_lock.locked():
+                self._release_arm()
+            return {
+                "success": False,
+                "station_id": -1,
+                "material_id": material_id,
+                "material_number": material_number,
+                "message": f"移动失败: {str(e)}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+    @always_free
+    def start_heating(
+        self,
+        sample_uuids: SampleUUIDsType,
+        station_id: int,
+        material_number: int,
+    ) -> StartHeatingResult:
+        """
+        启动指定加热台的加热程序
+
+        Args:
+            station_id: 加热台ID (1-3)，从 move_to_heating_station 的 handle 传入
+            material_number: 物料编号，从 move_to_heating_station 的 handle 传入
+
+        Returns:
+            StartHeatingResult: 包含 station_id, material_number 等用于传递给下一个节点
+        """
+        self.logger.info(f"[加热台{station_id}] 开始加热")
+
+        if station_id not in self._heating_stations:
+            return {
+                "success": False,
+                "station_id": station_id,
+                "material_id": "",
+                "material_number": material_number,
+                "message": f"无效的加热台ID: {station_id}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+        with self._stations_lock:
+            station = self._heating_stations[station_id]
+
+            if station.current_material is None:
+                return {
+                    "success": False,
+                    "station_id": station_id,
+                    "material_id": "",
+                    "material_number": material_number,
+                    "message": f"加热台{station_id}上没有物料",
+                    "unilabos_samples": [
+                        LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                        sample_uuid, content in sample_uuids.items()]
+                }
+
+            if station.state == HeatingStationState.HEATING:
+                return {
+                    "success": False,
+                    "station_id": station_id,
+                    "material_id": station.current_material,
+                    "material_number": material_number,
+                    "message": f"加热台{station_id}已经在加热中",
+                    "unilabos_samples": [
+                        LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                        sample_uuid, content in sample_uuids.items()]
+                }
+
+            material_id = station.current_material
+
+            # 开始加热
+            station.state = HeatingStationState.HEATING
+            station.heating_start_time = time.time()
+            station.heating_progress = 0.0
+
+        with self._tasks_lock:
+            if material_id in self._active_tasks:
+                self._active_tasks[material_id]["status"] = "heating"
+
+        self._update_data_status(f"加热台{station_id}开始加热{material_id}")
+
+        # 打印当前所有正在加热的台位
+        with self._stations_lock:
+            heating_list = [
+                f"加热台{sid}:{s.current_material}"
+                for sid, s in self._heating_stations.items()
+                if s.state == HeatingStationState.HEATING and s.current_material
+            ]
+        self.logger.info(f"[并行加热] 当前同时加热中: {', '.join(heating_list)}")
+
+        # 模拟加热过程
+        start_time = time.time()
+        last_countdown_log = start_time
+        while True:
+            elapsed = time.time() - start_time
+            remaining = max(0.0, self.HEATING_TIME - elapsed)
+            progress = min(100.0, (elapsed / self.HEATING_TIME) * 100)
+
+            with self._stations_lock:
+                self._heating_stations[station_id].heating_progress = progress
+
+            self._update_data_status(f"加热台{station_id}加热中: {progress:.1f}%")
+
+            # 每5秒打印一次倒计时
+            if time.time() - last_countdown_log >= 5.0:
+                self.logger.info(f"[加热台{station_id}] {material_id} 剩余 {remaining:.1f}s")
+                last_countdown_log = time.time()
+
+            if elapsed >= self.HEATING_TIME:
+                break
+
+            time.sleep(1.0)
+
+        # 加热完成
+        with self._stations_lock:
+            self._heating_stations[station_id].state = HeatingStationState.COMPLETED
+            self._heating_stations[station_id].heating_progress = 100.0
+
+        with self._tasks_lock:
+            if material_id in self._active_tasks:
+                self._active_tasks[material_id]["status"] = "heating_completed"
+
+        self._update_data_status(f"加热台{station_id}加热完成")
+        self.logger.info(f"[加热台{station_id}] {material_id}加热完成 (用时{self.HEATING_TIME}s)")
+
+        return {
+            "success": True,
+            "station_id": station_id,
+            "material_id": material_id,
+            "material_number": material_number,
+            "message": f"加热台{station_id}加热完成",
+            "unilabos_samples": [
+                LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                sample_uuid, content in sample_uuids.items()]
+        }
+
+    def move_to_output(
+        self,
+        sample_uuids: SampleUUIDsType,
+        station_id: int,
+        material_number: int,
+    ) -> MoveToOutputResult:
+        """
+        将物料从加热台移动到输出位置Cn
+
+        Args:
+            station_id: 加热台ID (1-3)，从 start_heating 的 handle 传入
+            material_number: 物料编号，从 start_heating 的 handle 传入，用于确定输出位置 Cn
+
+        Returns:
+            MoveToOutputResult: 包含执行结果
+        """
+        output_number = material_number  # 物料编号决定输出位置
+
+        if station_id not in self._heating_stations:
+            return {
+                "success": False,
+                "station_id": station_id,
+                "material_id": "",
+                "output_position": f"C{output_number}",
+                "message": f"无效的加热台ID: {station_id}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+        with self._stations_lock:
+            station = self._heating_stations[station_id]
+            material_id = station.current_material
+
+            if material_id is None:
+                return {
+                    "success": False,
+                    "station_id": station_id,
+                    "material_id": "",
+                    "output_position": f"C{output_number}",
+                    "message": f"加热台{station_id}上没有物料",
+                    "unilabos_samples": [
+                        LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                        sample_uuid, content in sample_uuids.items()]
+                }
+
+            if station.state != HeatingStationState.COMPLETED:
+                return {
+                    "success": False,
+                    "station_id": station_id,
+                    "material_id": material_id,
+                    "output_position": f"C{output_number}",
+                    "message": f"加热台{station_id}尚未完成加热 (当前状态: {station.state.value})",
+                    "unilabos_samples": [
+                        LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                        sample_uuid, content in sample_uuids.items()]
+                }
+
+        output_position = f"C{output_number}"
+        task_desc = f"从加热台{station_id}移动{material_id}到{output_position}"
+        self.logger.info(f"[任务] {task_desc}")
+
+        try:
+            with self._tasks_lock:
+                if material_id in self._active_tasks:
+                    self._active_tasks[material_id]["status"] = "waiting_for_arm_output"
+
+            # 获取机械臂
+            self._acquire_arm(task_desc)
+
+            with self._tasks_lock:
+                if material_id in self._active_tasks:
+                    self._active_tasks[material_id]["status"] = "arm_moving_to_output"
+
+            # 模拟机械臂操作 (3秒)
+            self.logger.info(f"[{material_id}] 机械臂正在从加热台{station_id}取出并移动到{output_position}...")
+            time.sleep(self.ARM_OPERATION_TIME)
+
+            # 清空加热台
+            with self._stations_lock:
+                self._heating_stations[station_id].state = HeatingStationState.IDLE
+                self._heating_stations[station_id].current_material = None
+                self._heating_stations[station_id].material_number = None
+                self._heating_stations[station_id].heating_progress = 0.0
+                self._heating_stations[station_id].heating_start_time = None
+
+            # 释放机械臂
+            self._release_arm()
+
+            # 任务完成
+            with self._tasks_lock:
+                if material_id in self._active_tasks:
+                    self._active_tasks[material_id]["status"] = "completed"
+                    self._active_tasks[material_id]["end_time"] = time.time()
+
+            self._update_data_status(f"{material_id}已移动到{output_position}")
+            self.logger.info(f"[{material_id}] 已成功移动到{output_position} (用时{self.ARM_OPERATION_TIME}s)")
+
+            return {
+                "success": True,
+                "station_id": station_id,
+                "material_id": material_id,
+                "output_position": output_position,
+                "message": f"{material_id}已成功移动到{output_position}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+        except Exception as e:
+            self.logger.error(f"移动到输出位置失败: {str(e)}")
+            if self._arm_lock.locked():
+                self._release_arm()
+            return {
+                "success": False,
+                "station_id": station_id,
+                "material_id": "",
+                "output_position": output_position,
+                "message": f"移动失败: {str(e)}",
+                "unilabos_samples": [
+                    LabSample(sample_uuid=sample_uuid, oss_path="", extra={"material_uuid": content} if isinstance(content, str) else content.serialize()) for
+                    sample_uuid, content in sample_uuids.items()]
+            }
+
+    # ============ 状态属性 ============
+
+    @property
+    def status(self) -> str:
+        return self.data.get("status", "Unknown")
+
+    @property
+    def arm_state(self) -> str:
+        return self._arm_state.value
+
+    @property
+    def arm_current_task(self) -> str:
+        return self._arm_current_task or ""
+
+    @property
+    def heating_station_1_state(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(1)
+            return station.state.value if station else "unknown"
+
+    @property
+    def heating_station_1_material(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(1)
+            return station.current_material or "" if station else ""
+
+    @property
+    def heating_station_1_progress(self) -> float:
+        with self._stations_lock:
+            station = self._heating_stations.get(1)
+            return station.heating_progress if station else 0.0
+
+    @property
+    def heating_station_2_state(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(2)
+            return station.state.value if station else "unknown"
+
+    @property
+    def heating_station_2_material(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(2)
+            return station.current_material or "" if station else ""
+
+    @property
+    def heating_station_2_progress(self) -> float:
+        with self._stations_lock:
+            station = self._heating_stations.get(2)
+            return station.heating_progress if station else 0.0
+
+    @property
+    def heating_station_3_state(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(3)
+            return station.state.value if station else "unknown"
+
+    @property
+    def heating_station_3_material(self) -> str:
+        with self._stations_lock:
+            station = self._heating_stations.get(3)
+            return station.current_material or "" if station else ""
+
+    @property
+    def heating_station_3_progress(self) -> float:
+        with self._stations_lock:
+            station = self._heating_stations.get(3)
+            return station.heating_progress if station else 0.0
+
+    @property
+    def active_tasks_count(self) -> int:
+        with self._tasks_lock:
+            return len(self._active_tasks)
+
+    @property
+    def message(self) -> str:
+        return self.data.get("message", "")

unilabos/devices/workstation/README.md

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

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

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

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

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

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

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

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

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

unilabos/devices/workstation/bioyond_studio/bioyond_rpc.py

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