dex_workbench/L20_IMITATION.md

L20 状态输入 ACT：训练准备与运行

v0.1.3 更新：最新汇总见 PROGRESS_v0.1.3.md。本轮120项回归及新的4步CPU smoke通过。 已收到1333帧同源轨迹和估计相机；这不构成新的独立采集组或实测尺度审查。 默认展示相机参考回放已有PASS，原视频相机完整运行超时；ACT策略GPU E2E仍NOT_RUN。 下文环境安装、118项测试和“未升级/未提交”等描述是初次ACT准备阶段的历史记录，不是v0.1.3提交状态。

当前交付范围

路线A：腕手参考轨迹模仿 → 仿真评估 → 后续PPO refinement。 当前提供可执行的状态输入ACT-style CVAE Transformer、数据门禁、离线训练/保存/加载/留出评估， 以及已有Isaac Lab受限回放入口的可选闭环策略分支。

• PASS：本机CPU依赖、editable安装、synthetic短训练→保存→加载→离线预测链路及回归测试。
• BLOCKED：真实专家训练，目前只有单条示例，且独立坐标/尺度审查未闭合；不能自动批准。
• NOT_RUN：新策略分支的GPU仿真E2E、真实专家训练/质量评测、GUI策略回放。 历史75/80倍参考回放PASS不等于新策略回放PASS。
• 没有创建L20 Gym/RL任务、奖励、物体场景、PPO、视觉模型或硬件驱动；Cartpole任务及checkpoint保留。 本页的“训练可运行”指离线参考模仿，不是抓取训练就绪或Sim2Real验收。

1. 本机环境

继续使用已有Isaac Sim Python，不更换它的PyTorch/CUDA。 本次实测：Python3.12.13、PyTorch2.10.0+cu128、numpy2.5.1、h5py3.16.0， Isaac Sim6.0.1-rc.7；Isaac Lab可发现。本轮没有初始化CUDA训练或启动Kit。

从仓库根目录运行：

# 本机默认使用 ~/isaacsim/python.sh；不同安装位置由调用者显式设置。
# export ISAACSIM_PYTHON=/path/to/isaacsim/python.sh
bash scripts/imitation.sh doctor

# 本机已实际执行：仅安装项目，不访问索引、不安装/升级依赖。
~/isaacsim/python.sh -m pip install --no-index --no-deps --no-build-isolation -e source/dex_workbench

setup.py已收录dex_workbench_imitation包及imitation可选依赖。 本机旧installed metadata为0.1.0，本次重新安装后与源码0.1.2一致；未修改源码版本号。 不要在Isaac Python里盲目执行pip install --upgrade torch或复制另一机器的CUDA wheel。 新节点须先安装兼容的Isaac Sim/Lab和已核验依赖，再执行上述本地安装与doctor。 右手USD目前仅本地存在，存储/再分发许可尚未闭合；离线训练只消费HDF5与清单， 新节点仿真评估另需合法取得同哈希资产并重建prepared层，不保证干净克隆直接可回放。 可选 doctor --cuda仅检查CUDA可用性，不是GPU容量或仿真验收。

包装脚本设置本仓库PYTHONPATH，不改变调用者cwd；输入/输出相对路径仍相对于调用目录。 不要求激活系统Python或下载额外模型，也不会自动搜索“最新checkpoint”或自动开始训练。

2. HDF5补齐后还需要哪些输入

沿用 l20_tracking_v1，不新增伪造观测/力矩字段，不改变现有回放契约。 训练前需要三个实际文件及同版模型清单：

1. HDF5：经过同版模型绑定，全部使用一侧L20与同一校准；各episode全有效，单位/时间/顺序/限位/联动正确。 不能直接把原始交付的暂定资产哈希替换成当前清单哈希。
2. 划分文件：参照 configs/imitation/splits.example.json，在仓库外填写实际episode与采集来源。
3. 数据审查文件：参照 configs/imitation/data_review.example.json，在独立复核后由负责人填写。

