dex_workbench/L20_REFERENCE_DIAGNOSTIC.md

L20 专家参考轨迹：离线可执行性诊断

最新进展（2026-09-14）：用户另行授权的一次75倍慢放、两轮各30000步动态回放已PASS， 见第7节。第1–6节保留此前CPU审计与当时的NOT_RUN边界，不将数据真实性标为通过。

结论

80 倍慢放主要由腕部平移参考速度门禁决定，而不是已证实的动力学极限。 对当前这条轨迹，保持现有速度阈值和几何路径时，统一慢放的速度必要下界约为 69.37266 倍。 70/75/80 倍在 0.8 m 对比工作半径下通过现有 CPU validate_reference()； 这不是动力学通过范围，也不授权仿真或真机动作。默认工作半径仍为 0.1 m，没有修改控制参数。

本次不启动 Kit/GPU、不运行训练、不改原始/派生 HDF5、不重绑定资产。当前代码基线 8e7ab5f（v0.1.2）加本次诊断模块；工作区原有其他未提交修改保留。

1. 输入身份与质量

• 原始输入：Data/l20_linkerbot_urdf_delivery/demonstrations.hdf5，右手， expert_retargeted，demo_000000，51 帧全有效，50 个源采样区间。
• 本次实际清单校验输入：历史制品目录 expert-replay-recovery-20260914/recovered-20260914T033624Z/bound.hdf5。 复核其历史绑定记录；原始文件与该文件的时间、腕位姿、关节、valid、关节顺序及坐标矩阵逐值相同。 80 倍派生文件全部几何样本也逐值相同，时间恰为原时间乘 80。
• 原始交付使用供应方暂定资产摘要，直接配当前清单仍 FAIL: asset bundle hash mismatch。 本次没有添加任何 hash override；已有绑定文件通过清单校验不等于重新检查整个 USD 或硬件身份。
• l20_tracking_v1 schema、有限值、时间严格递增、四元数及清单限位/联动检查：PASS。 长度 1.666666667 s，30 Hz；dt 最小/最大 0.033333333333333215 / 0.03333333333333344 s， 没有可见重复时间或异常长采样间隔。四元数最大范数误差约 3.47e-8。
• 关节最小限位余量约 -7.43e-8 rad，在已有 1e-6 rad 浮点容差内； 多个参考关节触及边界，不代表有动态余量。五组联动最大参考残差约 2.56e-8 rad， 小于既有 1e-3 rad 容差；不能把这些参考等式当作本轮物理联动验收。
• 米制尺度来源明确为 SLAM 估计，不是测量控制网。字段正确不证明尺度、腕根转换或重定向正确； 不再次应用 world_from_source 或 scale_to_meters。

输入	SHA-256
原始 HDF5	bd9321096803fbb64f590b4fdeb9056edc11ac446a7e16458c509beedc8b9552
历史 bound HDF5	ad64968150a67f504a7a2a4d18667c5e69bb2ee47f251917f8f9477bd4014c35
历史 slow80 HDF5	8f584c7409698394429737d509924013b8b90700117f8af2fb22465223dc1815
右手清单文件	52419b16d8faedc299f36711b6109b90eeb908e10e1c1b9faec3e16b9eaf37c9

2. 哪些区间超限

帧号均为 0-based，时间为原始秒。速度是相邻参考样本的派生量，不是传感器或仿真速度。 平移/关节使用 float64 差分；旋转使用 shortest-arc 世界旋转向量。 表中百分位按区间等权，关节列先取各区间所有 21 个状态关节的最大绝对速度。 21 个状态关节不等于 21 个独立驱动；JSON 中显式标识模型 follower。

量	中位数	P95	峰值	现有参考上限	超限区间数	单项慢放下界
腕平移 m/s	0.988018	2.203842	3.468633	0.05	50/50	69.372659
腕旋转 rad/s	2.893062	6.756863	8.999576	0.5	49/50	17.999153
最大关节 rad/s	1.263341	2.640378	2.935250	0.5	46/50	5.870501

优先核查的原始片段：

1. 帧 49→50，1.633333→1.666667 s：平移峰值，约 0.11562 m / 帧。 帧 47→48、48→49 的平移速度分别为 1.967910、2.696393 m/s，末段速度连续上升。 应回看原视频/SLAM/腕根重定向；不能仅凭高速就判为离群并删除尾帧。
2. 帧 28→29，0.933333→0.966667 s：旋转峰值 8.999576 rad/s。
3. 帧 29→30，0.966667→1.0 s：ring_mcp_pitch 速度峰值 2.935250 rad/s。
4. 帧 0→1 已有平移 1.684308 m/s、旋转 4.293173 rad/s。 当前 replay reset 清零速度；参考并非从静止平滑起步，启动瞬态需运行时验证。

