Merge branch 'dev' into prcix9320

* add sample_material

* adapt to new samples sys

* fix pump transfer. fix resource update when protocol & ros callback

* Adapt to new scheduler.

.conda/base/recipe.yaml

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

.conda/environment/recipe.yaml

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

.conda/full/recipe.yaml

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

.conda/recipe.yaml

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

.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__

.github/workflows/ci-check.yml

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

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

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

.github/workflows/deploy-docs.yml

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

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

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

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

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

.gitignore

@@ -1,8 +1,11 @@
+cursor_docs/
 configs/
 temp/
 output/
 unilabos_data/
 pyrightconfig.json
+.cursorignore
+device_package*/
 ## Python
 
 # Byte-compiled / optimized / DLL files
@@ -249,3 +252,9 @@ ros-humble-unilabos-msgs-0.9.13-h6403a04_5.tar.bz2
 test_config.py
 
 
+/.claude
+/.conda
+/.cursor
+/.github
+/.conda/base
+.conda/base/recipe.yaml

AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Also follow the monorepo-level rules in `../AGENTS.md`.
+
+## Build & Development
+
+```bash
+# Install in editable mode (requires mamba env with python 3.11)
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+
+# Run with a device graph
+unilab --graph <graph.json> --config <config.py> --backend ros
+unilab --graph <graph.json> --config <config.py> --backend simple  # no ROS2 needed
+
+# Common CLI flags
+unilab --app_bridges websocket fastapi    # communication bridges
+unilab --test_mode                        # simulate hardware, no real execution
+unilab --check_mode                       # CI validation of registry imports
+unilab --skip_env_check                   # skip auto-install of dependencies
+unilab --visual rviz|web|disable          # visualization mode
+unilab --is_slave                         # run as slave node
+
+# Workflow upload subcommand
+unilab workflow_upload -f <workflow.json> -n <name> --tags tag1 tag2
+
+# Tests
+pytest tests/                              # all tests
+pytest tests/resources/test_resourcetreeset.py  # single test file
+pytest tests/resources/test_resourcetreeset.py::TestClassName::test_method  # single test
+```
+
+## Architecture
+
+### Startup Flow
+
+`unilab` CLI → `unilabos/app/main.py:main()` → loads config → builds registry → reads device graph (JSON/GraphML) → starts backend thread (ROS2/simple) → starts FastAPI web server + WebSocket client.
+
+### Core Layers
+
+**Registry** (`unilabos/registry/`): Singleton `Registry` class discovers and catalogs all device types, resource types, and communication devices from YAML definitions. Device types live in `registry/devices/*.yaml`, resources in `registry/resources/`, comms in `registry/device_comms/`. The registry resolves class paths to actual Python classes via `utils/import_manager.py`.
+
+**Resource Tracking** (`unilabos/resources/resource_tracker.py`): Pydantic-based `ResourceDict` → `ResourceDictInstance` → `ResourceTreeSet` hierarchy. `ResourceTreeSet` is the canonical in-memory representation of all devices and resources, used throughout the system. Graph I/O is in `resources/graphio.py` (reads JSON/GraphML device topology files into `nx.Graph` + `ResourceTreeSet`).
+
+**Device Drivers** (`unilabos/devices/`): 30+ hardware drivers organized by device type (liquid_handling, hplc, balance, arm, etc.). Each driver is a Python class that gets wrapped by `ros/device_node_wrapper.py:ros2_device_node()` to become a ROS2 node with publishers, subscribers, and action servers.
+
+**ROS2 Layer** (`unilabos/ros/`): `device_node_wrapper.py` dynamically wraps any device class into `ROS2DeviceNode` (defined in `ros/nodes/base_device_node.py`). Preset node types in `ros/nodes/presets/` include `host_node`, `controller_node`, `workstation`, `serial_node`, `camera`. Messages use custom `unilabos_msgs` (pre-built, distributed via releases).
+
+**Protocol Compilation** (`unilabos/compile/`): 20+ protocol compilers (add, centrifuge, dissolve, filter, heatchill, stir, pump, etc.) that transform YAML protocol definitions into executable sequences.
+
+**Communication** (`unilabos/device_comms/`): Hardware communication adapters — OPC-UA client, Modbus PLC, RPC, and a universal driver. `app/communication.py` provides a factory pattern for WebSocket client connections to the cloud.
+
+**Web/API** (`unilabos/app/web/`): FastAPI server with REST API (`api.py`), Jinja2 template pages (`pages.py`), and HTTP client for cloud communication (`client.py`). Runs on port 8002 by default.
+
+### Configuration System
+
+- **Config classes** in `unilabos/config/config.py`: `BasicConfig`, `WSConfig`, `HTTPConfig`, `ROSConfig` — all class-level attributes, loaded from Python config files
+- Config files are `.py` files with matching class names (see `config/example_config.py`)
+- Environment variables override with prefix `UNILABOS_` (e.g., `UNILABOS_BASICCONFIG_PORT=9000`)
+- Device topology defined in graph files (JSON with node-link format, or GraphML)
+
+### Key Data Flow
+
+1. Graph file → `graphio.read_node_link_json()` → `(nx.Graph, ResourceTreeSet, resource_links)`
+2. `ResourceTreeSet` + `Registry` → `initialize_device.initialize_device_from_dict()` → `ROS2DeviceNode` instances
+3. Device nodes communicate via ROS2 topics/actions or direct Python calls (simple backend)
+4. Cloud sync via WebSocket (`app/ws_client.py`) and HTTP (`app/web/client.py`)
+
+### Test Data
+
+Example device graphs and experiment configs are in `unilabos/test/experiments/` (not `tests/`). Registry test fixtures in `unilabos/test/registry/`.
+
+## Code Conventions
+
+- Code comments and log messages in simplified Chinese
+- Python 3.11+, type hints expected
+- Pydantic models for data validation (`resource_tracker.py`)
+- Singleton pattern via `@singleton` decorator (`utils/decorator.py`)
+- Dynamic class loading via `utils/import_manager.py` — device classes resolved at runtime from registry YAML paths
+- CLI argument dashes auto-converted to underscores for consistency
+
+## Licensing
+
+- Framework code: GPL-3.0
+- Device drivers (`unilabos/devices/`): DP Technology Proprietary License — do not redistribute

CLAUDE.md

@@ -0,0 +1,4 @@
+
+Please follow the rules defined in:
+
+@AGENTS.md

MANIFEST.in

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

NOTICE

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

README.md

@@ -8,17 +8,13 @@
 
 **English** | [中文](README_zh.md)
 
