基于 mjlab 的 Unitree G1 humanoid motion imitation 研究代码库。
这个仓库的目标不是只复现某一篇论文，而是把 DeepMimic → AMP → ASE → BeyondMimic 这条技术路线，整理到一套统一、可比较、可继续扩展的代码结构里。对于首次 commit，它已经具备了一个清晰的研究底座该有的三个核心能力：
- 统一的 motion 数据表示与转换链路
- 统一的 env / agent / model 构建方式
- 四条算法链路的最小训练与评估闭环
可以把它理解成一个 humanoid motion imitation 的研究底座：
- 研究问题统一：都在回答“如何让 humanoid 学会参考动作，并进一步产生自然、可控、可迁移的行为”
- 代码抽象统一：共享
motions/、envs/、learning/、utils/四层结构 - 实验入口统一：通过
scripts/train_agent.py、scripts/eval_agent.py、learning/builders.py管理不同算法 - 算法差异显式化：不同方法的差异尽量只保留在任务设计、观测构成、loss 结构这几层
所以它更接近“研究代码骨架 + 演进路线整理”，而不是“某单一 benchmark 的最终成品”。
DeepMimic 代表了最经典的动作模仿思路：把参考运动作为逐帧目标，用 PPO 直接优化对参考姿态的跟踪。
它的优点是直接、清晰、容易落地；缺点也同样明显：
- 强依赖手工设计的 tracking reward
- 往往要求参考帧和当前状态比较强的对齐关系
- 更像“精确跟随参考”，而不是“学会自然运动先验”
AMP 往前走了一步：不再让策略去死盯每一帧参考轨迹，而是通过对抗判别器学习“像不像自然参考运动”的风格先验。
这样做的核心变化是：
- 从显式 tracking reward 转向 style reward
- 从“跟参考帧一一对齐”转向“整体运动分布自然”
这让策略更容易生成自然动作，也降低了对逐帧对齐的依赖。
ASE 在 AMP 的基础上进一步引入 latent skill 表示。它关心的不只是“动作像不像”，还关心“动作风格能不能被编码、组合、切换”。
这里的关键变化是：
- policy 输入扩展为
[obs; z] z由 encoder / prior 支持训练和推理- skill space 变成后续任务控制与组合的接口
这使得 motion imitation 不再只是一种 tracking 技术，而开始具备 skill library 的味道。
BeyondMimic 可以看作对 DeepMimic 系路线的现代化重构：仍然保留“参考动作驱动”的思想，但不再停留在传统的多项 tracking reward 拼接上。
在这个仓库里，BeyondMimic 的角色是：
- 作为 DeepMimic 之后的任务设计升级版
- 强调 reference-conditioned policy 的表达方式
- 让 imitation 更接近“受参考约束的物理可行行为生成”
四个算法共享同一套底层基础设施：
- motion 数据层：统一
.npz格式，用户自行将原始数据与转换后的 motion 文件放到data/ - env 层：基于
mjlab的 manager-based RL env，MDP 组件解耦 - learning 层：
PPOAgent → AMPAgent → ASEAgent与ActorCritic → AMPModel → ASEModel的继承演进 - 脚本层：统一走 debug / train / eval 三个入口
- 实验产物层：统一写入
logs/
这意味着你可以把这个仓库视作一个“可横向比较算法、可纵向继续演化系统”的基础框架。
算法间最核心的差异可以概括为：
| 维度 | DeepMimic | BeyondMimic | AMP | ASE |
|---|---|---|---|---|
| 主要驱动 | tracking reward | reference-conditioned imitation | adversarial motion prior | adversarial prior + skill latent |
| policy 输入 | obs |
obs + ref_frame |
obs |
obs + z |
| learning target | PPO | PPO | PPO + discriminator | PPO + discriminator + encoder/prior |
HumanoidMimic/
configs/ 实验配置
data/ 用户自行放置原始数据与转换后的 motion 文件
envs/ 环境、MDP 配置和 runtime 桥接
learning/ agents / models / infra / builders
motions/ motion 数据定义、采样与特征构建
robots/ G1 常量与机器人相关配置
scripts/ debug / train / eval / csv_to_npz 入口
tests/ 当前 smoke tests
utils/ configs / checkpoints / run_logs / env_api
pyproject.toml 项目元信息与依赖
uv.lock 依赖锁文件
README.md
更细一点的职责划分：
motions/：统一的 motion 数据表示、采样与判别器特征envs/：DeepMimic / BeyondMimic / AMP / ASE 对应的 env 配置与 runtime 适配learning/agents/：训练逻辑learning/models/：网络结构learning/builders.py：统一实验构建入口utils/checkpoints.py：run 目录与 checkpoint 路径管理utils/run_logs.py：JSONL / YAML 轻量落盘tests/：当前最小 smoke tests
项目当前通过 uv 管理依赖，pyproject.toml 已配置好基础依赖与开发依赖。
uv sync如果你打算跑测试或做开发：
uv sync --extra dev仓库只跟踪 data/ 目录结构，不跟踪具体数据文件。你需要自行把原始 mocap 数据和转换后的 motion 文件放到 data/。
例如，可以把原始 CSV 放到：
data/your_motion.csv
再运行转换脚本生成统一 .npz：
.venv/bin/python scripts/csv_to_npz.py \
--input data/your_motion.csv \
--output data/your_motion.npz用于确认 env / model / agent 的构建链是通的。请把下面的 data/your_motion.npz 替换成你自己放到 data/ 目录下的 motion 文件：
.venv/bin/python scripts/debug_agent.py --algo deepmimic --motion-file data/your_motion.npz
.venv/bin/python scripts/debug_agent.py --algo amp --motion-file data/your_motion.npz
.venv/bin/python scripts/debug_agent.py --algo ase --motion-file data/your_motion.npz.venv/bin/python scripts/train_agent.py --config configs/experiments/deepmimic_g1.yaml --output-dir logs
.venv/bin/python scripts/train_agent.py --config configs/experiments/beyondmimic_g1.yaml --output-dir logs
.venv/bin/python scripts/train_agent.py --config configs/experiments/amp_g1.yaml --output-dir logs
.venv/bin/python scripts/train_agent.py --config configs/experiments/ase_g1.yaml --output-dir logs保存 checkpoint：
.venv/bin/python scripts/train_agent.py \
--config configs/experiments/amp_g1.yaml \
--output-dir logs \
--save-final \
--save-every 100训练产物默认写入：
logs/<algo>_<timestamp>/
builder_config.yaml
run_summary.yaml
metrics.jsonl
train_result.yaml
checkpoint_final.pt
checkpoint_<N>.pt
.venv/bin/python scripts/eval_agent.py \
--config configs/experiments/amp_g1.yaml \
--steps 200
.venv/bin/python scripts/eval_agent.py \
--config configs/experiments/amp_g1.yaml \
--checkpoint logs/amp_20260309_003021/checkpoint_final.pt \
--steps 200评估产物默认写入：
logs/eval/<algo>_<timestamp>/
eval_metrics.jsonl
eval_summary.yaml
当前仓库里已经有最小 smoke tests：
tests/test_csv_to_npz_smoke.pytests/test_g1_env_cfgs_smoke.pytests/test_runtime_smoke.py
运行方式：
.venv/bin/python -m pytest tests -q目前已经具备：
- DeepMimic / BeyondMimic / AMP / ASE 四条链路的最小训练闭环
- checkpoint 保存 / 加载
- run 目录与 YAML / JSONL 日志落盘
- 从 motion 数据到 env / learning / scripts 的统一组织结构
仍然明确留在后续工作的内容包括：
- 长时训练稳定性验证
- 视频录制 / 可视化导出
- TensorBoard / WandB 集成
- 更系统的 benchmark 与实验报告
如果你准备做第一次 commit / push，建议工作树保持“代码 + 配置 + 文档”干净，不带历史运行产物。当前默认日志目录已经是 logs/，因此历史遗留的 outputs/ 可以删除，不会影响当前脚本行为。
- TensorBoard / WandB 集成