整条腕路径长度约 1.872604 m，相对起点最大距离 0.651218 m（帧 15）。 帧 2–50 超过默认 0.1 m 半径；任何慢放都不改变这一点。 历史使用的 0.8 m 半径可包含该几何路径，但不是碰撞、可达性或硬件工作空间证明。

附加的中点差分加速度峰值：平移 33.683240 m/s²、旋转 99.073881 rad/s²、 各区间最大关节 62.699264 rad/s²。它们仅用于定位参考粗糙程度，不是物理加速度上界。 现有线性/SLERP 插值在节点速度可能跳变，不能据此估算真实力矩、认定饱和或保证平滑性。 独立的归一化四元数 dot/acos 算法与报告旋转速度的最大差约 1.06e-12 rad/s。

3. 慢放候选：仅 CPU 门禁结果

对原始 bound 样本在内存中使用现有 stretch_time()，再实际调用 validate_reference()； 没有生成新的慢放 HDF5。报告中的派生速度提升到 float64 计算，门禁仍使用既有实现，未改精度或容差。

慢放倍数	单轮时长 s	平移峰值 m/s	0.8 m 半径下参考门禁	本次动力学
1	1.666667	3.468633	FAIL：平移过快	NOT_RUN
60	100	0.057811	FAIL：平移过快	NOT_RUN
69	115	0.050270	FAIL：平移过快	NOT_RUN
70	116.666667	0.049552	PASS	NOT_RUN
75	125	0.046248	PASS	NOT_RUN
80	133.333333	0.043358	PASS	NOT_RUN

默认 0.1 m 半径下，这六档全部 FAIL（较慢档仍违反工作半径）。 70 倍的平移速度余量仅约 0.90%，75 倍约 7.50%，80 倍约 13.28%。 因此不建议先盲试 40/20 倍，也不把 69.37266 倍数学边界直接当作可执行速度。

历史 80 倍动力学 PASS 及误差见 L20_TRACKING.md 第5节。 本次重新核对历史原始日志 SHA，但没有重跑；不能把历史 PASS 扩展到70/75倍或当前GUI入口。

4. 控制器归因与下一步

源码核查 control.py / scripts/tracking/track_l20.py：

• 腕 PD 为 Kp*(p_ref-p)-Kd*v_measured，角速度同理，没有参考速度前馈； 手指位置目标的 velocity target 也保持0。移动目标需要误差抵消阻尼，存在跟踪滞后机制。 忽略惯性、重力残差和耦合的恒速近似下，腕滞后时间 Kd/Kp=0.1 s；这只是定性诊断， 不能当作全轨迹误差预测或改变增益的依据。
• 当前目标在 step 开始时发送，step 后与下一参考点比较，另有离散采样因素。
• 20 N / 1 N·m 总 wrench 限制、0.2 N·m finger effort、0.5 rad/s finger velocity 都是未标定的仿真配置。仅凭参考数据无法知道实际执行是否饱和。
• 默认参考速度门禁、物理 drive cap、运行时速度安全断言及误差断言是不同层次； 不能拿较宽的实测速度安全界限替代较窄的参考门禁。

建议顺序：

1. 先请数据方核查上述关键帧、SLAM 米制尺度与腕根变换，保留原文件与版本； 当前证据不能区分真实高速动作与重建/重定向误差，不擅自平滑、裁剪、缩放或重居中。
2. 若几何确认无误且继续使用现有控制器，可另行授权一次 75 倍、两轮各30000步、单环境、 240 Hz、工作半径0.8 m、外部上限600秒的完整回放；保持阈值，先记录误差及饱和信息。 本轮未运行，也未增加运行时日志字段。75倍通过后才考虑70倍。
3. 若目标是接近原速，这类慢放提速收益很有限。需单独设计经确认的参考速度前馈/启动过渡 与控制带宽实验，而不是直接放宽门禁；随后再接入任务、示教基线与RL。

5. 复现与验证

新增入口 source/dex_workbench/dex_workbench_tracking/diagnostic.py 仅依赖已有 numpy/h5py， 不导入 pxr、torch、isaaclab 或 Kit。JSON 包含每关节统计、全部区间、超限位置、mimic残差、 输入/清单哈希、未标定默认参数和候选实际门禁结果。拒绝无效帧间隙、不匹配身份、覆盖输出。 status=PASS 仅表示报告成功生成；候选的 reference_gate 单独报告，dynamic_replay=NOT_RUN。