-[![GitHub Stars](https://img.shields.io/github/stars/dptech-corp/Uni-Lab-OS.svg)](https://github.com/dptech-corp/Uni-Lab-OS/stargazers)
+[![GitHub 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/dptech-corp/Uni-Lab-OS/network/members)
+[![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/dptech-corp/Uni-Lab-OS/issues)
+[![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/dptech-corp/Uni-Lab-OS/blob/main/LICENSE)
+[![GitHub License](https://img.shields.io/github/license/dptech-corp/Uni-Lab-OS.svg)](https://github.com/deepmodeling/Uni-Lab-OS/blob/main/LICENSE)
 
 Uni-Lab-OS is a platform for laboratory automation, designed to connect and control various experimental equipment, enabling automation and standardization of experimental workflows.
 
-## 🏆 Competition
-
-Join the [Intelligent Organic Chemistry Synthesis Competition](https://bohrium.dp.tech/competitions/1451645258) to explore automated synthesis with Uni-Lab-OS!
-
 ## Key Features
 
 - Multi-device integration management
@@ -31,41 +27,89 @@ Join the [Intelligent Organic Chemistry Synthesis Competition](https://bohrium.d
 
 Detailed documentation can be found at:
 
-- [Online Documentation](https://xuwznln.github.io/Uni-Lab-OS-Doc/)
+- [Online Documentation](https://deepmodeling.github.io/Uni-Lab-OS/)
 
 ## Quick Start
 
-Uni-Lab-OS recommends using `mamba` for environment management. Choose the appropriate environment file for your operating system:
+### 1. Setup Conda Environment
+
+Uni-Lab-OS recommends using `mamba` for environment management. Choose the package that fits your needs:
+
+| Package | Use Case | Contents |
+|---------|----------|----------|
+| `unilabos` | **Recommended for most users** | Complete package, ready to use |
+| `unilabos-env` | Developers (editable install) | Environment only, install unilabos via pip |
+| `unilabos-full` | Simulation/Visualization | unilabos + ROS2 Desktop + Gazebo + MoveIt |
 
 ```bash
 # Create new environment
-mamba create -n unilab python=3.11.11
+mamba create -n unilab python=3.11.14
 mamba activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# Option A: Standard installation (recommended for most users)
+mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+
+# Option B: For developers (editable mode development)
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+# Then install unilabos and dependencies:
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git && cd Uni-Lab-OS
+pip install -e .
+uv pip install -r unilabos/utils/requirements.txt
+
+# Option C: Full installation (simulation/visualization)
+mamba install uni-lab::unilabos-full -c robostack-staging -c conda-forge
 ```
 
-## Install Dev Uni-Lab-OS
+**When to use which?**
+- **unilabos**: Standard installation for production deployment and general usage (recommended)
+- **unilabos-env**: For developers who need `pip install -e .` editable mode, modify source code
+- **unilabos-full**: For simulation (Gazebo), visualization (rviz2), and Jupyter notebooks
+
+### 2. Clone Repository (Optional, for developers)
 
 ```bash
-# Clone the repository
+# Clone the repository (only needed for development or examples)
-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
 
@@ -77,4 +121,4 @@ This project is licensed under GPL-3.0 - see the [LICENSE](LICENSE) file for det
 
 ## Contact Us
 
-- GitHub Issues: [https://github.com/dptech-corp/Uni-Lab-OS/issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- GitHub Issues: [https://github.com/deepmodeling/Uni-Lab-OS/issues](https://github.com/deepmodeling/Uni-Lab-OS/issues)

README_zh.md

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

docs/conf.py

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

docs/developer_guide/add_device.md

@@ -15,6 +15,9 @@ Python 类设备驱动在完成注册表后可以直接在 Uni-Lab 中使用，
 **示例：**
 
 ```python
+from unilabos.registry.decorators import device, topic_config
+
+@device(id="mock_gripper", category=["gripper"], description="Mock Gripper")
 class MockGripper:
     def __init__(self):
         self._position: float = 0.0
@@ -23,19 +26,23 @@ class MockGripper:
         self._status = "Idle"
 
     @property
+    @topic_config()  # 添加 @topic_config 才会定时广播
     def position(self) -> float:
         return self._position
 
     @property
+    @topic_config()
     def velocity(self) -> float:
         return self._velocity
 
     @property
+    @topic_config()
     def torque(self) -> float:
         return self._torque
 
-    # 会被自动识别的设备属性，接入 Uni-Lab 时会定时对外广播
+    # 使用 @topic_config 装饰的属性，接入 Uni-Lab 时会定时对外广播
     @property
+    @topic_config(period=2.0)  # 可自定义发布周期
     def status(self) -> str:
         return self._status
 
@@ -149,7 +156,7 @@ my_device: # 设备唯一标识符
 
 系统会自动分析您的 Python 驱动类并生成：
 
-- `status_types`：从 `@property` 装饰的方法自动识别状态属性
+- `status_types`：从 `@topic_config` 装饰的 `@property` 或方法自动识别状态属性
 - `action_value_mappings`：从类方法自动生成动作映射
 - `init_param_schema`：从 `__init__` 方法分析初始化参数
 - `schema`：前端显示用的属性类型定义
@@ -179,7 +186,9 @@ Uni-Lab 设备驱动是一个 Python 类，需要遵循以下结构：
 
 ```python
 from typing import Dict, Any
+from unilabos.registry.decorators import device, topic_config
 
+@device(id="my_device", category=["general"], description="My Device")
 class MyDevice:
     """设备类文档字符串
 
@@ -198,8 +207,9 @@ class MyDevice:
         # 初始化硬件连接
 
     @property
+    @topic_config()  # 必须添加 @topic_config 才会广播
     def status(self) -> str:
-        """设备状态（会自动广播）"""
+        """设备状态（通过 @topic_config 广播）"""
         return self._status
 
     def my_action(self, param: float) -> Dict[str, Any]:
@@ -217,34 +227,61 @@ class MyDevice:
 
 ## 状态属性 vs 动作方法
 
-### 状态属性（@property）
+### 状态属性（@property + @topic_config）
 
-状态属性会被自动识别并定期广播：
+状态属性需要同时使用 `@property` 和 `@topic_config` 装饰器才会被识别并定期广播：
 
 ```python
+from unilabos.registry.decorators import topic_config
+
 @property
+@topic_config()  # 必须添加，否则不会广播
 def temperature(self) -> float:
     """当前温度"""
     return self._read_temperature()
 
 @property
+@topic_config(period=2.0)  # 可自定义发布周期（秒）
 def status(self) -> str:
     """设备状态: idle, running, error"""
     return self._status
 
 @property
+@topic_config(name="ready")  # 可自定义发布名称
 def is_ready(self) -> bool:
     """设备是否就绪"""
     return self._status == "idle"
 ```
 
+也可以使用普通方法（非 @property）配合 `@topic_config`：
+
+```python
+@topic_config(period=10.0)
+def get_sensor_data(self) -> Dict[str, float]:
+    """获取传感器数据（get_ 前缀会自动去除，发布名为 sensor_data）"""
+    return {"temp": self._temp, "humidity": self._humidity}
+```
+
+**`@topic_config` 参数**:
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `period` | float | 5.0 | 发布周期（秒） |
+| `print_publish` | bool | 节点默认 | 是否打印发布日志 |
+| `qos` | int | 10 | QoS 深度 |
+| `name` | str | None | 自定义发布名称 |
+
+**发布名称优先级**：`@topic_config(name=...)` > `get_` 前缀去除 > 方法名
+
 **特点**:
 
-- 使用`@property`装饰器
+- 必须使用 `@topic_config` 装饰器
-- 只读，不能有参数
+- 支持 `@property` 和普通方法
-- 自动添加到注册表的`status_types`
+- 添加到注册表的 `status_types`
 - 定期发布到 ROS2 topic
 
+> **⚠️ 重要：** 仅有 `@property` 装饰器而没有 `@topic_config` 的属性**不会**被广播。这是一个 Breaking Change。
+
 ### 动作方法
 
 动作方法是设备可以执行的操作：
@@ -497,6 +534,7 @@ class LiquidHandler:
         self._status = "idle"
 
     @property
+    @topic_config()
     def status(self) -> str:
         return self._status
 
@@ -886,7 +924,52 @@ class MyDevice:
 
 ## 最佳实践
 
-### 1. 类型注解
+### 1. 使用 `@device` 装饰器标识设备类
+
+```python
+from unilabos.registry.decorators import device
+
+@device(id="my_device", category=["heating"], description="My Heating Device", icon="heater.webp")
+class MyDevice:
+    ...
+```
+
+- `id`：设备唯一标识符，用于注册表匹配
+- `category`：分类列表，前端用于分组显示
+- `description`：设备描述
+- `icon`：图标文件名（可选）
+
+### 2. 使用 `@topic_config` 声明需要广播的状态
+
+```python
+from unilabos.registry.decorators import topic_config
+
+# ✓ @property + @topic_config → 会广播
+@property
+@topic_config(period=2.0)
+def temperature(self) -> float:
+    return self._temp
+
+# ✓ 普通方法 + @topic_config → 会广播（get_ 前缀自动去除）
+@topic_config(period=10.0)
+def get_sensor_data(self) -> Dict[str, float]:
+    return {"temp": self._temp}
+
+# ✓ 使用 name 参数自定义发布名称
+@property
+@topic_config(name="ready")
+def is_ready(self) -> bool:
+    return self._status == "idle"
+
+# ✗ 仅有 @property，没有 @topic_config → 不会广播
+@property
+def internal_state(self) -> str:
+    return self._state
+```
+
+> **注意：** 与 `@property` 连用时，`@topic_config` 必须放在 `@property` 下面。
+
+### 3. 类型注解
 
 ```python
 from typing import Dict, Any, Optional, List
@@ -901,7 +984,7 @@ def method(
     pass
 ```
 
-### 2. 文档字符串
+### 4. 文档字符串
 
 ```python
 def method(self, param: float) -> Dict[str, Any]:
@@ -923,7 +1006,7 @@ def method(self, param: float) -> Dict[str, Any]:
     pass
 ```
 
-### 3. 配置验证
+### 5. 配置验证
 
 ```python
 def __init__(self, config: Dict[str, Any]):
@@ -937,7 +1020,7 @@ def __init__(self, config: Dict[str, Any]):
     self.baudrate = config['baudrate']
 ```
 
-### 4. 资源清理
+### 6. 资源清理
 
 ```python
 def __del__(self):
@@ -946,7 +1029,7 @@ def __del__(self):
         self.connection.close()
 ```
 
-### 5. 设计前端友好的返回值
+### 7. 设计前端友好的返回值
 
 **记住：返回值会直接显示在 Web 界面**
 

docs/developer_guide/add_registry.md

@@ -422,18 +422,20 @@ placeholder_keys:
 
 ### status_types
 
-系统会扫描你的 Python 类，从状态方法（property 或 get\_方法）自动生成这部分：
+系统会扫描你的 Python 类，从带有 `@topic_config` 装饰器的 `@property` 或方法自动生成这部分：
 
 ```yaml
 status_types:
-  current_temperature: float # 从 get_current_temperature() 或 @property current_temperature
+  current_temperature: float # 从 @topic_config 装饰的 @property 或方法
-  is_heating: bool # 从 get_is_heating() 或 @property is_heating
+  is_heating: bool
-  status: str # 从 get_status() 或 @property status
+  status: str
 ```
 
 **注意事项**：
 
-- 系统会查找所有 `get_` 开头的方法和 `@property` 装饰的属性
+- 仅有带 `@topic_config` 装饰器的 `@property` 或方法才会被识别为状态属性
+- 没有 `@topic_config` 的 `@property` 不会生成 status_types，也不会广播
+- `get_` 前缀的方法名会自动去除前缀（如 `get_temperature` → `temperature`）
 - 类型会自动转成相应的类型（如 `str`、`float`、`bool`）
 - 如果类型是 `Any`、`None` 或未知的，默认使用 `String`
 
@@ -537,11 +539,13 @@ class AdvancedLiquidHandler:
         self._temperature = 25.0
 
     @property
+    @topic_config()
     def status(self) -> str:
         """设备状态"""
         return self._status
 
     @property
+    @topic_config()
     def temperature(self) -> float:
         """当前温度"""
         return self._temperature
@@ -809,21 +813,23 @@ my_temperature_controller:
 你的设备类需要符合以下要求：
 
 ```python
-from unilabos.common.device_base import DeviceBase
+from unilabos.registry.decorators import device, topic_config
 
-class MyDevice(DeviceBase):
+@device(id="my_device", category=["temperature"], description="My Device")
+class MyDevice:
     def __init__(self, config):
         """初始化，参数会自动分析到 init_param_schema.config"""
-        super().__init__(config)
         self.port = config.get('port', '/dev/ttyUSB0')
 
-    # 状态方法（会自动生成到 status_types）
+    # 状态方法（必须添加 @topic_config 才会生成到 status_types 并广播）
     @property
+    @topic_config()
     def status(self):
         """返回设备状态"""
         return "idle"
 
     @property
+    @topic_config()
     def temperature(self):
         """返回当前温度"""
         return 25.0
@@ -1039,7 +1045,34 @@ resource.type      # "resource"
 
 ### 代码规范
 
-1. **始终使用类型注解**
+1. **使用 `@device` 装饰器标识设备类**
+
+```python
+from unilabos.registry.decorators import device
+
+@device(id="my_device", category=["heating"], description="My Device")
+class MyDevice:
+    ...
+```
+
+2. **使用 `@topic_config` 声明广播属性**
+
+```python
+from unilabos.registry.decorators import topic_config
+
+# ✓ 需要广播的状态属性
+@property
+@topic_config(period=2.0)
+def temperature(self) -> float:
+    return self._temp
+
+# ✗ 仅有 @property 不会广播
+@property
+def internal_counter(self) -> int:
+    return self._counter
+```
+
+3. **始终使用类型注解**
 
 ```python
 # ✓ 好
@@ -1051,7 +1084,7 @@ def method(self, resource, device):
     pass
 ```
 
-2. **提供有意义的参数名**
+4. **提供有意义的参数名**
 
 ```python
 # ✓ 好 - 清晰的参数名
@@ -1063,7 +1096,7 @@ def transfer(self, r1: ResourceSlot, r2: ResourceSlot):
     pass
 ```
 
-3. **使用 Optional 表示可选参数**
+5. **使用 Optional 表示可选参数**
 
 ```python
 from typing import Optional
@@ -1076,7 +1109,7 @@ def method(
     pass
 ```
 
-4. **添加详细的文档字符串**
+6. **添加详细的文档字符串**
 
 ```python
 def method(
@@ -1096,13 +1129,13 @@ def method(
     pass
 ```
 
-5. **方法命名规范**
+7. **方法命名规范**
 
-   - 状态方法使用 `@property` 装饰器或 `get_` 前缀
+   - 状态方法使用 `@property` + `@topic_config` 装饰器，或普通方法 + `@topic_config`
    - 动作方法使用动词开头
    - 保持命名清晰、一致
 
-6. **完善的错误处理**
+8. **完善的错误处理**
    - 实现完善的错误处理
    - 添加日志记录
    - 提供有意义的错误信息

docs/developer_guide/networking_overview.md

@@ -221,10 +221,10 @@ Laboratory A    Laboratory B
 
 ```bash
 # 实验室A
-unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+unilab --ak your_ak --sk your_sk --upload_registry
 
 # 实验室B
-unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+unilab --ak your_ak --sk your_sk --upload_registry
 ```
 
 ---

docs/requirements.txt

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

docs/user_guide/best_practice.md

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

docs/user_guide/graph_files.md

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

docs/user_guide/installation.md

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

docs/user_guide/launch.md

@@ -22,7 +22,6 @@ options:
   --is_slave            Run the backend as slave node (without host privileges).
   --slave_no_host       Skip waiting for host service in slave mode
   --upload_registry     Upload registry information when starting unilab
-  --use_remote_resource Use remote resources when starting unilab
   --config CONFIG       Configuration file path, supports .py format Python config files
   --port PORT           Port for web service information page
   --disable_browser     Disable opening information page on startup
@@ -85,7 +84,7 @@ Uni-Lab 的启动过程分为以下几个阶段：
 支持两种方式：
 
 - **本地文件**：使用 `-g` 指定图谱文件（支持 JSON 和 GraphML 格式）
-- **远程资源**：使用 `--use_remote_resource` 从云端获取
+- **远程资源**：不指定本地文件即可
 
 ### 7. 注册表构建
 
@@ -196,7 +195,7 @@ unilab --config path/to/your/config.py
 unilab --ak your_ak --sk your_sk -g path/to/graph.json --upload_registry
 
 # 使用远程资源启动
-unilab --ak your_ak --sk your_sk --use_remote_resource
+unilab --ak your_ak --sk your_sk
 
 # 更新注册表
 unilab --ak your_ak --sk your_sk --complete_registry

recipes/msgs/recipe.yaml

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

recipes/unilabos/recipe.yaml

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

scripts/create_readme.py

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

scripts/dev_install.py

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

setup.py

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

tests/__init__.py

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

tests/devices/__init__.py

@@ -0,0 +1 @@
+

tests/devices/liquid_handling/README.md

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

tests/devices/liquid_handling/__init__.py

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

tests/devices/liquid_handling/test_transfer_liquid.py

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

tests/devices/liquid_handling/unit_test.py

@@ -0,0 +1,547 @@
+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}))
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def test_one_to_one_single_channel_basic_calls():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(64))
+
+  sources = [DummyContainer(f"S{i}") for i in range(3)]
+  targets = [DummyContainer(f"T{i}") for i in range(3)]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=targets,
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=[1, 2, 3],
+      dis_vols=[4, 5, 6],
+      mix_times=None,  # 应该仍能执行（不 mix）
+    )
+  )
+
+  assert [c[0] for c in lh.calls].count("pick_up_tips") == 3
+  assert [c[0] for c in lh.calls].count("aspirate") == 3
+  assert [c[0] for c in lh.calls].count("dispense") == 3
+  assert [c[0] for c in lh.calls].count("discard_tips") == 3
+
+  # 每次 aspirate/dispense 都是单孔列表
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  assert aspirates[0]["resources"] == [sources[0]]
+  assert aspirates[0]["vols"] == [1.0]
+
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert dispenses[2]["resources"] == [targets[2]]
+  assert dispenses[2]["vols"] == [6.0]
+
+
+def test_one_to_one_single_channel_before_stage_mixes_prior_to_aspirate():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(16))
+
+  source = DummyContainer("S0")
+  target = DummyContainer("T0")
+
+  run(
+    lh.transfer_liquid(
+      sources=[source],
+      targets=[target],
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=[5],
+      dis_vols=[5],
+      mix_stage="before",
+      mix_times=1,
+      mix_vol=3,
+    )
+  )
+
+  aspirate_calls = [(idx, payload) for idx, (name, payload) in enumerate(lh.calls) if name == "aspirate"]
+  assert len(aspirate_calls) >= 2
+  mix_idx, mix_payload = aspirate_calls[0]
+  assert mix_payload["resources"] == [target]
+  assert mix_payload["vols"] == [3]
+  transfer_idx, transfer_payload = aspirate_calls[1]
+  assert transfer_payload["resources"] == [source]
+  assert mix_idx < transfer_idx
+
+
+def test_one_to_one_eight_channel_groups_by_8():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(256))
+
+  sources = [DummyContainer(f"S{i}") for i in range(16)]
+  targets = [DummyContainer(f"T{i}") for i in range(16)]
+  asp_vols = list(range(1, 17))
+  dis_vols = list(range(101, 117))
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=targets,
+      tip_racks=[],
+      use_channels=list(range(8)),
+      asp_vols=asp_vols,
+      dis_vols=dis_vols,
+      mix_times=0,  # 触发逻辑但不 mix
+    )
+  )
+
+  # 16 个任务 -> 2 组，每组 8 通道一起做
+  assert [c[0] for c in lh.calls].count("pick_up_tips") == 2
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert len(aspirates) == 2
+  assert len(dispenses) == 2
+
+  assert aspirates[0]["resources"] == sources[0:8]
+  assert aspirates[0]["vols"] == [float(v) for v in asp_vols[0:8]]
+  assert dispenses[1]["resources"] == targets[8:16]
+  assert dispenses[1]["vols"] == [float(v) for v in dis_vols[8:16]]
+
+
+def test_one_to_one_eight_channel_requires_multiple_of_8_targets():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(64))
+
+  sources = [DummyContainer(f"S{i}") for i in range(9)]
+  targets = [DummyContainer(f"T{i}") for i in range(9)]
+
+  with pytest.raises(ValueError, match="multiple of 8"):
+    run(
+      lh.transfer_liquid(
+        sources=sources,
+        targets=targets,
+        tip_racks=[],
+        use_channels=list(range(8)),
+        asp_vols=[1] * 9,
+        dis_vols=[1] * 9,
+        mix_times=0,
+      )
+    )
+
+
+def test_one_to_one_eight_channel_parameter_lists_are_chunked_per_8():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(512))
+
+  sources = [DummyContainer(f"S{i}") for i in range(16)]
+  targets = [DummyContainer(f"T{i}") for i in range(16)]
+  asp_vols = [i + 1 for i in range(16)]
+  dis_vols = [200 + i for i in range(16)]
+  asp_flow_rates = [0.1 * (i + 1) for i in range(16)]
+  dis_flow_rates = [0.2 * (i + 1) for i in range(16)]
+  offsets = [f"offset_{i}" for i in range(16)]
+  liquid_heights = [i * 0.5 for i in range(16)]
+  blow_out_air_volume = [i + 0.05 for i in range(16)]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=targets,
+      tip_racks=[],
+      use_channels=list(range(8)),
+      asp_vols=asp_vols,
+      dis_vols=dis_vols,
+      asp_flow_rates=asp_flow_rates,
+      dis_flow_rates=dis_flow_rates,
+      offsets=offsets,
+      liquid_height=liquid_heights,
+      blow_out_air_volume=blow_out_air_volume,
+      mix_times=0,
+    )
+  )
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert len(aspirates) == len(dispenses) == 2
+
+  for batch_idx in range(2):
+    start = batch_idx * 8
+    end = start + 8
+    asp_call = aspirates[batch_idx]
+    dis_call = dispenses[batch_idx]
+    assert asp_call["resources"] == sources[start:end]
+    assert asp_call["flow_rates"] == asp_flow_rates[start:end]
+    assert asp_call["offsets"] == offsets[start:end]
+    assert asp_call["liquid_height"] == liquid_heights[start:end]
+    assert asp_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
+    assert dis_call["flow_rates"] == dis_flow_rates[start:end]
+    assert dis_call["offsets"] == offsets[start:end]
+    assert dis_call["liquid_height"] == liquid_heights[start:end]
+    assert dis_call["blow_out_air_volume"] == blow_out_air_volume[start:end]
+
+
+def test_one_to_one_eight_channel_handles_32_tasks_four_batches():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(1024))
+
+  sources = [DummyContainer(f"S{i}") for i in range(32)]
+  targets = [DummyContainer(f"T{i}") for i in range(32)]
+  asp_vols = [i + 1 for i in range(32)]
+  dis_vols = [300 + i for i in range(32)]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=targets,
+      tip_racks=[],
+      use_channels=list(range(8)),
+      asp_vols=asp_vols,
+      dis_vols=dis_vols,
+      mix_times=0,
+    )
+  )
+
+  pick_calls = [name for name, _ in lh.calls if name == "pick_up_tips"]
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert len(pick_calls) == 4
+  assert len(aspirates) == len(dispenses) == 4
+  assert aspirates[0]["resources"] == sources[0:8]
+  assert aspirates[-1]["resources"] == sources[24:32]
+  assert dispenses[0]["resources"] == targets[0:8]
+  assert dispenses[-1]["resources"] == targets[24:32]
+
+
+def test_one_to_many_single_channel_aspirates_total_when_asp_vol_too_small():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(64))
+
+  source = DummyContainer("SRC")
+  targets = [DummyContainer(f"T{i}") for i in range(3)]
+  dis_vols = [10, 20, 30]  # sum=60
+
+  run(
+    lh.transfer_liquid(
+      sources=[source],
+      targets=targets,
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=10,  # 小于 sum(dis_vols) -> 应吸 60
+      dis_vols=dis_vols,
+      mix_times=0,
+    )
+  )
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  assert len(aspirates) == 1
+  assert aspirates[0]["resources"] == [source]
+  assert aspirates[0]["vols"] == [60.0]
+  assert aspirates[0]["use_channels"] == [0]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert [d["vols"][0] for d in dispenses] == [10.0, 20.0, 30.0]
+
+
+def test_one_to_many_eight_channel_basic():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(128))
+
+  source = DummyContainer("SRC")
+  targets = [DummyContainer(f"T{i}") for i in range(8)]
+  dis_vols = [i + 1 for i in range(8)]
+
+  run(
+    lh.transfer_liquid(
+      sources=[source],
+      targets=targets,
+      tip_racks=[],
+      use_channels=list(range(8)),
+      asp_vols=999,  # one-to-many 8ch 会按 dis_vols 吸（每通道各自）
+      dis_vols=dis_vols,
+      mix_times=0,
+    )
+  )
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  assert aspirates[0]["resources"] == [source] * 8
+  assert aspirates[0]["vols"] == [float(v) for v in dis_vols]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert dispenses[0]["resources"] == targets
+  assert dispenses[0]["vols"] == [float(v) for v in dis_vols]
+
+
+def test_many_to_one_single_channel_standard_dispense_equals_asp_by_default():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(128))
+
+  sources = [DummyContainer(f"S{i}") for i in range(3)]
+  target = DummyContainer("T")
+  asp_vols = [5, 6, 7]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=[target],
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=asp_vols,
+      dis_vols=1,  # many-to-one 允许标量；非比例模式下实际每次分液=对应 asp_vol
+      mix_times=0,
+    )
+  )
+
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert [d["vols"][0] for d in dispenses] == [float(v) for v in asp_vols]
+  assert all(d["resources"] == [target] for d in dispenses)
+
+
+def test_many_to_one_single_channel_before_stage_mixes_target_once():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(128))
+
+  sources = [DummyContainer("S0"), DummyContainer("S1")]
+  target = DummyContainer("T")
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=[target],
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=[5, 6],
+      dis_vols=1,
+      mix_stage="before",
+      mix_times=2,
+      mix_vol=4,
+    )
+  )
+
+  aspirate_calls = [(idx, payload) for idx, (name, payload) in enumerate(lh.calls) if name == "aspirate"]
+  assert len(aspirate_calls) >= 1
+  mix_idx, mix_payload = aspirate_calls[0]
+  assert mix_payload["resources"] == [target]
+  assert mix_payload["vols"] == [4]
+  # 第一個 mix 之後會真正開始吸 source
+  assert any(call["resources"] == [sources[0]] for _, call in aspirate_calls[1:])
+
+
+def test_many_to_one_single_channel_proportional_mixing_uses_dis_vols_per_source():
+  lh = FakeLiquidHandler(channel_num=1)
+  lh.current_tip = iter(make_tip_iter(128))
+
+  sources = [DummyContainer(f"S{i}") for i in range(3)]
+  target = DummyContainer("T")
+  asp_vols = [5, 6, 7]
+  dis_vols = [1, 2, 3]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=[target],
+      tip_racks=[],
+      use_channels=[0],
+      asp_vols=asp_vols,
+      dis_vols=dis_vols,  # 比例模式
+      mix_times=0,
+    )
+  )
+
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert [d["vols"][0] for d in dispenses] == [float(v) for v in dis_vols]
+
+
+def test_many_to_one_eight_channel_basic():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(256))
+
+  sources = [DummyContainer(f"S{i}") for i in range(8)]
+  target = DummyContainer("T")
+  asp_vols = [10 + i for i in range(8)]
+
+  run(
+    lh.transfer_liquid(
+      sources=sources,
+      targets=[target],
+      tip_racks=[],
+      use_channels=list(range(8)),
+      asp_vols=asp_vols,
+      dis_vols=999,  # 非比例模式下每通道分液=对应 asp_vol
+      mix_times=0,
+    )
+  )
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert aspirates[0]["resources"] == sources
+  assert aspirates[0]["vols"] == [float(v) for v in asp_vols]
+  assert dispenses[0]["resources"] == [target] * 8
+  assert dispenses[0]["vols"] == [float(v) for v in asp_vols]
+
+
+def test_transfer_liquid_mode_detection_unsupported_shape_raises():
+  lh = FakeLiquidHandler(channel_num=8)
+  lh.current_tip = iter(make_tip_iter(64))
+
+  sources = [DummyContainer("S0"), DummyContainer("S1")]
+  targets = [DummyContainer("T0"), DummyContainer("T1"), DummyContainer("T2")]
+
+  with pytest.raises(ValueError, match="Unsupported transfer mode"):
+    run(
+      lh.transfer_liquid(
+        sources=sources,
+        targets=targets,
+        tip_racks=[],
+        use_channels=[0],
+        asp_vols=[1, 1],
+        dis_vols=[1, 1, 1],
+        mix_times=0,
+      )
+    )
+
+
+def test_mix_single_target_produces_matching_cycles():
+  lh = FakeLiquidHandler(channel_num=1)
+  target = DummyContainer("T_mix")
+
+  run(lh.mix(targets=[target], mix_time=2, mix_vol=5))
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  dispenses = [payload for name, payload in lh.calls if name == "dispense"]
+  assert len(aspirates) == len(dispenses) == 2
+  assert all(call["resources"] == [target] for call in aspirates)
+  assert all(call["vols"] == [5] for call in aspirates)
+  assert all(call["resources"] == [target] for call in dispenses)
+  assert all(call["vols"] == [5] for call in dispenses)
+
+
+def test_mix_multiple_targets_supports_per_target_offsets():
+  lh = FakeLiquidHandler(channel_num=1)
+  targets = [DummyContainer("T0"), DummyContainer("T1")]
+  offsets = ["left", "right"]
+  heights = [0.1, 0.2]
+  rates = [0.5, 1.0]
+
+  run(
+    lh.mix(
+      targets=targets,
+      mix_time=1,
+      mix_vol=3,
+      offsets=offsets,
+      height_to_bottom=heights,
+      mix_rate=rates,
+    )
+  )
+
+  aspirates = [payload for name, payload in lh.calls if name == "aspirate"]
+  assert len(aspirates) == 2
+  assert aspirates[0]["resources"] == [targets[0]]
+  assert aspirates[0]["offsets"] == [offsets[0]]
+  assert aspirates[0]["liquid_height"] == [heights[0]]
+  assert aspirates[0]["flow_rates"] == [rates[0]]
+  assert aspirates[1]["resources"] == [targets[1]]
+  assert aspirates[1]["offsets"] == [offsets[1]]
+  assert aspirates[1]["liquid_height"] == [heights[1]]
+  assert aspirates[1]["flow_rates"] == [rates[1]]
+
+

tests/resources/test_resourcetreeset.py

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

tests/ros/msgs/test_runner.py

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

tests/workflow/test.json

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

unilabos/__init__.py

@@ -1 +1 @@
-__version__ = "0.10.12"
+__version__ = "0.10.19"

unilabos/app/backend.py

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

unilabos/app/main.py

@@ -1,13 +1,14 @@
 import argparse
 import asyncio
 import os
+import platform
 import shutil
 import signal
+import subprocess
 import sys
 import threading
 import time
 from typing import Dict, Any, List
-
 import networkx as nx
 import yaml
 
@@ -17,9 +18,92 @@ unilabos_dir = os.path.dirname(os.path.dirname(current_dir))
 if unilabos_dir not in sys.path:
     sys.path.append(unilabos_dir)
 
+from unilabos.app.utils import cleanup_for_restart
 from unilabos.utils.banner_print import print_status, print_unilab_banner
 from unilabos.config.config import load_config, BasicConfig, HTTPConfig
 
+# Global restart flags (used by ws_client and web/server)
+_restart_requested: bool = False
+_restart_reason: str = ""
+
+RESTART_EXIT_CODE = 42
+
+
+def _build_child_argv():
+    """Build sys.argv for child process, stripping supervisor-only arguments."""
+    result = []
+    skip_next = False
+    for arg in sys.argv:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg in ("--restart_mode", "--restart-mode"):
+            continue
+        if arg in ("--auto_restart_count", "--auto-restart-count"):
+            skip_next = True
+            continue
+        if arg.startswith("--auto_restart_count=") or arg.startswith("--auto-restart-count="):
+            continue
+        result.append(arg)
+    return result
+
+
+def _run_as_supervisor(max_restarts: int):
+    """
+    Supervisor process that spawns and monitors child processes.
+
+    Similar to Uvicorn's --reload: the supervisor itself does no heavy work,
+    it only launches the real process as a child and restarts it when the child
+    exits with RESTART_EXIT_CODE.
+    """
+    child_argv = [sys.executable] + _build_child_argv()
+    restart_count = 0
+
+    print_status(
+        f"[Supervisor] Restart mode enabled (max restarts: {max_restarts}), "
+        f"child command: {' '.join(child_argv)}",
+        "info",
+    )
+
+    while True:
+        print_status(
+            f"[Supervisor] Launching process (restart {restart_count}/{max_restarts})...",
+            "info",
+        )
+
+        try:
+            process = subprocess.Popen(child_argv)
+            exit_code = process.wait()
+        except KeyboardInterrupt:
+            print_status("[Supervisor] Interrupted, terminating child process...", "info")
+            process.terminate()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+            sys.exit(1)
+
+        if exit_code == RESTART_EXIT_CODE:
+            restart_count += 1
+            if restart_count > max_restarts:
+                print_status(
+                    f"[Supervisor] Maximum restart count ({max_restarts}) reached, exiting",
+                    "warning",
+                )
+                sys.exit(1)
+            print_status(
+                f"[Supervisor] Child requested restart ({restart_count}/{max_restarts}), restarting in 2s...",
+                "info",
+            )
+            time.sleep(2)
+        else:
+            if exit_code != 0:
+                print_status(f"[Supervisor] Child exited with code {exit_code}", "warning")
+            else:
+                print_status("[Supervisor] Child exited normally", "info")
+            sys.exit(exit_code)
+
 
 def load_config_from_file(config_path):
     if config_path is None:
@@ -61,6 +145,13 @@ def parse_args():
         action="append",
         help="Path to the registry directory",
     )
+    parser.add_argument(
+        "--devices",
+        type=str,
+        default=None,
+        action="append",
+        help="Path to Python code directory for AST-based device/resource scanning",
+    )
     parser.add_argument(
         "--working_dir",
         type=str,
@@ -150,11 +241,52 @@ def parse_args():
         action="store_true",
         help="Skip environment dependency check on startup",
     )
+    parser.add_argument(
+        "--check_mode",
+        action="store_true",
+        default=False,
+        help="Run in check mode for CI: validates registry imports and ensures no file changes",
+    )
     parser.add_argument(
         "--complete_registry",
         action="store_true",
         default=False,
-        help="Complete registry information",
+        help="Complete and rewrite YAML registry files using AST analysis results",
+    )
+    parser.add_argument(
+        "--no_update_feedback",
+        action="store_true",
+        help="Disable sending update feedback to server",
+    )
+    parser.add_argument(
+        "--test_mode",
+        action="store_true",
+        default=False,
+        help="Test mode: all actions simulate execution and return mock results without running real hardware",
+    )
+    parser.add_argument(
+        "--external_devices_only",
+        action="store_true",
+        default=False,
+        help="Only load external device packages (--devices), skip built-in unilabos/devices/ scanning and YAML device registry",
+    )
+    parser.add_argument(
+        "--extra_resource",
+        action="store_true",
+        default=False,
+        help="Load extra lab_ prefixed labware resources (529 auto-generated definitions from lab_resources.py)",
+    )
+    parser.add_argument(
+        "--restart_mode",
+        action="store_true",
+        default=False,
+        help="Enable supervisor mode: automatically restart the process when triggered via WebSocket",
+    )
+    parser.add_argument(
+        "--auto_restart_count",
+        type=int,
+        default=500,
+        help="Maximum number of automatic restarts in restart mode (default: 500)",
     )
     # workflow upload subcommand
     workflow_parser = subparsers.add_parser(
@@ -189,6 +321,12 @@ def parse_args():
         default=False,
         help="Whether to publish the workflow (default: False)",
     )
+    workflow_parser.add_argument(
+        "--description",
+        type=str,
+        default="",
+        help="Workflow description, used when publishing the workflow",
+    )
     return parser
 
 
@@ -200,61 +338,102 @@ def main():
     args = parser.parse_args()
     args_dict = vars(args)
 
+    # Supervisor mode: spawn child processes and monitor for restart
+    if args_dict.get("restart_mode", False):
+        _run_as_supervisor(args_dict.get("auto_restart_count", 5))
+        return
+
     # 环境检查 - 检查并自动安装必需的包 (可选)
-    if not args_dict.get("skip_env_check", False):
+    skip_env_check = args_dict.get("skip_env_check", False)
-        from unilabos.utils.environment_check import check_environment
+    check_mode = args_dict.get("check_mode", False)
+
+    if not skip_env_check:
+        from unilabos.utils.environment_check import check_environment, check_device_package_requirements
 
         if not check_environment(auto_install=True):
             print_status("环境检查失败，程序退出", "error")
             os._exit(1)
