cmvr_ai_lab/source/engineai_lab/tasks/velocity/config/gen2

Gen2 分阶段训练说明

本目录维护 Gen2 从基础低速行走到 3.0 m/s 跑步的完整训练链。重构后的原则是：

• 共享的机器人语义、scene、action、observation、event 放在 common_env_cfg.py。
• 每个训练阶段只在 stages/ 的一个文件中定义该阶段新增或覆盖的 reward、command 和 curriculum。
• 每个阶段的 PPO 差异放在 agents/ 的独立文件中。
• 保留原 Gym Task ID、策略输入输出和日志根，已有 checkpoint 可以继续使用。

当前仓库没有独立的 Gen2 Stand policy。Flat-Gen2-v0 是基础低速行走任务，其中 20% 环境采样站立指令。真正的“纯站立”任务若要增加，应单独设计和验证，不能把现有 Task ID 改名或改义。

目录结构

gen2/
├── README.md
├── __init__.py                 # 触发任务注册
├── registry.py                 # Task ID -> EnvCfg/PPO 入口
├── common_env_cfg.py           # body 语义、scene、action、observation、event、Play helper
├── stages/
│   ├── walk.py                 # 阶段 1：基础低速行走
│   ├── speed.py                # 阶段 2：平地速度巩固
│   ├── natural.py              # 阶段 3：自然摆臂
│   ├── fast.py                 # 阶段 4：0.8 -> 1.6 m/s
│   ├── sprint.py               # 阶段 5：1.6 -> 3.0 m/s
│   └── natural_run.py          # 阶段 6：高速自然跑姿
├── agents/
│   ├── walk_ppo_cfg.py
│   ├── speed_ppo_cfg.py
│   ├── natural_ppo_cfg.py
│   ├── fast_ppo_cfg.py
│   ├── sprint_ppo_cfg.py
│   └── natural_run_ppo_cfg.py
├── flat_env_cfg.py             # 旧导入路径兼容层
├── sprint_env_cfg.py           # 旧导入路径兼容层
└── natural_run_env_cfg.py      # 旧导入路径兼容层

阶段依赖保持单向：

walk -> speed -> natural -> fast -> sprint -> natural_run

后面的阶段只继承前一阶段，不允许反向导入。这样查看某个文件时，可以直接看到“本阶段相对上一阶段改了什么”。

阶段总表

阶段	训练 Task	Play Task	主要目标	默认前向速度	PPO 迭代
1 基础低速行走	Flat-Gen2-v0	Flat-Gen2-Play-v0	站立采样、低速交替踏步、基础地形	-0.2~0.4 m/s	1500
2 平地速度巩固	Flat-Gen2-Speed-v0	Flat-Gen2-Speed-Play-v0	plane、无 push、降低脚滑和落脚冲击	0.2~0.6 m/s	400
3 自然摆臂	Flat-Gen2-Natural-v0	Flat-Gen2-Natural-Play-v0	对侧摆臂、腕部稳定	继承阶段 2	300
4 Fast	Flat-Gen2-Fast-v0	Flat-Gen2-Fast-Play-v0	课程提升至 1.6 m/s	0.8 -> 1.6 m/s	750
5 Sprint	Flat-Gen2-Sprint-v0	Flat-Gen2-Sprint-Play-v0	建立跑步腾空与 3.0 m/s 能力	1.6 -> 3.0 m/s	2250
6 NaturalRun	Flat-Gen2-NaturalRun-v0	Flat-Gen2-NaturalRun-Play-v0	高速肩、肘、前臂协调	2.0 -> 3.0 m/s	1500

所有阶段故意共用：

• experiment_name = velocity_flat_terrain_gen2
• 28 个 action，关节顺序由 GEN2_DFS_JOINT_NAMES 固定
• 15 帧 observation history
• actor/critic 隐藏层 [512, 256, 128]

这些是 checkpoint 兼容契约。修改 observation 顺序、history、action 顺序或网络维度，会导致旧 checkpoint 不能加载。

Natural 及后续阶段把腕部 J5/J6/J7 action scale 从 0.15 缩小为 0.06，所以必须使用对应阶段的 Play Task。

三种加载方式

1. 从头训练阶段 1

cd /home/xtkuang/Projects/cmvr/RL/cmvr_ai_lab

/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python scripts/train.py \
  --task Flat-Gen2-v0 \
  --num_envs 4096 \
  --seed 42 \
  --max_iterations 1500 \
  --run_name gen2_walk_v0 \
  --device cuda:0 \
  --rl_device cuda:0 \
  --headless