从仓库根目录执行，BOUND 必须指向已有独立核验的同清单文件；不是原始交付的 hash 替换开关。 EVIDENCE 指向已存在的仓库外制品目录，新输出路径不得已存在。

export PYTHONPATH="$PWD/source/dex_workbench${PYTHONPATH:+:$PYTHONPATH}"
MANIFEST=assets/robots/dex_hand/linkerhand_g20_right/tracking_manifest.json
~/isaacsim/python.sh -m dex_workbench_tracking.diagnostic "$BOUND" \
  --manifest "$MANIFEST" --output "$EVIDENCE/default-workspace.json"
~/isaacsim/python.sh -m dex_workbench_tracking.diagnostic "$BOUND" \
  --manifest "$MANIFEST" --workspace-radius 0.8 --output "$EVIDENCE/extended-workspace.json"
~/isaacsim/python.sh -m unittest discover -s source/dex_workbench/tests -p 'test_tracking_*.py' -v
~/isaacsim/python.sh -m ruff check source/dex_workbench/dex_workbench_tracking/diagnostic.py \
  source/dex_workbench/tests/test_tracking_diagnostic.py
~/isaacsim/python.sh -m ruff format --check source/dex_workbench/dex_workbench_tracking/diagnostic.py \
  source/dex_workbench/tests/test_tracking_diagnostic.py
git diff --check

实际 CPU 环境：Python 3.12.13、numpy 2.5.1、h5py 3.16.0；未安装/升级依赖。 本机制品目录（相对仓库根）：../dex_workbench-evidence/l20-reference-9Q2Cbs/，不随源码分发。 含两份JSON、输入审计脚本/结果、测试日志及实际命令记录；干净克隆不自带 bound/右USD/专家数据。

• PASS：新诊断10项回归；全部tracking CPU/USD回归 98项，无跳过。 首次诊断测试因合成测试清单缺少右手必需身份字段失败；补全测试夹具后全量重跑。 没有放宽生产身份门禁。初次Ruff行宽失败，经格式化后复检。
• PASS：原始/bound/slow80身份与样本保留审计，独立旋转数值交叉核对。
• NOT_RUN：GPU仿真、GUI、70/75倍动力学、碰撞/接触、训练及硬件；本任务限定CPU诊断。
• 完整 pre-commit 工具不可用，不将局部Ruff与单测代替全量发布门禁。
• 新增只读诊断，不改变既有数据schema、运行控制器、资产、Cartpole任务、checkpoint或包版本。 没有提交/推送。

6. 继续核查：关键帧与导出链路

本节为后续 CPU 审计，不新增运行时验收。使用交付中的 retarget/right_qpos.npz 与 demo_000000_triple_0_50.mp4，没有重新拟合、修复或发布数据。

已排除：关节导出列错位与时间轴不一致

• NPZ 有121帧、21列，HDF5交付前51帧；两者关节列顺序不同。 按名称显式重排后，NPZ前51帧转为float32，与HDF5的全部关节样本逐值完全一致。 原float64到HDF5 float32的最大差仅 5.88378966e-8 rad。
• ring_mcp_pitch 的帧29→30峰值在NPZ中已经存在，约 2.93524959 rad/s。 因而该峰值不是本次HDF5序列化或关节列错位制造的；仍不证明重定向结果等于真实关节运动。
• HDF5时间逐值等于 arange(51)/30，NPZ声明fps=30。 预览按顺序解码得到51帧、30fps；帧28/29/30/49/50的媒体时间与对应HDF5时间一致。 这只核对交付内部时间索引，不能证明与原始相机/SLAM真实同步。

尚未闭合：相机系腕位姿到世界系的变换

NPZ声明 view=ego_cam，其 wrist_pos 不能直接与世界系HDF5位置相减后当作误差。 NPZ本身也没有显式腕位置单位字段；交付说明暗示米制，但仍应由数据方确认。

帧49→50	NPZ相机系（原单位）	HDF5世界系（m）
位移范数	0.013635702	0.115621099
位移范数 / dt	0.409071067	3.468632970

若双方长度单位确认为米，此差异不能由一个固定刚体坐标变换单独解释： 固定旋转/平移不会改变相邻点间距离。交付声明另外应用了逐帧SLAM相机运动， 因此需要复算的是这一步的旋转、平移、方向、帧对齐与尺度，不能认定世界系高速就是错误。 不以逆向拟合出来的相机轨迹代替缺失的独立SLAM证据。