+
+        # 第一次设备包依赖检查：build_registry 之前，确保 import map 可用
+        devices_dirs_for_req = args_dict.get("devices", None)
+        if devices_dirs_for_req:
+            if not check_device_package_requirements(devices_dirs_for_req):
+                print_status("设备包依赖检查失败，程序退出", "error")
+                os._exit(1)
     else:
         print_status("跳过环境依赖检查", "warning")
 
     # 加载配置文件，优先加载config，然后从env读取
     config_path = args_dict.get("config")
-    if os.getcwd().endswith("unilabos_data"):
-        working_dir = os.path.abspath(os.getcwd())
-    else:
-        working_dir = os.path.abspath(os.path.join(os.getcwd(), "unilabos_data"))
 
-    if args_dict.get("working_dir"):
+    # === 解析 working_dir ===
-        working_dir = args_dict.get("working_dir", "")
+    # 规则1: working_dir 传入 → 检测 unilabos_data 子目录，已是则不修改
-        if config_path and not os.path.exists(config_path):
+    # 规则2: 仅 config_path 传入 → 用其父目录作为 working_dir
-            config_path = os.path.join(working_dir, "local_config.py")
+    # 规则4: 两者都传入 → 各用各的，但 working_dir 仍做 unilabos_data 子目录检测
-            if not os.path.exists(config_path):
+    raw_working_dir = args_dict.get("working_dir")
-                print_status(
+    if raw_working_dir:
-                    f"当前工作目录 {working_dir} 未找到local_config.py，请通过 --config 传入 local_config.py 文件路径",
+        working_dir = os.path.abspath(raw_working_dir)
-                    "error",
-                )
-                os._exit(1)
     elif config_path and os.path.exists(config_path):
-        working_dir = os.path.dirname(config_path)
+        working_dir = os.path.dirname(os.path.abspath(config_path))
-    elif os.path.exists(working_dir) and os.path.exists(os.path.join(working_dir, "local_config.py")):
+    else:
-        config_path = os.path.join(working_dir, "local_config.py")
+        working_dir = os.path.abspath(os.getcwd())
-    elif not config_path and (
+
-        not os.path.exists(working_dir) or not os.path.exists(os.path.join(working_dir, "local_config.py"))
+    # unilabos_data 子目录自动检测
-    ):
+    if os.path.basename(working_dir) != "unilabos_data":
-        print_status(f"未指定config路径，可通过 --config 传入 local_config.py 文件路径", "info")
+        unilabos_data_sub = os.path.join(working_dir, "unilabos_data")
-        print_status(f"您是否为第一次使用？并将当前路径 {working_dir} 作为工作目录？ (Y/n)", "info")
+        if os.path.isdir(unilabos_data_sub):
-        if input() != "n":
+            working_dir = unilabos_data_sub
-            os.makedirs(working_dir, exist_ok=True)
+        elif not raw_working_dir and not (config_path and os.path.exists(config_path)):
-            config_path = os.path.join(working_dir, "local_config.py")
+            # 未显式指定路径，默认使用 cwd/unilabos_data
-            shutil.copy(
+            working_dir = os.path.abspath(os.path.join(os.getcwd(), "unilabos_data"))
-                os.path.join(os.path.dirname(os.path.dirname(__file__)), "config", "example_config.py"), config_path
+
-            )
+    # === 解析 config_path ===
-            print_status(f"已创建 local_config.py 路径： {config_path}", "info")
+    if config_path and not os.path.exists(config_path):
+        # config_path 传入但不存在，尝试在 working_dir 中查找
+        candidate = os.path.join(working_dir, "local_config.py")
+        if os.path.exists(candidate):
+            config_path = candidate
+            print_status(f"在工作目录中发现配置文件: {config_path}", "info")
         else:
+            print_status(
+                f"配置文件 {config_path} 不存在，工作目录 {working_dir} 中也未找到 local_config.py，"
+                f"请通过 --config 传入 local_config.py 文件路径",
+                "error",
+            )
             os._exit(1)
-    # 加载配置文件
+    elif not config_path:
+        # 规则3: 未传入 config_path，尝试 working_dir/local_config.py
+        candidate = os.path.join(working_dir, "local_config.py")
+        if os.path.exists(candidate):
+            config_path = candidate
+            print_status(f"发现本地配置文件: {config_path}", "info")
+        else:
+            print_status(f"未指定config路径，可通过 --config 传入 local_config.py 文件路径", "info")
+            print_status(f"您是否为第一次使用？并将当前路径 {working_dir} 作为工作目录？ (Y/n)", "info")
+            if check_mode or input() != "n":
+                os.makedirs(working_dir, exist_ok=True)
+                config_path = os.path.join(working_dir, "local_config.py")
+                shutil.copy(
+                    os.path.join(os.path.dirname(os.path.dirname(__file__)), "config", "example_config.py"),
+                    config_path,
+                )
+                print_status(f"已创建 local_config.py 路径： {config_path}", "info")
+            else:
+                os._exit(1)
+
+    # 加载配置文件 (check_mode 跳过)
     print_status(f"当前工作目录为 {working_dir}", "info")
-    load_config_from_file(config_path)
+    if not check_mode:
+        load_config_from_file(config_path)
 
     # 根据配置重新设置日志级别
     from unilabos.utils.log import configure_logger, logger
 
     if hasattr(BasicConfig, "log_level"):
         logger.info(f"Log level set to '{BasicConfig.log_level}' from config file.")
-    configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
+    file_path = configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
+    if file_path is not None:
+        logger.info(f"[LOG_FILE] {file_path}")
 
     if args.addr != parser.get_default("addr"):
         if args.addr == "test":
@@ -297,41 +476,67 @@ def main():
     BasicConfig.is_host_mode = not args_dict.get("is_slave", False)
     BasicConfig.slave_no_host = args_dict.get("slave_no_host", False)
     BasicConfig.upload_registry = args_dict.get("upload_registry", False)
+    BasicConfig.no_update_feedback = args_dict.get("no_update_feedback", False)
+    BasicConfig.test_mode = args_dict.get("test_mode", False)
+    if BasicConfig.test_mode:
+        print_status("启用测试模式：所有动作将模拟执行，不调用真实硬件", "warning")
+    BasicConfig.extra_resource = args_dict.get("extra_resource", False)
+    if BasicConfig.extra_resource:
+        print_status("启用额外资源加载：将加载lab_开头的labware资源定义", "info")
     BasicConfig.communication_protocol = "websocket"
-    machine_name = os.popen("hostname").read().strip()
+    machine_name = platform.node()
     machine_name = "".join([c if c.isalnum() or c == "_" else "_" for c in machine_name])
     BasicConfig.machine_name = machine_name
     BasicConfig.vis_2d_enable = args_dict["2d_vis"]
+    BasicConfig.check_mode = check_mode
 
-    from unilabos.resources.graphio import (
-        read_node_link_json,
-        read_graphml,
-        dict_from_graph,
-    )
-    from unilabos.app.communication import get_communication_client
     from unilabos.registry.registry import build_registry
-    from unilabos.app.backend import start_backend
-    from unilabos.app.web import http_client
-    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
 
     # 显示启动横幅
     print_unilab_banner(args_dict)
 
-    # 注册表
+    # Step 0: AST 分析优先 + YAML 注册表加载
+    # check_mode 和 upload_registry 都会执行实际 import 验证
+    devices_dirs = args_dict.get("devices", None)
+    complete_registry = args_dict.get("complete_registry", False) or check_mode
+    external_only = args_dict.get("external_devices_only", False)
     lab_registry = build_registry(
-        args_dict["registry_path"], args_dict.get("complete_registry", False), BasicConfig.upload_registry
+        registry_paths=args_dict["registry_path"],
+        devices_dirs=devices_dirs,
+        upload_registry=BasicConfig.upload_registry,
+        check_mode=check_mode,
+        complete_registry=complete_registry,
+        external_only=external_only,
     )
 
+    # Check mode: 注册表验证完成后直接退出
+    if check_mode:
+        device_count = len(lab_registry.device_type_registry)
+        resource_count = len(lab_registry.resource_type_registry)
+        print_status(f"Check mode: 注册表验证完成 ({device_count} 设备, {resource_count} 资源)，退出", "info")
+        os._exit(0)
+
+    # 以下导入依赖 ROS2 环境，check_mode 已退出不需要
+    from unilabos.resources.graphio import (
+        read_node_link_json,
+        read_graphml,
+        dict_from_graph,
+        modify_to_backend_format,
+    )
+    from unilabos.app.communication import get_communication_client
+    from unilabos.app.backend import start_backend
+    from unilabos.app.web import http_client
+    from unilabos.app.web import start_server
+    from unilabos.app.register import register_devices_and_resources
+    from unilabos.resources.resource_tracker import ResourceTreeSet, ResourceDict
+
+    # Step 1: 上传全部注册表到服务端，同步保存到 unilabos_data
     if BasicConfig.upload_registry:
-        # 设备注册到服务端 - 需要 ak 和 sk
         if BasicConfig.ak and BasicConfig.sk:
-            print_status("开始注册设备到服务端...", "info")
+            # print_status("开始注册设备到服务端...", "info")
             try:
                 register_devices_and_resources(lab_registry)
-                print_status("设备注册完成", "info")
+                # print_status("设备注册完成", "info")
             except Exception as e:
                 print_status(f"设备注册失败: {e}", "error")
         else:
@@ -416,12 +621,16 @@ def main():
             continue
 
     # 如果从远端获取了物料信息，则与本地物料进行同步
-    if request_startup_json and "nodes" in request_startup_json:
+    if file_path is not None and 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")
 
+    # 第二次设备包依赖检查：云端物料同步后，community 包可能引入新的 requirements
+    # TODO: 当 community device package 功能上线后，在这里调用
+    #   install_requirements_txt(community_pkg_path / "requirements.txt", label="community.xxx")
+
     # 使用 ResourceTreeSet 代替 list
     args_dict["resources_config"] = resource_tree_set
     args_dict["devices_config"] = resource_tree_set
@@ -497,16 +706,26 @@ def main():
                 time.sleep(1)
         else:
             start_backend(**args_dict)
