调研：从 mjlab / unitree_rl_mjlab 分工看 UniLab Manager-Based API 边界与 Unitree 任务外迁

[TATP-233]

结论先行

我调研了三个当前基线：

• mjlab：main@8ee51fbcf806a7419189f706d9e394cbeb7790fa（本地为 v1.6.0-7）
• unitree_rl_mjlab：main@1425b15f73bd4095f0df53709d7c389c3eb9e790
• UniLab：main@e466aec746ed0523d761a20f98f14151cc1546f5（v1.3.0）

我的判断是：Manager-Based API 不应该跟着机器人任务一起外迁。 它是 UniLab 的环境编排、任务组合和 backend/training contract；应该外迁的是 concrete task、机器人资产、motion profile、机器人专属 term 和对应 owner YAML。这个边界与 mjlab 的实际分层一致，也符合 UniLab ADR-0006 已经确立的 NumPy / Hydra / SimBackend / NpEnvState 边界。

建议 UniLab 保留 两个 reference/conformance task：

1. G1WalkFlat：当前覆盖面最好的 locomotion 代表，覆盖 MuJoCo / mjwarp / Motrix，并为 IsaacGym / IsaacSim 提供 configured owner；PPO / SAC / FlashSAC 路径也最有代表性。
2. G1MotionTracking：保留 stateful command、motion loader、tracking reward/observation、PPO/APPO/SAC 这些比普通 locomotion 更复杂的 Manager 使用面。

其余 30 个 Unitree 相关 production task、对应机器人/场景/motion 资产、任务专属 term 和所有算法 owner YAML 迁到已创建但尚未填充的 unilabsim/unitree_rl_unilab。保留的两个任务应标记为 reference/conformance 任务，而不是继续把 UniLab 当 Unitree production task zoo；下游可以注册带 Unitree 前缀的 production 名称，避免全局 registry 冲突。

如果维护者更倾向“核心仓库完全不保留厂商任务”，可以改为保留 StewartBalance / FR3JointTarget 这类非 Unitree 代表任务，并把 G1 的多后端覆盖搬到 backend conformance fixtures 或下游 CI。但这个方案会牺牲当前最完整的多后端真实任务证据，我认为第一阶段的迁移成本和回归风险都更高。

---

1. mjlab 中 Manager-Based API 的功能归属

mjlab 的架构是“simulation layer + manager layer + reference tasks”三层，而不是把所有任务逻辑都放进 manager。

1.1 核心 runtime 归 mjlab

mjlab 拥有这些与具体机器人无关的能力：

能力	mjlab owner	职责
Physics / Warp simulation	mjlab.sim	MuJoCo Warp、CUDA graph、并行 world、NaN guard
Scene composition	mjlab.scene	Entity 组合、MjSpec 编译、env origin、sensor 挂载
Entity / actuator / sensor	mjlab.entity, mjlab.actuator, mjlab.sensor	MJCF 资产抽象、执行器、contact/raycast/camera 等
Terrain	mjlab.terrains	plane/generator/rough terrain、curriculum 所需 terrain state
Manager runtime	mjlab.managers	Action / Observation / Reward / Termination / Event / Command / Curriculum / Metrics / Recorder 的生命周期、聚合和 reset
通用 MDP terms	mjlab.envs.mdp	base/joint/action/sensor 等通用 observation、reward、termination、reset/DR event
Registry / training / play	mjlab.tasks.registry, mjlab.rl, mjlab.scripts	task ID 到 env cfg + runner cfg 的映射，RSL-RL wrapper、训练回放
Viewer / tooling	mjlab.viewer, scripts	debug visualization、scene export、benchmarks

ManagerBasedRlEnvCfg 是组合接口：scene/sim 加上 observations/actions/rewards/terminations/events/commands/curriculum/metrics/recorders 的 term dict。Manager 只负责生命周期和聚合；单个 term 负责一个 observation/reward/event/command 计算；backend/scene 负责状态与物理；training wrapper 负责算法适配。

1.2 mjlab 也保留 reference task family

mjlab 不是只有抽象库。当前注册了 12 个 task：

• Cartpole：2 个，tutorial/sanity check；
• YAM manipulation：4 个；
• G1 motion tracking：2 个；
• G1/Go1 velocity：4 个。

