Research: 借鉴 mjlab，规划 UniLab PyPI package 发布路径

[TATP-233]

Parent roadmap: #1252（候选项 7 的扩展）
Related: #360（已关闭；当前安装文档仍记录同一缺口）
Work type: research
Area: CI/tooling

一句话问题

UniLab 的 pyproject.toml 已声明 uv_build、0.1.0 元数据和 console scripts，但 package 产物、仓外可运行的 CLI、资产/依赖边界及 PyPI 发布流程尚未闭环。

为什么现在做

• src/unilab/cli.py:40-57 明确要求源码 checkout 同时存在 conf/ 和 scripts/；二者位于仓库顶层，clean wheel/sdist 不包含它们。安装文档也明确说明 pip/wheel 尚不支持仓外训练（EN、中文）。
• 对 origin/main@34880c7a 做 clean archive 后运行 uv build：wheel 55,860,217 bytes、sdist 55,738,839 bytes；wheel 含 279 个 asset member（未压缩约 140 MiB），但没有 conf//scripts/。src/unilab/__init__.py:5 仍为 0.0.0，与 pyproject.toml 的 0.1.0 不一致；当前 uv 0.12.5 还会提示 build-system 上限 <0.12。
• PyPI 上已经存在 unilab==0.0.0 占位项目（项目页），发布前必须确认项目所有权、2FA 和 Trusted Publisher 配置。
• UniLab 当前没有 mjlab 所具备的 RELEASING.md、make build/publish-test/publish、tag 触发的 release workflow 或 wheel/sdist 安装冒烟 job；现有 CI 只验证源码 checkout。
• mjlab v1.6.0 是可复用的发布先例：运行脚本、任务配置和必要 XML 都在 src/mjlab 包内；使用 uv_build 和完整 PyPI metadata/extras；Makefile 提供 build/TestPyPI/发布目标；RELEASING.md 固化版本、annotated tag 和发布后验证；release.yml 用 v* tag、PyPI OIDC、wheel+sdist isolated smoke 后再 publish；PyPI 产物约 14 MB，可用 uvx --from mjlab demo 验证。UniLab 仍须保留 Hydra、多后端和 owner-config contract，不能直接照搬 mjlab 的单后端布局。

最小交付结果

只产出一份 maintainer 可决策的发布分析和一个后续 child issue 草案，不改代码、不改配置、不改 CI、不上传包。推荐把“单一 unilab wheel/sdist、明确支持的 CLI 子集、package-owned 配置/脚本、backend extras、动态资产使用用户可写缓存”作为最小方案基线，同时说明 library-only 与拆分 package 的真实成本；最终支持面由 maintainer 确认。

In scope

• 审计 wheel/sdist 的文件清单、版本来源、console scripts，以及 cli.py、demo.py、HORA/多卡路径中的源码根目录假设。
• 对照 mjlab v1.6.0 的 package layout、metadata、extras、build/release workflow 和 artifact smoke，标出可借鉴与不适用部分。
• 比较最多三个发布面选项（library-only、仓外可运行的 self-contained CLI、拆分 core/backend/assets），给出用户价值、规模和长期维护成本。
• 盘点 Hydra 配置、MuJoCo/MJWarp/Motrix extras、PyTorch 私有 index、mujoco-uni-runtime 原生构建、资产体积/许可证、PyPI 名称所有权等阻塞项。
• 写出 wheel/sdist、干净环境、仓外命令和 optional backend 的最小验证矩阵，并拆出一个独立 implementation issue（含文件/LOC/PR 预算）。

Non-goals

• 本 issue 不修改 pyproject.toml、src/、conf/、scripts/、资产、文档或 GitHub Actions，不 bump version，不创建 release，不上传 TestPyPI/PyPI。
• 不用 tyro 替代 Hydra，不改变 SimBackend、env、runner、learner、registry 或 sim2sim contract。
• 不承诺一次支持所有算法、任务、后端、操作系统或第三方 task plugin。
• 不顺手清理资产/Git 历史（见 chore: 仓库瘦身，清理未使用资产和历史大文件 #350），也不实施 Roadmap: 借鉴 mjlab 的性能机制与开发体验优势（7 个候选 sub-issue） #1252 的其他候选项。

Owner 与预计改动

Owner layer 为 package/release boundary + CI/tooling；建议 owner @TATP-233（待 maintainer 确认）。本 issue 预计 0 个文件、0 行代码、0 个 PR；后续实现必须另立并单独确认的 child issue。

