AGILE 复现经验：视频诊断、评测边界与资产管理
AGILE 复现的关键是把任务注册、场景加载、策略输入输出和评测指标逐项接通。本章围绕 T1 速度跟踪、G1 速度与高度控制、G1 抓取放置场景，说明如何诊断视频不动、选择权重文件，以及在保留可复现性的同时清理模型副本。安装命令和完整视频见主教程。
1. 先确定每个实验要验证什么
| 实验 | 输入与执行方式 | 已获得的证据 | 进一步评测需要什么 |
|---|---|---|---|
| T1 速度跟踪 | 预训练策略与速度命令 | 策略加载、仿真推进和短视频录制 | 多回合速度误差与跌倒统计 |
| G1 速度与高度控制 | 循环学生策略的完整检查点 | 策略加载、仿真推进和短视频录制 | 高度误差、速度误差与稳定性统计 |
| G1 抓取放置场景 | 正弦动作驱动 | 场景、参考轨迹和动作链路可运行 | 任务匹配的上肢策略、成功判据与多回合评测 |
表 1 三种实验的证据范围。 场景能运行、策略能推理、任务能成功是三个不同的验收条件。短视频没有提供抓取成功率，也没有证明策略经过重新训练。
2026 年 6 月复现所检查的 WBC-AGILE 版本为 7259792cf10803aab814d101134d493d24c8f22f。该版本的预训练目录提供运动控制权重，未包含 G1-PickPlace-Tracking-v0 对应的上肢抓取检查点。这个结论限定于所检查的版本；后续版本是否补发，应查看官方预训练策略文档和文件列表。
2. 视频不动时，沿动作链路排查
最初录制抓取场景时使用了调试任务。源码 agile/rl_env/tasks/pick_place/g1/g1_pick_place_tracking_env_cfg.py 的调试配置会移除原来的上下肢关节动作项，并加入图形界面的关节控制动作。无界面运行时，没有交互输入，录到的画面可能接近静止。
排查时先看任务最终生效的配置，再看动作生成代码：确认仿真步数在增加、动作是否随时间变化、动作项是否仍连接到关节，最后比较物体与末端位姿。仅比较两帧图像不足以证明任务完成，阴影、相机或标记移动也会造成像素变化。
scripts/play.py 使用 generate_sinusoidal_actions() 生成正弦动作。切换到非调试的 G1-PickPlace-Tracking-v0 后，可以验证原始动作链路与场景，但它仍没有执行经过训练的上肢抓取策略。完整策略评估应从 scripts/eval.py 进入，并显式加载匹配任务的检查点。
视频 1 正弦动作驱动的 G1 抓取放置场景验证。 观察机器人、场景和参考轨迹的显示；该视频没有给出闭环抓取成功的证据。
来源：本项目本地生成，执行命令见主教程第九节。
3. 权重后缀相同，加载接口也可能不同
.pt 文件可以是训练检查点，也可以是 TorchScript［脚本化模型格式］导出策略。训练检查点由训练框架恢复网络和相关状态；导出策略按部署接口提供推理。选文件时要同时核对任务、网络结构、观测顺序、动作尺度和循环隐状态接口。
本次 G1 循环学生策略验证使用 unitree_g1_velocity_height_recurrent_student_checkpoint.pt。同目录的导出策略不能仅凭扩展名相同就替换到同一加载路径。更换权重后，应先完成单环境短运行，再检查跟踪指标；张量维度吻合也不能保证关节顺序和归一化语义一致。
图 1 上下肢策略的分工。 下肢运动策略和上肢操作策略需要各自匹配的输入与输出接口；已有行走权重并不能补齐抓取任务的上肢权重。
来源：WBC-AGILE 官方图示。
4. 固定版本与分离大文件目录
本次环境组合是 Isaac Sim 5.1 与 Isaac Lab 2.3.2。两者属于不同项目，版本号不能互换。复现时复制已有可用环境，在副本中安装项目依赖；新环境、下载缓存与批量输出应放在容量充足的数据盘。
下面是目录约定示例。先把数据根目录改成实际挂载的数据盘，再进入主教程执行安装；设置变量本身不会创建环境。
bashexport DATA_ROOT=/path/to/data-disk
export WORKSPACE="$DATA_ROOT/projects/agile"
export AGILE_ROOT="$WORKSPACE/WBC-AGILE"
export ISAACLAB_PATH="$WORKSPACE/IsaacLab"
export AGILE_ENV="$DATA_ROOT/envs/agile-wbc-isaac51-py311"
export AGILE_PY="$AGILE_ENV/bin/python"
export PIP_CACHE_DIR="$DATA_ROOT/cache/pip"
export HF_HOME="$DATA_ROOT/cache/huggingface"
记录源码版本、运行命令和关键输出，比保存整套环境压缩包更方便复查。预训练文件还应保留官方地址、对应源码版本、大小与 SHA-256［安全散列算法摘要］，下载完成后核对文件内容。
5. 模型按需恢复，教程保留轻量证据
官方可重新下载的模型可以清理本地副本。使用 Git LFS［Git 大文件存储］的仓库同时存在工作目录中的权重和本地对象缓存，只删其中一份可能无法释放预期空间。清理前应核验本地文件没有修改、官方文件可以下载、内容摘要相同，并确认没有运行中的训练或推理进程使用它。
保留源码中的大文件指针，可以继续记录原始权重的摘要与大小。以下命令在已经克隆的 AGILE 目录执行，只恢复策略文件，不额外下载官方视频：
bashcd "$AGILE_ROOT"
git lfs pull --include="agile/data/policy/**" --exclude=""
git lfs ls-files
恢复后，权重文件应由百余字节的指针变为实际模型。应在启动主教程的推理命令前完成恢复，尤其注意抓取场景也可能依赖下肢运动策略。
自训权重、独有采集数据和评测轨迹需要先归档，再删除本地文件。发布到 Datawhale 的 Hugging Face 仓库时，应附使用许可、任务配置、来源、文件清单和摘要，并核验远程文件后再清理。本次没有新训练出的抓取权重或独立采集数据集需要发布；现有官方权重可从上游按需恢复。
教程保留必要图示、短视频及来源说明。共享仿真资源、其它项目的数据和已有环境应按各自的使用关系管理，不能仅凭目录较大就推断其属于当前项目。
6. 完整抓取评测如何验收
获得任务匹配的上肢策略后，先确认策略输出确实驱动上肢关节，再分别记录接近、接触、抓起、搬运、释放与稳定放置。成功判据应包含物体到目标区域的距离、释放状态、稳定持续时间和机器人是否跌倒，并明确超时与失败重置规则。
最终报告应给出评测回合数、随机种子、初始物体分布、成功次数、成功率和失败原因。单个成功视频适合展示行为，多回合统计用于判断策略可靠性。跨房间搬运还需要定位导航、避障和任务规划，这些模块超出本次局部场景验证的范围。