mjlab.tasks.velocity 和 mjlab.tasks.tracking 因此不是单纯的“示例目录”，而是 task-domain library + representative config：

• velocity 提供 UniformVelocityCommand、tracking reward、terrain curriculum、foot/contact 相关 term；
• tracking 提供 MotionLoader、MotionCommand、motion reward/observation/termination/metric；
• 再用 G1/Go1 少数代表机器人展示如何组合。

这层与 manager core 的边界是：manager 不知道“velocity”或“motion tracking”；task family terms 使用 manager API，并被 reference config 组合。

2. unitree_rl_mjlab 的实际分工

unitree_rl_mjlab 没有复制 mjlab.managers，而是依赖 mjlab；这个方向是正确的。它当前拥有：

• 20 个注册 task：8 flat velocity、8 rough velocity、4 tracking；
• 7 个 Unitree 机器人目录 / 8 个模型 variant：A2、As2、G1、G1-23Dof、Go2、H1_2、H2、R1；
• Unitree 专属参数、资产下载、motion CSV/NPZ；
• 训练/播放/转换脚本；
• MuJoCo simulation、C++ deploy、Unitree SDK/sim2real 侧代码。

代码规模上，src/tasks 约 5.1k LOC、src/assets 约 1.7k LOC、scripts 约 1.4k LOC，自有 term/class 定义约 86 个。它大量 import mjlab 的 manager cfg、scene/entity/sensor、RL wrapper 和 registry，但 velocity/tracking 的 task-domain MDP 文件存在本地分叉：例如相对本地 mjlab，velocity rewards 有数百行差异，tracking command 也有大量差异。

这说明 mjlab 与下游的实际约定是：

层	归属
Manager runtime、scene/entity/sensor/sim、通用 MDP terms	mjlab
velocity/tracking task family 的参考实现	mjlab，服务文档、测试和 API 演进
多机器人 Unitree production variants、机器人资产和调参	unitree_rl_mjlab
实机部署 / Unitree SDK / simulation deploy	unitree_rl_mjlab
新物理或 manager 通用能力	先进 mjlab contract，再由下游消费

另一个重要教训是版本协调。unitree_rl_mjlab pin 了 mjlab==1.2.0 / mujoco-warp==3.5.0，而本地 mjlab 已是 1.6.x；下游还复制并修改了 velocity/tracking term。这个模式对生产仓库可以接受，但如果没有明确兼容策略，会逐渐变成“API 名字相同、task 语义漂移”。UniLab 外迁时应避免重复这个坑。

3. UniLab 当前的 Manager-Based 现状

当前 UniLab main 已经不是 #1017 时“没有可用 manager runtime”的状态。ADR-0006 已接受，v1.3.0 的生产 registry 已全部走 canonical NumPy Manager-Based runtime：

• unilab.managers 提供 source-aligned 的 Action / Observation / Reward / Termination / Event / Command / Curriculum / Metrics / Recorder API；
• term 输入输出是 np.ndarray，没有 mjlab 的 Torch device contract；
• ManagerBasedRlEnv 继承并复用 NpEnv lifecycle，返回 NpEnvState，reset 返回 (obs_dict, info_dict)；
• actor/critic observation group 被显式映射到 obs / critic，runner/learner 不推断；
• production task 的配置 source of truth 是 Hydra owner YAML，冷路径 materialize 成 typed dataclass；
• entity/sensor/model mutation 只能通过 SceneEntityCfg、Entity facade 和 SimBackend 正式能力，不允许 term 访问 backend 私有对象；
• capability 缺失 fail-closed，而不是 warning 后跳过。

当前 migration_matrix.py 声明 37 个 production task，且全部是 canonical Manager-Based runtime。按名称粗分：

• A2 / Go1 / Go2 / G1 相关：32 个；
• 非 Unitree：Allegro 2 个、FR3 1 个、Stewart 1 个、X2 1 个。

也就是说，UniLab 的 runtime 已经完成收敛，但 concrete task 层仍然明显偏 Unitree production zoo：tasks/{locomotion,manipulation,motion_tracking} 约 9.5k LOC，G1/Go/A2 机器人资产和 motion profile 也主要服务这些任务。这正是适合外迁的部分。