Acceptance criteria

• issue comment 或附录记录可复现的 clean-tree build 命令、artifact manifest/size、缺失的 conf/scripts 和版本不一致事实。
• 给出 UniLab 与 mjlab 的对照表，并明确哪些机制采用、哪些因 Hydra/多后端/资产约束拒绝。
• 明确首个发布版本支持的安装方式、命令、extras、平台和“不支持”边界。
• 对 PyPI 名称/权限、依赖索引与原生构建、资产许可证/缓存位置给出结论或责任人；未解决项有 stop condition。
• 产出一个可独立 review 的 implementation child 草案，声明文件数、净手写 LOC、PR 数和近风险验证；本 issue 全程无代码/发布副作用。

Stop conditions

• maintainer 尚未在 library-only 与仓外可运行 CLI 之间做出选择时，暂停，不进入实现。
• 资产再分发权、包大小/缓存写入策略或 optional dependency 的平台可用性无法确认时，拆分或回到决策。
• 需要新增公共 contract、execution path、runner/lifecycle 或长期 CI/support claim 时，另立 issue 并重新确认。
• unilab 项目所有权或 Trusted Publisher 未确认时，不执行任何发布动作。

[TATP-233]

复核结论与发布方案（参考 mjlab v1.6.0）

审计基准：本地 checkout 161f720a（feat/issue-1416-isaacsim-rendering，包含 origin/main@22d735d9）。对 issue 描述的原始基准 34880c7a 逐条复核，全部事实仍然成立，另有三项新发现（见 1.3）。

1. 事实复核

1.1 原结论确认

• src/unilab/cli.py:40-57 的 repo_root() / _check_private_checkout() 仍在，强制要求源码 checkout 同时存在 conf/ 和 scripts/。
• 训练脚本通过 Hydra 相对路径定位配置：scripts/train_rsl_rl.py:314 等为 config_path="../conf/ppo"，conf/（185 个文件，1.3 MB）与 scripts/（104 个文件）都在仓库顶层，uv_build 的默认产物不包含它们。
• src/unilab/__init__.py:5 仍为 __version__ = "0.0.0"，与 pyproject.toml 的 0.1.0 不一致。
• build-system 仍为 uv_build>=0.11.3,<0.12；uv 0.12.5 会提示上限过旧（mjlab v1.6.0 已升到 >=0.12.1,<0.13.0）。
• .github/workflows/ 只有 ci.yml 和 docs.yml，CI 仅验证源码 checkout；Makefile 无 build/publish 目标。
• git 追踪的 src/unilab/assets/ 共 252 个文件、140.7 MiB（g1 52.3 / go2 31.8 / a2 14.1 / allegro_hand 12.2 / sharpa_wave 11.1 / go1 9.9 / go2_arm 8.8 MiB；49 个 XML + 182 个 mesh/纹理），与 issue 记录的 wheel 55,860,217 bytes / 279 asset members 互相印证。
• 安装文档仍声明 wheel/仓外运行不支持（zh_CN 2-installation.md L68-71，指向 Work: 让 UniLab 支持 pip 安装后直接使用 #360）。
• PyPI 上 unilab==0.0.0 占位项目仍存在；mujoco-uni-runtime==0.4.0 与 motrixsim-core==0.8.2 均已在 PyPI 上有发布。

1.2 issue 提到的 HORA / 多卡路径已定位

除 cli.py、demo.py（demo.py:56 的 _repo_root()，且把 UV_PROJECT_ENVIRONMENT 指向仓库 .venv）外，repo-root 假设还存在于：cli_completion.py、ipc/dp_launcher.py（多卡）、algos/hora/distill_config.py。共 5 个文件，改造面明确可控。

1.3 新发现（对原评估的补充，均为有利条件）

1. 资产外置机制已在仓库内运行：src/unilab/assets/hub.py 已实现从 Hugging Face 下载 motions / caches / checkpoints 三类资产，assets/pull.py + unilab-pull-assets 命令已覆盖 microduck / x2 / t800 的机器人 mesh（这三个机器人在 git 中占用 ≈ 0，重资产本就不入库）。把 g1/go2 等已入库 mesh 切换到同一机制，是扩展既有路径，无需新建基础设施。
2. extras 边界已经是 PyPI 友好形态：mujoco / mjwarp / motrix / viser 四个 optional extra 的依赖全部在 PyPI 可解析；isaacgym / isaacsim 走外部运行时 + find_spec 守卫，天然不进发布物。
3. 资产许可证已有随包先例：robots/microduck/LICENSE.pollen-robotics.txt、robots/t800/LICENSE.engineai.txt 已随资产分发，HF 再分发路线延续同一模式。

