docs: standardize Jazzy and Python 3.12 guidance

.cursor/skills/create-device-package/SKILL.md

@@ -195,7 +195,7 @@ build-backend = "setuptools.build_meta"
 name = "<package_name>"
 version = "0.1.0"
 description = "<description>"
-requires-python = ">=3.10"
+requires-python = ">=3.12,<3.13"
 dependencies = [
     # 用户指定的依赖
 ]
@@ -218,18 +218,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: conda-incubator/setup-miniconda@v3
+      - uses: conda-incubator/setup-miniconda@v4
         with:
           miniforge-version: latest
           use-mamba: true
-          python-version: '3.11.14'
-          channels: conda-forge,robostack-staging,uni-lab
-          channel-priority: flexible
+          python-version: '3.12.13'
+          channels: conda-forge,robostack-jazzy,uni-lab
+          channel-priority: strict
           activate-environment: unilab
           auto-update-conda: false
       - name: Install unilabos
         shell: bash -el {0}
-        run: mamba install -n unilab --override-channels -c uni-lab -c robostack-staging -c conda-forge uni-lab::unilabos -y
+        run: mamba install -n unilab --override-channels -c uni-lab -c conda-forge -c robostack-jazzy uni-lab::unilabos -y
       - name: Validate
         shell: bash -el {0}
         run: unilab --check_mode --devices ./<package_name> --external_devices_only

.gitignore

@@ -248,7 +248,7 @@ unilabos/device_mesh/view_robot.rviz
 # Certs
 **/.certs
 local_test2.py
-ros-humble-unilabos-msgs-0.9.13-h6403a04_5.tar.bz2
+ros-*-unilabos-msgs-*.tar.bz2
 *.bz2
 test_config.py
 

README.md

