架构总览：外部包如何挂到 mjlab 上

这一页最重要的一句话

``mjlab-homierl`` 现在不再是框架本体，而是一个挂在上游 ``mjlab`` 上的外部任务包。

  • 上游 mjlab 负责 ManagerBasedRlEnv、manager、scene、simulation、 CLI 入口和 viewer。

  • 这个仓库负责 HOMIE 的 env cfg、H1 / 2F85 资产、HIMPPO runner，以及包内 的测试和文档。

这也是为什么很多旧路径 src/mjlab/... 在当前仓库里已经不存在了。

从 task id 到训练循环：端到端链路

  1. Task 注册

    • 当前仓库路径：src/mjlab_homierl/__init__.py

    • 使用的 API：mjlab.tasks.registry.register_mjlab_task

    • 作用：通过 mjlab.tasks entry point 注册 Mjlab-Homie-Unitree-H1 和 Mjlab-Homie-Unitree-H1-with_hands

  2. train / play 入口

    • CLI 仍然来自上游 mjlab：uv run train ...、uv run play ...

    • CLI 会读取注册好的 env cfg / rl cfg，构建 ManagerBasedRlEnv，再实例化 对应 runner

  3. 本包内的任务组装

    • base HOMIE cfg：src/mjlab_homierl/homie_env_cfg.py

    • H1 与 with_hands override：src/mjlab_homierl/env_cfgs.py

    • 任务专用 MDP term：src/mjlab_homierl/mdp/*

    • 自定义 runner：src/mjlab_homierl/rl/runner.py

  4. 运行时分工

    • 训练时使用带 actor/critic 观测的 HIMPPO

    • play 时如果 env 去掉了 critic 组，就走 HOMIE 自己的 actor-only inference path

一眼看懂的控制流

uv run train/play -> 上游 mjlab CLI
  |
  v
task registry entry -> env cfg + rl cfg + runner class
  |
  v
ManagerBasedRlEnv(cfg=...) + RslRlVecEnvWrapper
  |
  v
HomieHimOnPolicyRunner
  |
  v
policy(obs) -> action
  |
  v
上游 env step:
  ActionManager -> Simulation -> Managers -> observations / rewards / resets
  |
  v
train loop 或 viewer loop

建议从哪些文件开始读

  • 包入口与 task 注册：src/mjlab_homierl/__init__.py

  • base HOMIE task cfg：src/mjlab_homierl/homie_env_cfg.py

  • H1 task override 与 play 行为：src/mjlab_homierl/env_cfgs.py

  • 资产与手部挂载逻辑：src/mjlab_homierl/robots/unitree_h1/h1_constants.py

  • 如果你需要看框架内部：去安装后的上游 mjlab 包里看 mjlab.envs、mjlab.managers、mjlab.scene、mjlab.sim