2. 与 mjlab v1.6.0 的对照

机制	mjlab v1.6.0	UniLab 采用方式
运行脚本入包	src/mjlab/scripts/ + console scripts（train/play/demo/list-envs）	采用：5 个 train_*.py 入口移入包内；scripts/benchmark、tools 等开发工具留在仓库顶层
任务配置入包	Python registry（register_mjlab_task），配置即代码	采用并保留 Hydra：conf/ 整体迁入 src/unilab/conf/ 作为 package data，config_path 改为包内路径；owner YAML contract 不变
构建后端	uv_build + 完整 PyPI metadata/classifiers	采用：补 authors/keywords/classifiers，build-system 升到 <0.13，__version__ 对齐单一版本源
本地发布目标	Makefile build（uv build + wheel/sdist 隔离冒烟）、publish-test、publish	照搬
发布流程固化	RELEASING.md（bump 清单、annotated tag、TestPyPI、发布后 uvx 验证）	照搬
tag 触发发布	release.yml：v* tag + PyPI OIDC（Trusted Publisher）+ wheel/sdist 双冒烟后再 publish	照搬；冒烟脚本改为 import unilab + CLI --help（无 GPU/GL 依赖）
torch 索引路由	tool.uv.sources + 互斥 extras（cu128/cpu），PyPI 依赖本身宽松（torch>=2.7.0）	采用：依赖声明放宽为 torch>=2.7.0，现有 sources 路由保留给 uv 工作流；pip 用户从 PyPI 解析（x86_64 wheel 自带 CUDA）；aarch64 CUDA 的安装路径写入文档
第三方任务插件	mjlab.tasks entry point 组自动发现	首版不纳入；作为后续 plugin contract 候选另立 issue
资产	必要 XML 在包内，wheel ≈ 14 MB	适配：XML/元数据（小）入包，mesh/纹理（约 140 MiB）走现有 HF 下载到用户缓存；UniLab 资产体量超出 PyPI 合理包体积，HF 路线同时满足 cold-path asset access 原则

3. 发布面选项

• A. Library-only：保证 import unilab 与 backend API 在仓外可用，CLI 仍要求 checkout。改动最小（约 1 个 PR），用户价值集中在二次开发场景，train 命令的仓外可用性留给后续版本。
• B. 单一 wheel + 仓外可运行 CLI 子集（推荐基线）：pip install unilab[mujoco] 后任意目录可运行 train / eval / demo，覆盖 5 个算法 × registry 任务 × mujoco/mjwarp/motrix 后端。复用 mjlab 全套发布机制，改动约 3 个 PR（见第 6 节），长期只维护一个发布物。
• C. 拆分 core/backend/assets 多包：各 backend 独立演进、资产独立版本化，发布物边界最清晰；代价是 registry、backend contract、CI 都要按多包重组，维护多个发布节奏。适合在插件体系（unilab.tasks entry point）落地时再评估。

推荐 B 作为首版基线：它以最小改动闭环 issue 描述的全部缺口，A 是 B 的自然子集（B 的 PR1 即达成 A），C 的机制在 B 落地后仍然开放。

4. 首版支持面（建议，待 maintainer 确认）

• 安装：pip install unilab[<mujoco|mjwarp|motrix>]；发布后验证用 uvx --from unilab demo。
• 命令：train / eval / demo（含 --algo/--task/--sim/--profile 路由与 Hydra override 透传）；unilab-pull-assets、unilab-export-scene 等辅助命令随包发布。
• 平台：linux/x86_64、linux/aarch64、darwin/arm64（与 required-environments 对齐）；ROCm / XPU 维持源码 make sync-rocm / make sync-xpu 路径。
• 不支持边界（首版明确排除）：isaacgym / isaacsim 后端（外部运行时）、HORA distill 多卡提交路径、scripts/benchmark 与 scripts/tools 开发工具、第三方 task plugin 机制。
• 错误提示同步更新：_check_runtime_requirements 目前提示 uv sync --extra ...，pip 语境改为 pip install unilab[...]。

5. 阻塞项与责任人