@@ -29,6 +29,15 @@ Detailed documentation can be found at:
 
 - [Online Documentation](https://deepmodeling.github.io/Uni-Lab-OS/)
 
+## Supported Runtime
+
+The current binary and development baseline is **Python 3.12.13 (`cp312`) + ROS 2
+Jazzy + NumPy 2**, using `robostack-jazzy::ros2-distro-mutex 0.15.*`. Python 3.11
+and ROS 2 Humble environments are legacy combinations and should not be upgraded in
+place or mixed with the Jazzy channels. See the
+[runtime and ABI baseline](docs/user_guide/runtime_baseline.md) for migration and
+verification instructions.
+
 ## Quick Start
 
 ### 1. Setup Conda Environment
@@ -47,17 +56,17 @@ mamba create -n unilab python=3.12.13
 mamba activate unilab
 
 # Option A: Standard installation (recommended for most users)
-mamba install uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 
 # Option B: For developers (editable mode development)
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 # 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 conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-full -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 **When to use which?**

README_zh.md

@@ -29,6 +29,13 @@ Uni-Lab-OS 是一个用于实验室自动化的综合平台，旨在连接和控
 
 - [在线文档](https://deepmodeling.github.io/Uni-Lab-OS/)
 
+## 支持的运行时
+
+当前二进制包和开发环境统一使用 **Python 3.12.13（`cp312`）+ ROS 2 Jazzy +
+NumPy 2**，并锁定 `robostack-jazzy::ros2-distro-mutex 0.15.*`。Python 3.11
+与 ROS 2 Humble 环境仅作为历史组合保留，不应在原环境中直接升级或与 Jazzy
+频道混用。迁移和版本核对方法见[运行时与 ABI 基线](docs/user_guide/runtime_baseline.md)。
+
 ## 快速开始
 
 ### 1. 配置 Conda 环境
@@ -47,17 +54,17 @@ mamba create -n unilab python=3.12.13
 mamba activate unilab
 
 # 方案 A：标准安装（推荐大多数用户）
-mamba install uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 
 # 方案 B：开发者环境（可编辑模式开发）
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 # 然后安装 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 conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-full -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 **如何选择？**

docs/_static/.gitkeep

@@ -0,0 +1 @@
+# Placeholder for Sphinx static assets.

docs/advanced_usage/configuration.md

@@ -760,4 +760,4 @@ unilab --config base_config.py \
 
 - [工作目录详解](working_directory.md)
 - [启动参数详解](../user_guide/launch.md)
-- [快速安装指南](../user_guide/quick_install_guide.md)
+- [安装指南](../user_guide/installation.md)

docs/developer_guide/networking_overview.md

@@ -658,7 +658,7 @@ ros2 topic list
 - [安装指南](../user_guide/installation.md) - 环境安装步骤
 - [启动参数详解](../user_guide/launch.md) - 启动参数说明
 - [添加设备驱动](add_device.md) - 自定义设备开发
-- [工作站架构](workstation_architecture.md) - 复杂工作站搭建
+- [工作站架构](examples/workstation_architecture.md) - 复杂工作站搭建
 
 ---
 

docs/index.md

@@ -2,6 +2,9 @@
 
 Uni-Lab-OS 是一个开源的实验室自动化操作系统，提供统一的设备接口、工作流管理和分布式部署能力。
 
+当前支持的运行时基线为 Python 3.12.13（`cp312`）、ROS 2 Jazzy 和 NumPy 2。
+安装或从旧环境迁移前，请先阅读[运行时与 ABI 基线](user_guide/runtime_baseline.md)。
+
 ```{toctree}
 :maxdepth: 3
 

docs/intro.md

@@ -18,6 +18,7 @@ concepts/02-topology-and-chemputer-compile.md
 :maxdepth: 2
 
 user_guide/best_practice.md
+user_guide/runtime_baseline.md
 user_guide/installation.md
 user_guide/launch.md
 user_guide/graph_files.md

docs/user_guide/best_practice.md

@@ -4,6 +4,9 @@
 
 本指南将引导您从零开始完成 Uni-Lab-OS 实验室系统的完整搭建，从环境安装到高级设备开发。无论您是初次接触 Uni-Lab-OS 的用户，还是希望深入定制开发的开发者，都能在本指南中找到清晰的步骤和实用建议。
 
+> 本指南统一以 Python 3.12.13（`cp312`）、ROS 2 Jazzy 和 NumPy 2 为基线。
+> 从 Python 3.11/ROS 2 Humble 环境迁移时，请先阅读[运行时与 ABI 基线](runtime_baseline.md)。
+
 ### 适用对象
 
 - **实验室管理员**：负责实验室系统部署和维护
@@ -54,15 +57,15 @@ mamba activate unilab
 # 4. 安装 Uni-Lab-OS（选择其一）
 
 # 方案 A：标准安装（推荐大多数用户）
-mamba install uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 
 # 方案 B：开发者环境（可编辑模式开发）
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 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 conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-full -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 **选择建议：**
@@ -802,7 +805,7 @@ Waiting for host service...
 # 1. 创建环境并安装 unilabos-env（ROS2 + conda 依赖 + uv）
 mamba create -n unilab python=3.12.13
 conda activate unilab
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 
 # 2. 克隆代码
 git clone https://github.com/deepmodeling/Uni-Lab-OS.git

docs/user_guide/installation.md

@@ -13,6 +13,18 @@
   - 开发者需要 Git 和基本的 Python 开发知识
   - 自定义 msgs 需要 GitHub 账号
 
+### 当前运行时基线
+
+| 组件 | 要求 |
+|------|------|
+| Python | 3.12.13（`cp312` ABI，包约束为 `>=3.12,<3.13`） |
+| ROS 2 | Jazzy（`robostack-jazzy`） |
+| NumPy | `>=2,<3` |
+| ROS 2 distro mutex | `0.15.*`，Jazzy 构建 |
+
+Python 3.11/ROS 2 Humble 旧环境请新建环境迁移，不要原地混用 Humble 与 Jazzy
+频道。完整的兼容矩阵、迁移步骤和验证命令见[运行时与 ABI 基线](runtime_baseline.md)。
+
 ## 安装包选择
 
 Uni-Lab-OS 提供三个安装包版本，根据您的需求选择：
@@ -161,17 +173,17 @@ mamba activate unilab
 # 选择安装包（三选一）：
 
 # 方案 A：标准安装（推荐大多数用户）
-mamba install uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 
 # 方案 B：开发者环境（可编辑模式开发）
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 # 然后安装 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 conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-full -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 **参数说明**:
@@ -180,7 +192,7 @@ mamba install uni-lab::unilabos-full -c conda-forge -c robostack-jazzy
 - `uni-lab::unilabos`: 安装 unilabos 完整包，开箱即用（推荐）
 - `uni-lab::unilabos-env`: 仅安装环境依赖，适合开发者使用 `pip install -e .`
 - `uni-lab::unilabos-full`: 安装完整包（含 ROS2 Desktop、Gazebo、MoveIt 等）
-- `-c conda-forge -c robostack-jazzy`: 添加通用依赖与 ROS 2 Jazzy 软件源
+- `-c uni-lab -c conda-forge -c robostack-jazzy`: 添加 UniLabOS、通用依赖与 ROS 2 Jazzy 软件源
 
 **包选择建议**：
 - **日常使用/生产部署**：安装 `unilabos`（推荐，完整功能，开箱即用）
@@ -196,10 +208,10 @@ mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/f
 mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
 
 # 然后重新执行安装命令（推荐标准安装）
-mamba create -n unilab uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba create -n unilab uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 
 # 或完整版（仿真/可视化）
-mamba create -n unilab uni-lab::unilabos-full -c conda-forge -c robostack-jazzy
+mamba create -n unilab uni-lab::unilabos-full -c uni-lab -c conda-forge -c robostack-jazzy
 
 # pip 安装时使用清华镜像（开发者安装时使用）
 uv pip install -r unilabos/utils/requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
@@ -255,7 +267,7 @@ mamba create -n unilab python=3.12.13
 conda activate unilab
 
 # 安装开发者环境包（ROS2 + conda 依赖 + uv）
-mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 ### 第三步：安装 pip 依赖和可编辑模式安装
@@ -455,7 +467,7 @@ where unilab  # Windows
 # 删除旧环境重新创建
 conda deactivate
 conda env remove -n unilab
-mamba create -n unilab uni-lab::unilabos -c conda-forge -c robostack-jazzy
+mamba create -n unilab uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
 ```
 
 ### 问题 3: 下载速度慢
@@ -535,13 +547,13 @@ cd $CONDA_PREFIX/envs/unilab
 
 1. **使用 `unilabos` 标准版**（推荐大多数用户）：
    ```bash
-   mamba install uni-lab::unilabos -c conda-forge -c robostack-jazzy
+   mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
    ```
    标准版包含完整功能，环境大小约 2-3GB（相比完整版的 8-10GB）。
 
 2. **使用 `unilabos-env` 开发者版**（最小化）：
    ```bash
-   mamba install uni-lab::unilabos-env -c conda-forge -c robostack-jazzy
+   mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
    # 然后手动安装依赖
    pip install -e .
    uv pip install -r unilabos/utils/requirements.txt

docs/user_guide/launch.md

@@ -118,7 +118,7 @@ Uni-Lab 支持使用 Python 格式的配置文件进行系统设置。通过 `--
 unilab --config path/to/your/config.py
 ```
 
-配置文件包含实验室和 WebSocket 连接等设置。有关配置文件的详细信息，请参阅[配置指南](configuration.md)。
+配置文件包含实验室和 WebSocket 连接等设置。有关配置文件的详细信息，请参阅[配置指南](../advanced_usage/configuration.md)。
 
 ## 初始化信息来源
 

docs/user_guide/runtime_baseline.md

@@ -0,0 +1,58 @@
+# 运行时与 ABI 基线
+
+本页记录当前 `dev` 分支及正式 Conda 包使用的统一运行时基线。安装、开发、CI
+和设备包应以此处为准，避免混用不同 ROS 发行版或 Python ABI。
+
+## 当前支持矩阵
+
+| 组件 | 当前基线 | 说明 |
+| --- | --- | --- |
+| Python | 3.12.13 | 固定 `cp312` ABI；当前包要求 `>=3.12,<3.13` |
+| ROS 2 | Jazzy | 使用 `robostack-jazzy` 频道 |
+| ROS 2 distro mutex | `0.15.*` | 构建字符串应为 `jazzy_*` |
+| NumPy | `>=2,<3` | 与 Jazzy/cp312 包保持同一 ABI 组合 |
+| UniLabOS messages | `ros-jazzy-unilabos-msgs` | 从 `uni-lab` 频道安装 |
+
+Python 3.11 与 ROS 2 Humble 不再是当前二进制包的支持组合。已有旧环境不要原地
+混装或切换 `robostack-humble`/`robostack-jazzy` 频道；请新建环境，避免 Conda
+求解出 ABI 不一致的 ROS、NumPy 或扩展模块。
+
+## 推荐安装
+
+```bash
+mamba create -n unilab python=3.12.13
+mamba activate unilab
+mamba install uni-lab::unilabos -c uni-lab -c conda-forge -c robostack-jazzy
+```
+
+开发者使用环境包后再安装源码：
+
+```bash
+mamba install uni-lab::unilabos-env -c uni-lab -c conda-forge -c robostack-jazzy
+uv pip install -r unilabos/utils/requirements.txt
+pip install -e .
+```
+
+## 从旧环境迁移
+
+1. 保留旧环境用于复现实验，不要在其中直接升级 ROS 发行版。
+2. 按上面的命令创建新的 Python 3.12.13/Jazzy 环境。
+3. 重新安装设备驱动及其 Python 依赖，不要复制旧环境的 `site-packages`。
+4. 验证实际安装版本：
+
+```bash
+python -c "import sys, numpy; print(sys.version); print(numpy.__version__)"
+conda list | grep -E "ros2-distro-mutex|ros-jazzy|unilabos"
+```
+
+Windows 可将最后一条命令改为：
+
+```powershell
+conda list | findstr /I "ros2-distro-mutex ros-jazzy unilabos"
+```
+
+## 历史兼容文件
+
+仓库中的 `recipes/ros-humble-unilabos-msgs/` 仅用于维护历史 Humble 消息包，
+不是当前安装入口。新的 Jazzy 消息包由 `recipes/msgs/` 构建；用户环境应安装
+`ros-jazzy-unilabos-msgs`。

unilabos/app/package_cli.py

@@ -796,7 +796,7 @@ def _sha256_file(path: Path) -> str:
 
 
 def _load_toml(path: Path) -> Dict[str, Any]:
-    """加载 toml：优先标准库 tomllib（3.11+），回退 tomli，再回退极简解析（仅取 [project] 标量）。"""
+    """加载 toml：优先当前运行时的标准库 tomllib，再回退 tomli 和极简解析。"""
     raw = path.read_bytes()
     try:
         import tomllib  # type: ignore

unilabos/devices/ros_dev/moveit2.py

@@ -2005,7 +2005,7 @@ def _plan_cartesian_path(
             self.__move_action_goal.request.start_state
         )
 
-        # The below attributes were introduced in Iron and do not exist in Humble.
+        # Jazzy 提供以下字段；保留 hasattr 以兼容旧消息对象。
         if hasattr(self.__cartesian_path_request, "max_velocity_scaling_factor"):
             self.__cartesian_path_request.max_velocity_scaling_factor = (
                 self.__move_action_goal.request.max_velocity_scaling_factor