-            start_server(
+            restart_requested = start_server(
                 open_browser=not args_dict["disable_browser"],
                 port=BasicConfig.port,
             )
+            if restart_requested:
+                print_status("[Main] Restart requested, cleaning up...", "info")
+                cleanup_for_restart()
+                return
     else:
         start_backend(**args_dict)
-        start_server(
+
+        # 启动服务器（默认支持WebSocket触发重启）
+        restart_requested = start_server(
             open_browser=not args_dict["disable_browser"],
             port=BasicConfig.port,
         )
+        if restart_requested:
+            print_status("[Main] Restart requested, cleaning up...", "info")
+            cleanup_for_restart()
+            os._exit(RESTART_EXIT_CODE)
 
 
 if __name__ == "__main__":

unilabos/app/model.py

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

unilabos/app/register.py

@@ -1,9 +1,8 @@
-import json
 import time
-from typing import Optional, Tuple, Dict, Any
+from typing import Any, Dict, Optional, Tuple
 
 from unilabos.utils.log import logger
-from unilabos.utils.type_check import TypeEncoder
+from unilabos.utils.tools import normalize_json as _normalize_device
 
 
 def register_devices_and_resources(lab_registry, gather_only=False) -> Optional[Tuple[Dict[str, Any], Dict[str, Any]]]:
@@ -11,50 +10,63 @@ def register_devices_and_resources(lab_registry, gather_only=False) -> Optional[
     注册设备和资源到服务器（仅支持HTTP）
     """
 
-    # 注册资源信息 - 使用HTTP方式
     from unilabos.app.web.client import http_client
 
     logger.info("[UniLab Register] 开始注册设备和资源...")
 
-    # 注册设备信息
     devices_to_register = {}
     for device_info in lab_registry.obtain_registry_device_info():
-        devices_to_register[device_info["id"]] = json.loads(
+        devices_to_register[device_info["id"]] = _normalize_device(device_info)
-            json.dumps(device_info, ensure_ascii=False, cls=TypeEncoder)
+        logger.trace(f"[UniLab Register] 收集设备: {device_info['id']}")
-        )
-        logger.debug(f"[UniLab Register] 收集设备: {device_info['id']}")
 
     resources_to_register = {}
     for resource_info in lab_registry.obtain_registry_resource_info():
         resources_to_register[resource_info["id"]] = resource_info
-        logger.debug(f"[UniLab Register] 收集资源: {resource_info['id']}")
+        logger.trace(f"[UniLab Register] 收集资源: {resource_info['id']}")
 
     if gather_only:
         return devices_to_register, resources_to_register
-    # 注册设备
+
     if devices_to_register:
         try:
             start_time = time.time()
-            response = http_client.resource_registry({"resources": list(devices_to_register.values())})
+            response = http_client.resource_registry(
+                {"resources": list(devices_to_register.values())},
+                tag="device_registry",
+            )
             cost_time = time.time() - start_time
-            if response.status_code in [200, 201]:
+            res_data = response.json() if response.status_code == 200 else {}
-                logger.info(f"[UniLab Register] 成功注册 {len(devices_to_register)} 个设备 {cost_time}ms")
+            skipped = res_data.get("data", {}).get("skipped", False)
+            if skipped:
+                logger.info(
+                    f"[UniLab Register] 设备注册跳过（内容未变化）"
+                    f" {len(devices_to_register)} 个 {cost_time:.3f}s"
+                )
+            elif response.status_code in [200, 201]:
+                logger.info(f"[UniLab Register] 成功注册 {len(devices_to_register)} 个设备 {cost_time:.3f}s")
             else:
-                logger.error(f"[UniLab Register] 设备注册失败: {response.status_code}, {response.text} {cost_time}ms")
+                logger.error(f"[UniLab Register] 设备注册失败: {response.status_code}, {response.text} {cost_time:.3f}s")
         except Exception as e:
             logger.error(f"[UniLab Register] 设备注册异常: {e}")
 
-    # 注册资源
     if resources_to_register:
         try:
             start_time = time.time()
-            response = http_client.resource_registry({"resources": list(resources_to_register.values())})
+            response = http_client.resource_registry(
+                {"resources": list(resources_to_register.values())},
+                tag="resource_registry",
+            )
             cost_time = time.time() - start_time
-            if response.status_code in [200, 201]:
+            res_data = response.json() if response.status_code == 200 else {}
-                logger.info(f"[UniLab Register] 成功注册 {len(resources_to_register)} 个资源 {cost_time}ms")
+            skipped = res_data.get("data", {}).get("skipped", False)
+            if skipped:
+                logger.info(
+                    f"[UniLab Register] 资源注册跳过（内容未变化）"
+                    f" {len(resources_to_register)} 个 {cost_time:.3f}s"
+                )
+            elif response.status_code in [200, 201]:
+                logger.info(f"[UniLab Register] 成功注册 {len(resources_to_register)} 个资源 {cost_time:.3f}s")
             else:
-                logger.error(f"[UniLab Register] 资源注册失败: {response.status_code}, {response.text} {cost_time}ms")
+                logger.error(f"[UniLab Register] 资源注册失败: {response.status_code}, {response.text} {cost_time:.3f}s")
         except Exception as e:
             logger.error(f"[UniLab Register] 资源注册异常: {e}")
-
-    logger.info("[UniLab Register] 设备和资源注册完成.")

unilabos/app/utils.py

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

unilabos/app/web/api.py

@@ -1052,7 +1052,7 @@ async def handle_file_import(websocket: WebSocket, request_data: dict):
                                 "result": {},
                                 "schema": lab_registry._generate_unilab_json_command_schema(v["args"], k),
                                 "goal_default": {i["name"]: i["default"] for i in v["args"]},
-                                "handles": [],
+                                "handles": {},
                             }
                             # 不生成已配置action的动作
                             for k, v in enhanced_info["action_methods"].items()
@@ -1340,5 +1340,5 @@ def setup_api_routes(app):
     # 启动广播任务
     @app.on_event("startup")
     async def startup_event():
-        asyncio.create_task(broadcast_device_status())
+        asyncio.create_task(broadcast_device_status(), name="web-api-startup-device")
-        asyncio.create_task(broadcast_status_page_data())
+        asyncio.create_task(broadcast_status_page_data(), name="web-api-startup-status")

unilabos/app/web/client.py

@@ -3,15 +3,15 @@ HTTP客户端模块
 
 提供与远程服务器通信的客户端功能，只有host需要用
 """
-
+import gzip
 import json
 import os
-import time
-from threading import Thread
 from typing import List, Dict, Any, Optional
 
+from unilabos.utils.tools import fast_dumps as _fast_dumps, fast_dumps_pretty as _fast_dumps_pretty
+
 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
@@ -282,22 +282,54 @@ class HTTPClient:
             )
         return response
 
-    def resource_registry(self, registry_data: Dict[str, Any] | List[Dict[str, Any]]) -> requests.Response:
+    def resource_registry(
+        self, registry_data: Dict[str, Any] | List[Dict[str, Any]], tag: str = "registry",
+    ) -> requests.Response:
         """
-        注册资源到服务器
+        注册资源到服务器，同步保存请求/响应到 unilabos_data
 
         Args:
             registry_data: 注册表数据，格式为 {resource_id: resource_info} / [{resource_info}]
+            tag: 保存文件的标签后缀 (如 "device_registry" / "resource_registry")
 
         Returns:
             Response: API响应对象
         """
+        # 序列化一次，同时用于保存和发送
+        json_bytes = _fast_dumps(registry_data)
+
+        # 保存请求数据到 unilabos_data
+        req_path = os.path.join(BasicConfig.working_dir, f"req_{tag}_upload.json")
+        try:
+            os.makedirs(BasicConfig.working_dir, exist_ok=True)
+            with open(req_path, "wb") as f:
+                f.write(_fast_dumps_pretty(registry_data))
+            logger.trace(f"注册表请求数据已保存: {req_path}")
+        except Exception as e:
+            logger.warning(f"保存注册表请求数据失败: {e}")
+
+        compressed_body = gzip.compress(json_bytes)
+        headers = {
+            "Authorization": f"Lab {self.auth}",
+            "Content-Type": "application/json",
+            "Content-Encoding": "gzip",
+        }
         response = requests.post(
             f"{self.remote_addr}/lab/resource",
-            json=registry_data,
+            data=compressed_body,
-            headers={"Authorization": f"Lab {self.auth}"},
+            headers=headers,
             timeout=30,
         )
+
+        # 保存响应数据到 unilabos_data
+        res_path = os.path.join(BasicConfig.working_dir, f"res_{tag}_upload.json")
+        try:
+            with open(res_path, "w", encoding="utf-8") as f:
+                f.write(f"{response.status_code}\n{response.text}")
+            logger.trace(f"注册表响应数据已保存: {res_path}")
+        except Exception as e:
+            logger.warning(f"保存注册表响应数据失败: {e}")
+
         if response.status_code not in [200, 201]:
             logger.error(f"注册资源失败: {response.status_code}, {response.text}")
         if response.status_code == 200:
@@ -345,9 +377,10 @@ class HTTPClient:
         edges: List[Dict[str, Any]],
         tags: Optional[List[str]] = None,
         published: bool = False,
+        description: str = "",
     ) -> Dict[str, Any]:
         """
-        导入工作流到服务器
+        导入工作流到服务器，如果 published 为 True，则额外发起发布请求
 
         Args:
             name: 工作流名称（顶层）
@@ -357,13 +390,12 @@ class HTTPClient:
             edges: 工作流边列表
             tags: 工作流标签列表，默认为空列表
             published: 是否发布工作流，默认为False
+            description: 工作流描述，发布时使用
 
         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,
@@ -371,7 +403,6 @@ class HTTPClient:
                 "nodes": nodes,
                 "edges": edges,
                 "tags": tags if tags is not None else [],
-                "published": published,
             },
         }
         # 保存请求到文件
@@ -392,11 +423,51 @@ class HTTPClient:
             res = response.json()
             if "code" in res and res["code"] != 0:
                 logger.error(f"导入工作流失败: {response.text}")
+                return res
+            # 导入成功后，如果需要发布则额外发起发布请求
+            if published:
+                imported_uuid = res.get("data", {}).get("uuid", workflow_uuid)
+                publish_res = self.workflow_publish(imported_uuid, description)
+                res["publish_result"] = publish_res
             return res
         else:
             logger.error(f"导入工作流失败: {response.status_code}, {response.text}")
             return {"code": response.status_code, "message": response.text}
 
+    def workflow_publish(self, workflow_uuid: str, description: str = "") -> Dict[str, Any]:
+        """
+        发布工作流
+
+        Args:
+            workflow_uuid: 工作流UUID
+            description: 工作流描述
+
+        Returns:
+            Dict: API响应数据
+        """
+        payload = {
+            "uuid": workflow_uuid,
+            "description": description,
+            "published": True,
+        }
+        logger.info(f"正在发布工作流: {workflow_uuid}")
+        response = requests.patch(
+            f"{self.remote_addr}/lab/workflow/owner",
+            json=payload,
+            headers={"Authorization": f"Lab {self.auth}"},
+            timeout=60,
+        )
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"发布工作流失败: {response.text}")
+            else:
+                logger.info(f"工作流发布成功: {workflow_uuid}")
+            return res
+        else:
+            logger.error(f"发布工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+
 
 # 创建默认客户端实例
 http_client = HTTPClient()

unilabos/app/web/controller.py

@@ -327,6 +327,7 @@ def job_add(req: JobAddReq) -> JobData:
             queue_item,
             action_type=action_type,
             action_kwargs=action_args,
+            sample_material=req.sample_material,
             server_info=server_info,
         )
 

unilabos/app/web/server.py

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

unilabos/app/ws_client.py

@@ -23,9 +23,10 @@ from typing import Optional, Dict, Any, List
 from urllib.parse import urlparse
 from enum import Enum
 
-from jedi.inference.gradual.typing import TypedDict
+from typing_extensions import TypedDict
 
 from unilabos.app.model import JobAddReq
+from unilabos.resources.resource_tracker import ResourceDictType
 from unilabos.ros.nodes.presets.host_node import HostNode
 from unilabos.utils.type_check import serialize_result_info
 from unilabos.app.communication import BaseCommunicationClient
@@ -76,6 +77,7 @@ class JobInfo:
     start_time: float
     last_update_time: float = field(default_factory=time.time)
     ready_timeout: Optional[float] = None  # READY状态的超时时间
+    always_free: bool = False  # 是否为永久闲置动作(不受排队限制)
 
     def update_timestamp(self):
         """更新最后更新时间"""
@@ -127,6 +129,15 @@ class DeviceActionManager:
             # 总是将job添加到all_jobs中
             self.all_jobs[job_info.job_id] = job_info
 
+            # always_free的动作不受排队限制，直接设为READY
+            if job_info.always_free:
+                job_info.status = JobStatus.READY
+                job_info.update_timestamp()
+                job_info.set_ready_timeout(10)
+                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                logger.trace(f"[DeviceActionManager] Job {job_log} always_free, start immediately")
+                return True
+
             # 检查是否有正在执行或准备执行的任务
             if device_key in self.active_jobs:
                 # 有正在执行或准备执行的任务，加入队列
@@ -154,7 +165,7 @@ class DeviceActionManager:
             job_info.set_ready_timeout(10)  # 设置10秒超时
             self.active_jobs[device_key] = job_info
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-            logger.info(f"[DeviceActionManager] Job {job_log} can start immediately for {device_key}")
+            logger.trace(f"[DeviceActionManager] Job {job_log} can start immediately for {device_key}")
             return True
 
     def start_job(self, job_id: str) -> bool:
@@ -176,11 +187,15 @@ class DeviceActionManager:
                 logger.error(f"[DeviceActionManager] Job {job_log} is not in READY status, current: {job_info.status}")
                 return False
 
-            # 检查设备上是否是这个job
+            # always_free的job不需要检查active_jobs
-            if device_key not in self.active_jobs or self.active_jobs[device_key].job_id != job_id:
+            if not job_info.always_free:
-                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                # 检查设备上是否是这个job
-                logger.error(f"[DeviceActionManager] Job {job_log} is not the active job for {device_key}")
+                if device_key not in self.active_jobs or self.active_jobs[device_key].job_id != job_id:
-                return False
+                    job_log = format_job_log(
+                        job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name
+                    )
+                    logger.error(f"[DeviceActionManager] Job {job_log} is not the active job for {device_key}")
+                    return False
 
             # 开始执行任务，将状态从READY转换为STARTED
             job_info.status = JobStatus.STARTED
@@ -203,6 +218,13 @@ class DeviceActionManager:
             job_info = self.all_jobs[job_id]
             device_key = job_info.device_action_key
 
+            # always_free的job直接清理，不影响队列
+            if job_info.always_free:
+                job_info.status = JobStatus.ENDED
+                job_info.update_timestamp()
+                del self.all_jobs[job_id]
+                return None
+
             # 移除活跃任务
             if device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id:
                 del self.active_jobs[device_key]
@@ -210,8 +232,9 @@ class DeviceActionManager:
                 job_info.update_timestamp()
                 # 从all_jobs中移除已结束的job
                 del self.all_jobs[job_id]
-                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                # job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                logger.info(f"[DeviceActionManager] Job {job_log} ended for {device_key}")
+                # logger.debug(f"[DeviceActionManager] Job {job_log} ended for {device_key}")
+                pass
             else:
                 job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
                 logger.warning(f"[DeviceActionManager] Job {job_log} was not active for {device_key}")
@@ -227,15 +250,20 @@ class DeviceActionManager:
                 next_job_log = format_job_log(
                     next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
                 )
-                logger.info(f"[DeviceActionManager] Next job {next_job_log} can start for {device_key}")
+                logger.trace(f"[DeviceActionManager] Next job {next_job_log} can start for {device_key}")
                 return next_job
 
             return None
 
     def get_active_jobs(self) -> List[JobInfo]:
-        """获取所有正在执行的任务"""
+        """获取所有正在执行的任务(含active_jobs和always_free的STARTED job)"""
         with self.lock:
-            return list(self.active_jobs.values())
+            jobs = list(self.active_jobs.values())
+            # 补充 always_free 的 STARTED job(它们不在 active_jobs 中)
+            for job in self.all_jobs.values():
+                if job.always_free and job.status == JobStatus.STARTED and job not in jobs:
+                    jobs.append(job)
+            return jobs
 
     def get_queued_jobs(self) -> List[JobInfo]:
         """获取所有排队中的任务"""
@@ -260,6 +288,14 @@ class DeviceActionManager:
             job_info = self.all_jobs[job_id]
             device_key = job_info.device_action_key
 
+            # always_free的job直接清理
+            if job_info.always_free:
+                job_info.status = JobStatus.ENDED
+                del self.all_jobs[job_id]
+                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                logger.trace(f"[DeviceActionManager] Always-free job {job_log} cancelled")
+                return True
+
             # 如果是正在执行的任务
             if device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id:
                 # 清理active job状态
@@ -268,7 +304,7 @@ class DeviceActionManager:
                 # 从all_jobs中移除
                 del self.all_jobs[job_id]
                 job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                logger.info(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
+                logger.trace(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
 
                 # 启动下一个任务
                 if device_key in self.device_queues and self.device_queues[device_key]:
@@ -281,7 +317,7 @@ class DeviceActionManager:
                     next_job_log = format_job_log(
                         next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
                     )
-                    logger.info(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
+                    logger.trace(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
                 return True
 
             # 如果是排队中的任务
@@ -295,7 +331,7 @@ class DeviceActionManager:
                     job_log = format_job_log(
                         job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name
                     )
-                    logger.info(f"[DeviceActionManager] Queued job {job_log} cancelled for {device_key}")
+                    logger.trace(f"[DeviceActionManager] Queued job {job_log} cancelled for {device_key}")
                     return True
 
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
@@ -333,13 +369,18 @@ class DeviceActionManager:
         timeout_jobs = []
 
         with self.lock:
-            # 统计READY状态的任务数量
+            # 收集所有需要检查的 READY 任务(active_jobs + always_free READY jobs)
-            ready_jobs_count = sum(1 for job in self.active_jobs.values() if job.status == JobStatus.READY)
+            ready_candidates = list(self.active_jobs.values())
+            for job in self.all_jobs.values():
+                if job.always_free and job.status == JobStatus.READY and job not in ready_candidates:
+                    ready_candidates.append(job)
+
+            ready_jobs_count = sum(1 for job in ready_candidates if job.status == JobStatus.READY)
             if ready_jobs_count > 0:
                 logger.trace(f"[DeviceActionManager] Checking {ready_jobs_count} READY jobs for timeout")  # type: ignore  # noqa: E501
 
             # 找到所有超时的READY任务（只检测，不处理）
-            for job_info in self.active_jobs.values():
+            for job_info in ready_candidates:
                 if job_info.is_ready_timeout():
                     timeout_jobs.append(job_info)
                     job_log = format_job_log(
@@ -359,7 +400,7 @@ class MessageProcessor:
         self.device_manager = device_manager
         self.queue_processor = None  # 延迟设置
         self.websocket_client = None  # 延迟设置
-        self.session_id = ""
+        self.session_id = str(uuid.uuid4())[:6]  # 产生一个随机的session_id
 
         # WebSocket连接
         self.websocket = None
@@ -368,6 +409,7 @@ class MessageProcessor:
         # 线程控制
         self.is_running = False
         self.thread = None
+        self._loop = None  # asyncio event loop引用，用于外部关闭websocket
         self.reconnect_count = 0
 
         logger.info(f"[MessageProcessor] Initialized for URL: {websocket_url}")
@@ -394,22 +436,31 @@ class MessageProcessor:
     def stop(self) -> None:
         """停止消息处理线程"""
         self.is_running = False
+        # 主动关闭websocket以快速中断消息接收循环
+        ws = self.websocket
+        loop = self._loop
+        if ws and loop and loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(ws.close(), loop)
+            except Exception:
+                pass
         if self.thread and self.thread.is_alive():
             self.thread.join(timeout=2)
         logger.info("[MessageProcessor] Stopped")
 
     def _run(self):
         """运行消息处理主循环"""
-        loop = asyncio.new_event_loop()
+        self._loop = asyncio.new_event_loop()
         try:
-            asyncio.set_event_loop(loop)
+            asyncio.set_event_loop(self._loop)
-            loop.run_until_complete(self._connection_handler())
+            self._loop.run_until_complete(self._connection_handler())
         except Exception as e:
             logger.error(f"[MessageProcessor] Thread error: {str(e)}")
             logger.error(traceback.format_exc())
         finally:
-            if loop:
+            if self._loop:
-                loop.close()
+                self._loop.close()
+            self._loop = None
 
     async def _connection_handler(self):
         """处理WebSocket连接和重连逻辑"""
@@ -426,8 +477,10 @@ class MessageProcessor:
                 async with websockets.connect(
                     self.websocket_url,
                     ssl=ssl_context,
+                    open_timeout=20,
                     ping_interval=WSConfig.ping_interval,
                     ping_timeout=10,
+                    close_timeout=5,
                     additional_headers={
                         "Authorization": f"Lab {BasicConfig.auth_secret()}",
                         "EdgeSession": f"{self.session_id}",
@@ -438,68 +491,94 @@ class MessageProcessor:
                     self.connected = True
                     self.reconnect_count = 0
 
-                    logger.trace(f"[MessageProcessor] Connected to {self.websocket_url}")
+                    logger.info(f"[MessageProcessor] 已连接到 {self.websocket_url}")
 
                     # 启动发送协程
-                    send_task = asyncio.create_task(self._send_handler())
+                    send_task = asyncio.create_task(self._send_handler(), name="websocket-send_task")
+
+                    # 每次连接（含重连）后重新向服务端注册，
+                    # 否则服务端不知道客户端已上线，不会推送消息。
+                    if self.websocket_client:
+                        self.websocket_client.publish_host_ready()
 
                     try:
                         # 接收消息循环
                         await self._message_handler()
                     finally:
+                        # 必须在 async with __aexit__ 之前停止 send_task，
+                        # 否则 send_task 会在关闭握手期间继续发送数据，
+                        # 干扰 websockets 库的内部清理，导致 task 泄漏。
+                        self.connected = False
                         send_task.cancel()
                         try:
                             await send_task
                         except asyncio.CancelledError:
                             pass
-                        self.connected = False
 
             except websockets.exceptions.ConnectionClosed:
-                logger.warning("[MessageProcessor] Connection closed")
+                logger.warning("[MessageProcessor] 与服务端连接中断")
-                self.connected = False
+            except TimeoutError:
+                logger.warning(
+                    f"[MessageProcessor] 与服务端连接通信超时 (已尝试 {self.reconnect_count + 1} 次)，请检查您的网络状况"
+                )
+            except websockets.exceptions.InvalidStatus as e:
+                logger.warning(
+                    f"[MessageProcessor] 收到服务端注册码 {e.response.status_code}, 上一进程可能还未退出"
+                )
             except Exception as e:
-                logger.error(f"[MessageProcessor] Connection error: {str(e)}")
                 logger.error(traceback.format_exc())
-                self.connected = False
+                logger.error(f"[MessageProcessor] 尝试重连时出错 {str(e)}")
             finally:
+                self.connected = False
                 self.websocket = None
 
             # 重连逻辑
-            if self.is_running and self.reconnect_count < WSConfig.max_reconnect_attempts:
+            if not self.is_running:
+                break
+            if self.reconnect_count < WSConfig.max_reconnect_attempts:
                 self.reconnect_count += 1
+                backoff = WSConfig.reconnect_interval
                 logger.info(
-                    f"[MessageProcessor] Reconnecting in {WSConfig.reconnect_interval}s "
+                    f"[MessageProcessor] 即将在 {backoff} 秒后重连 (已尝试 {self.reconnect_count}/{WSConfig.max_reconnect_attempts})"
-                    f"(attempt {self.reconnect_count}/{WSConfig.max_reconnect_attempts})"
                 )
-                await asyncio.sleep(WSConfig.reconnect_interval)
+                await asyncio.sleep(backoff)
-            elif self.reconnect_count >= WSConfig.max_reconnect_attempts:
+            else:
                 logger.error("[MessageProcessor] Max reconnection attempts reached")
                 break
-            else:
-                self.reconnect_count -= 1
 
     async def _message_handler(self):
-        """处理接收到的消息"""
+        """处理接收到的消息。
+
+        ConnectionClosed 不在此处捕获，让其向上传播到 _connection_handler，
+        以便 async with websockets.connect() 的 __aexit__ 能感知连接已断，
+        正确清理内部 task，避免 task 泄漏。
+        """
         if not self.websocket:
             logger.error("[MessageProcessor] WebSocket connection is None")
             return
 
-        try:
+        async for message in self.websocket:
-            async for message in self.websocket:
+            try:
-                try:
+                data = json.loads(message)
-                    data = json.loads(message)
+                message_type = data.get("action", "")
-                    await self._process_message(data)
+                message_data = data.get("data")
-                except json.JSONDecodeError:
+                if self.session_id and self.session_id == data.get("edge_session"):
-                    logger.error(f"[MessageProcessor] Invalid JSON received: {message}")
+                    await self._process_message(message_type, message_data)
-                except Exception as e:
+                else:
-                    logger.error(f"[MessageProcessor] Error processing message: {str(e)}")
+                    if message_type.endswith("_material"):
-                    logger.error(traceback.format_exc())
+                        logger.trace(
-
+                            f"[MessageProcessor] 收到一条归属 {data.get('edge_session')} 的旧消息：{data}"
-        except websockets.exceptions.ConnectionClosed:
+                        )
-            logger.info("[MessageProcessor] Message handler stopped - connection closed")
+                        logger.debug(
-        except Exception as e:
+                            f"[MessageProcessor] 跳过了一条归属 {data.get('edge_session')} 的旧消息: {data.get('action')}"
-            logger.error(f"[MessageProcessor] Message handler error: {str(e)}")
+                        )
-            logger.error(traceback.format_exc())
+                    else:
+                        await self._process_message(message_type, message_data)
+            except json.JSONDecodeError:
+                logger.error(f"[MessageProcessor] Invalid JSON received: {message}")
+            except Exception as e:
+                logger.error(f"[MessageProcessor] Error processing message: {str(e)}")
+                logger.error(traceback.format_exc())
 
     async def _send_handler(self):
         """处理发送队列中的消息"""
@@ -531,7 +610,7 @@ class MessageProcessor:
                         try:
                             message_str = json.dumps(msg, ensure_ascii=False)
                             await self.websocket.send(message_str)
-                            logger.trace(f"[MessageProcessor] Message sent: {msg.get('action', 'unknown')}")  # type: ignore  # noqa: E501
+                            # logger.trace(f"[MessageProcessor] Message sent: {msg.get('action', 'unknown')}")  # type: ignore  # noqa: E501
                         except Exception as e:
                             logger.error(f"[MessageProcessor] Failed to send message: {str(e)}")
                             logger.error(traceback.format_exc())
@@ -548,18 +627,16 @@ class MessageProcessor:
 
         except asyncio.CancelledError:
             logger.debug("[MessageProcessor] Send handler cancelled")
+            raise
         except Exception as e:
             logger.error(f"[MessageProcessor] Fatal error in send handler: {str(e)}")
             logger.error(traceback.format_exc())
         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", "")
+        logger.trace(f"[MessageProcessor] Processing message: {message_type}")
-        message_data = data.get("data")
-
-        logger.debug(f"[MessageProcessor] Processing message: {message_type}")
 
         try:
             if message_type == "pong":
@@ -571,14 +648,23 @@ 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":
+            # elif message_type == "session_id":
-                self.session_id = message_data.get("session_id")
+            #     self.session_id = message_data.get("session_id")
-                logger.info(f"[MessageProcessor] Session ID: {self.session_id}")
+            #     logger.info(f"[MessageProcessor] Session ID: {self.session_id}")
+            elif message_type == "add_device":
+                await self._handle_device_manage(message_data, "add")
+            elif message_type == "remove_device":
+                await self._handle_device_manage(message_data, "remove")
+            elif message_type == "request_restart":
+                await self._handle_request_restart(message_data)
             else:
                 logger.debug(f"[MessageProcessor] Unknown message type: {message_type}")
 
@@ -592,6 +678,24 @@ class MessageProcessor:
         if host_node:
             host_node.handle_pong_response(pong_data)
 
+    def _check_action_always_free(self, device_id: str, action_name: str) -> bool:
+        """检查该action是否标记为always_free，通过HostNode统一的_action_value_mappings查找"""
+        try:
+            host_node = HostNode.get_instance(0)
+            if not host_node:
+                return False
+            # noinspection PyProtectedMember
+            action_mappings = host_node._action_value_mappings.get(device_id)
+            if not action_mappings:
+                return False
+            # 尝试直接匹配或 auto- 前缀匹配
+            for key in [action_name, f"auto-{action_name}"]:
+                if key in action_mappings:
+                    return action_mappings[key].get("always_free", False)
+            return False
+        except Exception:
+            return False
+
     async def _handle_query_action_state(self, data: Dict[str, Any]):
         """处理query_action_state消息"""
         device_id = data.get("device_id", "")
@@ -606,6 +710,9 @@ class MessageProcessor:
 
         device_action_key = f"/devices/{device_id}/{action_name}"
 
+        # 检查action是否为always_free
+        action_always_free = self._check_action_always_free(device_id, action_name)
+
         # 创建任务信息
         job_info = JobInfo(
             job_id=job_id,
@@ -615,6 +722,7 @@ class MessageProcessor:
             device_action_key=device_action_key,
             status=JobStatus.QUEUE,
             start_time=time.time(),
+            always_free=action_always_free,
         )
 
         # 添加到设备管理器
@@ -626,13 +734,13 @@ class MessageProcessor:
             await self._send_action_state_response(
                 device_id, action_name, task_id, job_id, "query_action_status", True, 0
             )
-            logger.info(f"[MessageProcessor] Job {job_log} can start immediately")
+            logger.trace(f"[MessageProcessor] Job {job_log} can start immediately")
         else:
             # 需要排队
             await self._send_action_state_response(
                 device_id, action_name, task_id, job_id, "query_action_status", False, 10
             )
-            logger.info(f"[MessageProcessor] Job {job_log} queued")
+            logger.trace(f"[MessageProcessor] Job {job_log} queued")
 
             # 通知QueueProcessor有新的队列更新
             if self.queue_processor:
@@ -641,9 +749,37 @@ class MessageProcessor:
     async def _handle_job_start(self, data: Dict[str, Any]):
         """处理job_start消息"""
         try:
+            if not data.get("sample_material"):
+                data["sample_material"] = {}
             req = JobAddReq(**data)
 
             job_log = format_job_log(req.job_id, req.task_id, req.device_id, req.action)
+
+            # 服务端对always_free动作可能跳过query_action_state直接发job_start，
+            # 此时job尚未注册，需要自动补注册
+            existing_job = self.device_manager.get_job_info(req.job_id)
+            if not existing_job:
+                action_name = req.action
+                device_action_key = f"/devices/{req.device_id}/{action_name}"
+                action_always_free = self._check_action_always_free(req.device_id, action_name)
+
+                if action_always_free:
+                    job_info = JobInfo(
+                        job_id=req.job_id,
+                        task_id=req.task_id,
+                        device_id=req.device_id,
+                        action_name=action_name,
+                        device_action_key=device_action_key,
+                        status=JobStatus.QUEUE,
+                        start_time=time.time(),
+                        always_free=True,
+                    )
+                    self.device_manager.add_queue_request(job_info)
+                    logger.info(f"[MessageProcessor] Job {job_log} always_free, auto-registered from direct job_start")
+                else:
+                    logger.error(f"[MessageProcessor] Job {job_log} not registered (missing query_action_state)")
+                    return
+
             success = self.device_manager.start_job(req.job_id)
             if not success:
                 logger.error(f"[MessageProcessor] Failed to start job {job_log}")
@@ -672,6 +808,7 @@ class MessageProcessor:
                 queue_item,
                 action_type=req.action_type,
                 action_kwargs=req.action_args,
+                sample_material=req.sample_material,
                 server_info=req.server_info,
             )
 
@@ -836,9 +973,7 @@ class MessageProcessor:
                         device_action_groups[key_add] = []
                     device_action_groups[key_add].append(item["uuid"])
 
-                    logger.info(
+                    logger.info(f"[资源同步] 跨站Transfer: {item['uuid'][:8]} from {device_old_id} to {device_id}")
-                        f"[MessageProcessor] Resource migrated: {item['uuid'][:8]} from {device_old_id} to {device_id}"
-                    )
                 else:
                     # 正常update
                     key = (device_id, "update")
@@ -852,11 +987,13 @@ class MessageProcessor:
                     device_action_groups[key] = []
                 device_action_groups[key].append(item["uuid"])
 
-        logger.info(f"触发物料更新 {action} 分组数量: {len(device_action_groups)}, 总数量: {len(resource_uuid_list)}")
+        logger.trace(
+            f"[资源同步] 动作 {action} 分组数量: {len(device_action_groups)}, 总数量: {len(resource_uuid_list)}"
+        )
 
         # 为每个(device_id, action)创建独立的更新线程
         for (device_id, actual_action), items in device_action_groups.items():
-            logger.info(f"设备 {device_id} 物料更新 {actual_action} 数量: {len(items)}")
+            logger.trace(f"[资源同步] {device_id} 物料动作 {actual_action} 数量: {len(items)}")
 
             def _notify_resource_tree(dev_id, act, item_list):
                 try:
@@ -888,6 +1025,81 @@ class MessageProcessor:
             )
             thread.start()
 
+    async def _handle_device_manage(self, device_list: list[ResourceDictType], action: str):
+        """Handle add_device / remove_device from LabGo server."""
+        if not device_list:
+            return
+
+        for item in device_list:
+            target_node_id = item.get("target_node_id", "host_node")
+
+            def _notify(target_id: str, act: str, cfg: ResourceDictType):
+                try:
+                    host_node = HostNode.get_instance(timeout=5)
+                    if not host_node:
+                        logger.error(f"[DeviceManage] HostNode not available for {act}_device")
+                        return
+                    success = host_node.notify_device_manage(target_id, act, cfg)
+                    if success:
+                        logger.info(f"[DeviceManage] {act}_device completed on {target_id}")
+                    else:
+                        logger.warning(f"[DeviceManage] {act}_device failed on {target_id}")
+                except Exception as e:
+                    logger.error(f"[DeviceManage] Error in {act}_device: {e}")
+                    logger.error(traceback.format_exc())
+
+            thread = threading.Thread(
+                target=_notify,
+                args=(target_node_id, action, item),
+                daemon=True,
+                name=f"DeviceManage-{action}-{item.get('id', '')}",
+            )
+            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")
+
+        # 发送确认消息
+        self.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
     ):
@@ -959,6 +1171,7 @@ class QueueProcessor:
     def stop(self) -> None:
         """停止队列处理线程"""
         self.is_running = False
+        self.queue_update_event.set()  # 立即唤醒等待中的线程
         if self.thread and self.thread.is_alive():
             self.thread.join(timeout=2)
         logger.info("[QueueProcessor] Stopped")
@@ -1059,6 +1272,11 @@ class QueueProcessor:
         logger.debug(f"[QueueProcessor] Sending busy status for {len(queued_jobs)} queued jobs")
 
         for job_info in queued_jobs:
+            # 快照可能已过期：在遍历过程中 end_job() 可能已将此 job 移至 READY，
+            # 此时不应再发送 busy/need_more，否则会覆盖已发出的 free=True 通知
+            if job_info.status != JobStatus.QUEUE:
+                continue
+
             message = {
                 "action": "report_action_state",
                 "data": {
@@ -1074,7 +1292,7 @@ class QueueProcessor:
             success = self.message_processor.send_message(message)
             job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
             if success:
-                logger.debug(f"[QueueProcessor] Sent busy/need_more for queued job {job_log}")
+                logger.trace(f"[QueueProcessor] Sent busy/need_more for queued job {job_log}")
             else:
                 logger.warning(f"[QueueProcessor] Failed to send busy status for job {job_log}")
 
@@ -1097,7 +1315,7 @@ class QueueProcessor:
             job_info.action_name,
         )
 
-        logger.info(f"[QueueProcessor] Job {job_log} completed with status: {status}")
+        logger.trace(f"[QueueProcessor] Job {job_log} completed with status: {status}")
 
         # 结束任务，获取下一个可执行的任务
         next_job = self.device_manager.end_job(job_id)
@@ -1117,8 +1335,8 @@ class QueueProcessor:
                 },
             }
             self.message_processor.send_message(message)
-            next_job_log = format_job_log(next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name)
+            # next_job_log = format_job_log(next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name)
-            logger.info(f"[QueueProcessor] Notified next job {next_job_log} can start")
+            # logger.debug(f"[QueueProcessor] Notified next job {next_job_log} can start")
 
             # 立即触发下一轮状态检查
             self.notify_queue_update()
@@ -1207,8 +1425,8 @@ class WebSocketClient(BaseCommunicationClient):
                 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}")
-                # 给一点时间让消息发送出去
+                # send_handler 每100ms检查一次队列，等300ms足以让消息发出
-                time.sleep(1)
+                time.sleep(0.3)
             except Exception as e:
                 logger.warning(f"[WebSocketClient] Failed to send normal_exit message: {str(e)}")
 
@@ -1240,7 +1458,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
@@ -1260,7 +1478,7 @@ class WebSocketClient(BaseCommunicationClient):
                 except (KeyError, AttributeError):
                     logger.warning(f"[WebSocketClient] Failed to remove job {item.job_id} from HostNode status")
 
-            logger.info(f"[WebSocketClient] Intercepting final status for job_id: {item.job_id} - {status}")
+            # logger.debug(f"[WebSocketClient] Intercepting final status for job_id: {item.job_id} - {status}")
 
             # 通知队列处理器job完成（包括timeout的job）
             self.queue_processor.handle_job_completed(item.job_id, status)
@@ -1282,7 +1500,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消息"""
@@ -1313,17 +1531,59 @@ class WebSocketClient(BaseCommunicationClient):
             logger.warning(f"[WebSocketClient] Failed to cancel job {job_log}")
 
     def publish_host_ready(self) -> None:
-        """发布host_node ready信号"""
+        """发布host_node ready信号，包含设备和动作信息"""
         if self.is_disabled or not self.is_connected():
             logger.debug("[WebSocketClient] Not connected, cannot publish host ready signal")
             return
 
+        # 收集设备信息
+        devices = []
+        machine_name = BasicConfig.machine_name
+
+        try:
+            host_node = HostNode.get_instance(0)
+            if host_node:
+                # 获取设备信息
+                for device_id, namespace in host_node.devices_names.items():
+                    device_key = (
+                        f"{namespace}/{device_id}" if namespace.startswith("/") else f"/{namespace}/{device_id}"
+                    )
+                    is_online = device_key in host_node._online_devices
+
+                    # 获取设备的动作信息
+                    actions = {}
+                    for action_id, client in host_node._action_clients.items():
+                        # action_id 格式: /namespace/device_id/action_name
+                        if device_id in action_id:
+                            action_name = action_id.split("/")[-1]
+                            actions[action_name] = {
+                                "action_path": action_id,
+                                "action_type": str(type(client).__name__),
+                            }
+
+                    devices.append(
+                        {
+                            "device_id": device_id,
+                            "namespace": namespace,
+                            "device_key": device_key,
+                            "is_online": is_online,
+                            "machine_name": host_node.device_machine_names.get(device_id, machine_name),
+                            "actions": actions,
+                        }
+                    )
+
+                logger.info(f"[WebSocketClient] Collected {len(devices)} devices for host_ready")
+        except Exception as e:
+            logger.warning(f"[WebSocketClient] Error collecting device info: {e}")
+
         message = {
             "action": "host_node_ready",
             "data": {
                 "status": "ready",
                 "timestamp": time.time(),
+                "machine_name": machine_name,
+                "devices": devices,
             },
         }
         self.message_processor.send_message(message)
-        logger.info("[WebSocketClient] Host node ready signal published")
+        logger.info(f"[WebSocketClient] Host node ready signal published with {len(devices)} devices")

unilabos/compile/pump_protocol.py

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

unilabos/config/config.py

@@ -16,11 +16,15 @@ class BasicConfig:
     upload_registry = False
     machine_name = "undefined"
     vis_2d_enable = False
+    no_update_feedback = False
     enable_resource_load = True
     communication_protocol = "websocket"
     startup_json_path = None  # 填写绝对路径
     disable_browser = False  # 禁止浏览器自动打开
     port = 8002  # 本地HTTP服务
+    check_mode = False  # CI 检查模式，用于验证 registry 导入和文件一致性
+    test_mode = False  # 测试模式，所有动作不实际执行，返回模拟结果
+    extra_resource = False  # 是否加载lab_开头的额外资源
     # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
     log_level: Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "DEBUG"
 
@@ -37,7 +41,7 @@ class BasicConfig:
 class WSConfig:
     reconnect_interval = 5  # 重连间隔（秒）
     max_reconnect_attempts = 999  # 最大重连次数
-    ping_interval = 30  # ping间隔（秒）
+    ping_interval = 20  # ping间隔（秒）
 
 
 # HTTP配置
@@ -143,5 +147,5 @@ def load_config(config_path=None):
             traceback.print_exc()
             exit(1)
     else:
-        config_path = os.path.join(os.path.dirname(__file__), "local_config.py")
+        config_path = os.path.join(os.path.dirname(__file__), "example_config.py")
         load_config(config_path)

unilabos/device_comms/coin_cell_assembly_workstation.py

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

unilabos/device_comms/universal_driver.py

@@ -1,4 +1,3 @@
-
 from abc import abstractmethod
 from functools import wraps
 import inspect

unilabos/devices/LICENSE

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

unilabos/devices/LICENSE_eng

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

unilabos/devices/liquid_handling/biomek.py

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

unilabos/devices/liquid_handling/prcxi/prcxi.py

@@ -1,10 +1,12 @@
 import asyncio
 import collections
+from collections import OrderedDict
 import contextlib
 import json
 import os
 import socket
 import time
+import uuid
 from typing import Any, List, Dict, Optional, Tuple, TypedDict, Union, Sequence, Iterator, Literal
 from pylabrobot.liquid_handling.standard import GripDirection
 
@@ -28,9 +30,32 @@ from pylabrobot.liquid_handling.standard import (
     ResourceMove,
     ResourceDrop,
 )
-from pylabrobot.resources import ResourceHolder, ResourceStack, Tip, Deck, Plate, Well, TipRack, Resource, Container, Coordinate, TipSpot, Trash
+from pylabrobot.resources import (
+    ResourceHolder,
+    ResourceStack,
+    Tip,
+    Deck,
+    Plate,
+    Well,
+    TipRack,
+    Resource,
+    Container,
+    Coordinate,
+    TipSpot,
+    Trash,
+    PlateAdapter,
+    TubeRack,
+)
 
-from unilabos.devices.liquid_handling.liquid_handler_abstract import LiquidHandlerAbstract, SimpleReturn
+from unilabos.devices.liquid_handling.liquid_handler_abstract import (
+    LiquidHandlerAbstract,
+    SimpleReturn,
+    SetLiquidReturn,
+    SetLiquidFromPlateReturn,
+    TransferLiquidReturn,
+)
+from unilabos.registry.placeholder_type import ResourceSlot
+from unilabos.resources.resource_tracker import ResourceTreeSet
 from unilabos.ros.nodes.base_device_node import BaseROS2DeviceNode
 
 
@@ -66,9 +91,131 @@ class PRCXI9300Deck(Deck):
     该类定义了 PRCXI 9300 的工作台布局和槽位信息。
     """
 
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, **kwargs):
+    # T1-T16 默认位置 (4列×4行)
-        super().__init__(name, size_x, size_y, size_z)
+    _DEFAULT_SITE_POSITIONS = [
-        self.slots = [None] * 6  # PRCXI 9300 有 6 个槽位
+        (0, 0, 0), (138, 0, 0), (276, 0, 0), (414, 0, 0),         # T1-T4
+        (0, 96, 0), (138, 96, 0), (276, 96, 0), (414, 96, 0),     # T5-T8
+        (0, 192, 0), (138, 192, 0), (276, 192, 0), (414, 192, 0), # T9-T12
+        (0, 288, 0), (138, 288, 0), (276, 288, 0), (414, 288, 0), # T13-T16
+    ]
+    _DEFAULT_SITE_SIZE = {"width": 128.0, "height": 86, "depth": 0}
+    _DEFAULT_CONTENT_TYPE = ["plate", "tip_rack", "plates", "tip_racks", "tube_rack", "adaptor"]
+
+    def __init__(self, name: str, size_x: float, size_y: float, size_z: float,
+                 sites: Optional[List[Dict[str, Any]]] = None, **kwargs):
+        super().__init__(size_x, size_y, size_z, name)
+        if sites is not None:
+            self.sites: List[Dict[str, Any]] = [dict(s) for s in sites]
+        else:
+            self.sites = []
+            for i, (x, y, z) in enumerate(self._DEFAULT_SITE_POSITIONS):
+                self.sites.append({
+                    "label": f"T{i + 1}",
+                    "visible": True,
+                    "position": {"x": x, "y": y, "z": z},
+                    "size": dict(self._DEFAULT_SITE_SIZE),
+                    "content_type": list(self._DEFAULT_CONTENT_TYPE),
+                })
+        # _ordering: label -> None, 用于外部通过 list(keys()).index(site) 将 Tn 转换为 spot index
+        self._ordering = collections.OrderedDict(
+            (site["label"], None) for site in self.sites
+        )
+
+    def _get_site_location(self, idx: int) -> Coordinate:
+        pos = self.sites[idx]["position"]
+        return Coordinate(pos["x"], pos["y"], pos["z"])
+
+    def _get_site_resource(self, idx: int) -> Optional[Resource]:
+        site_loc = self._get_site_location(idx)
+        for child in self.children:
+            if child.location == site_loc:
+                return child
+        return None
+
+    def assign_child_resource(
+        self,
+        resource: Resource,
+        location: Optional[Coordinate] = None,
+        reassign: bool = True,
+        spot: Optional[int] = None,
+    ):
+        idx = spot
+        if spot is not None:
+            idx = spot
+        else:
+            for i, site in enumerate(self.sites):
+                site_loc = self._get_site_location(i)
+                if site.get("label") == resource.name:
+                    idx = i
+                    break
+                if location is not None and site_loc == location:
+                    idx = i
+                    break
+
+        if idx is None:
+            for i in range(len(self.sites)):
+                if self._get_site_resource(i) is None:
+                    idx = i
+                    break
+
+        if idx is None:
+            raise ValueError(f"No available site on deck '{self.name}' for resource '{resource.name}'")
+
+        if not reassign and self._get_site_resource(idx) is not None:
+            raise ValueError(f"Site {idx} ('{self.sites[idx]['label']}') is already occupied")
+
+        loc = self._get_site_location(idx)
+        super().assign_child_resource(resource, location=loc, reassign=reassign)
+
+    def assign_child_at_slot(self, resource: Resource, slot: int, reassign: bool = False) -> None:
+        self.assign_child_resource(resource, spot=slot - 1, reassign=reassign)
+
+    def serialize(self) -> dict:
+        data = super().serialize()
+        sites_out = []
+        for i, site in enumerate(self.sites):
+            occupied = self._get_site_resource(i)
+            sites_out.append({
+                "label": site["label"],
+                "visible": site.get("visible", True),
+                "occupied_by": occupied.name if occupied is not None else None,
+                "position": site["position"],
+                "size": site["size"],
+                "content_type": site["content_type"],
+            })
+        data["sites"] = sites_out
+        return data
+
+
+class PRCXI9300Container(Container):
+    """PRCXI 9300 的专用 Container 类，继承自 Plate，用于槽位定位和未知模块。
+
+    该类定义了 PRCXI 9300 的工作台布局和槽位信息。
+    """
+
+    def __init__(
+        self,
+        name: str,
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str,
+        model: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(name, size_x, size_y, size_z, category=category, model=model)
+        self._unilabos_state = {}
+
+    def load_state(self, state: Dict[str, Any]) -> None:
+        """从给定的状态加载工作台信息。"""
+        super().load_state(state)
+        self._unilabos_state = state
+
+    def serialize_state(self) -> Dict[str, Dict[str, Any]]:
+        data = super().serialize_state()
+        data.update(self._unilabos_state)
+        return data
+
 
 class PRCXI9300Plate(Plate):
     """
@@ -76,35 +223,72 @@ class PRCXI9300Plate(Plate):
     1. 继承自 PLR 原生 Plate，保留所有物理特性。
     2. 增加 material_info 参数，用于在初始化时直接绑定 Unilab UUID。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
+
-                 category: str = "plate", 
+    def __init__(
-                 ordered_items: collections.OrderedDict = None, 
+        self,
-                 ordering: Optional[collections.OrderedDict] = None,
+        name: str,
-                 model: Optional[str] = None, 
+        size_x: float,
-                 material_info: Optional[Dict[str, Any]] = None, 
+        size_y: float,
-                 **kwargs):
+        size_z: float,
-        items = ordered_items if ordered_items is not None else ordering
+        category: str = "plate",
-        super().__init__(name, size_x, size_y, size_z, 
+        ordered_items: collections.OrderedDict = None,
-                         ordered_items=items,
+        ordering: Optional[collections.OrderedDict] = None,
-                         category=category,
+        model: Optional[str] = None,
-                         model=model, **kwargs)
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        # 如果 ordered_items 不为 None，直接使用
+        items = None
+        ordering_param = None
+        if ordered_items is not None:
+            items = ordered_items
+        elif ordering is not None:
+            # 检查 ordering 中的值是否是字符串（从 JSON 反序列化时的情况）
+            # 如果是字符串，说明这是位置名称，需要让 Plate 自己创建 Well 对象
+            # 我们只传递位置信息（键），不传递值，使用 ordering 参数
+            if ordering:
+                values = list(ordering.values())
+                value = values[0]
+                if isinstance(value, str):
+                    # ordering 的值是字符串，只使用键（位置信息）创建新的 OrderedDict
+                    # 传递 ordering 参数而不是 ordered_items，让 Plate 自己创建 Well 对象
+                    items = None
+                    # 使用 ordering 参数，只包含位置信息（键）
+                    ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
+                elif value is None:
+                    ordering_param = ordering
+            else:
+                # ordering 的值已经是对象，可以直接使用
+                items = ordering
+                ordering_param = None
+
+        # 根据情况传递不同的参数
+        if items is not None:
+            super().__init__(
+                name, size_x, size_y, size_z, ordered_items=items, category=category, model=model, **kwargs
+            )
+        elif ordering_param is not None:
+            # 传递 ordering 参数，让 Plate 自己创建 Well 对象
+            super().__init__(
+                name, size_x, size_y, size_z, ordering=ordering_param, category=category, model=model, **kwargs
+            )
+        else:
+            super().__init__(name, size_x, size_y, size_z, category=category, model=model, **kwargs)
 
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
 
-
     def load_state(self, state: Dict[str, Any]) -> None:
         super().load_state(state)
         self._unilabos_state = state
 
-
     def serialize_state(self) -> Dict[str, Dict[str, Any]]:
         try:
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -124,22 +308,59 @@ class PRCXI9300Plate(Plate):
                     safe_state[k] = v
 
             data.update(safe_state)
-        return data
+        return data  # 其他顶层属性也进行类型检查
+
 
 class PRCXI9300TipRack(TipRack):
-    """ 专用吸头盒类 """
+    """专用吸头盒类"""
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
+
-                 category: str = "tip_rack", 
+    def __init__(
-                 ordered_items: collections.OrderedDict = None, 
+        self,
-                 ordering: Optional[collections.OrderedDict] = None,
+        name: str,
-                 model: Optional[str] = None,
+        size_x: float,
-                 material_info: Optional[Dict[str, Any]] = None,
+        size_y: float,
-                 **kwargs):
+        size_z: float,
-        items = ordered_items if ordered_items is not None else ordering
+        category: str = "tip_rack",
-        super().__init__(name, size_x, size_y, size_z, 
+        ordered_items: collections.OrderedDict = None,
-                         ordered_items=items,
+        ordering: Optional[collections.OrderedDict] = None,
-                         category=category, 
+        model: Optional[str] = None,
-                         model=model, **kwargs)
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        # 如果 ordered_items 不为 None，直接使用
+        if ordered_items is not None:
+            items = ordered_items
+        elif ordering is not None:
+            # 检查 ordering 中的值类型来决定如何处理：
+            # - 字符串值（从 JSON 反序列化）: 只用键创建 ordering_param
+            # - None 值（从第二次往返序列化）: 同样只用键创建 ordering_param
+            # - 对象值（已经是实际的 Resource 对象）: 直接作为 ordered_items 使用
+            first_val = next(iter(ordering.values()), None) if ordering else None
+            if not ordering or first_val is None or isinstance(first_val, str):
+                # ordering 的值是字符串或 None，只使用键（位置信息）创建新的 OrderedDict
+                # 传递 ordering 参数而不是 ordered_items，让 TipRack 自己创建 Tip 对象
+                items = None
+                ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
+            else:
+                # ordering 的值已经是对象，可以直接使用
+                items = ordering
+                ordering_param = None
+        else:
+            items = None
+            ordering_param = None
+
+        # 根据情况传递不同的参数
+        if items is not None:
+            super().__init__(
+                name, size_x, size_y, size_z, ordered_items=items, category=category, model=model, **kwargs
+            )
+        elif ordering_param is not None:
+            # 传递 ordering 参数，让 TipRack 自己创建 Tip 对象
+            super().__init__(
+                name, size_x, size_y, size_z, ordering=ordering_param, category=category, model=model, **kwargs
+            )
+        else:
+            super().__init__(name, size_x, size_y, size_z, category=category, model=model, **kwargs)
         self._unilabos_state = {}
         if material_info:
             self._unilabos_state["Material"] = material_info
@@ -153,7 +374,7 @@ class PRCXI9300TipRack(TipRack):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -175,16 +396,23 @@ class PRCXI9300TipRack(TipRack):
             data.update(safe_state)
         return data
 
+
 class PRCXI9300Trash(Trash):
     """PRCXI 9300 的专用 Trash 类，继承自 Trash。
 
     该类定义了 PRCXI 9300 的工作台布局和槽位信息。
     """
 
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
+    def __init__(
-                 category: str = "trash", 
+        self,
-                 material_info: Optional[Dict[str, Any]] = None,
+        name: str,
-                 **kwargs):
+        size_x: float,
+        size_y: float,
+        size_z: float,
+        category: str = "trash",
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
 
         if name != "trash":
             print(f"Warning: PRCXI9300Trash usually expects name='trash' for backend logic, but got '{name}'.")
@@ -204,7 +432,7 @@ class PRCXI9300Trash(Trash):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -226,25 +454,63 @@ class PRCXI9300Trash(Trash):
             data.update(safe_state)
         return data
 
+
 class PRCXI9300TubeRack(TubeRack):
     """
     专用管架类：用于 EP 管架、试管架等。
     继承自 PLR 的 TubeRack，并支持注入 material_info (UUID)。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
-                 category: str = "tube_rack", 
-                 items: Optional[Dict[str, Any]] = None,
-                 ordered_items: Optional[OrderedDict] = None,
-                 model: Optional[str] = None,
-                 material_info: Optional[Dict[str, Any]] = None, 
-                 **kwargs):
 
-        # 兼容处理：PLR 的 TubeRack 构造函数可能接受 items 或 ordered_items
+    def __init__(
-        items_to_pass = items if items is not None else ordered_items
+        self,
-        super().__init__(name, size_x, size_y, size_z, 
+        name: str,
-                         ordered_items=ordered_items, 
+        size_x: float,
-                         model=model, 
+        size_y: float,
-                         **kwargs)
+        size_z: float,
+        category: str = "tube_rack",
+        items: Optional[Dict[str, Any]] = None,
+        ordered_items: Optional[OrderedDict] = None,
+        ordering: Optional[OrderedDict] = None,
+        model: Optional[str] = None,
+        material_info: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+
+        # 如果 ordered_items 不为 None，直接使用
+        if ordered_items is not None:
+            items_to_pass = ordered_items
+            ordering_param = None
+        elif ordering is not None:
+            # 检查 ordering 中的值类型来决定如何处理：
+            # - 字符串值（从 JSON 反序列化）: 只用键创建 ordering_param
+            # - None 值（从第二次往返序列化）: 同样只用键创建 ordering_param
+            # - 对象值（已经是实际的 Resource 对象）: 直接作为 ordered_items 使用
+            first_val = next(iter(ordering.values()), None) if ordering else None
+            if not ordering or first_val is None or isinstance(first_val, str):
+                # ordering 的值是字符串或 None，只使用键（位置信息）创建新的 OrderedDict
+                # 传递 ordering 参数而不是 ordered_items，让 TubeRack 自己创建 Tube 对象
+                items_to_pass = None
+                ordering_param = collections.OrderedDict((k, None) for k in ordering.keys())
+            else:
+                # ordering 的值已经是对象，可以直接使用
+                items_to_pass = ordering
+                ordering_param = None
+        elif items is not None:
+            # 兼容旧的 items 参数
+            items_to_pass = items
+            ordering_param = None
+        else:
+            items_to_pass = None
+            ordering_param = None
+
+        # 根据情况传递不同的参数
+        if items_to_pass is not None:
+            super().__init__(name, size_x, size_y, size_z, ordered_items=items_to_pass, model=model, **kwargs)
+        elif ordering_param is not None:
+            # 传递 ordering 参数，让 TubeRack 自己创建 Tube 对象
+            super().__init__(name, size_x, size_y, size_z, ordering=ordering_param, model=model, **kwargs)
+        else:
+            super().__init__(name, size_x, size_y, size_z, model=model, **kwargs)
 
         self._unilabos_state = {}
         if material_info:
@@ -255,7 +521,7 @@ class PRCXI9300TubeRack(TubeRack):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -277,23 +543,31 @@ class PRCXI9300TubeRack(TubeRack):
             data.update(safe_state)
         return data
 
+
 class PRCXI9300PlateAdapter(PlateAdapter):
     """
     专用板式适配器类：用于承载 Plate 的底座（如 PCR 适配器、磁吸架等）。
     支持注入 material_info (UUID)。
     """
-    def __init__(self, name: str, size_x: float, size_y: float, size_z: float, 
+
-                 category: str = "plate_adapter", 
+    def __init__(
-                 model: Optional[str] = None,
+        self,
-                 material_info: Optional[Dict[str, Any]] = None, 
+        name: str,
-                 # 参数给予默认值 (标准96孔板尺寸)
+        size_x: float,
-                 adapter_hole_size_x: float = 127.76, 
+        size_y: float,
-                 adapter_hole_size_y: float = 85.48, 
+        size_z: float,
-                 adapter_hole_size_z: float = 10.0, # 假设凹槽深度或板子放置高度
+        category: str = "plate_adapter",
-                 dx: Optional[float] = None,
+        model: Optional[str] = None,
-                 dy: Optional[float] = None,
+        material_info: Optional[Dict[str, Any]] = None,
-                 dz: float = 0.0, # 默认Z轴偏移
+        # 参数给予默认值 (标准96孔板尺寸)
-                 **kwargs):
+        adapter_hole_size_x: float = 127.76,
+        adapter_hole_size_y: float = 85.48,
+        adapter_hole_size_z: float = 10.0,  # 假设凹槽深度或板子放置高度
+        dx: Optional[float] = None,
+        dy: Optional[float] = None,
+        dz: float = 0.0,  # 默认Z轴偏移
+        **kwargs,
+    ):
 
         # 自动居中计算：如果未指定 dx/dy，则根据适配器尺寸和孔尺寸计算居中位置
         if dx is None:
@@ -313,7 +587,7 @@ class PRCXI9300PlateAdapter(PlateAdapter):
             adapter_hole_size_y=adapter_hole_size_y,
             adapter_hole_size_z=adapter_hole_size_z,
             model=model,
-            **kwargs
+            **kwargs,
         )
 
         self._unilabos_state = {}
@@ -325,7 +599,7 @@ class PRCXI9300PlateAdapter(PlateAdapter):
             data = super().serialize_state()
         except AttributeError:
             data = {}
-        if hasattr(self, '_unilabos_state') and self._unilabos_state:
+        if hasattr(self, "_unilabos_state") and self._unilabos_state:
             safe_state = {}
             for k, v in self._unilabos_state.items():
                 # 如果是 Material 字典，深入检查
@@ -347,6 +621,7 @@ class PRCXI9300PlateAdapter(PlateAdapter):
             data.update(safe_state)
         return data
 
+
 class PRCXI9300Handler(LiquidHandlerAbstract):
     support_touch_tip = False
 
@@ -359,7 +634,7 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
 
     def __init__(
         self,
-        deck: Deck,
+        deck: PRCXI9300Deck,
         host: str,
         port: int,
         timeout: float,
@@ -373,14 +648,16 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         is_9320=False,
     ):
         tablets_info = []
-        count = 0
+        for site_id in range(len(deck.sites)):
-        for child in deck.children:
+            child = deck._get_site_resource(site_id)
-            if child.children:
+            # 如果放其他类型的物料，是不可以的
-                if "Material" in child.children[0]._unilabos_state:
+            if hasattr(child, "_unilabos_state") and "Material" in child._unilabos_state:
-                    number = int(child.name.replace("T", ""))
+                number = site_id + 1
-                    tablets_info.append(
+                tablets_info.append(
-                        WorkTablets(Number=number, Code=f"T{number}", Material=child.children[0]._unilabos_state["Material"])
+                    WorkTablets(
+                        Number=number, Code=f"T{number}", Material=child._unilabos_state["Material"]
                     )
+                )
         if is_9320:
             print("当前设备是9320")
         # 始终初始化 step_mode 属性
@@ -399,9 +676,14 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         super().post_init(ros_node)
         self._unilabos_backend.post_init(ros_node)
 
-    def set_liquid(self, wells: list[Well], liquid_names: list[str], volumes: list[float]) -> SimpleReturn:
+    def set_liquid(self, wells: list[Well], liquid_names: list[str], volumes: list[float]) -> SetLiquidReturn:
         return super().set_liquid(wells, liquid_names, volumes)
 
+    def set_liquid_from_plate(
+        self, plate: ResourceSlot, well_names: list[str], liquid_names: list[str], volumes: list[float]
+    ) -> SetLiquidFromPlateReturn:
+        return super().set_liquid_from_plate(plate, well_names, liquid_names, volumes)
+
     def set_group(self, group_name: str, wells: List[Well], volumes: List[float]):
         return super().set_group(group_name, wells, volumes)
 
@@ -521,7 +803,7 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
         mix_liquid_height: Optional[float] = None,
         delays: Optional[List[int]] = None,
         none_keys: List[str] = [],
-    ):
+    ) -> TransferLiquidReturn:
         return await super().transfer_liquid(
             sources,
             targets,
@@ -661,6 +943,7 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
 
     async def heater_action(self, temperature: float, time: int):
         return await self._unilabos_backend.heater_action(temperature, time)
+
     async def move_plate(
         self,
         plate: Plate,
@@ -683,10 +966,11 @@ class PRCXI9300Handler(LiquidHandlerAbstract):
             drop_direction,
             pickup_direction,
             pickup_distance_from_top,
-            target_plate_number = to,
+            target_plate_number=to,
             **backend_kwargs,
         )
 
+
 class PRCXI9300Backend(LiquidHandlerBackend):
     """PRCXI 9300 的后端实现，继承自 LiquidHandlerBackend。
 
@@ -739,13 +1023,12 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         self.steps_todo_list.append(step)
         return step
 
-
     async def pick_up_resource(self, pickup: ResourcePickup, **backend_kwargs):
 
-        resource=pickup.resource
+        resource = pickup.resource
-        offset=pickup.offset
+        offset = pickup.offset
-        pickup_distance_from_top=pickup.pickup_distance_from_top
+        pickup_distance_from_top = pickup.pickup_distance_from_top
-        direction=pickup.direction
+        direction = pickup.direction
 
         plate_number = int(resource.parent.name.replace("T", ""))
         is_whole_plate = True
@@ -757,13 +1040,11 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def drop_resource(self, drop: ResourceDrop, **backend_kwargs):
 
-
         plate_number = None
         target_plate_number = backend_kwargs.get("target_plate_number", None)
         if target_plate_number is not None:
             plate_number = int(target_plate_number.name.replace("T", ""))
 
-
         is_whole_plate = True
         balance_height = 0
         if plate_number is None:
@@ -772,7 +1053,6 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         self.steps_todo_list.append(step)
         return step
 
-
     async def heater_action(self, temperature: float, time: int):
         print(f"\n\nHeater action: temperature={temperature}, time={time}\n\n")
         # return await self.api_client.heater_action(temperature, time)
@@ -841,7 +1121,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
                 # 检查重置状态并等待完成
                 while not self.is_reset_ok:
                     print("Waiting for PRCXI9300 to reset...")
-                    if hasattr(self, '_ros_node') and self._ros_node is not None:
+                    if hasattr(self, "_ros_node") and self._ros_node is not None:
                         await self._ros_node.sleep(1)
                     else:
                         await asyncio.sleep(1)
@@ -859,7 +1139,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
         """Pick up tips from the specified resource."""
         # INSERT_YOUR_CODE
         # Ensure use_channels is converted to a list of ints if it's an array
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -913,7 +1193,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def drop_tips(self, ops: List[Drop], use_channels: List[int] = None):
         """Pick up tips from the specified resource."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1039,7 +1319,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def aspirate(self, ops: List[SingleChannelAspiration], use_channels: List[int] = None):
         """Aspirate liquid from the specified resources."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1096,7 +1376,7 @@ class PRCXI9300Backend(LiquidHandlerBackend):
 
     async def dispense(self, ops: List[SingleChannelDispense], use_channels: List[int] = None):
         """Dispense liquid into the specified resources."""
-        if hasattr(use_channels, 'tolist'):
+        if hasattr(use_channels, "tolist"):
             _use_channels = use_channels.tolist()
         else:
             _use_channels = list(use_channels) if use_channels is not None else None
@@ -1277,7 +1557,6 @@ class PRCXI9300Api:
                 time.sleep(1)
         return success
 
-
     def call(self, service: str, method: str, params: Optional[list] = None) -> Any:
         payload = json.dumps(
             {"ServiceName": service, "MethodName": method, "Paramters": params or []}, separators=(",", ":")
@@ -1404,7 +1683,7 @@ class PRCXI9300Api:
         assist_fun5: str = "",
         liquid_method: str = "NormalDispense",
         axis: str = "Left",
-        ) -> Dict[str, Any]:
+    ) -> Dict[str, Any]:
         return {
             "StepAxis": axis,
             "Function": "Imbibing",
@@ -1482,7 +1761,7 @@ class PRCXI9300Api:
         assist_fun5: str = "",
         liquid_method: str = "NormalDispense",
         axis: str = "Left",
-        ) -> Dict[str, Any]:
+    ) -> Dict[str, Any]:
         return {
             "StepAxis": axis,
             "Function": "Blending",
@@ -1542,11 +1821,11 @@ class PRCXI9300Api:
             "LiquidDispensingMethod": liquid_method,
         }
 
