roadmap: MuJoCo 全线对齐 3.11 + mujoco-uni-runtime 预编译 wheel + 依赖声明统一放宽 #1515

Owner summary

目标：把 UniLab 当前三条 MuJoCo 版本线（mujoco extra 锁 3.10.0、mjwarp extra 钉 mujoco-warp 3.10.0.3、newton extra 钉 3.11.0）统一对齐到 3.11 线，并让默认安装路径不再要求本机 C++ 工具链——目前在没有编译器的干净机器上 make setup 必然失败（已复现：error: [Errno 2] No such file or directory: 'c++'，mujoco-uni-runtime 只发 sdist、同步时就地编译原生扩展）。

推荐方案（三个不可分割的部分，整体交付）：

1. mujoco-uni-runtime 上游把支持窗口扩展到 3.11，unisim / UniLab 三条 extra 的 mujoco、mujoco-warp、warp-lang 全线对齐，争取删除现有两条 extra conflicts，实现单环境装齐全部 MuJoCo 系后端。
2. 对齐后把 mujoco 依赖声明统一为 mjlab 风格的宽松 bound（mujoco~=3.11.0）+ uv.lock 精确钉版；newton 线因上游耦合精确，保持 == 钉死。
3. mujoco-uni-runtime 为默认 mujoco 3.11.0 发布 3 平台（linux x86_64 / linux aarch64 / darwin arm64）× 4 Python（3.10–3.13）共 12 个预编译 wheel；UniLab 摘除 no-binary-package，make mujoco 改为 sdist 回退路径，文档补齐本地切换 mujoco 绑定的方法与报错对照表。

交付边界：不考虑物理行为漂移——不做 benchmark 重基线，不做已训练策略的跨版本回归验证。不涉及 mujoco 3.12+ 支持，不做原生扩展动态符号绑定重构。

预计规模：3 个仓库（mujoco_uni、unisim、UniLab），4–6 个 PR，中大规模 roadmap。

永久维护责任：mujoco 版本 bump 与 runtime wheel 发版的跨仓协调规则、wheel 发布 CI 的维护、对齐线随 newton 上游升级的跟进。

需要 maintainer 决定：是否接受 3.11 成为唯一支持线（放弃 >=3.5,<3.11 窗口）；wheel 发布规则（默认 mujoco bump 即 runtime 发新版）；conflicts 删除的验收方式。

现状（证据）

• pyproject.toml:118-119：mujoco extra 为 mujoco>=3.5（宽松 bound）+ mujoco-uni-runtime==0.4.0；uv.lock 钉 mujoco 3.10.0，测试窗口 >=3.5,<3.11。
• pyproject.toml:127-133：mjwarp extra 钉 mujoco-warp==3.10.0.3（historical 线）、warp-lang>=1.14（lock 在 1.14.x）。
• pyproject.toml:136-149：newton extra 钉 newton==1.5.1 + mujoco-warp==3.11.0 + mujoco==3.11.0 + warp-lang==1.16.0。
• pyproject.toml:181-184：两条 conflicts（mjwarp×newton、mujoco×newton），根因正是三条版本线不能同环境共存。
• pyproject.toml:185-194：no-build-isolation-package + no-binary-package 强制 mujoco-uni-runtime 在本环境从 sdist 编译；注释说明索引上的预编译 wheel 绑定单一 mujoco build，故弃用。
• unisim 侧完全镜像上述 extras（unisim-core pyproject：mujoco / mjwarp / newton 三个 extra 同样分裂）。
• mujoco_uni 上游（mujoco_uni/pyproject.toml）：声明 mujoco>=3.5,<3.11，tools/version_matrix.py 默认只测 3.5–3.10；release.yml 只发 sdist，注释明确"预编译 wheel 会把消费者悄悄钉到某一个 MuJoCo release"；原生扩展编译时记录 mujoco 版本（batch_env.cc 的 MUJOCO_UNI_BUILD_MUJOCO_VERSION），加载时不匹配即拒绝。
• 报错复现（Ubuntu 26.04 干净机器）：make setup 在编译 batch_env.cc 时失败 error: [Errno 2] No such file or directory: 'c++'；安装文档（docs/sphinx/source/zh_CN/1-getting_started/2-installation.md:12-20）只写了 Python.h 一种报错形态，该形态查不到。
• unilab-rl 不依赖 mujoco（仅 numpy / torch / tensordict / omegaconf），本 roadmap 对它无改动。

关键设计约束（三部分组合后的矛盾消解规则）

