0.10.7 Update (#101)

* Cleanup registry to be easy-understanding (#76) * delete deprecated mock devices * rename categories * combine chromatographic devices * rename rviz simulation nodes * organic virtual devices * parse vessel_id * run registry completion before merge --------- Co-authored-by: Xuwznln <18435084+Xuwznln@users.noreply.github.com> * fix: workstation handlers and vessel_id parsing * fix: working dir error when input config path feat: report publish topic when error * modify default discovery_interval to 15s * feat: add trace log level * feat: 添加ChinWe设备控制类，支持串口通信和电机控制功能 (#79) * fix: drop_tips not using auto resource select * fix: discard_tips error * fix: discard_tips * fix: prcxi_res * add: prcxi res fix: startup slow * feat: workstation example * fix pumps and liquid_handler handle * feat: 优化protocol node节点运行日志 * fix all protocol_compilers and remove deprecated devices * feat: 新增use_remote_resource参数 * fix and remove redundant info * bugfixes on organic protocols * fix filter protocol * fix protocol node * 临时兼容错误的driver写法 * fix: prcxi import error * use call_async in all service to avoid deadlock * fix: figure_resource * Update recipe.yaml * add workstation template and battery example * feat: add sk & ak * update workstation base * Create workstation_architecture.md * refactor: workstation_base 重构为仅含业务逻辑，通信和子设备管理交给 ProtocolNode * refactor: ProtocolNode→WorkstationNode * Add:msgs.action (#83) * update: Workstation dev 将版本号从 0.10.3 更新为 0.10.4 (#84) * Add:msgs.action * update: 将版本号从 0.10.3 更新为 0.10.4 * simplify resource system * uncompleted refactor * example for use WorkstationBase * feat: websocket * feat: websocket test * feat: workstation example * feat: action status * fix: station自己的方法注册错误 * fix: 还原protocol node处理方法 * fix: build * fix: missing job_id key * ws test version 1 * ws test version 2 * ws protocol * 增加物料关系上传日志 * 增加物料关系上传日志 * 修正物料关系上传 * 修复工站的tracker实例追踪失效问题 * 增加handle检测，增加material edge关系上传 * 修复event loop错误 * 修复edge上报错误 * 修复async错误 * 更新schema的title字段 * 主机节点信息等支持自动刷新 * 注册表编辑器 * 修复status密集发送时，消息出错 * 增加addr参数 * fix: addr param * fix: addr param * 取消labid 和强制config输入 * Add action definitions for LiquidHandlerSetGroup and LiquidHandlerTransferGroup - Created LiquidHandlerSetGroup.action with fields for group name, wells, and volumes. - Created LiquidHandlerTransferGroup.action with fields for source and target group names and unit volume. - Both actions include response fields for return information and success status. * Add LiquidHandlerSetGroup and LiquidHandlerTransferGroup actions to CMakeLists * Add set_group and transfer_group methods to PRCXI9300Handler and update liquid_handler.yaml * result_info改为字典类型 * 新增uat的地址替换 * runze multiple pump support (cherry picked from commit 49354fcf39) * remove runze multiple software obtainer (cherry picked from commit 8bcc92a394) * support multiple backbone (cherry picked from commit 4771ff2347) * Update runze pump format * Correct runze multiple backbone * Update runze_multiple_backbone * Correct runze pump multiple receive method. * Correct runze pump multiple receive method. * 对于PRCXI9320的transfer_group，一对多和多对多 * 移除MQTT，更新launch文档，提供注册表示例文件，更新到0.10.5 * fix import error * fix dupe upload registry * refactor ws client * add server timeout * Fix: run-column with correct vessel id (#86) * fix run_column * Update run_column_protocol.py (cherry picked from commit e5aa4d940a) * resource_update use resource_add * 新增版位推荐功能 * 重新规定了版位推荐的入参 * update registry with nested obj * fix protocol node log_message, added create_resource return value * fix protocol node log_message, added create_resource return value * try fix add protocol * fix resource_add * 修复移液站错误的aspirate注册表 * Feature/xprbalance-zhida (#80) * feat(devices): add Zhida GC/MS pretreatment automation workstation * feat(devices): add mettler_toledo xpr balance * balance * 重新补全zhida注册表 * PRCXI9320 json * PRCXI9320 json * PRCXI9320 json * fix resource download * remove class for resource * bump version to 0.10.6 * 更新所有注册表 * 修复protocolnode的兼容性 * 修复protocolnode的兼容性 * Update install md * Add Defaultlayout * 更新物料接口 * fix dict to tree/nested-dict converter * coin_cell_station draft * refactor: rename "station_resource" to "deck" * add standardized BIOYOND resources: bottle_carrier, bottle * refactor and add BIOYOND resources tests * add BIOYOND deck assignment and pass all tests * fix: update resource with correct structure; remove deprecated liquid_handler set_group action * feat: 将新威电池测试系统驱动与配置文件并入 workstation_dev_YB2 (#92) * feat: 新威电池测试系统驱动与注册文件 * feat: bring neware driver & battery.json into workstation_dev_YB2 * add bioyond studio draft * bioyond station with communication init and resource sync * fix bioyond station and registry * fix: update resource with correct structure; remove deprecated liquid_handler set_group action * frontend_docs * create/update resources with POST/PUT for big amount/ small amount data * create/update resources with POST/PUT for big amount/ small amount data * refactor: add itemized_carrier instead of carrier consists of ResourceHolder * create warehouse by factory func * update bioyond launch json * add child_size for itemized_carrier * fix bioyond resource io * Workstation templates: Resources and its CRUD, and workstation tasks (#95) * coin_cell_station draft * refactor: rename "station_resource" to "deck" * add standardized BIOYOND resources: bottle_carrier, bottle * refactor and add BIOYOND resources tests * add BIOYOND deck assignment and pass all tests * fix: update resource with correct structure; remove deprecated liquid_handler set_group action * feat: 将新威电池测试系统驱动与配置文件并入 workstation_dev_YB2 (#92) * feat: 新威电池测试系统驱动与注册文件 * feat: bring neware driver & battery.json into workstation_dev_YB2 * add bioyond studio draft * bioyond station with communication init and resource sync * fix bioyond station and registry * create/update resources with POST/PUT for big amount/ small amount data * refactor: add itemized_carrier instead of carrier consists of ResourceHolder * create warehouse by factory func * update bioyond launch json * add child_size for itemized_carrier * fix bioyond resource io --------- Co-authored-by: h840473807 <47357934+h840473807@users.noreply.github.com> Co-authored-by: Xie Qiming <97236197+Andy6M@users.noreply.github.com> * 更新物料接口 * Workstation dev yb2 (#100) * Refactor and extend reaction station action messages * Refactor dispensing station tasks to enhance parameter clarity and add batch processing capabilities - Updated `create_90_10_vial_feeding_task` to include detailed parameters for 90%/10% vial feeding, improving clarity and usability. - Introduced `create_batch_90_10_vial_feeding_task` for batch processing of 90%/10% vial feeding tasks with JSON formatted input. - Added `create_batch_diamine_solution_task` for batch preparation of diamine solution, also utilizing JSON formatted input. - Refined `create_diamine_solution_task` to include additional parameters for better task configuration. - Enhanced schema descriptions and default values for improved user guidance. * 修复to_plr_resources * add update remove * 支持选择器注册表自动生成支持转运物料 * 修复资源添加 * 修复transfer_resource_to_another生成 * 更新transfer_resource_to_another参数，支持spot入参 * 新增test_resource动作 * fix host_node error * fix host_node test_resource error * fix host_node test_resource error * 过滤本地动作 * 移动内部action以兼容host node * 修复同步任务报错不显示的bug * feat: 允许返回非本节点物料，后面可以通过decoration进行区分，就不进行warning了 * update todo * modify bioyond/plr converter, bioyond resource registry, and tests * pass the tests * update todo * add conda-pack-build.yml * add auto install script for conda-pack-build.yml (cherry picked from commit 172599adcf) * update conda-pack-build.yml * update conda-pack-build.yml * update conda-pack-build.yml * update conda-pack-build.yml * update conda-pack-build.yml * Add version in __init__.py Update conda-pack-build.yml Add create_zip_archive.py * Update conda-pack-build.yml * Update conda-pack-build.yml (with mamba) * Update conda-pack-build.yml * Fix FileNotFoundError * Try fix 'charmap' codec can't encode characters in position 16-23: character maps to <undefined> * Fix unilabos msgs search error * Fix environment_check.py * Update recipe.yaml * Update registry. Update uuid loop figure method. Update install docs. * Fix nested conda pack * Fix one-key installation path error * Bump version to 0.10.7 * Workshop bj (#99) * Add LaiYu Liquid device integration and tests Introduce LaiYu Liquid device implementation, including backend, controllers, drivers, configuration, and resource files. Add hardware connection, tip pickup, and simplified test scripts, as well as experiment and registry configuration for LaiYu Liquid. Documentation and .gitignore for the device are also included. * feat(LaiYu_Liquid): 重构设备模块结构并添加硬件文档 refactor: 重新组织LaiYu_Liquid模块目录结构 docs: 添加SOPA移液器和步进电机控制指令文档 fix: 修正设备配置中的最大体积默认值 test: 新增工作台配置测试用例 chore: 删除过时的测试脚本和配置文件 * add * 重构: 将 LaiYu_Liquid.py 重命名为 laiyu_liquid_main.py 并更新所有导入引用 - 使用 git mv 将 LaiYu_Liquid.py 重命名为 laiyu_liquid_main.py - 更新所有相关文件中的导入引用 - 保持代码功能不变，仅改善命名一致性 - 测试确认所有导入正常工作 * 修复: 在 core/__init__.py 中添加 LaiYuLiquidBackend 导出 - 添加 LaiYuLiquidBackend 到导入列表 - 添加 LaiYuLiquidBackend 到 __all__ 导出列表 - 确保所有主要类都可以正确导入 * 修复大小写文件夹名字 * 电池装配工站二次开发教程（带目录）上传至dev (#94) * 电池装配工站二次开发教程 * Update intro.md * 物料教程 * 更新物料教程，json格式注释 * Update prcxi driver & fix transfer_liquid mix_times (#90) * Update prcxi driver & fix transfer_liquid mix_times * fix: correct mix_times type * Update liquid_handler registry * test: prcxi.py * Update registry from pr * fix ony-key script not exist * clean files --------- Co-authored-by: Junhan Chang <changjh@dp.tech> Co-authored-by: ZiWei <131428629+ZiWei09@users.noreply.github.com> Co-authored-by: Guangxin Zhang <guangxin.zhang.bio@gmail.com> Co-authored-by: Xie Qiming <97236197+Andy6M@users.noreply.github.com> Co-authored-by: h840473807 <47357934+h840473807@users.noreply.github.com> Co-authored-by: LccLink <1951855008@qq.com> Co-authored-by: lixinyu1011 <61094742+lixinyu1011@users.noreply.github.com> Co-authored-by: shiyubo0410 <shiyubo@dp.tech>
2025-12-17 04:51:10 +00:00 · 2025-10-12 23:34:26 +08:00
parent 172599adcf
commit 9aeffebde1
229 changed files with 136969 additions and 17429 deletions
--- a/docs/user_guide/configuration.md
+++ b/docs/user_guide/configuration.md
@@ -1,82 +1,75 @@
 # Uni-Lab 配置指南

-Uni-Lab支持通过Python配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的Uni-Lab环境。
+Uni-Lab 支持通过 Python 配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的 Uni-Lab 环境。

 ## 配置文件格式

-Uni-Lab支持Python格式的配置文件，它比YAML或JSON提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
+Uni-Lab 支持 Python 格式的配置文件，它比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。

-### 基本配置示例
+### 默认配置示例

-一个典型的配置文件包含以下部分：
+首次使用时，系统会自动创建一个基础配置文件 `local_config.py`：
+
+```python
+# unilabos的配置文件
+
+class BasicConfig:
+    ak = ""  # 实验室网页给您提供的ak代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --ak 传入，优先按照传入参数解析
+    sk = ""  # 实验室网页给您提供的sk代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --sk 传入，优先按照传入参数解析
+
+
+# WebSocket配置，一般无需调整
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）
+```
+您可以进入实验室，点击左下角的头像在实验室详情中获取所在实验室的ak sk
+![copy_aksk.gif](image/copy_aksk.gif)
+
+### 完整配置示例
+
+您可以根据需要添加更多配置选项：

 ```python
 #!/usr/bin/env python
 # coding=utf-8
 """Uni-Lab 配置文件"""

-from dataclasses import dataclass
+# 基础配置
+class BasicConfig:
+    ak = "your_access_key"  # 实验室访问密钥
+    sk = "your_secret_key"  # 实验室私钥
+    working_dir = ""  # 工作目录（通常自动设置）
+    config_path = ""  # 配置文件路径（自动设置）
+    is_host_mode = True  # 是否为主站模式
+    slave_no_host = False  # 从站模式下是否跳过等待主机服务
+    upload_registry = False  # 是否上传注册表
+    machine_name = "undefined"  # 机器名称（自动获取）
+    vis_2d_enable = False  # 是否启用2D可视化
+    enable_resource_load = True  # 是否启用资源加载
+    communication_protocol = "websocket"  # 通信协议

-# 配置类定义
+# WebSocket配置
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）

-class MQConfig:
-    """MQTT 配置类"""
-    lab_id: str = "YOUR_LAB_ID"
-    # 更多配置...
+# OSS上传配置
+class OSSUploadConfig:
+    api_host = ""  # API主机地址
+    authorization = ""  # 授权信息
+    init_endpoint = ""  # 初始化端点
+    complete_endpoint = ""  # 完成端点
+    max_retries = 3  # 最大重试次数

-# 其他配置类...
-```
-
-## 配置选项说明
-
-### MQTT配置 (MQConfig)
-
-MQTT配置用于连接消息队列服务，是Uni-Lab与云端通信的主要方式。
-
-```python
-
-class MQConfig:
-    """MQTT 配置类"""
-    lab_id: str = "7AAEDBEA"  # 实验室唯一标识
-    instance_id: str = "mqtt-cn-instance"
-    access_key: str = "your-access-key"
-    secret_key: str = "your-secret-key"
-    group_id: str = "GID_labs"
-    broker_url: str = "mqtt-cn-instance.mqtt.aliyuncs.com"
-    port: int = 8883
-    
-    # 可以直接提供证书文件路径
-    ca_file: str = "/path/to/ca.pem"  # 相对config.py所在目录的路径
-    cert_file: str = "/path/to/cert.pem"  # 相对config.py所在目录的路径
-    key_file: str = "/path/to/key.pem"  # 相对config.py所在目录的路径
-    
-    # 或者直接提供证书内容
-    ca_content: str = ""
-    cert_content: str = ""
-    key_content: str = ""
-```
-
-#### 证书配置
-
-MQTT连接支持两种方式配置证书：
-
-1. **文件路径方式**（推荐）：指定证书文件的路径，系统会自动读取文件内容
-2. **直接内容方式**：直接在配置中提供证书内容
-
-推荐使用文件路径方式，便于证书的更新和管理。
-
-### HTTP客户端配置 (HTTPConfig)
-
-即将开放 Uni-Lab 云端实验室。
-
-### ROS模块配置 (ROSConfig)
-
-配置ROS消息转换器需要加载的模块：
-
-```python
+# HTTP配置
+class HTTPConfig:
+    remote_addr = "http://127.0.0.1:48197/api/v1"  # 远程地址

+# ROS配置
 class ROSConfig:
-    """ROS模块配置"""
    modules = [
        "std_msgs.msg",
        "geometry_msgs.msg",
@@ -85,25 +78,365 @@ class ROSConfig:
        "nav2_msgs.action",
        "unilabos_msgs.msg",
        "unilabos_msgs.action",
+    ]  # 需要加载的ROS模块
+```
+
+## 命令行参数覆盖配置
+
+Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。命令行参数的优先级高于配置文件。
+
+### 支持命令行覆盖的配置项
+
+以下配置项可以通过命令行参数进行覆盖：
+
+| 配置类        | 配置字段          | 命令行参数          | 说明                             |
+| ------------- | ----------------- | ------------------- | -------------------------------- |
+| `BasicConfig` | `ak`              | `--ak`              | 实验室访问密钥                   |
+| `BasicConfig` | `sk`              | `--sk`              | 实验室私钥                       |
+| `BasicConfig` | `working_dir`     | `--working_dir`     | 工作目录路径                     |
+| `BasicConfig` | `is_host_mode`    | `--is_slave`        | 主站模式（参数为从站模式，取反） |
+| `BasicConfig` | `slave_no_host`   | `--slave_no_host`   | 从站模式下跳过等待主机服务       |
+| `BasicConfig` | `upload_registry` | `--upload_registry` | 启动时上传注册表信息             |
+| `BasicConfig` | `vis_2d_enable`   | `--2d_vis`          | 启用 2D 可视化                   |
+| `HTTPConfig`  | `remote_addr`     | `--addr`            | 远程服务地址                     |
+
+### 特殊命令行参数
+
+除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
+
+| 参数                | 说明                                 |
+| ------------------- | ------------------------------------ |
+| `--config`          | 指定配置文件路径                     |
+| `--port`            | Web 服务端口（不影响配置文件）       |
+| `--disable_browser` | 禁用自动打开浏览器（不影响配置文件） |
+| `--visual`          | 可视化工具选择（不影响配置文件）     |
+| `--skip_env_check`  | 跳过环境检查（不影响配置文件）       |
+
+### 配置优先级
+
+配置项的生效优先级从高到低为：
+
+1. **命令行参数**：最高优先级
+2. **环境变量**：中等优先级
+3. **配置文件**：基础优先级
+
+### 使用示例
+
+```bash
+# 通过命令行覆盖认证信息
+unilab --ak "new_access_key" --sk "new_secret_key"
+
+# 覆盖服务器地址
+unilab --addr "https://custom.server.com/api/v1"
+
+# 启用从站模式并跳过等待主机
+unilab --is_slave --slave_no_host
+
+# 启用上传注册表和2D可视化
+unilab --upload_registry --2d_vis
+
+# 组合使用多个覆盖参数
+unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis
+```
+
+### 预设环境地址
+
+`--addr` 参数支持以下预设值，会自动转换为对应的完整 URL：
+
+- `test` → `https://uni-lab.test.bohrium.com/api/v1`
+- `uat` → `https://uni-lab.uat.bohrium.com/api/v1`
+- `local` → `http://127.0.0.1:48197/api/v1`
+- 其他值 → 直接使用作为完整 URL
+
+## 配置选项详解
+
+### 基础配置 (BasicConfig)
+
+基础配置包含了系统运行的核心参数：
+
+| 参数                     | 类型 | 默认值        | 说明                                       |
+| ------------------------ | ---- | ------------- | ------------------------------------------ |
+| `ak`                     | str  | `""`          | 实验室访问密钥（必需）                     |
+| `sk`                     | str  | `""`          | 实验室私钥（必需）                         |
+| `working_dir`            | str  | `""`          | 工作目录，通常自动设置                     |
+| `is_host_mode`           | bool | `True`        | 是否为主站模式                             |
+| `slave_no_host`          | bool | `False`       | 从站模式下是否跳过等待主机服务             |
+| `upload_registry`        | bool | `False`       | 启动时是否上传注册表信息                   |
+| `machine_name`           | str  | `"undefined"` | 机器名称，自动从 hostname 获取（不可配置） |
+| `vis_2d_enable`          | bool | `False`       | 是否启用 2D 可视化                         |
+| `communication_protocol` | str  | `"websocket"` | 通信协议，固定为 websocket                 |
+
+#### 认证配置
+
+`ak` 和 `sk` 是必需的认证参数：
+
+1. **获取方式**：在 [Uni-Lab 官网](https://uni-lab.bohrium.com) 注册实验室后获得
+2. **配置方式**：
+   - **命令行参数**：`--ak "your_key" --sk "your_secret"`（最高优先级）
+   - **配置文件**：在 `BasicConfig` 类中设置
+   - **环境变量**：`UNILABOS_BASICCONFIG_AK` 和 `UNILABOS_BASICCONFIG_SK`
+3. **优先级顺序**：命令行参数 > 环境变量 > 配置文件
+4. **安全注意**：请妥善保管您的密钥信息
+
+**推荐做法**：
+
+- 开发环境：使用配置文件
+- 生产环境：使用环境变量或命令行参数
+- 临时测试：使用命令行参数
+
+### WebSocket 配置 (WSConfig)
+
+WebSocket 是 Uni-Lab 的主要通信方式：
+
+| 参数                     | 类型 | 默认值 | 说明               |
+| ------------------------ | ---- | ------ | ------------------ |
+| `reconnect_interval`     | int  | `5`    | 断线重连间隔（秒） |
+| `max_reconnect_attempts` | int  | `999`  | 最大重连次数       |
+| `ping_interval`          | int  | `30`   | 心跳检测间隔（秒） |
+
+### HTTP 配置 (HTTPConfig)
+
+HTTP 客户端配置用于与云端服务通信：
+
+| 参数          | 类型 | 默认值                            | 说明         |
+| ------------- | ---- | --------------------------------- | ------------ |
+| `remote_addr` | str  | `"http://127.0.0.1:48197/api/v1"` | 远程服务地址 |
+
+**预设环境地址**：
+
+- 生产环境：`https://uni-lab.bohrium.com/api/v1`
+- 测试环境：`https://uni-lab.test.bohrium.com/api/v1`
+- UAT 环境：`https://uni-lab.uat.bohrium.com/api/v1`
+- 本地环境：`http://127.0.0.1:48197/api/v1`
+
+### ROS 配置 (ROSConfig)
+
+配置 ROS 消息转换器需要加载的模块：
+
+```python
+class ROSConfig:
+    modules = [
+        "std_msgs.msg",           # 标准消息类型
+        "geometry_msgs.msg",      # 几何消息类型
+        "control_msgs.msg",       # 控制消息类型
+        "control_msgs.action",    # 控制动作类型
+        "nav2_msgs.action",       # 导航动作类型
+        "unilabos_msgs.msg",      # UniLab 自定义消息类型
+        "unilabos_msgs.action",   # UniLab 自定义动作类型
    ]
 ```

-您可以根据需要添加其他ROS模块。
+您可以根据实际使用的设备和功能添加其他 ROS 模块。

-### 其他配置选项
+### OSS 上传配置 (OSSUploadConfig)

- **OSSUploadConfig**: 对象存储上传配置
+对象存储服务配置，用于文件上传功能：

-## 如何使用配置文件
+| 参数                | 类型 | 默认值 | 说明                 |
+| ------------------- | ---- | ------ | -------------------- |
+| `api_host`          | str  | `""`   | OSS API 主机地址     |
+| `authorization`     | str  | `""`   | 授权认证信息         |
+| `init_endpoint`     | str  | `""`   | 上传初始化端点       |
+| `complete_endpoint` | str  | `""`   | 上传完成端点         |
+| `max_retries`       | int  | `3`    | 上传失败最大重试次数 |

-启动Uni-Lab时通过`--config`参数指定配置文件路径：
+## 环境变量支持
+
+Uni-Lab 支持通过环境变量覆盖配置文件中的设置。环境变量格式为：
+
+```
+UNILABOS_{配置类名}_{字段名}
+```
+
+### 环境变量示例

 ```bash
-unilab --config path/to/your/config.py
+# 设置基础配置
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
+
+# 设置WebSocket配置
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
+export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
+
+# 设置HTTP配置
+export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.bohrium.com/api/v1"
 ```

-如果您不涉及多环境开发，可以在unilabos的安装路径中手动添加local_config.py的文件
+### 环境变量类型转换

-# 启动Uni-Lab
-python -m unilabos.app.main --config path/to/your/config.py
+- **布尔值**：`"true"`, `"1"`, `"yes"` → `True`；其他 → `False`
+- **整数**：自动转换为 `int` 类型
+- **浮点数**：自动转换为 `float` 类型
+- **字符串**：保持原值
+
+## 配置文件使用方法
+
+### 1. 指定配置文件启动
+
+```bash
+# 使用指定配置文件启动
+unilab --config /path/to/your/config.py
 ```
+
+### 2. 使用默认配置文件
+
+如果不指定配置文件，系统会按以下顺序查找：
+
+1. 环境变量 `UNILABOS_BASICCONFIG_CONFIG_PATH` 指定的路径
+2. 工作目录下的 `local_config.py`
+3. 首次使用时会引导创建配置文件
+
+### 3. 配置文件验证
+
+系统启动时会自动验证配置文件：
+
+- **语法检查**：确保 Python 语法正确
+- **类型检查**：验证配置项类型是否匹配
+- **必需项检查**：确保 `ak` 和 `sk` 已配置
+
+## 最佳实践
+
+### 1. 安全配置
+
+- 不要将包含密钥的配置文件提交到版本控制系统
+- 使用环境变量或命令行参数在生产环境中配置敏感信息
+- 定期更换访问密钥
+- **推荐配置方式**：
+
+  ```bash
+  # 生产环境 - 使用环境变量
+  export UNILABOS_BASICCONFIG_AK="your_access_key"
+  export UNILABOS_BASICCONFIG_SK="your_secret_key"
+  unilab
+
+  # 或使用命令行参数
+  unilab --ak "your_access_key" --sk "your_secret_key"
+  ```
+
+### 2. 多环境配置
+
+为不同环境创建不同的配置文件并结合命令行参数：
+
+```
+configs/
+├── local_config.py      # 本地开发
+├── test_config.py       # 测试环境
+├── prod_config.py       # 生产环境
+└── example_config.py    # 示例配置
+```
+
+**环境切换示例**：
+
+```bash
+# 本地开发环境
+unilab --config configs/local_config.py --addr local
+
+# 测试环境
+unilab --config configs/test_config.py --addr test --upload_registry
+
+# 生产环境
+unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK"
+```
+
+### 3. 配置管理
+
+- 保持配置文件简洁，只包含需要修改的配置项
+- 为配置项添加注释说明其作用
+- 定期检查和更新配置文件
+- **命令行参数优先使用场景**：
+  - 临时测试不同配置
+  - CI/CD 流水线中的动态配置
+  - 不同环境间快速切换
+  - 敏感信息的安全传递
+
+### 4. 灵活配置策略
+
+**基础配置文件 + 命令行覆盖**的推荐方式：
+
+```python
+# base_config.py - 基础配置
+class BasicConfig:
+    # 非敏感配置写在文件中
+    is_host_mode = True
+    upload_registry = False
+    vis_2d_enable = False
+
+class WSConfig:
+    reconnect_interval = 5
+    max_reconnect_attempts = 999
+    ping_interval = 30
+```
+
+```bash
+# 启动时通过命令行覆盖关键参数
+unilab --config base_config.py \
+       --ak "$AK" \
+       --sk "$SK" \
+       --addr "test" \
+       --upload_registry \
+       --2d_vis
+```
+
+## 故障排除
+
+### 1. 配置文件加载失败
+
+**错误信息**：`[ENV] 配置文件 xxx 不存在`
+
+**解决方法**：
+
+- 确认配置文件路径正确
+- 检查文件权限是否可读
+- 确保配置文件是 `.py` 格式
+
+### 2. 语法错误
+
+**错误信息**：`[ENV] 加载配置文件 xxx 失败`
+
+**解决方法**：
+
+- 检查 Python 语法是否正确
+- 确认类名和字段名拼写正确
+- 验证缩进是否正确（使用空格而非制表符）
+
+### 3. 认证失败
+
+**错误信息**：`后续运行必须拥有一个实验室`
+
+**解决方法**：
+
+- 确认 `ak` 和 `sk` 已正确配置
+- 检查密钥是否有效
+- 确认网络连接正常
+
+### 4. 环境变量不生效
+
+**解决方法**：
+
+- 确认环境变量名格式正确（`UNILABOS_CLASS_FIELD`）
+- 检查环境变量是否已正确设置
+- 重启系统或重新加载环境变量
+
+### 5. 命令行参数不生效
+
+**错误现象**：设置了命令行参数但配置没有生效
+
+**解决方法**：
+
+- 确认参数名拼写正确（如 `--ak` 而不是 `--access_key`）
+- 检查参数格式是否正确（布尔参数如 `--is_slave` 不需要值）
+- 确认参数位置正确（所有参数都应在 `unilab` 之后）
+- 查看启动日志确认参数是否被正确解析
+
+### 6. 配置优先级混淆
+
+**错误现象**：不确定哪个配置生效
+
+**解决方法**：
+
+- 记住优先级：命令行参数 > 环境变量 > 配置文件
+- 使用 `--ak` 和 `--sk` 参数时会看到提示信息
+- 检查启动日志中的配置加载信息
+- 临时移除低优先级配置来测试高优先级配置是否生效
--- a/docs/user_guide/image/copy_aksk.gif
+++ b/docs/user_guide/image/copy_aksk.gif
--- a/docs/user_guide/image/creatworkfollow.gif
+++ b/docs/user_guide/image/creatworkfollow.gif
--- a/docs/user_guide/image/links.png
+++ b/docs/user_guide/image/links.png
--- a/docs/user_guide/image/linksandrun.png
+++ b/docs/user_guide/image/linksandrun.png
--- a/docs/user_guide/image/material.png
+++ b/docs/user_guide/image/material.png
--- a/docs/user_guide/image/new.png
+++ b/docs/user_guide/image/new.png
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -1,24 +1,43 @@
 # **Uni-Lab 安装**

-请先 `git clone` 本仓库，随后按照以下步骤安装项目：
+## 快速开始

-`Uni-Lab` 建议您采用 `mamba` 管理环境。若需从头建立 `Uni-Lab` 的运行依赖环境，请执行
+1. **配置 Conda 环境**
+
+Uni-Lab-OS 建议使用 `mamba` 管理环境。创建新的环境：

 ```shell
-mamba env create -f unilabos-<YOUR_OS>.yaml
-mamba activate unilab
+mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```

-其中 `YOUR_OS` 是您的操作系统，可选值 `win64`, `linux-64`, `osx-64`, `osx-arm64`
-
-若需将依赖安装进当前环境，请执行
+2. **安装开发版 Uni-Lab-OS**

 ```shell
-conda env update --file unilabos-<YOUR_OS>.yml
+# 配置好conda环境后，克隆仓库
+git clone https://github.com/dptech-corp/Uni-Lab-OS.git -b dev
+cd Uni-Lab-OS
+
+# 安装 Uni-Lab-OS
+pip install -e .
 ```

-随后，可在本仓库安装 `unilabos` 的开发版：
+3. **安装开发版 ros-humble-unilabos-msgs**

+**卸载老版本：**
 ```shell
-pip install .
+conda activate unilab
+conda remove --force ros-humble-unilabos-msgs
 ```
+有时相同的安装包版本会由于dev构建得到的md5不一样，触发安全检查，可输入 `config set safety_checks disabled` 来关闭安全检查。
+
+**安装新版本：**
+
+访问 https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/multi-platform-build.yml 选择最新的构建，下载对应平台的压缩包（仅解压一次，得到.conda文件）使用如下指令：
+```shell
+conda activate base
+conda install ros-humble-unilabos-msgs-<version>-<platform>.conda --offline -n <环境名>
+```
+
+4. **启动 Uni-Lab 系统**
+
+请参见{doc}`启动样例 <../boot_examples/index>`或{doc}`启动指南 <launch>`了解详细的启动方法。
--- a/docs/user_guide/launch.md
+++ b/docs/user_guide/launch.md
@@ -1,4 +1,4 @@
-# Uni-Lab 启动
+# Uni-Lab 启动指南

 安装完毕后，可以通过 `unilab` 命令行启动：

@@ -8,70 +8,315 @@ Start Uni-Lab Edge server.
 options:
  -h, --help            show this help message and exit
  -g GRAPH, --graph GRAPH
-                        Physical setup graph.
-  -d DEVICES, --devices DEVICES
-                        Devices config file.
-  -r RESOURCES, --resources RESOURCES
-                        Resources config file.
+                        Physical setup graph file path.
  -c CONTROLLERS, --controllers CONTROLLERS
-                        Controllers config file.
+                        Controllers config file path.
  --registry_path REGISTRY_PATH
-                        Path to the registry
+                        Path to the registry directory
+  --working_dir WORKING_DIR
+                        Path to the working directory
  --backend {ros,simple,automancer}
                        Choose the backend to run with: 'ros', 'simple', or 'automancer'.
  --app_bridges APP_BRIDGES [APP_BRIDGES ...]
-                        Bridges to connect to. Now support 'mqtt' and 'fastapi'.
-  --without_host        Run the backend as slave (without host).
-  --config CONFIG       Configuration file path for system settings
+                        Bridges to connect to. Now support 'websocket' and 'fastapi'.
+  --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
+  --2d_vis              Enable 2D visualization when starting pylabrobot instance
+  --visual {rviz,web,disable}
+                        Choose visualization tool: rviz, web, or disable
+  --ak AK               Access key for laboratory requests
+  --sk SK               Secret key for laboratory requests
+  --addr ADDR           Laboratory backend address
+  --skip_env_check      Skip environment dependency check on startup
+  --complete_registry   Complete registry information
 ```

+## 启动流程详解
+
+Uni-Lab 的启动过程分为以下几个阶段：
+
+### 1. 参数解析阶段
+
+- 解析命令行参数
+- 处理参数格式转换（支持 dash 和 underscore 格式）
+
+### 2. 环境检查阶段 (可选)
+
+- 默认进行环境依赖检查并自动安装必需包
+- 使用 `--skip_env_check` 可跳过此步骤
+
+### 3. 配置文件处理阶段
+
+您可以直接跟随 unilabos 的提示进行，无需查阅本节
+
+- **工作目录设置**：
+
+  - 如果当前目录以 `unilabos_data` 结尾，则使用当前目录
+  - 否则使用 `当前目录/unilabos_data` 作为工作目录
+  - 可通过 `--working_dir` 指定自定义工作目录
+
+- **配置文件查找顺序**：
+  1. 使用 `--config` 参数指定的配置文件
+  2. 在工作目录中查找 `local_config.py`
+  3. 首次使用时会引导创建配置文件
+
+### 4. 服务器地址配置
+
+支持多种后端环境：
+
+- `--addr test`：测试环境 (`https://uni-lab.test.bohrium.com/api/v1`)
+- `--addr uat`：UAT 环境 (`https://uni-lab.uat.bohrium.com/api/v1`)
+- `--addr local`：本地环境 (`http://127.0.0.1:48197/api/v1`)
+- 自定义地址：直接指定完整 URL
+
+### 5. 认证配置
+
+- **必需参数**：`--ak` 和 `--sk` 必须同时提供
+- 命令行参数优先于配置文件中的设置
+- 未提供认证信息会导致启动失败并提示注册实验室
+
+### 6. 设备图谱加载
+
+支持两种方式：
+
+- **本地文件**：使用 `-g` 指定图谱文件（支持 JSON 和 GraphML 格式）
+- **远程资源**：使用 `--use_remote_resource` 从云端获取
+
+### 7. 注册表构建
+
+- 构建设备和资源注册表
+- 支持自定义注册表路径 (`--registry_path`)
+- 可选择补全注册表信息 (`--complete_registry`)
+
+### 8. 设备验证和注册
+
+- 验证设备连接和端点配置
+- 自动注册设备到云端服务
+
+### 9. 通信桥接配置
+
+- **WebSocket**：实时通信和任务下发
+- **FastAPI**：HTTP API 服务和物料更新
+
+### 10. 可视化和服务启动
+
+- 可选启动可视化工具 (`--visual`)
+- 启动 Web 信息服务 (默认端口 8002)
+- 启动后端通信服务
+
 ## 使用配置文件

-Uni-Lab支持使用Python格式的配置文件进行系统设置。通过 `--config` 参数指定配置文件路径：
+Uni-Lab 支持使用 Python 格式的配置文件进行系统设置。通过 `--config` 参数指定配置文件路径：

 ```bash
 # 使用配置文件启动
 unilab --config path/to/your/config.py
 ```

-配置文件包含MQTT、HTTP、ROS等系统设置。有关配置文件的详细信息，请参阅[配置指南](configuration.md)。
+配置文件包含实验室和 WebSocket 连接等设置。有关配置文件的详细信息，请参阅[配置指南](configuration.md)。

 ## 初始化信息来源

-启动 Uni-Lab 时，可以选用两种方式之一配置实验室设备、耗材、通信、控制逻辑：
+启动 Uni-Lab 时，可以选用两种方式之一配置实验室设备：

 ### 1. 组态&拓扑图

-使用 `-g` 时，组态&拓扑图应包含实验室所有信息，详见{ref}`graph`。目前支持 graphml 和 node-link json 两种格式。格式可参照 `tests/experiments` 下的启动文件。
+使用 `-g` 时，组态&拓扑图应包含实验室所有信息，详见{ref}`graph`。目前支持 GraphML 和 node-link JSON 两种格式。格式可参照 `tests/experiments` 下的启动文件。

-### 2. 分别指定设备、耗材、控制逻辑
+### 2. 分别指定控制逻辑

-分别使用 `-d, -r, -c` 依次传入设备组态配置、耗材列表、控制逻辑。
+使用 `-c` 传入控制逻辑配置。

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

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

-目前 Uni-Lab 仅支持 ros2 作为通信中间件。
+目前 Uni-Lab 支持以下通信中间件：
+
+- **ros** (默认)：基于 ROS2 的通信
+- **simple**：简化通信模式
+- **automancer**：Automancer 兼容模式

 ## 端云桥接 `--app_bridges`

-目前 Uni-Lab 提供 FastAPI (http), MQTT 两种端云通信方式。其中默认 MQTT 负责端对云状态同步和云对端任务下发，FastAPI 负责端对云物料更新。
+目前 Uni-Lab 提供 WebSocket、FastAPI (http) 两种端云通信方式：
+
+- **WebSocket**：负责实时通信和任务下发
+- **FastAPI**：负责端对云物料更新和 HTTP API

 ## 分布式组网

-启动 Uni-Lab 时，加入 `--without_host` 将作为从站，不加将作为主站，主站 (host) 持有物料修改权以及对云端的通信。局域网内分别启动的 Uni-Lab 主站/从站将自动组网，互相能访问所有设备状态、传感器信息并发送指令。
+启动 Uni-Lab 时，加入 `--is_slave` 将作为从站，不加将作为主站：
+
+- **主站 (host)**：持有物料修改权以及对云端的通信
+- **从站 (slave)**：无主机权限，可选择跳过等待主机服务 (`--slave_no_host`)
+
+局域网内分别启动的 Uni-Lab 主站/从站将自动组网，互相能访问所有设备状态、传感器信息并发送指令。
+
+## 可视化选项
+
+### 2D 可视化
+
+使用 `--2d_vis` 在 PyLabRobot 实例启动时同时启动 2D 可视化。
+
+### 3D 可视化
+
+通过 `--visual` 参数选择：
+
+- **rviz**：使用 RViz 进行 3D 可视化
+- **web**：使用 Web 界面进行可视化
+- **disable** (默认)：禁用可视化
+
+## 实验室管理
+
+### 首次使用
+
+如果是首次使用，系统会：
+
+1. 提示前往 https://uni-lab.bohrium.com 注册实验室
+2. 引导创建配置文件
+3. 设置工作目录
+
+### 认证设置
+
+- `--ak`：实验室访问密钥
+- `--sk`：实验室私钥
+- 两者必须同时提供才能正常启动

 ## 完整启动示例

 以下是一些常用的启动命令示例：

 ```bash
-# 使用配置文件和组态图启动
-unilab -g path/to/graph.json
+# 使用组态图启动，上传注册表
+unilab --ak your_ak --sk your_sk -g path/to/graph.json --upload_registry

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