事项	结论 / 行动	责任人
PyPI unilab 名称	存在 0.0.0 占位项目；发布前确认所有权 / 转移 + 2FA + Trusted Publisher（OIDC）	maintainer（未确认前不执行任何发布动作，沿用本 issue stop condition）
torch aarch64 CUDA	PyPI 的 aarch64 torch wheel 为 CPU-only；uv 工作流已有 r2-cu130 索引路由，pip 用户按文档走 PyTorch 官方索引	实现 owner（文档 + 验证矩阵覆盖）
mujoco-uni-runtime 原生构建	no-build-isolation / no-binary 是 uv 项目级配置；pip 用户将拿到 PyPI 预编译 wheel（绑定特定 mujoco build），需在干净环境验证 pip install unilab[mujoco] 的 mujoco 版本窗口兼容性，必要时为首版收紧 mujoco pin	实现 owner（验证矩阵第一项）
资产许可证	microduck / t800 已有随包 LICENSE；g1 / go2 / a2 / allegro_hand / sharpa_wave 的 HF 再分发权需确认（这些资产当前已随公开 git 仓库分发，HF 路线延续同一分发模式）	maintainer 指定
conf/ 入包的 contract 定位	owner YAML 成为 package data 后，第三方覆盖配置的路径规则需在文档中定义	maintainer 确认

6. Implementation child issue 草案

目标：pip install unilab[mujoco] 在干净环境、任意目录完成 demo 与一次短 train，发布流程可一键复现。

• PR1 — 包布局闭环（达成选项 A）：conf/ → src/unilab/conf/（185 文件，机械 git mv）；5 个训练入口脚本入包并修正 config_path（5 文件）；cli.py / demo.py / cli_completion.py / ipc/dp_launcher.py / algos/hora/distill_config.py 的 repo-root 假设改为包内资源定位（5 文件，约 150 行手写）；pyproject.toml 补 package-data、metadata、版本单一源、build-system <0.13（约 40 行）。验证：make test-all + 干净 venv pip install . 后仓外 train --help / demo。
• PR2 — 资产外置：hub.py 下载机制扩展到 g1 / go2 / a2 / allegro_hand / sharpa_wave / go2_arm（约 100 行）；uv_build exclude 规则（约 10 行）；缓存目录约定（HF cache / ~/.cache/unilab）与文档。验证：wheel 清单不含大 mesh、wheel 体积 < 20 MB、干净环境首次运行自动下载、离线缓存复用。
• PR3 — 发布工作流：Makefile build / publish-test / publish（约 20 行）；RELEASING.md（约 60 行）；.github/workflows/release.yml（v* tag + OIDC + 双冒烟，约 45 行）；tests/smoke_test.py（约 30 行）；安装文档更新。验证：TestPyPI 全流程 + 发布后 uvx --refresh --from unilab demo。

预算合计：净手写约 400–500 行（其余为机械移动），3 个可独立 review / 回退的 PR。每个 PR 创建或更新前在最终 head 运行 make test-all。

7. 请 maintainer 确认的决策点

1. 首版支持面采用选项 B（仓外可运行 CLI 子集）。
2. conf/ 以 package data 身份入包，Hydra 机制与 owner YAML contract 保持不变。
3. 大体积 mesh 默认走 HF 下载 + 用户缓存（扩展 assets/hub.py 既有机制）。
4. PyPI 名称所有权与资产许可证确认的责任人指派。

以上任一点未确认前，按本 issue 既有 stop condition 暂停，不进入实现。

[TATP-233]

三个 implementation 子任务已创建并挂为本 issue 的 sub-issue（按依赖顺序推进）：

1. Packaging: conf/ 与训练入口迁入包内，消除 repo-root 假设（#1326 子任务 1） #1421 — 包布局闭环：conf/ 与训练入口迁入包内，消除 repo-root 假设（1 PR，净手写约 200 行）
2. Packaging: 机器人 mesh 切换至 HF 下载与用户缓存，wheel 瘦身（#1326 子任务 2） #1422 — 资产外置：机器人 mesh 切换至 HF 下载与用户缓存，wheel < 20 MB（1 PR，净手写约 120 行）
3. Release: Makefile 发布目标 + RELEASING.md + tag 触发的 PyPI 发布 workflow（#1326 子任务 3） #1423 — 发布工作流：Makefile 发布目标 + RELEASING.md + tag 触发的 PyPI 发布 workflow（1 PR，净手写约 160 行）

每个子任务的范围、Non-goals、验收标准与 stop conditions 均在各自 issue 内独立成立，可分别 review 与回退。进入实现前仍需 #1326 第 7 节的四个决策点获得 maintainer 确认。