-    def clamp_jaw_pick_up(self,
+    def clamp_jaw_pick_up(
+        self,
         plate_no: int,
         is_whole_plate: bool,
         balance_height: int,
-
     ) -> Dict[str, Any]:
         return {
             "StepAxis": "ClampingJaw",
@@ -1556,7 +1835,7 @@ class PRCXI9300Api:
             "HoleRow": 1,
             "HoleCol": 1,
             "BalanceHeight": balance_height,
-            "PlateOrHoleNum": f"T{plate_no}"
+            "PlateOrHoleNum": f"T{plate_no}",
         }
 
     def clamp_jaw_drop(
@@ -1564,7 +1843,6 @@ class PRCXI9300Api:
         plate_no: int,
         is_whole_plate: bool,
         balance_height: int,
-
     ) -> Dict[str, Any]:
         return {
             "StepAxis": "ClampingJaw",
@@ -1574,7 +1852,7 @@ class PRCXI9300Api:
             "HoleRow": 1,
             "HoleCol": 1,
             "BalanceHeight": balance_height,
-            "PlateOrHoleNum": f"T{plate_no}"
+            "PlateOrHoleNum": f"T{plate_no}",
         }
 
     def shaker_action(self, time: int, module_no: int, amplitude: int, is_wait: bool):
@@ -1587,6 +1865,7 @@ class PRCXI9300Api:
             "AssistFun4": is_wait,
         }
 
