Code Walkthrough（面向科研开发，上手 + 深入）

这套文档的目标是：让第一次阅读本项目的同学在 1-2 小时 内建立可靠的心智模型，并能在现有 Unitree G1 任务（velocity / tracking）的基础上，快速开发自己的 RL 任务。

你会在这里学到什么

• 架构总览：ManagerBasedRlEnv = Scene + Simulation + Managers 的数据流与控制流。

• Manager-base API 设计：设计哲学、扩展方法以及 奖励 (Reward) 与终止 (Termination) 的配置。

• 任务开发路径：如何像写 Isaac Lab manager-based task 一样写 mjlab task（但用 dict cfg）。

• g1/h1 任务解剖：tasks/velocity、tasks/tracking 与 tasks/homie 的 cfg/MDP/训练入口拆解与改造建议。

阅读顺序建议

第一次阅读：按顺序看（总览 → 环境生命周期 → managers/terms → 任务实例 → 自己动手）。

已经熟 Isaac Lab：直接跳到 managers_and_terms 与两个任务章节对照代码即可。

章节目录

• 架构总览：一张图看懂 mjlab
  • 这张图对应的“最重要一句话”
  • 从 task id 到训练循环：端到端链路
  • 一眼看懂的“数据流/控制流”
  • 建议从哪些文件开始读
• 快速上手：最短开发闭环（训练 / Play / 改任务）
  • 0) 先把能跑的 baseline 跑通
  • 1) 用 dummy agent 做“MDP 体检”（强烈建议）
  • 2) 最常见的修改点在哪里（velocity / tracking / homie）
  • 3) 任务 cfg 是怎么被 “cli 覆盖” 的？
• 代码地图：你应该去哪里改东西？
  • 核心目录一览
  • 任务的“标准骨架”长什么样？
• 重点类一：ManagerBasedRlEnv（环境生命周期与数据流）
  • 配置入口：ManagerBasedRlEnvCfg
  • 环境构建：Scene + Simulation + Managers
  • Manager 加载顺序（为什么重要）
  • step()：action → physics → done/reward → reset → obs
  • reset 的顺序敏感（为什么 extras/log 很重要）
  • finite horizon vs infinite horizon（terminated vs truncated）
• 重点类二：Managers + Terms（isaaclab-like 的核心抽象）
  • 三层抽象：TermCfg → Term → Manager
  • 核心机制：SceneEntityCfg 的“延迟绑定” + 类 term 自动实例化
  • 各个 Manager 的“要点速记”
  • 写一个新 term 的“最小模板”
• 奖励函数与终止条件 (Rewards and Terminations)
  • 奖励函数 (Reward Function)
  • 终止条件 (Termination Conditions)
• 实例一：Velocity Tracking（Unitree G1）
  • 任务骨架：make_velocity_env_cfg（base cfg）
  • 理解 velocity 任务最重要的 3 个 term
  • g1 覆盖：unitree_g1_*_env_cfg（robot-specific）
  • Task 注册：register_mjlab_task
  • 你要做一个新 locomotion 任务：最少改哪几处？
• 实例二：Motion Tracking / Imitation（Unitree G1）
  • 任务骨架：make_tracking_env_cfg（base cfg）
  • MotionCommand：tracking 的“发动机”
  • Rewards & Terminations：高精度的影子模仿
  • 训练入口的关键逻辑：motion_file 如何注入？
  • g1 覆盖：unitree_g1_flat_tracking_env_cfg
  • Task 注册
  • 你要改 tracking：通常改哪里？
• 实例三：Homie —— 混合运动与干扰（Unitree H1）
  • 任务骨架：make_homie_env_cfg（base cfg）
  • Env Grouping：一套 vec env 并行训练三种“子任务”
  • H1 覆盖：unitree_h1_homie_env_cfg
  • 核心特性：UpperBodyPoseAction（policy-free，上身 0 维 action）
  • 课程学习：让干扰逐渐增强
  • Rewards & Terminations：混合任务的平衡艺术
  • H1 机器人覆盖与 H1 Constants
  • with_hands：带夹爪版本（policy-free）
  • 总结：为什么参考 Homie？
• 如何新增一个 G1 RL 任务（从 0 到可训练）
  • 关键设计：tasks 是“导入即注册”的
  • 目录骨架（推荐）
  • Step-by-step：从 base cfg 写到能跑
  • 常见踩坑清单（按出现频率排序）
• 调试与性能：让你“稳”且“快”
  • 第一优先级：先确保 MDP 正确
  • 第二优先级：NaN/Inf 与物理不稳定
  • 第三优先级：domain randomization 的正确姿势
  • 性能心法：让训练跑得快
  • 可观测性：你应该把什么看成“单步的 truth source”