预览关键帧0、28、29、30、47、48、49、50已实际抽帧并查看： 末段桌椅在画面中明显移动，画面模糊，手/叠加模型接近下边缘； 这与视角变化相容，但单目叠加预览没有独立米制依据，既不能证实也不能否定3.47 m/s世界速度。 帧28–30的叠加显示也不足以验证8.9996 rad/s世界系腕角速度。

另有待确认字段：NPZ的 hand_scale 前51帧范围为 0.678304–0.845200； 帧49→50从0.720546降到0.681751（约 −5.38%）。它的估计方法及应用位置未随NPZ提供， 不能把它等同于HDF5的 scale_to_meters=1.0，也不能据此直接重新缩放轨迹。 它可能与手模型拟合有关，是否影响腕根平移需查看上游代码，而不是从字段名推断。

给数据方的最小补充清单

请补充同一 video_0、至少覆盖帧0–51（包含交付末帧后的一个邻帧）的以下材料； 最好提供已有完整121帧，不必重新采集：

1. hawor_slam_w_scale_0_121.npz 或等价逐帧相机SE3，附帧ID、秒时间戳、 变换方向（camera→world还是world→camera）、轴向、位置单位及四元数顺序。
2. 同版本 export_l20_tracking_hdf5.py 与 retarget_mano_to_g20_mujoco.py， 或相关变换/尺度计算片段，附版本/提交及实际参数。
3. 明确 right_qpos.npz 的腕位置单位、四元数顺序、hand_scale 的含义、 每帧变化是否应用于腕根平移，以及SLAM米制尺度来自何种估计/标定。
4. 原始 video_0.mp4 的对应短片及原帧号/时间映射；说明重定向、视频、SLAM是否存在偏移或丢帧。

优先解释帧49→50的世界位移0.115621 m及帧28→29的世界旋转峰值。 请保留当前交付，任何修正另出版本与哈希，不原地替换样本或静默裁剪。

当前交付与本仓库 Data/、scripts/ 中未找到上述SLAM文件、原始视频或两份上游脚本。 因此 世界腕位姿导出复算为BLOCKED（缺独立输入），不是仿真或训练失败。 先补齐此接口，再判断是否需要修正数据或开展75倍受限回放。

本轮证据与边界

本机制品目录：../dex_workbench-evidence/l20-keyframes-ANfXqd/，不随代码提交。 包含 audit_keyframes.py、keyframe-audit.json、audit.log、 keyframes-video-mano.jpg 和完整三联帧49/50图片。 审计使用 np.load(..., allow_pickle=False)；OpenCV 4.13.0软件解码既有预览，不调用Kit或GPU仿真。 环境PATH无ffmpeg/ffprobe，本轮使用已有OpenCV，未安装依赖。

实际命令（仓库根；KEYFRAME_EVIDENCE指上述仓库外目录）：

PYTHONPATH=source/dex_workbench ~/isaacsim/python.sh "$KEYFRAME_EVIDENCE/audit_keyframes.py"
git diff --check

• PASS：脚本退出0；命名关节映射/float32样本一致、时间一致、51帧预览解码断言， 对交付目录全部文件的运行前后SHA-256相等；原始数据没有改变。
• BLOCKED：世界系腕位姿独立复算，缺逐帧相机SE3/导出源码/尺度说明。
• NOT_RUN：新GPU回放、GUI、训练、硬件；本轮没有启动，也未授权扩大默认资源预算。
• 本轮仅追加本文及仓库外诊断制品；未改变应用代码、控制参数、资产、schema或包版本。 不重复把上一轮98项回归当作本轮新运行；本轮文档变更的仿真E2E为N/A。 未暂存、提交或推送。

7. 单次授权75倍慢放动态回放：PASS（2026-09-14）

用户明确确认GPU预算后，只执行一次：单环境、seed42、240Hz、两轮各30000步、 每轮125秒完整参考，工作半径0.8m，headless，外部timeout600秒（终止宽限15秒）。 未重试、未启动70倍或其他实验；未调增益、限速、力/力矩上限或验收断言。

准备与真实验收结果