+
 class DefaultLayout:
 
     def __init__(self, product_name: str = "PRCXI9300"):
@@ -1965,7 +2244,9 @@ if __name__ == "__main__":
             size_y=50,
             size_z=10,
             category="tip_rack",
-            ordered_items=collections.OrderedDict({k: f"{child_prefix}_{k}" for k, v in tip_racks["ordering"].items()}),
+            ordered_items=collections.OrderedDict(
+                {k: f"{child_prefix}_{k}" for k, v in tip_racks["ordering"].items()}
+            ),
         )
         tip_rack_serialized = tip_rack.serialize()
         tip_rack_serialized["parent_name"] = deck.name
@@ -2160,43 +2441,37 @@ if __name__ == "__main__":
 
     A = tree_to_list([resource_plr_to_ulab(deck)])
     with open("deck.json", "w", encoding="utf-8") as f:
-        A.insert(0, {
+        A.insert(
-            "id": "PRCXI",
+            0,
-            "name": "PRCXI",
+            {
-            "parent": None,
+                "id": "PRCXI",
-            "type": "device",
+                "name": "PRCXI",
-            "class": "liquid_handler.prcxi",
+                "parent": None,
-            "position": {
+                "type": "device",
-                "x": 0,
+                "class": "liquid_handler.prcxi",
-                "y": 0,
+                "position": {"x": 0, "y": 0, "z": 0},
-                "z": 0
+                "config": {
-            },
+                    "deck": {
-            "config": {
+                        "_resource_child_name": "PRCXI_Deck",
-                "deck": {
+                        "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck",
-                    "_resource_child_name": "PRCXI_Deck",
+                    },
-                    "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck"
+                    "host": "192.168.0.121",
+                    "port": 9999,
+                    "timeout": 10.0,
+                    "axis": "Right",
+                    "channel_num": 1,
+                    "setup": False,
+                    "debug": True,
+                    "simulator": True,
+                    "matrix_id": "5de524d0-3f95-406c-86dd-f83626ebc7cb",
+                    "is_9320": True,
                 },
-                "host": "192.168.0.121",
+                "data": {},
-                "port": 9999,
+                "children": ["PRCXI_Deck"],
-                "timeout": 10.0,
-                "axis": "Right",
-                "channel_num": 1,
-                "setup": False,
-                "debug": True,
-                "simulator": True,
-                "matrix_id": "5de524d0-3f95-406c-86dd-f83626ebc7cb",
-                "is_9320": True
             },
-            "data": {},
+        )
-            "children": [
-                "PRCXI_Deck"
-            ]
-        })
         A[1]["parent"] = "PRCXI"
-        json.dump({
+        json.dump({"nodes": A, "links": []}, f, indent=4, ensure_ascii=False)
-            "nodes": A,
-            "links": []
-        }, f, indent=4, ensure_ascii=False)
 
     handler = PRCXI9300Handler(
         deck=deck,
@@ -2238,7 +2513,6 @@ if __name__ == "__main__":
     time.sleep(5)
     os._exit(0)
 
-
     prcxi_api = PRCXI9300Api(host="192.168.0.121", port=9999)
     prcxi_api.list_matrices()
     prcxi_api.get_all_materials()

unilabos/devices/liquid_handling/test_transfer_liquid.py

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

unilabos/devices/ros_dev/liquid_handler_joint_publisher.py

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

unilabos/devices/virtual/virtual_sample_demo.py

@@ -0,0 +1,88 @@
+"""虚拟样品演示设备 — 用于前端 sample tracking 功能的极简 demo"""
+
+import asyncio
+import logging
+import random
+import time
+from typing import Any, Dict, List, Optional
+
+
+class VirtualSampleDemo:
+    """虚拟样品追踪演示设备，提供两种典型返回模式：
+    - measure_samples: 等长输入输出 (前端按 index 自动对齐)
+    - split_and_measure: 输出比输入长，附带 samples 列标注归属
+    """
+
+    def __init__(self, device_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, **kwargs):
+        if device_id is None and "id" in kwargs:
+            device_id = kwargs.pop("id")
+        if config is None and "config" in kwargs:
+            config = kwargs.pop("config")
+
+        self.device_id = device_id or "unknown_sample_demo"
+        self.config = config or {}
+        self.logger = logging.getLogger(f"VirtualSampleDemo.{self.device_id}")
+        self.data: Dict[str, Any] = {"status": "Idle"}
+
+    # ------------------------------------------------------------------
+    # Action 1: 等长输入输出，无 samples 列
+    # ------------------------------------------------------------------
+    async def measure_samples(self, concentrations: List[float]) -> Dict[str, Any]:
+        """模拟光度测量。absorbance = concentration * 0.05 + noise
+
+        入参和出参 list 长度相等，前端按 index 自动对齐。
+        """
+        self.logger.info(f"measure_samples: concentrations={concentrations}")
+        absorbance = [round(c * 0.05 + random.gauss(0, 0.005), 4) for c in concentrations]
+        return {"concentrations": concentrations, "absorbance": absorbance}
+
+    # ------------------------------------------------------------------
+    # Action 2: 输出比输入长，带 samples 列
+    # ------------------------------------------------------------------
+    async def split_and_measure(self, volumes: List[float], split_count: int = 3) -> Dict[str, Any]:
+        """将每个样品均分为 split_count 份后逐份测量。
+
+        返回的 list 长度 = len(volumes) * split_count，
+        附带 samples 列标注每行属于第几个输入样品 (0-based index)。
+        """
+        self.logger.info(f"split_and_measure: volumes={volumes}, split_count={split_count}")
+        out_volumes: List[float] = []
+        readings: List[float] = []
+        samples: List[int] = []
+
+        for idx, vol in enumerate(volumes):
+            split_vol = round(vol / split_count, 2)
+            for _ in range(split_count):
+                out_volumes.append(split_vol)
+                readings.append(round(random.uniform(0.1, 1.0), 4))
+                samples.append(idx)
+
+        return {"volumes": out_volumes, "readings": readings, "unilabos_samples": samples}
+
+    # ------------------------------------------------------------------
+    # Action 3: 入参和出参都带 samples 列（不等长）
+    # ------------------------------------------------------------------
+    async def analyze_readings(self, readings: List[float], samples: List[int]) -> Dict[str, Any]:
+        """对 split_and_measure 的输出做二次分析。
+
+        入参 readings/samples 长度相同但 > 原始样品数，
+        出参同样带 samples 列，长度与入参一致。
+        """
+        self.logger.info(f"analyze_readings: readings={readings}, samples={samples}")
+        scores: List[float] = []
+        passed: List[bool] = []
+        threshold = 0.4
+
+        for r in readings:
+            score = round(r * 100 + random.gauss(0, 2), 2)
+            scores.append(score)
+            passed.append(r >= threshold)
+
+        return {"scores": scores, "passed": passed, "unilabos_samples": samples}
+
+    # ------------------------------------------------------------------
+    # 状态属性
+    # ------------------------------------------------------------------
+    @property
+    def status(self) -> str:
+        return self.data.get("status", "Idle")

unilabos/devices/virtual/virtual_transferpump.py

@@ -31,14 +31,14 @@ class VirtualTransferPump:
 
         # 从config或kwargs中获取参数，确保类型正确
         if config:
-            self.max_volume = float(config.get('max_volume', 25.0))
+            self.max_volume = float(config.get("max_volume", 25.0))
-            self.port = config.get('port', 'VIRTUAL')
+            self.port = config.get("port", "VIRTUAL")
         else:
-            self.max_volume = float(kwargs.get('max_volume', 25.0))
+            self.max_volume = float(kwargs.get("max_volume", 25.0))
-            self.port = kwargs.get('port', 'VIRTUAL')
+            self.port = kwargs.get("port", "VIRTUAL")
 
-        self._transfer_rate = float(kwargs.get('transfer_rate', 0))
+        self._transfer_rate = float(kwargs.get("transfer_rate", 0))
-        self.mode = kwargs.get('mode', VirtualPumpMode.Normal)
+        self.mode = kwargs.get("mode", VirtualPumpMode.Normal)
 
         # 状态变量 - 确保都是正确类型
         self._status = "Idle"
@@ -54,7 +54,9 @@ class VirtualTransferPump:
         self.logger = logging.getLogger(f"VirtualTransferPump.{self.device_id}")
 
         print(f"🚰 === 虚拟转移泵 {self.device_id} 已创建 === ✨")
-        print(f"💨 快速模式: {'启用' if self._fast_mode else '禁用'} | 移动时间: {self._fast_move_time}s | 喷射时间: {self._fast_dispense_time}s")
+        print(
+            f"💨 快速模式: {'启用' if self._fast_mode else '禁用'} | 移动时间: {self._fast_move_time}s | 喷射时间: {self._fast_dispense_time}s"
+        )
         print(f"📊 最大容量: {self.max_volume}mL | 端口: {self.port}")
 
     def post_init(self, ros_node: BaseROS2DeviceNode):
@@ -189,7 +191,9 @@ class VirtualTransferPump:
                 operation_emoji = "📍"
 
             self.logger.info(f"🎯 SET_POSITION: {operation_type} {operation_emoji}")
-            self.logger.info(f"  📍 位置: {self._position:.2f}mL → {target_position:.2f}mL (移动 {volume_to_move:.2f}mL)")
+            self.logger.info(
+                f"  📍 位置: {self._position:.2f}mL → {target_position:.2f}mL (移动 {volume_to_move:.2f}mL)"
+            )
             self.logger.info(f"  🌊 速度: {velocity:.2f} mL/s")
             self.logger.info(f"  ⏰ 预计时间: {display_duration:.2f}s")
 
@@ -207,7 +211,11 @@ class VirtualTransferPump:
                 for i in range(steps + 1):
                     # 计算当前位置和进度
                     progress = (i / steps) * 100 if steps > 0 else 100
-                    current_pos = start_position + (target_position - start_position) * (i / steps) if steps > 0 else target_position
+                    current_pos = (
+                        start_position + (target_position - start_position) * (i / steps)
+                        if steps > 0
+                        else target_position
+                    )
 
                     # 更新状态
                     if i < steps:
@@ -244,7 +252,9 @@ class VirtualTransferPump:
 
             # 📊 最终状态日志
             if volume_to_move > 0.01:
-                self.logger.info(f"🎉 SET_POSITION 完成! 📍 最终位置: {self._position:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL")
+                self.logger.info(
+                    f"🎉 SET_POSITION 完成! 📍 最终位置: {self._position:.2f}mL | 💧 当前体积: {self._current_volume:.2f}mL"
+                )
 
             # 返回符合action定义的结果
             return {
@@ -252,7 +262,7 @@ class VirtualTransferPump:
                 "message": f"✅ 成功移动到位置 {self._position:.2f}mL ({operation_type})",
                 "final_position": self._position,
                 "final_volume": self._current_volume,
-                "operation_type": operation_type
+                "operation_type": operation_type,
             }
 
         except Exception as e:
@@ -262,7 +272,7 @@ class VirtualTransferPump:
                 "success": False,
                 "message": error_msg,
                 "final_position": self._position,
-                "final_volume": self._current_volume
+                "final_volume": self._current_volume,
             }
 
     # 其他泵操作方法
@@ -388,7 +398,9 @@ class VirtualTransferPump:
         return self._current_volume >= (self.max_volume - 0.01)  # 允许小量误差
 
     def __str__(self):
-        return f"VirtualTransferPump({self.device_id}: {self._current_volume:.2f}/{self.max_volume} ml, {self._status})"
+        return (
+            f"VirtualTransferPump({self.device_id}: {self._current_volume:.2f}/{self.max_volume} ml, {self._status})"
+        )
 
     def __repr__(self):
         return self.__str__()

unilabos/devices/virtual/workbench.py

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

unilabos/registry/decorators.py

@@ -0,0 +1,658 @@
+"""
+装饰器注册表系统
+
+通过 @device, @action, @resource 装饰器替代 YAML 配置文件来定义设备/动作/资源注册表信息。
+
+Usage:
+    from unilabos.registry.decorators import (
+        device, action, resource,
+        InputHandle, OutputHandle,
+        ActionInputHandle, ActionOutputHandle,
+        HardwareInterface, Side, DataSource, NodeType,
+    )
+
+    @device(
+        id="solenoid_valve.mock",
+        category=["pump_and_valve"],
+        description="模拟电磁阀设备",
+        handles=[
+            InputHandle(key="in", data_type="fluid", label="in", side=Side.NORTH),
+            OutputHandle(key="out", data_type="fluid", label="out", side=Side.SOUTH),
+        ],
+        hardware_interface=HardwareInterface(
+            name="hardware_interface",
+            read="send_command",
+            write="send_command",
+        ),
+    )
+    class SolenoidValveMock:
+        @action(action_type=EmptyIn)
+        def close(self):
+            ...
+
+        @action(
+            handles=[
+                ActionInputHandle(key="in", data_type="fluid", label="in"),
+                ActionOutputHandle(key="out", data_type="fluid", label="out"),
+            ],
+        )
+        def set_valve_position(self, position):
+            ...
+
+        # 无 @action 装饰器 => auto- 前缀动作
+        def is_open(self):
+            ...
+"""
+
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ---------------------------------------------------------------------------
+# 枚举
+# ---------------------------------------------------------------------------
+
+
+class Side(str, Enum):
+    """UI 上 Handle 的显示位置"""
+
+    NORTH = "NORTH"
+    SOUTH = "SOUTH"
+    EAST = "EAST"
+    WEST = "WEST"
+
+
+class DataSource(str, Enum):
+    """Handle 的数据来源"""
+
+    HANDLE = "handle"  # 从上游 handle 获取数据 (用于 InputHandle)
+    EXECUTOR = "executor"  # 从执行器输出数据 (用于 OutputHandle)
+
+
+class NodeType(str, Enum):
+    """动作的节点类型（用于区分 ILab 节点和人工确认节点等）"""
+
+    ILAB = "ILab"
+    MANUAL_CONFIRM = "manual_confirm"
+
+
+# ---------------------------------------------------------------------------
+# Device / Resource Handle (设备/资源级别端口, 序列化时包含 io_type)
+# ---------------------------------------------------------------------------
+
+
+class _DeviceHandleBase(BaseModel):
+    """设备/资源端口基类 (内部使用)"""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    key: str = Field(serialization_alias="handler_key")
+    data_type: str
+    label: str
+    side: Optional[Side] = None
+    data_key: Optional[str] = None
+    data_source: Optional[str] = None
+    description: Optional[str] = None
+
+    # 子类覆盖
+    io_type: str = ""
+
+    def to_registry_dict(self) -> Dict[str, Any]:
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class InputHandle(_DeviceHandleBase):
+    """
+    输入端口 (io_type="target"), 用于 @device / @resource handles
+
+    Example:
+        InputHandle(key="in", data_type="fluid", label="in", side=Side.NORTH)
+    """
+
+    io_type: str = "target"
+
+
+class OutputHandle(_DeviceHandleBase):
+    """
+    输出端口 (io_type="source"), 用于 @device / @resource handles
+
+    Example:
+        OutputHandle(key="out", data_type="fluid", label="out", side=Side.SOUTH)
+    """
+
+    io_type: str = "source"
+
+
+# ---------------------------------------------------------------------------
+# Action Handle (动作级别端口, 序列化时不含 io_type, 按类型自动分组)
+# ---------------------------------------------------------------------------
+
+
+class _ActionHandleBase(BaseModel):
+    """动作端口基类 (内部使用)"""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    key: str = Field(serialization_alias="handler_key")
+    data_type: str
+    label: str
+    side: Optional[Side] = None
+    data_key: Optional[str] = None
+    data_source: Optional[str] = None
+    description: Optional[str] = None
+    io_type: Optional[str] = None  # source/sink (dataflow) or target/source (device-style)
+
+    def to_registry_dict(self) -> Dict[str, Any]:
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class ActionInputHandle(_ActionHandleBase):
+    """
+    动作输入端口, 用于 @action handles, 序列化后归入 "input" 组
+
+    Example:
+        ActionInputHandle(
+            key="material_input", data_type="workbench_material",
+            label="物料编号", data_key="material_number", data_source="handle",
+        )
+    """
+
+    pass
+
+
+class ActionOutputHandle(_ActionHandleBase):
+    """
+    动作输出端口, 用于 @action handles, 序列化后归入 "output" 组
+
+    Example:
+        ActionOutputHandle(
+            key="station_output", data_type="workbench_station",
+            label="加热台ID", data_key="station_id", data_source="executor",
+        )
+    """
+
+    pass
+
+
+# ---------------------------------------------------------------------------
+# HardwareInterface
+# ---------------------------------------------------------------------------
+
+
+class HardwareInterface(BaseModel):
+    """
+    硬件通信接口定义
+
+    描述设备与底层硬件通信的方式 (串口、Modbus 等)。
+
+    Example:
+        HardwareInterface(name="hardware_interface", read="send_command", write="send_command")
+    """
+
+    name: str
+    read: Optional[str] = None
+    write: Optional[str] = None
+    extra_info: Optional[List[str]] = None
+
+
+# ---------------------------------------------------------------------------
+# 全局注册表 -- 记录所有被装饰器标记的类/函数
+# ---------------------------------------------------------------------------
+_registered_devices: Dict[str, type] = {}  # device_id -> class
+_registered_resources: Dict[str, Any] = {}  # resource_id -> class or function
+
+
+def _device_handles_to_list(
+    handles: Optional[List[_DeviceHandleBase]],
+) -> List[Dict[str, Any]]:
+    """将设备/资源 Handle 列表序列化为字典列表 (含 io_type)"""
+    if handles is None:
+        return []
+    return [h.to_registry_dict() for h in handles]
+
+
+def _action_handles_to_dict(
+    handles: Optional[List[_ActionHandleBase]],
+) -> Dict[str, Any]:
+    """
+    将动作 Handle 列表序列化为 {"input": [...], "output": [...]} 格式。
+
+    ActionInputHandle => "input", ActionOutputHandle => "output"
+    """
+    if handles is None:
+        return {}
+    input_list = [h.to_registry_dict() for h in handles if isinstance(h, ActionInputHandle)]
+    output_list = [h.to_registry_dict() for h in handles if isinstance(h, ActionOutputHandle)]
+    result: Dict[str, Any] = {}
+    if input_list:
+        result["input"] = input_list
+    if output_list:
+        result["output"] = output_list
+    return result
+
+
+# ---------------------------------------------------------------------------
+# @device 类装饰器
+# ---------------------------------------------------------------------------
+
+
+# noinspection PyShadowingBuiltins
+def device(
+    id: Optional[str] = None,
+    ids: Optional[List[str]] = None,
+    id_meta: Optional[Dict[str, Dict[str, Any]]] = None,
+    category: Optional[List[str]] = None,
+    description: str = "",
+    display_name: str = "",
+    icon: str = "",
+    version: str = "1.0.0",
+    handles: Optional[List[_DeviceHandleBase]] = None,
+    model: Optional[Dict[str, Any]] = None,
+    device_type: str = "python",
+    hardware_interface: Optional[HardwareInterface] = None,
+):
+    """
+    设备类装饰器
+
+    将类标记为一个 UniLab-OS 设备，并附加注册表元数据。
+
+    支持两种模式:
+      1. 单设备: id="xxx", category=[...]
+      2. 多设备: ids=["id1","id2"], id_meta={"id1":{handles:[...]}, "id2":{...}}
+
+    Args:
+        id: 单设备时的注册表唯一标识
+        ids: 多设备时的 id 列表，与 id_meta 配合使用
+        id_meta: 每个 device_id 的覆盖元数据 (handles/description/icon/model)
+        category: 设备分类标签列表 (必填)
+        description: 设备描述
+        display_name: 人类可读的设备显示名称，缺失时默认使用 id
+        icon: 图标路径
+        version: 版本号
+        handles: 设备端口列表 (单设备或 id_meta 未覆盖时使用)
+        model: 可选的 3D 模型配置
+        device_type: 设备实现类型 ("python" / "ros2")
+        hardware_interface: 硬件通信接口 (HardwareInterface)
+    """
+    # Resolve device ids
+    if ids is not None:
+        device_ids = list(ids)
+        if not device_ids:
+            raise ValueError("@device ids 不能为空")
+        id_meta = id_meta or {}
+    elif id is not None:
+        device_ids = [id]
+        id_meta = {}
+    else:
+        raise ValueError("@device 必须提供 id 或 ids")
+
+    if category is None:
+        raise ValueError("@device category 必填")
+
+    base_meta = {
+        "category": category,
+        "description": description,
+        "display_name": display_name,
+        "icon": icon,
+        "version": version,
+        "handles": _device_handles_to_list(handles),
+        "model": model,
+        "device_type": device_type,
+        "hardware_interface": (hardware_interface.model_dump(exclude_none=True) if hardware_interface else None),
+    }
+
+    def decorator(cls):
+        cls._device_registry_meta = base_meta
+        cls._device_registry_id_meta = id_meta
+        cls._device_registry_ids = device_ids
+
+        for did in device_ids:
+            if did in _registered_devices:
+                raise ValueError(f"@device id 重复: '{did}' 已被 {_registered_devices[did]} 注册")
+            _registered_devices[did] = cls
+
+        return cls
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# @action 方法装饰器
+# ---------------------------------------------------------------------------
+
+# 区分 "用户没传 action_type" 和 "用户传了 None"
+_ACTION_TYPE_UNSET = object()
+
+
+# noinspection PyShadowingNames
+def action(
+    action_type: Any = _ACTION_TYPE_UNSET,
+    goal: Optional[Dict[str, str]] = None,
+    feedback: Optional[Dict[str, str]] = None,
+    result: Optional[Dict[str, str]] = None,
+    handles: Optional[List[_ActionHandleBase]] = None,
+    goal_default: Optional[Dict[str, Any]] = None,
+    placeholder_keys: Optional[Dict[str, str]] = None,
+    always_free: bool = False,
+    is_protocol: bool = False,
+    description: str = "",
+    auto_prefix: bool = False,
+    parent: bool = False,
+    node_type: Optional["NodeType"] = None,
+):
+    """
+    动作方法装饰器
+
+    标记方法为注册表动作。有三种用法:
+      1. @action(action_type=EmptyIn, ...)  -- 非 auto, 使用指定 ROS Action 类型
+      2. @action()                          -- 非 auto, UniLabJsonCommand (从方法签名生成 schema)
+      3. 不加 @action                       -- auto- 前缀, UniLabJsonCommand
+
+    Protocol 用法:
+      @action(action_type=Add, is_protocol=True)
+      def AddProtocol(self): ...
+      标记该动作为高级协议 (protocol)，运行时通过 ROS Action 路由到
+      protocol generator 执行。action_type 指向 unilabos_msgs 的 Action 类型。
+
+    Args:
+        action_type: ROS Action 消息类型 (如 EmptyIn, SendCmd, HeatChill).
+                     不传/默认 = UniLabJsonCommand (非 auto).
+        goal: Goal 字段映射 (ROS字段名 -> 设备参数名).
+              protocol 模式下可留空，系统自动生成 identity 映射.
+        feedback: Feedback 字段映射
+        result: Result 字段映射
+        handles: 动作端口列表 (ActionInputHandle / ActionOutputHandle)
+        goal_default: Goal 字段默认值映射 (字段名 -> 默认值), 与自动生成的 goal_default 合并
+        placeholder_keys: 参数占位符配置
+        always_free: 是否为永久闲置动作 (不受排队限制)
+        is_protocol: 是否为工作站协议 (protocol)。True 时运行时走 protocol generator 路径。
+        description: 动作描述
+        auto_prefix: 若为 True，动作名使用 auto-{method_name} 形式（与无 @action 时一致）
+        parent: 若为 True，当方法参数为空 (*args, **kwargs) 时，通过 MRO 从父类获取真实方法参数
+        node_type: 动作的节点类型 (NodeType.ILAB / NodeType.MANUAL_CONFIRM)。
+                   不填写时不写入注册表。
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # action_type 为哨兵值 => 用户没传, 视为 None (UniLabJsonCommand)
+        resolved_type = None if action_type is _ACTION_TYPE_UNSET else action_type
+
+        meta = {
+            "action_type": resolved_type,
+            "goal": goal or {},
+            "feedback": feedback or {},
+            "result": result or {},
+            "handles": _action_handles_to_dict(handles),
+            "goal_default": goal_default or {},
+            "placeholder_keys": placeholder_keys or {},
+            "always_free": always_free,
+            "is_protocol": is_protocol,
+            "description": description,
+            "auto_prefix": auto_prefix,
+            "parent": parent,
+        }
+        if node_type is not None:
+            meta["node_type"] = node_type.value if isinstance(node_type, NodeType) else str(node_type)
+        wrapper._action_registry_meta = meta  # type: ignore[attr-defined]
+
+        # 设置 _is_always_free 保持与旧 @always_free 装饰器兼容
+        if always_free:
+            wrapper._is_always_free = True  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def get_action_meta(func) -> Optional[Dict[str, Any]]:
+    """获取方法上的 @action 装饰器元数据"""
+    return getattr(func, "_action_registry_meta", None)
+
+
+def has_action_decorator(func) -> bool:
+    """检查函数是否带有 @action 装饰器"""
+    return hasattr(func, "_action_registry_meta")
+
+
+# ---------------------------------------------------------------------------
+# @resource 类/函数装饰器
+# ---------------------------------------------------------------------------
+
+
+def resource(
+    id: str,
+    category: List[str],
+    description: str = "",
+    icon: str = "",
+    version: str = "1.0.0",
+    handles: Optional[List[_DeviceHandleBase]] = None,
+    model: Optional[Dict[str, Any]] = None,
+    class_type: str = "pylabrobot",
+):
+    """
+    资源类/函数装饰器
+
+    将类或工厂函数标记为一个 UniLab-OS 资源，附加注册表元数据。
+
+    Args:
+        id: 注册表唯一标识 (必填, 不可重复)
+        category: 资源分类标签列表 (必填)
+        description: 资源描述
+        icon: 图标路径
+        version: 版本号
+        handles: 端口列表 (InputHandle / OutputHandle)
+        model: 可选的 3D 模型配置
+        class_type: 资源实现类型 ("python" / "pylabrobot" / "unilabos")
+    """
+
+    def decorator(obj):
+        meta = {
+            "resource_id": id,
+            "category": category,
+            "description": description,
+            "icon": icon,
+            "version": version,
+            "handles": _device_handles_to_list(handles),
+            "model": model,
+            "class_type": class_type,
+        }
+        obj._resource_registry_meta = meta
+
+        if id in _registered_resources:
+            raise ValueError(f"@resource id 重复: '{id}' 已被 {_registered_resources[id]} 注册")
+        _registered_resources[id] = obj
+
+        return obj
+
+    return decorator
+
+
+def get_device_meta(cls, device_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """
+    获取类上的 @device 装饰器元数据。
+
+    当 device_id 存在且类使用 ids+id_meta 时，返回合并后的 meta
+    (base_meta 与 id_meta[device_id] 深度合并)。
+    """
+    base = getattr(cls, "_device_registry_meta", None)
+    if base is None:
+        return None
+    id_meta = getattr(cls, "_device_registry_id_meta", None) or {}
+    if device_id is None or device_id not in id_meta:
+        result = dict(base)
+        ids = getattr(cls, "_device_registry_ids", None)
+        result["device_id"] = device_id if device_id is not None else (ids[0] if ids else None)
+        return result
+
+    overrides = id_meta[device_id]
+    result = dict(base)
+    result["device_id"] = device_id
+    for key in ["handles", "description", "icon", "model"]:
+        if key in overrides:
+            val = overrides[key]
+            if key == "handles" and isinstance(val, list):
+                # handles 必须是 Handle 对象列表
+                result[key] = [h.to_registry_dict() for h in val]
+            else:
+                result[key] = val
+    return result
+
+
+def get_resource_meta(obj) -> Optional[Dict[str, Any]]:
+    """获取对象上的 @resource 装饰器元数据"""
+    return getattr(obj, "_resource_registry_meta", None)
+
+
+def get_all_registered_devices() -> Dict[str, type]:
+    """获取所有已注册的设备类"""
+    return _registered_devices.copy()
+
+
+def get_all_registered_resources() -> Dict[str, Any]:
+    """获取所有已注册的资源"""
+    return _registered_resources.copy()
+
+
+def clear_registry():
+    """清空全局注册表 (用于测试)"""
+    _registered_devices.clear()
+    _registered_resources.clear()
+
+
+# ---------------------------------------------------------------------------
+# 枚举值归一化
+# ---------------------------------------------------------------------------
+
+
+def normalize_enum_value(raw: Any, enum_cls) -> Optional[str]:
+    """将 AST 提取的枚举成员名 / YAML 值字符串 / 旧格式长路径统一归一化为枚举值。
+
+    适用于 Side、DataSource、NodeType 等继承自 ``str, Enum`` 的装饰器枚举。
+
+    处理以下格式:
+      - "MANUAL_CONFIRM"  →  NodeType["MANUAL_CONFIRM"].value = "manual_confirm"
+      - "manual_confirm"  →  NodeType("manual_confirm").value = "manual_confirm"
+      - "HANDLE"          →  DataSource["HANDLE"].value = "handle"
+      - "NORTH"           →  Side["NORTH"].value = "NORTH"
+      - 旧缓存长路径 "unilabos...NodeType.MANUAL_CONFIRM" → 先 rsplit 再查找
+    """
+    if not raw:
+        return None
+    raw_str = str(raw)
+    if "." in raw_str:
+        raw_str = raw_str.rsplit(".", 1)[-1]
+    try:
+        return enum_cls[raw_str].value
+    except KeyError:
+        pass
+    try:
+        return enum_cls(raw_str).value
+    except ValueError:
+        return raw_str
+
+
+# ---------------------------------------------------------------------------
+# topic_config / not_action / always_free 装饰器
+# ---------------------------------------------------------------------------
+
+
+def topic_config(
+    period: Optional[float] = None,
+    print_publish: Optional[bool] = None,
+    qos: Optional[int] = None,
+    name: Optional[str] = None,
+) -> Callable[[F], F]:
+    """
+    Topic发布配置装饰器
+
+    用于装饰 get_{attr_name} 方法或 @property，控制对应属性的ROS topic发布行为。
+
+    Args:
+        period: 发布周期（秒）。None 表示使用默认值 5.0
+        print_publish: 是否打印发布日志。None 表示使用节点默认配置
+        qos: QoS深度配置。None 表示使用默认值 10
+        name: 自定义发布名称。None 表示使用方法名（去掉 get_ 前缀）
+
+    Note:
+        与 @property 连用时，@topic_config 必须放在 @property 下面，
+        这样装饰器执行顺序为：先 topic_config 添加配置，再 property 包装。
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        wrapper._topic_period = period  # type: ignore[attr-defined]
+        wrapper._topic_print_publish = print_publish  # type: ignore[attr-defined]
+        wrapper._topic_qos = qos  # type: ignore[attr-defined]
+        wrapper._topic_name = name  # type: ignore[attr-defined]
+        wrapper._has_topic_config = True  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def get_topic_config(func) -> dict:
+    """获取函数上的 topic 配置 (period, print_publish, qos, name)"""
+    if hasattr(func, "_has_topic_config") and getattr(func, "_has_topic_config", False):
+        return {
+            "period": getattr(func, "_topic_period", None),
+            "print_publish": getattr(func, "_topic_print_publish", None),
+            "qos": getattr(func, "_topic_qos", None),
+            "name": getattr(func, "_topic_name", None),
+        }
+    return {}
+
+
+def always_free(func: F) -> F:
+    """
+    标记动作为永久闲置(不受busy队列限制)的装饰器
+
+    被此装饰器标记的 action 方法，在执行时不会受到设备级别的排队限制，
+    任何时候请求都可以立即执行。适用于查询类、状态读取类等轻量级操作。
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    wrapper._is_always_free = True  # type: ignore[attr-defined]
+
+    return wrapper  # type: ignore[return-value]
+
+
+def is_always_free(func) -> bool:
+    """检查函数是否被标记为永久闲置"""
+    return getattr(func, "_is_always_free", False)
+
+
+def not_action(func: F) -> F:
+    """
+    标记方法为非动作的装饰器
+
+    用于装饰 driver 类中的方法，使其在注册表扫描时不被识别为动作。
+    适用于辅助方法、内部工具方法等不应暴露为设备动作的公共方法。
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    wrapper._is_not_action = True  # type: ignore[attr-defined]
+
+    return wrapper  # type: ignore[return-value]
+
+
+def is_not_action(func) -> bool:
+    """检查函数是否被标记为非动作"""
+    return getattr(func, "_is_not_action", False)

unilabos/registry/device_comms/communication_devices.yaml

@@ -96,10 +96,13 @@ serial:
           type: string
         port:
           type: string
+        registry_name:
+          type: string
         resource_tracker:
           type: object
       required:
       - device_id
+      - registry_name
       - port
       type: object
     data:

unilabos/registry/devices/Qone_nmr.yaml

@@ -13,21 +13,18 @@ Qone_nmr:
           description: ''
           properties:
             feedback:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: EmptyIn_Feedback
               type: object
             goal:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: EmptyIn_Goal
               type: object
             result:
+              additionalProperties: false
               properties:
                 return_info:
                   type: string
-              required:
-              - return_info
               title: EmptyIn_Result
               type: object
           required:
@@ -71,31 +68,6 @@ Qone_nmr:
           title: monitor_folder_for_new_content参数
           type: object
         type: UniLabJsonCommand
-      auto-post_init:
-        feedback: {}
-        goal: {}
-        goal_default:
-          ros_node: null
-        handles: {}
-        placeholder_keys: {}
-        result: {}
-        schema:
-          description: ''
-          properties:
-            feedback: {}
-            goal:
-              properties:
-                ros_node:
-                  type: string
-              required:
-              - ros_node
-              type: object
-            result: {}
-          required:
-          - goal
-          title: post_init参数
-          type: object
-        type: UniLabJsonCommand
       auto-strings_to_txt:
         feedback: {}
         goal: {}
@@ -138,21 +110,18 @@ Qone_nmr:
           description: ''
           properties:
             feedback:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: EmptyIn_Feedback
               type: object
             goal:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: EmptyIn_Goal
               type: object
             result:
+              additionalProperties: false
               properties:
                 return_info:
                   type: string
-              required:
-              - return_info
               title: EmptyIn_Result
               type: object
           required:
@@ -167,32 +136,31 @@ Qone_nmr:
         goal_default:
           string: ''
         handles: {}
-        result: {}
+        placeholder_keys: {}
+        result:
+          return_info: return_info
+          success: success
         schema:
           description: ''
           properties:
             feedback:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: StrSingleInput_Feedback
               type: object
             goal:
+              additionalProperties: false
               properties:
                 string:
                   type: string
-              required:
-              - string
               title: StrSingleInput_Goal
               type: object
             result:
+              additionalProperties: false
               properties:
                 return_info:
                   type: string
                 success:
                   type: boolean
-              required:
-              - return_info
-              - success
               title: StrSingleInput_Result
               type: object
           required:

unilabos/registry/devices/bioyond_dispensing_station.yaml

@@ -24,77 +24,13 @@ bioyond_dispensing_station:
               required:
               - data
               type: object
-            result: {}
+            result:
+              type: object
           required:
           - goal
           title: brief_step_parameters参数
           type: object
         type: UniLabJsonCommand
-      auto-compute_experiment_design:
-        feedback: {}
-        goal: {}
-        goal_default:
-          m_tot: '70'
-          ratio: null
-          titration_percent: '0.03'
-          wt_percent: '0.25'
-        handles: {}
-        placeholder_keys: {}
-        result: {}
-        schema:
-          description: ''
-          properties:
-            feedback: {}
-            goal:
-              properties:
-                m_tot:
-                  default: '70'
-                  type: string
-                ratio:
-                  type: object
-                titration_percent:
-                  default: '0.03'
-                  type: string
-                wt_percent:
-                  default: '0.25'
-                  type: string
-              required:
-              - ratio
-              type: object
-            result:
-              properties:
-                feeding_order:
-                  items: {}
-                  title: Feeding Order
-                  type: array
-                return_info:
-                  title: Return Info
-                  type: string
-                solutions:
-                  items: {}
-                  title: Solutions
-                  type: array
-                solvents:
-                  additionalProperties: true
-                  title: Solvents
-                  type: object
-                titration:
-                  additionalProperties: true
-                  title: Titration
-                  type: object
-              required:
-              - solutions
-              - titration
-              - solvents
-              - feeding_order
-              - return_info
-              title: ComputeExperimentDesignReturn
-              type: object
-          required:
-          - goal
-          title: compute_experiment_design参数
-          type: object
-        type: UniLabJsonCommand
       auto-process_order_finish_report:
         feedback: {}
         goal: {}
@@ -118,7 +54,8 @@ bioyond_dispensing_station:
               - report_request
               - used_materials
               type: object
-            result: {}
+            result:
+              type: object
           required:
           - goal
           title: process_order_finish_report参数
@@ -143,7 +80,8 @@ bioyond_dispensing_station:
               required:
               - order_id
               type: object
-            result: {}
+            result:
+              type: object
           required:
           - goal
           title: project_order_report参数
@@ -193,7 +131,8 @@ bioyond_dispensing_station:
               required:
               - workflow_id
               type: object
-            result: {}
+            result:
+              type: object
           required:
           - goal
           title: workflow_sample_locations参数
@@ -209,12 +148,12 @@ bioyond_dispensing_station:
           temperature: temperature
           titration: titration
         goal_default:
-          delay_time: '600'
+          delay_time: null
-          hold_m_name: ''
+          hold_m_name: null
           liquid_material_name: NMP
-          speed: '400'
+          speed: null
-          temperature: '40'
+          temperature: null
-          titration: ''
+          titration: null
         handles:
           input:
           - data_key: titration
@@ -230,20 +169,16 @@ bioyond_dispensing_station:
             handler_key: BATCH_CREATE_RESULT
             io_type: sink
             label: Complete Batch Create Result JSON (contains order_codes and order_ids)
-        result:
+        placeholder_keys: {}
-          return_info: return_info
+        result: {}
         schema:
           description: 批量创建90%10%小瓶投料任务。从计算节点接收titration数据,包含物料名称、主称固体质量、滴定固体质量和滴定溶剂体积。返回的return_info中包含order_codes和order_ids列表。
           properties:
             feedback:
-              properties: {}
-              required: []
               title: BatchCreate9010VialFeedingTasks_Feedback
-              type: object
             goal:
               properties:
                 delay_time:
-                  default: '600'
                   description: 延迟时间(秒),默认600
                   type: string
                 hold_m_name:
@@ -254,11 +189,9 @@ bioyond_dispensing_station:
                   description: 10%物料的液体物料名称,默认为"NMP"
                   type: string
                 speed:
-                  default: '400'
                   description: 搅拌速度,默认400
                   type: string
                 temperature:
-                  default: '40'
                   description: 温度(℃),默认40
                   type: string
                 titration:
@@ -267,21 +200,14 @@ bioyond_dispensing_station:
                   type: string
               required:
               - titration
-              - hold_m_name
               title: BatchCreate9010VialFeedingTasks_Goal
               type: object
             result:
-              properties:
-                return_info:
-                  description: 批量任务创建结果汇总JSON字符串，包含total(总数)、success(成功数)、failed(失败数)、order_codes(任务编码数组)、order_ids(任务ID数组)、details(每个任务的详细信息)
-                  type: string
-              required:
-              - return_info
               title: BatchCreate9010VialFeedingTasks_Result
-              type: object
+              type: string
           required:
           - goal
-          title: BatchCreate9010VialFeedingTasks
+          title: batch_create_90_10_vial_feeding_tasks参数
           type: object
         type: UniLabJsonCommand
       batch_create_diamine_solution_tasks:
@@ -293,11 +219,11 @@ bioyond_dispensing_station:
           speed: speed
           temperature: temperature
         goal_default:
-          delay_time: '600'
+          delay_time: null
           liquid_material_name: NMP
-          solutions: ''
+          solutions: null
-          speed: '400'
+          speed: null
-          temperature: '20'
+          temperature: null
         handles:
           input:
           - data_key: solutions
@@ -313,20 +239,16 @@ bioyond_dispensing_station:
             handler_key: BATCH_CREATE_RESULT
             io_type: sink
             label: Complete Batch Create Result JSON (contains order_codes and order_ids)
-        result:
+        placeholder_keys: {}
-          return_info: return_info
+        result: {}
         schema:
           description: 批量创建二胺溶液配置任务。自动为多个二胺样品创建溶液配置任务，每个任务包含固体物料称量、溶剂添加、搅拌混合等步骤。返回的return_info中包含order_codes和order_ids列表。
           properties:
             feedback:
-              properties: {}
-              required: []
               title: BatchCreateDiamineSolutionTasks_Feedback
-              type: object
             goal:
               properties:
                 delay_time:
-                  default: '600'
                   description: 溶液配置完成后的延迟时间（秒），用于充分混合和溶解，默认600秒
                   type: string
                 liquid_material_name:
@@ -340,11 +262,9 @@ bioyond_dispensing_station:
                     4.5, "solvent_volume": 18}]'
                   type: string
                 speed:
