探索wbt任务合理的迁入UniLab的全链路

Work type

research / feature

Area

G1

Problem

UniLab 当前的 G1MotionTracking 任务（src/unilab/envs/motion_tracking/g1/）本质是 BeyondMimic / HybridRobotics whole_body_tracking 风格的 WBT 实现：

• NPZ 数据 schema：joint_pos / joint_vel / body_pos_w / body_quat_w / body_lin_vel_w / body_ang_vel_w / fps，body 索引按 MuJoCo body-id 排布（见 src/unilab/envs/motion_tracking/g1/motion_loader.py）
• motion 来源主要是 BeyondMimic（dance1_subject2_part, gangnam_style）+ LAFAN/Seed 经 *_from_csv.npz 转换得到，注释里写在 src/unilab/envs/motion_tracking/g1/tracking.py
• 已实现：adaptive/uniform/start/clip_start/mixed 采样、anchor body yaw-only delta、RSI、anchor pos_z/ori 终止、EE z 终止、exp reward 家族、Hydra YAML × {mujoco, motrix} owner

mjlab 最近也独立做了一份 BeyondMimic 的 re-implementation，位于其仓库 src/mjlab/tasks/tracking/，基于 HybridRobotics/whole_body_tracking commit f8e20c88...。两边在 motion schema、anchor 数学、adaptive 采样算法、reward 家族上是同源的，但 mjlab 在工程组件上引入了一些 UniLab 当前没有的部分。我们需要做一次正式调研，明确哪些组件值得吸收、迁移成本多少、与 UniLab 现有 contract 是否兼容。

Deliverable

Phase 1 是一份调研报告 + 可落地的迁移清单（不写功能代码）。

调研报告（落在 docs/ 或本 issue comment 下）需要回答以下问题，并给出每一项的迁移难度（S/M/L）+ 建议（迁移 / 不迁移 / 等需求）：

1. 架构对比：mjlab 的 Manager-based ManagerBasedRlEnvCfg（src/mjlab/tasks/tracking/tracking_env_cfg.py）vs UniLab 的 dataclass cfg + registry.env/registry.envcfg + NpEnvState contract。结论需要明确：Manager 架构不应整体迁移（与 CLAUDE.md 中 env contract 条款冲突），只能借鉴。
2. NPZ schema 兼容性：确认两边 schema 完全一致（fps/joint_pos/joint_vel/body_pos_w/body_quat_w/body_lin_vel_w/body_ang_vel_w），并确认 mjlab 的 MuJoCo body-id 排布与 UniLab body_indices 假设一致 → 若一致，motion 文件可零成本互通。
3. csv_to_npz.py 迁移评估：mjlab 的 src/mjlab/scripts/csv_to_npz.py 用 MuJoCo Warp 走一遍 FK 来产 NPZ。评估：是否能替代 UniLab 当前 *_from_csv.npz 流水线？是否需要在 UniLab 加一个 scripts/preprocess/csv_to_motion_npz.py？
4. 评估流水线：mjlab tasks/tracking/scripts/evaluate.py + mdp/metrics.py（MPKPE / R-MPKPE / joint_vel_error / EE pos & ori error / success_rate）是 UniLab 当前缺失的。评估迁移成本，并指出落到 scripts/eval_motion_tracking.py 的可行性。
5. Self-collision penalty：mjlab 用 ContactSensor（subtree pelvis vs subtree pelvis）做 self_collision_cost，比 UniLab 现在的 undesired_contact_z_threshold 启发式更严谨。评估在 UniLab 端做接入需要在 SimBackend 抽象接口加什么（参照 CLAUDE.md 中"backend isolation"条款）。
6. No-state-estimation 变体：mjlab 提供 Mjlab-Tracking-Flat-Unitree-G1-No-State-Estimation（actor obs 去掉 motion_anchor_pos_b + base_lin_vel），用于无状态估计的部署侧。评估在 UniLab 加一个 G1MotionTrackingNoStateEst 注册项（或者 owner YAML 变体）的成本。
7. ONNX 导出 + motion buffer：mjlab MotionTrackingOnPolicyRunner 把 motion 数据作为 register_buffer 一起塞进 ONNX，下游部署直接读 time_step 取参考。评估 UniLab scripts/deploy/export_motion_bin.py 是否已经覆盖此能力，差异在哪里。
8. Viewer ghost + scrubber：mjlab 提供 ghost mesh + Viser GUI scrubber。评估是否值得移植到 src/unilab/visualization/（这部分偏 nice-to-have）。
9. Crawl-slope tracking：mjlab 的 unitree_g1_crawl_slope_tracking_env_cfg + src/mjlab/tasks/tracking/config/g1/crawl_slope.py 在场景里替换 terrain entity；UniLab 已有 procedural terrain（见 src/unilab/terrains/）。评估"tracking + procedural terrain"组合任务是否值得作为后续 follow-up issue。
10. 不可迁移 / 与 UniLab 不变量冲突的部分清单：明确写出，避免后续 PR 反复踩雷。例如：Manager-based env、mdp.builtin_sensor 字符串选择器、Entity scene 抽象、subtract_frame_transforms torch 版本（UniLab 走 NumPy 热路径）。

