动作追踪¶
G1 动作追踪任务位于 src/unilab/tasks/motion_tracking/ 下，并通过
src/unilab/conf/ppo/、src/unilab/conf/appo/ 以及选定的 off-policy 路径中的 task owner YAML 选择。
Motion 资产已迁移到 Hugging Face。
.npz片段不再随仓库分发，首次使用时由MotionLoader（src/unilab/tasks/motion_tracking/common/motion_loader.py）按需从 unilabsim/unilab-motions 下载，下载逻辑在src/unilab/assets/hub.py（_HF_MOTIONS_REPO_ID）。uv sync已自动安装所需的huggingface_hub依赖。
Task Owners¶
每个 task 都在 Hydra task owner YAML 中定义默认 motion 片段。Hydra 是唯一配置入口；
选中的 owner 会被物化为共享的 ManagerBasedRlEnvCfg，再由 NumPy Manager-Based
runtime 执行。
CLI Task |
Registered Env |
默认 motion |
Owner Evidence |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
23-DoF task owner 目录选择对应的 23-DoF 场景、motion、entity 与 action 声明。 profile 差异全部留在 Hydra 中。G1 identity 使用共享 manager factory；X2 只在委托给 该 factory 前增加一层冷路径 mesh resolver。
PPO 与 APPO¶
PPO owner 迭代预算（--sim mujoco owner YAML）：g1_motion_tracking 为
algo.max_iterations=15000；g1_flip_tracking 和 g1_wall_flip_tracking 为
20000；x2_wall_flip_tracking 为 9500。（g1_flip_tracking 的 Motrix owner
YAML 将其提到 30000。）
uv run train --algo ppo --task g1_motion_tracking --sim mujoco
uv run train --algo ppo --task g1_flip_tracking --sim mujoco
uv run train --algo ppo --task g1_wall_flip_tracking --sim mujoco
uv run train --algo ppo --task x2_wall_flip_tracking --sim mujoco
uv run train --algo ppo --task g1_motion_tracking --sim motrix
uv run train --algo appo --task g1_motion_tracking --sim mujoco training.no_play=true
uv run train --algo ppo --task g1_motion_tracking --sim mujoco \
algo.num_envs=128 algo.max_iterations=5 training.no_play=true
uv run eval --algo ppo --task g1_motion_tracking --sim mujoco --load-run -1
uv run eval --algo ppo --task g1_motion_tracking --sim mujoco --load-run -1 \
training.cam_tracking=true training.cam_tracking_env_idx=0
SAC WBT 路径¶
uv run train --algo sac --task g1_motion_tracking --sim mujoco training.use_amp=true
uv run train --algo sac --task g1_wbt_obs --sim mujoco training.use_amp=true
g1_wbt_obs owner 是与部署对齐的 off-policy 观测配置。actor 的 command 与 anchor
orientation term 保持单步，base_ang_vel、joint_pos、joint_vel 和 actions term
分别声明 history_length: 5。这些逐项历史由 ObservationManager 维护并展开；actor
使用配置中的 encoder-biased joint-position term，critic 则保留 clean term。逐项最旧
优先顺序由 tests/scripts/test_obs_alignment_g1_wbt.py 守护；硬件侧契约见仿真到真机
部署指南。当 Motrix sim2sim 回放需要引用其他日志根目录下的 checkpoint 时，用
uv run eval 透传绝对路径：
uv run eval --algo sac --task g1_motion_tracking --sim motrix \
algo.load_run=/abs/path/to/logs/fast_sac/G1MotionTrackingSAC/2026-04-23_14-06-57_mujoco
动作文件¶
动作 NPZ 文件通过 env.commands.motion.params.motion_file 选择，既可传单个路径，
也可传路径列表。标准片段必须包含七个 key：
fps、joint_pos、joint_vel、body_pos_w、body_quat_w、body_lin_vel_w、
body_ang_vel_w（在 common/motion_loader.py 中校验）：
env:
commands:
motion:
params:
motion_file:
- motions/g1/dance1_subject2_part.npz
- motions/g1/walk1_subject5_from_csv.npz
转换与检查辅助工具在 scripts/motion/ 中：
uv run scripts/motion/csv_to_npz.py \
--input_file src/unilab/assets/motions/g1/dance1_subject2.csv \
--output_file src/unilab/assets/motions/g1/dance1_subject2_from_csv.npz \
--input_fps 30 --output_fps 50
uv run scripts/motion/csv_to_npz.py \
--input_file src/unilab/assets/motions/g1/dance1_subject2.csv \
--output_file src/unilab/assets/motions/g1/dance1_subject2_clip.npz \
--input_fps 30 --output_fps 50 --start_time 4.0 --end_time 9.0
uv run scripts/motion/replay_npz.py \
--npz_file src/unilab/assets/motions/g1/dance1_subject2_part.npz --loop
uv run scripts/motion/replay_npz.py \
--npz_file src/unilab/assets/motions/g1/dance1_subject2_part.npz --speed 0.5
如果 MuJoCo replay 里 body 姿态明显错位，优先检查：NPZ 是否包含标准 7 个 key、
fps 是否匹配控制频率、body layout 是否需要 remap、joint 顺序是否匹配当前 G1 模型。
更详细的动作转换说明见 scripts/motion/README.md。
SAC WBT on crawl-slope 场景¶
在斜坡地形上跑 g1_motion_tracking，需要同时切换 motion 片段和 MuJoCo 场景文件，
并固定 episode 长度、关闭 reset 随机化，以复用 clip 精确初始状态：
CUDA_VISIBLE_DEVICES=1 uv run train --algo sac --task g1_motion_tracking --sim mujoco \
training.use_amp=true algo.seed=1 \
env.commands.motion.params.motion_file=motions/g1/motion_crawl_slope_uni.npz \
env.scene.model_file=src/unilab/assets/robots/g1/scene_crawl_slope.xml \
env.commands.motion.params.sampling_mode=start \
env.commands.motion.params.truncate_on_clip_end=true \
env.max_episode_seconds=20.0 \
'env.commands.motion.params.pose_range={x:[0,0],y:[0,0],z:[0,0],roll:[0,0],pitch:[0,0],yaw:[0,0]}' \
'env.commands.motion.params.velocity_range={x:[0,0],y:[0,0],z:[0,0],roll:[0,0],pitch:[0,0],yaw:[0,0]}' \
'env.commands.motion.params.joint_position_range=[0,0]'
关键覆写：env.commands.motion.params.motion_file 切换爬坡动作；
env.scene.model_file 切换斜坡场景（scene_crawl_slope.xml 在
src/unilab/assets/robots/g1/ 下）；sampling_mode=start 加
truncate_on_clip_end=true 从 clip 起点出发并在结尾截断；command reset 范围全置零
即可复用 motion 的精确初始状态。
交互式调试¶
常规 checkpoint 回放用 uv run eval。需要 target body 或 reward debug overlay 时，
src/unilab/scripts/play_interactive.py 是使用 MuJoCo viewer 的低层调试入口，当前没有暴露为
统一 uv run eval 参数。