外部任务缝也已经具备：

• third-party package 可声明 [project.entry-points."unilab.tasks"]；
• bootstrap package 暴露 __unilab_registry_modules__；
• 外部 Hydra config 可通过薄 CLI 的 --config-dir 进入同一训练入口；
• engineai_rl_unilab、microduck_rl_unilab、sharpa_rl_unilab 等已有实践；
• unilabsim/unitree_rl_unilab 仓库已创建，但目前只有 README first commit，尚无实现。

4. 建议的 UniLab / unitree_rl_unilab 边界

4.1 留在 UniLab

保留 infrastructure 和公共 contract：

1. Manager runtime 与公共 cfg 类型；
2. unilab.envs.mdp 中真正跨机器人、跨任务、backend-neutral 的 terms；
3. SimBackend、Entity facade、scene/reset transaction、sensor binding；
4. registry、Hydra materialization、训练/评估/回放、sim2sim contract；
5. backend conformance 与 manager 回归测试；
6. 少量 reference task，用于证明 public contract 可组合、可训练、可回放。

不建议为了“任务数量变少”把 locomotion.common、motion_tracking.common 中已被多任务复用的公共 term 全部搬走。否则下游会复制这些文件，重演 unitree_rl_mjlab 的 task-term drift。正确判断标准是语义和使用者，不是文件所在目录：

• 多厂商/多任务可复用、无 backend 私有访问：留在 UniLab public API；
• 只为某个 Unitree profile 服务，或参数/selector/资产强绑定 Unitree：外迁。

4.2 迁到 unitree_rl_unilab

外迁内容：

1. 除两个 core reference task 之外的 Unitree production task；
2. A2 / Go1 / Go2 / Go2W 等机器人 XML、mesh、texture、task scene fragment；
3. G1 production 变体与 motion profile（core 若保留 G1WalkFlat / G1MotionTracking，下游不再重复注册同名任务）；
4. Unitree 专属 manager terms、奖励调参、command profile、curriculum；
5. conf/{ppo,appo,sac,td3,flashsac}/task/** 中对应 owner YAML；
6. 任务级测试、支持矩阵证据和短冒烟命令；
7. 后续如要引入 Unitree SDK / 实机部署，也应放在该仓库，而不是 UniLab core。

外部仓库建议结构：

pyproject.toml
src/unitree_rl_unilab/
  cli.py
  assets.py                 # HF/cache/checksum resolver
  tasks/__init__.py         # __unilab_registry_modules__
  tasks/go2/...
  tasks/g1/...
  conf/ppo/task/...
  conf/sac/task/...
tests/

pyproject.toml 应使用正式 package 名和 entry point：

dependencies = [
  "unilab[mujoco]==1.3.0",
  "unilab-rl==1.2.0",
]

[project.entry-points."unilab.tasks"]
unitree = "unitree_rl_unilab.tasks"

薄 CLI 只做 config-dir 转发和入口发现，不复制训练 runner。外部任务名建议统一加 Unitree 前缀，例如 UnitreeGo2JoystickFlat、UnitreeG1FlipTracking，避免与 core registry 或其他下游冲突。

5. 迁移路线

Phase 0：先定边界和兼容承诺

需要先在 issue/ADR 中确认：

• 保留哪些 reference task；
• unilab.envs.mdp、unilab.managers、registry/Hydra owner YAML 的版本兼容政策；
• 外部任务从哪个 UniLab commit/tag 起步；
• core 移除是 breaking release 还是先有一个 deprecated alias/release。

我建议以 v1.3.0 为第一个 coordinated baseline，下游 pin exact version，core API 变更时同步迁移说明。

Phase 1：先迁两个种子任务，而不是一次搬 30 个

建议先迁：

• Go2JoystickRough：验证 quadruped common terms、assets、多算法 owner YAML；
• 一个 G1 motion profile：验证 motion loader/stateful command/SAC 路径。

在 unitree_rl_unilab 中完成 entry point、Hydra config、资产解析、PPO/SAC smoke test 和 CI 后，再批量迁移。

Phase 2：批量迁移 concrete tasks

按 family 迁移：

1. Go1/Go2/Go2W/A2 locomotion；
2. G1 locomotion variants；
3. G1 motion tracking/profile variants；
4. 对应 assets、motions、tests、docs。

每迁移一组就同步删除 UniLab 的 task module、registry tuple、owner YAML、migration matrix 记录和支持矩阵行，避免留下“已删除但矩阵仍声称存在”的漂移。

Phase 3：收窄 core production matrix

保留 G1WalkFlat / G1MotionTracking 作为 reference/conformance task，并把文档措辞从“生产任务集合”改成“核心参考任务 + ecosystem 任务”。同时：

• tests/tasks/test_package_boundary.py 的 registry tuple 缩小；
• migration_matrix.py 只描述 core retained tasks，或改名避免继续承担外部任务审计；
• support matrix 明确区分 core evidence 与 downstream repo evidence；
• core CI 保留 manager/backend conformance，不再用 30 个厂商变体当隐性测试矩阵；
• 下游仓库提供自己的 support matrix 和 CI 结果。

Phase 4：把 mjlab 的部署经验移到下游

unitree_rl_mjlab 中的 simulation deploy、Unitree SDK、C++ controller、实机安全流程都不应该进入 UniLab core。unitree_rl_unilab 可以后续按需要引入，但应有独立安全评审和硬件验证，不与 Manager API 迁移混在同一 PR。

6. 主要风险和对策

风险	对策
G1 task 是当前多后端覆盖最完整的真实任务，删除后 core CI 覆盖下降	先保留 G1WalkFlat；其余迁移
外部仓库复制 common terms 后漂移	公共 term 留 core 并纳入兼容政策；下游只放 Unitree 专属 term
registry 全局名称冲突	外部任务加 Unitree 前缀；保留任务不再在下游重复注册
Hydra owner YAML 漏迁某个算法	按 src/unilab/conf/*/task/<task>/ 全量清单迁移，特别是 SAC/TD3/FlashSAC
大资产污染 git 历史	使用 HF/cache/checksum，keyframe 放 task scene fragment，机器人 XML 保持纯描述
core 与下游版本脱节	pin coordinated tag，下游 CI 定期对 UniLab main 做兼容测试
支持矩阵夸大外部任务能力	core 与 downstream 分开记录 evidence grade，不能把 configured 当 tested