最终交付物（Phase 1）：

• 调研报告（markdown，建议 1500–2500 字），落在 docs/sphinx/source/zh_CN/4-developer_guide/ 下，或作为 issue comment + 上传 PR。报告里每一项都要包含：mjlab 当前怎么做、UniLab 当前怎么做、差异、迁移成本（S/M/L）、是否建议迁移、迁移落到 UniLab 哪个 owner 层
• 迁移清单（issue 列表）：把"建议迁移"的项各拆成一个独立 follow-up issue（标题 + 一句话 scope），不在本 issue 实现
• motion 文件互通性的最小验证：跑一遍 tests/envs/test_motion_loader.py 风格的脚本，把 mjlab 转出来的一个 NPZ 喂给 UniLab MotionLoader 走一段 episode，确认 body_indices 排布无 misalignment（这一步是 evidence-only 原则下唯一必须跑的代码）

Non-goals for Phase 1：

• 不实现 mjlab → UniLab 的任何功能代码迁移（评估指标、self-collision sensor、no-state-est variant、ONNX motion buffer 全部留到 follow-up）
• 不引入 Manager-based 架构
• 不动现有 G1MotionTracking{,Deploy,SAC} 任务的训练动力学

Definition of done

• 调研报告完成并合入 main（路径在 PR 里明确）
• motion 文件互通最小验证脚本/测试可复现，写在报告里
• 至少为以下 3 项分别开出 follow-up issue（如果调研结论判定值得做）：
  • 评估流水线移植（MPKPE/R-MPKPE/EE error/success_rate）
  • csv_to_npz 统一预处理脚本
  • G1MotionTrackingNoStateEst 变体（actor obs 裁剪）
• 报告里明确标注哪些 mjlab 组件不迁移以及原因（trace 到 CLAUDE.md 对应条款）

Dependencies and blockers

• 参考实现：mjlab 仓库 src/mjlab/tasks/tracking/
• 上游论文 / 仓库：BeyondMimic（https://beyondmimic.github.io/）+ HybridRobotics/whole_body_tracking @ commit f8e20c88
• UniLab 端入口：src/unilab/envs/motion_tracking/g1/tracking.py、src/unilab/envs/motion_tracking/g1/motion_loader.py、conf/ppo/task/g1_motion_tracking/
• 相关 PR/issue：与 G1 WBT / motion tracking 已有的工作流（如 flip / wall_flip / box tracking）紧密相关，调研报告需要顺带说明这些子任务是否能复用 mjlab 的组件

Proposed owner

（待指派）

Validation plan

• 阅读 + 报告：把 mjlab tasks/tracking/{tracking_env_cfg.py, mdp/*, config/g1/*, rl/runner.py, scripts/evaluate.py} 与 UniLab envs/motion_tracking/g1/* 对照过一遍
• 唯一代码验证：写一个一次性 smoke 脚本（不进 tests/，留在报告里），跑 mjlab csv_to_npz 产出的 NPZ → UniLab MotionLoader → G1MotionTrackingEnv.reset()，确认无 shape/index error，初始 anchor pos 在 motion 第一帧附近（容差 1e-3）
• 报告评审：调研报告需要至少一位 G1 / motion_tracking 方向的 maintainer review，确认每一项的 S/M/L 判断和迁移建议；评审通过后再拆 follow-up issue