• 以历史已核验的 bound.hdf5 为输入，使用已有 stretch-time --factor 75 生成仓库外新文件。 原始交付不改写、不重新绑定；原始/bound样本完全一致，slow75几何/valid/坐标元数据保持， 时间恰为原始时间乘75。派生文件通过清单及现有参考速度/工作半径检查。
• 注册现有PhysX/Newton schema后的prepared检查通过，覆盖层包SHA保持 3e2071a60496b23bed252f4e2fc6e1d4540eecc8098578506419b5eb594f7da0。
• 本轮新运行全部tracking CPU/USD回归：98项PASS，无跳过。
• GPU运行 364秒、退出0，日志唯一的 bounded_experimental_dynamic_tracking 结果为PASS； 确认HDF5哈希、全覆盖125秒、两轮各30000步、浮动根、1个有效articulation root、21个状态关节。 原入口的有限值、速度安全界限、限位、非零被动联动、reset、逐步位姿及速度重复性断言全部执行通过。
• 每轮的max/RMS汇总相同，但不承诺跨运行GPU位级确定性。下列关节/联动统计沿用运行入口语义： 每步先取各关节最大绝对误差/残差，再对时间汇总。

误差	最大值	RMS
腕位置 m	0.004526687	0.001701794
腕姿态 rad	0.014233187	0.007083100
各步最大关节误差 rad	0.011136770	0.007015317
各步最大mimic残差 rad	0.000231415	0.000100018

历史80倍的最大腕位置/姿态误差分别为0.004234530m / 0.013369173rad； 本次75倍略大，但均在既有门禁内。这是两个指定轨迹速度的结果对照，不是收敛、性能或全速度区间保证。

执行环境、命令与证据

Isaac Sim安装版本 6.0.1-rc.7+release.42383.32955d8d.gl，运行时PhysX 110.1.13； RTX5080，驱动595.84，Python3.12.13、numpy2.5.1、h5py3.16.0。 Isaac Lab基线 6a7acb0320a0bdc15b13e44e83b575e00797faf4，其本机工作区有既有 source/isaaclab/isaaclab/cloner/cloner_utils.py 修改：本任务未改该文件，已另存patch， 不能将本次结果当作干净上游Lab环境验收。项目运行源码仍为 8e7ab5f 对应控制入口， 另有前几轮新增的独立CPU诊断和文档；本次未改应用代码。

实际运行命令（仓库根目录；EVIDENCE指下方本机制品目录）：

export PYTHONPATH="$PWD/source/dex_workbench${PYTHONPATH:+:$PYTHONPATH}"
RIGHT=assets/robots/dex_hand/linkerhand_g20_right
# 仅复现记录，不是再次启动授权。
timeout --kill-after=15s 600s ~/isaacsim/python.sh scripts/tracking/track_l20.py \
  "$RIGHT/tracking.usda" --manifest "$RIGHT/tracking_manifest.json" \
  --hdf5 "$EVIDENCE/slow75.hdf5" --steps 30000 --full-episode \
  --workspace-radius 0.8 --execute-experimental --headless

本机制品目录：../dex_workbench-evidence/l20-slow75-DeXIEX/，不随源码提交。 包含精确展开命令 exact-command.txt、单次启动脚本 run-once.sh、LAUNCH-CONSUMED、 replay.log、result.txt、metrics.json、acceptance.json、输入预检/样本保留检查、 source-before.json、CPU测试日志、前后GPU/进程快照及既有Lab patch。

• slow75 HDF5 SHA256：6133e58499e3eb4739bed4b70f3147c9361c445dc97d32ba4f03a60c74afe8f9。
• replay.log SHA256：794c5a95b3176285ca2852febacd295a701c4ea846e916008d582397271cf75d。
• 接受脚本另外核验退出0、预算、唯一PASS、步数/轮数/身份、参数、有限指标及阈值； 在更新本文前，93个被快照的源码/文档/资产/交付文件SHA与运行前相同。
• 启动前后无Kit或GPU计算进程；运行后显存633MiB，仍有正常桌面图形进程。 没有停止其他用户进程，不据此保证所有资源位级恢复。

剩余边界

• 保留了现有headless参数弃用/重复提示、protobuf重复注册诊断、visualizer配置缺失、 MaterialX/usdrt及TGS外力迭代警告。16/21 actuator提示对应5个有意被动关节，未关闭警告或放宽检查。
• 当前入口只保存汇总误差，未导出逐步wrench/力矩饱和统计；不能声称无控制饱和。 要做带宽或前馈归因，应另行增加可审计的遥测，而不是仅靠本次PASS推断。
• 上游相机SE3、尺度和原视频的独立核查依旧BLOCKED；本次只是把给定参考在仿真中受限跟踪。
• 原速、70倍、GUI整合、接触/物体任务、多环境、训练与硬件本轮均NOT_RUN。 不自动启动下一档；不把75/80倍两个离散PASS泛化为整个区间可执行。
• 本轮仅更新验收文档、变更记录及仓库外制品；资产/控制器/schema/版本不变。 完整pre-commit仍未具备，测试通过不等于完整Release就绪。未暂存、提交或推送。