From e2403f64ceb1920416bdad1492d08ac509287f5a Mon Sep 17 00:00:00 2001 From: Xuwznln <18435084+Xuwznln@users.noreply.github.com> Date: Mon, 10 Aug 2026 09:26:24 +0800 Subject: [PATCH] docs: standardize Jazzy and Python 3.12 guidance --- .cursor/skills/create-device-package/SKILL.md | 12 ++-- .gitignore | 2 +- README.md | 15 ++++- README_zh.md | 13 ++++- docs/_static/.gitkeep | 1 + docs/advanced_usage/configuration.md | 2 +- docs/developer_guide/networking_overview.md | 2 +- docs/index.md | 3 + docs/intro.md | 1 + docs/user_guide/best_practice.md | 11 ++-- docs/user_guide/installation.md | 32 ++++++---- docs/user_guide/launch.md | 2 +- docs/user_guide/runtime_baseline.md | 58 +++++++++++++++++++ unilabos/app/package_cli.py | 2 +- unilabos/devices/ros_dev/moveit2.py | 2 +- 15 files changed, 126 insertions(+), 32 deletions(-) create mode 100644 docs/_static/.gitkeep create mode 100644 docs/user_guide/runtime_baseline.md diff --git a/.cursor/skills/create-device-package/SKILL.md b/.cursor/skills/create-device-package/SKILL.md index 29c82a6b3..48277103a 100644 --- a/.cursor/skills/create-device-package/SKILL.md +++ b/.cursor/skills/create-device-package/SKILL.md @@ -195,7 +195,7 @@ build-backend = "setuptools.build_meta" name = "" version = "0.1.0" 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 ./ --external_devices_only diff --git a/.gitignore b/.gitignore index fa3c9693d..2b6eb87ac 100644 --- a/.gitignore +++ b/.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 diff --git a/README.md b/README.md index 0cb07d5b6..d7b50a043 100644 --- a/README.md +++ b/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?** diff --git a/README_zh.md b/README_zh.md index 8f386500b..066a00435 100644 --- a/README_zh.md +++ b/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 ``` **如何选择？** diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 000000000..17ceff3ad --- /dev/null +++ b/docs/_static/.gitkeep @@ -0,0 +1 @@ +# Placeholder for Sphinx static assets. diff --git a/docs/advanced_usage/configuration.md b/docs/advanced_usage/configuration.md index 465175910..2392d6dbc 100644 --- a/docs/advanced_usage/configuration.md +++ b/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) diff --git a/docs/developer_guide/networking_overview.md b/docs/developer_guide/networking_overview.md index 828fa7b06..32abd81ab 100644 --- a/docs/developer_guide/networking_overview.md +++ b/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) - 复杂工作站搭建 --- diff --git a/docs/index.md b/docs/index.md index 6326bb8ce..b1fdeb6d7 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/intro.md b/docs/intro.md index 8ef2a1cec..53b29a941 100644 --- a/docs/intro.md +++ b/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 diff --git a/docs/user_guide/best_practice.md b/docs/user_guide/best_practice.md index 6b3fff379..329fa1bfb 100644 --- a/docs/user_guide/best_practice.md +++ b/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 diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index bcb8ce4ed..0ee71eae5 100644 --- a/docs/user_guide/installation.md +++ b/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 diff --git a/docs/user_guide/launch.md b/docs/user_guide/launch.md index cf3b9c422..f5faaadb2 100644 --- a/docs/user_guide/launch.md +++ b/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)。 ## 初始化信息来源 diff --git a/docs/user_guide/runtime_baseline.md b/docs/user_guide/runtime_baseline.md new file mode 100644 index 000000000..dd2542e2f --- /dev/null +++ b/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`。 diff --git a/unilabos/app/package_cli.py b/unilabos/app/package_cli.py index 658dccf60..d10489b2d 100644 --- a/unilabos/app/package_cli.py +++ b/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 diff --git a/unilabos/devices/ros_dev/moveit2.py b/unilabos/devices/ros_dev/moveit2.py index 80bea9da8..7273f5715 100644 --- a/unilabos/devices/ros_dev/moveit2.py +++ b/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