Upgrade to py 3.11.14; ROS2 Humble 0.7; unilabos 0.10.16

Workbench example, adjust log level, and ci check (#220) * TestLatency Return Value Example & gitignore update * Adjust log level & Add workbench virtual example & Add not action decorator & Add check_mode & * Add CI Check Fix/workstation yb revision (#217) * Revert log change & update registry * Revert opcua client & move electrolyte node Workstation yb merge dev ready 260113 (#216) * feat(bioyond): 添加计算实验设计功能，支持化合物配比和滴定比例参数 * feat(bioyond): 添加测量小瓶功能，支持基本参数配置 * feat(bioyond): 添加测量小瓶配置，支持新设备参数 * feat(bioyond): 更新仓库布局和尺寸，支持竖向排列的测量小瓶和试剂存放堆栈 * feat(bioyond): 优化任务创建流程，确保无论成功与否都清理任务队列以避免重复累积 * feat(bioyond): 添加设置反应器温度功能，支持温度范围和异常处理 * feat(bioyond): 调整反应器位置配置，统一坐标格式 * feat(bioyond): 添加调度器启动功能，支持任务队列执行并处理异常 * feat(bioyond): 优化调度器启动功能，添加异常处理并更新相关配置 * feat(opcua): 增强节点ID解析兼容性和数据类型处理改进节点ID解析逻辑以支持多种格式，包括字符串和数字标识符添加数据类型转换处理，确保写入值时类型匹配优化错误提示信息，便于调试节点连接问题 * feat(registry): 新增后处理站的设备配置文件添加后处理站的YAML配置文件，包含动作映射、状态类型和设备描述 * 添加调度器启动功能，合并物料参数配置，优化物料参数处理逻辑 * 添加从 Bioyond 系统自动同步工作流序列的功能，并更新相关配置 * fix：兼容 BioyondReactionStation 中 workflow_sequence 被重写为 property * fix:同步工作流序列 * feat: remove commented workflow synchronization from `reaction_station.py`. * 添加时间约束功能及相关配置 * fix：自动更新物料缓存功能，添加物料时更新缓存并在删除时移除缓存项 * fix：在添加物料时处理字符串和字典返回值，确保正确更新缓存 * fix：更新奔曜错误处理报送为物料变更报送，调整日志记录和响应消息 * feat：添加实验报告简化功能，去除冗余信息并保留关键信息 * feat: 添加任务状态事件发布功能，监控并报告任务运行、超时、完成和错误状态 * fix: 修复添加物料时数据格式错误 * Refactor bioyond_dispensing_station and reaction_station_bioyond YAML configurations - Removed redundant action value mappings from bioyond_dispensing_station. - Updated goal properties in bioyond_dispensing_station to use enums for target_stack and other parameters. - Changed data types for end_point and start_point in reaction_station_bioyond to use string enums (Start, End). - Simplified descriptions and updated measurement units from μL to mL where applicable. - Removed unused commands from reaction_station_bioyond to streamline the configuration. * fix：Change the material unit from μL to mL * fix：refresh_material_cache * feat: 动态获取工作流步骤ID，优化工作流配置 * feat: 添加清空服务端所有非核心工作流功能 * fix：修复Bottle类的序列化和反序列化方法 * feat：增强材料缓存更新逻辑，支持处理返回数据中的详细信息 * Add debug log * feat(workstation): update bioyond config migration and coin cell material search logic - Migrate bioyond_cell config to JSON structure and remove global variable dependencies - Implement material search confirmation dialog auto-handling - Add documentation: 20260113_物料搜寻确认弹窗自动处理功能.md and 20260113_配置迁移修改总结.md * Refactor module paths for Bioyond devices in YAML configuration files - Updated the module path for BioyondDispensingStation in bioyond_dispensing_station.yaml to reflect the new directory structure. - Updated the module path for BioyondReactionStation and BioyondReactor in reaction_station_bioyond.yaml to align with the revised organization of the codebase. * fix: WareHouse 的不可哈希类型错误，优化父节点去重逻辑 * refactor: Move config from module to instance initialization * fix: 修正 reaction_station 目录名拼写错误 * feat: Integrate material search logic and cleanup deprecated files - Update coin_cell_assembly.py with material search dialog handling - Update YB_warehouses.py with latest warehouse configurations - Remove outdated documentation and test data files * Refactor: Use instance attributes for action names and workflow step IDs * refactor: Split tipbox storage into left and right warehouses * refactor: Merge tipbox storage left and right into single warehouse --------- Co-authored-by: ZiWei <131428629+ZiWei09@users.noreply.github.com> Co-authored-by: Andy6M <xieqiming1132@qq.com> fix: WareHouse 的不可哈希类型错误，优化父节点去重逻辑 fix parent_uuid fetch when bind_parent_id == node_name 物料更新也是用父节点进行报送 Add None conversion for tube rack etc. Add set_liquid example. Add create_resource and test_resource example. Add restart. Temp allow action message. Add no_update_feedback option. Create session_id by edge. bump version to 0.10.15 temp cancel update req
2026-02-04 05:15:10 +00:00 · 2026-01-08 15:26:31 +08:00
parent 8580b84167
commit 2a5ddd611d
106 changed files with 17805 additions and 25458 deletions
--- a/docs/user_guide/best_practice.md
+++ b/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
@@ -768,7 +791,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 +836,7 @@ Uni-Lab-OS 内置了常见设备，但您的实验室可能有特殊设备需要
 - 特殊的实验流程
 - 第三方设备集成

-#### 9.2 创建 Python 包
+#### 9.3 创建 Python 包

 为了方便开发和管理，建议为您的实验室创建独立的 Python 包。

@@ -814,7 +873,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 +904,7 @@ setup(
 )
 ```

-#### 9.4 开发安装
+#### 9.5 开发安装

 使用 `-e` 参数进行可编辑安装，这样代码修改后立即生效：

@@ -860,7 +919,7 @@ pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
 - 方便调试和测试
 - 支持版本控制（git）

-#### 9.5 编写设备驱动
+#### 9.6 编写设备驱动

 创建设备驱动文件：

@@ -1001,7 +1060,7 @@ class MyPump:
 - **返回 Dict**：所有动作方法返回字典类型
 - **文档字符串**：详细说明参数和功能

-#### 9.6 测试设备驱动
+#### 9.7 测试设备驱动

 创建简单的测试脚本：

--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -13,15 +13,26 @@
  - 开发者需要 Git 和基本的 Python 开发知识
  - 自定义 msgs 需要 GitHub 账号

+## 安装包选择
+
+Uni-Lab-OS 提供三个安装包版本，根据您的需求选择：
+
+| 安装包 | 适用场景 | 包含组件 | 磁盘占用 |
+|--------|----------|----------|----------|
+| **unilabos** | **推荐大多数用户**，生产部署 | 完整安装包，开箱即用 | ~2-3 GB |
+| **unilabos-env** | 开发者环境（可编辑安装） | 仅环境依赖，通过 pip 安装 unilabos | ~2 GB |
+| **unilabos-full** | 仿真可视化、完整功能体验 | unilabos + 完整 ROS2 桌面版 + Gazebo + MoveIt | ~8-10 GB |
+
 ## 安装方式选择

 根据您的使用场景，选择合适的安装方式：

-| 安装方式               | 适用人群             | 特点                           | 安装时间                     |
-| ---------------------- | -------------------- | ------------------------------ | ---------------------------- |
-| **方式一：一键安装**   | 实验室用户、快速体验 | 预打包环境，离线可用，无需配置 | 5-10 分钟 (网络良好的情况下) |
-| **方式二：手动安装**   | 标准用户、生产环境   | 灵活配置，版本可控             | 10-20 分钟                   |
-| **方式三：开发者安装** | 开发者、需要修改源码 | 可编辑模式，支持自定义 msgs    | 20-30 分钟                   |
+| 安装方式               | 适用人群             | 推荐安装包        | 特点                           | 安装时间                     |
+| ---------------------- | -------------------- | ----------------- | ------------------------------ | ---------------------------- |
+| **方式一：一键安装**   | 快速体验、演示       | 预打包环境        | 离线可用，无需配置             | 5-10 分钟 (网络良好的情况下) |
+| **方式二：手动安装**   | **大多数用户**       | `unilabos`        | 完整功能，开箱即用             | 10-20 分钟                   |
+| **方式三：开发者安装** | 开发者、需要修改源码 | `unilabos-env`    | 可编辑模式，支持自定义开发     | 20-30 分钟                   |
+| **仿真/可视化**        | 仿真测试、可视化调试 | `unilabos-full`   | 含 Gazebo、rviz2、MoveIt       | 30-60 分钟                   |

 ---

@@ -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
 ```

 ### 第三步：激活环境
@@ -203,58 +241,87 @@ cd Uni-Lab-OS
   cd Uni-Lab-OS
   ```

-### 第二步：安装基础环境
+### 第二步：安装开发环境（unilabos-env）

-**推荐方式**：先通过**方式一（一键安装）**或**方式二（手动安装）**完成基础环境的安装，这将包含所有必需的依赖项（ROS2、msgs 等）。
-
-#### 选项 A：通过一键安装（推荐）
-
-参考上文"方式一：一键安装"，完成基础环境的安装后，激活环境：
+**重要**：开发者请使用 `unilabos-env` 包，它专为开发者设计：
+- 包含 ROS2 核心组件和消息包（ros-humble-ros-core、std-msgs、geometry-msgs 等）
+- 包含 transforms3d、cv-bridge、tf2 等 conda 依赖
+- 包含 `uv` 工具，用于快速安装 pip 依赖
+- **不包含** pip 依赖和 unilabos 包（由 `pip install -e .` 和 `uv pip install` 安装）

 ```bash
+# 创建并激活环境
+mamba create -n unilab python=3.11.14
 conda activate unilab
+
+# 安装开发者环境包（ROS2 + conda 依赖 + uv）
+mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
 ```

-#### 选项 B：通过手动安装
+### 第三步：安装 pip 依赖和可编辑模式安装

-参考上文"方式二：手动安装"，创建并安装环境：
-
-```bash
-mamba create -n unilab python=3.11.11
-conda activate unilab
-mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
-```
-
-**说明**：这会安装包括 Python 3.11.11、ROS2 Humble、ros-humble-unilabos-msgs 和所有必需依赖
-
-### 第三步：切换到开发版本
-
-现在你已经有了一个完整可用的 Uni-Lab 环境，接下来将 unilabos 包切换为开发版本：
+克隆代码并安装依赖：

 ```bash
 # 确保环境已激活
 conda activate unilab

-# 卸载 pip 安装的 unilabos（保留所有 conda 依赖）
-pip uninstall unilabos -y
-
-# 克隆 dev 分支（如果还未克隆）
-cd /path/to/your/workspace
-git clone -b dev https://github.com/deepmodeling/Uni-Lab-OS.git
-# 或者如果已经克隆，切换到 dev 分支
+# 克隆仓库（如果还未克隆）
+git clone https://github.com/deepmodeling/Uni-Lab-OS.git
 cd Uni-Lab-OS
+
+# 切换到 dev 分支（可选）
 git checkout dev
 git pull
-
-# 以可编辑模式安装开发版 unilabos
-pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
 ```

-**参数说明**：
+**推荐：使用安装脚本**（自动检测中文环境，使用 uv 加速）：

- `-e`: editable mode（可编辑模式），代码修改立即生效，无需重新安装
- `-i`: 使用清华镜像源加速下载
- `pip uninstall unilabos`: 只卸载 pip 安装的 unilabos 包，不影响 conda 安装的其他依赖（如 ROS2、msgs 等）
+```bash
+# 自动检测中文环境，如果是中文系统则使用清华镜像
+python scripts/dev_install.py
+
+# 或者手动指定：
+python scripts/dev_install.py --china     # 强制使用清华镜像
+python scripts/dev_install.py --no-mirror # 强制使用 PyPI
+python scripts/dev_install.py --skip-deps # 跳过 pip 依赖安装
+python scripts/dev_install.py --use-pip   # 使用 pip 而非 uv
+```
+
+**手动安装**（如果脚本安装失败或速度太慢）：
+
+```bash
+# 1. 安装 unilabos（可编辑模式）
+pip install -e .
+
+# 2. 使用 uv 安装 pip 依赖（推荐，速度更快）
+uv pip install -r unilabos/utils/requirements.txt
+
+# 国内用户使用清华镜像：
+pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+uv pip install -r unilabos/utils/requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+```
+
+**注意**：
+- `uv` 已包含在 `unilabos-env` 中，无需单独安装
+- `unilabos/utils/requirements.txt` 包含运行 unilabos 所需的所有 pip 依赖
+- 部分特殊包（如 pylabrobot）会在运行时由 unilabos 自动检测并安装
+
+**为什么使用可编辑模式？**
+
+- `-e` (editable mode)：代码修改**立即生效**，无需重新安装
+- 适合开发调试：修改代码后直接运行测试
+- 与 `unilabos-env` 配合：环境依赖由 conda 管理，unilabos 代码由 pip 管理
+
+**验证安装**：
+
+```bash
+# 检查 unilabos 版本
+python -c "import unilabos; print(unilabos.__version__)"
+
+# 检查安装位置（应该指向你的代码目录）
+pip show unilabos | grep Location
+```

 ### 第四步：安装或自定义 ros-humble-unilabos-msgs（可选）

@@ -464,7 +531,45 @@ cd $CONDA_PREFIX/envs/unilab

 ### 问题 8: 环境很大，有办法减小吗？

-**解决方案**: 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用方式二手动安装，只安装需要的组件。
+**解决方案**: 
+
+1. **使用 `unilabos` 标准版**（推荐大多数用户）：
+   ```bash
+   mamba install uni-lab::unilabos -c robostack-staging -c conda-forge
+   ```
+   标准版包含完整功能，环境大小约 2-3GB（相比完整版的 8-10GB）。
+
+2. **使用 `unilabos-env` 开发者版**（最小化）：
+   ```bash
+   mamba install uni-lab::unilabos-env -c robostack-staging -c conda-forge
+   # 然后手动安装依赖
+   pip install -e .
+   uv pip install -r unilabos/utils/requirements.txt
+   ```
+   开发者版只包含环境依赖，体积最小约 2GB。
+
+3. **按需安装额外组件**：
+   如果后续需要特定功能，可以单独安装：
+   ```bash
+   # 需要 Jupyter
+   mamba install jupyter jupyros
+   
+   # 需要可视化
+   mamba install matplotlib opencv
+   
+   # 需要仿真（注意：这会安装大量依赖）
+   mamba install ros-humble-gazebo-ros
+   ```
+
+4. **预打包环境问题**：
+   预打包环境（方式一）包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。
+
+**包选择建议**：
+| 需求 | 推荐包 | 预估大小 |
+|------|--------|----------|
+| 日常使用/生产部署 | `unilabos` | ~2-3 GB |
+| 开发调试（可编辑模式） | `unilabos-env` | ~2 GB |
+| 仿真/可视化 | `unilabos-full` | ~8-10 GB |

 ### 问题 9: 如何更新到最新版本？

@@ -511,6 +616,7 @@ mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-f

 **提示**:

- 生产环境推荐使用方式二（手动安装）的稳定版本
- 开发和测试推荐使用方式三（开发者安装）
- 快速体验和演示推荐使用方式一（一键安装）
+- **大多数用户**推荐使用方式二（手动安装）的 `unilabos` 标准版
+- **开发者**推荐使用方式三（开发者安装），安装 `unilabos-env` 后使用 `uv pip install -r unilabos/utils/requirements.txt` 安装依赖
+- **仿真/可视化**推荐安装 `unilabos-full` 完整版
+- **快速体验和演示**推荐使用方式一（一键安装）