调研：mjlab 课程学习（Curriculum）MBA 设计 vs UniLab 现状——框架能力已补齐，剩余差距在文档与增强项

[TATP-233]

调研：mjlab 课程学习（Curriculum）MBA 设计 vs UniLab 现状

结论（TL;DR）

带着"UniLab 是否存在课程学习能力缺口"的问题，对照本地 mjlab（/home/user/ws/simulator/mjlab，v1.6.0+）与 UniLab main（v1.3.0）做了逐文件调研。结论：框架级课程学习能力 UniLab 已经具备，当前不是缺口。

• CurriculumManager 随 ADR-0006 从 mjlab v1.6.0 整体迁移（src/unilab/managers/curriculum_manager.py），生命周期语义与 mjlab 一致（reset 时 compute()，先于 reset events/DR 生效）；
• 通用 stage 式课程引擎（reward / termination / command / event 四类）已由 MBA: 通用 curriculum 引擎（stage 式 weight/params ramp terms） #1397（roadmap roadmap: 对照 mjlab 补齐 UniLab MBA 能力缺口（curriculum / DR / 通用 term 库），MicroDuck 作验收 example #1389 S1）落地，通用 term 覆盖面是 mjlab 的超集；
• UniLab 还有 mjlab 没有的性能驱动自适应课程（G1PenaltyCurriculum）和 per-env 地形课程。
• 真正的剩余差距主要是：①缺一篇面向用户的 curriculum 专题文档（mjlab 有 docs/source/curriculum.rst）；②若干双方都没有的增强方向（success-rate 驱动的通用 per-env term、curriculum 内部状态 checkpoint、learner→env 反馈通道）。

调研基线

• mjlab：本地 checkout /home/user/ws/simulator/mjlab（v1.6.0+，main 分支）
• UniLab：本仓库 main，v1.3.0
• 与 UniLab 与 mjlab v1.6.0 Manager-Based API 完整设计与功能对比 #1289（MBA 全面对比）的关系：UniLab 与 mjlab v1.6.0 Manager-Based API 完整设计与功能对比 #1289 锁定的是集成分支上的迁移基线对比，本篇聚焦 curriculum 单项、以 main 现状为准。

mjlab 的课程学习设计要点

Manager 与配置（src/mjlab/managers/curriculum_manager.py，155 行）：

• CurriculumManager(ManagerBase) + 鸭子类型的 NullCurriculumManager；CurriculumTermCfg 继承 ManagerTermBaseCfg 且不新增字段（只有 func + params）。
• _curriculum_state 仅保存每个 term 最近一次返回值，用于日志（extras["log"]["Curriculum/<term>"] → rsl_rl → wandb/tensorboard），不是持久状态。

生命周期：唯二调用点在 _reset_idx()（src/mjlab/envs/manager_based_rl_env.py:581,605）——compute(env_ids) 先于 sim.reset / scene.reset / reset-mode events 执行，因此课程对参数的修改在同一次 reset 内生效；reset(env_ids) 只负责日志与 class term 的 reset() 钩子。没有 per-step compute。

内置 term：

• 通用 staged 引擎（src/mjlab/envs/mdp/curriculums.py）：reward_curriculum / termination_curriculum，stages 表（step + weight/params）按 env.common_step_counter 全局、单向地改写目标 term 的 live cfg（经 reward_manager.get_term_cfg 解析）；构造期校验 stage 顺序与字段名，typo 直接 KeyError。
• 任务级（src/mjlab/tasks/velocity/mdp/curriculums.py）：terrain_levels_vel（per-env 性能驱动：按行走距离 promote/demote terrain_levels，改写 env_origins，同一 reset 生效）与 commands_vel（全局 staged 扩张速度指令采样范围）。
• per-env（向量化、性能驱动）与 global（步数驱动）的区分由 term 实现决定，manager 不管。

配套：play 配置手动剥离 curriculum（cfg.curriculum = {}）；专题文档 docs/source/curriculum.rst（内置 term 表 + 配方 + 自定义指南）；测试 tests/test_curriculum_manager.py、tests/test_envs_curriculums.py（275 行）、tests/test_velocity_terrain_curriculum.py；curriculum 内部状态不进 checkpoint（step counter 由 MjlabOnPolicyRunner 持久化）。

UniLab 现状（证据）

框架层（与 mjlab 同构）：

• src/unilab/managers/curriculum_manager.py:32 CurriculumManager / :22 CurriculumTermCfg / :145 NullCurriculumManager；日志值 NaN/Inf fail-closed 校验（:121-131）。
• 生命周期：src/unilab/envs/manager_based_rl_env.py:587 curriculum_manager.compute(env_ids=ids) 在 reset 事务前调用；:597-606 参与 manager reset 循环并输出 Curriculum/... extras。
• ManagerBasedRlEnvCfg.curriculum: dict[str, CurriculumTermCfg | None]（manager_based_rl_env.py:83），Hydra owner YAML 声明、可省略 _target_。