2. 同一 Task 中断后继续：resume

resume 会恢复 actor、critic、optimizer、iteration 和 curriculum 计数。Task ID 必须和 checkpoint 中记录的一致。

/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python scripts/train.py \
  --task Flat-Gen2-Sprint-v0 \
  --num_envs 4096 \
  --max_iterations 200 \
  --resume True \
  --load_mode resume \
  --load_run '2026-07-13_15-39-32_gen2_sprint_3p0_curriculum_v1' \
  --checkpoint model_2249.pt \
  --run_name gen2_sprint_resume \
  --device cuda:0 \
  --rl_device cuda:0 \
  --headless

3. 从上一阶段迁移到下一阶段：finetune

finetune 只加载 actor/critic 权重，使用新阶段的 optimizer 和 curriculum。跨 Task 迁移必须使用它，不能使用完整 resume。

下面以 Sprint -> NaturalRun 为例：

/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python scripts/train.py \
  --task Flat-Gen2-NaturalRun-v0 \
  --num_envs 4096 \
  --seed 42 \
  --max_iterations 1500 \
  --resume True \
  --load_mode finetune \
  --load_run '2026-07-13_15-39-32_gen2_sprint_3p0_curriculum_v1' \
  --checkpoint model_2249.pt \
  --run_name gen2_natural_run_v1 \
  --device cuda:0 \
  --rl_device cuda:0 \
  --headless

推荐迁移顺序：

Flat-Gen2-v0
  -> Flat-Gen2-Speed-v0
  -> Flat-Gen2-Natural-v0
  -> Flat-Gen2-Fast-v0
  -> Flat-Gen2-Sprint-v0
  -> Flat-Gen2-NaturalRun-v0

每一步都从上一阶段视觉和固定速度测试最好的 checkpoint 开始，不要只按最后一次迭代选择。

固定指令回放

Sprint 3.0 m/s 示例：

/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python scripts/play.py \
  --task Flat-Gen2-Sprint-Play-v0 \
  --load_run '2026-07-13_15-39-32_gen2_sprint_3p0_curriculum_v1' \
  --checkpoint model_2249.pt \
  --num_envs 1 \
  --command_source fixed \
  --command_mode ramp \
  --linear_accel 0.6 \
  --vx 3.0 \
  --vy 0.0 \
  --wz 0.0 \
  --max_steps 4000 \
  --device cuda:0 \
  --rl_device cuda:0

回放检查：

1. pelvis 的真实前向速度是否接近命令，而不是只靠胸/腰扭动。
2. 左右脚是否交替，接触脚是否明显滑动。
3. Natural 之后是否为对侧摆臂，腕部是否高频乱动。
4. Sprint 是否出现合理腾空，而不是单脚连续 pogo。
5. 固定条件下比较 checkpoint，不用随机指令画面下结论。

修改某个阶段时

1. 只在对应 stages/<stage>.py 修改该阶段差异。
2. 共享 body 名称、观测、动作或 reset 才修改 common_env_cfg.py。
3. 修改 action scale 时同步验证该阶段 Play 配置。
4. 保持 super().__post_init__() 先执行，再写本阶段覆盖。
5. 不要顺手修改前一阶段已经验证的参数；新增能力应在后续阶段建立。
6. 训练后以该 run 中的 params/env.yaml 和 params/agent.yaml 作为事实快照。

Fast 中有一个刻意保留的历史行为：Gen2FastRewards 声明速度跟踪权重为 3.0，但继承的 Speed __post_init__ 最终将它设为 2.5；现有 Fast checkpoint 使用的就是 2.5。若要修正，应作为单独的训练行为改动，不应混在目录重构中。

快速检查

# Python 语法
/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python -m compileall \
  source/engineai_lab/tasks/velocity/config/gen2

# Gen2 URDF、惯量、关节限位和碰撞体
/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python \
  scripts/gen2_check_rl_readiness.py

# 不启动 Isaac Sim 的目录与 mesh 引用测试
/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python -m unittest \
  tests.test_gen2_structure

# 启动 Isaac Sim，验证全部 Task 注册和 Train/Play action 契约
/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/python \
  scripts/gen2_validate_registry.py

# 查看 TensorBoard
/home/xtkuang/App/anaconda3/envs/engineai_lab/bin/tensorboard \
  --logdir logs/rsl_rl/velocity_flat_terrain_gen2 \
  --port 6006

资产目录和生成方式见 Gen2 资产 README。完整的人形机器人接入方法见仓库根目录的 docs/humanoid_locomotion_onboarding_guide.md。