roadmap: 对照 mjlab 补齐 UniLab MBA 能力缺口（curriculum / DR / 通用 term 库），MicroDuck 作验收 example

[TATP-233]

Roadmap: 对照 mjlab 补齐 UniLab MBA 能力缺口（curriculum / DR / 通用 term 库）

目标

UniLab MBA 框架骨架移植自 mjlab v1.6.0（src/unilab/managers/ 同构，9 个 manager、term 注册、obs 管线一致），差距不在框架机制，而在 term 库覆盖面与后端消费能力。本 roadmap 对照 mjlab（本地 /home/user/ws/simulator/mjlab）系统性补齐：

1. 主线 — MBA 框架层能力缺口（与物理后端无关）：通用 curriculum 引擎、通用 locomotion reward/termination term 库、event/DR term 覆盖面、观测真实化 term。
2. 独立切片 — unilab-mjwarp 后端 DR 消费能力：contract 层已完备，缺的是后端消费 payload 的写入路径（mjlab 已在 MuJoCo Warp 上证明可行）。
3. 验收 example — MicroDuck velocity 配方：用补齐后的能力以声明式配置复现 legacy microduck_rl（mjlab 1.3.0 + rsl_rl，已实机部署）配方，检验能力是否过关。microduck 适配是顺带的验收手段，不是本 roadmap 的目标本身。

非理想执行器（DC motor / BAM 类 + action delay）体量大，单独立项，不在本 roadmap 内。

declared base branch：dev/issue-1042-manager-based-api（上层 MBA roadmap 集成分支）。理由：整个 MBA 运行时（src/unilab/managers/）与 MicroDuck 移植（#1368）均只存在于该集成分支（领先 main 231 commits，未合入 main），本 roadmap 全部切片都建立在 MBA 运行时之上。

背景与证据

移植对照基线：legacy microduck_rl（/home/user/ws/simulator/microduck_rl，microduck_velocity_env_cfg.py + tasks/mdp.py + robot/microduck_constants.py）；UniLab 侧 #1368 已完成 MicroDuck MBA 移植（PPO/SAC × mujoco/mjwarp 可训练）。逐项对照后确认的能力缺口：

MBA 框架层（主线）

• 通用 curriculum 引擎缺失：mjlab 有 reward_curriculum/termination_curriculum（stage 表按步数覆盖 live term cfg 的 weight/params）；UniLab 无任何通用 ramp 基建，仅 g1 私有 G1PenaltyCurriculum。legacy 的 5 条阶梯课表无处落地。
• 通用 locomotion term 库薄：feet_air_time（窗口计数形态）/feet_clearance/feet_swing_height/feet_slip/angular_momentum_penalty/joint_pos_limits/variable_posture/nan_detection 终止，mjlab 全部内置，UniLab 缺失或各 task 私有重复。
• event/DR term 缺口：无 apply_body_impulse/外力力矩 term（backend apply_body_force 能力在、term 缺）；push_by_setting_velocity 只支持线速度（角速度 fail-closed）；model-field 写入仅 mode=reset、min_step_count_between_reset>0 不可用；无 pseudo_inertia 物理一致惯量随机化。
• 观测真实化：obs 管线（noise 加/乘、delay lag/hold_prob/update_period、history、多 group 特权观测、NaN policy）已完整，缺通用 IMU 安装错位 obs term（legacy：每 env 恒定 ≤6° 随机轴旋转，gyro/gravity 共用四元数）。

unilab-mjwarp 后端层（独立）

• DomainRandomizationCapabilities() 全空（src/unilab/base/backend/mjwarp/backend.py:1055），mjwarp owner 被迫禁用 base_com/push_robot。mjlab 已证明路径：mjwarp Model 字段 leading dim 为 "*"，expand_model_fields tile 成 (nworld,...) 即 per-world（kernel 无需改）→ GPU 原位写 → 分级 mjwarp.set_const* 重算派生量 → 重捕获 CUDA graph（UniLab 后端已预留约定，backend.py:492-497）。工作量几乎全在 backend 层。
• mjwarp 无原生回放（record 绕道 MuJoCo 渲染），另行评估。
• 传感器面无缺口：gyro/velocimeter/framequat/subtreeangmom/contact-force 在 warp 上均工作（feat: port MicroDuck velocity task to Manager-Based API #1368 smoke 实测）。

交付边界（不做什么）

• 不动 feat: port MicroDuck velocity task to Manager-Based API #1368 已确立 contract：61D actor 观测布局、shared sensor_reward_terms 语义、home keyframe 与 action offset 链路。
• 不重复 Roadmap: Manager-Based task 层校验 helper 收敛与近义 terms 边界记录 #1373（校验 helper 收编）；不改 motrix 方向。
• 非理想执行器（BAM 类）单独立项，不在本 roadmap 的 sub-issue 里。
• per-world gravity DR 不做（opt.gravity 嵌套 struct，mjlab 也未暴露）。
• 新增通用能力沉淀到 envs/mdp/ 或 locomotion 共享层，不留在 task 私有层；S7 验收中不得新增 microduck 私有框架 hack。

切片（sub-issues，按依赖排序）

#	issue	层	依赖	规模
S1	#1397 通用 curriculum 引擎（stage 式 weight/params ramp）	MBA 框架	无	~300 LOC
S2	#1398 通用 locomotion reward/termination term 库沉淀	MBA 框架	无	~400 LOC
S3	#1399 event/DR term 补齐（body impulse / push 角速度 / fail-closed 放开）	MBA 框架	无	~300 LOC
S4	#1400 观测真实化通用 term（IMU 安装错位等）	MBA 框架	无	~150 LOC
S5	#1401 mjwarp 后端 DR 消费能力（per-world model mutation）	backend	无（contract 已备）	数百行 + effect 测试
S7	#1402 example：MicroDuck velocity 配方对齐 legacy（验收）	example	S1+S2 必需，S3/S4 按需，mjwarp 全量 DR 依赖 S5	配置为主 + 训练机时

S1–S4 纯框架、互相独立可并行；S5 完全隔离在 backend 层（框架/contract 零改动）；S7 是唯一汇聚验收点。非理想执行器为第 S6 项，单独立项。

验收标准

• 每个 sub-issue 附带：owner yaml 变更（如适用）+ 契约/单元测试 + 本地 make test-all 通过。
• S5 追加 effect 测试（mutation 后物理行为变化、world 间隔离、与 mujoco 后端统计一致性）。
• S7 追加：与 legacy 同预算对照训练曲线（reward、episode length、tracking 误差、foot_air_time）；yaw 误差以分存活 env 的 error_vel_yaw 显著下降为准；sim2real 检查表（观测链路、DR 范围与 legacy 逐项一致）。

关联

• feat: port MicroDuck velocity task to Manager-Based API #1368（MicroDuck MBA 移植，本 roadmap 的基线）
• Roadmap: Locomotion 具名 sensor terms 公共化与跨任务复用契约 #1371（locomotion 共享 reward terms 契约）
• Roadmap: Manager-Based task 层校验 helper 收敛与近义 terms 边界记录 #1373（MBA 校验 helper 收编，仓库级）
• 参照实现：mjlab /home/user/ws/simulator/mjlab；legacy /home/user/ws/simulator/microduck_rl