外部仓库分发实践：以 T800 为例的 unilab 包分发与外迁/新建指南

[TATP-233]

外部仓库分发实践：以 T800 为例的 unilab 包分发与外迁/新建指南

接续 #1451 的 P0 方向（发布真正可安装的 UniLab 包、降低首次使用门槛），最小外部仓库分发已完成闭环验证并正式化：

• 包分发（生产 PyPI）：unilab 0.1.0 —— https://pypi.org/project/unilab/0.1.0/ ；unilab-rl 0.2.0 —— https://pypi.org/project/unilab-rl/0.2.0/ ；unisim-core 此前已在 PyPI。下游不再需要任何 TestPyPI index 配置（UniLab 侧切换见 chore: switch unilab-rl distribution from TestPyPI to PyPI #1492）。
• 外部训练仓库：https://github.com/unilabsim/engineai_rl_unilab —— 以 EngineAI T800 walk-flat（Manager-Based PPO + SAC，MuJoCo 后端；SAC 另有 configured-only 的 mjwarp owner）为例，只依赖 PyPI 上的 unilab/unilab-rl wheel，不依赖 UniLab 源码 checkout。
• 仓内外迁已闭环：UniLab 仓内 T800 任务已删除（chore: 移除仓内 T800 任务，完成到 engineai_rl_unilab 的外迁 (#1490) #1491），训练任务唯一归属外部仓库。
• 端到端验证：干净 venv uv sync 后 PPO 冒烟训练、headless eval 跑通；SAC 默认参数完整训练跑通并产出 checkpoint（logs/fast_sac/EngineAIT800WalkFlat/）。
• release 工程化：unilab_rl 已有 tag 触发自动发 PyPI 的 workflow（PYPI_TOKEN secret，ci: publish releases to PyPI instead of TestPyPI unilabsim/unilab_rl#8）；版本纪律（public contract 变更至少 minor bump + CHANGELOG）见其 AGENTS.md。

外部仓库对接 UniLab 的两个缝（seam）

外部仓库不需要 fork 或 patch UniLab，只需使用两个已存在的扩展点：

1. 任务注册 —— 环境变量 UNILAB_EXTRA_REGISTRY_PACKAGES（src/unilab/base/registry.py）
   让 ensure_registries() 在训练主进程和 spawn collector 子进程中额外导入外部任务包；
   任务包通过 __unilab_registry_modules__ 声明 leaf 模块，模块内调用
   registry.register_env_config / registry.register_env 完成注册。
2. 配置组合 —— Hydra --config-dir 把外部仓库的 conf 目录追加进 UniLab 训练脚本的
   config search path。实践要点：conf 树按算法分目录（conf/ppo/、conf/sac/），与 UniLab
   仓内布局一致；薄 CLI 按 --algo 把对应的 conf/<algo> 注入 --config-dir 后转发给 wheel 内
   的 src/unilab/scripts/train_*.py。外部 task=<task>/<sim> owner YAML（base.yaml 任务声明 +
   <sim>.yaml 后端 owner）直接参与组合。

机器人资产策略（实践修正）：最初按 UniLab 仓内模式把 mesh/纹理托管 HF、XML 入 git；实际
外迁后发现对外部仓库更省心的做法是全部资产（XML + mesh/纹理）直接入 git，开箱即用，
assets.py 的 snapshot_download 仅作为文件缺失时的 HF 兜底（冷路径）。训练 run 的资产解析
相对仓库根 cwd，无需任何下载等待。

指南一：内部已有机器人训练外迁

以 T800 为例（外迁实例：外部仓库 EngineAIT800WalkFlat，仓内删除 PR #1491）：

1. 复制任务代码：src/unilab/tasks/locomotion/<robot>/ 整目录迁到外部仓库
   src/<pkg>/tasks/<robot>/。manager terms 中对 unilab.envs.mdp、
   unilab.managers、unilab.utils 等公共 API 的 import 不变 —— 这些都在 wheel 里。
2. 复制 owner 配置 —— 按算法族逐个核对：src/unilab/conf/<algo>/task/<task>/ 的
   base.yaml + <sim>.yaml 迁到外部仓库 src/<pkg>/conf/<algo>/task/<task>/。
   实践教训：offpolicy 算法族（SAC/TD3/FlashSAC）容易漏迁 —— T800 第一版只迁了 PPO，
   后来补齐 conf/sac/（base/mujoco owner + mjwarp 注册）才完整。迁移清单按
   ls src/unilab/conf/*/task/<task>/ 全量核对。然后：
   • _target_ / func 中指向仓内任务模块的 dotted path 改为外部包路径
     （如 unilab.tasks.locomotion.t800.manager_terms.T800JointPositionActionCfg
     → engineai_rl_unilab.tasks.t800.manager_terms.T800JointPositionActionCfg）；
     指向 unilab.envs.mdp.*、unilab.tasks.locomotion.common.* 等公共 term 的引用保持不变；
   • env.scene.model_file 改为外部仓库相对路径（训练从仓库根启动，cwd 相对解析）；
   • training.task_name 与 registry.register_env* 的名字对齐；
   • 外部任务名建议加前缀（如 EngineAI…），避免与仓内同名注册冲突。
3. 迁移机器人资产：src/unilab/assets/robots/<robot>/ 整目录（XML + mesh/纹理）入外部
   仓库 git。注意保持 robot.xml 为纯机器人描述，<keyframe> 放 task-level scene XML（仓库不变量）。
4. 接入两个缝：任务包提供 __unilab_registry_modules__；仓库提供一个薄 CLI
   （参考 engineai_rl_unilab/cli.py，约 100 行）按 --algo 注入 env var 和
   --config-dir conf/<algo> 后转发给 unilab 的训练脚本。
5. 从 UniLab 仓内删除原任务（外迁最后一步）：移除 tasks 模块、__unilab_registry_modules__
   条目、conf owner YAML，并同步 support matrix / migration matrix / 相关测试（实例：chore: 移除仓内 T800 任务，完成到 engineai_rl_unilab 的外迁 (#1490) #1491）。
   实践教训：删除 commit 不要夹带资产二进制 —— 如果同一提交动了 .gitignore 再
   git add -A，会把本应忽略的资产文件带进历史；一旦发现用 git rm -r --cached + amend
   修复，不要让大文件污染仓库历史。

指南二：新机器人仓库从零基于 unilab 分发构建

1. pyproject 依赖 PyPI 分发包（无需任何额外 index）：

   [project]
   dependencies = ["unilab[mujoco]==0.1.0", "unilab-rl==0.2.0"]

   pip 等价：pip install "unilab[mujoco]==0.1.0"。
   注意 [mujoco] extra 里的 mujoco-uni-runtime 需要对着解析出的 mujoco 版本本机编译
   （uv 项目需照抄 unilab 的 no-build-isolation-package / no-binary-package 设置）；
   torch 走 cu128 index 的 tool.uv.sources 配置也要照抄。

2. 准备机器人资产：robot.xml 保持纯机器人描述（body/joint/actuator/sensor），
   <keyframe> 放 task-level scene XML；XML + mesh/纹理全部入 git（或按 UniLab 仓内模式
   托管 HF + 冷路径下载兜底）。

3. 写任务：Manager-Based 路线下，多数任务只需一份 base.yaml 任务声明
   （obs/action/command/event/termination 组合 unilab.envs.mdp.* 公共 term）+
   每后端一份 owner YAML；机器人专属 term（如 T800 的 hold-joint action）放本仓库
   tasks/<robot>/manager_terms.py。要支持多个算法就在 conf/<algo>/task/<task>/ 各备一套。

4. 注册 + 薄 CLI：照抄 engineai_rl_unilab 的 tasks/__init__.py 与 cli.py 模式即可。

5. 验证：PPO 冒烟 —
   uv run <pkg>-train --algo ppo --task <task> --sim mujoco algo.num_envs=4 algo.max_iterations=2 training.no_play=true training.play_env_num=4。
   实践教训：offpolicy（SAC）不要用极限缩小的 override 冒烟（过小 num_envs/buffer 会卡在
   collector 启动），直接用默认参数短跑确认 checkpoint 落盘即可。

当前边界

• unilab/unilab-rl 已是 PyPI 正式分发（0.1.0 / 0.2.0），但版本策略仍处早期：外部仓库
  pin 死 unilab==0.1.0；unilab 公共 API（unilab.envs.mdp、unilab.managers、registry、
  Hydra 配置契约）的稳定性决定下游维护成本，后续版本演进需要明确的兼容承诺或迁移说明。
• SAC 的 mjwarp owner 是 configured-only（关闭 kp/kd DR）；sim2sim 跨后端 play、更多后端
  owner、资产权限模型仍是开放项。
• 欢迎有真实机器人外迁需求的团队直接在 https://github.com/unilabsim/engineai_rl_unilab
  的模式上试水并反馈缺口。