划分与来源

• 至少 两个独立采集组才可进行训练+验证，建议另有独立test组；这只是最小接口门槛，不是数据充足标准。
• 每个episode必须且只能属于train/validation/test中的一个。不能随机按帧划分。
• 同一原始录制的切片、慢放、重采样或重复导出，必须使用同一episode_groups值且落在同一分区。
• 自动拒绝跨分区同group及几何数组逐值重复的轨迹（忽略时间，捕获改名/慢放副本）。 不能自动识别所有重采样、裁剪或旋转等价副本；仍需负责人核对真实采集来源。
• episode_groups不是自动生成的独立性证据，示例中的占位名称必须替换。
• HDF5中所有episode必须明确划分，不静默忽略文件里的额外轨迹。

审查文件不是绕过门禁的开关

填写实际HDF5文件SHA256和资产包SHA，记录reviewer与evidence，明确：

• coordinate_and_scale_reviewed：坐标变换、SLAM尺度与同步已经独立复核；
• reference_state_targets_accepted：同意把未来参考状态作为这一实验的目标代理，而非宣称实测动作；
• capture_groups_reviewed：数据来源与跨分区泄漏已人工审核。

示例默认false/空值，刻意不能通过训练门禁。程序只检查声明与文件绑定，不能替代人的真实审查。 当前已收到估计相机SE3，但尺度与独立数据审查仍未闭合，不能把标记自动改为true来启动。

速度和时间

• 配置控制频率30Hz；保留数据物理时间，按线性位置/关节插值及shortest-arc SLERP重采样。
• episode末时刻须落在控制频率网格上；只处理浮点舍入，不静默裁去尾帧或改变时长。
• 保留既有参考上限：腕平移0.05m/s、腕旋转0.5rad/s、所有状态关节0.5rad/s。 默认实验工作半径0.8m，与先前扩范围回放一致。
• 训练准备不自动慢放、缩放、平滑、重居中或跨无效帧插值。超限时明确失败，由数据方另出可追溯版本。
• 单文件读取上限2GiB，重采样总帧数默认500000；大数据须明确分片/扩展，不自动放大资源预算。

3. 观测/动作契约：l20_goal_reference_act_v1

这是状态参考模仿基线，不是完整Canonical Skill Space或全项目DexSchema实现。 共享几何使用相对episode初始根link的腕部位姿；构型特有的关节顺序、主从映射与限幅封装在Adapter中。 不把21状态关节或16个目标硬编码为所有手型接口，也不把模型独立目标数当作硬件电机数。

项目	定义
当前状态	初始根坐标系中的当前腕位置3维、旋转6D（旋转矩阵前两列）、清单全部J个状态关节
条件目标	同坐标系下的episode终点腕位姿、终点M个模型独立关节姿态
时间条件	归一化phase及episode时长（秒）；用于指定此参考的时间参数，不是奖励
观测维数	20 + J + M（当前已核验右手为57）
输出	未来chunk的腕位置/旋转6D与M个独立q_target代理，维数9 + M（当前右手25）
训练输入来源	HDF5的参考状态；没有声称这是执行后传感器观测
仿真输入来源	实际当前root-link pose/q，加预先给定终点目标、phase和时长；不喂未来中间参考帧

当前状态→未来状态目标不是已测量的动作因果对。训练中teacher-forced参考状态与部署时受扰状态存在分布差异； 多条路径也可能共享相同起终点。这是需要真实仿真评估和后续示教/残差策略研究的风险，不因loss降低而消失。 不向网络输入完整未来参考轨迹来假装闭环成功。

模型与loss

• 状态输入ACT-style CVAE：训练时Transformer posterior编码观测及未padding的未来动作块， 得到高斯latent；decoder根据观测+latent与chunk queries预测未来目标。
• masked normalized L1 + KL；padding既不参与reconstruction loss，也被posterior attention mask排除。
• 推理固定latent=0，不使用训练posterior的未来目标；无dropout，CPU推理确定。
• 不是官方ACT仓库/权重兼容实现；没有视觉ResNet或Diffusion分支。
• normalization仅由训练分区的非padding帧拟合，验证/test数据不参与统计。
• best checkpoint仅按validation选择；test不参与优化或checkpoint选择。

