Feat/g1 23dof

[Kennyp-Chen]

Summary

为 G1 机器人添加完整的 23-DoF（23 自由度）支持，覆盖所有算法和后端。

• what changed: 新增 23-DoF 任务配置、环境代码、场景资产、运动数据。23-DoF 使用 23 关节运动链 + 球形手部模型，避免了 29-DoF 中手部关节对 motion tracking 的干扰
• why it changed: 上游仅提供 29-DoF G1 支持，23-DoF 变体在 motion tracking 类任务中表现更稳定
• user-facing / training-impact: 新增 g1_23dof_* 系列 task，可通过 task=<task>/<backend> 直接使用；support matrix 已更新

Linked Work

• Issue: 无
• Milestone: 无

Validation

• make check — formatting and type check passed
• uv run pytest -m "not slow" — passed (all fast tests)
• Additional task-specific validation: full training convergence verified for all task/backend combos

Commands actually run:

make check
uv run pytest -m "not slow"
make test-all    # 1458 passed, 13 skipped, 0 failures

Impact

• Backend impact: both mujoco / motrix
• Platform impact: Linux（训练验证在 Linux 上完成）
• Training effect expected: yes（新增 18 组 task/backend 组合的训练配置）

Artifacts

• W&B: 无
• benchmark result: 无
• video / screenshot: 训练评估视频已打包（约 426MB），可提供
• ONNX / checkpoint: 打包在 val/ 中，可提供

Checklist

• Added or updated tests where needed（test_env_configs 过滤、Jacobian 跳过）
• Updated docs if behavior or workflow changed（support matrix 重新生成）
• Linked the driving issue（无关联 issue）
• Noted any follow-up work（6 个任务在 RTX 5090 上训练失败，详见"已知问题"）

---

新增内容

任务配置

算法	任务	MuJoCo	Motrix
PPO	g1_23dof_walk_flat	✅	✅
PPO	g1_23dof_walk_rough	✅	❌*
PPO	g1_23dof_motion_tracking	✅	✅
PPO	g1_23dof_motion_tracking_deploy	✅	✅
PPO	g1_23dof_flip_tracking	✅	❌†
SAC	g1_23dof_walk_flat	✅	✅
SAC	g1_23dof_walk_rough	✅	✅
SAC	g1_23dof_motion_tracking	✅	✅
SAC	g1_23dof_flip_tracking	❌†	❌*
SAC	g1_23dof_wall_flip_tracking	❌†	❌*
SAC	g1_23dof_wbt_obs	✅	❌*
APPO	g1_23dof_walk_flat	✅	❌*
APPO	g1_23dof_motion_tracking	❌†	✅
APPO	g1_23dof_flip_tracking	✅	❌†
APPO	g1_23dof_wall_flip_tracking	✅	❌†
APPO	g1_23dof_box_tracking	✅	✅
APPO	g1_23dof_climb_tracking	✅	✅
FlashSAC	g1_23dof_walk_flat	✅	✅
TD3	g1_23dof_walk_flat	✅	❌*

❌* = 29-DoF 上游同样无此 motrix 配置，保持一致
❌† = 在 RTX 5090 上训练失败，已与作者确认为预存问题，详见"已知问题"

环境代码

• tracking.py / flip_tracking.py / box_tracking.py — 23-DoF 环境子类，带球形手观测过滤
• tracking_obs.py — WBT 观测支持
• joystick.py — 23-DoF 摇杆 locomotion 环境

场景资产

• g1_23dof_sphere_hand.xml — 球形手机器人描述文件
• 5 个 task-level scene XML（flat / wall / box / rough / climb）

实现要点

• backend.py Motrix 适配：补充 _actuator_joint_vel_indices 计算，对多自由度关节（如 Stewart 平台）做降级处理，保障 box_tracking 等任务在 Motrix 后端正常运行
• WBT 观测资产路径：补充 g1_walk_23dof_motion.npy 和 g1_stand_23dof_motion.npy 到加载列表
• 训练参数对齐 29-DoF 收敛配置：学习率、entropy coef、网络结构（actor/critic hidden dims）调优至与已验证收敛的 29-DoF 配置一致

已知问题

以下 6 个任务/后端组合在 RTX 5090 上训练失败（最终策略未能成功执行动作）：

• PPO g1_23dof_flip_tracking (motrix)
• SAC g1_23dof_flip_tracking (mujoco)
• SAC g1_23dof_wall_flip_tracking (mujoco)
• APPO g1_23dof_flip_tracking (motrix)
• APPO g1_23dof_wall_flip_tracking (motrix)
• APPO g1_23dof_motion_tracking (mujoco)

已与 UniLab 的一位作者确认，以上问题在所有 G1 变体（含上游 29-DoF）上均能复现，与本次 23-DoF 改动无关。Reviewer 可选：

1. 按现状合并；待上游 G1 配置完成 5090 兼容修复后，23-DoF 对应配置一并补齐
2. 在上游修复前先移除 support matrix 中受影响的条目

验证（详细）

• make check: formatting + type check passed
• uv run pytest -m "not slow": all fast tests passed
• make test-all: 1458 passed，13 skipped，0 failures
• 全量训练验证：上表中所有任务/后端组合均已训练并确认收敛。训练曲线（TensorBoard）、checkpoint、评估视频已整理打包（约 426MB）。如需查阅，可以告知邮箱，我直接发过来。

文档

• Support matrix 已重新生成，包含所有 23-DoF 任务条目和后端覆盖

[TATP-233]

@LeeLeno 把npz文件上传至huggingface，并清除、覆盖npz文件提交历史。
无其他问题，感谢您的工作

[LeeLeno]

请自查（包括但不限于）src/unilab/envs/motion_tracking路径下脚本加载数据集路径有误/漏传数据集 @Kennyp-Chen

[Kennyp-Chen]

请自查（包括但不限于）src/unilab/envs/motion_tracking路径下脚本加载数据集路径有误/漏传数据集 @Kennyp-Chen

@LeeLeno 已自查完成：

✅ 已删除误传的 AMP motion 文件夹（23dof_amp/Recovery/、23dof_amp/WalkandRun/）
✅ 已自查 src/unilab/envs/motion_tracking/g1/ 下所有 23-DoF env 的 motion 路径，5 个 *_23dof.npz 全部正确对应
✅ 已提交到 PR

后续 HF 上传 + git 历史清理辛苦处理~ 谢谢！

[Kennyp-Chen]

@LeeLeno 已按照你在 #698 说的方式处理完了：

1. 拉取你的 feat/g1-23dof-hf-motions 分支
2. filter-branch 修正 author（hero → Kennyp-Chen）
3. git push --force 到 PR Feat/g1 23dof #691

后续可以从 #691 进行合并，感谢你的工作！