1. ~= bound 与 wheel 精确绑定的冲突：mujoco~=3.11.0 允许解析器升到 3.11.1，但 wheel 与任何已编译扩展只认构建时的 3.11.0，加载即拒绝。规则：pyproject bound 用 ~=3.11.0，uv.lock 精确钉 3.11.0，wheel 绑定 3.11.0；mujoco patch/minor bump = mujoco-uni-runtime 同步发新版 wheel，UniLab 升 lock 中 mujoco 以 wheel 就绪为 gate；加载时报错文案改为直接指向 sdist 重建路径。
2. warp-lang 对齐是 conflicts 删除的前提：mjwarp extra 的 warp-lang>=1.14（1.14.x）与 newton 的 warp-lang==1.16.0 不对齐时，即使 mujoco / mujoco-warp 全部统一到 3.11，两条 conflicts 仍删不掉。方案 1 的范围明确包含 warp-lang 对齐验证。
3. wheel 身份限制：PyPI 文件名只编码 包版本-Python ABI-平台，一个发布的 runtime 版本只能携带一种 mujoco 绑定的 wheel；默认 mujoco 变更必须伴随 runtime 版本号升级重新发布。
4. 回退路径保留：make mujoco MJ=<version> 改用 uv sync --no-binary-package mujoco-uni-runtime --reinstall-package ... 强制 sdist 重建；Makefile 增加 C++ 工具链 preflight 检查（缺 c++ 时直接给出 apt-get install build-essential 等提示），因为换版本路径永远需要本地编译。

Child issues 与集成顺序

#1 [mujoco_uni] spike：支持窗口扩展到 3.11（version_matrix 3.11 全绿）—— go/no-go 决策点
        │
#2 [mujoco_uni] release.yml 改造：12 wheel 矩阵构建与发布 + 发布规则文档（依赖 #1）
        │
#3 [unisim] 三个 extra 对齐 3.11 线 + warp-lang 对齐（依赖 #1）
        │
#4 [UniLab] extras 对齐 + 删 conflicts + 摘 no-binary-package + Makefile preflight
   与 make mujoco 回退改造（依赖 #1、#2、#3）
        │
#5 [UniLab] 文档：安装页错误签名对照表、本地切换 mujoco 绑定教程、双语更新
   （与 #4 可并行，合入不早于 #4）

• Feat/rsl rl v4 compat #1 是整个 roadmap 的唯一硬阻塞点：mujoco 3.10→3.11 若存在 API/ABI 断裂且修复成本过高，整体方案需要回到 maintainer 处重新决策。
• Feat/appo #2 的 CI 改造可以基于现有 release.yml（已在 4 个 OS 上编译测试 sdist，产 wheel 是既有构建矩阵的副产品）并行开发。
• declared base branch：main。集成分支在 roadmap 授权后从 main 最新 head 创建。

预计规模

• mujoco_uni：窗口扩展 + 可能的 API 适配 + release.yml 矩阵改造 + 发布规则文档，2 个 PR，中规模（spike 结果决定 API 适配量）。
• unisim：extras 对齐 + contract 验证，1 个 PR，小规模。
• UniLab：pyproject extras / tool.uv 调整、Makefile preflight 与 make mujoco 改造、conflicts 删除验证、双语安装文档与教程，1–2 个 PR，中小规模。
• 验证：每个 PR 按仓库 gate 跑本地测试；UniLab 侧 PR 合入前 make test-all。

验收标准

1. 在无 C++ 编译器的干净机器上 git clone + make setup 成功（走 wheel，无需 build-essential）。
2. make mujoco MJ=3.10.0 走 sdist 回退路径可用，preflight 与文档能引导用户完成。
3. mujoco / mjwarp / newton 三个 extra 可在单环境共存（conflicts 删除成功；若 warp-lang 对齐验证不通过，则保留 conflicts 并记录原因，作为范围复核点回到 maintainer）。
4. 加载时 mujoco 版本不匹配的报错信息直接指向重建文档。
5. 安装文档可从 c++: No such file or directory 与 Python.h 两类报错反查到修复方法（中英双语）。

永久维护成本

• 跨仓发布协调规则：mujoco 版本 bump → mujoco-uni-runtime 发新版 wheel → unisim/UniLab 升 lock，需要明确 owner 与顺序。
• wheel 发布 CI 跟随 Python（3.10–3.13）与平台（linux x86_64 / aarch64 / darwin arm64）矩阵演进。
• newton 上游升级时对齐线漂移的跟进（newton 钉死其耦合的 mujoco-warp 版本，对齐是快照而非永久状态）。
• mujoco 3.12 等未来版本的窗口扩展评估成为常规维护动作。

关联

• 动机证据：干净机器 make setup 因缺 C++ 工具链失败（本 issue 现状节），安装文档未覆盖该报错形态。
• 参考实现风格：mjlab 使用 mujoco~=3.11.0 / mujoco-warp~=3.11.0 宽松 bound（mjlab 无本地编译产物，风格不能直接平移，差异见关键设计约束第 1 条）。