默认 configs/imitation/l20_right_act.json：chunk16、每次执行前4个目标再规划、30Hz目标频率， Transformer宽128/2层/4heads/latent32、batch32、seed42、最多1000更新且600秒。 这是有界起始配置，不是已调优或保证收敛的超参。600秒是训练/验证循环的内部预算， 不包含此前的数据预检；命令另设外部进程超时。预算耗尽记FAIL/未完成，不伪装成完成训练。

4. 数据到位后的命令

下面变量由调用者指向审核后的文件；OUT必须是新的仓库外目录。 当前示例数据不会通过这些正式训练门禁，这属于预期BLOCKED，不是安装失败。

MANIFEST=assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json
CONFIG=configs/imitation/l20_right_act.json
# DATA=/approved/path/demonstrations.hdf5
# SPLITS=/approved/path/splits.json
# REVIEW=/approved/path/data_review.json
# OUT=/external/artifacts/l20-act-run-001

# 先只做CPU数据预检；父目录须存在，输出JSON必须为新文件。
bash scripts/imitation.sh preflight --hdf5 "$DATA" --manifest "$MANIFEST" \
  --config "$CONFIG" --splits "$SPLITS" --data-review "$REVIEW" --output "$OUT-preflight.json"

# 审核数据与资源预算后再由用户启动；不传--execute会拒绝。
# CUDA是显式选择；不可用时报错，不静默换CPU，也不安装替代CUDA依赖。
timeout --kill-after=15s 660s bash scripts/imitation.sh train --hdf5 "$DATA" --manifest "$MANIFEST" \
  --config "$CONFIG" --splits "$SPLITS" --data-review "$REVIEW" \
  --device cuda --execute --output "$OUT"

# 按完整test分区做离线预测评测（CPU）；这不是仿真rollout或任务成功率。
bash scripts/imitation.sh evaluate --checkpoint "$OUT/best.pt" --hdf5 "$DATA" \
  --manifest "$MANIFEST" --split test --output "$OUT-test.json"

train默认device为CPU；不要省略CUDA选择后误以为已用GPU。修改max_updates/max_seconds等资源预算应先确认。 训练输出为run.json、逐更新metrics.jsonl、best.pt、last.pt、result.json； 受控异常输出failure.json，不写成功result；进程硬超时/中断可能只留下部分制品，缺少result不能算PASS。 已有目录拒绝使用，不自动覆盖历史实验。 同一新run内best/last通过临时文件原子发布；记录配置、数据/Adapter、split/review、源模块哈希与依赖版本。

checkpoint使用tensor-only加载，绑定contract、资产/Adapter及normalization。 本版本支持推理加载，不提供优化器resume；不要把另一次新训练冒充恢复同一优化状态。 同一checkpoint的评估必须使用同一HDF5哈希；新评测数据需要显式评估接口扩展，不靠改metadata冒充原评测集。

5. 仿真策略评估入口（已实现，GPU E2E为NOT_RUN）

新增可选 scripts/tracking/track_l20.py --policy-checkpoint，默认不传时保留参考目标回放逻辑。 PASS日志增加control_source与policy_checkpoint_sha256字段；不改变HDF5 schema。 只接受训练数据中明确属于validation/test的episode，拒绝train episode；要求完整回合回放。 运行前仍检查source/prepared USD、PhysX后端、参考速度/范围及所有旧门禁。

策略在控制步读取实际状态，执行chunk前4个目标后重规划；每个240Hz物理步均经过Adapter：