通用 staged term（#1397，比 mjlab 多两类）：src/unilab/envs/mdp/curriculums.py 的 reward_curriculum(:152) / termination_curriculum(:191) / command_curriculum(:228) / event_curriculum(:269)；构造期 fail-closed 校验（_validate_stages :83-111）。demo owner：tests/fixtures/mjlab_cartpole/conf/stage_curriculum.yaml。

性能驱动自适应（mjlab 没有）：G1PenaltyCurriculum（src/unilab/tasks/locomotion/g1/manager_terms.py:671-767）基于 EpisodeLengthTracker（src/unilab/base/curriculum.py:8-22）在 min_scale/max_scale 间缩放全部负 reward 权重；已部署于 sac/td3/flashsac/ppo 多个生产 owner（如 src/unilab/conf/sac/task/g1_walk_flat/base.yaml:212-227）。

per-env 地形课程：TerrainSpawnManager + TerrainCurriculumCfg（src/unilab/tasks/locomotion/common/terrain_spawn.py:47-243），per-env levels、按 episode 结束时的行走距离 promote/demote；RoughTerrainCurriculum term（rough_manager_terms.py:342-369）+ RoughTerrainReset event 配套；owner 示例 src/unilab/conf/ppo/task/quadruped_joystick_rough/base.yaml:121-125。

冷路径改写面：reward/termination/command/event_manager.get_term_cfg 已形式化为 protocol（src/unilab/managers/_types.py:196-220）。

训练反馈：extras info["log"]["Curriculum/..."] 被 uni_rl 消费（uni_rl/algos/rsl_rl.py:307-308、uni_rl/algos/appo/worker.py:347）。

Checkpoint：NpEnv.export_training_state 只导出 step counter（src/unilab/base/np_env.py:645-651）；staged 课程因 import_training_state 恢复计数器而 resume 一致（manager_based_rl_env.py:750-754）；更富状态可走 uni_rl.training_state.TrainingStateProvider 协议 seam。

测试：tests/envs/mdp/test_curriculums.py（463 行）、tests/managers/test_stage_curriculum_demo.py、tests/managers/test_core_managers.py:249-261。

逐项对比

维度	mjlab	UniLab	判定
Manager / Cfg schema	CurriculumManager / CurriculumTermCfg（func+params）	同名同构（ADR-0006 迁移）	平齐
生命周期	reset 时 compute，先于 reset events	相同（:587 先于 reset 事务）	平齐
per-step compute	无	无	平齐（共同增强点）
通用 staged term	reward / termination	reward / termination / command / event	UniLab 超集
per-env 地形课程	terrain_levels_vel（torch 向量化）	TerrainSpawnManager + RoughTerrainCurriculum（NumPy）	平齐
性能驱动自适应	无	G1PenaltyCurriculum（episode-length 驱动）	UniLab 领先
日志通道	extras → rsl_rl → wandb/tb	extras → uni_rl（PPO/APPO 均已消费）	平齐
learner→env 反向通道	无	无	平齐（共同增强点）
内部状态 checkpoint	无（step counter 有）	无（step counter 有；provider seam 已有）	平齐
专题用户文档	docs/source/curriculum.rst 完整一页	散见于 ADR-0006 / API reference / 迁移与地形指南	UniLab 缺口
play 剥离课程	手动 cfg.curriculum = {}	手动 override；标准化见 #1499	平齐，#1499 收敛中

剩余差距与建议

1. 补一篇 curriculum 用户文档页（唯一明确的 mjlab 对照缺口）。对齐 mjlab curriculum.rst 结构：内置 term 表、四类 staged term 的 YAML 配方（ramp penalty weight、tighten std、command ranges 扩张、event 范围扩张）、terrain 课程语义、自定义 term 指南。素材全部存在于测试与 fixture owner，工作量小。
2. 通用 success-rate 驱动的 per-env 自适应 term（双方都没有）。UniLab 已有 EpisodeLengthTracker 先例，可泛化为 success/metric tracker + 通用 adaptive term，把 G1 私有实现沉淀为 envs/mdp/ 公共能力。
3. curriculum 内部状态 checkpoint：实现 TrainingStateProvider，把 G1PenaltyCurriculum._current_scale、terrain levels 纳入 export/import，消除长训 resume 后课程状态漂移。
4. （可选、双方都没有）per-step compute() hook：仅在有明确任务需求时单独论证。
5. play 入口剥离课程的标准化已由 标准化 play variant：play_profile 扩展到 DR/noise/push/curriculum 剥离并覆盖全部 play 入口（roadmap #1252 第 3 点遗留） #1499 覆盖，无需重复立项。

关联

ADR-0006；#1289（MBA 全面对比）；#1389 / #1397（curriculum 缺口 roadmap 与落地，已关闭）；#1252（mjlab 优势借鉴 roadmap）；#1499（play variant 标准化，含 curriculum 剥离）。