-                  default: '400'
                   description: 搅拌速度（rpm），用于混合溶液，默认400转/分钟
                   type: string
                 temperature:
-                  default: '20'
                   description: 配置温度（℃），溶液配置过程的目标温度，默认20℃（室温）
                   type: string
               required:
@@ -352,17 +272,109 @@ bioyond_dispensing_station:
               title: BatchCreateDiamineSolutionTasks_Goal
               type: object
             result:
+              title: BatchCreateDiamineSolutionTasks_Result
+              type: string
+          required:
+          - goal
+          title: batch_create_diamine_solution_tasks参数
+          type: object
+        type: UniLabJsonCommand
+      compute_experiment_design:
+        feedback: {}
+        goal:
+          m_tot: m_tot
+          ratio: ratio
+          titration_percent: titration_percent
+          wt_percent: wt_percent
+        goal_default:
+          m_tot: '70'
+          ratio: null
+          titration_percent: '0.03'
+          wt_percent: '0.25'
+        handles:
+          output:
+          - data_key: solutions
+            data_source: executor
+            data_type: array
+            handler_key: solutions
+            io_type: sink
+            label: Solution Data From Python
+          - data_key: titration
+            data_source: executor
+            data_type: object
+            handler_key: titration
+            io_type: sink
+            label: Titration Data From Calculation Node
+          - data_key: solvents
+            data_source: executor
+            data_type: object
+            handler_key: solvents
+            io_type: sink
+            label: Solvents Data From Calculation Node
+          - data_key: feeding_order
+            data_source: executor
+            data_type: array
+            handler_key: feeding_order
+            io_type: sink
+            label: Feeding Order Data From Calculation Node
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 计算实验设计，输出solutions/titration/solvents/feeding_order用于后续节点。
+          properties:
+            feedback: {}
+            goal:
               properties:
-                return_info:
+                m_tot:
-                  description: 批量任务创建结果汇总JSON字符串，包含total(总数)、success(成功数)、failed(失败数)、order_codes(任务编码数组)、order_ids(任务ID数组)、details(每个任务的详细信息)
+                  default: '70'
+                  description: 总质量(g)
+                  type: string
+                ratio:
+                  description: 组分摩尔比的对象，保持输入顺序，如{"MDA":1,"BTDA":1}
+                  type: object
+                titration_percent:
+                  default: '0.03'
+                  description: 滴定比例(10%部分)
+                  type: string
+                wt_percent:
+                  default: '0.25'
+                  description: 目标固含质量分数
                   type: string
               required:
+              - ratio
+              type: object
+            result:
+              properties:
+                feeding_order:
+                  items: {}
+                  title: Feeding Order
+                  type: array
+                return_info:
+                  title: Return Info
+                  type: string
+                solutions:
+                  items: {}
+                  title: Solutions
+                  type: array
+                solvents:
+                  additionalProperties: true
+                  title: Solvents
+                  type: object
+                titration:
+                  additionalProperties: true
+                  title: Titration
+                  type: object
+              required:
+              - solutions
+              - titration
+              - solvents
+              - feeding_order
               - return_info
-              title: BatchCreateDiamineSolutionTasks_Result
+              title: ComputeExperimentDesignReturn
               type: object
           required:
           - goal
-          title: BatchCreateDiamineSolutionTasks
+          title: compute_experiment_design参数
           type: object
         type: UniLabJsonCommand
       create_90_10_vial_feeding_task:
@@ -416,17 +428,18 @@ bioyond_dispensing_station:
           speed: ''
           temperature: ''
         handles: {}
+        placeholder_keys: {}
         result:
           return_info: return_info
         schema:
           description: ''
           properties:
             feedback:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: DispenStationVialFeed_Feedback
               type: object
             goal:
+              additionalProperties: false
               properties:
                 delay_time:
                   type: string
@@ -474,38 +487,13 @@ bioyond_dispensing_station:
                   type: string
                 temperature:
                   type: string
-              required:
-              - order_name
-              - percent_90_1_assign_material_name
-              - percent_90_1_target_weigh
-              - percent_90_2_assign_material_name
-              - percent_90_2_target_weigh
-              - percent_90_3_assign_material_name
-              - percent_90_3_target_weigh
-              - percent_10_1_assign_material_name
-              - percent_10_1_target_weigh
-              - percent_10_1_volume
-              - percent_10_1_liquid_material_name
-              - percent_10_2_assign_material_name
-              - percent_10_2_target_weigh
-              - percent_10_2_volume
-              - percent_10_2_liquid_material_name
-              - percent_10_3_assign_material_name
-              - percent_10_3_target_weigh
-              - percent_10_3_volume
-              - percent_10_3_liquid_material_name
-              - speed
-              - temperature
-              - delay_time
-              - hold_m_name
               title: DispenStationVialFeed_Goal
               type: object
             result:
+              additionalProperties: false
               properties:
                 return_info:
                   type: string
-              required:
-              - return_info
               title: DispenStationVialFeed_Result
               type: object
           required:
@@ -536,17 +524,18 @@ bioyond_dispensing_station:
           temperature: ''
           volume: ''
         handles: {}
+        placeholder_keys: {}
         result:
           return_info: return_info
         schema:
           description: ''
           properties:
             feedback:
-              properties: {}
+              additionalProperties: true
-              required: []
               title: DispenStationSolnPrep_Feedback
               type: object
             goal:
+              additionalProperties: false
               properties:
                 delay_time:
                   type: string
@@ -566,24 +555,13 @@ bioyond_dispensing_station:
                   type: string
                 volume:
                   type: string
-              required:
-              - order_name
-              - material_name
-              - target_weigh
-              - volume
-              - liquid_material_name
-              - speed
-              - temperature
-              - delay_time
-              - hold_m_name
               title: DispenStationSolnPrep_Goal
               type: object
             result:
+              additionalProperties: false
               properties:
                 return_info:
                   type: string
-              required:
-              - return_info
               title: DispenStationSolnPrep_Result
               type: object
           required:
@@ -591,6 +569,64 @@ bioyond_dispensing_station:
           title: DispenStationSolnPrep
           type: object
         type: DispenStationSolnPrep
+      scheduler_start:
+        feedback: {}
+        goal: {}
+        goal_default: {}
+        handles: {}
+        placeholder_keys: {}
+        result: {}
+        schema:
+          description: 启动调度器 - 启动Bioyond配液站的任务调度器，开始执行队列中的任务
+          properties:
+            feedback: {}
+            goal:
+              properties: {}
+              required: []
+              type: object
+            result:
+              title: scheduler_start结果
+              type: object
+          required:
+          - goal
+          title: scheduler_start参数
+          type: object
+        type: UniLabJsonCommand
+      transfer_materials_to_reaction_station:
+        feedback: {}
+        goal:
+          target_device_id: target_device_id
+          transfer_groups: transfer_groups
+        goal_default:
+          target_device_id: null
+          transfer_groups: null
+        handles: {}
+        placeholder_keys:
+          target_device_id: unilabos_devices
+        result: {}
+        schema:
+          description: 将配液站完成的物料（溶液、样品等）转移到指定反应站的堆栈库位。支持配置多组转移任务，每组包含物料名称、目标堆栈和目标库位。
+          properties:
+            feedback: {}
+            goal:
+              properties:
+                target_device_id:
+                  description: 目标反应站设备ID（从设备列表中选择，所有转移组都使用同一个目标设备）
+                  type: string
+                transfer_groups:
+                  description: 转移任务组列表，每组包含物料名称、目标堆栈和目标库位，可以添加多组
+                  type: array
+              required:
+              - target_device_id
+              - transfer_groups
+              type: object
+            result:
+              type: object
+          required:
+          - goal
+          title: transfer_materials_to_reaction_station参数
+          type: object
+        type: UniLabJsonCommand
       wait_for_multiple_orders_and_get_reports:
         feedback: {}
         goal:
@@ -598,9 +634,9 @@ bioyond_dispensing_station:
           check_interval: check_interval
           timeout: timeout
         goal_default:
-          batch_create_result: ''
+          batch_create_result: null
-          check_interval: '10'
+          check_interval: 10
-          timeout: '7200'
+          timeout: 7200
         handles:
           input:
           - data_key: batch_create_result
@@ -616,50 +652,38 @@ bioyond_dispensing_station:
             handler_key: batch_reports_result
             io_type: sink
             label: Batch Order Completion Reports
-        result:
+        placeholder_keys: {}
-          return_info: return_info
+        result: {}
         schema:
           description: 同时等待多个任务完成并获取所有实验报告。从上游batch_create任务接收包含order_codes和order_ids的结果对象，并行监控所有任务状态并返回每个任务的报告。
           properties:
             feedback:
-              properties: {}
-              required: []
               title: WaitForMultipleOrdersAndGetReports_Feedback
-              type: object
             goal:
               properties:
                 batch_create_result:
                   description: 批量创建任务的返回结果对象，包含order_codes和order_ids数组。从上游batch_create节点通过handle传递
                   type: string
                 check_interval:
-                  default: '10'
+                  default: 10
                   description: 检查任务状态的时间间隔（秒），默认每10秒检查一次所有待完成任务
-                  type: string
+                  type: integer
                 timeout:
-                  default: '7200'
+                  default: 7200
                   description: 等待超时时间（秒），默认7200秒（2小时）。超过此时间未完成的任务将标记为timeout
-                  type: string
+                  type: integer
-              required:
+              required: []
-              - batch_create_result
               title: WaitForMultipleOrdersAndGetReports_Goal
               type: object
             result:
-              properties:
-                return_info:
-                  description: 'JSON格式的批量任务完成信息，包含: total(总数), completed(成功数), timeout(超时数),
-                    error(错误数), elapsed_time(总耗时), reports(报告数组，每个元素包含order_code,
-                    order_id, status, completion_status, report, elapsed_time)'
-                  type: string
-              required:
-              - return_info
               title: WaitForMultipleOrdersAndGetReports_Result
               type: object
           required:
           - goal
-          title: WaitForMultipleOrdersAndGetReports
+          title: wait_for_multiple_orders_and_get_reports参数
           type: object
         type: UniLabJsonCommand
-    module: unilabos.devices.workstation.bioyond_studio.dispensing_station:BioyondDispensingStation
+    module: unilabos.devices.workstation.bioyond_studio.dispensing_station.dispensing_station:BioyondDispensingStation
     status_types: {}
     type: python
   config_info: []
@@ -670,15 +694,16 @@ bioyond_dispensing_station:
     config:
       properties:
         config:
-          type: string
+          type: object
         deck:
           type: string
-      required:
+        protocol_type:
-      - config
+          type: string
-      - deck
+      required: []
       type: object
     data:
       properties: {}
       required: []
       type: object
+  model: {}
   version: 1.0.0