• 将6D旋转恢复为合法旋转；退化/非有限输出明确失败，不能静默给单位姿态。
• 限制起点相对工作半径、目标平移/转动速度；关节按主从约束交集限位。
• 独立关节限速还考虑mimic倍率，确保派生状态关节目标也满足参考速度上限。
• 只发master q_target及既有根部wrench PD；从动关节由物理耦合响应，不独立驱动。
• 两轮分别清空policy chunk、时间计数及限幅器状态；只有原有reset路径写物理状态。
• 保留原有动态误差/限位/速度/mimic/非零运动及reset、位姿/速度重复性检查。 策略未训练好时应该FAIL，不用参考轨迹替代网络输出来通过。

确认无其他GPU/Kit作业，并另行批准单次仿真预算后才运行：

export PYTHONPATH="$PWD/source/dex_workbench${PYTHONPATH:+:$PYTHONPATH}"
# EPISODE必须属于validation/test，STEPS必须等于该回合秒数*240，且100<=STEPS<=32000。
# TIMEOUT_S须覆盖已批准预算；外部终止宽限15秒，不自动重试。
timeout --kill-after=15s "$TIMEOUT_S" ~/isaacsim/python.sh scripts/tracking/track_l20.py \
  assets/robots/dex_hand/linkerhand_g20_right/tracking.usda --manifest "$MANIFEST" \
  --hdf5 "$DATA" --episode "$EPISODE" --steps "$STEPS" --full-episode \
  --workspace-radius 0.8 --policy-checkpoint "$OUT/best.pt" --execute-experimental --headless

策略与运行时控制参数必须与checkpoint绑定值一致；不允许临时扩大范围或阈值来通过。 日志使用独立标记bounded_reference_act_rollout，记录checkpoint SHA、推理次数和目标限幅步数。 目标限幅计数不是真实wrench/力矩饱和统计。 完整轨迹、非零运动和误差门禁仍可能限制部分静止/局部手指episode的仿真验收； 这些数据可以用于离线训练，不得为了满足诊断而添加伪运动。

6. 本次测试证据与剩余工作

本机证据位于 ../dex_workbench-evidence/l20-act-setup-M9Y0OX/，不随代码分发。

# 已执行：只生成明确synthetic的三条不同解析轨迹，4次小CPU更新；不启动Kit。
bash scripts/imitation.sh smoke --manifest assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json \
  --output "$NEW_EXTERNAL_SMOKE_DIRECTORY"

PYTHONPATH=source/dex_workbench ~/isaacsim/python.sh -m unittest discover \
  -s source/dex_workbench/tests -p 'test_*.py' -v

• 依赖/安装PASS：项目editable安装成功，无依赖下载/升级；CPU doctor及doctor --cuda可用性探测成功。 另在仓库外、清除PYTHONPATH后验证安装包可导入；CUDA可用不代表本轮执行过GPU训练或仿真。
• CPU smoke PASS：真实反向传播4次、有限loss、保存非空checkpoint、tensor-only重新加载； 重新加载预测最大差0；独立test分区离线预测有限。仅为管线验证，不宣称收敛。
• 全部118项回归PASS，无跳过（包含20项新增模仿学习测试）；覆盖坐标/半周旋转、coupling/rate限幅、 数据划分/分组/重复轨迹、训练统计隔离、padding mask、CVAE梯度、checkpoint身份、预算失败、 拒绝覆盖、held-out策略时钟/reset，以及旧tracking回归。
• 新仿真策略分支E2E、当前修改后的默认参考回放GPU回归、真实数据训练为NOT_RUN； 没有沿用上一轮已消耗的600秒GPU授权。完整pre-commit工具仍缺失，不宣称全量发布门禁通过。
• 后续：补齐数据审查与独立episode → 批准小规模真实训练预算 → 新checkpoint仿真闭环验收； 之后才设计PPO refinement或视觉/物体任务。尚无任务成功率、Sim2Real或SkillBundle交付声明。
• 本轮新增包/配置/文档，扩展可选策略入口；原始数据、USD、控制增益与物理阈值未改， 不升级包版本或改变Cartpole任务。未暂存、提交、推送。