Skip to main content
wuji-mjlab 是一个三层栈。本仓库持有任务与部署桥，mjlab 提供 manager-based RL 框架，MuJoCo 与 mujoco-warp 提供 GPU 批量化物理。PPO 通过内嵌在 src/wuji_rl_libs/rsl_rl/ 下的 rsl-rl 后端运行。

​
Reorient 任务

reorient 任务是手掌朝下的灵巧手对握持 cube 做完整 SO(3) 手内翻转。策略接收手掌 tag 坐标系下的目标姿态，把 cube 原地旋转到姿态与目标匹配并保持一个 hold 窗口，且全程不掉落。 任务设计——MDP terms、reward shaping 与域随机化——放在任务包里，与机器人 binding 分离。这个拆分让任务可复用，也让 Wuji Hand binding 保持精简。 mdp/ 包持有 mjlab manager 系统消费的运行时任务 terms，包括 SO(3) 目标状态机（commands.py）、手掌相对的 cage 几何与 reward 升级（cage.py），以及 action、observation、reward、termination、curriculum 的标准 term 模块。

​
域随机化

接触参数域随机化把手分成两个解剖学组：手掌加拇指柔顺区，与食指到小指。分组分别随机化（而非统一随机化），正是让仿真训练的策略迁移到真机不均匀接触行为的关键。完整随机化规格在 reorient_terms.py。

​
部署复用

部署桥原封不动地复用仿真 env。RealHandEnv 继承 mjlab 的 ManagerBasedRlEnv，因此相同的 observation 和 action manager 在真机上生效，没有并行流水线会漂移失同步。运行时管线见 Sim-to-real 部署。

​
架构约束

  • mdp/event_impl/ 下的 event 实现拆分是内部的。外部调用方只通过 mdp.events facade 消费 event。
  • ReorientEventState 是每个 event 侧运行时缓存的唯一持有者。通过 get_reorient_event_state(env) 访问它，而非直接在 env 上挂字段。
  • tooling/ 是脚本逻辑的可 import 核心。scripts/ 只持有 argparse、env-var 设置与 __main__ 胶水，所以 tooling/ 里的全部内容都能从 Python 调用，用于 sweep、测试或 notebook。
  • 公共 API 面（make_reorient_env_cfg、wuji_hand_reorient_env_cfg、mdp re-export、已注册任务 ID 与评测核心）保持稳定。内部模块可以移动，但外部调用方消费的名字不会。

​
新增任务

  1. 在 src/wuji_mjlab/tasks/<your_task>/ 下创建 env-cfg 工厂。
  2. 把所有 MDP 设计（events、rewards、terminations）放入 <your_task>_terms.py，config/<robot>/ 层保持精简 binding。
  3. 在 config/<robot>/__init__.py 中用 register_mjlab_task() 注册任务。
  4. 提交前运行一次 pixi run train --task <your_task_id> 冒烟测试。标准训练入口是 scripts/train/train_rsl_rl.py，通过 train pixi 任务暴露。