update action

fix: WareHouse 的不可哈希类型错误，优化父节点去重逻辑
2026-02-05 05:45:10 +00:00 · 2026-01-15 10:05:03 +08:00 · 2026-01-14 20:15:05 +08:00 · 2026-01-14 14:17:29 +08:00 · 2026-01-13 20:21:37 +08:00 · 2026-01-13 17:49:11 +08:00
306 changed files with 331818 additions and 18934 deletions
--- a/.conda/recipe.yaml
+++ b/.conda/recipe.yaml
@@ -1,6 +1,6 @@
 package:
  name: unilabos
-  version: 0.10.10
+  version: 0.10.15

 source:
  path: ../unilabos
@@ -9,7 +9,7 @@ source:
 build:
  python:
    entry_points:
-     - unilab = unilabos.app.main:main
+    - unilab = unilabos.app.main:main
  script:
  - set PIP_NO_INDEX=
  - if: win
@@ -25,7 +25,6 @@ build:
    - cp $RECIPE_DIR/../setup.py $SRC_DIR
    - $PYTHON -m pip install $SRC_DIR

-
 requirements:
  host:
  - python ==3.11.11
@@ -87,6 +86,6 @@ requirements:
  - uni-lab::ros-humble-unilabos-msgs

 about:
-  repository: https://github.com/dptech-corp/Uni-Lab-OS
+  repository: https://github.com/deepmodeling/Uni-Lab-OS
  license: GPL-3.0-only
  description: "Uni-Lab-OS"
--- a/.cursorignore
+++ b/.cursorignore
@@ -0,0 +1,26 @@
+.conda
+# .github
+.idea
+# .vscode
+output
+pylabrobot_repo
+recipes
+scripts
+service
+temp
+# unilabos/test
+# unilabos/app/web
+unilabos/device_mesh
+unilabos_data
+unilabos_msgs
+unilabos.egg-info
+CONTRIBUTORS
+# LICENSE
+MANIFEST.in
+pyrightconfig.json
+# README.md
+# README_zh.md
+setup.py
+setup.cfg
+.gitattrubutes
+**/__pycache__
--- a/.github/workflows/conda-pack-build.yml
+++ b/.github/workflows/conda-pack-build.yml
@@ -24,7 +24,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
--- a/.github/workflows/multi-platform-build.yml
+++ b/.github/workflows/multi-platform-build.yml
@@ -27,7 +27,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
--- a/.github/workflows/unilabos-conda-build.yml
+++ b/.github/workflows/unilabos-conda-build.yml
@@ -26,7 +26,7 @@ jobs:
        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
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+cursor_docs/
 configs/
 temp/
 output/
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,4 @@
+recursive-include unilabos/test *
 recursive-include unilabos/registry *.yaml
 recursive-include unilabos/app/web/static *
 recursive-include unilabos/app/web/templates *
--- a/17
+++ b/17
@@ -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.
--- a/README.md
+++ b/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,39 +27,69 @@ 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:

 ```bash
 # Create new environment
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```

-## Install Dev Uni-Lab-OS
+2. Install Dev Uni-Lab-OS

 ```bash
 # Clone the repository
-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

 # 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

@@ -75,4 +101,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)
--- a/README_zh.md
+++ b/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,7 +27,7 @@ Uni-Lab-OS 是一个用于实验室自动化的综合平台，旨在连接和控

 详细文档可在以下位置找到:

- [在线文档](https://xuwznln.github.io/Uni-Lab-OS-Doc/)
+- [在线文档](https://deepmodeling.github.io/Uni-Lab-OS/)

 ## 快速开始

@@ -41,31 +37,59 @@ Uni-Lab-OS 建议使用 `mamba` 管理环境。根据您的操作系统选择适

 ```bash
 # 创建新环境
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```

 2. 安装开发版 Uni-Lab-OS:

 ```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)。

 ## 项目统计

@@ -77,4 +101,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)
--- a/docs/advanced_usage/configuration.md
+++ b/docs/advanced_usage/configuration.md
@@ -0,0 +1,726 @@
+# Uni-Lab 配置指南
+
+本文档详细介绍 Uni-Lab 配置文件的结构、配置项、命令行覆盖和环境变量的使用方法。
+
+## 配置文件概述
+
+Uni-Lab 使用 Python 格式的配置文件（`.py`），默认为 `unilabos_data/local_config.py`。配置文件采用类属性的方式定义各种配置项，比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
+
+## 获取实验室密钥
+
+在配置文件或启动命令中，您需要提供实验室的访问密钥（ak）和私钥（sk）。
+
+**获取方式：**
+
+进入 [Uni-Lab 实验室](https://uni-lab.bohrium.com)，点击左下角的头像，在实验室详情中获取所在实验室的 ak 和 sk：
+
+![copy_aksk.gif](image/copy_aksk.gif)
+
+## 配置文件格式
+
+### 默认配置示例
+
+首次使用时，系统会自动创建一个基础配置文件 `local_config.py`：
+
+```python
+# unilabos的配置文件
+
+class BasicConfig:
+    ak = ""  # 实验室网页给您提供的ak代码
+    sk = ""  # 实验室网页给您提供的sk代码
+
+
+# WebSocket配置，一般无需调整
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）
+```
+
+### 完整配置示例
+
+您可以根据需要添加更多配置选项：
+
+```python
+#!/usr/bin/env python
+# coding=utf-8
+"""Uni-Lab 配置文件"""
+
+# 基础配置
+class BasicConfig:
+    ak = ""  # 实验室访问密钥
+    sk = ""  # 实验室私钥
+    working_dir = ""  # 工作目录（通常自动设置）
+    config_path = ""  # 配置文件路径（自动设置）
+    is_host_mode = True  # 是否为主站模式
+    slave_no_host = False  # 从站模式下是否跳过等待主机服务
+    upload_registry = False  # 是否上传注册表
+    machine_name = "undefined"  # 机器名称（自动获取）
+    vis_2d_enable = False  # 是否启用2D可视化
+    enable_resource_load = True  # 是否启用资源加载
+    communication_protocol = "websocket"  # 通信协议
+    log_level = "DEBUG"  # 日志级别：TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+# WebSocket配置
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）
+
+# HTTP配置
+class HTTPConfig:
+    remote_addr = "https://uni-lab.bohrium.com/api/v1"  # 远程服务器地址
+
+# ROS配置
+class ROSConfig:
+    modules = [
+        "std_msgs.msg",
+        "geometry_msgs.msg",
+        "control_msgs.msg",
+        "control_msgs.action",
+        "nav2_msgs.action",
+        "unilabos_msgs.msg",
+        "unilabos_msgs.action",
+    ]  # 需要加载的ROS模块
+```
+
+## 配置优先级
+
+配置项的生效优先级从高到低为：
+
+1. **命令行参数**：最高优先级
+2. **环境变量**：中等优先级
+3. **配置文件**：基础优先级
+
+这意味着命令行参数会覆盖环境变量和配置文件，环境变量会覆盖配置文件。
+
+## 推荐配置方式
+
+根据参数特性，不同配置项有不同的推荐配置方式：
+
+### 建议通过命令行指定的参数（不需要写入配置文件）
+
+以下参数推荐通过命令行或环境变量指定，**一般不需要在配置文件中配置**：
+
+| 参数              | 命令行参数          | 原因                                 |
+| ----------------- | ------------------- | ------------------------------------ |
+| `ak` / `sk`       | `--ak` / `--sk`     | **安全考虑**：避免敏感信息泄露       |
+| `working_dir`     | `--working_dir`     | **灵活性**：不同环境可能使用不同目录 |
+| `is_host_mode`    | `--is_slave`        | **运行模式**：由启动场景决定，不固定 |
+| `slave_no_host`   | `--slave_no_host`   | **运行模式**：从站特殊配置，按需使用 |
+| `upload_registry` | `--upload_registry` | **临时操作**：仅首次启动或更新时需要 |
+| `vis_2d_enable`   | `--2d_vis`          | **调试功能**：按需临时启用           |
+| `remote_addr`     | `--addr`            | **环境切换**：测试/生产环境快速切换  |
+
+**推荐用法示例：**
+
+```bash
+# 标准启动命令（所有必要参数通过命令行指定）
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 测试环境
+unilab --addr test --ak your_ak --sk your_sk -g graph.json
+
+# 从站模式
+unilab --is_slave --ak your_ak --sk your_sk
+
+# 首次启动上传注册表
+unilab --ak your_ak --sk your_sk -g graph.json --upload_registry
+```
+
+### 适合在配置文件中配置的参数
+
+以下参数适合在配置文件中配置，通常不会频繁更改：
+
+| 参数                     | 配置类      | 说明                   |
+| ------------------------ | ----------- | ---------------------- |
+| `log_level`              | BasicConfig | 日志级别配置           |
+| `reconnect_interval`     | WSConfig    | WebSocket 重连间隔     |
+| `max_reconnect_attempts` | WSConfig    | WebSocket 最大重连次数 |
+| `ping_interval`          | WSConfig    | WebSocket 心跳间隔     |
+| `modules`                | ROSConfig   | ROS 模块列表           |
+
+**配置文件示例（推荐最小配置）：**
+
+```python
+# unilabos的配置文件
+
+class BasicConfig:
+    log_level = "INFO"  # 生产环境建议 INFO，调试时用 DEBUG
+
+# WebSocket配置，一般保持默认即可
+class WSConfig:
+    reconnect_interval = 5
+    max_reconnect_attempts = 999
+    ping_interval = 30
+```
+
+**注意：** `ak` 和 `sk` 不建议写在配置文件中，始终通过命令行参数或环境变量传递。
+
+## 命令行参数覆盖配置
+
+Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。
+
+### 支持命令行覆盖的配置项
+
+| 配置类        | 配置字段          | 命令行参数          | 说明                             |
+| ------------- | ----------------- | ------------------- | -------------------------------- |
+| `BasicConfig` | `ak`              | `--ak`              | 实验室访问密钥                   |
+| `BasicConfig` | `sk`              | `--sk`              | 实验室私钥                       |
+| `BasicConfig` | `working_dir`     | `--working_dir`     | 工作目录路径                     |
+| `BasicConfig` | `is_host_mode`    | `--is_slave`        | 主站模式（参数为从站模式，取反） |
+| `BasicConfig` | `slave_no_host`   | `--slave_no_host`   | 从站模式下跳过等待主机服务       |
+| `BasicConfig` | `upload_registry` | `--upload_registry` | 启动时上传注册表信息             |
+| `BasicConfig` | `vis_2d_enable`   | `--2d_vis`          | 启用 2D 可视化                   |
+| `HTTPConfig`  | `remote_addr`     | `--addr`            | 远程服务地址                     |
+
+### 特殊命令行参数
+
+除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
+
+| 参数                | 说明                                 |
+| ------------------- | ------------------------------------ |
+| `--config`          | 指定配置文件路径                     |
+| `--port`            | Web 服务端口（不影响配置文件）       |
+| `--disable_browser` | 禁用自动打开浏览器（不影响配置文件） |
+| `--visual`          | 可视化工具选择（不影响配置文件）     |
+| `--skip_env_check`  | 跳过环境检查（不影响配置文件）       |
+
+### 命令行覆盖使用示例
+
+```bash
+# 通过命令行覆盖认证信息
+unilab --ak "new_access_key" --sk "new_secret_key" -g graph.json
+
+# 覆盖服务器地址
+unilab --ak ak --sk sk --addr "https://custom.server.com/api/v1" -g graph.json
+
+# 启用从站模式并跳过等待主机
+unilab --is_slave --slave_no_host --ak ak --sk sk
+
+# 启用上传注册表和2D可视化
+unilab --upload_registry --2d_vis --ak ak --sk sk -g graph.json
+
+# 组合使用多个覆盖参数
+unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis -g graph.json
+```
+
+### 预设环境地址
+
+`--addr` 参数支持以下预设值，会自动转换为对应的完整 URL：
+
+- `test` → `https://uni-lab.test.bohrium.com/api/v1`
+- `uat` → `https://uni-lab.uat.bohrium.com/api/v1`
+- `local` → `http://127.0.0.1:48197/api/v1`
+- 其他值 → 直接使用作为完整 URL
+
+## 配置选项详解
+
+### 1. BasicConfig - 基础配置
+
+基础配置包含了系统运行的核心参数：
+
+| 参数                     | 类型 | 默认值        | 说明                                       |
+| ------------------------ | ---- | ------------- | ------------------------------------------ |
+| `ak`                     | str  | `""`          | 实验室访问密钥（必需）                     |
+| `sk`                     | str  | `""`          | 实验室私钥（必需）                         |
+| `working_dir`            | str  | `""`          | 工作目录，通常自动设置                     |
+| `config_path`            | str  | `""`          | 配置文件路径，自动设置                     |
+| `is_host_mode`           | bool | `True`        | 是否为主站模式                             |
+| `slave_no_host`          | bool | `False`       | 从站模式下是否跳过等待主机服务             |
+| `upload_registry`        | bool | `False`       | 启动时是否上传注册表信息                   |
+| `machine_name`           | str  | `"undefined"` | 机器名称，自动从 hostname 获取（不可配置） |
+| `vis_2d_enable`          | bool | `False`       | 是否启用 2D 可视化                         |
+| `enable_resource_load`   | bool | `True`        | 是否启用资源加载                           |
+| `communication_protocol` | str  | `"websocket"` | 通信协议，固定为 websocket                 |
+| `log_level`              | str  | `"DEBUG"`     | 日志级别                                   |
+
+#### 日志级别选项
+
+- `TRACE` - 追踪级别（最详细）
+- `DEBUG` - 调试级别（默认）
+- `INFO` - 信息级别
+- `WARNING` - 警告级别
+- `ERROR` - 错误级别
+- `CRITICAL` - 严重错误级别（最简略）
+
+#### 认证配置（ak / sk）
+
+`ak` 和 `sk` 是必需的认证参数：
+
+1. **获取方式**：在 [Uni-Lab 官网](https://uni-lab.bohrium.com) 注册实验室后获得
+2. **配置方式**：
+   - **命令行参数**：`--ak "your_key" --sk "your_secret"`（最高优先级，推荐）
+   - **环境变量**：`UNILABOS_BASICCONFIG_AK` 和 `UNILABOS_BASICCONFIG_SK`
+   - **配置文件**：在 `BasicConfig` 类中设置（不推荐，安全风险）
+3. **安全注意**：请妥善保管您的密钥信息，不要提交到版本控制
+
+**推荐做法**：
+
+- **开发环境**：使用命令行参数或环境变量
+- **生产环境**：使用环境变量
+- **临时测试**：使用命令行参数
+
+### 2. WSConfig - WebSocket 配置
+
+WebSocket 是 Uni-Lab 的主要通信方式：
+
+| 参数                     | 类型 | 默认值 | 说明               |
+| ------------------------ | ---- | ------ | ------------------ |
+| `reconnect_interval`     | int  | `5`    | 断线重连间隔（秒） |
+| `max_reconnect_attempts` | int  | `999`  | 最大重连次数       |
+| `ping_interval`          | int  | `30`   | 心跳检测间隔（秒） |
+
+### 3. HTTPConfig - HTTP 配置
+
+HTTP 客户端配置用于与云端服务通信：
+
+| 参数          | 类型 | 默认值                                 | 说明         |
+| ------------- | ---- | -------------------------------------- | ------------ |
+| `remote_addr` | str  | `"https://uni-lab.bohrium.com/api/v1"` | 远程服务地址 |
+
+**预设环境地址**：
+
+- 生产环境：`https://uni-lab.bohrium.com/api/v1`（默认）
+- 测试环境：`https://uni-lab.test.bohrium.com/api/v1`
+- UAT 环境：`https://uni-lab.uat.bohrium.com/api/v1`
+- 本地环境：`http://127.0.0.1:48197/api/v1`
+
+### 4. ROSConfig - ROS 配置
+
+配置 ROS 消息转换器需要加载的模块：
+
+| 配置项    | 类型 | 默认值     | 说明         |
+| --------- | ---- | ---------- | ------------ |
+| `modules` | list | 见下方示例 | ROS 模块列表 |
+
+**默认模块列表：**
+
+```python
+class ROSConfig:
+    modules = [
+        "std_msgs.msg",           # 标准消息类型
+        "geometry_msgs.msg",      # 几何消息类型
+        "control_msgs.msg",       # 控制消息类型
+        "control_msgs.action",    # 控制动作类型
+        "nav2_msgs.action",       # 导航动作类型
+        "unilabos_msgs.msg",      # UniLab 自定义消息类型
+        "unilabos_msgs.action",   # UniLab 自定义动作类型
+    ]
+```
+
+您可以根据实际使用的设备和功能添加其他 ROS 模块。
+
+## 环境变量配置
+
+Uni-Lab 支持通过环境变量覆盖配置文件中的设置。
+
+### 环境变量命名规则
+
+```
+UNILABOS_<配置类名>_<配置项名>
+```
+
+**注意：**
+
+- 环境变量名不区分大小写
+- 配置类名和配置项名都会转换为大写进行匹配
+
+### 设置环境变量
+
+#### Linux / macOS
+
+```bash
+# 临时设置（当前终端）
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+
+# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
+echo 'export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO' >> ~/.bashrc
+source ~/.bashrc
+```
+
+#### Windows (cmd)
+
+```cmd
+# 临时设置
+set UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+set UNILABOS_BASICCONFIG_AK=your_access_key
+
+# 永久设置（系统环境变量）
+setx UNILABOS_BASICCONFIG_LOG_LEVEL INFO
+```
+
+#### Windows (PowerShell)
+
+```powershell
+# 临时设置
+$env:UNILABOS_BASICCONFIG_LOG_LEVEL="INFO"
+$env:UNILABOS_BASICCONFIG_AK="your_access_key"
+
+# 永久设置
+[Environment]::SetEnvironmentVariable("UNILABOS_BASICCONFIG_LOG_LEVEL", "INFO", "User")
+```
+
+### 环境变量类型转换
+
+系统会根据配置项的原始类型自动转换环境变量值：
+
+| 原始类型 | 转换规则                                |
+| -------- | --------------------------------------- |
+| `bool`   | "true", "1", "yes" → True；其他 → False |
+| `int`    | 转换为整数                              |
+| `float`  | 转换为浮点数                            |
+| `str`    | 直接使用字符串值                        |
+
+**示例：**
+
+```bash
+# 布尔值
+export UNILABOS_BASICCONFIG_IS_HOST_MODE=true  # 将设置为 True
+export UNILABOS_BASICCONFIG_IS_HOST_MODE=false  # 将设置为 False
+
+# 整数
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL=10  # 将设置为 10
+
+# 字符串
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO  # 将设置为 "INFO"
+```
+
+### 环境变量示例
+
+```bash
+# 设置基础配置
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
+
+# 设置WebSocket配置
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
+export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
+
+# 设置HTTP配置
+export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.test.bohrium.com/api/v1"
+```
+
+## 配置文件使用方法
+
+### 1. 使用默认配置文件（推荐）
+
+系统会自动查找并加载配置文件：
+
+```bash
+# 直接启动，使用默认的 unilabos_data/local_config.py
+unilab --ak your_ak --sk your_sk -g graph.json
+```
+
+查找顺序：
+
+1. 环境变量 `UNILABOS_BASICCONFIG_CONFIG_PATH` 指定的路径
+2. 工作目录下的 `local_config.py`
+3. 首次使用时会引导创建配置文件
+
+### 2. 指定配置文件启动
+
+```bash
+# 使用指定配置文件启动
+unilab --config /path/to/your/config.py --ak ak --sk sk -g graph.json
+```
+
+### 3. 配置文件验证
+
+系统启动时会自动验证配置文件：
+
+- **语法检查**：确保 Python 语法正确
+- **类型检查**：验证配置项类型是否匹配
+- **加载确认**：控制台输出加载成功信息
+
+## 常用配置场景
+
+### 场景 1：调整日志级别
+
+**配置文件方式：**
+
+```python
+class BasicConfig:
+    log_level = "INFO"  # 生产环境建议使用 INFO 或 WARNING
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+unilab --ak ak --sk sk -g graph.json
+```
+
+**命令行方式**（需要配置文件已包含）：
+
+```bash
+# 配置文件无直接命令行参数，需通过环境变量
+UNILABOS_BASICCONFIG_LOG_LEVEL=INFO unilab --ak ak --sk sk -g graph.json
+```
+
+### 场景 2：配置 WebSocket 重连
+
+**配置文件方式：**
+
+```python
+class WSConfig:
+    reconnect_interval = 10  # 增加重连间隔到 10 秒
+    max_reconnect_attempts = 100  # 减少最大重连次数到 100 次
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL=10
+export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS=100
+```
+
+### 场景 3：切换服务器环境
+
+**配置文件方式：**
+
+```python
+class HTTPConfig:
+    remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_HTTPCONFIG_REMOTE_ADDR=https://uni-lab.test.bohrium.com/api/v1
+```
+
+**命令行方式（推荐）：**
+
+```bash
+unilab --addr test --ak your_ak --sk your_sk -g graph.json
+```
+
+### 场景 4：从站模式配置
+
+**配置文件方式：**
+
+```python
+class BasicConfig:
+    is_host_mode = False  # 从站模式
+    slave_no_host = True  # 不等待主机服务
+```
+
+**命令行方式（推荐）：**
+
+```bash
+unilab --is_slave --slave_no_host --ak your_ak --sk your_sk
+```
+
+## 最佳实践
+
+### 1. 安全配置
+
+**不要在配置文件中存储敏感信息**
+
+- ❌ **不推荐**：在配置文件中明文存储 ak/sk
+- ✅ **推荐**：使用环境变量或命令行参数
+
+```bash
+# 生产环境 - 使用环境变量（推荐）
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+unilab -g graph.json
+
+# 或使用命令行参数
+unilab --ak "your_access_key" --sk "your_secret_key" -g graph.json
+```
+
+**其他安全建议：**
+
+- 不要将包含密钥的配置文件提交到版本控制系统
+- 限制配置文件权限：`chmod 600 local_config.py`
+- 定期更换访问密钥
+- 使用 `.gitignore` 排除配置文件
+
+### 2. 多环境配置
+
+为不同环境创建不同的配置文件：
+
+```
+configs/
+├── base_config.py       # 基础配置（非敏感）
+├── dev_config.py        # 开发环境
+├── test_config.py       # 测试环境
+├── prod_config.py       # 生产环境
+└── example_config.py    # 示例配置
+```
+
+**环境切换示例**：
+
+```bash
+# 本地开发环境
+unilab --config configs/dev_config.py --addr local --ak ak --sk sk -g graph.json
+
+# 测试环境
+unilab --config configs/test_config.py --addr test --ak ak --sk sk --upload_registry -g graph.json
+
+# 生产环境
+unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK" -g graph.json
+```
+
+### 3. 配置管理
+
+**配置文件最佳实践：**
+
+- 保持配置文件简洁，只包含需要修改的配置项
+- 为配置项添加注释说明其作用
+- 定期检查和更新配置文件
+- 版本控制仅保存示例配置，不包含实际密钥
+
+**命令行参数优先使用场景：**
+
+- 临时测试不同配置
+- CI/CD 流水线中的动态配置
+- 不同环境间快速切换
+- 敏感信息的安全传递
+
+### 4. 灵活配置策略
+
+**基础配置文件 + 命令行覆盖**的推荐方式：
+
+```python
+# base_config.py - 基础配置（非敏感信息）
+class BasicConfig:
+    # 非敏感配置写在文件中
+    is_host_mode = True
+    upload_registry = False
+    vis_2d_enable = False
+    log_level = "INFO"
+
+class WSConfig:
+    reconnect_interval = 5
+    max_reconnect_attempts = 999
+    ping_interval = 30
+```
+
+```bash
+# 启动时通过命令行覆盖关键参数
+unilab --config base_config.py \
+       --ak "$AK" \
+       --sk "$SK" \
+       --addr "test" \
+       --upload_registry \
+       --2d_vis \
+       -g graph.json
+```
+
+## 故障排除
+
+### 1. 配置文件加载失败
+
+**错误信息**：`[ENV] 配置文件 xxx 不存在`
+
+**解决方法**：
+
+- 确认配置文件路径正确
+- 检查文件权限是否可读
+- 确保配置文件是 `.py` 格式
+- 使用绝对路径或相对于当前目录的路径
+
+### 2. 语法错误
+
+**错误信息**：`[ENV] 加载配置文件 xxx 失败`
+
+**解决方法**：
+
+- 检查 Python 语法是否正确
+- 确认类名和字段名拼写正确
+- 验证缩进是否正确（使用空格而非制表符）
+- 确保字符串使用引号包裹
+
+### 3. 认证失败
+
+**错误信息**：`后续运行必须拥有一个实验室`
+
+**解决方法**：
+
+- 确认 `ak` 和 `sk` 已正确配置
+- 检查密钥是否有效（未过期或撤销）
+- 确认网络连接正常
+- 验证密钥是否来自正确的实验室
+
+### 4. 环境变量不生效
+
+**解决方法**：
+
+- 确认环境变量名格式正确（`UNILABOS_<类名>_<字段名>`）
+- 检查环境变量是否已正确设置（`echo $VARIABLE_NAME`）
+- 重启终端或重新加载环境变量
+- 确认环境变量值的类型正确
+
+### 5. 命令行参数不生效
+
+**错误现象**：设置了命令行参数但配置没有生效
+
+**解决方法**：
+
+- 确认参数名拼写正确（如 `--ak` 而不是 `--access_key`）
+- 检查参数格式是否正确（布尔参数如 `--is_slave` 不需要值）
+- 确认参数位置正确（所有参数都应在 `unilab` 之后）
+- 查看启动日志确认参数是否被正确解析
+- 检查是否有配置文件或环境变量与之冲突
+
+### 6. 配置优先级混淆
+
+**错误现象**：不确定哪个配置生效
+
+**解决方法**：
+
+- 记住优先级：**命令行参数 > 环境变量 > 配置文件**
+- 使用 `--ak` 和 `--sk` 参数时会看到提示信息："传入了 ak 参数，优先采用传入参数！"
+- 检查启动日志中的配置加载信息
+- 临时移除低优先级配置来测试高优先级配置是否生效
+- 使用 `printenv | grep UNILABOS` 查看所有相关环境变量
+
+## 配置验证
+
+### 检查配置是否生效
+
+启动 Uni-Lab 时，控制台会输出配置加载信息：
+
+```
+[ENV] 配置文件 /path/to/config.py 加载成功
+[ENV] 设置 BasicConfig.log_level = INFO
+传入了ak参数，优先采用传入参数！
+传入了sk参数，优先采用传入参数！
+```
+
+### 常见配置错误
+
+1. **配置文件格式错误**
+
+   ```
+   [ENV] 加载配置文件 /path/to/config.py 失败
+   ```
+
+   **解决方案**：检查 Python 语法，确保配置类定义正确
+
+2. **环境变量格式错误**
+
+   ```
+   [ENV] 环境变量格式不正确：UNILABOS_INVALID_VAR
+   ```
+
+   **解决方案**：确保环境变量遵循 `UNILABOS_<类名>_<字段名>` 格式
+
+3. **类或字段不存在**
+   ```
+   [ENV] 未找到类：UNKNOWNCONFIG
+   [ENV] 类 BasicConfig 中未找到字段：UNKNOWN_FIELD
+   ```
+   **解决方案**：检查配置类名和字段名是否正确
+
+## 相关文档
+
+- [工作目录详解](working_directory.md)
+- [启动参数详解](../user_guide/launch.md)
+- [快速安装指南](../user_guide/quick_install_guide.md)
--- a/docs/advanced_usage/image/copy_aksk.gif
+++ b/docs/advanced_usage/image/copy_aksk.gif
--- a/docs/advanced_usage/working_directory.md
+++ b/docs/advanced_usage/working_directory.md
@@ -0,0 +1,218 @@
+# 工作目录详解
+
+本文档详细介绍 Uni-Lab 工作目录（`working_dir`）的判断逻辑和详细用法。
+
+## 什么是工作目录
+
+工作目录是 Uni-Lab 存储配置文件、日志和运行数据的目录。默认情况下，工作目录为 `当前目录/unilabos_data`。
+
+## 工作目录判断逻辑
+
+系统按以下决策树自动确定工作目录：
+
+### 第一步：初始判断
+
+```python
+# 检查当前目录
+if 当前目录以 "unilabos_data" 结尾:
+    working_dir = 当前目录的绝对路径
+else:
+    working_dir = 当前目录/unilabos_data
+```
+
+**解释：**
+- 如果您已经在 `unilabos_data` 目录内启动，系统直接使用当前目录
+- 否则，系统会在当前目录下创建或使用 `unilabos_data` 子目录
+
+### 第二步：处理 `--working_dir` 参数
+
+如果用户指定了 `--working_dir` 参数：
+
+```python
+working_dir = 用户指定的路径
+```
+
+此时还会检查配置文件：
+- 如果同时指定了 `--config` 但该文件不存在
+- 系统会尝试在 `working_dir/local_config.py` 查找
+- 如果仍未找到，报错退出
+
+### 第三步：处理 `--config` 参数
+
+如果用户指定了 `--config` 且文件存在：
+
+```python
+# 工作目录改为配置文件所在目录
+working_dir = config_path 的父目录
+```
+
+**重要：** 这意味着配置文件的位置会影响工作目录的判断。
+
+## 使用场景示例
+
+### 场景 1：默认场景（推荐）
+
+```bash
+# 当前目录：/home/user/project
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /home/user/project/unilabos_data
+# config_path = /home/user/project/unilabos_data/local_config.py
+```
+
+### 场景 2：在 unilabos_data 目录内启动
+
+```bash
+cd /home/user/project/unilabos_data
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /home/user/project/unilabos_data
+# config_path = /home/user/project/unilabos_data/local_config.py
+```
+
+### 场景 3：手动指定工作目录
+
+```bash
+unilab --working_dir /custom/path --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /custom/path
+# config_path = /custom/path/local_config.py （如果存在）
+```
+
+### 场景 4：通过配置文件路径推断工作目录
+
+```bash
+unilab --config /data/lab_a/local_config.py --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /data/lab_a
+# config_path = /data/lab_a/local_config.py
+```
+
+## 高级用法：管理多个实验室配置
+
+### 方法 1：使用不同的工作目录
+
+```bash
+# 实验室 A
+unilab --working_dir ~/labs/lab_a --ak ak_a --sk sk_a -g graph_a.json
+
+# 实验室 B
+unilab --working_dir ~/labs/lab_b --ak ak_b --sk sk_b -g graph_b.json
+```
+
+### 方法 2：使用不同的配置文件
+
+```bash
+# 实验室 A
+unilab --config ~/labs/lab_a/config.py --ak ak_a --sk sk_a -g graph_a.json
+
+# 实验室 B
+unilab --config ~/labs/lab_b/config.py --ak ak_b --sk sk_b -g graph_b.json
+```
+
+### 方法 3：使用shell脚本管理
+
+创建 `start_lab_a.sh`：
+
+```bash
+#!/bin/bash
+cd ~/labs/lab_a
+unilab --ak your_ak_a --sk your_sk_a -g graph_a.json
+```
+
+创建 `start_lab_b.sh`：
+
+```bash
+#!/bin/bash
+cd ~/labs/lab_b
+unilab --ak your_ak_b --sk your_sk_b -g graph_b.json
+```
+
+## 完整决策流程图
+
+```
+开始
+  ↓
+判断当前目录是否以 unilabos_data 结尾？
+  ├─ 是 → working_dir = 当前目录
+  └─ 否 → working_dir = 当前目录/unilabos_data
+  ↓
+用户是否指定 --working_dir？
+  └─ 是 → working_dir = 指定路径
+  ↓
+用户是否指定 --config 且文件存在？
+  └─ 是 → working_dir = config 文件所在目录
+  ↓
+检查 working_dir/local_config.py 是否存在？
+  ├─ 是 → 加载配置文件 → 继续启动
+  └─ 否 → 询问是否首次使用
+      ├─ 是 → 创建目录和配置文件 → 继续启动
+      └─ 否 → 退出程序
+```
+
+## 常见问题
+
+### 1. 如何查看当前使用的工作目录？
+
+启动 Uni-Lab 时，系统会在控制台输出：
+
+```
+当前工作目录为 /path/to/working_dir
+```
+
+### 2. 可以在同一台机器上运行多个实验室吗？
+
+可以。使用不同的工作目录或配置文件即可：
+
+```bash
+# 终端 1
+unilab --working_dir ~/lab1 --ak ak1 --sk sk1 -g graph1.json
+
+# 终端 2
+unilab --working_dir ~/lab2 --ak ak2 --sk sk2 -g graph2.json
+```
+
+### 3. 工作目录中存储了什么？
+
+- `local_config.py` - 配置文件
+- 日志文件
+- 临时运行数据
+- 缓存文件
+
+### 4. 可以删除工作目录吗？
+
+可以，但会丢失：
+- 配置文件（需要重新创建）
+- 历史日志
+- 缓存数据
+
+建议定期备份配置文件。
+
+### 5. 如何迁移到新的工作目录？
+
+```bash
+# 1. 复制旧的工作目录
+cp -r ~/old_path/unilabos_data ~/new_path/unilabos_data
+
+# 2. 在新位置启动
+cd ~/new_path
+unilab --ak your_ak --sk your_sk -g graph.json
+```
+
+## 最佳实践
+
+1. **使用默认工作目录**：对于单一实验室，使用默认的 `./unilabos_data` 即可
+2. **组织多实验室**：为每个实验室创建独立的目录结构
+3. **版本控制**：将配置文件纳入版本控制，但排除日志和缓存
+4. **备份配置**：定期备份 `local_config.py` 文件
+5. **使用脚本**：为不同实验室创建启动脚本，简化操作
+
+## 相关文档
+
+- [配置文件指南](configuration.md)
+- [启动参数详解](../user_guide/launch.md)
+
--- a/docs/concepts/01-communication-instruction.md
+++ b/docs/concepts/01-communication-instruction.md
@@ -1,7 +1,7 @@
 (instructions)=
 # 设备抽象、指令集与通信中间件

-Uni-Lab 操作系统的目的是将不同类型和厂家的实验仪器进行抽象统一，对应用层提供服务。因此，理清实验室设备之间的业务逻辑至关重要。
+Uni-Lab-OS的目的是将不同类型和厂家的实验仪器进行抽象统一，对应用层提供服务。因此，理清实验室设备之间的业务逻辑至关重要。

 ## 设备间通信模式

--- a/docs/conf.py
+++ b/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,
--- a/docs/developer_guide/action_includes.md
+++ b/docs/developer_guide/action_includes.md
@@ -156,383 +156,3 @@ Uni-Lab 生物操作指令集多数来自 [PyLabRobot](https://docs.pylabrobot.o
 ```

 ----
-## 机械臂、夹爪等机器人设备
-
-Uni-Lab 机械臂、机器人、夹爪和导航指令集沿用 ROS2 的 `control_msgs` 和 `nav2_msgs`：
-
-
-### `FollowJointTrajectory`
-
-```yaml
-# The trajectory for all revolute, continuous or prismatic joints
-trajectory_msgs/JointTrajectory trajectory
-# The trajectory for all planar or floating joints (i.e. individual joints with more than one DOF)
-trajectory_msgs/MultiDOFJointTrajectory multi_dof_trajectory
-
-# Tolerances for the trajectory.  If the measured joint values fall
-# outside the tolerances the trajectory goal is aborted.  Any
-# tolerances that are not specified (by being omitted or set to 0) are
-# set to the defaults for the action server (often taken from the
-# parameter server).
-
-# Tolerances applied to the joints as the trajectory is executed.  If
-# violated, the goal aborts with error_code set to
-# PATH_TOLERANCE_VIOLATED.
-JointTolerance[] path_tolerance
-JointComponentTolerance[] component_path_tolerance
-
-# To report success, the joints must be within goal_tolerance of the
-# final trajectory value.  The goal must be achieved by time the
-# trajectory ends plus goal_time_tolerance.  (goal_time_tolerance
-# allows some leeway in time, so that the trajectory goal can still
-# succeed even if the joints reach the goal some time after the
-# precise end time of the trajectory).
-#
-# If the joints are not within goal_tolerance after "trajectory finish
-# time" + goal_time_tolerance, the goal aborts with error_code set to
-# GOAL_TOLERANCE_VIOLATED
-JointTolerance[] goal_tolerance
-JointComponentTolerance[] component_goal_tolerance
-builtin_interfaces/Duration goal_time_tolerance
-
---
-int32 error_code
-int32 SUCCESSFUL = 0
-int32 INVALID_GOAL = -1
-int32 INVALID_JOINTS = -2
-int32 OLD_HEADER_TIMESTAMP = -3
-int32 PATH_TOLERANCE_VIOLATED = -4
-int32 GOAL_TOLERANCE_VIOLATED = -5
-
-# Human readable description of the error code. Contains complementary
-# information that is especially useful when execution fails, for instance:
-# - INVALID_GOAL: The reason for the invalid goal (e.g., the requested
-#   trajectory is in the past).
-# - INVALID_JOINTS: The mismatch between the expected controller joints
-#   and those provided in the goal.
-# - PATH_TOLERANCE_VIOLATED and GOAL_TOLERANCE_VIOLATED: Which joint
-#   violated which tolerance, and by how much.
-string error_string
-
---
-std_msgs/Header header
-string[] joint_names
-trajectory_msgs/JointTrajectoryPoint desired
-trajectory_msgs/JointTrajectoryPoint actual
-trajectory_msgs/JointTrajectoryPoint error
-
-string[] multi_dof_joint_names
-trajectory_msgs/MultiDOFJointTrajectoryPoint multi_dof_desired
-trajectory_msgs/MultiDOFJointTrajectoryPoint multi_dof_actual
-trajectory_msgs/MultiDOFJointTrajectoryPoint multi_dof_error
-
-```
-
----
-### `GripperCommand`
-
-```yaml
-GripperCommand command
---
-float64 position  # The current gripper gap size (in meters)
-float64 effort    # The current effort exerted (in Newtons)
-bool stalled      # True iff the gripper is exerting max effort and not moving
-bool reached_goal # True iff the gripper position has reached the commanded setpoint
---
-float64 position  # The current gripper gap size (in meters)
-float64 effort    # The current effort exerted (in Newtons)
-bool stalled      # True iff the gripper is exerting max effort and not moving
-bool reached_goal # True iff the gripper position has reached the commanded setpoint
-
-```
-
----
-### `JointTrajectory`
-
-```yaml
-trajectory_msgs/JointTrajectory trajectory
---
---
-
-```
-
----
-### `ParallelGripperCommand`
-
-```yaml
-# Parallel grippers refer to an end effector where two opposing fingers grasp an object from opposite sides.
-sensor_msgs/JointState command
-# name: the name(s) of the joint this command is requesting
-# position: desired position of each gripper joint (radians or meters)
-# velocity: (optional, not used if empty) max velocity of the joint allowed while moving (radians or meters / second)
-# effort: (optional, not used if empty) max effort of the joint allowed while moving (Newtons or Newton-meters)
---
-sensor_msgs/JointState state # The current gripper state.
-# position of each joint (radians or meters)
-# optional: velocity of each joint (radians or meters / second)
-# optional: effort of each joint (Newtons or Newton-meters)
-bool stalled      # True if the gripper is exerting max effort and not moving
-bool reached_goal # True if the gripper position has reached the commanded setpoint
---
-sensor_msgs/JointState state # The current gripper state.
-# position of each joint (radians or meters)
-# optional: velocity of each joint (radians or meters / second)
-# optional: effort of each joint (Newtons or Newton-meters)
-
-```
-
----
-### `PointHead`
-
-```yaml
-geometry_msgs/PointStamped target
-geometry_msgs/Vector3 pointing_axis
-string pointing_frame
-builtin_interfaces/Duration min_duration
-float64 max_velocity
---
---
-float64 pointing_angle_error
-
-```
-
----
-### `SingleJointPosition`
-
-```yaml
-float64 position
-builtin_interfaces/Duration min_duration
-float64 max_velocity
---
---
-std_msgs/Header header
-float64 position
-float64 velocity
-float64 error
-
-```
-
----
-### `AssistedTeleop`
-
-```yaml
-#goal definition
-builtin_interfaces/Duration time_allowance
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback
-builtin_interfaces/Duration current_teleop_duration
-
-```
-
----
-### `BackUp`
-
-```yaml
-#goal definition
-geometry_msgs/Point target
-float32 speed
-builtin_interfaces/Duration time_allowance
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback definition
-float32 distance_traveled
-
-```
-
----
-### `ComputePathThroughPoses`
-
-```yaml
-#goal definition
-geometry_msgs/PoseStamped[] goals
-geometry_msgs/PoseStamped start
-string planner_id
-bool use_start # If false, use current robot pose as path start, if true, use start above instead
---
-#result definition
-nav_msgs/Path path
-builtin_interfaces/Duration planning_time
---
-#feedback definition
-
-```
-
----
-### `ComputePathToPose`
-
-```yaml
-#goal definition
-geometry_msgs/PoseStamped goal
-geometry_msgs/PoseStamped start
-string planner_id
-bool use_start # If false, use current robot pose as path start, if true, use start above instead
---
-#result definition
-nav_msgs/Path path
-builtin_interfaces/Duration planning_time
---
-#feedback definition
-
-```
-
----
-### `DriveOnHeading`
-
-```yaml
-#goal definition
-geometry_msgs/Point target
-float32 speed
-builtin_interfaces/Duration time_allowance
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback definition
-float32 distance_traveled
-
-```
-
----
-### `DummyBehavior`
-
-```yaml
-#goal definition
-std_msgs/String command
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback definition
-
-```
-
----
-### `FollowPath`
-
-```yaml
-#goal definition
-nav_msgs/Path path
-string controller_id
-string goal_checker_id
---
-#result definition
-std_msgs/Empty result
---
-#feedback definition
-float32 distance_to_goal
-float32 speed
-
-```
-
----
-### `FollowWaypoints`
-
-```yaml
-#goal definition
-geometry_msgs/PoseStamped[] poses
---
-#result definition
-int32[] missed_waypoints
---
-#feedback definition
-uint32 current_waypoint
-
-```
-
----
-### `NavigateThroughPoses`
-
-```yaml
-#goal definition
-geometry_msgs/PoseStamped[] poses
-string behavior_tree
---
-#result definition
-std_msgs/Empty result
---
-#feedback definition
-geometry_msgs/PoseStamped current_pose
-builtin_interfaces/Duration navigation_time
-builtin_interfaces/Duration estimated_time_remaining
-int16 number_of_recoveries
-float32 distance_remaining
-int16 number_of_poses_remaining
-
-```
-
----
-### `NavigateToPose`
-
-```yaml
-#goal definition
-geometry_msgs/PoseStamped pose
-string behavior_tree
---
-#result definition
-std_msgs/Empty result
---
-#feedback definition
-geometry_msgs/PoseStamped current_pose
-builtin_interfaces/Duration navigation_time
-builtin_interfaces/Duration estimated_time_remaining
-int16 number_of_recoveries
-float32 distance_remaining
-
-```
-
----
-### `SmoothPath`
-
-```yaml
-#goal definition
-nav_msgs/Path path
-string smoother_id
-builtin_interfaces/Duration max_smoothing_duration
-bool check_for_collisions
---
-#result definition
-nav_msgs/Path path
-builtin_interfaces/Duration smoothing_duration
-bool was_completed
---
-#feedback definition
-
-```
-
----
-### `Spin`
-
-```yaml
-#goal definition
-float32 target_yaw
-builtin_interfaces/Duration time_allowance
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback definition
-float32 angular_distance_traveled
-
-```
-
----
-### `Wait`
-
-```yaml
-#goal definition
-builtin_interfaces/Duration time
---
-#result definition
-builtin_interfaces/Duration total_elapsed_time
---
-#feedback definition
-builtin_interfaces/Duration time_left
-
-```
-
----
--- a/docs/developer_guide/add_device.md
+++ b/docs/developer_guide/add_device.md
@@ -1,10 +1,18 @@
-# 添加新设备
+# 添加设备：编写驱动

-在 Uni-Lab 中，设备（Device）是实验操作的基础单元。Uni-Lab 使用**注册表机制**来兼容管理种类繁多的设备驱动程序。回顾 {ref}`instructions` 中的概念，抽象的设备对外拥有【话题】【服务】【动作】三种通信机制，因此将设备添加进 Uni-Lab，实际上是将设备驱动中的三种机制映射到 Uni-Lab 标准指令集上。
+在 Uni-Lab 中，设备（Device）是实验操作的基础单元。Uni-Lab 使用**注册表机制**来兼容管理种类繁多的设备驱动程序。抽象的设备对外拥有【话题】【服务】【动作】三种通信机制，因此将设备添加进 Uni-Lab，实际上是将设备驱动中的这三种机制映射到 Uni-Lab 标准指令集上。

-能被 Uni-Lab 添加的驱动程序类型有以下种类：
+> **💡 提示：** 本文档介绍如何使用已有的设备驱动（SDK）。若设备没有现成的驱动程序，需要自己开发驱动，请参考 {doc}`add_old_device`。

-1. Python Class，如
+## 支持的驱动类型
+
+Uni-Lab 支持以下两种驱动程序：
+
+### 1. Python Class（推荐）
+
+Python 类设备驱动在完成注册表后可以直接在 Uni-Lab 中使用，无需额外编译。
+
+**示例：**

 ```python
 class MockGripper:
@@ -31,12 +39,11 @@ class MockGripper:
    def status(self) -> str:
        return self._status

-    # 会被自动识别的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
    @status.setter
    def status(self, target):
        self._status = target

-    # 需要在注册表添加的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
+    # 会被自动识别的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
    def push_to(self, position: float, torque: float, velocity: float = 0.0):
        self._status = "Running"
        current_pos = self.position
@@ -53,9 +60,11 @@ class MockGripper:
        self._status = "Idle"
 ```

-Python 类设备驱动在完成注册表后可以直接在 Uni-Lab 使用。
+### 2. C# Class

-2. C# Class，如
+C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能使用（仅需一次）。
+
+**示例：**

 ```csharp
 using System;
@@ -84,7 +93,7 @@ public class MockGripper
            position = currentPos + (Position - currentPos) / 20 * (i + 1);
            torque = Torque / (20 - i);
            velocity = Velocity;
-            await Task.Delay((int)(moveTime * 1000 / 20)); // Convert seconds to milliseconds
+            await Task.Delay((int)(moveTime * 1000 / 20));
        }
        torque = Torque;
        status = "Idle";
@@ -92,12 +101,16 @@ public class MockGripper
 }
 ```

-C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能使用，但只需一次。
+---

-## 快速开始：使用注册表编辑器（推荐）
+## 快速开始：两种方式添加设备
+
+### 方式 1：使用注册表编辑器（推荐）

 推荐使用 Uni-Lab-OS 自带的可视化编辑器，它能自动分析您的设备驱动并生成大部分配置：

+**步骤：**
+
 1. 启动 Uni-Lab-OS
 2. 在浏览器中打开"注册表编辑器"页面
 3. 选择您的 Python 设备驱动文件
@@ -106,13 +119,18 @@ C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能
 6. 点击"生成注册表"，复制生成的内容
 7. 保存到 `devices/` 目录下

---
+**优点：**

-## 手动编写注册表（简化版）
+- 自动识别设备属性和方法
+- 可视化界面，易于操作
+- 自动生成完整配置
+- 减少手动配置错误
+
+### 方式 2：手动编写注册表（简化版）

 如果需要手动编写，只需要提供两个必需字段，系统会自动补全其余内容：

-### 最小配置示例
+**最小配置示例：**

 ```yaml
 my_device: # 设备唯一标识符
@@ -121,22 +139,22 @@ my_device: # 设备唯一标识符
    type: python # 驱动类型
 ```

-### 注册表文件位置
+**注册表文件位置：**

 - 默认路径：`unilabos/registry/devices`
- 自定义路径：启动时使用 `--registry` 参数指定
- 可将多个设备写在同一个 yaml 文件中
+- 自定义路径：启动时使用 `--registry_path` 参数指定
+- 可将多个设备写在同一个 YAML 文件中

-### 系统自动生成的内容
+**系统自动生成的内容：**

 系统会自动分析您的 Python 驱动类并生成：

- `status_types`：从 `get_*` 方法自动识别状态属性
+- `status_types`：从 `@property` 装饰的方法自动识别状态属性
 - `action_value_mappings`：从类方法自动生成动作映射
 - `init_param_schema`：从 `__init__` 方法分析初始化参数
 - `schema`：前端显示用的属性类型定义

-### 完整结构概览
+**完整结构概览：**

 ```yaml
 my_device:
@@ -151,4 +169,848 @@ my_device:
  schema: {} # 自动生成
 ```

-详细的注册表编写指南和高级配置，请参考{doc}`yaml 注册表编写指南 <add_yaml>`。
+> 💡 **提示：** 详细的注册表编写指南和高级配置，请参考 {doc}`03_add_device_registry`。
+
+---
+
+## Python 类结构要求
+
+Uni-Lab 设备驱动是一个 Python 类，需要遵循以下结构：
+
+```python
+from typing import Dict, Any
+
+class MyDevice:
+    """设备类文档字符串
+
+    说明设备的功能、连接方式等
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """初始化设备
+
+        Args:
+            config: 配置字典，来自图文件或注册表
+        """
+        self.port = config.get('port', '/dev/ttyUSB0')
+        self.baudrate = config.get('baudrate', 9600)
+        self._status = "idle"
+        # 初始化硬件连接
+
+    @property
+    def status(self) -> str:
+        """设备状态（会自动广播）"""
+        return self._status
+
+    def my_action(self, param: float) -> Dict[str, Any]:
+        """执行动作
+
+        Args:
+            param: 参数说明
+
+        Returns:
+            {"success": True, "result": ...}
+        """
+        # 执行设备操作
+        return {"success": True}
+```
+
+## 状态属性 vs 动作方法
+
+### 状态属性（@property）
+
+状态属性会被自动识别并定期广播：
+
+```python
+@property
+def temperature(self) -> float:
+    """当前温度"""
+    return self._read_temperature()
+
+@property
+def status(self) -> str:
+    """设备状态: idle, running, error"""
+    return self._status
+
+@property
+def is_ready(self) -> bool:
+    """设备是否就绪"""
+    return self._status == "idle"
+```
+
+**特点**:
+
+- 使用`@property`装饰器
+- 只读，不能有参数
+- 自动添加到注册表的`status_types`
+- 定期发布到 ROS2 topic
+
+### 动作方法
+
+动作方法是设备可以执行的操作：
+
+```python
+def start_heating(self, target_temp: float, rate: float = 1.0) -> Dict[str, Any]:
+    """开始加热
+
+    Args:
+        target_temp: 目标温度(°C)
+        rate: 升温速率(°C/min)
+
+    Returns:
+        {"success": bool, "message": str}
+    """
+    self._status = "heating"
+    self._target_temp = target_temp
+    # 发送命令到硬件
+    return {"success": True, "message": f"Heating to {target_temp}°C"}
+
+async def async_operation(self, duration: float) -> Dict[str, Any]:
+    """异步操作（长时间运行）
+
+    Args:
+        duration: 持续时间(秒)
+    """
+    # 使用 self.sleep 而不是 asyncio.sleep（ROS2 异步机制）
+    await self.sleep(duration)
+    return {"success": True}
+```
+
+**特点**:
+
+- 普通方法或 async 方法
+- 返回 Dict 类型的结果
+- 自动注册为 ROS2 Action
+- 支持参数和返回值
+
+### 返回值设计指南
+
+> **⚠️ 重要：返回值会自动显示在前端**
+>
+> 动作方法的返回值（字典）会自动显示在 Web 界面的工作流执行结果中。因此，**强烈建议**设计结构化、可读的返回值字典。
+
+**推荐的返回值结构：**
+
+```python
+def my_action(self, param: float) -> Dict[str, Any]:
+    """执行操作"""
+    try:
+        # 执行操作...
+        result = self._do_something(param)
+
+        return {
+            "success": True,              # 必需：操作是否成功
+            "message": "操作完成",          # 推荐：用户友好的消息
+            "result": result,             # 可选：具体结果数据
+            "param_used": param,          # 可选：记录使用的参数
+            # 其他有用的信息...
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "操作失败"
+        }
+```
+
+**最佳实践示例（参考 `host_node.test_latency`）：**
+
+```python
+def test_latency(self) -> Dict[str, Any]:
+    """测试网络延迟
+
+    返回值会在前端显示，包含详细的测试结果
+    """
+    # 执行测试...
+    avg_rtt_ms = 25.5
+    avg_time_diff_ms = 10.2
+    test_count = 5
+
+    # 返回结构化的测试结果
+    return {
+        "status": "success",                    # 状态标识
+        "avg_rtt_ms": avg_rtt_ms,              # 平均往返时间
+        "avg_time_diff_ms": avg_time_diff_ms,  # 平均时间差
+        "max_time_error_ms": 5.3,              # 最大误差
+        "task_delay_ms": 15.7,                 # 任务延迟
+        "test_count": test_count,              # 测试次数
+    }
+```
+
+**前端显示效果：**
+
+当用户在 Web 界面执行工作流时，返回的字典会以 JSON 格式显示在结果面板中：
+
+```json
+{
+  "status": "success",
+  "avg_rtt_ms": 25.5,
+  "avg_time_diff_ms": 10.2,
+  "max_time_error_ms": 5.3,
+  "task_delay_ms": 15.7,
+  "test_count": 5
+}
+```
+
+**返回值设计建议：**
+
+1. **始终包含 `success` 字段**：布尔值，表示操作是否成功
+2. **包含 `message` 字段**：字符串，提供用户友好的描述
+3. **使用有意义的键名**：使用描述性的键名（如 `avg_rtt_ms` 而不是 `v1`）
+4. **包含单位**：在键名中包含单位（如 `_ms`、`_ml`、`_celsius`）
+5. **记录重要参数**：返回使用的关键参数值，便于追溯
+6. **错误信息详细**：失败时包含 `error` 字段和详细的错误描述
+7. **避免返回大数据**：不要返回大型数组或二进制数据，这会影响前端性能
+
+**错误处理示例：**
+
+```python
+def risky_operation(self, param: float) -> Dict[str, Any]:
+    """可能失败的操作"""
+    if param < 0:
+        return {
+            "success": False,
+            "error": "参数不能为负数",
+            "message": f"无效参数: {param}",
+            "param": param
+        }
+
+    try:
+        result = self._execute(param)
+        return {
+            "success": True,
+            "message": "操作成功",
+            "result": result,
+            "param": param
+        }
+    except IOError as e:
+        return {
+            "success": False,
+            "error": "通信错误",
+            "message": str(e),
+            "device_status": self._status
+        }
+```
+
+## 特殊参数类型：ResourceSlot 和 DeviceSlot
+
+Uni-Lab 提供特殊的参数类型，用于在方法中声明需要选择资源或设备。
+
+### 导入类型
+
+```python
+from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
+from typing import List
+```
+
+### ResourceSlot - 资源选择
+
+用于需要选择物料资源的场景：
+
+```python
+def pipette_liquid(
+    self,
+    source: ResourceSlot,              # 单个源容器
+    target: ResourceSlot,              # 单个目标容器
+    volume: float
+) -> Dict[str, Any]:
+    """从源容器吸取液体到目标容器
+
+    Args:
+        source: 源容器（前端会显示资源选择下拉框）
+        target: 目标容器（前端会显示资源选择下拉框）
+        volume: 体积(μL)
+    """
+    print(f"Pipetting {volume}μL from {source.id} to {target.id}")
+    return {"success": True}
+```
+
+**多选示例**:
+
+```python
+def mix_multiple(
+    self,
+    containers: List[ResourceSlot],    # 多个容器选择
+    speed: float
+) -> Dict[str, Any]:
+    """混合多个容器
+
+    Args:
+        containers: 容器列表（前端会显示多选下拉框）
+        speed: 混合速度
+    """
+    for container in containers:
+        print(f"Mixing {container.name}")
+    return {"success": True}
+```
+
+### DeviceSlot - 设备选择
+
+用于需要选择其他设备的场景：
+
+```python
+def coordinate_with_device(
+    self,
+    other_device: DeviceSlot,          # 单个设备选择
+    command: str
+) -> Dict[str, Any]:
+    """与另一个设备协同工作
+
+    Args:
+        other_device: 协同设备（前端会显示设备选择下拉框）
+        command: 命令
+    """
+    print(f"Coordinating with {other_device.name}")
+    return {"success": True}
+```
+
+**多设备示例**:
+
+```python
+def sync_devices(
+    self,
+    devices: List[DeviceSlot],         # 多个设备选择
+    sync_signal: str
+) -> Dict[str, Any]:
+    """同步多个设备
+
+    Args:
+        devices: 设备列表（前端会显示多选下拉框）
+        sync_signal: 同步信号
+    """
+    for dev in devices:
+        print(f"Syncing {dev.name}")
+    return {"success": True}
+```
+
+### 完整示例：液体处理工作站
+
+```python
+from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
+from typing import List, Dict, Any
+
+class LiquidHandler:
+    """液体处理工作站"""
+
+    def __init__(self, config: Dict[str, Any]):
+        self.simulation = config.get('simulation', False)
+        self._status = "idle"
+
+    @property
+    def status(self) -> str:
+        return self._status
+
+    def transfer_liquid(
+        self,
+        source: ResourceSlot,               # 源容器选择
+        target: ResourceSlot,               # 目标容器选择
+        volume: float,
+        tip: ResourceSlot = None            # 可选的枪头选择
+    ) -> Dict[str, Any]:
+        """转移液体
+
+        前端效果：
+        - source: 下拉框，列出所有可用容器
+        - target: 下拉框，列出所有可用容器
+        - volume: 数字输入框
+        - tip: 下拉框（可选），列出所有枪头
+        """
+        self._status = "transferring"
+
+        # source和target会被解析为实际的资源对象
+        print(f"Transferring {volume}μL")
+        print(f"  From: {source.id} ({source.name})")
+        print(f"  To: {target.id} ({target.name})")
+
+        if tip:
+            print(f"  Using tip: {tip.id}")
+
+        # 执行实际的液体转移
+        # ...
+
+        self._status = "idle"
+        return {
+            "success": True,
+            "volume_transferred": volume,
+            "source_id": source.id,
+            "target_id": target.id
+        }
+
+    def multi_dispense(
+        self,
+        source: ResourceSlot,               # 单个源
+        targets: List[ResourceSlot],        # 多个目标
+        volumes: List[float]
+    ) -> Dict[str, Any]:
+        """从一个源分配到多个目标
+
+        前端效果：
+        - source: 单选下拉框
+        - targets: 多选下拉框（可选择多个容器）
+        - volumes: 数组输入（每个目标对应一个体积）
+        """
+        results = []
+        for target, vol in zip(targets, volumes):
+            print(f"Dispensing {vol}μL to {target.name}")
+            results.append({
+                "target": target.id,
+                "volume": vol
+            })
+
+        return {
+            "success": True,
+            "dispense_results": results
+        }
+
+    def test_with_balance(
+        self,
+        target: ResourceSlot,               # 容器
+        balance: DeviceSlot                 # 天平设备
+    ) -> Dict[str, Any]:
+        """使用天平测量容器
+
+        前端效果：
+        - target: 容器选择下拉框
+        - balance: 设备选择下拉框（仅显示天平类型）
+        """
+        print(f"Weighing {target.name} on {balance.name}")
+
+        # 可以调用balance的方法
+        # weight = balance.get_weight()
+
+        return {
+            "success": True,
+            "container": target.id,
+            "balance_used": balance.id
+        }
+```
+
+### 工作原理
+
+#### 1. 类型识别
+
+注册表扫描方法签名时：
+
+```python
+def my_method(self, resource: ResourceSlot, device: DeviceSlot):
+    pass
+```
+
+系统识别到`ResourceSlot`和`DeviceSlot`类型。
+
+#### 2. 自动添加 placeholder_keys
+
+在注册表中自动生成：
+
+```yaml
+my_device:
+  class:
+    action_value_mappings:
+      my_method:
+        goal:
+          resource: resource
+          device: device
+        placeholder_keys:
+          resource: unilabos_resources # 自动添加！
+          device: unilabos_devices # 自动添加！
+```
+
+#### 3. 前端 UI 生成
+
+- `unilabos_resources`: 渲染为资源选择下拉框
+- `unilabos_devices`: 渲染为设备选择下拉框
+
+#### 4. 运行时解析
+
+用户选择资源/设备后，实际调用时会传入完整的资源/设备对象：
+
+```python
+# 用户在前端选择了 plate_1
+# 运行时，source参数会收到完整的Resource对象
+source.id        # "plate_1"
+source.name      # "96孔板"
+source.type      # "resource"
+source.class_    # "corning_96_wellplate_360ul_flat"
+```
+
+## 支持的通信方式
+
+### 1. 串口（Serial）
+
+```python
+import serial
+
+class SerialDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.port = config['port']
+        self.baudrate = config.get('baudrate', 9600)
+        self.ser = serial.Serial(
+            port=self.port,
+            baudrate=self.baudrate,
+            timeout=1
+        )
+
+    def send_command(self, cmd: str) -> str:
+        """发送命令并读取响应"""
+        self.ser.write(f"{cmd}\r\n".encode())
+        response = self.ser.readline().decode().strip()
+        return response
+
+    def __del__(self):
+        if hasattr(self, 'ser') and self.ser.is_open:
+            self.ser.close()
+```
+
+### 2. TCP/IP Socket
+
+```python
+import socket
+
+class TCPDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.host = config['host']
+        self.port = config['port']
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.sock.connect((self.host, self.port))
+
+    def send_command(self, cmd: str) -> str:
+        self.sock.sendall(cmd.encode())
+        response = self.sock.recv(1024).decode()
+        return response
+```
+
+### 3. Modbus
+
+```python
+from pymodbus.client import ModbusTcpClient
+
+class ModbusDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.host = config['host']
+        self.port = config.get('port', 502)
+        self.client = ModbusTcpClient(self.host, port=self.port)
+        self.client.connect()
+
+    def read_register(self, address: int) -> int:
+        result = self.client.read_holding_registers(address, 1)
+        return result.registers[0]
+
+    def write_register(self, address: int, value: int):
+        self.client.write_register(address, value)
+```
+
+### 4. OPC UA
+
+```python
+from opcua import Client
+
+class OPCUADevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.url = config['url']
+        self.client = Client(self.url)
+        self.client.connect()
+
+    def read_node(self, node_id: str):
+        node = self.client.get_node(node_id)
+        return node.get_value()
+
+    def write_node(self, node_id: str, value):
+        node = self.client.get_node(node_id)
+        node.set_value(value)
+```
+
+### 5. HTTP/RPC
+
+```python
+import requests
+
+class HTTPDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.base_url = config['url']
+        self.auth_token = config.get('token')
+
+    def send_command(self, endpoint: str, data: Dict) -> Dict:
+        url = f"{self.base_url}/{endpoint}"
+        headers = {'Authorization': f'Bearer {self.auth_token}'}
+        response = requests.post(url, json=data, headers=headers)
+        return response.json()
+```
+
+## 异步 vs 同步方法
+
+### 同步方法（适合快速操作）
+
+```python
+def quick_operation(self, param: float) -> Dict[str, Any]:
+    """快速操作，立即返回"""
+    result = self._do_something(param)
+    return {"success": True, "result": result}
+```
+
+### 异步方法（适合耗时操作）
+
+```python
+async def long_operation(self, duration: float) -> Dict[str, Any]:
+    """长时间运行的操作"""
+    self._status = "running"
+
+    # 使用 ROS2 提供的 sleep 方法（而不是 asyncio.sleep）
+    await self.sleep(duration)
+
+    # 可以在过程中发送feedback
+    # 需要配合ROS2 Action的feedback机制
+
+    self._status = "idle"
+    return {"success": True, "duration": duration}
+```
+
+> **⚠️ 重要提示：ROS2 异步机制 vs Python asyncio**
+>
+> Uni-Lab 的设备驱动虽然使用 `async def` 语法，但**底层是 ROS2 的异步机制，而不是 Python 的 asyncio**。
+>
+> **不能使用的 asyncio 功能：**
+>
+> - ❌ `asyncio.sleep()` - 会导致 ROS2 事件循环阻塞
+> - ❌ `asyncio.create_task()` - 任务不会被 ROS2 正确调度
+> - ❌ `asyncio.gather()` - 无法与 ROS2 集成
+> - ❌ 其他 asyncio 标准库函数
+>
+> **应该使用的方法（继承自 BaseROS2DeviceNode）：**
+>
+> - ✅ `await self.sleep(seconds)` - ROS2 兼容的睡眠
+> - ✅ `await self.create_task(func, **kwargs)` - ROS2 兼容的任务创建
+> - ✅ ROS2 的 Action/Service 回调机制
+>
+> **示例：**
+>
+> ```python
+> async def complex_operation(self, duration: float) -> Dict[str, Any]:
+>     """正确使用 ROS2 异步方法"""
+>     self._status = "processing"
+>
+>     # ✅ 正确：使用 self.sleep
+>     await self.sleep(duration)
+>
+>     # ✅ 正确：创建并发任务
+>     task = await self.create_task(self._background_work)
+>
+>     # ❌ 错误：不要使用 asyncio
+>     # await asyncio.sleep(duration)  # 这会导致问题！
+>     # task = asyncio.create_task(...)  # 这也不行！
+>
+>     self._status = "idle"
+>     return {"success": True}
+>
+> async def _background_work(self):
+>     """后台任务"""
+>     await self.sleep(1.0)
+>     self.lab_logger().info("Background work completed")
+> ```
+>
+> **为什么不能混用？**
+>
+> ROS2 使用 `rclpy` 的事件循环来管理所有异步操作。如果使用 `asyncio` 的函数，这些操作会在不同的事件循环中运行，导致：
+>
+> - ROS2 回调无法正确执行
+> - 任务可能永远不会完成
+> - 程序可能死锁或崩溃
+>
+> **参考实现：**
+>
+> `BaseROS2DeviceNode` 提供的方法定义（`base_device_node.py:563-572`）：
+>
+> ```python
+> async def sleep(self, rel_time: float, callback_group=None):
+>     """ROS2 兼容的异步睡眠"""
+>     if callback_group is None:
+>         callback_group = self.callback_group
+>     await ROS2DeviceNode.async_wait_for(self, rel_time, callback_group)
+>
+> @classmethod
+> async def create_task(cls, func, trace_error=True, **kwargs) -> Task:
+>     """ROS2 兼容的任务创建"""
+>     return ROS2DeviceNode.run_async_func(func, trace_error, **kwargs)
+> ```
+
+## 错误处理
+
+### 基本错误处理
+
+```python
+def operation_with_error_handling(self, param: float) -> Dict[str, Any]:
+    """带错误处理的操作"""
+    try:
+        result = self._risky_operation(param)
+        return {
+            "success": True,
+            "result": result
+        }
+    except ValueError as e:
+        return {
+            "success": False,
+            "error": "Invalid parameter",
+            "message": str(e)
+        }
+    except IOError as e:
+        self._status = "error"
+        return {
+            "success": False,
+            "error": "Communication error",
+            "message": str(e)
+        }
+```
+
+### 自定义异常
+
+```python
+class DeviceError(Exception):
+    """设备错误基类"""
+    pass
+
+class DeviceNotReadyError(DeviceError):
+    """设备未就绪"""
+    pass
+
+class DeviceTimeoutError(DeviceError):
+    """设备超时"""
+    pass
+
+class MyDevice:
+    def operation(self) -> Dict[str, Any]:
+        if self._status != "idle":
+            raise DeviceNotReadyError(f"Device is {self._status}")
+
+        # 执行操作
+        return {"success": True}
+```
+
+## 最佳实践
+
+### 1. 类型注解
+
+```python
+from typing import Dict, Any, Optional, List
+
+def method(
+    self,
+    param1: float,
+    param2: str,
+    optional_param: Optional[int] = None
+) -> Dict[str, Any]:
+    """完整的类型注解有助于自动生成注册表"""
+    pass
+```
+
+### 2. 文档字符串
+
+```python
+def method(self, param: float) -> Dict[str, Any]:
+    """方法简短描述
+
+    更详细的说明...
+
+    Args:
+        param: 参数说明，包括单位和范围
+
+    Returns:
+        Dict包含:
+        - success (bool): 是否成功
+        - result (Any): 结果数据
+
+    Raises:
+        DeviceError: 错误情况说明
+    """
+    pass
+```
+
+### 3. 配置验证
+
+```python
+def __init__(self, config: Dict[str, Any]):
+    # 验证必需参数
+    required = ['port', 'baudrate']
+    for key in required:
+        if key not in config:
+            raise ValueError(f"Missing required config: {key}")
+
+    self.port = config['port']
+    self.baudrate = config['baudrate']
+```
+
+### 4. 资源清理
+
+```python
+def __del__(self):
+    """析构函数，清理资源"""
+    if hasattr(self, 'connection') and self.connection:
+        self.connection.close()
+```
+
+### 5. 设计前端友好的返回值
+
+**记住：返回值会直接显示在 Web 界面**
+
+```python
+import time
+
+def measure_temperature(self) -> Dict[str, Any]:
+    """测量温度
+
+    ✅ 好的返回值设计：
+    - 包含 success 状态
+    - 使用描述性键名
+    - 在键名中包含单位
+    - 记录测量时间
+    """
+    temp = self._read_temperature()
+
+    return {
+        "success": True,
+        "temperature_celsius": temp,      # 键名包含单位
+        "timestamp": time.time(),          # 记录时间
+        "sensor_status": "normal",         # 额外状态信息
+        "message": f"温度测量完成: {temp}°C"  # 用户友好的消息
+    }
+
+def bad_example(self) -> Dict[str, Any]:
+    """❌ 不好的返回值设计"""
+    return {
+        "s": True,          # ❌ 键名不明确
+        "v": 25.5,          # ❌ 没有说明单位
+        "t": 1234567890,    # ❌ 不清楚是什么时间戳
+    }
+```
+
+**参考 `host_node.test_latency` 方法**（第 1216-1340 行），它返回详细的测试结果，在前端清晰显示：
+
+```python
+return {
+    "status": "success",
+    "avg_rtt_ms": 25.5,            # 有意义的键名 + 单位
+    "avg_time_diff_ms": 10.2,
+    "max_time_error_ms": 5.3,
+    "task_delay_ms": 15.7,
+    "test_count": 5,               # 记录重要信息
+}
+```
+
+## 下一步
+
+看完本文档后，建议继续阅读：
+
+- {doc}`add_action` - 了解如何添加新的动作指令
+- {doc}`add_yaml` - 学习如何编写和完善 YAML 注册表
+
+进阶主题：
+
+- {doc}`03_add_device_registry` - 了解如何配置注册表
+- {doc}`04_add_device_testing` - 学习如何测试设备
+- {doc}`add_old_device` - 没有 SDK 时如何开发设备驱动
+
+## 参考
+
+- [Python 类型注解](https://docs.python.org/3/library/typing.html)
+- [ROS2 rclpy 异步编程](https://docs.ros.org/en/humble/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.html) - Uni-Lab 使用 ROS2 的异步机制
+- [串口通信](https://pyserial.readthedocs.io/)
+
+> **注意：** 虽然设备驱动使用 `async def` 语法，但请**不要参考** Python 标准的 [asyncio 文档](https://docs.python.org/3/library/asyncio.html)。Uni-Lab 使用的是 ROS2 的异步机制，两者不兼容。请使用 `self.sleep()` 和 `self.create_task()` 等 BaseROS2DeviceNode 提供的方法。
--- a/docs/developer_guide/add_old_device.md
+++ b/docs/developer_guide/add_old_device.md
@@ -1,8 +1,10 @@
-# 设备 Driver 开发
+# 设备 Driver 开发（无 SDK 设备）

 我们对设备 Driver 的定义，是一个 Python/C++/C# 类，类的方法可以用于获取传感器数据、执行设备动作、更新物料信息。它们经过 Uni-Lab 的通信中间件包装，就能成为高效分布式通信的设备节点。

-因此，若已有设备的 SDK (Driver)，可以直接 [添加进 Uni-Lab](add_device.md)。仅当没有 SDK (Driver) 时，请参考本章作开发。
+因此，若已有设备的 SDK (Driver)，可以直接 [添加进 Uni-Lab](add_device.md)。**仅当没有 SDK (Driver) 时，请参考本章进行驱动开发。**
+
+> **💡 提示：** 本文档介绍如何为没有现成驱动的老设备开发驱动程序。如果您的设备已经有 SDK 或驱动，请直接参考 {doc}`add_device`。

 ## 有串口字符串指令集文档的设备：Python 串口通信（常见 RS485, RS232, USB）

@@ -12,13 +14,13 @@

 Modbus 与 RS485、RS232 不一样的地方在于，会有更多直接寄存器的读写，以及涉及字节序转换（Big Endian, Little Endian）。

-Uni-Lab 开发团队在仓库中提供了3个样例：
+Uni-Lab 开发团队在仓库中提供了 3 个样例：

-* 单一机械设备**电夹爪**，通讯协议可见 [增广夹爪通讯协议](https://doc.rmaxis.com/docs/communication/fieldbus/)，驱动代码位于 `unilabos/devices/gripper/rmaxis_v4.py`
-* 单一通信设备**IO板卡**，驱动代码位于 `unilabos/device_comms/gripper/SRND_16_IO.py`
-* 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`
+- 单一机械设备**电夹爪**，通讯协议可见 [增广夹爪通讯协议](https://doc.rmaxis.com/docs/communication/fieldbus/)，驱动代码位于 `unilabos/devices/gripper/rmaxis_v4.py`
+- 单一通信设备**IO 板卡**，驱动代码位于 `unilabos/device_comms/gripper/SRND_16_IO.py`
+- 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`

-****
+---

 ## 其他工业通信协议：CANopen, Ethernet, OPCUA...

@@ -26,32 +28,32 @@ Uni-Lab 开发团队在仓库中提供了3个样例：

 ## 没有接口的老设备老软件：使用 PyWinAuto

-**pywinauto**是一个 Python 库，用于自动化Windows GUI操作。它可以模拟用户的鼠标点击、键盘输入、窗口操作等，广泛应用于自动化测试、GUI自动化等场景。它支持通过两个后端进行操作：
+**pywinauto**是一个 Python 库，用于自动化 Windows GUI 操作。它可以模拟用户的鼠标点击、键盘输入、窗口操作等，广泛应用于自动化测试、GUI 自动化等场景。它支持通过两个后端进行操作：

-* **win32**后端：适用于大多数Windows应用程序，使用native Win32 API。（pywinauto_recorder默认使用win32后端）
-* **uia**后端：基于Microsoft UI Automation，适用于较新的应用程序，特别是基于WPF或UWP的应用程序。（在win10上，会有更全的目录，有的窗口win32会识别不到）
+- **win32**后端：适用于大多数 Windows 应用程序，使用 native Win32 API。（pywinauto_recorder 默认使用 win32 后端）
+- **uia**后端：基于 Microsoft UI Automation，适用于较新的应用程序，特别是基于 WPF 或 UWP 的应用程序。（在 win10 上，会有更全的目录，有的窗口 win32 会识别不到）

-### windows平台安装pywinauto和pywinauto_recorder
+### windows 平台安装 pywinauto 和 pywinauto_recorder

 直接安装会造成环境崩溃，需要下载并解压已经修改好的文件。

-cd到对应目录，执行安装
+cd 到对应目录，执行安装

-`pip install . -i ``https://pypi.tuna.tsinghua.edu.cn/simple`
+` pip install . -i ``https://pypi.tuna.tsinghua.edu.cn/simple `

 ![pywinauto_install](image/device_driver/pywinauto_install.png)

-windows平台测试 python pywinauto_recorder.py，退出使用两次ctrl+alt+r取消选中，关闭命令提示符。
+windows 平台测试 python pywinauto_recorder.py，退出使用两次 ctrl+alt+r 取消选中，关闭命令提示符。

 ### 计算器例子

-你可以先打开windows的计算器，然后在ilab的环境中运行下面的代码片段，可观察到得到结果，通过这一案例，你需要掌握的pywinauto用法：
+你可以先打开 windows 的计算器，然后在 ilab 的环境中运行下面的代码片段，可观察到得到结果，通过这一案例，你需要掌握的 pywinauto 用法：

-* 连接到指定进程
-* 利用dump_tree查找需要的窗口
-* 获取某个位置的信息
-* 模拟点击
-* 模拟输入
+- 连接到指定进程
+- 利用 dump_tree 查找需要的窗口
+- 获取某个位置的信息
+- 模拟点击
+- 模拟输入

 #### 代码学习

@@ -74,39 +76,39 @@ window.dump_tree(depth=3)
 Dialog - '计算器'    (L-419, T773, R-73, B1287)
 ['计算器Dialog', 'Dialog', '计算器', '计算器Dialog0', '计算器Dialog1', 'Dialog0', 'Dialog1', '计算器0', '计算器1']
 child_window(title="计算器", control_type="Window")
-   | 
+   |
   | Dialog - '计算器'    (L-269, T774, R-81, B806)
   | ['计算器Dialog2', 'Dialog2', '计算器2']
   | child_window(title="计算器", auto_id="TitleBar", control_type="Window")
-   |    | 
+   |    |
   |    | Menu - '系统'    (L0, T0, R0, B0)
   |    | ['Menu', '系统', '系统Menu', '系统0', '系统1']
   |    | child_window(title="系统", auto_id="SystemMenuBar", control_type="MenuBar")
-   |    | 
+   |    |
   |    | Button - '最小化 计算器'    (L-219, T774, R-173, B806)
   |    | ['Button', '最小化 计算器Button', '最小化 计算器', 'Button0', 'Button1']
   |    | child_window(title="最小化 计算器", auto_id="Minimize", control_type="Button")
-   |    | 
+   |    |
   |    | Button - '使 计算器 最大化'    (L-173, T774, R-127, B806)
   |    | ['Button2', '使 计算器 最大化', '使 计算器 最大化Button']
   |    | child_window(title="使 计算器 最大化", auto_id="Maximize", control_type="Button")
-   |    | 
+   |    |
   |    | Button - '关闭 计算器'    (L-127, T774, R-81, B806)
   |    | ['Button3', '关闭 计算器Button', '关闭 计算器']
   |    | child_window(title="关闭 计算器", auto_id="Close", control_type="Button")
-   | 
+   |
   | Dialog - '计算器'    (L-411, T774, R-81, B1279)
   | ['计算器Dialog3', 'Dialog3', '计算器3']
   | child_window(title="计算器", control_type="Window")
-   |    | 
+   |    |
   |    | Static - '计算器'    (L-363, T782, R-327, B798)
   |    | ['计算器Static', 'Static', '计算器4', 'Static0', 'Static1']
   |    | child_window(title="计算器", auto_id="AppName", control_type="Text")
-   |    | 
+   |    |
   |    | Custom - ''    (L-411, T806, R-81, B1279)
   |    | ['Custom', '计算器Custom']
   |    | child_window(auto_id="NavView", control_type="Custom")
-   | 
+   |
   | Pane - ''    (L-411, T806, R-81, B1279)
   | ['Pane', '计算器Pane']
 """
@@ -122,58 +124,58 @@ target_window.dump_tree(depth=3)
 Custom - ''    (L-411, T806, R-81, B1279)
 ['标准Custom', 'Custom']
 child_window(auto_id="NavView", control_type="Custom")
-   | 
+   |
   | Button - '打开导航'    (L-407, T812, R-367, B848)
   | ['打开导航Button', '打开导航', 'Button', 'Button0', 'Button1']
   | child_window(title="打开导航", auto_id="TogglePaneButton", control_type="Button")
-   |    | 
+   |    |
   |    | Static - ''    (L0, T0, R0, B0)
   |    | ['Static', 'Static0', 'Static1']
   |    | child_window(auto_id="PaneTitleTextBlock", control_type="Text")
-   | 
+   |
   | GroupBox - ''    (L-411, T814, R-81, B1275)
   | ['标准GroupBox', 'GroupBox', 'GroupBox0', 'GroupBox1']
-   |    | 
+   |    |
   |    | Static - '表达式为 '    (L0, T0, R0, B0)
   |    | ['表达式为 ', 'Static2', '表达式为 Static']
   |    | child_window(title="表达式为 ", auto_id="CalculatorExpression", control_type="Text")
-   |    | 
+   |    |
   |    | Static - '显示为 0'    (L-411, T875, R-81, B947)
   |    | ['显示为 0Static', '显示为 0', 'Static3']
   |    | child_window(title="显示为 0", auto_id="CalculatorResults", control_type="Text")
-   |    | 
+   |    |
   |    | Button - '打开历史记录浮出控件'    (L-121, T814, R-89, B846)
   |    | ['打开历史记录浮出控件', '打开历史记录浮出控件Button', 'Button2']
   |    | child_window(title="打开历史记录浮出控件", auto_id="HistoryButton", control_type="Button")
-   |    | 
+   |    |
   |    | GroupBox - '记忆控件'    (L-407, T948, R-85, B976)
   |    | ['记忆控件', '记忆控件GroupBox', 'GroupBox2']
   |    | child_window(title="记忆控件", auto_id="MemoryPanel", control_type="Group")
-   |    | 
+   |    |
   |    | GroupBox - '显示控件'    (L-407, T978, R-85, B1026)
   |    | ['显示控件', 'GroupBox3', '显示控件GroupBox']
   |    | child_window(title="显示控件", auto_id="DisplayControls", control_type="Group")
-   |    | 
+   |    |
   |    | GroupBox - '标准函数'    (L-407, T1028, R-166, B1076)
   |    | ['标准函数', '标准函数GroupBox', 'GroupBox4']
   |    | child_window(title="标准函数", auto_id="StandardFunctions", control_type="Group")
-   |    | 
+   |    |
   |    | GroupBox - '标准运算符'    (L-164, T1028, R-85, B1275)
   |    | ['标准运算符', '标准运算符GroupBox', 'GroupBox5']
   |    | child_window(title="标准运算符", auto_id="StandardOperators", control_type="Group")
-   |    | 
+   |    |
   |    | GroupBox - '数字键盘'    (L-407, T1078, R-166, B1275)
   |    | ['GroupBox6', '数字键盘', '数字键盘GroupBox']
   |    | child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   |    | 
+   |    |
   |    | Button - '正负'    (L-407, T1228, R-328, B1275)
   |    | ['Button32', '正负Button', '正负']
   |    | child_window(title="正负", auto_id="negateButton", control_type="Button")
-   | 
+   |
   | Static - '标准'    (L-363, T815, R-322, B842)
   | ['标准', '标准Static', 'Static4']
   | child_window(title="标准", auto_id="Header", control_type="Text")
-   | 
+   |
   | Button - '始终置顶'    (L-312, T814, R-280, B846)
   | ['始终置顶Button', '始终置顶', 'Button33']
   | child_window(title="始终置顶", auto_id="NormalAlwaysOnTopButton", control_type="Button")
@@ -187,47 +189,47 @@ numpad.dump_tree(depth=2)
 GroupBox - '数字键盘'    (L-334, T1350, R-93, B1547)
 ['GroupBox', '数字键盘', '数字键盘GroupBox']
 child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   | 
+   |
   | Button - '零'    (L-253, T1500, R-174, B1547)
   | ['零Button', 'Button', '零', 'Button0', 'Button1']
   | child_window(title="零", auto_id="num0Button", control_type="Button")
-   | 
+   |
   | Button - '一'    (L-334, T1450, R-255, B1498)
   | ['一Button', 'Button2', '一']
   | child_window(title="一", auto_id="num1Button", control_type="Button")
-   | 
+   |
   | Button - '二'    (L-253, T1450, R-174, B1498)
   | ['Button3', '二', '二Button']
   | child_window(title="二", auto_id="num2Button", control_type="Button")
-   | 
+   |
   | Button - '三'    (L-172, T1450, R-93, B1498)
   | ['Button4', '三', '三Button']
   | child_window(title="三", auto_id="num3Button", control_type="Button")
-   | 
+   |
   | Button - '四'    (L-334, T1400, R-255, B1448)
   | ['四', 'Button5', '四Button']
   | child_window(title="四", auto_id="num4Button", control_type="Button")
-   | 
+   |
   | Button - '五'    (L-253, T1400, R-174, B1448)
   | ['Button6', '五Button', '五']
   | child_window(title="五", auto_id="num5Button", control_type="Button")
-   | 
+   |
   | Button - '六'    (L-172, T1400, R-93, B1448)
   | ['六Button', 'Button7', '六']
   | child_window(title="六", auto_id="num6Button", control_type="Button")
-   | 
+   |
   | Button - '七'    (L-334, T1350, R-255, B1398)
   | ['Button8', '七Button', '七']
   | child_window(title="七", auto_id="num7Button", control_type="Button")
-   | 
+   |
   | Button - '八'    (L-253, T1350, R-174, B1398)
   | ['八', 'Button9', '八Button']
   | child_window(title="八", auto_id="num8Button", control_type="Button")
-   | 
+   |
   | Button - '九'    (L-172, T1350, R-93, B1398)
   | ['Button10', '九', '九Button']
   | child_window(title="九", auto_id="num9Button", control_type="Button")
-   | 
+   |
   | Button - '十进制分隔符'    (L-172, T1500, R-93, B1547)
   | ['十进制分隔符Button', 'Button11', '十进制分隔符']
   | child_window(title="十进制分隔符", auto_id="decimalSeparatorButton", control_type="Button")
@@ -262,13 +264,13 @@ r, g, b = pyautogui.pixel(point_x, point_y)

 ### pywinauto_recorder

-pywinauto_recorder是一个配合 pywinauto 使用的工具，用于录制用户的操作，并生成相应的 pywinauto 脚本。这对于一些暂时无法直接调用DLL的函数并且需要模拟用户操作的场景非常有用。同时，可以省去仅用pywinauto的一些查找UI步骤。
+pywinauto_recorder 是一个配合 pywinauto 使用的工具，用于录制用户的操作，并生成相应的 pywinauto 脚本。这对于一些暂时无法直接调用 DLL 的函数并且需要模拟用户操作的场景非常有用。同时，可以省去仅用 pywinauto 的一些查找 UI 步骤。

 #### 运行尝试

-请参照 上手尝试-环境创建-3 开启pywinauto_recorder
+请参照 上手尝试-环境创建-3 开启 pywinauto_recorder

-例如我们这里先启动一个windows自带的计算器软件
+例如我们这里先启动一个 windows 自带的计算器软件

 ![calculator_01](image/device_driver/calculator_01.png)

@@ -286,7 +288,7 @@ with UIPath(u"计算器||Window"):
        click(u"九||Button")
 ```

-执行该python脚本，可以观察到新开启的计算器被点击了数字9
+执行该 python 脚本，可以观察到新开启的计算器被点击了数字 9

 ![calculator_03](image/device_driver/calculator_03.png)

@@ -308,23 +310,38 @@ window.dump_tree(depth=[int类型数字], filename=None)
 GroupBox - '数字键盘'    (L-334, T1350, R-93, B1547)
 ['GroupBox', '数字键盘', '数字键盘GroupBox']
 child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   | 
+   |
   | Button - '零'    (L-253, T1500, R-174, B1547)
   | ['零Button', 'Button', '零', 'Button0', 'Button1']
   | child_window(title="零", auto_id="num0Button", control_type="Button")
 """
 ```

-这里以上面计算器的例子对dump_tree进行解读
+这里以上面计算器的例子对 dump_tree 进行解读

-2~4行为当前对象的窗口
+2~4 行为当前对象的窗口

-* 第2行分别是窗体的类型 `GroupBox`，窗体的题目 `数字键盘`，窗体的矩形区域坐标，对应的是屏幕上的位置（左、上、右、下）
-* 第3行是 `['GroupBox', '数字键盘', '数字键盘GroupBox']`，为控件的标识符列表，可以选择任意一个，使用 `child_window(best_match="标识符")`来获取该窗口
-* 第4行是获取该控件的方法，请注意该方法不能保证获取唯一，`title`如果是变化的，也需要删除 `title`参数
+- 第 2 行分别是窗体的类型 `GroupBox`，窗体的题目 `数字键盘`，窗体的矩形区域坐标，对应的是屏幕上的位置（左、上、右、下）
+- 第 3 行是 `['GroupBox', '数字键盘', '数字键盘GroupBox']`，为控件的标识符列表，可以选择任意一个，使用 `child_window(best_match="标识符")`来获取该窗口
+- 第 4 行是获取该控件的方法，请注意该方法不能保证获取唯一，`title`如果是变化的，也需要删除 `title`参数

-6~8行为当前对象窗口所包含的子窗口信息，信息类型对应2~4行
+6~8 行为当前对象窗口所包含的子窗口信息，信息类型对应 2~4 行

 ### 窗口获取注意事项

-1. 在 `child_window`的时候，并不会立刻报错，只有在执行窗口的信息获取时才会调用，查询窗口是否存在，因此要想确定 `child_window`是否正确，可以调用子窗口对象的属性 `element_info`，来保证窗口存在
+1. 在 `child_window`的时候，并不会立刻报错，只有在执行窗口的信息获取时才会调用，查询窗口是否存在，因此要想确定 `child_window`是否正确，可以调用子窗口对象的属性 `element_info`，来保证窗口存在
+
+---
+
+## 下一步
+
+完成设备驱动开发后，建议继续阅读：
+
+- {doc}`add_device` - 了解如何将驱动添加到 Uni-Lab 中
+- {doc}`add_action` - 学习如何添加新的动作指令
+- {doc}`add_yaml` - 编写和完善 YAML 注册表
+
+进阶主题：
+
+- {doc}`03_add_device_registry` - 详细的注册表配置
+- {doc}`04_add_device_testing` - 设备测试指南
--- a/docs/developer_guide/add_registry.md
+++ b/docs/developer_guide/add_registry.md
--- a/docs/developer_guide/examples/battery_plc_workstation.md
+++ b/docs/developer_guide/examples/battery_plc_workstation.md
@@ -1,6 +1,17 @@
-# 电池装配工站接入（PLC）
+# 实例：电池装配工站接入（PLC 控制）

-本指南将引导你完成电池装配工站（以 PLC 控制为例）的接入流程，包括新建工站文件、编写驱动与寄存器读写、生成注册表、上传及注意事项。
+> **文档类型**：实际应用案例  
+> **适用场景**：使用 PLC 控制的电池装配工站接入  
+> **前置知识**：{doc}`../add_device` | {doc}`../add_registry`
+
+本指南以电池装配工站为实际案例，引导你完成 PLC 控制设备的完整接入流程，包括新建工站文件、编写驱动与寄存器读写、生成注册表、上传及注意事项。
+
+## 案例概述
+
+**设备类型**：电池装配工站  
+**通信方式**：Modbus TCP (PLC)  
+**工站基类**：`WorkstationBase`  
+**主要功能**：电池组装、寄存器读写、数据采集

 ## 1. 新建工站文件

@@ -39,8 +50,6 @@ class CoinCellAssemblyWorkstation(WorkstationBase):
        self.client = tcp.register_node_list(self.nodes)
 ```

-
-
 ## 2. 编写驱动与寄存器读写

 ### 2.1 寄存器示例
@@ -84,49 +93,49 @@ def start_and_read_metrics(self):

 完成工站类与驱动后，需要生成（或更新）工站注册表供系统识别。

-
 ### 3.1 新增工站设备（或资源）首次生成注册表
-首先通过以下命令启动unilab。进入unilab系统状态检查页面
+
+首先通过以下命令启动 unilab。进入 unilab 系统状态检查页面

 ```bash
 python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK>
 ```

 点击注册表编辑，进入注册表编辑页面
-![Layers](image_add_batteryPLC/unilab_sys_status.png)
+
+![系统状态页面](image_battery_plc/unilab_sys_status.png)

 按照图示步骤填写自动生成注册表信息：
-![Layers](image_add_batteryPLC/unilab_registry_process.png)
+
+![注册表生成流程](image_battery_plc/unilab_registry_process.png)

 步骤说明：
+
 1. 选择新增的工站`coin_cell_assembly.py`文件
 2. 点击分析按钮，分析`coin_cell_assembly.py`文件
 3. 选择`coin_cell_assembly.py`文件中继承`WorkstationBase`类
-4. 填写新增的工站.py文件与`unilabos`目录的距离。例如，新增的工站文件`coin_cell_assembly.py`路径为`unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly.py`，则此处填写`unilabos.devices.workstation.coin_cell_assembly`。
+4. 填写新增的工站.py 文件与`unilabos`目录的距离。例如，新增的工站文件`coin_cell_assembly.py`路径为`unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly.py`，则此处填写`unilabos.devices.workstation.coin_cell_assembly`。
 5. 此处填写新定义工站的类的名字（名称可以自拟）
 6. 填写新的工站注册表备注信息
 7. 生成注册表

-以上操作步骤完成，则会生成的新的注册表ymal文件，如下图：
-![Layers](image_add_batteryPLC/unilab_new_yaml.png)
-
-
-
-
+以上操作步骤完成，则会生成的新的注册表 YAML 文件，如下图：

+![生成的YAML文件](image_battery_plc/unilab_new_yaml.png)

 ### 3.2 添加新生成注册表
-在`unilabos\registry\devices`目录下新建一个yaml文件，此处新建文件命名为`coincellassemblyworkstation_device.yaml`，将上面生成的新的注册表信息粘贴到`coincellassemblyworkstation_device.yaml`文件中。   
+
+在`unilabos\registry\devices`目录下新建一个 yaml 文件，此处新建文件命名为`coincellassemblyworkstation_device.yaml`，将上面生成的新的注册表信息粘贴到`coincellassemblyworkstation_device.yaml`文件中。

 在终端输入以下命令进行注册表补全操作。
+
 ```bash
 python unilabos\app\register.py --complete_registry
 ```

-
 ### 3.3 启动并上传注册表

-新增设备之后，启动unilab需要增加`--upload_registry`参数，来上传注册表信息。
+新增设备之后，启动 unilab 需要增加`--upload_registry`参数，来上传注册表信息。

 ```bash
 python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK> --upload_registry
@@ -134,14 +143,60 @@ python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK> -

 ## 4. 注意事项

- 在新生成的 YAML 中，确认 `module` 指向新工站类，本例中需检查`coincellassemblyworkstation_device.yaml`文件中是否指向了`coin_cell_assembly.py`文件中定义的`CoinCellAssemblyWorkstation`类文件：
+### 4.1 验证模块路径

-```
+在新生成的 YAML 中，确认 `module` 指向新工站类。本例中需检查 `coincellassemblyworkstation_device.yaml` 文件中是否正确指向了 `CoinCellAssemblyWorkstation` 类：
+
+```yaml
 module: unilabos.devices.workstation.coin_cell_assembly.coin_cell_assembly:CoinCellAssemblyWorkstation
 ```

- 首次新增设备（或资源）需要在网页端新增注册表信息，`--complete_registry`补全注册表，`--upload_registry`上传注册表信息。
+### 4.2 首次接入流程

- 如果不是新增设备（或资源），仅对工站驱动的.py文件进行了修改，则不需要在网页端新增注册表信息。只需要运行补全注册表信息之后，上传注册表即可。
+首次新增设备（或资源）需要完整流程：

+1. ✅ 在网页端生成注册表信息
+2. ✅ 使用 `--complete_registry` 补全注册表
+3. ✅ 使用 `--upload_registry` 上传注册表信息

+### 4.3 驱动更新流程
+
+如果不是新增设备，仅修改了工站驱动的 `.py` 文件：
+
+1. ✅ 运行 `--complete_registry` 补全注册表
+2. ✅ 运行 `--upload_registry` 上传注册表
+3. ❌ 不需要在网页端重新生成注册表
+
+### 4.4 PLC 通信注意事项
+
+- **握手机制**：若需参数下发，建议在 PLC 端设置标志寄存器并完成握手复位，避免粘连与竞争
+- **字节序**：FLOAT32 等多字节数据类型需要正确指定字节序（如 `WorderOrder.LITTLE`）
+- **寄存器映射**：确保 CSV 文件中的寄存器地址与 PLC 实际配置一致
+- **连接稳定性**：在初始化时检查 PLC 连接状态，建议添加重连机制
+
+## 5. 扩展阅读
+
+### 相关文档
+
+- {doc}`../add_device` - 设备驱动编写通用指南
+- {doc}`../add_registry` - 注册表配置完整指南
+- {doc}`../workstation_architecture` - 工站架构详解
+
+### 技术要点
+
+- **Modbus TCP 通信**：PLC 通信协议和寄存器读写
+- **WorkstationBase**：工站基类的继承和使用
+- **寄存器映射**：CSV 格式的寄存器配置
+- **注册表生成**：自动化工具使用
+
+## 6. 总结
+
+通过本案例，你应该掌握：
+
+1. ✅ 如何创建 PLC 控制的工站驱动
+2. ✅ Modbus TCP 通信和寄存器读写
+3. ✅ 使用可视化编辑器生成注册表
+4. ✅ 注册表的补全和上传流程
+5. ✅ 新增设备与更新驱动的区别
+
+这个案例展示了完整的 PLC 设备接入流程，可以作为其他类似设备接入的参考模板。
--- a/docs/developer_guide/examples/image_battery_plc/unilab_new_yaml.png
+++ b/docs/developer_guide/examples/image_battery_plc/unilab_new_yaml.png
--- a/docs/developer_guide/examples/image_battery_plc/unilab_registry_process.png
+++ b/docs/developer_guide/examples/image_battery_plc/unilab_registry_process.png
--- a/docs/developer_guide/examples/image_battery_plc/unilab_sys_status.png
+++ b/docs/developer_guide/examples/image_battery_plc/unilab_sys_status.png
--- a/docs/developer_guide/examples/materials_construction_guide.md
+++ b/docs/developer_guide/examples/materials_construction_guide.md
@@ -1,4 +1,8 @@
-# 物料构建指南
+# 实例：物料构建指南
+
+> **文档类型**：物料系统实战指南  
+> **适用场景**：工作站物料系统构建、Deck/Warehouse/Carrier/Bottle 配置  
+> **前置知识**：PyLabRobot 基础 | 资源管理概念

 ## 概述

--- a/docs/developer_guide/examples/materials_tutorial.md
+++ b/docs/developer_guide/examples/materials_tutorial.md
@@ -1,6 +1,10 @@
-# 物料教程（Resource）
+# 实例：物料教程（Resource）

-本教程面向 Uni-Lab-OS 的开发者，讲解“物料”的核心概念、3种物料格式（UniLab、PyLabRobot、奔耀Bioyond）及其相互转换方法，并说明4种 children 结构表现形式及使用场景。
+> **文档类型**：物料系统完整教程  
+> **适用场景**：物料格式转换、多系统物料对接、资源结构理解  
+> **前置知识**：Python 基础 | JSON 数据结构
+
+本教程面向 Uni-Lab-OS 的开发者，讲解"物料"的核心概念、3种物料格式（UniLab、PyLabRobot、奔耀Bioyond）及其相互转换方法，并说明4种 children 结构表现形式及使用场景。

 ---

--- a/docs/developer_guide/examples/workstation_architecture.md
+++ b/docs/developer_guide/examples/workstation_architecture.md
@@ -1,4 +1,8 @@
-# 工作站模板架构设计与对接指南
+# 实例：工作站模板架构设计与对接指南
+
+> **文档类型**：架构设计指南与实战案例  
+> **适用场景**：大型工作站接入、子设备管理、物料系统集成  
+> **前置知识**：{doc}`../add_device` | {doc}`../add_registry`

 ## 0. 问题简介

@@ -6,19 +10,19 @@

 ### 0.1 自研常量有机工站：最重要的是子设备管理和通信转发

-![workstation_organic_yed](image/workstation_architecture/workstation_organic_yed.png)
+![workstation_organic_yed](../image/workstation_architecture/workstation_organic_yed.png)

-![workstation_organic](image/workstation_architecture/workstation_organic.png)
+![workstation_organic](../image/workstation_architecture/workstation_organic.png)

 这类工站由开发者自研，组合所有子设备和实验耗材、希望让他们在工作站这一级协调配合；

-1. 工作站包含大量已经注册的子设备，可能各自通信组态很不相同；部分设备可能会拥有同一个通信设备作为出口，如2个泵共用1个串口、所有设备共同接入PLC等。
-2. 任务系统是统一实现的 protocols，protocols 中会将高层指令处理成各子设备配合的工作流 json并管理执行、同时更改物料信息
+1. 工作站包含大量已经注册的子设备，可能各自通信组态很不相同；部分设备可能会拥有同一个通信设备作为出口，如 2 个泵共用 1 个串口、所有设备共同接入 PLC 等。
+2. 任务系统是统一实现的 protocols，protocols 中会将高层指令处理成各子设备配合的工作流 json 并管理执行、同时更改物料信息
 3. 物料系统较为简单直接，如常量有机化学仅为工作站内固定的瓶子，初始化时就已固定；随后在任务执行过程中，记录试剂量更改信息

 ### 0.2 移液工作站：物料系统和工作流模板管理

-![workstation_liquid_handler](image/workstation_architecture/workstation_liquid_handler.png)
+![workstation_liquid_handler](../image/workstation_architecture/workstation_liquid_handler.png)

 1. 绝大多数情况没有子设备，有时候选配恒温震荡等模块时，接口也由工作站提供
 2. 所有任务系统均由工作站本身实现并下发指令，有统一的抽象函数可实现（pick_up_tips, aspirate, dispense, transfer 等）。有时需要将这些指令组合、转化为工作站的脚本语言，再统一下发。因此会形成大量固定的 protocols。
@@ -26,12 +30,12 @@

 ### 0.3 厂家开发的定制大型工站

-![workstation_by_supplier](image/workstation_architecture/workstation_by_supplier.png)
+![workstation_by_supplier](../image/workstation_architecture/workstation_by_supplier.png)

 由厂家开发，具备完善的物料系统、任务系统甚至调度系统；由 PLC 或 OpenAPI TCP 协议统一通信

 1. 在监控状态时，希望展现子设备的状态；但子设备仅为逻辑概念，通信由工作站上位机接口提供；部分情况下，子设备状态是被记录在文件中的，需要读取
-2. 工作站有自己的工作流系统甚至调度系统；可以通过脚本/PLC连续读写来配置工作站可用的工作流；
+2. 工作站有自己的工作流系统甚至调度系统；可以通过脚本/PLC 连续读写来配置工作站可用的工作流；
 3. 部分拥有完善的物料入库、出库、过程记录，需要与 Uni-Lab-OS 物料系统对接

 ## 1. 整体架构图
@@ -45,7 +49,7 @@ graph TB
        RPN[ROS2WorkstationNode<br/>Protocol执行引擎]
        WB -.post_init关联.-> RPN
    end
-    
+
    subgraph "物料管理系统"
        DECK[Deck<br/>PLR本地物料系统]
        RS[ResourceSynchronizer<br/>外部物料同步器]
@@ -53,7 +57,7 @@ graph TB
        WB --> RS
        RS --> DECK
    end
-    
+
    subgraph "通信与子设备管理"
        HW[hardware_interface<br/>硬件通信接口]
        SUBDEV[子设备集合<br/>pumps/grippers/sensors]
@@ -61,7 +65,7 @@ graph TB
        RPN --> SUBDEV
        HW -.代理模式.-> RPN
    end
-    
+
    subgraph "工作流任务系统"
        PROTO[Protocol定义<br/>LiquidHandling/PlateHandling]
        WORKFLOW[Workflow执行器<br/>步骤管理与编排]
@@ -81,32 +85,32 @@ graph LR
        HW2[通信接口<br/>hardware_interface]
        HTTP[HTTP服务<br/>WorkstationHTTPService]
    end
-    
+
    subgraph "外部物料系统"
        BIOYOND[Bioyond物料管理]
        LIMS[LIMS系统]
        WAREHOUSE[第三方仓储]
    end
-    
+
    subgraph "外部硬件系统"
        PLC[PLC设备]
        SERIAL[串口设备]
        ROBOT[机械臂/机器人]
    end
-    
+
    subgraph "云端系统"
        CLOUD[UniLab云端<br/>资源管理]
        MONITOR[监控与调度]
    end
-    
+
    BIOYOND <-->|RPC双向同步| DECK2
    LIMS -->|HTTP报送| HTTP
    WAREHOUSE <-->|API对接| DECK2
-    
+
    PLC <-->|Modbus TCP| HW2
    SERIAL <-->|串口通信| HW2
    ROBOT <-->|SDK/API| HW2
-    
+
    WS -->|ROS消息| CLOUD
    CLOUD -->|任务下发| WS
    MONITOR -->|状态查询| WS
@@ -119,40 +123,40 @@ graph TB
    subgraph "工作站基类"
        BASE[WorkstationBase<br/>抽象基类]
    end
-    
+
    subgraph "Bioyond集成工作站"
        BW[BioyondWorkstation]
        BW_DECK[Deck + Warehouses]
        BW_SYNC[BioyondResourceSynchronizer]
        BW_HW[BioyondV1RPC]
        BW_HTTP[HTTP报送服务]
-        
+
        BW --> BW_DECK
        BW --> BW_SYNC
        BW --> BW_HW
        BW --> BW_HTTP
    end
-    
+
    subgraph "纯协议节点"
        PN[ProtocolNode]
        PN_SUB[子设备集合]
        PN_PROTO[Protocol工作流]
-        
+
        PN --> PN_SUB
        PN --> PN_PROTO
    end
-    
+
    subgraph "PLC控制工作站"
        PW[PLCWorkstation]
        PW_DECK[Deck物料系统]
        PW_PLC[Modbus PLC客户端]
        PW_WF[工作流定义]
-        
+
        PW --> PW_DECK
        PW --> PW_PLC
        PW --> PW_WF
    end
-    
+
    BASE -.继承.-> BW
    BASE -.继承.-> PN
    BASE -.继承.-> PW
@@ -171,25 +175,25 @@ classDiagram
        +hardware_interface: Union[Any, str]
        +current_workflow_status: WorkflowStatus
        +supported_workflows: Dict[str, WorkflowInfo]
-    
+
        +post_init(ros_node)*
        +set_hardware_interface(interface)
        +call_device_method(method, *args, **kwargs)
        +get_device_status()
        +is_device_available()
-    
+
        +get_deck()
        +get_all_resources()
        +find_resource_by_name(name)
        +find_resources_by_type(type)
        +sync_with_external_system()
-    
+
        +execute_workflow(name, params)
        +stop_workflow(emergency)
        +workflow_status
        +is_busy
    }
-  
+
    class ROS2WorkstationNode {
        +device_id: str
        +children: Dict[str, Any]
@@ -198,7 +202,7 @@ classDiagram
        +_action_clients: Dict
        +_action_servers: Dict
        +resource_tracker: DeviceNodeResourceTracker
-    
+
        +initialize_device(device_id, config)
        +create_ros_action_server(action_name, mapping)
        +execute_single_action(device_id, action, kwargs)
@@ -206,14 +210,14 @@ classDiagram
        +transfer_resource_to_another(resources, target, sites)
        +_setup_hardware_proxy(device, comm_device, read, write)
    }
-  
+
    %% 物料管理相关类
    class Deck {
        +name: str
        +children: List
        +assign_child_resource()
    }
-  
+
    class ResourceSynchronizer {
        <<abstract>>
        +workstation: WorkstationBase
@@ -221,23 +225,23 @@ classDiagram
        +sync_to_external(plr_resource)*
        +handle_external_change(change_info)*
    }
-  
+
    class BioyondResourceSynchronizer {
        +bioyond_api_client: BioyondV1RPC
        +sync_interval: int
        +last_sync_time: float
-    
+
        +initialize()
        +sync_from_external()
        +sync_to_external(resource)
        +handle_external_change(change_info)
    }
-  
+
    %% 硬件接口相关类
    class HardwareInterface {
        <<interface>>
    }
-  
+
    class BioyondV1RPC {
        +base_url: str
        +api_key: str
@@ -245,7 +249,7 @@ classDiagram
        +add_material()
        +material_inbound()
    }
-  
+
    %% 服务类
    class WorkstationHTTPService {
        +workstation: WorkstationBase
@@ -253,7 +257,7 @@ classDiagram
        +port: int
        +server: HTTPServer
        +running: bool
-    
+
        +start()
        +stop()
        +_handle_step_finish_report()
@@ -262,13 +266,13 @@ classDiagram
        +_handle_material_change_report()
        +_handle_error_handling_report()
    }
-  
+
    %% 具体实现类
    class BioyondWorkstation {
        +bioyond_config: Dict
        +workflow_mappings: Dict
        +workflow_sequence: List
-    
+
        +post_init(ros_node)
        +transfer_resource_to_another()
        +resource_tree_add(resources)
@@ -276,25 +280,25 @@ classDiagram
        +get_all_workflows()
        +get_bioyond_status()
    }
-  
+
    class ProtocolNode {
        +post_init(ros_node)
    }
-  
+
    %% 核心关系
    WorkstationBase o-- ROS2WorkstationNode : post_init关联
    WorkstationBase o-- WorkstationHTTPService : 可选服务
-  
+
    %% 物料管理侧
    WorkstationBase *-- Deck : deck
    WorkstationBase *-- ResourceSynchronizer : 可选组合
    ResourceSynchronizer <|-- BioyondResourceSynchronizer
-  
+
    %% 硬件接口侧
    WorkstationBase o-- HardwareInterface : hardware_interface
    HardwareInterface <|.. BioyondV1RPC : 实现
    BioyondResourceSynchronizer --> BioyondV1RPC : 使用
-  
+
    %% 继承关系
    BioyondWorkstation --|> WorkstationBase
    ProtocolNode --|> WorkstationBase
@@ -312,49 +316,49 @@ sequenceDiagram
    participant HW as HardwareInterface
    participant ROS as ROS2WorkstationNode
    participant HTTP as HTTPService
-  
+
    APP->>WS: 创建工作站实例(__init__)
    WS->>DECK: 初始化PLR Deck
    DECK->>DECK: 创建Warehouse等子资源
    DECK-->>WS: Deck创建完成
-  
+
    WS->>HW: 创建硬件接口(如BioyondV1RPC)
    HW->>HW: 建立连接(PLC/RPC/串口等)
    HW-->>WS: 硬件接口就绪
-  
+
    WS->>SYNC: 创建ResourceSynchronizer(可选)
    SYNC->>HW: 使用hardware_interface
    SYNC->>SYNC: 初始化同步配置
    SYNC-->>WS: 同步器创建完成
-  
+
    WS->>SYNC: sync_from_external()
    SYNC->>HW: 查询外部物料系统
    HW-->>SYNC: 返回物料数据
    SYNC->>DECK: 转换并添加到Deck
    SYNC-->>WS: 同步完成
-  
+
    Note over WS: __init__完成,等待ROS节点
-  
+
    APP->>ROS: 初始化ROS2WorkstationNode
    ROS->>ROS: 初始化子设备(children)
    ROS->>ROS: 创建Action客户端
    ROS->>ROS: 设置硬件接口代理
    ROS-->>APP: ROS节点就绪
-  
+
    APP->>WS: post_init(ros_node)
    WS->>WS: self._ros_node = ros_node
    WS->>ROS: update_resource([deck])
    ROS->>ROS: 上传物料到云端
    ROS-->>WS: 上传完成
-  
+
    WS->>HTTP: 创建WorkstationHTTPService(可选)
    HTTP->>HTTP: 启动HTTP服务器线程
    HTTP-->>WS: HTTP服务启动
-  
+
    WS-->>APP: 工作站完全就绪
 ```

-## 4. 工作流执行时序图（Protocol模式）
+## 4. 工作流执行时序图（Protocol 模式）

 ```{mermaid}
 sequenceDiagram
@@ -365,15 +369,15 @@ sequenceDiagram
    participant DECK as PLR Deck
    participant CLOUD as 云端资源管理
    participant DEV as 子设备
-  
+
    CLIENT->>ROS: 发送Protocol Action请求
    ROS->>ROS: execute_protocol回调
    ROS->>ROS: 从Goal提取参数
    ROS->>ROS: 调用protocol_steps_generator
    ROS->>ROS: 生成action步骤列表
-  
+
    ROS->>WS: 更新workflow_status = RUNNING
-  
+
    loop 执行每个步骤
        alt 调用子设备
            ROS->>ROS: execute_single_action(device_id, action, params)
@@ -394,19 +398,19 @@ sequenceDiagram
            end
            WS-->>ROS: 返回结果
        end
-    
+
        ROS->>DECK: 更新本地物料状态
        DECK->>DECK: 修改PLR资源属性
    end
-  
+
    ROS->>CLOUD: 同步物料到云端(可选)
    CLOUD-->>ROS: 同步完成
-  
+
    ROS->>WS: 更新workflow_status = COMPLETED
    ROS-->>CLIENT: 返回Protocol Result
 ```

-## 5. HTTP报送处理时序图
+## 5. HTTP 报送处理时序图

 ```{mermaid}
 sequenceDiagram
@@ -416,25 +420,25 @@ sequenceDiagram
    participant DECK as PLR Deck
    participant SYNC as ResourceSynchronizer
    participant CLOUD as 云端
-  
+
    EXT->>HTTP: POST /report/step_finish
    HTTP->>HTTP: 解析请求数据
    HTTP->>HTTP: 验证LIMS协议字段
    HTTP->>WS: process_step_finish_report(request)
-  
+
    WS->>WS: 增加接收计数(_reports_received_count++)
    WS->>WS: 记录步骤完成事件
    WS->>DECK: 更新相关物料状态(可选)
    DECK->>DECK: 修改PLR资源状态
-  
+
    WS->>WS: 保存报送记录到内存
-  
+
    WS-->>HTTP: 返回处理结果
    HTTP->>HTTP: 构造HTTP响应
    HTTP-->>EXT: 200 OK + acknowledgment_id
-  
+
    Note over EXT,CLOUD: 类似处理sample_finish, order_finish等报送
-  
+
    alt 物料变更报送
        EXT->>HTTP: POST /report/material_change
        HTTP->>WS: process_material_change_report(data)
@@ -459,7 +463,7 @@ sequenceDiagram
    participant HW as HardwareInterface
    participant HTTP as HTTPService
    participant LOG as 日志系统
-  
+
    alt 设备错误(ROS Action失败)
        DEV->>ROS: Action返回失败结果
        ROS->>ROS: 记录错误信息
@@ -471,7 +475,7 @@ sequenceDiagram
        WS->>WS: 记录错误历史
        WS->>LOG: 记录错误日志
    end
-  
+
    alt 关键错误需要停止
        WS->>ROS: stop_workflow(emergency=True)
        ROS->>ROS: 取消所有进行中的Action
@@ -483,44 +487,44 @@ sequenceDiagram
        WS->>ROS: 触发重试逻辑(可选)
        ROS->>DEV: 重新发送Action
    end
-  
+
    WS-->>HTTP: 返回错误处理结果
    HTTP-->>DEV: 200 OK + 处理状态
 ```

 ## 7. 典型工作站实现示例

-### 7.1 Bioyond集成工作站实现
+### 7.1 Bioyond 集成工作站实现

 ```python
 class BioyondWorkstation(WorkstationBase):
    def __init__(self, bioyond_config: Dict, deck: Deck, *args, **kwargs):
        # 初始化deck
        super().__init__(deck=deck, *args, **kwargs)
-      
+
        # 设置硬件接口为Bioyond RPC客户端
        self.hardware_interface = BioyondV1RPC(bioyond_config)
-      
+
        # 创建资源同步器
        self.resource_synchronizer = BioyondResourceSynchronizer(self)
-      
+
        # 从Bioyond同步物料到本地deck
        self.resource_synchronizer.sync_from_external()
-      
+
        # 配置工作流
        self.workflow_mappings = bioyond_config.get("workflow_mappings", {})
-  
+
    def post_init(self, ros_node: ROS2WorkstationNode):
        """ROS节点就绪后的初始化"""
        self._ros_node = ros_node
-      
+
        # 上传deck(包括所有物料)到云端
        ROS2DeviceNode.run_async_func(
-            self._ros_node.update_resource, 
-            True, 
+            self._ros_node.update_resource,
+            True,
            resources=[self.deck]
        )
-  
+
    def resource_tree_add(self, resources: List[ResourcePLR]):
        """添加物料并同步到Bioyond"""
        for resource in resources:
@@ -533,24 +537,24 @@ class BioyondWorkstation(WorkstationBase):
 ```python
 class ProtocolNode(WorkstationBase):
    """纯协议节点,不需要物料管理和外部通信"""
-  
+
    def __init__(self, deck: Optional[Deck] = None, *args, **kwargs):
        super().__init__(deck=deck, *args, **kwargs)
        # 不设置hardware_interface和resource_synchronizer
        # 所有功能通过子设备协同完成
-  
+
    def post_init(self, ros_node: ROS2WorkstationNode):
        self._ros_node = ros_node
        # 不需要上传物料或其他初始化
 ```

-### 7.3 PLC直接控制工作站
+### 7.3 PLC 直接控制工作站

 ```python
 class PLCWorkstation(WorkstationBase):
    def __init__(self, plc_config: Dict, deck: Deck, *args, **kwargs):
        super().__init__(deck=deck, *args, **kwargs)
-      
+
        # 设置硬件接口为Modbus客户端
        from pymodbus.client import ModbusTcpClient
        self.hardware_interface = ModbusTcpClient(
@@ -558,7 +562,7 @@ class PLCWorkstation(WorkstationBase):
            port=plc_config["port"]
        )
        self.hardware_interface.connect()
-      
+
        # 定义支持的工作流
        self.supported_workflows = {
            "battery_assembly": WorkflowInfo(
@@ -570,49 +574,49 @@ class PLCWorkstation(WorkstationBase):
                parameters_schema={"quantity": int, "model": str}
            )
        }
-  
+
    def execute_workflow(self, workflow_name: str, parameters: Dict):
        """通过PLC执行工作流"""
        workflow_id = self._get_workflow_id(workflow_name)
-      
+
        # 写入PLC寄存器启动工作流
        self.hardware_interface.write_register(100, workflow_id)
        self.hardware_interface.write_register(101, parameters["quantity"])
-      
+
        self.current_workflow_status = WorkflowStatus.RUNNING
        return True
 ```

 ## 8. 核心接口说明

-### 8.1 WorkstationBase核心属性
+### 8.1 WorkstationBase 核心属性

-| 属性                        | 类型                    | 说明                          |
-| --------------------------- | ----------------------- | ----------------------------- |
-| `_ros_node`               | ROS2WorkstationNode     | ROS节点引用，由post_init设置  |
-| `deck`                    | Deck                    | PyLabRobot Deck，本地物料系统 |
-| `plr_resources`           | Dict[str, PLRResource]  | 物料资源映射                  |
-| `resource_synchronizer`   | ResourceSynchronizer    | 外部物料同步器(可选)          |
-| `hardware_interface`      | Union[Any, str]         | 硬件接口或代理字符串          |
-| `current_workflow_status` | WorkflowStatus          | 当前工作流状态                |
-| `supported_workflows`     | Dict[str, WorkflowInfo] | 支持的工作流定义              |
+| 属性                      | 类型                    | 说明                            |
+| ------------------------- | ----------------------- | ------------------------------- |
+| `_ros_node`               | ROS2WorkstationNode     | ROS 节点引用，由 post_init 设置 |
+| `deck`                    | Deck                    | PyLabRobot Deck，本地物料系统   |
+| `plr_resources`           | Dict[str, PLRResource]  | 物料资源映射                    |
+| `resource_synchronizer`   | ResourceSynchronizer    | 外部物料同步器(可选)            |
+| `hardware_interface`      | Union[Any, str]         | 硬件接口或代理字符串            |
+| `current_workflow_status` | WorkflowStatus          | 当前工作流状态                  |
+| `supported_workflows`     | Dict[str, WorkflowInfo] | 支持的工作流定义                |

 ### 8.2 必须实现的方法

- `post_init(ros_node)`: ROS节点就绪后的初始化，必须实现
+- `post_init(ros_node)`: ROS 节点就绪后的初始化，必须实现

 ### 8.3 硬件接口相关方法

 - `set_hardware_interface(interface)`: 设置硬件接口
 - `call_device_method(method, *args, **kwargs)`: 统一设备方法调用
-  - 支持直接模式: 直接调用hardware_interface的方法
-  - 支持代理模式: hardware_interface="proxy:device_id"通过ROS转发
+  - 支持直接模式: 直接调用 hardware_interface 的方法
+  - 支持代理模式: hardware_interface="proxy:device_id"通过 ROS 转发
 - `get_device_status()`: 获取设备状态
 - `is_device_available()`: 检查设备可用性

 ### 8.4 物料管理方法

- `get_deck()`: 获取PLR Deck
+- `get_deck()`: 获取 PLR Deck
 - `get_all_resources()`: 获取所有物料
 - `find_resource_by_name(name)`: 按名称查找物料
 - `find_resources_by_type(type)`: 按类型查找物料
@@ -626,7 +630,7 @@ class PLCWorkstation(WorkstationBase):
 - `is_busy`: 检查是否忙碌(属性)
 - `workflow_runtime`: 获取运行时间(属性)

-### 8.6 可选的HTTP报送处理方法
+### 8.6 可选的 HTTP 报送处理方法

 - `process_step_finish_report()`: 步骤完成处理
 - `process_sample_finish_report()`: 样本完成处理
@@ -634,10 +638,10 @@ class PLCWorkstation(WorkstationBase):
 - `process_material_change_report()`: 物料变更处理
 - `handle_external_error()`: 错误处理

-### 8.7 ROS2WorkstationNode核心方法
+### 8.7 ROS2WorkstationNode 核心方法

 - `initialize_device(device_id, config)`: 初始化子设备
- `create_ros_action_server(action_name, mapping)`: 创建Action服务器
+- `create_ros_action_server(action_name, mapping)`: 创建 Action 服务器
 - `execute_single_action(device_id, action, kwargs)`: 执行单个动作
 - `update_resource(resources)`: 同步物料到云端
 - `transfer_resource_to_another(...)`: 跨设备物料转移
@@ -694,7 +698,7 @@ workstation = BioyondWorkstation(
                "config": {...}
            },
            "gripper_1": {
-                "type": "device", 
+                "type": "device",
                "driver": "RobotiqGripperDriver",
                "communication": "io_modbus_1",
                "config": {...}
@@ -716,7 +720,7 @@ workstation = BioyondWorkstation(
 }
 ```

-### 9.3 HTTP服务配置
+### 9.3 HTTP 服务配置

 ```python
 from unilabos.devices.workstation.workstation_http_service import WorkstationHTTPService
@@ -737,31 +741,31 @@ http_service.start()
 ### 10.1 清晰的职责分离

 - **WorkstationBase**: 负责物料管理(deck)、硬件接口(hardware_interface)、工作流状态管理
- **ROS2WorkstationNode**: 负责子设备管理、Protocol执行、云端物料同步
- **ResourceSynchronizer**: 可选的外部物料系统同步(如Bioyond)
- **WorkstationHTTPService**: 可选的HTTP报送接收服务
+- **ROS2WorkstationNode**: 负责子设备管理、Protocol 执行、云端物料同步
+- **ResourceSynchronizer**: 可选的外部物料系统同步(如 Bioyond)
+- **WorkstationHTTPService**: 可选的 HTTP 报送接收服务

 ### 10.2 灵活的硬件接口模式

-1. **直接模式**: hardware_interface是具体对象(如BioyondV1RPC、ModbusClient)
-2. **代理模式**: hardware_interface="proxy:device_id"，通过ROS节点转发到子设备
+1. **直接模式**: hardware_interface 是具体对象(如 BioyondV1RPC、ModbusClient)
+2. **代理模式**: hardware_interface="proxy:device_id"，通过 ROS 节点转发到子设备
 3. **混合模式**: 工作站有自己的接口，同时管理多个子设备

 ### 10.3 统一的物料系统

- 基于PyLabRobot Deck的标准化物料表示
- 通过ResourceSynchronizer实现与外部系统(如Bioyond、LIMS)的双向同步
- 通过ROS2WorkstationNode实现与云端的物料状态同步
+- 基于 PyLabRobot Deck 的标准化物料表示
+- 通过 ResourceSynchronizer 实现与外部系统(如 Bioyond、LIMS)的双向同步
+- 通过 ROS2WorkstationNode 实现与云端的物料状态同步

-### 10.4 Protocol驱动的工作流
+### 10.4 Protocol 驱动的工作流

- ROS2WorkstationNode负责Protocol的执行和步骤管理
- 支持子设备协同(通过Action Client调用)
- 支持工作站直接控制(通过hardware_interface)
+- ROS2WorkstationNode 负责 Protocol 的执行和步骤管理
+- 支持子设备协同(通过 Action Client 调用)
+- 支持工作站直接控制(通过 hardware_interface)

-### 10.5 可选的HTTP报送服务
+### 10.5 可选的 HTTP 报送服务

- 基于LIMS协议规范的统一报送接口
+- 基于 LIMS 协议规范的统一报送接口
 - 支持步骤完成、样本完成、任务完成、物料变更等多种报送类型
 - 与工作站解耦，可独立启停

--- a/docs/developer_guide/http_api.md
+++ b/docs/developer_guide/http_api.md
@@ -0,0 +1,334 @@
+# HTTP API 指南
+
+本文档介绍如何通过 HTTP API 与 Uni-Lab-OS 进行交互，包括查询设备、提交任务和获取结果。
+
+## 概述
+
+Uni-Lab-OS 提供 RESTful HTTP API，允许外部系统通过标准 HTTP 请求控制实验室设备。API 基于 FastAPI 构建，默认运行在 `http://localhost:8002`。
+
+### 基础信息
+
+- **Base URL**: `http://localhost:8002/api/v1`
+- **Content-Type**: `application/json`
+- **响应格式**: JSON
+
+### 通用响应结构
+
+```json
+{
+    "code": 0,
+    "data": { ... },
+    "message": "success"
+}
+```
+
+| 字段      | 类型   | 说明               |
+| --------- | ------ | ------------------ |
+| `code`    | int    | 状态码，0 表示成功 |
+| `data`    | object | 响应数据           |
+| `message` | string | 响应消息           |
+
+## 快速开始
+
+以下是一个完整的工作流示例：查询设备 → 获取动作 → 提交任务 → 获取结果。
+
+### 步骤 1: 获取在线设备
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/online-devices"
+```
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "online_devices": {
+      "host_node": {
+        "device_key": "/host_node",
+        "namespace": "",
+        "machine_name": "本地",
+        "uuid": "xxx-xxx-xxx",
+        "node_name": "host_node"
+      }
+    },
+    "total_count": 1,
+    "timestamp": 1732612345.123
+  },
+  "message": "success"
+}
+```
+
+### 步骤 2: 获取设备可用动作
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/devices/host_node/actions"
+```
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "device_id": "host_node",
+    "actions": {
+      "test_latency": {
+        "type_name": "unilabos_msgs.action._empty_in.EmptyIn",
+        "type_name_convert": "unilabos_msgs/action/_empty_in/EmptyIn",
+        "action_path": "/devices/host_node/test_latency",
+        "goal_info": "{}",
+        "is_busy": false,
+        "current_job_id": null
+      },
+      "create_resource": {
+        "type_name": "unilabos_msgs.action._resource_create_from_outer_easy.ResourceCreateFromOuterEasy",
+        "action_path": "/devices/host_node/create_resource",
+        "goal_info": "{res_id: '', device_id: '', class_name: '', ...}",
+        "is_busy": false,
+        "current_job_id": null
+      }
+    },
+    "action_count": 5
+  },
+  "message": "success"
+}
+```
+
+**动作状态字段说明**:
+
+| 字段             | 说明                          |
+| ---------------- | ----------------------------- |
+| `type_name`      | 动作类型的完整名称            |
+| `action_path`    | ROS2 动作路径                 |
+| `goal_info`      | 动作参数模板                  |
+| `is_busy`        | 动作是否正在执行              |
+| `current_job_id` | 当前执行的任务 ID（如果繁忙） |
+
+### 步骤 3: 提交任务
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{"device_id":"host_node","action":"test_latency","action_args":{}}'
+```
+
+**请求体**:
+
+```json
+{
+  "device_id": "host_node",
+  "action": "test_latency",
+  "action_args": {}
+}
+```
+
+**请求参数说明**:
+
+| 字段          | 类型   | 必填 | 说明                               |
+| ------------- | ------ | ---- | ---------------------------------- |
+| `device_id`   | string | ✓    | 目标设备 ID                        |
+| `action`      | string | ✓    | 动作名称                           |
+| `action_args` | object | ✓    | 动作参数（根据动作类型不同而变化） |
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 1,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+**任务状态码**:
+
+| 状态码 | 含义      | 说明                           |
+| ------ | --------- | ------------------------------ |
+| 0      | UNKNOWN   | 未知状态                       |
+| 1      | ACCEPTED  | 任务已接受，等待执行           |
+| 2      | EXECUTING | 任务执行中                     |
+| 3      | CANCELING | 任务取消中                     |
+| 4      | SUCCEEDED | 任务成功完成                   |
+| 5      | CANCELED  | 任务已取消                     |
+| 6      | ABORTED   | 任务中止（设备繁忙或执行失败） |
+
+### 步骤 4: 查询任务状态和结果
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/job/b6acb586-733a-42ab-9f73-55c9a52aa8bd/status"
+```
+
+**响应示例（执行中）**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 2,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+**响应示例（执行完成）**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 4,
+    "result": {
+      "error": "",
+      "suc": true,
+      "return_value": {
+        "avg_rtt_ms": 103.99,
+        "avg_time_diff_ms": 7181.55,
+        "max_time_error_ms": 7210.57,
+        "task_delay_ms": -1,
+        "raw_delay_ms": 33.19,
+        "test_count": 5,
+        "status": "success"
+      }
+    }
+  },
+  "message": "success"
+}
+```
+
+> **注意**: 任务结果在首次查询后会被自动删除，请确保保存返回的结果数据。
+
+## API 端点列表
+
+### 设备相关
+
+| 端点                                                       | 方法 | 说明                   |
+| ---------------------------------------------------------- | ---- | ---------------------- |
+| `/api/v1/online-devices`                                   | GET  | 获取在线设备列表       |
+| `/api/v1/devices`                                          | GET  | 获取设备配置           |
+| `/api/v1/devices/{device_id}/actions`                      | GET  | 获取指定设备的可用动作 |
+| `/api/v1/devices/{device_id}/actions/{action_name}/schema` | GET  | 获取动作参数 Schema    |
+| `/api/v1/actions`                                          | GET  | 获取所有设备的可用动作 |
+
+### 任务相关
+
+| 端点                          | 方法 | 说明               |
+| ----------------------------- | ---- | ------------------ |
+| `/api/v1/job/add`             | POST | 提交新任务         |
+| `/api/v1/job/{job_id}/status` | GET  | 查询任务状态和结果 |
+
+### 资源相关
+
+| 端点                | 方法 | 说明         |
+| ------------------- | ---- | ------------ |
+| `/api/v1/resources` | GET  | 获取资源列表 |
+
+## 常见动作示例
+
+### test_latency - 延迟测试
+
+测试系统延迟，无需参数。
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{"device_id":"host_node","action":"test_latency","action_args":{}}'
+```
+
+### create_resource - 创建资源
+
+在设备上创建新资源。
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "device_id": "host_node",
+    "action": "create_resource",
+    "action_args": {
+        "res_id": "my_plate",
+        "device_id": "host_node",
+        "class_name": "Plate",
+        "parent": "deck",
+        "bind_locations": {"x": 0, "y": 0, "z": 0}
+    }
+}'
+```
+
+## 错误处理
+
+### 设备繁忙
+
+当设备正在执行其他任务时，提交新任务会返回 `status: 6`（ABORTED）：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "xxx",
+    "status": 6,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+此时应等待当前任务完成后重试，或使用 `/devices/{device_id}/actions` 检查动作的 `is_busy` 状态。
+
+### 参数错误
+
+```json
+{
+    "code": 2002,
+    "data": { ... },
+    "message": "device_id is required"
+}
+```
+
+## 轮询策略
+
+推荐的任务状态轮询策略：
+
+```python
+import requests
+import time
+
+def wait_for_job(job_id, timeout=60, interval=0.5):
+    """等待任务完成并返回结果"""
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        response = requests.get(f"http://localhost:8002/api/v1/job/{job_id}/status")
+        data = response.json()["data"]
+
+        status = data["status"]
+        if status in (4, 5, 6):  # SUCCEEDED, CANCELED, ABORTED
+            return data
+
+        time.sleep(interval)
+
+    raise TimeoutError(f"Job {job_id} did not complete within {timeout} seconds")
+
+# 使用示例
+response = requests.post(
+    "http://localhost:8002/api/v1/job/add",
+    json={"device_id": "host_node", "action": "test_latency", "action_args": {}}
+)
+job_id = response.json()["data"]["jobId"]
+result = wait_for_job(job_id)
+print(result)
+```
+
+## 相关文档
+
+- [设备注册指南](add_device.md)
+- [动作定义指南](add_action.md)
+- [网络架构概述](networking_overview.md)
--- a/docs/developer_guide/networking_overview.md
+++ b/docs/developer_guide/networking_overview.md
@@ -0,0 +1,594 @@
+# 组网部署与主从模式配置
+
+本文档介绍 Uni-Lab-OS 的组网架构、部署方式和主从模式的详细配置。
+
+## 目录
+
+- [架构概览](#架构概览)
+- [节点类型](#节点类型)
+- [通信机制](#通信机制)
+- [典型拓扑](#典型拓扑)
+- [主从模式配置](#主从模式配置)
+- [网络配置](#网络配置)
+- [示例：多房间部署](#示例多房间部署)
+- [故障处理](#故障处理)
+- [监控和维护](#监控和维护)
+
+---
+
+## 架构概览
+
+Uni-Lab-OS 支持多种部署模式：
+
+```
+┌──────────────────────────────────────────────┐
+│      Cloud Platform/Self-hosted Platform     │
+│           uni-lab.bohrium.com                │
+│  (Resource Management, Task Scheduling,      │
+│              Monitoring)                     │
+└────────────────────┬─────────────────────────┘
+                     │ WebSocket / HTTP
+                     │
+          ┌──────────┴──────────┐
+          │                     │
+     ┌────▼─────┐         ┌────▼─────┐
+     │  Master  │◄──ROS2──►│  Slave   │
+     │   Node   │         │   Node   │
+     │  (Host)  │         │ (Slave)  │
+     └────┬─────┘         └────┬─────┘
+          │                    │
+     ┌────┴────┐          ┌────┴────┐
+     │ Device A│          │ Device B│
+     │ Device C│          │ Device D│
+     └─────────┘          └─────────┘
+```
+
+---
+
+## 节点类型
+
+### 主节点（Host Node）
+
+**功能**:
+
+- 创建和管理全局资源
+- 提供 host_node 服务
+- 连接云端平台
+- 协调多个从节点
+- 提供 Web 管理界面
+
+**启动命令**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g host_devices.json
+```
+
+### 从节点（Slave Node）
+
+**功能**:
+
+- 管理本地设备
+- 不连接云端（可选）
+- 向主节点注册
+- 执行分配的任务
+
+**启动命令**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g slave_devices.json --is_slave
+```
+
+---
+
+## 通信机制
+
+### ROS2 通信
+
+**用途**: 节点间实时通信
+
+**通信方式**:
+
+- **Topic**: 状态广播（设备状态、传感器数据）
+- **Service**: 同步请求（资源查询、配置获取）
+- **Action**: 异步任务（设备操作、长时间运行）
+
+**示例**:
+
+```bash
+# 查看ROS2节点
+ros2 node list
+
+# 查看topic
+ros2 topic list
+
+# 查看action
+ros2 action list
+```
+
+### WebSocket 通信
+
+**用途**: 主节点与云端通信
+
+**特点**:
+
+- 实时双向通信
+- 自动重连
+- 心跳保持
+
+**配置**:
+
+```python
+# local_config.py
+BasicConfig.ak = "your_ak"
+BasicConfig.sk = "your_sk"
+```
+
+---
+
+## 典型拓扑
+
+### 单节点模式
+
+**适用场景**: 小型实验室、开发测试
+
+```
+┌──────────────────┐
+│  Uni-Lab Node    │
+│  ┌────────────┐  │
+│  │  Device A  │  │
+│  │  Device B  │  │
+│  │  Device C  │  │
+│  └────────────┘  │
+└──────────────────┘
+```
+
+**优点**:
+
+- 配置简单
+- 无网络延迟
+- 适合快速原型
+
+**启动**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g all_devices.json
+```
+
+### 主从模式
+
+**适用场景**: 多房间、分布式设备
+
+```
+┌─────────────┐      ┌──────────────┐
+│ Master Node │◄────►│ Slave Node 1 │
+│ Coordinator │      │   Liquid     │
+│ Web UI      │      │  Handling    │
+└──────┬──────┘      └──────────────┘
+       │
+       │             ┌──────────────┐
+       └────────────►│ Slave Node 2 │
+                     │  Analytical  │
+                     │  (NMR/GC)    │
+                     └──────────────┘
+```
+
+**优点**:
+
+- 物理分隔
+- 独立故障域
+- 易于扩展
+
+**适用场景**:
+
+- 设备物理位置分散
+- 不同房间的设备
+- 需要独立故障域
+- 分阶段扩展系统
+
+**主节点**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g host.json
+```
+
+**从节点**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave
+unilab --ak your_ak --sk your_sk -g slave2.json --is_slave --port 8003
+```
+
+### 云端集成模式
+
+**适用场景**: 远程监控、多实验室协作
+
+```
+      Cloud Platform
+            │
+    ┌───────┴────────┐
+    │                │
+Laboratory A    Laboratory B
+(Master Node)   (Master Node)
+```
+
+**优点**:
+
+- 远程访问
+- 数据同步
+- 任务调度
+
+**启动**:
+
+```bash
+# 实验室A
+unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+
+# 实验室B
+unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+```
+
+---
+
+## 主从模式配置
+
+### 主节点配置
+
+#### 1. 创建主节点设备图
+
+`host.json`:
+
+```json
+{
+  "nodes": [],
+  "links": []
+}
+```
+
+#### 2. 启动主节点
+
+```bash
+# 基本启动
+unilab --ak your_ak --sk your_sk -g host.json
+
+# 带云端集成
+unilab --ak your_ak --sk your_sk -g host.json --upload_registry
+
+# 指定端口
+unilab --ak your_ak --sk your_sk -g host.json --port 8002
+```
+
+#### 3. 验证主节点
+
+```bash
+# 检查ROS2节点
+ros2 node list
+# 应该看到 /host_node
+
+# 检查服务
+ros2 service list | grep host_node
+
+# Web界面
+# 访问 http://localhost:8002
+```
+
+### 从节点配置
+
+#### 1. 创建从节点设备图
+
+`slave1.json`:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "liquid_handler_1",
+      "name": "液体处理工作站",
+      "type": "device",
+      "class": "liquid_handler",
+      "config": {
+        "simulation": false
+      }
+    }
+  ],
+  "links": []
+}
+```
+
+#### 2. 启动从节点
+
+```bash
+# 基本从节点启动
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave
+
+# 指定不同端口（如果多个从节点在同一台机器）
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --port 8003
+
+# 跳过等待主节点（独立测试）
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --slave_no_host
+```
+
+#### 3. 验证从节点
+
+```bash
+# 检查节点连接
+ros2 node list
+
+# 检查设备状态
+ros2 topic echo /liquid_handler_1/status
+```
+
+### 跨节点通信
+
+#### 资源访问
+
+主节点可以访问从节点的资源：
+
+```bash
+# 在主节点或其他节点调用从节点设备
+ros2 action send_goal /liquid_handler_1/transfer_liquid \
+  unilabos_msgs/action/TransferLiquid \
+  "{source: {...}, target: {...}, volume: 100.0}"
+```
+
+#### 状态监控
+
+主节点监控所有从节点状态：
+
+```bash
+# 订阅从节点状态
+ros2 topic echo /liquid_handler_1/status
+
+# 查看所有设备状态
+ros2 topic list | grep status
+```
+
+---
+
+## 网络配置
+
+### ROS2 DDS 配置
+
+确保主从节点在同一网络：
+
+```bash
+# 检查网络可达性
+ping <slave_node_ip>
+
+# 设置ROS_DOMAIN_ID（可选，用于隔离）
+export ROS_DOMAIN_ID=42
+```
+
+### 防火墙配置
+
+**建议做法**：
+
+为了确保 ROS2 DDS 通信正常，建议直接关闭防火墙，而不是配置特定端口。ROS2 使用动态端口范围，配置特定端口可能导致通信问题。
+
+**Linux**:
+
+```bash
+# 关闭防火墙
+sudo ufw disable
+
+# 或者临时停止防火墙
+sudo systemctl stop ufw
+```
+
+**Windows**:
+
+```powershell
+# 在Windows安全中心关闭防火墙
+# 控制面板 -> 系统和安全 -> Windows Defender 防火墙 -> 启用或关闭Windows Defender防火墙
+```
+
+### 验证网络连通性
+
+在配置完成后，使用 ROS2 自带的 demo 节点来验证跨节点通信是否正常：
+
+**在主节点机器上**（激活 unilab 环境后）：
+
+```bash
+# 启动talker
+ros2 run demo_nodes_cpp talker
+
+# 同时在另一个终端启动listener
+ros2 run demo_nodes_cpp listener
+```
+
+**在从节点机器上**（激活 unilab 环境后）：
+
+```bash
+# 启动talker
+ros2 run demo_nodes_cpp talker
+
+# 同时在另一个终端启动listener
+ros2 run demo_nodes_cpp listener
+```
+
+**注意**：必须在两台机器上**互相启动** talker 和 listener，否则可能出现只能收不能发的单向通信问题。
+
+**预期结果**：
+
+- 每台机器的 listener 应该能同时接收到本地和远程 talker 发送的消息
+- 如果只能看到本地消息，说明网络配置有问题
+- 如果两台机器都能互相收发消息，则组网配置正确
+
+### 本地网络要求
+
+**ROS2 通信**:
+
+- 同一局域网或 VPN
+- 端口：默认 DDS 端口（7400-7500）
+- 组播支持（或配置 unicast）
+
+**检查连通性**:
+
+```bash
+# Ping测试
+ping <target_ip>
+
+# ROS2节点发现
+ros2 node list
+ros2 daemon stop && ros2 daemon start
+```
+
+### 云端连接
+
+**要求**:
+
+- HTTPS (443)
+- WebSocket 支持
+- 稳定的互联网连接
+
+**测试连接**:
+
+```bash
+# 测试云端连接
+curl https://uni-lab.bohrium.com/api/v1/health
+
+# 测试WebSocket
+# 启动Uni-Lab后查看日志
+```
+
+---
+
+## 示例：多房间部署
+
+### 场景描述
+
+- **房间 A**: 主控室，有 Web 界面
+- **房间 B**: 液体处理室
+- **房间 C**: 分析仪器室
+
+### 房间 A - 主节点
+
+```bash
+# host.json
+unilab --ak your_ak --sk your_sk -g host.json --port 8002
+```
+
+### 房间 B - 从节点 1
+
+```bash
+# liquid_handler.json
+unilab --ak your_ak --sk your_sk -g liquid_handler.json --is_slave --port 8003
+```
+
+### 房间 C - 从节点 2
+
+```bash
+# analytical.json
+unilab --ak your_ak --sk your_sk -g analytical.json --is_slave --port 8004
+```
+
+---
+
+## 故障处理
+
+### 节点离线
+
+**检测**:
+
+```bash
+ros2 node list  # 查看在线节点
+```
+
+**处理**:
+
+1. 检查网络连接
+2. 重启节点
+3. 检查日志
+
+### 从节点无法连接主节点
+
+1. 检查网络：
+
+   ```bash
+   ping <host_ip>
+   ```
+
+2. 检查 ROS_DOMAIN_ID：
+
+   ```bash
+   echo $ROS_DOMAIN_ID
+   ```
+
+3. 使用`--slave_no_host`测试：
+   ```bash
+   unilab --ak your_ak --sk your_sk -g slave.json --is_slave --slave_no_host
+   ```
+
+### 通信延迟
+
+**排查**:
+
+```bash
+# 网络延迟
+ping <node_ip>
+
+# ROS2话题延迟
+ros2 topic hz /device_status
+ros2 topic bw /device_status
+```
+
+**优化**:
+
+- 减少发布频率
+- 使用 QoS 配置
+- 优化网络带宽
+
+### 数据同步失败
+
+**检查**:
+
+```bash
+# 查看日志
+tail -f unilabos_data/logs/unilab.log | grep sync
+```
+
+**解决**:
+
+- 检查云端连接
+- 验证 AK/SK
+- 手动触发同步
+
+### 资源不可见
+
+检查资源注册：
+
+```bash
+ros2 service call /host_node/resource_list \
+  unilabos_msgs/srv/ResourceList
+```
+
+---
+
+## 监控和维护
+
+### 节点状态监控
+
+```bash
+# 查看所有节点
+ros2 node list
+
+# 查看话题
+ros2 topic list
+```
+
+---
+
+## 相关文档
+
+- [最佳实践指南](../user_guide/best_practice.md) - 完整的实验室搭建流程
+- [安装指南](../user_guide/installation.md) - 环境安装步骤
+- [启动参数详解](../user_guide/launch.md) - 启动参数说明
+- [添加设备驱动](add_device.md) - 自定义设备开发
+- [工作站架构](workstation_architecture.md) - 复杂工作站搭建
+
+---
+
+## 参考资料
+
+- [ROS2 网络配置](https://docs.ros.org/en/humble/Tutorials/Advanced/Networking.html)
+- [DDS 配置](https://fast-dds.docs.eprosima.com/)
+- Uni-Lab 云平台文档
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,9 +1,23 @@
-# Uni-Lab 项目文档
+# Uni-Lab-OS 项目文档

-欢迎来到项目文档的首页！
+Uni-Lab-OS 是一个开源的实验室自动化操作系统，提供统一的设备接口、工作流管理和分布式部署能力。

 ```{toctree}
 :maxdepth: 3

 intro.md
 ```
+
+## 开发者指南
+
+```{toctree}
+:maxdepth: 2
+
+developer_guide/http_api.md
+developer_guide/networking_overview.md
+developer_guide/add_device.md
+developer_guide/add_action.md
+developer_guide/add_registry.md
+developer_guide/add_yaml.md
+developer_guide/action_includes.md
+```
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -10,35 +10,51 @@ concepts/01-communication-instruction.md
 concepts/02-topology-and-chemputer-compile.md
 ```

-## **用户指南**
+## 用户指南

-本指南将带你了解如何使用项目的功能。
+快速上手、系统配置与使用说明。

 ```{toctree}
 :maxdepth: 2

+user_guide/best_practice.md
 user_guide/installation.md
-user_guide/configuration.md
 user_guide/launch.md
+user_guide/graph_files.md
 boot_examples/index.md
 ```

+## 进阶配置
+
+高级配置和系统管理。
+
+```{toctree}
+:maxdepth: 2
+
+advanced_usage/configuration.md
+advanced_usage/working_directory.md
+```
+
 ## 开发者指南

-```{toctree}
+设备开发、系统扩展与架构说明。

+```{toctree}
 :maxdepth: 2

-developer_guide/device_driver
-developer_guide/add_device
-developer_guide/add_action
-developer_guide/actions
-developer_guide/workstation_architecture
-developer_guide/add_protocol
-developer_guide/add_batteryPLC
-developer_guide/materials_tutorial
-developer_guide/materials_construction_guide
-
+developer_guide/networking_overview.md
+developer_guide/add_device.md
+developer_guide/add_old_device.md
+developer_guide/add_registry.md
+developer_guide/add_yaml.md
+developer_guide/add_action.md
+developer_guide/actions.md
+developer_guide/action_includes.md
+developer_guide/add_protocol.md
+developer_guide/examples/workstation_architecture.md
+developer_guide/examples/materials_construction_guide.md
+developer_guide/examples/materials_tutorial.md
+developer_guide/examples/battery_plc_workstation.md
 ```

 ## 接口文档
--- a/docs/logo.png
+++ b/docs/logo.png
--- a/docs/requirements.txt
+++ b/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
--- a/docs/user_guide/best_practice.md
+++ b/docs/user_guide/best_practice.md
--- a/docs/user_guide/configuration.md
+++ b/docs/user_guide/configuration.md
@@ -1,442 +0,0 @@
-# Uni-Lab 配置指南
-
-Uni-Lab 支持通过 Python 配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的 Uni-Lab 环境。
-
-## 配置文件格式
-
-Uni-Lab 支持 Python 格式的配置文件，它比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
-
-### 默认配置示例
-
-首次使用时，系统会自动创建一个基础配置文件 `local_config.py`：
-
-```python
-# unilabos的配置文件
-
-class BasicConfig:
-    ak = ""  # 实验室网页给您提供的ak代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --ak 传入，优先按照传入参数解析
-    sk = ""  # 实验室网页给您提供的sk代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --sk 传入，优先按照传入参数解析
-
-
-# WebSocket配置，一般无需调整
-class WSConfig:
-    reconnect_interval = 5  # 重连间隔（秒）
-    max_reconnect_attempts = 999  # 最大重连次数
-    ping_interval = 30  # ping间隔（秒）
-```
-您可以进入实验室，点击左下角的头像在实验室详情中获取所在实验室的ak sk
-![copy_aksk.gif](image/copy_aksk.gif)
-
-### 完整配置示例
-
-您可以根据需要添加更多配置选项：
-
-```python
-#!/usr/bin/env python
-# coding=utf-8
-"""Uni-Lab 配置文件"""
-
-# 基础配置
-class BasicConfig:
-    ak = "your_access_key"  # 实验室访问密钥
-    sk = "your_secret_key"  # 实验室私钥
-    working_dir = ""  # 工作目录（通常自动设置）
-    config_path = ""  # 配置文件路径（自动设置）
-    is_host_mode = True  # 是否为主站模式
-    slave_no_host = False  # 从站模式下是否跳过等待主机服务
-    upload_registry = False  # 是否上传注册表
-    machine_name = "undefined"  # 机器名称（自动获取）
-    vis_2d_enable = False  # 是否启用2D可视化
-    enable_resource_load = True  # 是否启用资源加载
-    communication_protocol = "websocket"  # 通信协议
-
-# WebSocket配置
-class WSConfig:
-    reconnect_interval = 5  # 重连间隔（秒）
-    max_reconnect_attempts = 999  # 最大重连次数
-    ping_interval = 30  # ping间隔（秒）
-
-# OSS上传配置
-class OSSUploadConfig:
-    api_host = ""  # API主机地址
-    authorization = ""  # 授权信息
-    init_endpoint = ""  # 初始化端点
-    complete_endpoint = ""  # 完成端点
-    max_retries = 3  # 最大重试次数
-
-# HTTP配置
-class HTTPConfig:
-    remote_addr = "http://127.0.0.1:48197/api/v1"  # 远程地址
-
-# ROS配置
-class ROSConfig:
-    modules = [
-        "std_msgs.msg",
-        "geometry_msgs.msg",
-        "control_msgs.msg",
-        "control_msgs.action",
-        "nav2_msgs.action",
-        "unilabos_msgs.msg",
-        "unilabos_msgs.action",
-    ]  # 需要加载的ROS模块
-```
-
-## 命令行参数覆盖配置
-
-Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。命令行参数的优先级高于配置文件。
-
-### 支持命令行覆盖的配置项
-
-以下配置项可以通过命令行参数进行覆盖：
-
-| 配置类        | 配置字段          | 命令行参数          | 说明                             |
-| ------------- | ----------------- | ------------------- | -------------------------------- |
-| `BasicConfig` | `ak`              | `--ak`              | 实验室访问密钥                   |
-| `BasicConfig` | `sk`              | `--sk`              | 实验室私钥                       |
-| `BasicConfig` | `working_dir`     | `--working_dir`     | 工作目录路径                     |
-| `BasicConfig` | `is_host_mode`    | `--is_slave`        | 主站模式（参数为从站模式，取反） |
-| `BasicConfig` | `slave_no_host`   | `--slave_no_host`   | 从站模式下跳过等待主机服务       |
-| `BasicConfig` | `upload_registry` | `--upload_registry` | 启动时上传注册表信息             |
-| `BasicConfig` | `vis_2d_enable`   | `--2d_vis`          | 启用 2D 可视化                   |
-| `HTTPConfig`  | `remote_addr`     | `--addr`            | 远程服务地址                     |
-
-### 特殊命令行参数
-
-除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
-
-| 参数                | 说明                                 |
-| ------------------- | ------------------------------------ |
-| `--config`          | 指定配置文件路径                     |
-| `--port`            | Web 服务端口（不影响配置文件）       |
-| `--disable_browser` | 禁用自动打开浏览器（不影响配置文件） |
-| `--visual`          | 可视化工具选择（不影响配置文件）     |
-| `--skip_env_check`  | 跳过环境检查（不影响配置文件）       |
-
-### 配置优先级
-
-配置项的生效优先级从高到低为：
-
-1. **命令行参数**：最高优先级
-2. **环境变量**：中等优先级
-3. **配置文件**：基础优先级
-
-### 使用示例
-
-```bash
-# 通过命令行覆盖认证信息
-unilab --ak "new_access_key" --sk "new_secret_key"
-
-# 覆盖服务器地址
-unilab --addr "https://custom.server.com/api/v1"
-
-# 启用从站模式并跳过等待主机
-unilab --is_slave --slave_no_host
-
-# 启用上传注册表和2D可视化
-unilab --upload_registry --2d_vis
-
-# 组合使用多个覆盖参数
-unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis
-```
-
-### 预设环境地址
-
-`--addr` 参数支持以下预设值，会自动转换为对应的完整 URL：
-
- `test` → `https://uni-lab.test.bohrium.com/api/v1`
- `uat` → `https://uni-lab.uat.bohrium.com/api/v1`
- `local` → `http://127.0.0.1:48197/api/v1`
- 其他值 → 直接使用作为完整 URL
-
-## 配置选项详解
-
-### 基础配置 (BasicConfig)
-
-基础配置包含了系统运行的核心参数：
-
-| 参数                     | 类型 | 默认值        | 说明                                       |
-| ------------------------ | ---- | ------------- | ------------------------------------------ |
-| `ak`                     | str  | `""`          | 实验室访问密钥（必需）                     |
-| `sk`                     | str  | `""`          | 实验室私钥（必需）                         |
-| `working_dir`            | str  | `""`          | 工作目录，通常自动设置                     |
-| `is_host_mode`           | bool | `True`        | 是否为主站模式                             |
-| `slave_no_host`          | bool | `False`       | 从站模式下是否跳过等待主机服务             |
-| `upload_registry`        | bool | `False`       | 启动时是否上传注册表信息                   |
-| `machine_name`           | str  | `"undefined"` | 机器名称，自动从 hostname 获取（不可配置） |
-| `vis_2d_enable`          | bool | `False`       | 是否启用 2D 可视化                         |
-| `communication_protocol` | str  | `"websocket"` | 通信协议，固定为 websocket                 |
-
-#### 认证配置
-
-`ak` 和 `sk` 是必需的认证参数：
-
-1. **获取方式**：在 [Uni-Lab 官网](https://uni-lab.bohrium.com) 注册实验室后获得
-2. **配置方式**：
-   - **命令行参数**：`--ak "your_key" --sk "your_secret"`（最高优先级）
-   - **配置文件**：在 `BasicConfig` 类中设置
-   - **环境变量**：`UNILABOS_BASICCONFIG_AK` 和 `UNILABOS_BASICCONFIG_SK`
-3. **优先级顺序**：命令行参数 > 环境变量 > 配置文件
-4. **安全注意**：请妥善保管您的密钥信息
-
-**推荐做法**：
-
- 开发环境：使用配置文件
- 生产环境：使用环境变量或命令行参数
- 临时测试：使用命令行参数
-
-### WebSocket 配置 (WSConfig)
-
-WebSocket 是 Uni-Lab 的主要通信方式：
-
-| 参数                     | 类型 | 默认值 | 说明               |
-| ------------------------ | ---- | ------ | ------------------ |
-| `reconnect_interval`     | int  | `5`    | 断线重连间隔（秒） |
-| `max_reconnect_attempts` | int  | `999`  | 最大重连次数       |
-| `ping_interval`          | int  | `30`   | 心跳检测间隔（秒） |
-
-### HTTP 配置 (HTTPConfig)
-
-HTTP 客户端配置用于与云端服务通信：
-
-| 参数          | 类型 | 默认值                            | 说明         |
-| ------------- | ---- | --------------------------------- | ------------ |
-| `remote_addr` | str  | `"http://127.0.0.1:48197/api/v1"` | 远程服务地址 |
-
-**预设环境地址**：
-
- 生产环境：`https://uni-lab.bohrium.com/api/v1`
- 测试环境：`https://uni-lab.test.bohrium.com/api/v1`
- UAT 环境：`https://uni-lab.uat.bohrium.com/api/v1`
- 本地环境：`http://127.0.0.1:48197/api/v1`
-
-### ROS 配置 (ROSConfig)
-
-配置 ROS 消息转换器需要加载的模块：
-
-```python
-class ROSConfig:
-    modules = [
-        "std_msgs.msg",           # 标准消息类型
-        "geometry_msgs.msg",      # 几何消息类型
-        "control_msgs.msg",       # 控制消息类型
-        "control_msgs.action",    # 控制动作类型
-        "nav2_msgs.action",       # 导航动作类型
-        "unilabos_msgs.msg",      # UniLab 自定义消息类型
-        "unilabos_msgs.action",   # UniLab 自定义动作类型
-    ]
-```
-
-您可以根据实际使用的设备和功能添加其他 ROS 模块。
-
-### OSS 上传配置 (OSSUploadConfig)
-
-对象存储服务配置，用于文件上传功能：
-
-| 参数                | 类型 | 默认值 | 说明                 |
-| ------------------- | ---- | ------ | -------------------- |
-| `api_host`          | str  | `""`   | OSS API 主机地址     |
-| `authorization`     | str  | `""`   | 授权认证信息         |
-| `init_endpoint`     | str  | `""`   | 上传初始化端点       |
-| `complete_endpoint` | str  | `""`   | 上传完成端点         |
-| `max_retries`       | int  | `3`    | 上传失败最大重试次数 |
-
-## 环境变量支持
-
-Uni-Lab 支持通过环境变量覆盖配置文件中的设置。环境变量格式为：
-
-```
-UNILABOS_{配置类名}_{字段名}
-```
-
-### 环境变量示例
-
-```bash
-# 设置基础配置
-export UNILABOS_BASICCONFIG_AK="your_access_key"
-export UNILABOS_BASICCONFIG_SK="your_secret_key"
-export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
-
-# 设置WebSocket配置
-export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
-export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
-
-# 设置HTTP配置
-export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.bohrium.com/api/v1"
-```
-
-### 环境变量类型转换
-
- **布尔值**：`"true"`, `"1"`, `"yes"` → `True`；其他 → `False`
- **整数**：自动转换为 `int` 类型
- **浮点数**：自动转换为 `float` 类型
- **字符串**：保持原值
-
-## 配置文件使用方法
-
-### 1. 指定配置文件启动
-
-```bash
-# 使用指定配置文件启动
-unilab --config /path/to/your/config.py
-```
-
-### 2. 使用默认配置文件
-
-如果不指定配置文件，系统会按以下顺序查找：
-
-1. 环境变量 `UNILABOS_BASICCONFIG_CONFIG_PATH` 指定的路径
-2. 工作目录下的 `local_config.py`
-3. 首次使用时会引导创建配置文件
-
-### 3. 配置文件验证
-
-系统启动时会自动验证配置文件：
-
- **语法检查**：确保 Python 语法正确
- **类型检查**：验证配置项类型是否匹配
- **必需项检查**：确保 `ak` 和 `sk` 已配置
-
-## 最佳实践
-
-### 1. 安全配置
-
- 不要将包含密钥的配置文件提交到版本控制系统
- 使用环境变量或命令行参数在生产环境中配置敏感信息
- 定期更换访问密钥
- **推荐配置方式**：
-
-  ```bash
-  # 生产环境 - 使用环境变量
-  export UNILABOS_BASICCONFIG_AK="your_access_key"
-  export UNILABOS_BASICCONFIG_SK="your_secret_key"
-  unilab
-
-  # 或使用命令行参数
-  unilab --ak "your_access_key" --sk "your_secret_key"
-  ```
-
-### 2. 多环境配置
-
-为不同环境创建不同的配置文件并结合命令行参数：
-
-```
-configs/
-├── local_config.py      # 本地开发
-├── test_config.py       # 测试环境
-├── prod_config.py       # 生产环境
-└── example_config.py    # 示例配置
-```
-
-**环境切换示例**：
-
-```bash
-# 本地开发环境
-unilab --config configs/local_config.py --addr local
-
-# 测试环境
-unilab --config configs/test_config.py --addr test --upload_registry
-
-# 生产环境
-unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK"
-```
-
-### 3. 配置管理
-
- 保持配置文件简洁，只包含需要修改的配置项
- 为配置项添加注释说明其作用
- 定期检查和更新配置文件
- **命令行参数优先使用场景**：
-  - 临时测试不同配置
-  - CI/CD 流水线中的动态配置
-  - 不同环境间快速切换
-  - 敏感信息的安全传递
-
-### 4. 灵活配置策略
-
-**基础配置文件 + 命令行覆盖**的推荐方式：
-
-```python
-# base_config.py - 基础配置
-class BasicConfig:
-    # 非敏感配置写在文件中
-    is_host_mode = True
-    upload_registry = False
-    vis_2d_enable = False
-
-class WSConfig:
-    reconnect_interval = 5
-    max_reconnect_attempts = 999
-    ping_interval = 30
-```
-
-```bash
-# 启动时通过命令行覆盖关键参数
-unilab --config base_config.py \
-       --ak "$AK" \
-       --sk "$SK" \
-       --addr "test" \
-       --upload_registry \
-       --2d_vis
-```
-
-## 故障排除
-
-### 1. 配置文件加载失败
-
-**错误信息**：`[ENV] 配置文件 xxx 不存在`
-
-**解决方法**：
-
- 确认配置文件路径正确
- 检查文件权限是否可读
- 确保配置文件是 `.py` 格式
-
-### 2. 语法错误
-
-**错误信息**：`[ENV] 加载配置文件 xxx 失败`
-
-**解决方法**：
-
- 检查 Python 语法是否正确
- 确认类名和字段名拼写正确
- 验证缩进是否正确（使用空格而非制表符）
-
-### 3. 认证失败
-
-**错误信息**：`后续运行必须拥有一个实验室`
-
-**解决方法**：
-
- 确认 `ak` 和 `sk` 已正确配置
- 检查密钥是否有效
- 确认网络连接正常
-
-### 4. 环境变量不生效
-
-**解决方法**：
-
- 确认环境变量名格式正确（`UNILABOS_CLASS_FIELD`）
- 检查环境变量是否已正确设置
- 重启系统或重新加载环境变量
-
-### 5. 命令行参数不生效
-
-**错误现象**：设置了命令行参数但配置没有生效
-
-**解决方法**：
-
- 确认参数名拼写正确（如 `--ak` 而不是 `--access_key`）
- 检查参数格式是否正确（布尔参数如 `--is_slave` 不需要值）
- 确认参数位置正确（所有参数都应在 `unilab` 之后）
- 查看启动日志确认参数是否被正确解析
-
-### 6. 配置优先级混淆
-
-**错误现象**：不确定哪个配置生效
-
-**解决方法**：
-
- 记住优先级：命令行参数 > 环境变量 > 配置文件
- 使用 `--ak` 和 `--sk` 参数时会看到提示信息
- 检查启动日志中的配置加载信息
- 临时移除低优先级配置来测试高优先级配置是否生效
--- a/docs/user_guide/graph_files.md
+++ b/docs/user_guide/graph_files.md
@@ -0,0 +1,860 @@
+# 设备图文件说明
+
+设备图文件定义了实验室中所有设备、资源及其连接关系。本文档说明如何创建和使用设备图文件。
+
+## 概述
+
+设备图文件采用 JSON 格式，节点定义基于 **`ResourceDict`** 标准模型（定义在 `unilabos.ros.nodes.resource_tracker`）。系统会自动处理旧格式并转换为标准格式，确保向后兼容性。
+
+**核心概念**:
+
+- **Nodes（节点）**: 代表设备或资源，通过 `parent` 字段建立层级关系
+- **Links（连接）**: 可选的连接关系定义，用于展示设备间的物理或通信连接
+- **UUID**: 全局唯一标识符，用于跨系统的资源追踪
+- **自动转换**: 旧格式会通过 `ResourceDictInstance.get_resource_instance_from_dict()` 自动转换
+
+## 文件格式
+
+Uni-Lab 支持两种格式的设备图文件：
+
+### JSON 格式（推荐）
+
+**优点**:
+
+- 易于编辑和阅读
+- 支持注释（使用预处理）
+- 与 Web 界面完全兼容
+- 便于版本控制
+
+**示例**: `workshop1.json`
+
+### GraphML 格式
+
+**优点**:
+
+- 可用图形化工具编辑（如 yEd）
+- 适合复杂拓扑可视化
+
+**示例**: `setup.graphml`
+
+## JSON 文件结构
+
+一个完整的 JSON 设备图文件包含两个主要部分：
+
+```json
+{
+  "nodes": [
+    /* 设备和资源节点 */
+  ],
+  "links": [
+    /* 连接关系（可选）*/
+  ]
+}
+```
+
+### Nodes（节点）
+
+每个节点代表一个设备或资源。节点的定义遵循 `ResourceDict` 标准模型：
+
+```json
+{
+  "id": "liquid_handler_1",
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "液体处理工作站",
+  "type": "device",
+  "class": "liquid_handler",
+  "config": {
+    "port": "/dev/ttyUSB0",
+    "baudrate": 9600
+  },
+  "data": {},
+  "position": {
+    "x": 100,
+    "y": 200
+  },
+  "parent": null
+}
+```
+
+**字段说明（基于 ResourceDict 标准定义）**:
+
+| 字段          | 必需 | 说明                     | 示例                                                 | 默认值   |
+| ------------- | ---- | ------------------------ | ---------------------------------------------------- | -------- |
+| `id`          | ✓    | 唯一标识符               | `"pump_1"`                                           | -        |
+| `uuid`        |      | 全局唯一标识符 (UUID)    | `"550e8400-e29b-41d4-a716-446655440000"`             | 自动生成 |
+| `name`        | ✓    | 显示名称                 | `"主反应泵"`                                         | -        |
+| `type`        | ✓    | 节点类型                 | `"device"`, `"resource"`, `"container"`, `"deck"` 等 | -        |
+| `class`       | ✓    | 设备/资源类别            | `"liquid_handler"`, `"syringepump.runze"`            | `""`     |
+| `config`      |      | Python 类的初始化参数    | `{"port": "COM3"}`                                   | `{}`     |
+| `data`        |      | 资源的运行状态数据       | `{"status": "Idle", "position": 0.0}`                | `{}`     |
+| `position`    |      | 在图中的位置             | `{"x": 100, "y": 200}` 或完整的 pose 结构            | -        |
+| `pose`        |      | 完整的 3D 位置信息       | 参见下文                                             | -        |
+| `parent`      |      | 父节点 ID                | `"deck_1"`                                           | `null`   |
+| `parent_uuid` |      | 父节点 UUID              | `"550e8400-..."`                                     | `null`   |
+| `children`    |      | 子节点 ID 列表（旧格式） | `["child1", "child2"]`                               | -        |
+| `description` |      | 资源描述                 | `"用于精确控制试剂A的加料速率"`                      | `""`     |
+| `schema`      |      | 资源 schema 定义         | `{}`                                                 | `{}`     |
+| `model`       |      | 资源 3D 模型信息         | `{}`                                                 | `{}`     |
+| `icon`        |      | 资源图标                 | `"pump.webp"`                                        | `""`     |
+| `extra`       |      | 额外的自定义数据         | `{"custom_field": "value"}`                          | `{}`     |
+
+### Position 和 Pose（位置信息）
+
+**简单格式（旧格式，兼容）**:
+
+```json
+"position": {
+  "x": 100,
+  "y": 200,
+  "z": 0
+}
+```
+
+**完整格式（推荐）**:
+
+```json
+"pose": {
+  "size": {
+    "width": 127.76,
+    "height": 85.48,
+    "depth": 10.0
+  },
+  "scale": {
+    "x": 1.0,
+    "y": 1.0,
+    "z": 1.0
+  },
+  "layout": "x-y",
+  "position": {
+    "x": 100,
+    "y": 200,
+    "z": 0
+  },
+  "position3d": {
+    "x": 100,
+    "y": 200,
+    "z": 0
+  },
+  "rotation": {
+    "x": 0,
+    "y": 0,
+    "z": 0
+  },
+  "cross_section_type": "rectangle"
+}
+```
+
+### Links（连接）
+
+定义节点之间的连接关系（可选，主要用于物理连接或通信关系的可视化）：
+
+```json
+{
+  "source": "pump_1",
+  "target": "reactor_1",
+  "sourceHandle": "output",
+  "targetHandle": "input",
+  "type": "physical"
+}
+```
+
+**字段说明**:
+
+| 字段           | 必需 | 说明             | 示例                                     |
+| -------------- | ---- | ---------------- | ---------------------------------------- |
+| `source`       | ✓    | 源节点 ID        | `"pump_1"`                               |
+| `target`       | ✓    | 目标节点 ID      | `"reactor_1"`                            |
+| `sourceHandle` |      | 源节点的连接点   | `"output"`                               |
+| `targetHandle` |      | 目标节点的连接点 | `"input"`                                |
+| `type`         |      | 连接类型         | `"physical"`, `"communication"`          |
+| `port`         |      | 端口映射信息     | `{"source": "port1", "target": "port2"}` |
+
+**注意**: Links 主要用于图形化展示和文档说明，父子关系通过 `parent` 字段定义，不依赖 links。
+
+## 完整示例
+
+### 示例 1：液体处理工作站（PRCXI9300）
+
+这是一个真实的液体处理工作站配置，包含设备、工作台和多个板资源。
+
+**文件位置**: `test/experiments/prcxi_9300.json`
+
+```json
+{
+  "nodes": [
+    {
+      "id": "PRCXI9300",
+      "name": "PRCXI9300",
+      "parent": null,
+      "type": "device",
+      "class": "liquid_handler.prcxi",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "deck": {
+          "_resource_child_name": "PRCXI_Deck_9300",
+          "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck"
+        },
+        "host": "10.181.214.132",
+        "port": 9999,
+        "timeout": 10.0,
+        "axis": "Left",
+        "channel_num": 8,
+        "setup": false,
+        "debug": true,
+        "simulator": true,
+        "matrix_id": "71593"
+      },
+      "data": {},
+      "children": ["PRCXI_Deck_9300"]
+    },
+    {
+      "id": "PRCXI_Deck_9300",
+      "name": "PRCXI_Deck_9300",
+      "parent": "PRCXI9300",
+      "type": "deck",
+      "class": "",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "type": "PRCXI9300Deck",
+        "size_x": 100,
+        "size_y": 100,
+        "size_z": 100,
+        "rotation": {
+          "x": 0,
+          "y": 0,
+          "z": 0,
+          "type": "Rotation"
+        },
+        "category": "deck"
+      },
+      "data": {},
+      "children": [
+        "RackT1",
+        "PlateT2",
+        "trash",
+        "PlateT4",
+        "PlateT5",
+        "PlateT6"
+      ]
+    },
+    {
+      "id": "RackT1",
+      "name": "RackT1",
+      "parent": "PRCXI_Deck_9300",
+      "type": "tip_rack",
+      "class": "",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "type": "TipRack",
+        "size_x": 127.76,
+        "size_y": 85.48,
+        "size_z": 100
+      },
+      "data": {},
+      "children": []
+    }
+  ]
+}
+```
+
+**关键点**:
+
+- 使用 `parent` 字段建立层级关系（PRCXI9300 → Deck → Rack/Plate）
+- 使用 `children` 字段（旧格式）列出子节点
+- `config` 中包含设备特定的连接参数
+- `data` 存储运行时状态
+- `position` 使用简单的 x/y/z 坐标
+
+### 示例 2：有机合成工作站（带 Links）
+
+这是一个格林纳德反应的流动化学工作站配置，展示了完整的设备连接和通信关系。
+
+**文件位置**: `test/experiments/Grignard_flow_batchreact_single_pumpvalve.json`
+
+```json
+{
+  "nodes": [
+    {
+      "id": "YugongStation",
+      "name": "愚公常量合成工作站",
+      "parent": null,
+      "type": "device",
+      "class": "workstation",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "protocol_type": [
+          "PumpTransferProtocol",
+          "CleanProtocol",
+          "SeparateProtocol",
+          "EvaporateProtocol"
+        ]
+      },
+      "data": {},
+      "children": [
+        "serial_pump",
+        "pump_reagents",
+        "flask_CH2Cl2",
+        "reactor",
+        "pump_workup",
+        "separator_controller",
+        "flask_separator",
+        "rotavap",
+        "column"
+      ]
+    },
+    {
+      "id": "serial_pump",
+      "name": "serial_pump",
+      "parent": "YugongStation",
+      "type": "device",
+      "class": "serial",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "port": "COM7",
+        "baudrate": 9600
+      },
+      "data": {},
+      "children": []
+    },
+    {
+      "id": "pump_reagents",
+      "name": "pump_reagents",
+      "parent": "YugongStation",
+      "type": "device",
+      "class": "syringepump.runze",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "port": "/devices/PumpBackbone/Serial/serialwrite",
+        "address": "1",
+        "max_volume": 25.0
+      },
+      "data": {
+        "max_velocity": 1.0,
+        "position": 0.0,
+        "status": "Idle",
+        "valve_position": "0"
+      },
+      "children": []
+    },
+    {
+      "id": "reactor",
+      "name": "reactor",
+      "parent": "YugongStation",
+      "type": "container",
+      "class": null,
+      "position": {
+        "x": 430.4087301587302,
+        "y": 428,
+        "z": 0
+      },
+      "config": {},
+      "data": {},
+      "children": []
+    }
+  ],
+  "links": [
+    {
+      "source": "pump_reagents",
+      "target": "serial_pump",
+      "type": "communication",
+      "port": {
+        "pump_reagents": "port",
+        "serial_pump": "port"
+      }
+    },
+    {
+      "source": "pump_workup",
+      "target": "serial_pump",
+      "type": "communication",
+      "port": {
+        "pump_workup": "port",
+        "serial_pump": "port"
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+
+- 多级设备层次：工作站包含多个子设备和容器
+- `links` 定义通信关系（泵通过串口连接）
+- `data` 字段存储设备状态（如泵的位置、速度等）
+- `class` 可以使用点号分层（如 `"syringepump.runze"`）
+- 容器的 `class` 可以为 `null`
+
+## 格式兼容性和转换
+
+### 旧格式自动转换
+
+Uni-Lab 使用 `ResourceDictInstance.get_resource_instance_from_dict()` 方法自动处理旧格式的节点数据，确保向后兼容性。
+
+**自动转换规则**:
+
+1. **自动生成缺失字段**:
+
+   ```python
+   # 如果缺少 id，使用 name 作为 id
+   if "id" not in content:
+       content["id"] = content["name"]
+
+   # 如果缺少 uuid，自动生成
+   if "uuid" not in content:
+       content["uuid"] = str(uuid.uuid4())
+   ```
+
+2. **Position 格式转换**:
+
+   ```python
+   # 旧格式：简单的 x/y 坐标
+   "position": {"x": 100, "y": 200}
+
+   # 自动转换为新格式
+   "position": {
+       "position": {"x": 100, "y": 200}
+   }
+   ```
+
+3. **默认值填充**:
+
+   ```python
+   # 自动填充空字段
+   if not content.get("class"):
+       content["class"] = ""
+   if not content.get("config"):
+       content["config"] = {}
+   if not content.get("data"):
+       content["data"] = {}
+   if not content.get("extra"):
+       content["extra"] = {}
+   ```
+
+4. **Pose 字段同步**:
+   ```python
+   # 如果没有 pose，使用 position
+   if "pose" not in content:
+       content["pose"] = content.get("position", {})
+   ```
+
+### 使用示例
+
+```python
+from unilabos.resources.resource_tracker import ResourceDictInstance
+
+# 旧格式节点
+old_format_node = {
+    "name": "pump_1",
+    "type": "device",
+    "class": "syringepump",
+    "position": {"x": 100, "y": 200}
+}
+
+# 自动转换为标准格式
+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.config)  # {}
+print(instance.res_content.data)  # {}
+```
+
+### 格式迁移建议
+
+虽然系统会自动处理旧格式，但建议在新文件中使用完整的标准格式：
+
+| 字段   | 旧格式（兼容）                     | 新格式（推荐）                                   |
+| ------ | ---------------------------------- | ------------------------------------------------ |
+| 标识符 | 仅 `id` 或仅 `name`                | `id` + `uuid`                                    |
+| 位置   | `"position": {"x": 100, "y": 200}` | 完整的 `pose` 结构                               |
+| 父节点 | `"parent": "parent_id"`            | `"parent": "parent_id"` + `"parent_uuid": "..."` |
+| 配置   | 可省略                             | 显式设置为 `{}`                                  |
+| 数据   | 可省略                             | 显式设置为 `{}`                                  |
+
+## 节点类型详解
+
+### Device 节点
+
+设备节点代表实际的硬件设备：
+
+```json
+{
+  "id": "device_id",
+  "name": "设备名称",
+  "type": "device",
+  "class": "设备类别",
+  "parent": null,
+  "config": {
+    "port": "COM3"
+  },
+  "data": {},
+  "children": []
+}
+```
+
+**常见设备类别**:
+
+- `liquid_handler`: 液体处理工作站
+- `liquid_handler.prcxi`: PRCXI 液体处理工作站
+- `syringepump`: 注射泵
+- `syringepump.runze`: 润泽注射泵
+- `heaterstirrer`: 加热搅拌器
+- `balance`: 天平
+- `reactor_vessel`: 反应釜
+- `serial`: 串口通信设备
+- `workstation`: 自动化工作站
+
+### Resource 节点
+
+资源节点代表物料容器、载具等：
+
+```json
+{
+  "id": "resource_id",
+  "name": "资源名称",
+  "type": "resource",
+  "class": "资源类别",
+  "parent": "父节点ID",
+  "config": {
+    "size_x": 127.76,
+    "size_y": 85.48,
+    "size_z": 100
+  },
+  "data": {},
+  "children": []
+}
+```
+
+**常见资源类型**:
+
+- `deck`: 工作台/甲板
+- `plate`: 板（96 孔板等）
+- `tip_rack`: 枪头架
+- `tube`: 试管
+- `container`: 容器
+- `well`: 孔位
+- `bottle_carrier`: 瓶架
+
+## Handle（连接点）
+
+每个设备和资源可以有多个连接点（handles），用于定义可以连接的接口。
+
+### 查看可用 handles
+
+设备和资源的可用 handles 定义在注册表中：
+
+```yaml
+# 设备注册表示例
+liquid_handler:
+  handles:
+    - handler_key: pipette
+      io_type: source
+    - handler_key: deck
+      io_type: target
+```
+
+### 常见 handles
+
+| 设备类型   | Source Handles | Target Handles |
+| ---------- | -------------- | -------------- |
+| 泵         | output         | input          |
+| 反应釜     | output, vessel | input          |
+| 液体处理器 | pipette        | deck           |
+| 板         | wells          | access         |
+
+## 使用 Web 界面创建图文件
+
+Uni-Lab 提供 Web 界面来可视化创建和编辑设备图：
+
+### 1. 启动 Uni-Lab
+
+```bash
+unilab
+```
+
+### 2. 访问 Web 界面
+
+打开浏览器访问 `http://localhost:8002`
+
+### 3. 图形化编辑
+
+- 拖拽添加设备和资源
+- 连线建立连接关系
+- 编辑节点属性
+- 保存为 JSON 文件
+
+### 4. 导出图文件
+
+点击"导出"按钮，下载 JSON 文件到本地。
+
+## 从云端获取图文件
+
+如果不指定`-g`参数，Uni-Lab 会自动从云端获取：
+
+```bash
+# 使用云端配置
+unilab
+
+# 日志会显示:
+# [INFO] 未指定设备加载文件路径，尝试从HTTP获取...
+# [INFO] 联网获取设备加载文件成功
+```
+
+**云端图文件管理**:
+
+1. 登录 https://uni-lab.bohrium.com
+2. 进入"设备配置"
+3. 创建或编辑配置
+4. 保存到云端
+
+本地启动时会自动同步最新配置。
+
+## 调试图文件
+
+### 验证 JSON 格式
+
+```bash
+# 使用Python验证
+python -c "import json; json.load(open('workshop1.json'))"
+
+# 使用在线工具
+# https://jsonlint.com/
+```
+
+### 检查节点引用
+
+确保：
+
+- 所有`links`中的`source`和`target`都存在于`nodes`中
+- `parent`字段指向的节点存在
+- `class`字段对应的设备/资源在注册表中存在
+
+### 启动时验证
+
+```bash
+# Uni-Lab启动时会验证图文件
+unilab -g workshop1.json
+
+# 查看日志中的错误或警告
+# [ERROR] 节点 xxx 的source端点 yyy 不存在
+# [WARNING] 节点 zzz missing 'name', defaulting to ...
+```
+
+## 最佳实践
+
+### 1. 命名规范
+
+```json
+{
+  "id": "pump_reagent_1", // 小写+下划线，描述性
+  "name": "试剂进料泵A", // 中文显示名称
+  "class": "syringepump" // 使用注册表中的精确名称
+}
+```
+
+### 2. 层级组织
+
+```
+host_node (主节点)
+└── liquid_handler_1 (设备)
+    └── deck_1 (资源)
+        ├── tiprack_1 (资源)
+        ├── plate_1 (资源)
+        └── reservoir_1 (资源)
+```
+
+### 3. 配置分离
+
+将设备特定配置放在`config`中：
+
+```json
+{
+  "id": "pump_1",
+  "class": "syringepump",
+  "config": {
+    "port": "COM3", // 设备特定
+    "max_flow_rate": 10, // 设备特定
+    "volume": 50 // 设备特定
+  }
+}
+```
+
+### 4. 版本控制
+
+```bash
+# 使用Git管理图文件
+git add workshop1.json
+git commit -m "Add new liquid handler configuration"
+
+# 使用有意义的文件名
+workshop_v1.json
+workshop_production.json
+workshop_test.json
+```
+
+### 5. 注释（通过描述字段）
+
+虽然 JSON 不支持注释，但可以使用`description`字段：
+
+```json
+{
+  "id": "pump_1",
+  "name": "进料泵",
+  "description": "用于精确控制试剂A的加料速率，最大流速10mL/min",
+  "class": "syringepump"
+}
+```
+
+## 示例文件位置
+
+Uni-Lab 在安装时已预置了 **40+ 个真实的设备图文件示例**，位于 `unilabos/test/experiments/` 目录。这些都是真实项目中使用的配置文件，可以直接使用或作为参考。
+
+### 📁 主要示例文件
+
+```
+test/experiments/
+├── workshop.json                                 # 综合工作台（推荐新手）
+├── empty_devices.json                            # 空设备配置（最小化）
+├── prcxi_9300.json                               # PRCXI液体处理工作站（本文示例1）
+├── prcxi_9320.json                               # PRCXI 9320工作站
+├── biomek.json                                   # Biomek液体处理工作站
+├── Grignard_flow_batchreact_single_pumpvalve.json # 格林纳德反应工作站（本文示例2）
+├── dispensing_station_bioyond.json               # Bioyond配液站
+├── reaction_station_bioyond.json                 # Bioyond反应站
+├── HPLC.json                                     # HPLC分析系统
+├── plr_test.json                                 # PyLabRobot测试配置
+├── lidocaine-graph.json                          # 利多卡因合成工作站
+├── opcua_example.json                            # OPC UA设备集成示例
+│
+├── mock_devices/                                 # 虚拟设备（用于离线测试）
+│   ├── mock_all.json                             # 完整虚拟设备集
+│   ├── mock_pump.json                            # 虚拟泵
+│   ├── mock_stirrer.json                         # 虚拟搅拌器
+│   ├── mock_heater.json                          # 虚拟加热器
+│   └── ...                                       # 更多虚拟设备
+│
+├── Protocol_Test_Station/                        # 协议测试工作站
+│   ├── pumptransfer_test_station.json            # 泵转移协议测试
+│   ├── heatchill_protocol_test_station.json      # 加热冷却协议测试
+│   ├── filter_protocol_test_station.json         # 过滤协议测试
+│   └── ...                                       # 更多协议测试
+│
+└── comprehensive_protocol/                       # 综合协议示例
+    ├── comprehensive_station.json                # 综合工作站
+    └── comprehensive_slim.json                   # 精简版综合工作站
+```
+
+### 🚀 快速使用
+
+无需下载或创建，直接使用 `-g` 参数指定路径：
+
+```bash
+# 使用简单工作台（推荐新手）
+unilab --ak your_ak --sk your_sk -g test/experiments/workshop.json
+
+# 使用虚拟设备（无需真实硬件）
+unilab --ak your_ak --sk your_sk -g test/experiments/mock_devices/mock_all.json
+
+# 使用 PRCXI 液体处理工作站
+unilab --ak your_ak --sk your_sk -g test/experiments/prcxi_9300.json
+
+# 使用格林纳德反应工作站
+unilab --ak your_ak --sk your_sk -g test/experiments/Grignard_flow_batchreact_single_pumpvalve.json
+```
+
+### 📚 文件分类
+
+| 类别         | 说明                     | 文件数量 |
+| ------------ | ------------------------ | -------- |
+| **主工作站** | 完整的实验工作站配置     | 15+      |
+| **虚拟设备** | 用于开发测试的 mock 设备 | 10+      |
+| **协议测试** | 各种实验协议的测试配置   | 12+      |
+| **综合示例** | 包含多种协议的综合工作站 | 3+       |
+
+这些文件展示了不同场景下的设备图配置，涵盖液体处理、有机合成、分析检测等多个领域，是学习和创建自己配置的绝佳参考。
+
+## 快速参考：ResourceDict 完整字段列表
+
+基于 `unilabos.ros.nodes.resource_tracker.ResourceDict` 的完整字段定义：
+
+```python
+class ResourceDict(BaseModel):
+    # === 基础标识 ===
+    id: str                          # 资源ID（必需）
+    uuid: str                        # 全局唯一标识符（自动生成）
+    name: str                        # 显示名称（必需）
+
+    # === 类型和分类 ===
+    type: Union[Literal["device"], str]  # 节点类型（必需）
+    klass: str                       # 资源类别（alias="class"，必需）
+
+    # === 层级关系 ===
+    parent: Optional[ResourceDict]   # 父资源对象（不序列化）
+    parent_uuid: Optional[str]       # 父资源UUID
+
+    # === 位置和姿态 ===
+    position: ResourceDictPosition   # 位置信息
+    pose: ResourceDictPosition       # 姿态信息（推荐使用）
+
+    # === 配置和数据 ===
+    config: Dict[str, Any]           # 设备配置参数
+    data: Dict[str, Any]             # 运行时状态数据
+    extra: Dict[str, Any]            # 额外自定义数据
+
+    # === 元数据 ===
+    description: str                 # 资源描述
+    resource_schema: Dict[str, Any]  # schema定义（alias="schema"）
+    model: Dict[str, Any]            # 3D模型信息
+    icon: str                        # 图标路径
+```
+
+**Position/Pose 结构**:
+
+```python
+class ResourceDictPosition(BaseModel):
+    size: ResourceDictPositionSize           # width, height, depth
+    scale: ResourceDictPositionScale         # x, y, z
+    layout: Literal["2d", "x-y", "z-y", "x-z"]
+    position: ResourceDictPositionObject     # x, y, z
+    position3d: ResourceDictPositionObject   # x, y, z
+    rotation: ResourceDictPositionObject     # x, y, z
+    cross_section_type: Literal["rectangle", "circle", "rounded_rectangle"]
+```
+
+## 下一步
+
+- {doc}`../boot_examples/index` - 查看完整启动示例
+- {doc}`../developer_guide/add_device` - 了解如何添加新设备
+- {doc}`06_troubleshooting` - 图文件相关问题排查
+- 源码参考: `unilabos/ros/nodes/resource_tracker.py` - ResourceDict 标准定义
+
+## 获取帮助
+
+- 在 Web 界面中使用模板创建
+- 参考示例文件：`test/experiments/` 目录
+- 查看 ResourceDict 源码了解完整定义
+- [GitHub 讨论区](https://github.com/deepmodeling/Uni-Lab-OS/discussions)
--- a/docs/user_guide/image/test_latency_result.png
+++ b/docs/user_guide/image/test_latency_result.png
--- a/docs/user_guide/image/test_latency_running.png
+++ b/docs/user_guide/image/test_latency_running.png
--- a/docs/user_guide/image/test_latency_select_device.png
+++ b/docs/user_guide/image/test_latency_select_device.png
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -1,43 +1,516 @@
-# **Uni-Lab 安装**
+# Uni-Lab-OS 安装指南

-## 快速开始
+本指南提供 Uni-Lab-OS 的完整安装说明，涵盖从快速一键安装到完整开发环境配置的所有方式。

-1. **配置 Conda 环境**
+## 系统要求

-Uni-Lab-OS 建议使用 `mamba` 管理环境。创建新的环境：
+- **操作系统**: Windows 10/11, Linux (Ubuntu 20.04+), macOS (10.15+)
+- **内存**: 最小 4GB，推荐 8GB 以上
+- **磁盘空间**: 至少 10GB 可用空间
+- **网络**: 稳定的互联网连接（用于下载软件包）
+- **其他**:
+  - 已安装 Conda/Miniconda/Miniforge/Mamba
+  - 开发者需要 Git 和基本的 Python 开发知识
+  - 自定义 msgs 需要 GitHub 账号

-```shell
+## 安装方式选择
+
+根据您的使用场景，选择合适的安装方式：
+
+| 安装方式               | 适用人群             | 特点                           | 安装时间                     |
+| ---------------------- | -------------------- | ------------------------------ | ---------------------------- |
+| **方式一：一键安装**   | 实验室用户、快速体验 | 预打包环境，离线可用，无需配置 | 5-10 分钟 (网络良好的情况下) |
+| **方式二：手动安装**   | 标准用户、生产环境   | 灵活配置，版本可控             | 10-20 分钟                   |
+| **方式三：开发者安装** | 开发者、需要修改源码 | 可编辑模式，支持自定义 msgs    | 20-30 分钟                   |
+
+---
+
+## 方式一：一键安装（推荐新用户）
+
+使用预打包的 conda 环境，最快速的安装方法。
+
+### 前置条件
+
+确保已安装 Conda/Miniconda/Miniforge/Mamba。
+
+### 安装步骤
+
+#### 第一步：下载预打包环境
+
+1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/deepmodeling/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
+
+2. 选择最新的成功构建记录（绿色勾号 ✓）
+
+3. 在页面底部的 "Artifacts" 部分，下载对应你操作系统的压缩包：
+   - Windows: `unilab-pack-win-64-{branch}.zip`
+   - macOS (Intel): `unilab-pack-osx-64-{branch}.tar.gz`
+   - macOS (Apple Silicon): `unilab-pack-osx-arm64-{branch}.tar.gz`
+   - Linux: `unilab-pack-linux-64-{branch}.tar.gz`
+
+#### 第二步：解压并运行安装脚本
+
+**Windows**:
+
+```batch
+REM 使用 Windows 资源管理器解压下载的 zip 文件
+REM 或使用命令行：
+tar -xzf unilab-pack-win-64-dev.zip
+
+REM 进入解压后的目录
+cd unilab-pack-win-64-dev
+
+REM 双击运行 install_unilab.bat
+REM 或在命令行中执行：
+install_unilab.bat
+```
+
+**macOS**:
+
+```bash
+# 解压下载的压缩包
+tar -xzf unilab-pack-osx-arm64-dev.tar.gz
+
+# 进入解压后的目录
+cd unilab-pack-osx-arm64-dev
+
+# 运行安装脚本
+bash install_unilab.sh
+```
+
+**Linux**:
+
+```bash
+# 解压下载的压缩包
+tar -xzf unilab-pack-linux-64-dev.tar.gz
+
+# 进入解压后的目录
+cd unilab-pack-linux-64-dev
+
+# 添加执行权限（如果需要）
+chmod +x install_unilab.sh
+
+# 运行安装脚本
+./install_unilab.sh
+```
+
+#### 第三步：激活环境
+
+```bash
+conda activate unilab
+```
+
+激活后，您的命令行提示符应该会显示 `(unilab)` 前缀。
+
+---
+
+## 方式二：手动安装（标准用户）
+
+适合生产环境和需要灵活配置的用户。
+
+### 第一步：安装 Mamba 环境管理器
+
+Mamba 是 Conda 的快速替代品，我们强烈推荐使用 Mamba 来管理 Uni-Lab 环境。
+
+#### Windows
+
+下载并安装 Miniforge（包含 Mamba）:
+
+```powershell
+# 访问 https://github.com/conda-forge/miniforge/releases
+# 下载 Miniforge3-Windows-x86_64.exe
+# 运行安装程序
+
+# 也可以使用镜像站 https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/
+# 下载 Miniforge3-Windows-x86_64.exe
+# 运行安装程序
+```
+
+#### Linux/macOS
+
+```bash
+# 下载 Miniforge 安装脚本
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+
+# 运行安装
+bash Miniforge3-$(uname)-$(uname -m).sh
+
+# 按照提示完成安装，建议选择 yes 来初始化
+```
+
+安装完成后，重新打开终端使 Mamba 生效。
+
+### 第二步：创建 Uni-Lab 环境
+
+使用以下命令创建 Uni-Lab 专用环境：
+
+```bash
+mamba create -n unilab python=3.11.11  # 目前ros2组件依赖版本大多为3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+```
+
+**参数说明**:
+
+- `-n unilab`: 创建名为 "unilab" 的环境
+- `uni-lab::unilabos`: 从 uni-lab channel 安装 unilabos 包
+- `-c robostack-staging -c conda-forge`: 添加额外的软件源
+
+**如果遇到网络问题**，可以使用清华镜像源加速下载：
+
+```bash
+# 配置清华镜像源
+mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
+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
+```
+
+### 第三步：激活环境
+
+```bash
+conda activate unilab
+```
+
+---
+
+## 方式三：开发者安装
+
+适用于需要修改 Uni-Lab 源代码或开发新设备驱动的开发者。
+
+### 前置条件
+
+- 已安装 Git
+- 已安装 Mamba/Conda
+- 有 GitHub 账号（如需自定义 msgs）
+- 基本的 Python 开发知识
+
+### 第一步：克隆仓库
+
+```bash
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
+cd Uni-Lab-OS
+```
+
+如果您需要贡献代码，建议先 Fork 仓库：
+
+1. 访问 https://github.com/deepmodeling/Uni-Lab-OS
+2. 点击右上角的 "Fork" 按钮
+3. Clone 您的 Fork 版本：
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Uni-Lab-OS.git
+   cd Uni-Lab-OS
+   ```
+
+### 第二步：安装基础环境
+
+**推荐方式**：先通过**方式一（一键安装）**或**方式二（手动安装）**完成基础环境的安装，这将包含所有必需的依赖项（ROS2、msgs 等）。
+
+#### 选项 A：通过一键安装（推荐）
+
+参考上文"方式一：一键安装"，完成基础环境的安装后，激活环境：
+
+```bash
+conda activate unilab
+```
+
+#### 选项 B：通过手动安装
+
+参考上文"方式二：手动安装"，创建并安装环境：
+
+```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/deepmodeling/Uni-Lab-OS.git
+# 或者如果已经克隆，切换到 dev 分支
+cd Uni-Lab-OS
+git checkout dev
+git pull
+
+# 以可编辑模式安装开发版 unilabos
+pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+```
+
+**参数说明**：
+
+- `-e`: editable mode（可编辑模式），代码修改立即生效，无需重新安装
+- `-i`: 使用清华镜像源加速下载
+- `pip uninstall unilabos`: 只卸载 pip 安装的 unilabos 包，不影响 conda 安装的其他依赖（如 ROS2、msgs 等）
+
+### 第四步：安装或自定义 ros-humble-unilabos-msgs（可选）
+
+Uni-Lab 使用 ROS2 消息系统进行设备间通信。如果你使用方式一或方式二安装，msgs 包已经自动安装。
+
+#### 使用已安装的 msgs（大多数用户）
+
+如果你不需要修改 msgs，可以跳过此步骤，直接使用已安装的 msgs 包。验证安装：
+
+```bash
+# 列出所有 unilabos_msgs 接口
+ros2 interface list | grep unilabos_msgs
+
+# 查看特定 action 定义
+ros2 interface show unilabos_msgs/action/DeviceCmd
+```
+
+#### 自定义 msgs（高级用户）
+
+如果你需要：
+
+- 添加新的 ROS2 action 定义
+- 修改现有 msg/srv/action 接口
+- 为特定设备定制通信协议
+
+请参考 **[添加新动作指令（Action）指南](../developer_guide/add_action.md)**，该指南详细介绍了如何：
+
+- 编写新的 Action 定义
+- 在线构建 Action（通过 GitHub Actions）
+- 下载并安装自定义的 msgs 包
+- 测试和验证新的 Action
+
+```bash
+# 安装自定义构建的 msgs 包
+mamba remove --force ros-humble-unilabos-msgs
+mamba config set safety_checks disabled  # 关闭 md5 检查
+mamba install /path/to/ros-humble-unilabos-msgs-*.conda --offline
+```
+
+### 第五步：验证开发环境
+
+完成上述步骤后，验证开发环境是否正确配置：
+
+```bash
+# 确保环境已激活
+conda activate unilab
+
+# 检查 ROS2 环境
+ros2 --version
+
+# 检查 msgs 包
+ros2 interface list | grep unilabos_msgs
+
+# 检查 Python 可以导入 unilabos
+python -c "import unilabos; print(f'Uni-Lab版本: {unilabos.__version__}')"
+
+# 检查 unilab 命令
+unilab --help
+```
+
+如果所有命令都正常输出，说明开发环境配置成功！
+
+---
+
+## 验证安装
+
+无论使用哪种安装方式，都应该验证安装是否成功。
+
+### 基本验证
+
+```bash
+# 确保已激活环境
+conda activate unilab  # 或 unilab-dev
+
+# 检查 unilab 命令
+unilab --help
+```
+
+您应该看到类似以下的输出：
+
+```
+usage: unilab [-h] [-g GRAPH] [-c CONTROLLERS] [--registry_path REGISTRY_PATH]
+              [--working_dir WORKING_DIR] [--backend {ros,simple,automancer}]
+              ...
+```
+
+### 检查版本
+
+```bash
+python -c "import unilabos; print(f'Uni-Lab版本: {unilabos.__version__}')"
+```
+
+### 使用验证脚本（方式一）
+
+如果使用一键安装，可以运行预打包的验证脚本：
+
+```bash
+# 确保已激活环境
+conda activate unilab
+
+# 运行验证脚本
+python verify_installation.py
+```
+
+如果看到 "✓ All checks passed!"，说明安装成功！
+
+---
+
+## 常见问题
+
+### 问题 1: 找不到 unilab 命令
+
+**原因**: 环境未正确激活或 PATH 未设置
+
+**解决方案**:
+
+```bash
+# 确保激活了正确的环境
+conda activate unilab
+
+# 检查 unilab 是否在 PATH 中
+which unilab  # Linux/macOS
+where unilab  # Windows
+```
+
+### 问题 2: 包冲突或依赖错误
+
+**解决方案**:
+
+```bash
+# 删除旧环境重新创建
+conda deactivate
+conda env remove -n unilab
 mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```

-2. **安装开发版 Uni-Lab-OS**
+### 问题 3: 下载速度慢

-```shell
-# 配置好conda环境后，克隆仓库
-git clone https://github.com/dptech-corp/Uni-Lab-OS.git -b dev
-cd Uni-Lab-OS
+**解决方案**: 使用国内镜像源（清华、中科大等）

-# 安装 Uni-Lab-OS
-pip install -e .
+```bash
+# 查看当前 channel 配置
+conda config --show channels
+
+# 添加清华镜像
+conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
 ```

-3. **安装开发版 ros-humble-unilabos-msgs**
+### 问题 4: 权限错误

-**卸载老版本：**
-```shell
+**Windows 解决方案**: 以管理员身份运行命令提示符
+
+**Linux/macOS 解决方案**:
+
+```bash
+# 不要使用 sudo 安装 conda 包
+# 如果 conda 安装在需要权限的位置，考虑重新安装 conda 到用户目录
+```
+
+### 问题 5: 安装脚本找不到 conda（方式一）
+
+**解决方案**: 确保你已经安装了 conda/miniconda/miniforge，并且安装在标准位置：
+
+- **Windows**:
+
+  - `%USERPROFILE%\miniforge3`
+  - `%USERPROFILE%\miniconda3`
+  - `%USERPROFILE%\anaconda3`
+  - `C:\ProgramData\miniforge3`
+
+- **macOS/Linux**:
+  - `~/miniforge3`
+  - `~/miniconda3`
+  - `~/anaconda3`
+  - `/opt/conda`
+
+如果安装在其他位置，可以先激活 conda base 环境，然后手动运行安装脚本。
+
+### 问题 6: 安装后激活环境提示找不到？
+
+**解决方案**: 尝试以下方法：
+
+```bash
+# 方法 1: 使用 conda activate
 conda activate unilab
-conda remove --force ros-humble-unilabos-msgs
-```
-有时相同的安装包版本会由于dev构建得到的md5不一样，触发安全检查，可输入 `config set safety_checks disabled` 来关闭安全检查。

-**安装新版本：**
+# 方法 2: 使用完整路径激活（Windows）
+call C:\Users\{YourUsername}\miniforge3\envs\unilab\Scripts\activate.bat

-访问 https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/multi-platform-build.yml 选择最新的构建，下载对应平台的压缩包（仅解压一次，得到.conda文件）使用如下指令：
-```shell
-conda activate base
-conda install ros-humble-unilabos-msgs-<version>-<platform>.conda --offline -n <环境名>
+# 方法 2: 使用完整路径激活（Unix）
+source ~/miniforge3/envs/unilab/bin/activate
 ```

-4. **启动 Uni-Lab 系统**
+### 问题 7: conda-unpack 失败怎么办？（方式一）

-请参见{doc}`启动样例 <../boot_examples/index>`或{doc}`启动指南 <launch>`了解详细的启动方法。
+**解决方案**: 尝试手动运行：
+
+```bash
+# Windows
+cd %CONDA_PREFIX%\envs\unilab
+.\Scripts\conda-unpack.exe
+
+# macOS/Linux
+cd $CONDA_PREFIX/envs/unilab
+./bin/conda-unpack
+```
+
+### 问题 8: 环境很大，有办法减小吗？
+
+**解决方案**: 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用方式二手动安装，只安装需要的组件。
+
+### 问题 9: 如何更新到最新版本？
+
+**解决方案**:
+
+**方式一用户**: 重新下载最新的预打包环境，运行安装脚本时选择覆盖现有环境。
+
+**方式二/三用户**: 在现有环境中更新：
+
+```bash
+conda activate unilab
+
+# 更新 unilabos
+cd /path/to/Uni-Lab-OS
+git pull
+pip install -e . --upgrade -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+
+# 更新 ros-humble-unilabos-msgs
+mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge
+```
+
+---
+
+## 下一步
+
+安装完成后，请继续：
+
+- **快速启动**: 学习如何首次启动 Uni-Lab
+- **配置指南**: 配置您的实验室环境和设备
+- **运行示例**: 查看启动示例和最佳实践
+- **开发指南**:
+  - 添加新设备驱动
+  - 添加新物料资源
+  - 了解工作站架构
+
+## 需要帮助？
+
+- **故障排查**: 查看更详细的故障排查信息
+- **GitHub Issues**: [报告问题](https://github.com/deepmodeling/Uni-Lab-OS/issues)
+- **开发者文档**: 查看开发者指南获取更多技术细节
+- **社区讨论**: [GitHub Discussions](https://github.com/deepmodeling/Uni-Lab-OS/discussions)
+
+---
+
+**提示**:
+
+- 生产环境推荐使用方式二（手动安装）的稳定版本
+- 开发和测试推荐使用方式三（开发者安装）
+- 快速体验和演示推荐使用方式一（一键安装）
--- a/docs/user_guide/launch.md
+++ b/docs/user_guide/launch.md
@@ -132,15 +132,14 @@ unilab --config path/to/your/config.py

 使用 `-c` 传入控制逻辑配置。

-不管使用哪一种初始化方式，设备/物料字典均需包含 `class` 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 `unilabos/registry/{devices,device_comms,resources}`。要添加额外的注册表路径，可以使用 `--registry_path` 加入 `<your-registry-path>/{devices,device_comms,resources}`。
+不管使用哪一种初始化方式，设备/物料字典均需包含 `class` 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 `unilabos/registry/{devices,device_comms,resources}`。要添加额外的注册表路径，可以使用 `--registry_path` 加入 `<your-registry-path>/{devices,device_comms,resources}`，只输入<your-registry-path>即可，支持多次--registry_path指定多个目录。

 ## 通信中间件 `--backend`

 目前 Uni-Lab 支持以下通信中间件：

 - **ros** (默认)：基于 ROS2 的通信
- **simple**：简化通信模式
- **automancer**：Automancer 兼容模式
+- **automancer**：Automancer 兼容模式 (实验性)

 ## 端云桥接 `--app_bridges`

@@ -169,7 +168,7 @@ unilab --config path/to/your/config.py
 通过 `--visual` 参数选择：

 - **rviz**：使用 RViz 进行 3D 可视化
- **web**：使用 Web 界面进行可视化
+- **web**：使用 Web 界面进行可视化 (基于Pylabrobot)
 - **disable** (默认)：禁用可视化

 ## 实验室管理
@@ -245,78 +244,3 @@ unilab --ak your_ak --sk your_sk --port 8080 --disable_browser
 - 检查图谱文件格式是否正确
 - 验证设备连接和端点配置
 - 确保注册表路径正确
-
-## 页面操作
-
-### 1. 启动成功
-当您启动成功后，可以看到物料列表，节点模版和组态图如图展示
-![material.png](image/material.png)
-
-### 2. 根据需求创建设备和物料
-我们可以做一个简单的案例  
-* 在容器1中加入水  
-* 通过传输泵将容器1中的水转移到容器2中
-#### 2.1 添加所需的设备和物料  
-仪器设备work_station中的workstation 数量x1  
-仪器设备virtual_device中的virtual_transfer_pump 数量x1    
-物料耗材container中的container 数量x2  
-
-#### 2.2 将设备和物料根据父子关系进行关联  
-当我们添加设备时，仪器耗材模块的物料列表也会实时更新  
-我们需要将设备和物料拖拽到workstation中并在画布上将它们连接起来，就像真实的设备操作一样  
-![links.png](image/links.png)
-
-### 3. 创建工作流
-进入工作流模块 → 点击"我创建的" → 新建工作流
-![new.png](image/new.png)
-
-#### 3.1 新增工作流节点
-我们可以进入指定工作流，在空白处右键   
-* 选择Laboratory→host_node中的creat_resource
-* 选择Laboratory→workstation中的PumpTransferProtocol
-
-![creatworkfollow.gif](image/creatworkfollow.gif)
-
-#### 3.2 配置节点参数
-根据案例，工作流包含两个步骤：
-1. 使用creat_resource在容器中创建水
-2. 通过泵传输协议将水传输到另一个容器
-
-我们点击creat_resource卡片上的编辑按钮来配置参数⭐️  
-class_name ：container  
-device_id ： workstation  
-liquid_input_slot ： 0或-1均可  
-liquid_type : water  
-liquid_volume ： 根据需求填写即可，默认单位ml，这里举例50    
-parent ： workstation  
-res_id ： containe  
-关联设备名称(原unilabos_device_id) ： 这里就填写host_node  
-**配置完成后点击底部保存按钮**  
-
-我们点击PumpTransferProtocol卡片上的编辑按钮来配置参数⭐️  
-event ： transfer_liquid  
-from_vessel ： water  
-to_vessel ： container1  
-volume ： 根据需求填写即可，默认单位ml，这里举例50  
-关联设备名称(原unilabos_device_id) ： 这里就填写workstation  
-**配置完成后点击底部保存按钮**  
-
-#### 3.3 运行工作流
-1. 连接两个节点卡片
-2. 点击底部保存按钮
-3. 点击运行按钮执行工作流
-
-![linksandrun.png](image/linksandrun.png)
-
-### 运行监控
-* 运行状态和消息实时显示在底部控制台
-* 如有报错，可点击查看详细信息
-
-### 结果验证
-工作流完成后，返回仪器耗材模块：
-* 点击 container1卡片查看详情
-* 确认其中包含参数指定的水和容量
-
-
-
-
--- a/docs/user_guide/quick_install_guide.md
+++ b/docs/user_guide/quick_install_guide.md
@@ -1,197 +0,0 @@
-# Uni-Lab-OS 一键安装快速指南
-
-## 概述
-
-本指南提供最快速的 Uni-Lab-OS 安装方法，使用预打包的 conda 环境，无需手动配置依赖。
-
-## 前置要求
-
- 已安装 Conda/Miniconda/Miniforge/Mamba
- 至少 10GB 可用磁盘空间
- Windows 10+, macOS 10.14+, 或 Linux (Ubuntu 20.04+)
-
-## 安装步骤
-
-### 第一步：下载预打包环境
-
-1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
-
-2. 选择最新的成功构建记录（绿色勾号 ✓）
-
-3. 在页面底部的 "Artifacts" 部分，下载对应你操作系统的压缩包：
-   - Windows: `unilab-pack-win-64-{branch}.zip`
-   - macOS (Intel): `unilab-pack-osx-64-{branch}.tar.gz`
-   - macOS (Apple Silicon): `unilab-pack-osx-arm64-{branch}.tar.gz`
-   - Linux: `unilab-pack-linux-64-{branch}.tar.gz`
-
-### 第二步：解压并运行安装脚本
-
-#### Windows
-
-```batch
-REM 使用 Windows 资源管理器解压下载的 zip 文件
-REM 或使用命令行：
-tar -xzf unilab-pack-win-64-dev.zip
-
-REM 进入解压后的目录
-cd unilab-pack-win-64-dev
-
-REM 双击运行 install_unilab.bat
-REM 或在命令行中执行：
-install_unilab.bat
-```
-
-#### macOS
-
-```bash
-# 解压下载的压缩包
-tar -xzf unilab-pack-osx-arm64-dev.tar.gz
-
-# 进入解压后的目录
-cd unilab-pack-osx-arm64-dev
-
-# 运行安装脚本
-bash install_unilab.sh
-```
-
-#### Linux
-
-```bash
-# 解压下载的压缩包
-tar -xzf unilab-pack-linux-64-dev.tar.gz
-
-# 进入解压后的目录
-cd unilab-pack-linux-64-dev
-
-# 添加执行权限（如果需要）
-chmod +x install_unilab.sh
-
-# 运行安装脚本
-./install_unilab.sh
-```
-
-### 第三步：激活环境
-
-```bash
-conda activate unilab
-```
-
-### 第四步：验证安装（推荐）
-
-```bash
-# 确保已激活环境
-conda activate unilab
-
-# 运行验证脚本
-python verify_installation.py
-```
-
-如果看到 "✓ All checks passed!"，说明安装成功！
-
-## 常见问题
-
-### Q: 安装脚本找不到 conda？
-
-**A:** 确保你已经安装了 conda/miniconda/miniforge，并且安装在标准位置：
-
- **Windows**:
-
-  - `%USERPROFILE%\miniforge3`
-  - `%USERPROFILE%\miniconda3`
-  - `%USERPROFILE%\anaconda3`
-  - `C:\ProgramData\miniforge3`
-
- **macOS/Linux**:
-  - `~/miniforge3`
-  - `~/miniconda3`
-  - `~/anaconda3`
-  - `/opt/conda`
-
-如果安装在其他位置，可以先激活 conda base 环境，然后手动运行安装脚本。
-
-### Q: 安装后激活环境提示找不到？
-
-**A:** 尝试以下方法：
-
-```bash
-# 方法 1: 使用 conda activate
-conda activate unilab
-
-# 方法 2: 使用完整路径激活（Windows）
-call C:\Users\{YourUsername}\miniforge3\envs\unilab\Scripts\activate.bat
-
-# 方法 2: 使用完整路径激活（Unix）
-source ~/miniforge3/envs/unilab/bin/activate
-```
-
-### Q: conda-unpack 失败怎么办？
-
-**A:** 尝试手动运行：
-
-```bash
-# Windows
-cd %CONDA_PREFIX%\envs\unilab
-.\Scripts\conda-unpack.exe
-
-# macOS/Linux
-cd $CONDA_PREFIX/envs/unilab
-./bin/conda-unpack
-```
-
-### Q: 验证脚本报错？
-
-**A:** 首先确认环境已激活：
-
-```bash
-# 检查当前环境
-conda env list
-
-# 应该看到 unilab 前面有 * 标记
-```
-
-如果仍有问题，查看具体报错信息，可能需要：
-
- 重新运行安装脚本
- 检查磁盘空间
- 查看详细文档
-
-### Q: 环境很大，有办法减小吗？
-
-**A:** 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用手动安装方式，只安装需要的组件。
-
-### Q: 如何更新到最新版本？
-
-**A:** 重新下载最新的预打包环境，运行安装脚本时选择覆盖现有环境。
-
-或者在现有环境中更新：
-
-```bash
-conda activate unilab
-
-# 更新 unilabos
-cd /path/to/Uni-Lab-OS
-git pull
-pip install -e . --upgrade
-
-# 更新 ros-humble-unilabos-msgs
-mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge
-```
-
-## 下一步
-
-安装完成后，你可以：
-
-1. **查看启动指南**: {doc}`launch`
-2. **运行示例**: {doc}`../boot_examples/index`
-3. **配置设备**: 编辑 `unilabos_data/startup_config.json`
-4. **阅读开发文档**: {doc}`../developer_guide/workstation_architecture`
-
-## 需要帮助？
-
- **文档**: [docs/user_guide/installation.md](installation.md)
- **问题反馈**: [GitHub Issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
- **开发版安装**: 参考 {doc}`installation` 的方式二
-
---
-
-**提示**: 这个预打包环境包含了从指定分支（通常是 `dev`）构建的最新代码。如果需要稳定版本，请使用方式二手动安装 release 版本。
--- a/recipes/msgs/recipe.yaml
+++ b/recipes/msgs/recipe.yaml
@@ -1,6 +1,6 @@
 package:
  name: ros-humble-unilabos-msgs
-  version: 0.10.10
+  version: 0.10.15
 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."

--- a/recipes/unilabos/recipe.yaml
+++ b/recipes/unilabos/recipe.yaml
@@ -1,6 +1,6 @@
 package:
  name: unilabos
-  version: "0.10.10"
+  version: "0.10.15"

 source:
  path: ../..
--- a/scripts/create_readme.py
+++ b/scripts/create_readme.py
@@ -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
--- a/scripts/workflow.py
+++ b/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(
--- a/setup.py
+++ b/setup.py
@@ -4,7 +4,7 @@ package_name = 'unilabos'

 setup(
    name=package_name,
-    version='0.10.10',
+    version='0.10.15',
    packages=find_packages(),
    include_package_data=True,
    install_requires=['setuptools'],
--- a/test/workflow/merge_workflow.py
+++ b/test/workflow/merge_workflow.py
@@ -1,94 +0,0 @@
-import json
-import sys
-from datetime import datetime
-from pathlib import Path
-
-ROOT_DIR = Path(__file__).resolve().parents[2]
-if str(ROOT_DIR) not in sys.path:
-    sys.path.insert(0, str(ROOT_DIR))
-
-import pytest
-
-from scripts.workflow import build_protocol_graph, draw_protocol_graph, draw_protocol_graph_with_ports
-
-
-ROOT_DIR = Path(__file__).resolve().parents[2]
-if str(ROOT_DIR) not in sys.path:
-    sys.path.insert(0, str(ROOT_DIR))
-
-
-def _normalize_steps(data):
-    normalized = []
-    for step in data:
-        action = step.get("action") or step.get("operation")
-        if not action:
-            continue
-        raw_params = step.get("parameters") or step.get("action_args") or {}
-        params = dict(raw_params)
-
-        if "source" in raw_params and "sources" not in raw_params:
-            params["sources"] = raw_params["source"]
-        if "target" in raw_params and "targets" not in raw_params:
-            params["targets"] = raw_params["target"]
-
-        description = step.get("description") or step.get("purpose")
-        step_dict = {"action": action, "parameters": params}
-        if description:
-            step_dict["description"] = description
-        normalized.append(step_dict)
-    return normalized
-
-
-def _normalize_labware(data):
-    labware = {}
-    for item in data:
-        reagent_name = item.get("reagent_name")
-        key = reagent_name or item.get("material_name") or item.get("name")
-        if not key:
-            continue
-        key = str(key)
-        idx = 1
-        original_key = key
-        while key in labware:
-            idx += 1
-            key = f"{original_key}_{idx}"
-
-        labware[key] = {
-            "slot": item.get("positions") or item.get("slot"),
-            "labware": item.get("material_name") or item.get("labware"),
-            "well": item.get("well", []),
-            "type": item.get("type", "reagent"),
-            "role": item.get("role", ""),
-            "name": key,
-        }
-    return labware
-
-
-@pytest.mark.parametrize("protocol_name", [
-    "example_bio",
-    # "bioyond_materials_liquidhandling_1",
-    "example_prcxi",
-])
-def test_build_protocol_graph(protocol_name):
-    data_path = Path(__file__).with_name(f"{protocol_name}.json")
-    with data_path.open("r", encoding="utf-8") as fp:
-        d = json.load(fp)
-
-    if "workflow" in d and "reagent" in d:
-        protocol_steps = d["workflow"]
-        labware_info = d["reagent"]
-    elif "steps_info" in d and "labware_info" in d:
-        protocol_steps = _normalize_steps(d["steps_info"])
-        labware_info = _normalize_labware(d["labware_info"])
-    else:
-        raise ValueError("Unsupported protocol format")
-
-    graph = build_protocol_graph(
-        labware_info=labware_info,
-        protocol_steps=protocol_steps,
-        workstation_name="PRCXi",
-    )
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
-    output_path = data_path.with_name(f"{protocol_name}_graph_{timestamp}.png")
-    draw_protocol_graph_with_ports(graph, str(output_path))
-    print(graph)
--- a/tests/init.py
+++ b/tests/init.py
@@ -0,0 +1,7 @@
+"""
+测试包根目录。
+
+让 `tests.*` 模块可以被正常 import（例如给 `unilabos` 下的测试入口使用）。
+"""
+
+
--- a/tests/devices/init.py
+++ b/tests/devices/init.py
@@ -0,0 +1 @@
+
--- a/tests/devices/liquid_handling/init.py
+++ b/tests/devices/liquid_handling/init.py
@@ -0,0 +1,5 @@
+"""
+液体处理设备相关测试。
+"""
+
+
--- a/tests/devices/liquid_handling/test_transfer_liquid.py
+++ b/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,
+            )
+        )
+
--- a/tests/resources/init.py
+++ b/tests/resources/init.py
--- a/tests/resources/bioyond_materials_liquidhandling_1.json
+++ b/tests/resources/bioyond_materials_liquidhandling_1.json
--- a/tests/resources/bioyond_materials_liquidhandling_2.json
+++ b/tests/resources/bioyond_materials_liquidhandling_2.json
--- a/tests/resources/bioyond_materials_reaction.json
+++ b/tests/resources/bioyond_materials_reaction.json
--- a/tests/resources/test_bottle_carrier.py
+++ b/tests/resources/test_bottle_carrier.py
--- a/tests/resources/test_converter_bioyond.py
+++ b/tests/resources/test_converter_bioyond.py
--- a/tests/resources/test_itemized_carrier.py
+++ b/tests/resources/test_itemized_carrier.py
--- a/tests/resources/test_resourcetreeset.py
+++ b/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
--- a/tests/ros/init.py
+++ b/tests/ros/init.py
--- a/tests/ros/msgs/init.py
+++ b/tests/ros/msgs/init.py
--- a/tests/ros/msgs/test_basic.py
+++ b/tests/ros/msgs/test_basic.py
--- a/tests/ros/msgs/test_conversion.py
+++ b/tests/ros/msgs/test_conversion.py
--- a/tests/ros/msgs/test_mapping.py
+++ b/tests/ros/msgs/test_mapping.py
--- a/tests/ros/msgs/test_runner.py
+++ b/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():
--- a/tests/workflow/init.py
+++ b/tests/workflow/init.py
--- a/tests/workflow/example_bio.json
+++ b/tests/workflow/example_bio.json
--- a/tests/workflow/example_bio_graph.png
+++ b/tests/workflow/example_bio_graph.png
--- a/tests/workflow/example_prcxi.json
+++ b/tests/workflow/example_prcxi.json
--- a/tests/workflow/example_prcxi_graph.png
+++ b/tests/workflow/example_prcxi_graph.png
--- a/tests/workflow/example_prcxi_graph_20251022_1359.png
+++ b/tests/workflow/example_prcxi_graph_20251022_1359.png
--- a/tests/workflow/merge_workflow.py
+++ b/tests/workflow/merge_workflow.py
@@ -0,0 +1,35 @@
+import sys
+from datetime import datetime
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+import pytest
+
+from unilabos.workflow.convert_from_json import (
+    convert_from_json,
+    normalize_steps as _normalize_steps,
+    normalize_labware as _normalize_labware,
+)
+from unilabos.workflow.common import draw_protocol_graph_with_ports
+
+
+@pytest.mark.parametrize(
+    "protocol_name",
+    [
+        "example_bio",
+        # "bioyond_materials_liquidhandling_1",
+        "example_prcxi",
+    ],
+)
+def test_build_protocol_graph(protocol_name):
+    data_path = Path(__file__).with_name(f"{protocol_name}.json")
+
+    graph = convert_from_json(data_path, workstation_name="PRCXi")
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+    output_path = data_path.with_name(f"{protocol_name}_graph_{timestamp}.png")
+    draw_protocol_graph_with_ports(graph, str(output_path))
+    print(graph)
--- a/unilabos/init.py
+++ b/unilabos/init.py
@@ -1 +1 @@
-__version__ = "0.10.10"
+__version__ = "0.10.15"
--- a/unilabos/app/backend.py
+++ b/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


--- a/unilabos/app/communication.py
+++ b/unilabos/app/communication.py
@@ -141,7 +141,7 @@ class CommunicationClientFactory:
        """
        if cls._client_cache is None:
            cls._client_cache = cls.create_client(protocol)
-            logger.info(f"[CommunicationFactory] Created {type(cls._client_cache).__name__} client")
+            logger.trace(f"[CommunicationFactory] Created {type(cls._client_cache).__name__} client")

        return cls._client_cache

--- a/unilabos/app/main.py
+++ b/unilabos/app/main.py
@@ -19,6 +19,12 @@ if unilabos_dir not in sys.path:

 from unilabos.utils.banner_print import print_status, print_unilab_banner
 from unilabos.config.config import load_config, BasicConfig, HTTPConfig
+from unilabos.app.utils import cleanup_for_restart
+
+# 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:
@@ -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(
@@ -105,7 +113,7 @@ def parse_args():
    parser.add_argument(
        "--port",
        type=int,
-        default=8002,
+        default=None,
        help="Port for web service information page",
    )
    parser.add_argument(
@@ -153,21 +161,59 @@ def parse_args():
        default=False,
        help="Complete registry information",
    )
+    parser.add_argument(
+        "--no_update_feedback",
+        action="store_true",
+        help="Disable sending update feedback to server",
+    )
+    # 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)",
+    )
    return parser


 def main():
    """主函数"""
    # 解析命令行参数
-    args = parse_args()
-    convert_argv_dashes_to_underscores(args)
-    args_dict = vars(args.parse_args())
+    parser = parse_args()
+    convert_argv_dashes_to_underscores(parser)
+    args = parser.parse_args()
+    args_dict = vars(args)

    # 环境检查 - 检查并自动安装必需的包 (可选)
    if not args_dict.get("skip_env_check", False):
        from unilabos.utils.environment_check import check_environment

-        print_status("正在进行环境依赖检查...", "info")
        if not check_environment(auto_install=True):
            print_status("环境检查失败，程序退出", "error")
            os._exit(1)
@@ -218,19 +264,20 @@ def main():

    if hasattr(BasicConfig, "log_level"):
        logger.info(f"Log level set to '{BasicConfig.log_level}' from config file.")
-        configure_logger(loglevel=BasicConfig.log_level)
+    configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)

-    if args_dict["addr"] == "test":
-        print_status("使用测试环境地址", "info")
-        HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
-    elif args_dict["addr"] == "uat":
-        print_status("使用uat环境地址", "info")
-        HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
-    elif args_dict["addr"] == "local":
-        print_status("使用本地环境地址", "info")
-        HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
-    else:
-        HTTPConfig.remote_addr = args_dict.get("addr", "")
+    if args.addr != parser.get_default("addr"):
+        if args.addr == "test":
+            print_status("使用测试环境地址", "info")
+            HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
+        elif args.addr == "uat":
+            print_status("使用uat环境地址", "info")
+            HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
+        elif args.addr == "local":
+            print_status("使用本地环境地址", "info")
+            HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
+        else:
+            HTTPConfig.remote_addr = args.addr

    # 设置BasicConfig参数
    if args_dict.get("ak", ""):
@@ -239,9 +286,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

@@ -252,10 +302,12 @@ def main():
        else:
            print_status("远程资源不存在，本地将进行首次上报！", "info")

-    BasicConfig.working_dir = working_dir
+    BasicConfig.port = args_dict["port"] if args_dict["port"] else BasicConfig.port
+    BasicConfig.disable_browser = args_dict["disable_browser"] or BasicConfig.disable_browser
    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.communication_protocol = "websocket"
    machine_name = os.popen("hostname").read().strip()
    machine_name = "".join([c if c.isalnum() or c == "_" else "_" for c in machine_name])
@@ -274,16 +326,38 @@ 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"]
+        args_dict["registry_path"], args_dict.get("complete_registry", False), BasicConfig.upload_registry
    )

+    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")
        os._exit(1)
@@ -291,7 +365,9 @@ def main():
    resource_tree_set: ResourceTreeSet
    resource_links: List[Dict[str, Any]]
    request_startup_json = http_client.request_startup_json()
-    if args_dict["graph"] is None:
+
+    file_path = args_dict.get("graph", BasicConfig.startup_json_path)
+    if file_path is None:
        if not request_startup_json:
            print_status(
                "未指定设备加载文件路径，尝试从HTTP获取失败，请检查网络或者使用-g参数指定设备加载文件路径", "error"
@@ -301,7 +377,11 @@ def main():
            print_status("联网获取设备加载文件成功", "info")
        graph, resource_tree_set, resource_links = read_node_link_json(request_startup_json)
    else:
-        file_path = args_dict["graph"]
+        if not os.path.isfile(file_path):
+            temp_file_path = os.path.abspath(str(os.path.join(__file__, "..", "..", file_path)))
+            if os.path.isfile(temp_file_path):
+                print_status(f"使用相对路径{temp_file_path}", "info")
+                file_path = temp_file_path
        if file_path.endswith(".json"):
            graph, resource_tree_set, resource_links = read_node_link_json(file_path)
        else:
@@ -319,6 +399,10 @@ def main():
    for ind, i in enumerate(resource_edge_info[::-1]):
        source_node: ResourceDict = nodes[i["source"]]
        target_node: ResourceDict = nodes[i["target"]]
+        if "sourceHandle" not in source_node:
+            continue
+        if "targetHandle" not in target_node:
+            continue
        source_handle = i["sourceHandle"]
        target_handle = i["targetHandle"]
        source_handler_keys = [
@@ -345,7 +429,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")

@@ -354,20 +438,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:
@@ -382,6 +452,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)
@@ -413,8 +484,8 @@ def main():
            server_thread = threading.Thread(
                target=start_server,
                kwargs=dict(
-                    open_browser=not args_dict["disable_browser"],
-                    port=args_dict["port"],
+                    open_browser=not BasicConfig.disable_browser,
+                    port=BasicConfig.port,
                ),
            )
            server_thread.start()
@@ -423,16 +494,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
@@ -440,15 +508,21 @@ def main():
                time.sleep(1)
        else:
            start_backend(**args_dict)
-            start_server(
+            restart_requested = start_server(
                open_browser=not args_dict["disable_browser"],
-                port=args_dict["port"],
+                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=args_dict["port"],
+            port=BasicConfig.port,
        )


--- a/unilabos/app/model.py
+++ b/unilabos/app/model.py
@@ -51,21 +51,25 @@ class Resp(BaseModel):
 class JobAddReq(BaseModel):
    device_id: str = Field(examples=["Gripper"], description="device id")
    action: str = Field(examples=["_execute_driver_command_async"], description="action name", default="")
-    action_type: str = Field(examples=["unilabos_msgs.action._str_single_input.StrSingleInput"], description="action name", default="")
-    action_args: dict = Field(examples=[{'string': 'string'}], description="action name", default="")
-    task_id: str = Field(examples=["task_id"], description="task uuid")
-    job_id: str = Field(examples=["job_id"], description="goal uuid")
-    node_id: str = Field(examples=["node_id"], description="node uuid")
-    server_info: dict = Field(examples=[{"send_timestamp": 1717000000.0}], description="server info")
+    action_type: str = Field(
+        examples=["unilabos_msgs.action._str_single_input.StrSingleInput"], description="action type", default=""
+    )
+    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="")
+    node_id: str = Field(examples=["node_id"], description="node uuid", default="")
+    server_info: dict = Field(
+        examples=[{"send_timestamp": 1717000000.0}],
+        description="server info (auto-generated if empty)",
+        default_factory=dict,
+    )

-    data: dict = Field(examples=[{"position": 30, "torque": 5, "action": "push_to"}], default={})
+    data: dict = Field(examples=[{"position": 30, "torque": 5, "action": "push_to"}], default_factory=dict)


 class JobStepFinishReq(BaseModel):
    token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
    data: dict = Field(
        examples=[
            {
@@ -83,9 +87,7 @@ class JobStepFinishReq(BaseModel):

 class JobPreintakeFinishReq(BaseModel):
    token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
    data: dict = Field(
        examples=[
            {
@@ -102,9 +104,7 @@ class JobPreintakeFinishReq(BaseModel):

 class JobFinishReq(BaseModel):
    token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
    data: dict = Field(
        examples=[
            {
@@ -133,6 +133,10 @@ class JobData(BaseModel):
        default=0,
        description="0:UNKNOWN, 1:ACCEPTED, 2:EXECUTING, 3:CANCELING, 4:SUCCEEDED, 5:CANCELED, 6:ABORTED",
    )
+    result: dict = Field(
+        default_factory=dict,
+        description="Job result data (available when status is SUCCEEDED/CANCELED/ABORTED)",
+    )


 class JobStatusResp(Resp):
--- a/unilabos/app/oss_upload.py
+++ b/unilabos/app/oss_upload.py
@@ -1,161 +1,158 @@
 import argparse
 import os
 import time
-from typing import Dict, Optional, Tuple
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional, Tuple, Union

 import requests

-from unilabos.config.config import OSSUploadConfig
+from unilabos.app.web.client import http_client, HTTPClient
+from unilabos.utils import logger


-def _init_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
-                process_key: str = "file-upload", device_id: str = "default",
-                expires_hours: int = 1) -> Tuple[bool, Dict]:
+def _get_oss_token(
+    filename: str,
+    driver_name: str = "default",
+    exp_type: str = "default",
+    client: Optional[HTTPClient] = None,
+) -> Tuple[bool, Dict]:
    """
-    初始化上传过程
+    获取OSS上传Token

    Args:
-        file_path: 本地文件路径
-        oss_path: OSS目标路径
-        filename: 文件名，如果为None则使用file_path的文件名
-        process_key: 处理键
-        device_id: 设备ID
-        expires_hours: 链接过期小时数
+        filename: 文件名
+        driver_name: 驱动名称
+        exp_type: 实验类型
+        client: HTTPClient实例，如果不提供则使用默认的http_client

    Returns:
-        (成功标志, 响应数据)
+        (成功标志, Token数据字典包含token/path/host/expires)
    """
-    if filename is None:
-        filename = os.path.basename(file_path)
+    # 使用提供的client或默认的http_client
+    if client is None:
+        client = http_client

-    # 构造初始化请求
-    url = f"{OSSUploadConfig.api_host}{OSSUploadConfig.init_endpoint}"
-    headers = {
-        "Authorization": OSSUploadConfig.authorization,
-        "Content-Type": "application/json"
-    }
+    # 构造scene参数: driver_name-exp_type
+    sub_path = f"{driver_name}-{exp_type}"

-    payload = {
-        "device_id": device_id,
-        "process_key": process_key,
-        "filename": filename,
-        "path": oss_path,
-        "expires_hours": expires_hours
-    }
+    # 构造请求URL，使用client的remote_addr（已包含/api/v1/）
+    url = f"{client.remote_addr}/applications/token"
+    params = {"sub_path": sub_path, "filename": filename, "scene": "job"}

    try:
-        response = requests.post(url, headers=headers, json=payload)
-        if response.status_code == 201:
-            result = response.json()
-            if result.get("code") == "10000":
-                return True, result.get("data", {})
+        logger.info(f"[OSS] 请求预签名URL: sub_path={sub_path}, filename={filename}")
+        response = requests.get(url, params=params, headers={"Authorization": f"Lab {client.auth}"}, timeout=10)

-        print(f"初始化上传失败: {response.status_code}, {response.text}")
+        if response.status_code == 200:
+            result = response.json()
+            if result.get("code") == 0:
+                data = result.get("data", {})
+
+                # 转换expires时间戳为可读格式
+                expires_timestamp = data.get("expires", 0)
+                expires_datetime = datetime.fromtimestamp(expires_timestamp)
+                expires_str = expires_datetime.strftime("%Y-%m-%d %H:%M:%S")
+
+                logger.info(f"[OSS] 获取预签名URL成功")
+                logger.info(f"[OSS]   - URL: {data.get('url', 'N/A')}")
+                logger.info(f"[OSS]   - Expires: {expires_str} (timestamp: {expires_timestamp})")
+
+                return True, data
+
+        logger.error(f"[OSS] 获取预签名URL失败: {response.status_code}, {response.text}")
        return False, {}
    except Exception as e:
-        print(f"初始化上传异常: {str(e)}")
+        logger.error(f"[OSS] 获取预签名URL异常: {str(e)}")
        return False, {}


 def _put_upload(file_path: str, upload_url: str) -> bool:
    """
-    执行PUT上传
+    使用预签名URL上传文件到OSS

    Args:
        file_path: 本地文件路径
-        upload_url: 上传URL
+        upload_url: 完整的预签名上传URL

    Returns:
        是否成功
    """
    try:
+        logger.info(f"[OSS] 开始上传文件: {file_path}")
+
        with open(file_path, "rb") as f:
-            response = requests.put(upload_url, data=f)
+            # 使用预签名URL上传，不需要额外的认证header
+            response = requests.put(upload_url, data=f, timeout=300)
+
            if response.status_code == 200:
+                logger.info(f"[OSS] 文件上传成功")
                return True

-        print(f"PUT上传失败: {response.status_code}, {response.text}")
+        logger.error(f"[OSS] 上传失败: {response.status_code}")
+        logger.error(f"[OSS] 响应内容: {response.text[:500] if response.text else '无响应内容'}")
        return False
    except Exception as e:
-        print(f"PUT上传异常: {str(e)}")
+        logger.error(f"[OSS] 上传异常: {str(e)}")
        return False


-def _complete_upload(uuid: str) -> bool:
-    """
-    完成上传过程
-
-    Args:
-        uuid: 上传的UUID
-
-    Returns:
-        是否成功
-    """
-    url = f"{OSSUploadConfig.api_host}{OSSUploadConfig.complete_endpoint}"
-    headers = {
-        "Authorization": OSSUploadConfig.authorization,
-        "Content-Type": "application/json"
-    }
-
-    payload = {
-        "uuid": uuid
-    }
-
-    try:
-        response = requests.post(url, headers=headers, json=payload)
-        if response.status_code == 200:
-            result = response.json()
-            if result.get("code") == "10000":
-                return True
-
-        print(f"完成上传失败: {response.status_code}, {response.text}")
-        return False
-    except Exception as e:
-        print(f"完成上传异常: {str(e)}")
-        return False
-
-
-def oss_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
-              process_key: str = "file-upload", device_id: str = "default") -> bool:
+def oss_upload(
+    file_path: Union[str, Path],
+    filename: Optional[str] = None,
+    driver_name: str = "default",
+    exp_type: str = "default",
+    max_retries: int = 3,
+    client: Optional[HTTPClient] = None,
+) -> Dict:
    """
    文件上传主函数，包含重试机制

    Args:
        file_path: 本地文件路径
-        oss_path: OSS目标路径
        filename: 文件名，如果为None则使用file_path的文件名
-        process_key: 处理键
-        device_id: 设备ID
+        driver_name: 驱动名称，用于构造scene
+        exp_type: 实验类型，用于构造scene
+        max_retries: 最大重试次数
+        client: HTTPClient实例，如果不提供则使用默认的http_client

    Returns:
-        是否成功上传
+        Dict: {
+            "success": bool,  # 是否上传成功
+            "original_path": str,  # 原始文件路径
+            "oss_path": str  # OSS路径（成功时）或空字符串（失败时）
+        }
    """
-    max_retries = OSSUploadConfig.max_retries
+    file_path = Path(file_path)
+    if filename is None:
+        filename = os.path.basename(file_path)
+
+    if not os.path.exists(file_path):
+        logger.error(f"[OSS] 文件不存在: {file_path}")
+        return {"success": False, "original_path": file_path, "oss_path": ""}
+
    retry_count = 0
+    oss_path = ""

    while retry_count < max_retries:
        try:
-            # 步骤1：初始化上传
-            init_success, init_data = _init_upload(
-                file_path=file_path,
-                oss_path=oss_path,
-                filename=filename,
-                process_key=process_key,
-                device_id=device_id
+            # 步骤1：获取预签名URL
+            token_success, token_data = _get_oss_token(
+                filename=filename, driver_name=driver_name, exp_type=exp_type, client=client
            )

-            if not init_success:
-                print(f"初始化上传失败，重试 {retry_count + 1}/{max_retries}")
+            if not token_success:
+                logger.warning(f"[OSS] 获取预签名URL失败，重试 {retry_count + 1}/{max_retries}")
                retry_count += 1
-                time.sleep(1)  # 等待1秒后重试
+                time.sleep(1)
                continue

-            # 获取UUID和上传URL
-            uuid = init_data.get("uuid")
-            upload_url = init_data.get("upload_url")
+            # 获取预签名URL和OSS路径
+            upload_url = token_data.get("url")
+            oss_path = token_data.get("path", "")

-            if not uuid or not upload_url:
-                print(f"初始化上传返回数据不完整，重试 {retry_count + 1}/{max_retries}")
+            if not upload_url:
+                logger.warning(f"[OSS] 无法获取上传URL，API未返回url字段")
                retry_count += 1
                time.sleep(1)
                continue
@@ -163,69 +160,82 @@ def oss_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
            # 步骤2：PUT上传文件
            put_success = _put_upload(file_path, upload_url)
            if not put_success:
-                print(f"PUT上传失败，重试 {retry_count + 1}/{max_retries}")
-                retry_count += 1
-                time.sleep(1)
-                continue
-
-            # 步骤3：完成上传
-            complete_success = _complete_upload(uuid)
-            if not complete_success:
-                print(f"完成上传失败，重试 {retry_count + 1}/{max_retries}")
+                logger.warning(f"[OSS] PUT上传失败，重试 {retry_count + 1}/{max_retries}")
                retry_count += 1
                time.sleep(1)
                continue

            # 所有步骤都成功
-            print(f"文件 {file_path} 上传成功")
-            return True
+            logger.info(f"[OSS] 文件 {file_path} 上传成功")
+            return {"success": True, "original_path": file_path, "oss_path": oss_path}

        except Exception as e:
-            print(f"上传过程异常: {str(e)}，重试 {retry_count + 1}/{max_retries}")
+            logger.error(f"[OSS] 上传过程异常: {str(e)}，重试 {retry_count + 1}/{max_retries}")
            retry_count += 1
            time.sleep(1)

-    print(f"文件 {file_path} 上传失败，已达到最大重试次数 {max_retries}")
-    return False
+    logger.error(f"[OSS] 文件 {file_path} 上传失败，已达到最大重试次数 {max_retries}")
+    return {"success": False, "original_path": file_path, "oss_path": oss_path}


 if __name__ == "__main__":
-    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt
+    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt --driver HPLC --type test
+    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt --driver HPLC --type test \
+    #        --ak xxx --sk yyy --remote-addr http://xxx/api/v1
    # 命令行参数解析
-    parser = argparse.ArgumentParser(description='文件上传测试工具')
-    parser.add_argument('--file', '-f', type=str, required=True, help='要上传的本地文件路径')
-    parser.add_argument('--path', '-p', type=str, default='/HPLC1/Any', help='OSS目标路径')
-    parser.add_argument('--device', '-d', type=str, default='test-device', help='设备ID')
-    parser.add_argument('--process', '-k', type=str, default='HPLC-txt-result', help='处理键')
+    parser = argparse.ArgumentParser(description="文件上传测试工具")
+    parser.add_argument("--file", "-f", type=str, required=True, help="要上传的本地文件路径")
+    parser.add_argument("--driver", "-d", type=str, default="default", help="驱动名称")
+    parser.add_argument("--type", "-t", type=str, default="default", help="实验类型")
+    parser.add_argument("--ak", type=str, help="Access Key，如果提供则覆盖配置")
+    parser.add_argument("--sk", type=str, help="Secret Key，如果提供则覆盖配置")
+    parser.add_argument("--remote-addr", type=str, help="远程服务器地址（包含/api/v1），如果提供则覆盖配置")

    args = parser.parse_args()

    # 检查文件是否存在
    if not os.path.exists(args.file):
-        print(f"错误：文件 {args.file} 不存在")
+        logger.error(f"错误：文件 {args.file} 不存在")
        exit(1)

-    print("=" * 50)
-    print(f"开始上传文件: {args.file}")
-    print(f"目标路径: {args.path}")
-    print(f"设备ID: {args.device}")
-    print(f"处理键: {args.process}")
-    print("=" * 50)
+    # 如果提供了ak/sk/remote_addr，创建临时HTTPClient
+    temp_client = None
+    if args.ak and args.sk:
+        import base64
+
+        auth = base64.b64encode(f"{args.ak}:{args.sk}".encode("utf-8")).decode("utf-8")
+        remote_addr = args.remote_addr if args.remote_addr else http_client.remote_addr
+        temp_client = HTTPClient(remote_addr=remote_addr, auth=auth)
+        logger.info(f"[配置] 使用自定义配置: remote_addr={remote_addr}")
+    elif args.remote_addr:
+        temp_client = HTTPClient(remote_addr=args.remote_addr, auth=http_client.auth)
+        logger.info(f"[配置] 使用自定义remote_addr: {args.remote_addr}")
+    else:
+        logger.info(f"[配置] 使用默认配置: remote_addr={http_client.remote_addr}")
+
+    logger.info("=" * 50)
+    logger.info(f"开始上传文件: {args.file}")
+    logger.info(f"驱动名称: {args.driver}")
+    logger.info(f"实验类型: {args.type}")
+    logger.info(f"Scene: {args.driver}-{args.type}")
+    logger.info("=" * 50)

    # 执行上传
-    success = oss_upload(
+    result = oss_upload(
        file_path=args.file,
-        oss_path=args.path,
        filename=None,  # 使用默认文件名
-        process_key=args.process,
-        device_id=args.device
+        driver_name=args.driver,
+        exp_type=args.type,
+        client=temp_client,
    )

    # 输出结果
-    if success:
-        print("\n√ 文件上传成功！")
+    if result["success"]:
+        logger.info(f"\n√ 文件上传成功！")
+        logger.info(f"原始路径: {result['original_path']}")
+        logger.info(f"OSS路径: {result['oss_path']}")
        exit(0)
    else:
-        print("\n× 文件上传失败！")
+        logger.error(f"\n× 文件上传失败！")
+        logger.error(f"原始路径: {result['original_path']}")
        exit(1)
-
--- a/unilabos/app/utils.py
+++ b/unilabos/app/utils.py
@@ -0,0 +1,144 @@
+"""
+UniLabOS 应用工具函数
+
+提供清理、重启等工具函数
+"""
+
+import gc
+import os
+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
--- a/unilabos/app/web/api.py
+++ b/unilabos/app/web/api.py
@@ -9,13 +9,22 @@ import asyncio

 import yaml

-from unilabos.app.web.controler import devices, job_add, job_info
+from unilabos.app.web.controller import (
+    devices,
+    job_add,
+    job_info,
+    get_online_devices,
+    get_device_actions,
+    get_action_schema,
+    get_all_available_actions,
+)
 from unilabos.app.model import (
    Resp,
    RespCode,
    JobStatusResp,
    JobAddResp,
    JobAddReq,
+    JobData,
 )
 from unilabos.app.web.utils.host_utils import get_host_node_info
 from unilabos.registry.registry import lab_registry
@@ -1234,6 +1243,65 @@ def get_devices():
    return Resp(data=dict(data))


+@api.get("/online-devices", summary="Online devices list", response_model=Resp)
+def api_get_online_devices():
+    """获取在线设备列表
+
+    返回当前在线的设备列表，包含设备ID、命名空间、机器名等信息
+    """
+    isok, data = get_online_devices()
+    if not isok:
+        return Resp(code=RespCode.ErrorHostNotInit, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/devices/{device_id}/actions", summary="Device actions list", response_model=Resp)
+def api_get_device_actions(device_id: str):
+    """获取设备可用的动作列表
+
+    Args:
+        device_id: 设备ID
+
+    返回指定设备的所有可用动作，包含动作名称、类型、是否繁忙等信息
+    """
+    isok, data = get_device_actions(device_id)
+    if not isok:
+        return Resp(code=RespCode.ErrorInvalidReq, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/devices/{device_id}/actions/{action_name}/schema", summary="Action schema", response_model=Resp)
+def api_get_action_schema(device_id: str, action_name: str):
+    """获取动作的Schema详情
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    返回动作的参数Schema、默认值、类型等详细信息
+    """
+    isok, data = get_action_schema(device_id, action_name)
+    if not isok:
+        return Resp(code=RespCode.ErrorInvalidReq, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/actions", summary="All available actions", response_model=Resp)
+def api_get_all_actions():
+    """获取所有设备的可用动作
+
+    返回所有已注册设备的动作列表，包含设备信息和各动作的状态
+    """
+    isok, data = get_all_available_actions()
+    if not isok:
+        return Resp(code=RespCode.ErrorHostNotInit, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
@api.get("/job/{id}/status", summary="Job status", response_model=JobStatusResp)
 def job_status(id: str):
    """获取任务状态"""
@@ -1244,11 +1312,22 @@ def job_status(id: str):
@api.post("/job/add", summary="Create job", response_model=JobAddResp)
 def post_job_add(req: JobAddReq):
    """创建任务"""
-    device_id = req.device_id
-    if not req.data:
-        return Resp(code=RespCode.ErrorInvalidReq, message="Invalid request data")
+    # 检查必要参数：device_id 和 action
+    if not req.device_id:
+        return JobAddResp(
+            data=JobData(jobId="", status=6),
+            code=RespCode.ErrorInvalidReq,
+            message="device_id is required",
+        )
+
+    action_name = req.data.get("action", req.action) if req.data else req.action
+    if not action_name:
+        return JobAddResp(
+            data=JobData(jobId="", status=6),
+            code=RespCode.ErrorInvalidReq,
+            message="action is required",
+        )

-    req.device_id = device_id
    data = job_add(req)
    return JobAddResp(data=data)

--- a/unilabos/app/web/client.py
+++ b/unilabos/app/web/client.py
@@ -6,12 +6,10 @@ HTTP客户端模块

 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:
@@ -299,6 +298,10 @@ class HTTPClient:
        )
        if response.status_code not in [200, 201]:
            logger.error(f"注册资源失败: {response.status_code}, {response.text}")
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"注册资源失败: {response.text}")
        return response

    def request_startup_json(self) -> Optional[Dict[str, Any]]:
@@ -331,6 +334,67 @@ 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,
+    ) -> Dict[str, Any]:
+        """
+        导入工作流到服务器
+
+        Args:
+            name: 工作流名称（顶层）
+            workflow_uuid: 工作流UUID
+            workflow_name: 工作流名称（data内部）
+            nodes: 工作流节点列表
+            edges: 工作流边列表
+            tags: 工作流标签列表，默认为空列表
+            published: 是否发布工作流，默认为False
+
+        Returns:
+            Dict: API响应数据，包含 code 和 data (uuid, name)
+        """
+        # target_lab_uuid 暂时使用默认值，后续由后端根据 ak/sk 获取
+        payload = {
+            "target_lab_uuid": "28c38bb0-63f6-4352-b0d8-b5b8eb1766d5",
+            "name": name,
+            "data": {
+                "workflow_uuid": workflow_uuid,
+                "workflow_name": workflow_name,
+                "nodes": nodes,
+                "edges": edges,
+                "tags": tags if tags is not None else [],
+                "published": published,
+            },
+        }
+        # 保存请求到文件
+        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
+        else:
+            logger.error(f"导入工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+

 # 创建默认客户端实例
 http_client = HTTPClient()
--- a/unilabos/app/web/controler.py
+++ b/unilabos/app/web/controler.py
@@ -1,45 +0,0 @@
-
-import json
-import traceback
-import uuid
-from unilabos.app.model import JobAddReq, JobData
-from unilabos.ros.nodes.presets.host_node import HostNode
-from unilabos.utils.type_check import serialize_result_info
-
-
-def get_resources() -> tuple:
-    if HostNode.get_instance() is None:
-        return False, "Host node not initialized"
-
-    return True, HostNode.get_instance().resources_config
-
-def devices() -> tuple:
-    if HostNode.get_instance() is None:
-        return False, "Host node not initialized"
-    
-    return True, HostNode.get_instance().devices_config
-
-def job_info(id: str):
-    get_goal_status = HostNode.get_instance().get_goal_status(id)
-    return JobData(jobId=id, status=get_goal_status)
-
-def job_add(req: JobAddReq) -> JobData:
-    if req.job_id is None:
-        req.job_id = str(uuid.uuid4())
-    action_name = req.data["action"]
-    action_type = req.data.get("action_type", "LocalUnknown")
-    action_args = req.data.get("action_kwargs", None)  # 兼容老版本，后续删除
-    if action_args is None:
-        action_args = req.data.get("action_args")
-    else:
-        if "command" in action_args:
-            action_args = action_args["command"]
-    # print(f"job_add:{req.device_id} {action_name} {action_kwargs}")
-    try:
-        HostNode.get_instance().send_goal(req.device_id, action_type=action_type, action_name=action_name, action_kwargs=action_args, goal_uuid=req.job_id, server_info=req.server_info)
-    except Exception as e:
-        for bridge in HostNode.get_instance().bridges:
-            traceback.print_exc()
-            if hasattr(bridge, "publish_job_status"):
-                bridge.publish_job_status({}, req.job_id, "failed", serialize_result_info(traceback.format_exc(), False, {}))
-    return JobData(jobId=req.job_id)
--- a/unilabos/app/web/controller.py
+++ b/unilabos/app/web/controller.py
@@ -0,0 +1,587 @@
+"""
+Web API Controller
+
+提供Web API的控制器函数，处理设备、任务和动作相关的业务逻辑
+"""
+
+import threading
+import time
+import traceback
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Tuple
+
+from unilabos.app.model import JobAddReq, JobData
+from unilabos.ros.nodes.presets.host_node import HostNode
+from unilabos.utils import logger
+
+
+@dataclass
+class JobResult:
+    """任务结果数据"""
+
+    job_id: str
+    status: int  # 4:SUCCEEDED, 5:CANCELED, 6:ABORTED
+    result: Dict[str, Any] = field(default_factory=dict)
+    feedback: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+class JobResultStore:
+    """任务结果存储（单例）"""
+
+    _instance: Optional["JobResultStore"] = None
+    _lock = threading.Lock()
+
+    def __init__(self):
+        if not hasattr(self, "_initialized"):
+            self._results: Dict[str, JobResult] = {}
+            self._results_lock = threading.RLock()
+            self._initialized = True
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def store_result(
+        self, job_id: str, status: int, result: Optional[Dict[str, Any]], feedback: Optional[Dict[str, Any]] = None
+    ):
+        """存储任务结果"""
+        with self._results_lock:
+            self._results[job_id] = JobResult(
+                job_id=job_id,
+                status=status,
+                result=result or {},
+                feedback=feedback or {},
+                timestamp=time.time(),
+            )
+            logger.debug(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]}")
+            return result
+
+    def get_result(self, job_id: str) -> Optional[JobResult]:
+        """仅获取任务结果（不删除）"""
+        with self._results_lock:
+            return self._results.get(job_id)
+
+    def cleanup_old_results(self, max_age_seconds: float = 3600):
+        """清理过期的结果"""
+        current_time = time.time()
+        with self._results_lock:
+            expired_jobs = [
+                job_id for job_id, result in self._results.items() if current_time - result.timestamp > max_age_seconds
+            ]
+            for job_id in expired_jobs:
+                del self._results[job_id]
+                logger.debug(f"[JobResultStore] Cleaned up expired result for job {job_id[:8]}")
+
+
+# 全局结果存储实例
+job_result_store = JobResultStore()
+
+
+def store_job_result(
+    job_id: str, status: str, result: Optional[Dict[str, Any]], feedback: Optional[Dict[str, Any]] = None
+):
+    """存储任务结果（供外部调用）
+
+    Args:
+        job_id: 任务ID
+        status: 状态字符串 ("success", "failed", "cancelled")
+        result: 结果数据
+        feedback: 反馈数据
+    """
+    # 转换状态字符串为整数
+    status_map = {
+        "success": 4,  # SUCCEEDED
+        "failed": 6,  # ABORTED
+        "cancelled": 5,  # CANCELED
+        "running": 2,  # EXECUTING
+    }
+    status_int = status_map.get(status, 0)
+
+    # 只存储最终状态
+    if status_int in (4, 5, 6):
+        job_result_store.store_result(job_id, status_int, result, feedback)
+
+
+def get_resources() -> Tuple[bool, Any]:
+    """获取资源配置
+
+    Returns:
+        Tuple[bool, Any]: (是否成功, 资源配置或错误信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, "Host node not initialized"
+
+    return True, host_node.resources_config
+
+
+def devices() -> Tuple[bool, Any]:
+    """获取设备配置
+
+    Returns:
+        Tuple[bool, Any]: (是否成功, 设备配置或错误信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, "Host node not initialized"
+
+    return True, host_node.devices_config
+
+
+def job_info(job_id: str, remove_after_read: bool = True) -> JobData:
+    """获取任务信息
+
+    Args:
+        job_id: 任务ID
+        remove_after_read: 是否在读取后删除结果（默认True）
+
+    Returns:
+        JobData: 任务数据
+    """
+    # 首先检查结果存储中是否有已完成的结果
+    if remove_after_read:
+        stored_result = job_result_store.get_and_remove(job_id)
+    else:
+        stored_result = job_result_store.get_result(job_id)
+
+    if stored_result:
+        # 有存储的结果，直接返回
+        return JobData(
+            jobId=job_id,
+            status=stored_result.status,
+            result=stored_result.result,
+        )
+
+    # 没有存储的结果，从 HostNode 获取当前状态
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return JobData(jobId=job_id, status=0)
+
+    get_goal_status = host_node.get_goal_status(job_id)
+    return JobData(jobId=job_id, status=get_goal_status)
+
+
+def check_device_action_busy(device_id: str, action_name: str) -> Tuple[bool, Optional[str]]:
+    """检查设备动作是否正在执行（被占用）
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        Tuple[bool, Optional[str]]: (是否繁忙, 当前执行的job_id或None)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, None
+
+    device_action_key = f"/devices/{device_id}/{action_name}"
+
+    # 检查 _device_action_status 中是否有正在执行的任务
+    if device_action_key in host_node._device_action_status:
+        status = host_node._device_action_status[device_action_key]
+        if status.job_ids:
+            # 返回第一个正在执行的job_id
+            current_job_id = next(iter(status.job_ids.keys()), None)
+            return True, current_job_id
+
+    return False, None
+
+
+def _get_action_type(device_id: str, action_name: str) -> Optional[str]:
+    """从注册表自动获取动作类型
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        动作类型字符串，未找到返回None
+    """
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        # 方法1: 从运行时注册设备获取
+        if device_id in registered_devices:
+            device_info = registered_devices[device_id]
+            base_node = device_info.get("base_node_instance")
+            if base_node and hasattr(base_node, "_action_value_mappings"):
+                action_mappings = base_node._action_value_mappings
+                # 尝试直接匹配或 auto- 前缀匹配
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        action_type = action_mappings[key].get("type")
+                        if action_type:
+                            # 转换为字符串格式
+                            if hasattr(action_type, "__module__") and hasattr(action_type, "__name__"):
+                                return f"{action_type.__module__}.{action_type.__name__}"
+                            return str(action_type)
+
+        # 方法2: 从lab_registry获取
+        from unilabos.registry.registry import lab_registry
+
+        host_node = HostNode.get_instance(0)
+        if host_node and lab_registry:
+            devices_config = host_node.devices_config
+            device_class = None
+
+            for tree in devices_config.trees:
+                node = tree.root_node
+                if node.res_content.id == device_id:
+                    device_class = node.res_content.klass
+                    break
+
+            if device_class and device_class in lab_registry.device_type_registry:
+                device_type_info = lab_registry.device_type_registry[device_class]
+                class_info = device_type_info.get("class", {})
+                action_mappings = class_info.get("action_value_mappings", {})
+
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        action_type = action_mappings[key].get("type")
+                        if action_type:
+                            if hasattr(action_type, "__module__") and hasattr(action_type, "__name__"):
+                                return f"{action_type.__module__}.{action_type.__name__}"
+                            return str(action_type)
+
+    except Exception as e:
+        logger.warning(f"[Controller] Failed to get action type for {device_id}/{action_name}: {str(e)}")
+
+    return None
+
+
+def job_add(req: JobAddReq) -> JobData:
+    """添加任务（检查设备是否繁忙，繁忙则返回失败）
+
+    Args:
+        req: 任务添加请求
+
+    Returns:
+        JobData: 任务数据（包含状态）
+    """
+    # 服务端自动生成 job_id 和 task_id
+    job_id = str(uuid.uuid4())
+    task_id = str(uuid.uuid4())
+
+    # 服务端自动生成 server_info
+    server_info = {"send_timestamp": time.time()}
+
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        logger.error(f"[Controller] Host node not initialized for job: {job_id[:8]}")
+        return JobData(jobId=job_id, status=6)  # 6 = ABORTED
+
+    # 解析动作信息
+    action_name = req.data.get("action", req.action) if req.data else req.action
+    action_args = req.data.get("action_kwargs") or req.data.get("action_args") if req.data else req.action_args
+
+    if action_args is None:
+        action_args = req.action_args or {}
+    elif isinstance(action_args, dict) and "command" in action_args:
+        action_args = action_args["command"]
+
+    # 自动获取 action_type
+    action_type = _get_action_type(req.device_id, action_name)
+    if action_type is None:
+        logger.error(f"[Controller] Action type not found for {req.device_id}/{action_name}")
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+    # 检查设备动作是否繁忙
+    is_busy, current_job_id = check_device_action_busy(req.device_id, action_name)
+
+    if is_busy:
+        logger.warning(
+            f"[Controller] Device action busy: {req.device_id}/{action_name}, "
+            f"current job: {current_job_id[:8] if current_job_id else 'unknown'}"
+        )
+        # 返回失败状态，status=6 表示 ABORTED
+        return JobData(jobId=job_id, status=6)
+
+    # 设备空闲，提交任务执行
+    try:
+        from unilabos.app.ws_client import QueueItem
+
+        device_action_key = f"/devices/{req.device_id}/{action_name}"
+        queue_item = QueueItem(
+            task_type="job_call_back_status",
+            device_id=req.device_id,
+            action_name=action_name,
+            task_id=task_id,
+            job_id=job_id,
+            device_action_key=device_action_key,
+        )
+
+        host_node.send_goal(
+            queue_item,
+            action_type=action_type,
+            action_kwargs=action_args,
+            server_info=server_info,
+        )
+
+        logger.info(f"[Controller] Job submitted: {job_id[:8]} -> {req.device_id}/{action_name}")
+        # 返回已接受状态，status=1 表示 ACCEPTED
+        return JobData(jobId=job_id, status=1)
+
+    except ValueError as e:
+        # ActionClient not found 等错误
+        logger.error(f"[Controller] Action not available: {str(e)}")
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+    except Exception as e:
+        logger.error(f"[Controller] Error submitting job: {str(e)}")
+        traceback.print_exc()
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+
+def get_online_devices() -> Tuple[bool, Dict[str, Any]]:
+    """获取在线设备列表
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 在线设备信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        online_devices = {}
+        for device_key in host_node._online_devices:
+            # device_key 格式: "namespace/device_id"
+            parts = device_key.split("/")
+            if len(parts) >= 2:
+                device_id = parts[-1]
+            else:
+                device_id = device_key
+
+            # 获取设备详细信息
+            device_info = registered_devices.get(device_id, {})
+            machine_name = host_node.device_machine_names.get(device_id, "未知")
+
+            online_devices[device_id] = {
+                "device_key": device_key,
+                "namespace": host_node.devices_names.get(device_id, ""),
+                "machine_name": machine_name,
+                "uuid": device_info.get("uuid", "") if device_info else "",
+                "node_name": device_info.get("node_name", "") if device_info else "",
+            }
+
+        return True, {
+            "online_devices": online_devices,
+            "total_count": len(online_devices),
+            "timestamp": time.time(),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting online devices: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_device_actions(device_id: str) -> Tuple[bool, Dict[str, Any]]:
+    """获取设备可用的动作列表
+
+    Args:
+        device_id: 设备ID
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 动作列表信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+        from unilabos.app.web.utils.action_utils import get_action_info
+
+        # 检查设备是否已注册
+        if device_id not in registered_devices:
+            return False, {"error": f"Device not found: {device_id}"}
+
+        device_info = registered_devices[device_id]
+        actions = device_info.get("actions", {})
+
+        actions_list = {}
+        for action_name, action_server in actions.items():
+            try:
+                action_info = get_action_info(action_server, action_name)
+                # 检查动作是否繁忙
+                is_busy, current_job = check_device_action_busy(device_id, action_name)
+                actions_list[action_name] = {
+                    **action_info,
+                    "is_busy": is_busy,
+                    "current_job_id": current_job[:8] if current_job else None,
+                }
+            except Exception as e:
+                logger.warning(f"[Controller] Error getting action info for {action_name}: {str(e)}")
+                actions_list[action_name] = {
+                    "type_name": "unknown",
+                    "action_path": f"/devices/{device_id}/{action_name}",
+                    "is_busy": False,
+                    "error": str(e),
+                }
+
+        return True, {
+            "device_id": device_id,
+            "actions": actions_list,
+            "action_count": len(actions_list),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting device actions: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_action_schema(device_id: str, action_name: str) -> Tuple[bool, Dict[str, Any]]:
+    """获取动作的Schema详情
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, Schema信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.registry.registry import lab_registry
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        result = {
+            "device_id": device_id,
+            "action_name": action_name,
+            "schema": None,
+            "goal_default": None,
+            "action_type": None,
+            "is_busy": False,
+        }
+
+        # 检查动作是否繁忙
+        is_busy, current_job = check_device_action_busy(device_id, action_name)
+        result["is_busy"] = is_busy
+        result["current_job_id"] = current_job[:8] if current_job else None
+
+        # 方法1: 从 registered_devices 获取运行时信息
+        if device_id in registered_devices:
+            device_info = registered_devices[device_id]
+            base_node = device_info.get("base_node_instance")
+
+            if base_node and hasattr(base_node, "_action_value_mappings"):
+                action_mappings = base_node._action_value_mappings
+                if action_name in action_mappings:
+                    mapping = action_mappings[action_name]
+                    result["schema"] = mapping.get("schema")
+                    result["goal_default"] = mapping.get("goal_default")
+                    result["action_type"] = str(mapping.get("type", ""))
+
+        # 方法2: 从 lab_registry 获取注册表信息（如果运行时没有）
+        if result["schema"] is None and lab_registry:
+            # 尝试查找设备类型
+            devices_config = host_node.devices_config
+            device_class = None
+
+            # 从配置中获取设备类型
+            for tree in devices_config.trees:
+                node = tree.root_node
+                if node.res_content.id == device_id:
+                    device_class = node.res_content.klass
+                    break
+
+            if device_class and device_class in lab_registry.device_type_registry:
+                device_type_info = lab_registry.device_type_registry[device_class]
+                class_info = device_type_info.get("class", {})
+                action_mappings = class_info.get("action_value_mappings", {})
+
+                # 尝试直接匹配或 auto- 前缀匹配
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        mapping = action_mappings[key]
+                        result["schema"] = mapping.get("schema")
+                        result["goal_default"] = mapping.get("goal_default")
+                        result["action_type"] = str(mapping.get("type", ""))
+                        result["handles"] = mapping.get("handles", {})
+                        result["placeholder_keys"] = mapping.get("placeholder_keys", {})
+                        break
+
+        if result["schema"] is None:
+            return False, {"error": f"Action schema not found: {device_id}/{action_name}"}
+
+        return True, result
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting action schema: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_all_available_actions() -> Tuple[bool, Dict[str, Any]]:
+    """获取所有设备的可用动作
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 所有设备的动作信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+        from unilabos.app.web.utils.action_utils import get_action_info
+
+        all_actions = {}
+        total_action_count = 0
+
+        for device_id, device_info in registered_devices.items():
+            actions = device_info.get("actions", {})
+            device_actions = {}
+
+            for action_name, action_server in actions.items():
+                try:
+                    action_info = get_action_info(action_server, action_name)
+                    is_busy, current_job = check_device_action_busy(device_id, action_name)
+                    device_actions[action_name] = {
+                        "type_name": action_info.get("type_name", ""),
+                        "action_path": action_info.get("action_path", ""),
+                        "is_busy": is_busy,
+                        "current_job_id": current_job[:8] if current_job else None,
+                    }
+                    total_action_count += 1
+                except Exception as e:
+                    logger.warning(f"[Controller] Error processing action {device_id}/{action_name}: {str(e)}")
+
+            if device_actions:
+                all_actions[device_id] = {
+                    "actions": device_actions,
+                    "action_count": len(device_actions),
+                    "machine_name": host_node.device_machine_names.get(device_id, "未知"),
+                }
+
+        return True, {
+            "devices": all_actions,
+            "device_count": len(all_actions),
+            "total_action_count": total_action_count,
+            "timestamp": time.time(),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting all available actions: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
--- a/unilabos/app/web/server.py
+++ b/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


 # 当脚本直接运行时启动服务器
--- a/unilabos/app/ws_client.py
+++ b/unilabos/app/ws_client.py
@@ -359,6 +359,7 @@ class MessageProcessor:
        self.device_manager = device_manager
        self.queue_processor = None  # 延迟设置
        self.websocket_client = None  # 延迟设置
+        self.session_id = str(uuid.uuid4())[:6]  # 产生一个随机的session_id

        # WebSocket连接
        self.websocket = None
@@ -388,7 +389,7 @@ class MessageProcessor:
        self.is_running = True
        self.thread = threading.Thread(target=self._run, daemon=True, name="MessageProcessor")
        self.thread.start()
-        logger.info("[MessageProcessor] Started")
+        logger.trace("[MessageProcessor] Started")

    def stop(self) -> None:
        """停止消息处理线程"""
@@ -427,14 +428,17 @@ class MessageProcessor:
                    ssl=ssl_context,
                    ping_interval=WSConfig.ping_interval,
                    ping_timeout=10,
-                    additional_headers={"Authorization": f"Lab {BasicConfig.auth_secret()}"},
+                    additional_headers={
+                        "Authorization": f"Lab {BasicConfig.auth_secret()}",
+                        "EdgeSession": f"{self.session_id}",
+                    },
                    logger=ws_logger,
                ) as websocket:
                    self.websocket = websocket
                    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())
@@ -484,7 +488,16 @@ 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:
@@ -499,7 +512,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:
@@ -550,11 +563,8 @@ 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}")

        try:
@@ -567,11 +577,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 == "request_restart":
+                await self._handle_request_restart(message_data)
            else:
                logger.debug(f"[MessageProcessor] Unknown message type: {message_type}")

@@ -830,7 +848,7 @@ class MessageProcessor:
                    device_action_groups[key_add].append(item["uuid"])

                    logger.info(
-                        f"[MessageProcessor] Resource migrated: {item['uuid'][:8]} from {device_old_id} to {device_id}"
+                        f"[资源同步] 跨站Transfer: {item['uuid'][:8]} from {device_old_id} to {device_id}"
                    )
                else:
                    # 正常update
@@ -845,11 +863,11 @@ 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:
@@ -881,6 +899,49 @@ 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
    ):
@@ -932,7 +993,7 @@ class QueueProcessor:
        # 事件通知机制
        self.queue_update_event = threading.Event()

-        logger.info("[QueueProcessor] Initialized")
+        logger.trace("[QueueProcessor] Initialized")

    def set_websocket_client(self, websocket_client: "WebSocketClient"):
        """设置WebSocket客户端引用"""
@@ -947,7 +1008,7 @@ class QueueProcessor:
        self.is_running = True
        self.thread = threading.Thread(target=self._run, daemon=True, name="QueueProcessor")
        self.thread.start()
-        logger.info("[QueueProcessor] Started")
+        logger.trace("[QueueProcessor] Started")

    def stop(self) -> None:
        """停止队列处理线程"""
@@ -958,7 +1019,7 @@ class QueueProcessor:

    def _run(self):
        """运行队列处理主循环"""
-        logger.debug("[QueueProcessor] Queue processor started")
+        logger.trace("[QueueProcessor] Queue processor started")

        while self.is_running:
            try:
@@ -1168,7 +1229,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:
@@ -1181,13 +1241,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客户端"""
@@ -1196,6 +1254,18 @@ class WebSocketClient(BaseCommunicationClient):

        logger.info("[WebSocketClient] Stopping connection")

+        # 发送 normal_exit 消息
+        if self.is_connected():
+            try:
+                session_id = self.message_processor.session_id
+                message = {"action": "normal_exit", "data": {"session_id": session_id}}
+                self.message_processor.send_message(message)
+                logger.info(f"[WebSocketClient] Sent normal_exit message with session_id: {session_id}")
+                # 给一点时间让消息发送出去
+                time.sleep(1)
+            except Exception as e:
+                logger.warning(f"[WebSocketClient] Failed to send normal_exit message: {str(e)}")
+
        # 停止两个核心线程
        self.message_processor.stop()
        self.queue_processor.stop()
@@ -1224,7 +1294,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
@@ -1266,7 +1336,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消息"""
@@ -1295,3 +1365,57 @@ class WebSocketClient(BaseCommunicationClient):
            logger.info(f"[WebSocketClient] Job {job_log} cancelled successfully")
        else:
            logger.warning(f"[WebSocketClient] Failed to cancel job {job_log}")
+
+    def publish_host_ready(self) -> None:
+        """发布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(f"[WebSocketClient] Host node ready signal published with {len(devices)} devices")
--- a/unilabos/config/config.py
+++ b/unilabos/config/config.py
@@ -16,9 +16,14 @@ class BasicConfig:
    upload_registry = False
    machine_name = "undefined"
    vis_2d_enable = False
+    no_update_feedback = False
    enable_resource_load = True
    communication_protocol = "websocket"
-    log_level: Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = "DEBUG"  # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    startup_json_path = None  # 填写绝对路径
+    disable_browser = False  # 禁止浏览器自动打开
+    port = 8002  # 本地HTTP服务
+    # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    log_level: Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "DEBUG"

    @classmethod
    def auth_secret(cls):
@@ -36,18 +41,9 @@ class WSConfig:
    ping_interval = 30  # ping间隔（秒）


-# OSS上传配置
-class OSSUploadConfig:
-    api_host = ""
-    authorization = ""
-    init_endpoint = ""
-    complete_endpoint = ""
-    max_retries = 3
-
-
 # HTTP配置
 class HTTPConfig:
-    remote_addr = "http://127.0.0.1:48197/api/v1"
+    remote_addr = "https://uni-lab.bohrium.com/api/v1"


 # ROS配置
@@ -71,13 +67,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}")
--- a/unilabos/device_comms/coin_cell_assembly_workstation.py
+++ b/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()
        
        # 初始化基类
--- a/unilabos/device_comms/opcua_client/client.py
+++ b/unilabos/device_comms/opcua_client/client.py
--- a/unilabos/device_comms/opcua_client/node/uniopcua.py
+++ b/unilabos/device_comms/opcua_client/node/uniopcua.py
@@ -3,7 +3,7 @@ from enum import Enum
 from abc import ABC, abstractmethod
 from typing import Tuple, Union, Optional, Any, List

-from opcua import Client, Node
+from opcua import Client, Node, ua
 from opcua.ua import NodeId, NodeClass, VariantType


@@ -47,23 +47,68 @@ class Base(ABC):
    def _get_node(self) -> Node:
        if self._node is None:
            try:
-                # 检查是否是NumericNodeId(ns=X;i=Y)格式
-                if "NumericNodeId" in self._node_id:
-                    # 从字符串中提取命名空间和标识符
-                    import re
-                    match = re.search(r'ns=(\d+);i=(\d+)', self._node_id)
-                    if match:
-                        ns = int(match.group(1))
-                        identifier = int(match.group(2))
-                        node_id = NodeId(identifier, ns)
-                        self._node = self._client.get_node(node_id)
+                # 尝试多种 NodeId 字符串格式解析，兼容不同服务器/库的输出
+                # 可能的格式示例: 'ns=2;i=1234', 'ns=2;s=SomeString',
+                # 'StringNodeId(ns=4;s=OPC|变量名)', 'NumericNodeId(ns=2;i=1234)' 等
+                import re
+
+                nid = self._node_id
+                # 如果已经是 NodeId/Node 对象（库用户可能传入），直接使用
+                try:
+                    from opcua.ua import NodeId as UaNodeId
+                    if isinstance(nid, UaNodeId):
+                        self._node = self._client.get_node(nid)
+                        return self._node
+                except Exception:
+                    # 若导入或类型判断失败，则继续下一步
+                    pass
+
+                # 直接以字符串形式处理
+                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)
+                    if match_wrapped:
+                        # 提取括号内的实际 node_id 字符串
+                        nid = match_wrapped.group(2).strip()
+
+                    # 常见短格式 'ns=2;i=1234' 或 'ns=2;s=SomeString'
+                    if re.match(r'^ns=\d+;[is]=', nid):
+                        self._node = self._client.get_node(nid)
                    else:
-                        raise ValueError(f"无法解析节点ID: {self._node_id}")
+                        # 尝试提取 ns 和 i 或 s
+                        # 对于字符串标识符，可能包含特殊字符，使用非贪婪匹配
+                        m_num = re.search(r'ns=(\d+);i=(\d+)', nid)
+                        m_str = re.search(r'ns=(\d+);s=(.+?)(?:\)|$)', nid)
+                        if m_num:
+                            ns = int(m_num.group(1))
+                            identifier = int(m_num.group(2))
+                            node_id = NodeId(identifier, ns)
+                            self._node = self._client.get_node(node_id)
+                        elif m_str:
+                            ns = int(m_str.group(1))
+                            identifier = m_str.group(2).strip()
+                            # 对于字符串标识符，直接使用字符串格式
+                            node_id_str = f"ns={ns};s={identifier}"
+                            self._node = self._client.get_node(node_id_str)
+                        else:
+                            # 回退：尝试直接传入字符串（有些实现接受其它格式）
+                            try:
+                                self._node = self._client.get_node(self._node_id)
+                            except Exception as e:
+                                # 输出更详细的错误信息供调试
+                                print(f"获取节点失败(尝试直接字符串): {self._node_id}, 错误: {e}")
+                                raise
                else:
-                    # 直接使用节点ID字符串
+                    # 非字符串，尝试直接使用
                    self._node = self._client.get_node(self._node_id)
            except Exception as e:
                print(f"获取节点失败: {self._node_id}, 错误: {e}")
+                # 添加额外提示，帮助定位 BadNodeIdUnknown 问题
+                print("提示: 请确认该 node_id 是否来自当前连接的服务器地址空间，" \
+                      "以及 CSV/配置中名称与服务器 BrowseName 是否匹配。")
                raise
        return self._node

@@ -104,7 +149,56 @@ class Variable(Base):

    def write(self, value: Any) -> bool:
        try:
-            self._get_node().set_value(value)
+            # 如果声明了数据类型，则尝试转换并使用对应的 Variant 写入
+            coerced = value
+            try:
+                if self._data_type is not None:
+                    # 基于声明的数据类型做简单类型转换
+                    dt = self._data_type
+                    if dt in (DataType.SBYTE, DataType.BYTE, DataType.INT16, DataType.UINT16,
+                              DataType.INT32, DataType.UINT32, DataType.INT64, DataType.UINT64):
+                        # 数值类型 -> int
+                        if isinstance(value, str):
+                            coerced = int(value)
+                        else:
+                            coerced = int(value)
+                    elif dt in (DataType.FLOAT, DataType.DOUBLE):
+                        if isinstance(value, str):
+                            coerced = float(value)
+                        else:
+                            coerced = float(value)
+                    elif dt == DataType.BOOLEAN:
+                        if isinstance(value, str):
+                            v = value.strip().lower()
+                            if v in ("true", "1", "yes", "on"):
+                                coerced = True
+                            elif v in ("false", "0", "no", "off"):
+                                coerced = False
+                            else:
+                                coerced = bool(value)
+                        else:
+                            coerced = bool(value)
+                    elif dt == DataType.STRING or dt == DataType.BYTESTRING or dt == DataType.DATETIME:
+                        coerced = str(value)
+
+                    # 使用 ua.Variant 明确指定 VariantType
+                    try:
+                        variant = ua.Variant(coerced, dt.value)
+                        self._get_node().set_value(variant)
+                    except Exception:
+                        # 回退：有些 set_value 实现接受 (value, variant_type)
+                        try:
+                            self._get_node().set_value(coerced, dt.value)
+                        except Exception:
+                            # 最后回退到直接写入（保持兼容性）
+                            self._get_node().set_value(coerced)
+                else:
+                    # 未声明数据类型，直接写入
+                    self._get_node().set_value(value)
+            except Exception:
+                # 若在转换或按数据类型写入失败，尝试直接写入原始值并让上层捕获错误
+                self._get_node().set_value(value)
+
            return False
        except Exception as e:
            print(f"写入变量 {self._name} 失败: {e}")
@@ -120,20 +214,50 @@ class Method(Base):
    def _get_parent_node(self) -> Node:
        if self._parent_node is None:
            try:
-                # 检查是否是NumericNodeId(ns=X;i=Y)格式
-                if "NumericNodeId" in self._parent_node_id:
-                    # 从字符串中提取命名空间和标识符
-                    import re
-                    match = re.search(r'ns=(\d+);i=(\d+)', self._parent_node_id)
-                    if match:
-                        ns = int(match.group(1))
-                        identifier = int(match.group(2))
-                        node_id = NodeId(identifier, ns)
-                        self._parent_node = self._client.get_node(node_id)
+                # 处理父节点ID，使用与_get_node相同的解析逻辑
+                import re
+                
+                nid = self._parent_node_id
+                
+                # 如果已经是 NodeId 对象，直接使用
+                try:
+                    from opcua.ua import NodeId as UaNodeId
+                    if isinstance(nid, UaNodeId):
+                        self._parent_node = self._client.get_node(nid)
+                        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)
                    else:
-                        raise ValueError(f"无法解析父节点ID: {self._parent_node_id}")
+                        # 提取 ns 和 i 或 s
+                        m_num = re.search(r'ns=(\d+);i=(\d+)', nid)
+                        m_str = re.search(r'ns=(\d+);s=(.+?)(?:\)|$)', nid)
+                        if m_num:
+                            ns = int(m_num.group(1))
+                            identifier = int(m_num.group(2))
+                            node_id = NodeId(identifier, ns)
+                            self._parent_node = self._client.get_node(node_id)
+                        elif m_str:
+                            ns = int(m_str.group(1))
+                            identifier = m_str.group(2).strip()
+                            node_id_str = f"ns={ns};s={identifier}"
+                            self._parent_node = self._client.get_node(node_id_str)
+                        else:
+                            # 回退
+                            self._parent_node = self._client.get_node(self._parent_node_id)
                else:
-                    # 直接使用节点ID字符串
                    self._parent_node = self._client.get_node(self._parent_node_id)
            except Exception as e:
                print(f"获取父节点失败: {self._parent_node_id}, 错误: {e}")
--- a/unilabos/device_mesh/resource_visalization.py
+++ b/unilabos/device_mesh/resource_visalization.py
@@ -128,14 +128,21 @@ class ResourceVisualization:
                        new_dev.set("device_name", node["id"]+"_")
                        # if node["parent"] is not None:
                        #     new_dev.set("station_name", node["parent"]+'_')
-
-                        new_dev.set("x",str(float(node["position"]["position"]["x"])/1000))
-                        new_dev.set("y",str(float(node["position"]["position"]["y"])/1000))
-                        new_dev.set("z",str(float(node["position"]["position"]["z"])/1000))
+                        if "position" in node:
+                            new_dev.set("x",str(float(node["position"]["position"]["x"])/1000))
+                            new_dev.set("y",str(float(node["position"]["position"]["y"])/1000))
+                            new_dev.set("z",str(float(node["position"]["position"]["z"])/1000))
                        if "rotation" in node["config"]:
                            new_dev.set("rx",str(float(node["config"]["rotation"]["x"])))
                            new_dev.set("ry",str(float(node["config"]["rotation"]["y"])))
                            new_dev.set("r",str(float(node["config"]["rotation"]["z"])))
+                        if "pose" in node:
+                            new_dev.set("x",str(float(node["pose"]["position"]["x"])/1000))
+                            new_dev.set("y",str(float(node["pose"]["position"]["y"])/1000))
+                            new_dev.set("z",str(float(node["pose"]["position"]["z"])/1000))
+                            new_dev.set("rx",str(float(node["pose"]["rotation"]["x"])))
+                            new_dev.set("ry",str(float(node["pose"]["rotation"]["y"])))
+                            new_dev.set("r",str(float(node["pose"]["rotation"]["z"])))
                        if "device_config" in node["config"]:
                            for key, value in node["config"]["device_config"].items():
                                new_dev.set(key, str(value))
--- a/unilabos/devices/LICENSE
+++ b/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、语言优先
+本准则同时具有中文版本和英文版本，如果英文版本和中文版本有冲突，以中文版本为准。
+
--- a/unilabos/devices/LICENSE_eng
+++ b/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.
+
--- a/unilabos/devices/cameraSII/init.py
+++ b/unilabos/devices/cameraSII/init.py
--- a/unilabos/devices/cameraSII/cameraDriver.py
+++ b/unilabos/devices/cameraSII/cameraDriver.py
@@ -0,0 +1,712 @@
+#!/usr/bin/env python3
+import asyncio
+import json
+import subprocess
+import sys
+import threading
+from typing import Optional, Dict, Any
+import logging
+
+import requests
+import websockets
+
+logging.getLogger("zeep").setLevel(logging.WARNING)
+logging.getLogger("zeep.xsd.schema").setLevel(logging.WARNING)
+logging.getLogger("zeep.xsd.schema.schema").setLevel(logging.WARNING)
+from onvif import ONVIFCamera  # 新增：ONVIF PTZ 控制
+
+
+# ======================= 独立的 PTZController =======================
+class PTZController:
+    def __init__(self, host: str, port: int, user: str, password: str):
+        """
+        :param host: 摄像机 IP 或域名（和 RTSP 的一样即可）
+        :param port: ONVIF 端口（多数为 80，看你的设备）
+        :param user: 摄像机用户名
+        :param password: 摄像机密码
+        """
+        self.host = host
+        self.port = port
+        self.user = user
+        self.password = password
+
+        self.cam: Optional[ONVIFCamera] = None
+        self.media_service = None
+        self.ptz_service = None
+        self.profile = None
+
+    def connect(self) -> bool:
+        """
+        建立 ONVIF 连接并初始化 PTZ 能力，失败返回 False（不抛异常）
+        Note: 首先 pip install onvif-zeep
+        """
+        try:
+            self.cam = ONVIFCamera(self.host, self.port, self.user, self.password)
+            self.media_service = self.cam.create_media_service()
+            self.ptz_service = self.cam.create_ptz_service()
+            profiles = self.media_service.GetProfiles()
+            if not profiles:
+                print("[PTZ] No media profiles found on camera.", file=sys.stderr)
+                return False
+            self.profile = profiles[0]
+            return True
+        except Exception as e:
+            print(f"[PTZ] Failed to init ONVIF PTZ: {e}", file=sys.stderr)
+            return False
+
+    def _continuous_move(self, pan: float, tilt: float, zoom: float, duration: float) -> bool:
+        """
+        连续移动一段时间（秒），之后自动停止。
+        此函数为阻塞模式：只有在 Stop 调用结束后，才返回 True/False。
+        """
+        if not self.ptz_service or not self.profile:
+            print("[PTZ] _continuous_move: ptz_service or profile not ready", file=sys.stderr)
+            return False
+
+        # 进入前先强行停一下，避免前一次残留动作
+        self._force_stop()
+
+        req = self.ptz_service.create_type("ContinuousMove")
+        req.ProfileToken = self.profile.token
+
+        req.Velocity = {
+            "PanTilt": {"x": pan, "y": tilt},
+            "Zoom": {"x": zoom},
+        }
+
+        try:
+            print(f"[PTZ] ContinuousMove start: pan={pan}, tilt={tilt}, zoom={zoom}, duration={duration}", file=sys.stderr)
+            self.ptz_service.ContinuousMove(req)
+        except Exception as e:
+            print(f"[PTZ] ContinuousMove failed: {e}", file=sys.stderr)
+            return False
+
+        # 阻塞等待：这里决定“运动时间”
+        import time
+        wait_seconds = max(2 * duration, 0.0)
+        time.sleep(wait_seconds)
+
+        # 运动完成后强制停止
+        return self._force_stop()
+
+    def stop(self) -> bool:
+        """
+        阻塞调用 Stop（带重试），成功 True，失败 False。
+        """
+        return self._force_stop()
+
+    # ------- 对外动作接口（给 CameraController 调用） -------
+    # 所有接口都为“阻塞模式”：只有在运动 + Stop 完成后才返回 True/False
+
+    def move_up(self, speed: float = 0.5, duration: float = 1.0) -> bool:
+        print(f"[PTZ] move_up called, speed={speed}, duration={duration}", file=sys.stderr)
+        return self._continuous_move(pan=0.0, tilt=+speed, zoom=0.0, duration=duration)
+
+    def move_down(self, speed: float = 0.5, duration: float = 1.0) -> bool:
+        print(f"[PTZ] move_down called, speed={speed}, duration={duration}", file=sys.stderr)
+        return self._continuous_move(pan=0.0, tilt=-speed, zoom=0.0, duration=duration)
+
+    def move_left(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        print(f"[PTZ] move_left called, speed={speed}, duration={duration}", file=sys.stderr)
+        return self._continuous_move(pan=-speed, tilt=0.0, zoom=0.0, duration=duration)
+
+    def move_right(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        print(f"[PTZ] move_right called, speed={speed}, duration={duration}", file=sys.stderr)
+        return self._continuous_move(pan=+speed, tilt=0.0, zoom=0.0, duration=duration)
+
+    # ------- 占位的变倍接口（当前设备不支持） -------
+    def zoom_in(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        """
+        当前设备不支持变倍；保留方法只是避免上层调用时报错。
+        """
+        print("[PTZ] zoom_in is disabled for this device.", file=sys.stderr)
+        return False
+
+    def zoom_out(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        """
+        当前设备不支持变倍；保留方法只是避免上层调用时报错。
+        """
+        print("[PTZ] zoom_out is disabled for this device.", file=sys.stderr)
+        return False
+
+    def _force_stop(self, retries: int = 3, delay: float = 0.1) -> bool:
+        """
+        尝试多次调用 Stop，作为“强制停止”手段。
+        :param retries: 重试次数
+        :param delay: 每次重试间隔（秒）
+        """
+        if not self.ptz_service or not self.profile:
+            print("[PTZ] _force_stop: ptz_service or profile not ready", file=sys.stderr)
+            return False
+
+        import time
+        last_error = None
+        for i in range(retries):
+            try:
+                print(f"[PTZ] _force_stop: calling Stop(), attempt={i+1}", file=sys.stderr)
+                self.ptz_service.Stop({"ProfileToken": self.profile.token})
+                print("[PTZ] _force_stop: Stop() returned OK", file=sys.stderr)
+                return True
+            except Exception as e:
+                last_error = e
+                print(f"[PTZ] _force_stop: Stop() failed at attempt {i+1}: {e}", file=sys.stderr)
+                time.sleep(delay)
+
+        print(f"[PTZ] _force_stop: all {retries} attempts failed, last error: {last_error}", file=sys.stderr)
+        return False
+
+# ======================= CameraController（加入 PTZ） =======================
+
+class CameraController:
+    """
+    Uni-Lab-OS 摄像头驱动（driver 形式）
+    启动 Uni-Lab-OS 后，立即开始推流
+
+    - WebSocket 信令：通过 signal_backend_url 连接到后端
+      例如: wss://sciol.ac.cn/api/realtime/signal/host/<host_id>
+    - 媒体服务器：通过 rtmp_url / webrtc_api / webrtc_stream_url
+      当前配置为 SRS，与独立 HostSimulator 独立运行脚本保持一致。
+    """
+
+    def __init__(
+        self,
+        host_id: str = "demo-host",
+
+        # （1）信令后端（WebSocket）
+        signal_backend_url: str = "wss://sciol.ac.cn/api/realtime/signal/host",
+
+        # （2）媒体后端（RTMP + WebRTC API）
+        rtmp_url: str = "rtmp://srs.sciol.ac.cn:4499/live/camera-01",
+        webrtc_api: str = "https://srs.sciol.ac.cn/rtc/v1/play/",
+        webrtc_stream_url: str = "webrtc://srs.sciol.ac.cn:4500/live/camera-01",
+        camera_rtsp_url: str = "",
+
+        # （3）PTZ 控制相关（ONVIF）
+        ptz_host: str = "",           # 一般就是摄像头 IP，比如 "192.168.31.164"
+        ptz_port: int = 80,           # ONVIF 端口，不一定是 80，按实际情况改
+        ptz_user: str = "",           # admin
+        ptz_password: str = "",       # admin123
+    ):
+        self.host_id = host_id
+        self.camera_rtsp_url = camera_rtsp_url
+
+        # 拼接最终的 WebSocket URL：.../host/<host_id>
+        signal_backend_url = signal_backend_url.rstrip("/")
+        if not signal_backend_url.endswith("/host"):
+            signal_backend_url = signal_backend_url + "/host"
+        self.signal_backend_url = f"{signal_backend_url}/{host_id}"
+
+        # 媒体服务器配置
+        self.rtmp_url = rtmp_url
+        self.webrtc_api = webrtc_api
+        self.webrtc_stream_url = webrtc_stream_url
+
+        # PTZ 控制
+        self.ptz_host = ptz_host
+        self.ptz_port = ptz_port
+        self.ptz_user = ptz_user
+        self.ptz_password = ptz_password
+        self._ptz: Optional[PTZController] = None
+        self._init_ptz_if_possible()
+
+        # 运行时状态
+        self._ws: Optional[object] = None
+        self._ffmpeg_process: Optional[subprocess.Popen] = None
+        self._running = False
+        self._loop_task: Optional[asyncio.Future] = None
+
+        # 事件循环 & 线程
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._loop_thread: Optional[threading.Thread] = None
+
+        try:
+            self.start()
+        except Exception as e:
+            print(f"[CameraController] __init__ auto start failed: {e}", file=sys.stderr)
+
+    # ------------------------ PTZ 初始化 ------------------------
+
+    # ------------------------ PTZ 公开动作方法（一个动作一个函数） ------------------------
+
+    def ptz_move_up(self, speed: float = 0.5, duration: float = 1.0) -> bool:
+        print(f"[CameraController] ptz_move_up called, speed={speed}, duration={duration}")
+        return self._ptz.move_up(speed=speed, duration=duration)
+
+    def ptz_move_down(self, speed: float = 0.5, duration: float = 1.0) -> bool:
+        print(f"[CameraController] ptz_move_down called, speed={speed}, duration={duration}")
+        return self._ptz.move_down(speed=speed, duration=duration)
+
+    def ptz_move_left(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        print(f"[CameraController] ptz_move_left called, speed={speed}, duration={duration}")
+        return self._ptz.move_left(speed=speed, duration=duration)
+
+    def ptz_move_right(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        print(f"[CameraController] ptz_move_right called, speed={speed}, duration={duration}")
+        return self._ptz.move_right(speed=speed, duration=duration)
+
+    def zoom_in(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        """
+        当前设备不支持变倍；保留方法只是避免上层调用时报错。
+        """
+        print("[PTZ] zoom_in is disabled for this device.", file=sys.stderr)
+        return False
+
+    def zoom_out(self, speed: float = 0.2, duration: float = 1.0) -> bool:
+        """
+        当前设备不支持变倍；保留方法只是避免上层调用时报错。
+        """
+        print("[PTZ] zoom_out is disabled for this device.", file=sys.stderr)
+        return False
+
+    def ptz_stop(self):
+        if self._ptz is None:
+            print("[CameraController] PTZ not initialized.", file=sys.stderr)
+            return
+        self._ptz.stop()
+
+    def _init_ptz_if_possible(self):
+        """
+        根据 ptz_host / user / password 初始化 PTZ；
+        如果配置信息不全则不启用 PTZ（静默）。
+        """
+        if not (self.ptz_host and self.ptz_user and self.ptz_password):
+            return
+        ctrl = PTZController(
+            host=self.ptz_host,
+            port=self.ptz_port,
+            user=self.ptz_user,
+            password=self.ptz_password,
+        )
+        if ctrl.connect():
+            self._ptz = ctrl
+        else:
+            self._ptz = None
+
+    # ---------------------------------------------------------------------
+    # 对外暴露的方法：供 Uni-Lab-OS 调用
+    # ---------------------------------------------------------------------
+
+    def start(self, config: Optional[Dict[str, Any]] = None):
+        """
+        启动 Camera 连接 & 消息循环，并在启动时就开启 FFmpeg 推流，
+        """
+
+        if self._running:
+            return {"status": "already_running", "host_id": self.host_id}
+
+        # 应用 config 覆盖（如果有）
+        if config:
+            self.camera_rtsp_url = config.get("camera_rtsp_url", self.camera_rtsp_url)
+            cfg_host_id = config.get("host_id")
+            if cfg_host_id:
+                self.host_id = cfg_host_id
+
+            signal_backend_url = config.get("signal_backend_url")
+            if signal_backend_url:
+                signal_backend_url = signal_backend_url.rstrip("/")
+                if not signal_backend_url.endswith("/host"):
+                    signal_backend_url = signal_backend_url + "/host"
+                self.signal_backend_url = f"{signal_backend_url}/{self.host_id}"
+
+            self.rtmp_url = config.get("rtmp_url", self.rtmp_url)
+            self.webrtc_api = config.get("webrtc_api", self.webrtc_api)
+            self.webrtc_stream_url = config.get(
+                "webrtc_stream_url", self.webrtc_stream_url
+            )
+
+            # PTZ 相关配置也允许通过 config 注入
+            self.ptz_host = config.get("ptz_host", self.ptz_host)
+            self.ptz_port = int(config.get("ptz_port", self.ptz_port))
+            self.ptz_user = config.get("ptz_user", self.ptz_user)
+            self.ptz_password = config.get("ptz_password", self.ptz_password)
+            self._init_ptz_if_possible()
+
+        self._running = True
+
+        # === start 时启动 FFmpeg 推流 ===
+        self._start_ffmpeg()
+
+        # 创建新的事件循环和线程（用于 WebSocket 信令）
+        self._loop = asyncio.new_event_loop()
+
+        def loop_runner(loop: asyncio.AbstractEventLoop):
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_forever()
+            except Exception as e:
+                print(f"[CameraController] event loop error: {e}", file=sys.stderr)
+
+        self._loop_thread = threading.Thread(
+            target=loop_runner, args=(self._loop,), daemon=True
+        )
+        self._loop_thread.start()
+
+        self._loop_task = asyncio.run_coroutine_threadsafe(
+            self._run_main_loop(), self._loop
+        )
+
+        return {
+            "status": "started",
+            "host_id": self.host_id,
+            "signal_backend_url": self.signal_backend_url,
+            "rtmp_url": self.rtmp_url,
+            "webrtc_api": self.webrtc_api,
+            "webrtc_stream_url": self.webrtc_stream_url,
+        }
+
+    def stop(self) -> Dict[str, Any]:
+        """
+        停止推流 & 断开 WebSocket，并关闭事件循环线程。
+        """
+        self._running = False
+
+        self._stop_ffmpeg()
+
+        if self._ws and self._loop is not None:
+            async def close_ws():
+                try:
+                    await self._ws.close()
+                except Exception as e:
+                    print(
+                        f"[CameraController] error when closing WebSocket: {e}",
+                        file=sys.stderr,
+                    )
+
+            asyncio.run_coroutine_threadsafe(close_ws(), self._loop)
+
+        if self._loop_task is not None:
+            if not self._loop_task.done():
+                self._loop_task.cancel()
+            try:
+                self._loop_task.result()
+            except asyncio.CancelledError:
+                pass
+            except Exception as e:
+                print(
+                    f"[CameraController] main loop task error in stop(): {e}",
+                    file=sys.stderr,
+                )
+            finally:
+                self._loop_task = None
+
+        if self._loop is not None:
+            try:
+                self._loop.call_soon_threadsafe(self._loop.stop)
+            except Exception as e:
+                print(
+                    f"[CameraController] error when stopping event loop: {e}",
+                    file=sys.stderr,
+                )
+
+        if self._loop_thread is not None:
+            try:
+                self._loop_thread.join(timeout=5)
+            except Exception as e:
+                print(
+                    f"[CameraController] error when joining loop thread: {e}",
+                    file=sys.stderr,
+                )
+            finally:
+                self._loop_thread = None
+
+        self._ws = None
+        self._loop = None
+
+        return {"status": "stopped", "host_id": self.host_id}
+
+    def get_status(self) -> Dict[str, Any]:
+        """
+        查询当前状态，方便在 Uni-Lab-OS 中做监控。
+        """
+        ws_closed = None
+        if self._ws is not None:
+            ws_closed = getattr(self._ws, "closed", None)
+
+        if ws_closed is None:
+            websocket_connected = self._ws is not None
+        else:
+            websocket_connected = (self._ws is not None) and (not ws_closed)
+
+        return {
+            "host_id": self.host_id,
+            "running": self._running,
+            "websocket_connected": websocket_connected,
+            "ffmpeg_running": bool(
+                self._ffmpeg_process and self._ffmpeg_process.poll() is None
+            ),
+            "signal_backend_url": self.signal_backend_url,
+            "rtmp_url": self.rtmp_url,
+        }
+
+    # ---------------------------------------------------------------------
+    # 内部实现逻辑：WebSocket 循环 / FFmpeg / WebRTC Offer 处理
+    # ---------------------------------------------------------------------
+
+    async def _run_main_loop(self):
+        try:
+            while self._running:
+                try:
+                    async with websockets.connect(self.signal_backend_url) as ws:
+                        self._ws = ws
+                        await self._recv_loop()
+                except asyncio.CancelledError:
+                    raise
+                except Exception as e:
+                    if self._running:
+                        print(
+                            f"[CameraController] WebSocket connection error: {e}",
+                            file=sys.stderr,
+                        )
+                        await asyncio.sleep(3)
+        except asyncio.CancelledError:
+            pass
+
+    async def _recv_loop(self):
+        assert self._ws is not None
+        ws = self._ws
+
+        async for message in ws:
+            try:
+                data = json.loads(message)
+            except json.JSONDecodeError:
+                print(
+                    f"[CameraController] received non-JSON message: {message}",
+                    file=sys.stderr,
+                )
+                continue
+
+            try:
+                await self._handle_message(data)
+            except Exception as e:
+                print(
+                    f"[CameraController] error while handling message {data}: {e}",
+                    file=sys.stderr,
+                )
+
+    async def _handle_message(self, data: Dict[str, Any]):
+        """
+        处理来自信令后端的消息：
+        - command: start_stream / stop_stream / ptz_xxx
+        - type: offer (WebRTC)
+        """
+        cmd = data.get("command")
+
+        # ---------- 推流控制 ----------
+        if cmd == "start_stream":
+            try:
+                self._start_ffmpeg()
+            except Exception as e:
+                print(
+                    f"[CameraController] error when starting FFmpeg on start_stream: {e}",
+                    file=sys.stderr,
+                )
+            return
+
+        if cmd == "stop_stream":
+            try:
+                self._stop_ffmpeg()
+            except Exception as e:
+                print(
+                    f"[CameraController] error when stopping FFmpeg on stop_stream: {e}",
+                    file=sys.stderr,
+                )
+            return
+
+        # # ---------- PTZ 控制 ----------
+        # # 例如信令可以发：
+        # # {"command": "ptz_move", "direction": "down", "speed": 0.5, "duration": 0.5}
+        # if cmd == "ptz_move":
+        #     if self._ptz is None:
+        #         # 没有初始化 PTZ，静默忽略或打印一条
+        #         print("[CameraController] PTZ not initialized.", file=sys.stderr)
+        #         return
+
+        #     direction = data.get("direction", "")
+        #     speed = float(data.get("speed", 0.5))
+        #     duration = float(data.get("duration", 0.5))
+
+        #     try:
+        #         if direction == "up":
+        #             self._ptz.move_up(speed=speed, duration=duration)
+        #         elif direction == "down":
+        #             self._ptz.move_down(speed=speed, duration=duration)
+        #         elif direction == "left":
+        #             self._ptz.move_left(speed=speed, duration=duration)
+        #         elif direction == "right":
+        #             self._ptz.move_right(speed=speed, duration=duration)
+        #         elif direction == "zoom_in":
+        #             self._ptz.zoom_in(speed=speed, duration=duration)
+        #         elif direction == "zoom_out":
+        #             self._ptz.zoom_out(speed=speed, duration=duration)
+        #         elif direction == "stop":
+        #             self._ptz.stop()
+        #         else:
+        #             # 未知方向，忽略
+        #             pass
+        #     except Exception as e:
+        #         print(
+        #             f"[CameraController] error when handling PTZ move: {e}",
+        #             file=sys.stderr,
+        #         )
+        #     return
+
+        # ---------- WebRTC Offer ----------
+        if data.get("type") == "offer":
+            offer_sdp = data.get("sdp", "")
+            camera_id = data.get("cameraId", "camera-01")
+            try:
+                answer_sdp = await self._handle_webrtc_offer(offer_sdp)
+            except Exception as e:
+                print(
+                    f"[CameraController] error when handling WebRTC offer: {e}",
+                    file=sys.stderr,
+                )
+                return
+
+            if self._ws:
+                answer_payload = {
+                    "type": "answer",
+                    "sdp": answer_sdp,
+                    "cameraId": camera_id,
+                    "hostId": self.host_id,
+                }
+                try:
+                    await self._ws.send(json.dumps(answer_payload))
+                except Exception as e:
+                    print(
+                        f"[CameraController] error when sending WebRTC answer: {e}",
+                        file=sys.stderr,
+                    )
+
+    # ------------------------ FFmpeg 相关 ------------------------
+
+    def _start_ffmpeg(self):
+        if self._ffmpeg_process and self._ffmpeg_process.poll() is None:
+            return
+
+        cmd = [
+            "ffmpeg",
+            "-rtsp_transport", "tcp",
+            "-i", self.camera_rtsp_url,
+
+            "-c:v", "libx264",
+            "-preset", "ultrafast",
+            "-tune", "zerolatency",
+            "-profile:v", "baseline",
+            "-b:v", "1M",
+            "-maxrate", "1M",
+            "-bufsize", "2M",
+            "-g", "10",
+            "-keyint_min", "10",
+            "-sc_threshold", "0",
+            "-pix_fmt", "yuv420p",
+            "-x264-params", "bframes=0",
+
+            "-c:a", "aac",
+            "-ar", "44100",
+            "-ac", "1",
+            "-b:a", "64k",
+
+            "-f", "flv",
+            self.rtmp_url,
+        ]
+
+        try:
+            self._ffmpeg_process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
+                shell=False,
+            )
+        except Exception as e:
+            print(f"[CameraController] failed to start FFmpeg: {e}", file=sys.stderr)
+            self._ffmpeg_process = None
+            raise
+
+    def _stop_ffmpeg(self):
+        proc = self._ffmpeg_process
+
+        if proc and proc.poll() is None:
+            try:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    try:
+                        proc.kill()
+                        try:
+                            proc.wait(timeout=2)
+                        except subprocess.TimeoutExpired:
+                            print(
+                                f"[CameraController] FFmpeg process did not exit even after kill (pid={proc.pid})",
+                                file=sys.stderr,
+                            )
+                    except Exception as e:
+                        print(
+                            f"[CameraController] failed to kill FFmpeg process: {e}",
+                            file=sys.stderr,
+                        )
+            except Exception as e:
+                print(
+                    f"[CameraController] error when stopping FFmpeg: {e}",
+                    file=sys.stderr,
+                )
+
+        self._ffmpeg_process = None
+
+    # ------------------------ WebRTC Offer 相关 ------------------------
+
+    async def _handle_webrtc_offer(self, offer_sdp: str) -> str:
+        payload = {
+            "api": self.webrtc_api,
+            "streamurl": self.webrtc_stream_url,
+            "sdp": offer_sdp,
+        }
+
+        headers = {"Content-Type": "application/json"}
+
+        def _do_request():
+            return requests.post(
+                self.webrtc_api,
+                json=payload,
+                headers=headers,
+                timeout=10,
+            )
+
+        try:
+            loop = asyncio.get_running_loop()
+            resp = await loop.run_in_executor(None, _do_request)
+        except Exception as e:
+            print(
+                f"[CameraController] failed to send offer to media server: {e}",
+                file=sys.stderr,
+            )
+            raise
+
+        try:
+            resp.raise_for_status()
+        except Exception as e:
+            print(
+                f"[CameraController] media server HTTP error: {e}, "
+                f"status={resp.status_code}, body={resp.text[:200]}",
+                file=sys.stderr,
+            )
+            raise
+
+        try:
+            data = resp.json()
+        except Exception as e:
+            print(
+                f"[CameraController] failed to parse media server JSON: {e}, "
+                f"raw={resp.text[:200]}",
+                file=sys.stderr,
+            )
+            raise
+
+        answer_sdp = data.get("sdp", "")
+        if not answer_sdp:
+            msg = f"empty SDP from media server: {data}"
+            print(f"[CameraController] {msg}", file=sys.stderr)
+            raise RuntimeError(msg)
+
+        return answer_sdp
--- a/unilabos/devices/cameraSII/cameraUSB.py
+++ b/unilabos/devices/cameraSII/cameraUSB.py
@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+import asyncio
+import json
+import subprocess
+import sys
+import threading
+from typing import Optional, Dict, Any
+
+import requests
+import websockets
+
+
+class CameraController:
+    """
+    Uni-Lab-OS 摄像头驱动（Linux USB 摄像头版，无 PTZ）
+
+    - WebSocket 信令：signal_backend_url 连接到后端
+      例如: wss://sciol.ac.cn/api/realtime/signal/host/<host_id>
+    - 媒体服务器：RTMP 推流到 rtmp_url；WebRTC offer 转发到 SRS 的 webrtc_api
+    - 视频源：本地 USB 摄像头（V4L2，默认 /dev/video0）
+    """
+
+    def __init__(
+        self,
+        host_id: str = "demo-host",
+        signal_backend_url: str = "wss://sciol.ac.cn/api/realtime/signal/host",
+        rtmp_url: str = "rtmp://srs.sciol.ac.cn:4499/live/camera-01",
+        webrtc_api: str = "https://srs.sciol.ac.cn/rtc/v1/play/",
+        webrtc_stream_url: str = "webrtc://srs.sciol.ac.cn:4500/live/camera-01",
+        video_device: str = "/dev/video0",
+        width: int = 1280,
+        height: int = 720,
+        fps: int = 30,
+        video_bitrate: str = "1500k",
+        audio_device: Optional[str] = None,  # 比如 "hw:1,0"，没有音频就保持 None
+        audio_bitrate: str = "64k",
+    ):
+        self.host_id = host_id
+
+        # 拼接最终 WebSocket URL：.../host/<host_id>
+        signal_backend_url = signal_backend_url.rstrip("/")
+        if not signal_backend_url.endswith("/host"):
+            signal_backend_url = signal_backend_url + "/host"
+        self.signal_backend_url = f"{signal_backend_url}/{host_id}"
+
+        # 媒体服务器配置
+        self.rtmp_url = rtmp_url
+        self.webrtc_api = webrtc_api
+        self.webrtc_stream_url = webrtc_stream_url
+
+        # 本地采集配置
+        self.video_device = video_device
+        self.width = int(width)
+        self.height = int(height)
+        self.fps = int(fps)
+        self.video_bitrate = video_bitrate
+        self.audio_device = audio_device
+        self.audio_bitrate = audio_bitrate
+
+        # 运行时状态
+        self._ws: Optional[object] = None
+        self._ffmpeg_process: Optional[subprocess.Popen] = None
+        self._running = False
+        self._loop_task: Optional[asyncio.Future] = None
+
+        # 事件循环 & 线程
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._loop_thread: Optional[threading.Thread] = None
+
+        try:
+            self.start()
+        except Exception as e:
+            print(f"[CameraController] __init__ auto start failed: {e}", file=sys.stderr)
+
+    # ---------------------------------------------------------------------
+    # 对外方法
+    # ---------------------------------------------------------------------
+
+    def start(self, config: Optional[Dict[str, Any]] = None):
+        if self._running:
+            return {"status": "already_running", "host_id": self.host_id}
+
+        # 应用 config 覆盖（如果有）
+        if config:
+            cfg_host_id = config.get("host_id")
+            if cfg_host_id:
+                self.host_id = cfg_host_id
+
+            signal_backend_url = config.get("signal_backend_url")
+            if signal_backend_url:
+                signal_backend_url = signal_backend_url.rstrip("/")
+                if not signal_backend_url.endswith("/host"):
+                    signal_backend_url = signal_backend_url + "/host"
+                self.signal_backend_url = f"{signal_backend_url}/{self.host_id}"
+
+            self.rtmp_url = config.get("rtmp_url", self.rtmp_url)
+            self.webrtc_api = config.get("webrtc_api", self.webrtc_api)
+            self.webrtc_stream_url = config.get("webrtc_stream_url", self.webrtc_stream_url)
+
+            self.video_device = config.get("video_device", self.video_device)
+            self.width = int(config.get("width", self.width))
+            self.height = int(config.get("height", self.height))
+            self.fps = int(config.get("fps", self.fps))
+            self.video_bitrate = config.get("video_bitrate", self.video_bitrate)
+            self.audio_device = config.get("audio_device", self.audio_device)
+            self.audio_bitrate = config.get("audio_bitrate", self.audio_bitrate)
+
+        self._running = True
+
+        print("[CameraController] start(): starting FFmpeg streaming...", file=sys.stderr)
+        self._start_ffmpeg()
+
+        self._loop = asyncio.new_event_loop()
+
+        def loop_runner(loop: asyncio.AbstractEventLoop):
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_forever()
+            except Exception as e:
+                print(f"[CameraController] event loop error: {e}", file=sys.stderr)
+
+        self._loop_thread = threading.Thread(target=loop_runner, args=(self._loop,), daemon=True)
+        self._loop_thread.start()
+
+        self._loop_task = asyncio.run_coroutine_threadsafe(self._run_main_loop(), self._loop)
+
+        return {
+            "status": "started",
+            "host_id": self.host_id,
+            "signal_backend_url": self.signal_backend_url,
+            "rtmp_url": self.rtmp_url,
+            "webrtc_api": self.webrtc_api,
+            "webrtc_stream_url": self.webrtc_stream_url,
+            "video_device": self.video_device,
+            "width": self.width,
+            "height": self.height,
+            "fps": self.fps,
+            "video_bitrate": self.video_bitrate,
+            "audio_device": self.audio_device,
+        }
+
+    def stop(self) -> Dict[str, Any]:
+        self._running = False
+
+        # 先取消主任务（让 ws connect/sleep 尽快退出）
+        if self._loop_task is not None and not self._loop_task.done():
+            self._loop_task.cancel()
+
+        # 停止推流
+        self._stop_ffmpeg()
+
+        # 关闭 WebSocket（在 loop 中执行）
+        if self._ws and self._loop is not None:
+
+            async def close_ws():
+                try:
+                    await self._ws.close()
+                except Exception as e:
+                    print(f"[CameraController] error closing WebSocket: {e}", file=sys.stderr)
+
+            try:
+                asyncio.run_coroutine_threadsafe(close_ws(), self._loop)
+            except Exception:
+                pass
+
+        # 停止事件循环
+        if self._loop is not None:
+            try:
+                self._loop.call_soon_threadsafe(self._loop.stop)
+            except Exception as e:
+                print(f"[CameraController] error stopping loop: {e}", file=sys.stderr)
+
+        # 等待线程退出
+        if self._loop_thread is not None:
+            try:
+                self._loop_thread.join(timeout=5)
+            except Exception as e:
+                print(f"[CameraController] error joining loop thread: {e}", file=sys.stderr)
+
+        self._ws = None
+        self._loop_task = None
+        self._loop = None
+        self._loop_thread = None
+
+        return {"status": "stopped", "host_id": self.host_id}
+
+    def get_status(self) -> Dict[str, Any]:
+        ws_closed = None
+        if self._ws is not None:
+            ws_closed = getattr(self._ws, "closed", None)
+
+        if ws_closed is None:
+            websocket_connected = self._ws is not None
+        else:
+            websocket_connected = (self._ws is not None) and (not ws_closed)
+
+        return {
+            "host_id": self.host_id,
+            "running": self._running,
+            "websocket_connected": websocket_connected,
+            "ffmpeg_running": bool(self._ffmpeg_process and self._ffmpeg_process.poll() is None),
+            "signal_backend_url": self.signal_backend_url,
+            "rtmp_url": self.rtmp_url,
+            "video_device": self.video_device,
+            "width": self.width,
+            "height": self.height,
+            "fps": self.fps,
+            "video_bitrate": self.video_bitrate,
+        }
+
+    # ---------------------------------------------------------------------
+    # WebSocket / 信令
+    # ---------------------------------------------------------------------
+
+    async def _run_main_loop(self):
+        print("[CameraController] main loop started", file=sys.stderr)
+        try:
+            while self._running:
+                try:
+                    async with websockets.connect(self.signal_backend_url) as ws:
+                        self._ws = ws
+                        print(f"[CameraController] WebSocket connected: {self.signal_backend_url}", file=sys.stderr)
+                        await self._recv_loop()
+                except asyncio.CancelledError:
+                    raise
+                except Exception as e:
+                    if self._running:
+                        print(f"[CameraController] WebSocket connection error: {e}", file=sys.stderr)
+                        await asyncio.sleep(3)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            print("[CameraController] main loop exited", file=sys.stderr)
+
+    async def _recv_loop(self):
+        assert self._ws is not None
+        ws = self._ws
+
+        async for message in ws:
+            try:
+                data = json.loads(message)
+            except json.JSONDecodeError:
+                print(f"[CameraController] non-JSON message: {message}", file=sys.stderr)
+                continue
+
+            try:
+                await self._handle_message(data)
+            except Exception as e:
+                print(f"[CameraController] error handling message {data}: {e}", file=sys.stderr)
+
+    async def _handle_message(self, data: Dict[str, Any]):
+        cmd = data.get("command")
+
+        if cmd == "start_stream":
+            self._start_ffmpeg()
+            return
+
+        if cmd == "stop_stream":
+            self._stop_ffmpeg()
+            return
+
+        if data.get("type") == "offer":
+            offer_sdp = data.get("sdp", "")
+            camera_id = data.get("cameraId", "camera-01")
+
+            answer_sdp = await self._handle_webrtc_offer(offer_sdp)
+
+            if self._ws:
+                answer_payload = {
+                    "type": "answer",
+                    "sdp": answer_sdp,
+                    "cameraId": camera_id,
+                    "hostId": self.host_id,
+                }
+                await self._ws.send(json.dumps(answer_payload))
+
+    # ---------------------------------------------------------------------
+    # FFmpeg 推流（V4L2 USB 摄像头）
+    # ---------------------------------------------------------------------
+
+    def _start_ffmpeg(self):
+        if self._ffmpeg_process and self._ffmpeg_process.poll() is None:
+            return
+
+        # 兼容性优先：不强制输入像素格式；失败再通过外部调整 width/height/fps
+        video_size = f"{self.width}x{self.height}"
+
+        cmd = [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "warning",
+
+            # video input
+            "-f", "v4l2",
+            "-framerate", str(self.fps),
+            "-video_size", video_size,
+            "-i", self.video_device,
+        ]
+
+        # optional audio input
+        if self.audio_device:
+            cmd += [
+                "-f", "alsa",
+                "-i", self.audio_device,
+                "-c:a", "aac",
+                "-b:a", self.audio_bitrate,
+                "-ar", "44100",
+                "-ac", "1",
+            ]
+        else:
+            cmd += ["-an"]
+
+        # video encode + rtmp out
+        cmd += [
+            "-c:v", "libx264",
+            "-preset", "ultrafast",
+            "-tune", "zerolatency",
+            "-profile:v", "baseline",
+            "-pix_fmt", "yuv420p",
+            "-b:v", self.video_bitrate,
+            "-maxrate", self.video_bitrate,
+            "-bufsize", "2M",
+            "-g", str(max(self.fps, 10)),
+            "-keyint_min", str(max(self.fps, 10)),
+            "-sc_threshold", "0",
+            "-x264-params", "bframes=0",
+
+            "-f", "flv",
+            self.rtmp_url,
+        ]
+
+        print(f"[CameraController] starting FFmpeg: {' '.join(cmd)}", file=sys.stderr)
+
+        try:
+            # 不再丢弃日志，至少能看到 ffmpeg 报错（调试很关键）
+            self._ffmpeg_process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=sys.stderr,
+                shell=False,
+            )
+        except Exception as e:
+            self._ffmpeg_process = None
+            print(f"[CameraController] failed to start FFmpeg: {e}", file=sys.stderr)
+
+    def _stop_ffmpeg(self):
+        proc = self._ffmpeg_process
+        if proc and proc.poll() is None:
+            try:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+            except Exception as e:
+                print(f"[CameraController] error stopping FFmpeg: {e}", file=sys.stderr)
+        self._ffmpeg_process = None
+
+    # ---------------------------------------------------------------------
+    # WebRTC offer -> SRS
+    # ---------------------------------------------------------------------
+
+    async def _handle_webrtc_offer(self, offer_sdp: str) -> str:
+        payload = {
+            "api": self.webrtc_api,
+            "streamurl": self.webrtc_stream_url,
+            "sdp": offer_sdp,
+        }
+        headers = {"Content-Type": "application/json"}
+
+        def _do_post():
+            return requests.post(self.webrtc_api, json=payload, headers=headers, timeout=10)
+
+        loop = asyncio.get_running_loop()
+        resp = await loop.run_in_executor(None, _do_post)
+
+        resp.raise_for_status()
+        data = resp.json()
+        answer_sdp = data.get("sdp", "")
+        if not answer_sdp:
+            raise RuntimeError(f"empty SDP from media server: {data}")
+        return answer_sdp
+
+
+if __name__ == "__main__":
+    # 直接运行用于手动测试
+    c = CameraController(
+        host_id="demo-host",
+        video_device="/dev/video0",
+        width=1280,
+        height=720,
+        fps=30,
+        video_bitrate="1500k",
+        audio_device=None,
+    )
+    try:
+        while True:
+            asyncio.sleep(1)
+    except KeyboardInterrupt:
+        c.stop()
--- a/unilabos/devices/cameraSII/cameraUSB_test.py
+++ b/unilabos/devices/cameraSII/cameraUSB_test.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+import time
+import json
+
+from cameraUSB import CameraController
+
+
+def main():
+    # 按你的实际情况改
+    cfg = dict(
+        host_id="demo-host",
+        signal_backend_url="wss://sciol.ac.cn/api/realtime/signal/host",
+        rtmp_url="rtmp://srs.sciol.ac.cn:4499/live/camera-01",
+        webrtc_api="https://srs.sciol.ac.cn/rtc/v1/play/",
+        webrtc_stream_url="webrtc://srs.sciol.ac.cn:4500/live/camera-01",
+        video_device="/dev/video7",
+        width=1280,
+        height=720,
+        fps=30,
+        video_bitrate="1500k",
+        audio_device=None,
+    )
+
+    c = CameraController(**cfg)
+
+    # 可选：如果你不想依赖 __init__ 自动 start，可以这样显式调用：
+    # c = CameraController(host_id=cfg["host_id"])
+    # c.start(cfg)
+
+    run_seconds = 30  # 测试运行时长
+    t0 = time.time()
+
+    try:
+        while True:
+            st = c.get_status()
+            print(json.dumps(st, ensure_ascii=False, indent=2))
+
+            if time.time() - t0 >= run_seconds:
+                break
+
+            time.sleep(2)
+    except KeyboardInterrupt:
+        print("Interrupted, stopping...")
+    finally:
+        print("Stopping controller...")
+        c.stop()
+        print("Done.")
+
+
+if __name__ == "__main__":
+    main()
--- a/unilabos/devices/cameraSII/demo_camera_pic.py
+++ b/unilabos/devices/cameraSII/demo_camera_pic.py
@@ -0,0 +1,36 @@
+import cv2
+
+# 推荐把 @ 进行 URL 编码：@ -> %40
+RTSP_URL = "rtsp://admin:admin123@192.168.31.164:554/stream1"
+OUTPUT_IMAGE = "rtsp_test_frame.jpg"
+
+def main():
+    print(f"尝试连接 RTSP 流: {RTSP_URL}")
+    cap = cv2.VideoCapture(RTSP_URL)
+
+    if not cap.isOpened():
+        print("错误：无法打开 RTSP 流，请检查：")
+        print("  1. IP/端口是否正确")
+        print("  2. 账号密码（尤其是 @ 是否已转成 %40）是否正确")
+        print("  3. 摄像头是否允许当前主机访问（同一网段、防火墙等）")
+        return
+
+    print("连接成功，开始读取一帧...")
+    ret, frame = cap.read()
+
+    if not ret or frame is None:
+        print("错误：已连接但未能读取到帧数据（可能是码流未开启或网络抖动）")
+        cap.release()
+        return
+
+    # 保存当前帧
+    success = cv2.imwrite(OUTPUT_IMAGE, frame)
+    cap.release()
+
+    if success:
+        print(f"成功截取一帧并保存为: {OUTPUT_IMAGE}")
+    else:
+        print("错误：写入图片失败，请检查磁盘权限/路径")
+
+if __name__ == "__main__":
+    main()
--- a/unilabos/devices/cameraSII/demo_camera_push.py
+++ b/unilabos/devices/cameraSII/demo_camera_push.py
@@ -0,0 +1,21 @@
+# run_camera_push.py
+import time
+from cameraDriver import CameraController  # 这里根据你的文件名调整
+
+if __name__ == "__main__":
+    controller = CameraController(
+        host_id="demo-host",
+        signal_backend_url="wss://sciol.ac.cn/api/realtime/signal/host",
+        rtmp_url="rtmp://srs.sciol.ac.cn:4499/live/camera-01",
+        webrtc_api="https://srs.sciol.ac.cn/rtc/v1/play/",
+        webrtc_stream_url="webrtc://srs.sciol.ac.cn:4500/live/camera-01",
+        camera_rtsp_url="rtsp://admin:admin123@192.168.31.164:554/stream1",
+    )
+
+    try:
+        while True:
+            status = controller.get_status()
+            print(status)
+            time.sleep(5)
+    except KeyboardInterrupt:
+        controller.stop()
--- a/unilabos/devices/cameraSII/ptz_cameracontroller_test.py
+++ b/unilabos/devices/cameraSII/ptz_cameracontroller_test.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+使用 CameraController 来测试 PTZ：
+让摄像头按顺序向下、向上、向左、向右运动几次。
+"""
+
+import time
+import sys
+
+# 根据你的工程结构修改导入路径：
+# 假设 CameraController 定义在 cameraController.py 里
+from cameraDriver import CameraController
+
+
+def main():
+    # === 根据你的实际情况填 IP、端口、账号密码 ===
+    ptz_host = "192.168.31.164"
+    ptz_port = 2020          # 注意要和你单独测试 PTZController 时保持一致
+    ptz_user = "admin"
+    ptz_password = "admin123"
+
+    # 1. 创建 CameraController 实例
+    cam = CameraController(
+        # 其他摄像机相关参数按你类的 __init__ 来补充
+        ptz_host=ptz_host,
+        ptz_port=ptz_port,
+        ptz_user=ptz_user,
+        ptz_password=ptz_password,
+    )
+
+    # 2. 启动 / 初始化（如果你的 CameraController 有 start(config) 之类的接口）
+    #    这里给一个最小的 config，重点是 PTZ 相关字段
+    config = {
+        "ptz_host": ptz_host,
+        "ptz_port": ptz_port,
+        "ptz_user": ptz_user,
+        "ptz_password": ptz_password,
+    }
+
+    try:
+        cam.start(config)
+    except Exception as e:
+        print(f"[TEST] CameraController start() 失败: {e}", file=sys.stderr)
+        return
+
+    # 这里可以判断一下内部 _ptz 是否初始化成功（如果你对 CameraController 做了封装）
+    if getattr(cam, "_ptz", None) is None:
+        print("[TEST] CameraController 内部 PTZ 未初始化成功，请检查 ptz_host/port/user/password 配置。", file=sys.stderr)
+        return
+
+    # 3. 依次调用 CameraController 的 PTZ 方法
+    #    这里假设你在 CameraController 中提供了这几个对外方法：
+    #    ptz_move_down / ptz_move_up / ptz_move_left / ptz_move_right
+    #    如果你命名不一样，把下面调用名改成你的即可。
+
+    print("向下移动（通过 CameraController）...")
+    cam.ptz_move_down(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向上移动（通过 CameraController）...")
+    cam.ptz_move_up(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向左移动（通过 CameraController）...")
+    cam.ptz_move_left(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向右移动（通过 CameraController）...")
+    cam.ptz_move_right(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("测试结束。")
+
+
+if __name__ == "__main__":
+    main()
--- a/unilabos/devices/cameraSII/ptz_test.py
+++ b/unilabos/devices/cameraSII/ptz_test.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+测试 cameraDriver.py中的 PTZController 类，让摄像头按顺序运动几次
+"""
+
+import time
+
+from cameraDriver import PTZController
+
+
+def main():
+    # 根据你的实际情况填 IP、端口、账号密码
+    host = "192.168.31.164"
+    port = 80
+    user = "admin"
+    password = "admin123"
+
+    ptz = PTZController(host=host, port=port, user=user, password=password)
+
+    # 1. 连接摄像头
+    if not ptz.connect():
+        print("连接 PTZ 失败，检查 IP/用户名/密码/端口。")
+        return
+
+    # 2. 依次测试几个动作
+    # 每个动作之间 sleep 一下方便观察
+
+    print("向下移动...")
+    ptz.move_down(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向上移动...")
+    ptz.move_up(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向左移动...")
+    ptz.move_left(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("向右移动...")
+    ptz.move_right(speed=0.5, duration=1.0)
+    time.sleep(1)
+
+    print("测试结束。")
+
+
+if __name__ == "__main__":
+    main()
--- a/Show More
+++ b/Show More