7. 结论

mjlab 的可借鉴点不是“上游完全无任务”，而是：上游保留少量代表性 task family，用来驱动和证明 API；production robot zoo 放到下游按厂商/机器人维护。 UniLab 现在已经具备比 mjlab 更正式的外部任务缝，因此可以更干净地执行这个划分。

我建议下一步：

1. 确认保留 G1WalkFlat + G1MotionTracking；
2. 以 v1.3.0 初始化 unitree_rl_unilab 的 package/entry point/CI；
3. 先迁移一个 locomotion 和一个 motion tracking 种子任务；
4. 验证后再批量迁移剩余 30 个 Unitree task，并在下一个 breaking release 中从 UniLab 删除；
5. 明确 unilab.envs.mdp 和 manager public API 的兼容承诺，避免下游复制分叉。

---

证据入口

• mjlab architecture / manager lifecycle:
  docs/source/architecture_overview.rst 与 src/mjlab/envs/manager_based_rl_env.py
  （8ee51fbcf806）。
• mjlab task registry 与 reference tasks:
  src/mjlab/tasks/、list_tasks() 输出 12 个 task。
• unitree downstream:
  setup.py、src/tasks/、src/assets/robots/、deploy/
  （1425b15f73bd）。
• UniLab Manager contract:
  docs/sphinx/source/adr/ADR-0006-community-manager-api-on-numpy-runtime.md、
  src/unilab/managers/、src/unilab/envs/manager_based_rl_env.py
  （e466aec746ed）。
• UniLab task inventory / boundary:
  src/unilab/tasks/migration_matrix.py、src/unilab/tasks/__init__.py、
  tests/tasks/test_package_boundary.py、tests/tasks/test_production_registry_closeout.py。
• 外部任务缝:
  src/unilab/base/registry.py、
  docs/sphinx/source/en/4-developer_guide/1-architecture/5-registry.md。