hand-motion-pipeline/docs/PIPELINE_LATEST.md

最新流程（2026-09-17）：RGB-D 双手视频 → Dyn-HaMR → L20 重定向 → FoundationPose → 参考修复 → SPIDER 物理

本文是 docs/20260915_171525（D405 头戴 RGB-D，352 帧，双手 + 红/蓝两个盒子）这条数据上实际跑通并交付的链路，按执行顺序给出每一步的脚本、输入、输出、关键参数和验证文件。旧的单手 / 瓶子链路见 INTEGRATED_PROJECT.md，此处不再重复。RL 跟踪训练线不在本文范围。

当前状态

• 运动学参考已交付：output/final_smooth_20260915/。手-盒 / 手-桌穿透 0（含 2.5 mm 间隙、400 Hz 插值 4681 步），精确 CAD 探针侵入 0，腕位置二阶差分 0.4 mm，手指 0.35°。
• SPIDER 物理滚动：output/final_spider_run_20260915/。4680 步全部有限、穿透 0、CAD 探针 0；但手不真正合拢（实际接触步 20/4680），红盒抬起与蓝盒翻转都未复现。这是当前主问题。
• 所有"接触"都是几何假设（人手指尖到 CAD 表面最近点），没有触觉真值；蓝盒第 177 帧后被遮挡，位姿只是保持最后可靠值。

0. 总览

docs/<seq>/{color.mp4, depth/*.png, intrinsics.json}          docs/上半.stl（红盒）  docs/下半.stl（蓝盒）
        │
 [0] RGB-D 预处理 + 静态背景相机里程计   prepare_rgbd_20260915.py      → output/<seq>/rgbd_camera.npz
        │
 [1] Dyn-HaMR 双手重建                   run_dynhamr_rgbd_20260915.py  → output/<seq>_dynhamr/optimization/
     时序修正（SO(3) 局部均值 + 高斯）    correct_dynhamr_rgbd.py       → .../corrected/prior/*_world_results.npz
     导出人手 21 关节                     export_dynhamr_bimanual_rgbd.py → .../human_joints_{left,right}.npz
        │
 [2] L20 重定向（左右手各跑一次）         retarget_l20_video.py         → .../l20_{left,right}_stable/motion.npz
        │
 [3] FoundationPose 物体 6D 逐帧跟踪      track_yesterday_boxes.py      → output/foundationpose_spider_20260915/foundationpose_objects.npz
     碰撞资产（CoACD）                   decompose_yesterday_boxes.py / build_box_collision_v2.py / build_palm_collision_v2.py
        │
 [4] 手物配准 ①（世界系 + 尺度 + 深度）   register_hands_rgbd.py        → .../registered/
     SPIDER 任务初版                     prepare_yesterday_spider.py   → output/registered_spider_20260915/
     物体参考物理自洽                    smooth_object_reference.py    → output/final_spider_20260915/foundationpose_objects.npz
     手物配准 ②（指根对齐）              register_hands_rgbd.py  HF_ALIGN=mcp → .../aligned/
     SPIDER 任务（最终）                 prepare_yesterday_spider.py   → output/final_spider_20260915/
        │
 [5] 碰撞修复 + 桌面约束                 fix_yesterday_hand_collision.py → output/final_collision_fix_20260915/
     验证 / 审计 / 渲染                  verify_fix_interpolation.py · audit_collision_fix.py · render_collision_fix.py
     分开平滑 + 逐帧联合投影             smooth_project_reference.py   → output/final_smooth_20260915/   ← 最终运动学参考
        │
 [6] SPIDER 物理滚动                     configure_spider_task.py → run_yesterday_spider.py → output/final_spider_run_20260915/
     独立审计 / 重放 / 渲染 / 交互回放    audit_collision_physics.py · check_spider_dynamics_replay.py · audit_spider_dynamic_surfaces.py · render_collision_fix.py --physics · play_spider_result.py

解释器

解释器	用在哪
.venv/bin/python（执行 source scripts/foundationpose_env.sh 后就是 python）	FoundationPose、RGB-D 预处理、Dyn-HaMR 启动/修正/导出、配准、prepare / fix / verify / audit / smooth / render、交互回放
third_party/Dyn-HaMR/.dynhamr/bin/python	Dyn-HaMR run_opt.py（由 run_dynhamr_rgbd_20260915.py 内部调用，不用手动进）
.dex/bin/python	dex-retargeting 0.5.0：retarget_l20_video.py
.spider/bin/python	SPIDER / MuJoCo Warp：run_yesterday_spider.py、audit_collision_physics.py、check_spider_dynamics_replay.py

离屏渲染脚本默认 MUJOCO_GL=osmesa；交互回放脚本自动切 glfw。所有脚本从项目根目录执行。环境安装见 SETUP_AND_WEIGHTS.md、FOUNDATIONPOSE_SETUP.md。

输入数据

• docs/20260915_171525/color.mp4（848×480，标称 30 fps，真实硬件时间跨度 11.70 s）、depth/（352 张对齐深度 PNG）、intrinsics.json（fx fy cx cy、帧数、时间戳）。RGB / 深度逐帧时间差 < 0.31 ms。
• docs/上半.stl = 红盒，docs/下半.stl = 蓝盒。米制，18.16×16.60×4.69 cm。红盒网格不封闭（一条 T 形边），碰撞资产阶段在副本上修复，原文件不改。
• L20 模型：third_party/l20_assets/L20/{LEFT,RIGHT}/linkerhand_g20_{left,right}.urdf 与网格。左右手各用自己的 URDF，不是镜像。

1. 各阶段

[0] RGB-D 预处理与相机里程计

source scripts/foundationpose_env.sh
python scripts/prepare_rgbd_20260915.py

• 输出 output/20260915_171525/rgbd_camera.npz：c2w [352,4,4]、intrinsics、time、valid、method；另有 rgbd_preflight.json、object_assets/。
• 方法：静态背景 RGB-D 里程计，屏蔽皮肤、红蓝物体和画面底部；无闭环、无外部定位真值。
• 相机是头戴的，背景帧间移动约 17 px，里程计不能省略；后面所有"世界系"都指这个里程计世界（首帧相机系）。

[1] Dyn-HaMR 双手重建

python scripts/run_dynhamr_rgbd_20260915.py        # 内部调用 .dynhamr 解释器
python scripts/correct_dynhamr_rgbd.py
python scripts/export_dynhamr_bimanual_rgbd.py
python scripts/render_corrected_dynhamr_rgbd.py     # 可选：多视角回放视频

• run_dynhamr_rgbd_20260915.py 把 rgbd_camera.npz 写成 ViPE 文件格式（rgbd_cameras/{pose,intrinsics}/），然后跑上游 run_opt.py：data=video_vipe is_static=False model.opt_scale=False run_opt=True run_prior=True run_vis=True +data.vipe_pipeline=dynhamr_cameras，Hugging Face / Torch 缓存离线（.hf_cache、.torch_cache），EGL 渲染。原始结果在 output/20260915_171525_dynhamr/optimization/，逐帧检测在 dataset/dynhamr/track_preds/<seq>/{000,001}/。
• correct_dynhamr_rgbd.py → corrected/prior/20260915_171525_000000_world_results.npz、comparison_joints.npz、validation.json。腕与手指旋转做合法旋转空间局部加权平均（σ 1.2 帧），平移高斯 σ 1.5 帧（用未来帧，非实时滤波）。腕位置二阶差分 RMS 左 5.38→0.65、右 6.04→0.67 mm。这一步的 RGB-D 深度门槛把所有帧都拒了（depth_accepted_frames = 0），深度修正实际在 [4] 完成。
• export_dynhamr_bimanual_rgbd.py → human_joints_{left,right}.npz：joints [352,21,3]（腕相对、世界朝向）、wrist_world、time、detection_valid；并把 rgbd_camera.npz、object_assets/ 复制进 _dynhamr 目录供后续使用。
• 诊断（只读）：diagnose_dynhamr_rgbd.py（diagnosis/report.md）、diagnose_yesterday_hand_depth.py（留出像素深度残差，output/hand_depth_diagnosis_20260915/）。

[2] L20 重定向

MUJOCO_GL=osmesa .dex/bin/python scripts/retarget_l20_video.py \
  --input output/20260915_171525_dynhamr/human_joints_right.npz \
  --output-dir output/20260915_171525_dynhamr/l20_right_stable --side right
MUJOCO_GL=osmesa .dex/bin/python scripts/retarget_l20_video.py \
  --input output/20260915_171525_dynhamr/human_joints_left.npz \
  --output-dir output/20260915_171525_dynhamr/l20_left_stable --side left

• dex-retargeting 0.5.0 PositionOptimizer，16 个独立关节，其余按原 URDF 线性 mimic 精确展开（l20_consistent_optimizer.py 修正了 0.5.0 目标函数与梯度不一致）。离线平滑 --sigma 2.5 帧。
• 输出：motion.npz（腕位姿 + 关节角）、trajectory.csv、l20_{side}.xml / l20_moving.xml（MuJoCo）、l20_dex.urdf、dex_config.json、retarget_validation.json（指尖拟合误差、最大关节步长、限位越界、mimic 误差、Pinocchio 与 MuJoCo FK 一致性）。日志 retarget_{side}.log。
• 手指重定向只用关节方向，所以 [4] 的相似变换配准不需要重跑重定向（register_hands_rgbd.py 只改写 motion.npz 里的腕位置）。

[3] FoundationPose 物体跟踪与碰撞资产

source scripts/foundationpose_env.sh
python scripts/track_yesterday_boxes.py       # → output/foundationpose_spider_20260915/foundationpose_objects.npz, foundationpose_overlay.mp4
python scripts/decompose_yesterday_boxes.py   # → output/foundationpose_spider_20260915/collision/{upper,lower}_NNN.obj（CoACD ≤20 块，初版，prepare 用）
python scripts/build_box_collision_v2.py      # → output/collision_fix_20260915/collision_v2/（修 T 形边后的封闭 CAD *_closed.ply + 不限块数 CoACD + manifest.json，fix/smooth 用）
python scripts/build_palm_collision_v2.py     # → output/collision_fix_20260915/hand_collision/（L20 手部网格 CoACD + manifest.json）

• 逐帧模型法 RGB-D 位姿，两个 STL 各自跟踪；T_world = c2w @ T_cam，c2w 来自 [0]。
• 接受判据（非外部真值）：可见颜色像素 > 500、投影覆盖 > 65%、重叠像素深度中位残差 < 20 mm。红盒 307/352 帧接受，未接受帧插值；蓝盒 177/352，第 177 帧后遮挡，保持最后可靠位姿并停止作为接触目标来源。
• 实测噪声：静止红盒逐帧 2nd-diff 5.3 mm、0.56°；遮挡时静止物体会漂 2 cm。这些在 [4] 的物体参考自洽里处理。
• 环境验证：python scripts/verify_foundationpose_setup.py，说明见 FOUNDATIONPOSE_SETUP.md。

[4] 手物配准、物体参考自洽、SPIDER 任务构建

按下面顺序，5 条命令：

source scripts/foundationpose_env.sh
# ① 配准（默认：腕对齐，原始里程计相机）→ output/20260915_171525_dynhamr/registered/
python scripts/register_hands_rgbd.py
# ② 任务初版（供物体自洽读取手 / 桌面 / 接触目标）
HF_SPIDER_OUT=$PWD/output/registered_spider_20260915 \
HF_HAND_BASE=$PWD/output/20260915_171525_dynhamr/registered \
python scripts/prepare_yesterday_spider.py
# ③ 物体参考物理自洽（输入/输出路径写死：registered_spider_20260915 + registered/ → final_spider_20260915/）
python scripts/smooth_object_reference.py
# ④ 配准第二遍：指根对齐 + 平滑后的相机 → output/20260915_171525_dynhamr/aligned/
HF_REG_OUT=$PWD/output/20260915_171525_dynhamr/aligned \
HF_CAMERA_FILE=$PWD/output/final_spider_20260915/rgbd_camera_smooth.npz \
HF_ALIGN=mcp python scripts/register_hands_rgbd.py
# ⑤ 最终任务（同目录里已有 ③ 写好的自洽物体参考）
HF_SPIDER_OUT=$PWD/output/final_spider_20260915 \
HF_HAND_BASE=$PWD/output/20260915_171525_dynhamr/aligned \
python scripts/prepare_yesterday_spider.py

① register_hands_rgbd.py（三项刚体/相似修正，不改手指关节；registration.json）

1. 世界系：Dyn-HaMR world 与里程计 world 差常量平移 (−0.048, −0.023, −0.115) m，模 12.6 cm，逐帧标准差 < 4 mm。旧流程当同一个 world 用，手物错位 12.6 cm，这是此前腕修正量 8–10 cm 的主因。
2. 尺度：MANO 手在错的深度上与图像轮廓重合（渲染/皮肤面积比 ≈ 1.0），说明真手比 MANO 大；绕相机中心常量缩放，右 1.105、左 1.047，轮廓不变、深度对齐。
3. 残余深度：沿腕射线的逐帧留出像素残差，σ 2 帧平滑。留出残差右 42→9.4 mm、左 20→10 mm。 环境变量：HF_ALIGN（wrist | mcp）、HF_CAMERA_FILE、HF_REG_OUT。

② / ⑤ prepare_yesterday_spider.py：由深度拟合桌面（z-up 是桌面法线，不是 IMU 重力）；逐指尖选最近可观测物体生成可切换接触目标（进入 25 mm / 释放 35 mm）；有界关节/腕平移热启动。输出 datasets/processed/current/l20/bimanual/boxes/{scene_act.xml, task_info.json, 0/trajectory_kinematic_act.npz}、reference_video_rate.npz、config.json、model_{side}/l20_{side}.xml、object_reference.npz、preparation.json。collision/、foundationpose_objects.npz 缺省时符号链接到 foundationpose_spider_20260915。环境变量：HF_SPIDER_OUT、HF_HAND_BASE。

③ smooth_object_reference.py：物体只允许两种状态。静止段（0.5 s 窗内位移 < 6 mm、旋转 < 2°、无手接触）冻结在"深度共识"位姿，深度驱动分裂（连续 ≥ 9 帧比原观测差 3 mm 判定真动过），贴桌吸附只在深度残差不变差时接受（深度拟合的桌面只准到 ~1 cm）；握持段（≥ 2 指尖进入 25 mm）在腕系 σ 4 帧平滑后随手刚性运动，比纯平滑差 > 1 mm 则退回；自由段 σ 2；里程计 c2w σ 2。红盒 2nd-diff 4.7→1.5 mm，蓝盒 8.8→2.6 mm，深度残差不劣于原始。输出 foundationpose_objects.npz（同 schema）、rgbd_camera_smooth.npz、object_segments.npz、object_smoothing.json。

④ HF_ALIGN=mcp：L20 比缩放后的人手大 35–60%，差异几乎全在手掌（腕到指根 148 vs 90 mm）。改为 L20 指根中心对齐人手指根，腕自动后退 58–61 mm；人手指尖（接触目标）不变。L20 base 系约定已数值验证（landmark_world = wrist_R @ local + wrist_pos，误差 0）。

[5] 碰撞修复 + 桌面约束 + 平滑投影 → 最终运动学参考

source scripts/foundationpose_env.sh
export HF_FIX_OLD=$PWD/output/final_spider_20260915 \
       HF_FIX_OUT=$PWD/output/final_collision_fix_20260915 \
       HF_WRIST_WEIGHT=200 HF_MARGIN=0.0025 HF_TABLE=1 \
       SPIDER_TASK_OUT=$PWD/output/final_collision_fix_20260915
python scripts/fix_yesterday_hand_collision.py                 # 修复
python scripts/verify_fix_interpolation.py --video --buffer    # 视频率状态检查 + 投影
python scripts/verify_fix_interpolation.py --buffer            # 400 Hz 插值 4681 步检查 + 投影（物体固定）
python scripts/audit_collision_fix.py                          # 独立审计 → validation.json
python scripts/render_collision_fix.py                         # hand_collision_before_after.mp4

export HF_SMOOTH_OUT=$PWD/output/final_smooth_20260915
python scripts/smooth_project_reference.py                     # 平滑 + 联合投影
export HF_FIX_OUT=$HF_SMOOTH_OUT SPIDER_TASK_OUT=$HF_SMOOTH_OUT
python scripts/verify_fix_interpolation.py --buffer
python scripts/audit_collision_fix.py
python scripts/render_collision_fix.py

• fix_yesterday_hand_collision.py：解析接触雅可比 + 精确 mimic，逐帧最小改动求解，目标 = 接触目标 + 腕先验（HF_WRIST_WEIGHT，默认 25，本链 200）+ 关节限位；间隙放进求解器（HF_MARGIN，默认 0.5 mm，本链 2.5 mm）而不是事后投影（事后投影曾在 201–203 帧产生 88 mm 跳变）；HF_TABLE=1 把桌面变成硬约束（floor conaffinity 3）。碰撞体来自 collision_v2/ + hand_collision/。
• verify_fix_interpolation.py / audit_collision_fix.py：分别检查视频率与 400 Hz 插值状态、全连杆碰撞、限位、连续性和精确闭合 CAD 采样探针（CoACD 近似之外的独立检查）。都吃 HF_FIX_OLD / HF_FIX_OUT / HF_TABLE。
• smooth_project_reference.py：腕位置高斯 σ 2 帧、腕旋转 SO(3) 局部加权均值 σ 2、16 个独立手指关节 Savitzky–Golay（窗 11、二阶）后精确 mimic 展开、物体不动；再逐帧最小改动投影：线性化接触距离 ≥ 2.5 mm（盒 + 桌）、关节限位、相对上一帧步长上限（8 mm / 7° / 8.6°）。环境变量 HF_SMOOTH_OUT HF_SIGMA_POS HF_SIGMA_ROT HF_SG_WINDOW HF_CLEARANCE。
• 交付目录 output/final_smooth_20260915/（README 在内）：reference_video_rate.npz、datasets/.../0/trajectory_kinematic_act.npz（400 Hz）、validation.json、smoothing_report.json、hand_collision_before_after.mp4。交互回放：python scripts/play_spider_result.py --directory output/final_smooth_20260915 --mode reference（空格暂停，← → 逐帧）。

指标（右 / 左）	修复后（final_collision_fix）	平滑投影后（final_smooth）
腕位置二阶差分 RMS	3.05 · 3.15 mm	0.41 · 0.37 mm
手指二阶差分 RMS	1.49° · 1.33°	0.38° · 0.32°
右腕修正中位 / 118–235 帧段	11 / 45 mm	—
接触间隙中位	7.1 · 5.7 mm	8.0 · 7.8 mm
最大穿透（盒 + 桌，含 400 Hz 插值）	0	0
精确 CAD 探针最大侵入（红 / 蓝）	—	0.00 / 0.00 mm

[6] SPIDER 物理滚动

export SPIDER_SRC=$PWD/output/final_smooth_20260915 \
       SPIDER_TASK_OUT=$PWD/output/final_spider_run_20260915 \
       HF_FIX_OLD=$PWD/output/final_spider_20260915
source scripts/foundationpose_env.sh
python scripts/configure_spider_task.py                       # 复制任务 + 施加物理参数 → physics_parameters.json
.spider/bin/python scripts/run_yesterday_spider.py --pilot    # 冒烟：80 步、32 样本、2 轮
.spider/bin/python scripts/run_yesterday_spider.py            # 全程：64 样本 × 3 轮，horizon 0.4 s，ctrl_dt 0.1 s，4680 步
.spider/bin/python scripts/audit_collision_physics.py         # CPU 独立碰撞逐步检查 → physics_validation.json, physics_motion.npz
.spider/bin/python scripts/check_spider_dynamics_replay.py    # 保存控制量在全新 GPU 世界 + CPU 重放 → control_replay.json
python scripts/audit_spider_dynamic_surfaces.py               # 原始手部可视网格 vs 精确封闭 CAD 探针 → dynamic_surface_validation.json
python scripts/render_collision_fix.py --physics              # spider_collision_rollout.mp4（原视频 / 运动学参考 / 物理结果）
python scripts/play_spider_result.py --directory output/final_spider_run_20260915 --mode physics   # 交互回放

• configure_spider_task.py：从 SPIDER_SRC 复制 scene_act.xml、task_info.json、trajectory_kinematic_act.npz、reference_video_rate.npz、config.json（只改 dataset_dir），并写入经 GPU/CPU 短段重放选出的物理设置（仿真假设，非硬件标定）：求解 80 / 线搜索 50；所有 geom solimp .9 .95 .001 .5 2、solref .02 1；手/物/桌 margin 4 mm gap 2 mm（2 mm 提前激活）；腕平移 kp 500 kv 30 ±20 N，腕旋转 kp 15 kv 2 ±2 Nm，手指 kp 4 kv 0.15 ±0.1 Nm（HF_FINGER_KP / HF_FINGER_KV / HF_FINGER_TORQUE 可改）；物体执行器零增益（真实滚动无物体辅助）；桌面与手碰撞。SPIDER_CONFIG_OVERRIDES='{"contact_rew_scale": 8, "num_samples": 128}' 可覆盖 SPIDER config。
• run_yesterday_spider.py：调用上游 third_party/spider/examples/run_mjwp.py（MuJoCo Warp 采样优化），本地补丁：双手含被动关节的奖励权重划分、跨物体换握时关闭"单手固定物体"启发式、非有限状态即停。物体质量 0.12 kg、摩擦 0.8 是假设。上游 SPIDER 的其余本地修改（辅助弹簧力公式、接触奖励权重、重采样漏控制量、GPU 接触参数）随 third_party/spider 源码快照保留。
• 结果（final_spider_run_20260915/README.md）：

指标	值
物理步 / 全部有限	4680 / 是
最大手物穿透（CPU 独立检测）/ CAD 探针	0 / 0 mm
实际接触步数（< 1 mm）	20 / 4680
红盒观测段位置误差均值 / 旋转误差	93 mm / 8.1°（0–5 s 跟得住，6 s 参考抬起后物理盒留桌上）
蓝盒观测段位置误差均值 / 旋转误差	39 mm / 123°（1–2 s 参考翻转，物理盒不翻）
保存控制量独立 GPU 重放最大状态差	0.456

结论：参考干净之后，失败模式变清楚，手不真正合拢握住物体，位置伺服跟参考就是"悬着"。参考间隙 0.5 mm + contact_rew_scale 8 + 128 样本 × 5 轮的变体（output/final_spider_run_v2_20260915/）无实质变化（接触步 20→5），说明不是采样量问题，是参考/奖励只要求指尖到表面、不要求夹紧。

2. 已知问题与候选方向（运动学 / SPIDER 线）

• 接触语义：L20 比人手大，接触目标取人手指尖最近点，右手 118–235 帧腕仍要抬 45 mm 才能不进盒。候选：用 L20 指尖自身最近点做目标、按手长比例外推、或该段降接触权重。
• 夹紧：参考里给 on-接触帧手指多屈几度（目标进入物体一点）；手指力矩上限 0.1→0.3 Nm / kp 4→8；或奖励加法向力项。这些都改变仿真假设，需要决定。
• 右手指尖到红盒表面配准后仍约 4 cm（遮挡下 MANO 手指姿态误差），接触目标本身有此量级不确定性。
• 蓝盒 177 帧后无观测；红蓝相对装配不是已验证事实。
• 未验证真机；未做力/摩擦标定。

3. 换一段新视频要改什么

脚本里序列名和输入路径大多写死为 20260915_171525（或 yesterday 命名），环境变量只覆盖输出目录。新视频需要：

1. 放到 docs/<seq>/{color.mp4, depth/, intrinsics.json}，物体 CAD 放 docs/。
2. 改这些脚本里的常量：prepare_rgbd_20260915.py（SRC/OUT）、run_dynhamr_rgbd_20260915.py（SEQ）、correct_dynhamr_rgbd.py / export_dynhamr_bimanual_rgbd.py（BASE/SRC）、track_yesterday_boxes.py（SRC/OUT、STL 名）、decompose_yesterday_boxes.py（STL 名）、smooth_object_reference.py（SRC/OLD/HAND/OUT）、register_hands_rgbd.py（BASE）。
3. prepare_yesterday_spider.py 里颜色→CAD 映射（红 = 上半/upper，蓝 = 下半/lower）和物体质量 / 摩擦假设。
4. 之后 [4]–[6] 只靠环境变量指路径，不用改代码。

4. 脚本索引

阶段	脚本	解释器	输入 → 输出	环境变量 / 参数
0	prepare_rgbd_20260915.py	.venv	docs/ → output//rgbd_camera.npz	—
1	run_dynhamr_rgbd_20260915.py	.venv（内部 .dynhamr）	color.mp4 + rgbd_camera → _dynhamr/optimization	—
1	correct_dynhamr_rgbd.py	.venv	optimization → corrected/prior/*_world_results.npz	—
1	export_dynhamr_bimanual_rgbd.py	.venv	corrected → human_joints_{left,right}.npz	—
1	render_corrected_dynhamr_rgbd.py、diagnose_dynhamr_rgbd.py、diagnose_yesterday_hand_depth.py	.venv	可视化 / 诊断（只读）	—
2	retarget_l20_video.py	.dex	human_joints_{side}.npz → l20_{side}_stable/	--input --output-dir --side --sigma
3	track_yesterday_boxes.py	.venv (foundationpose_env)	RGB-D + STL → foundationpose_objects.npz	—
3	decompose_yesterday_boxes.py、build_box_collision_v2.py、build_palm_collision_v2.py	.venv	STL / L20 网格 → CoACD 凸块	—
4	register_hands_rgbd.py	.venv	human_joints + rgbd_camera → registered/ 或 aligned/	HF_ALIGN HF_CAMERA_FILE HF_REG_OUT
4	prepare_yesterday_spider.py	.venv	手 + 物体 → SPIDER 任务目录	HF_SPIDER_OUT HF_HAND_BASE
4	smooth_object_reference.py	.venv	registered_spider + registered → final_spider（物体参考）	—
5	fix_yesterday_hand_collision.py	.venv	任务目录 → 无穿透参考	HF_FIX_OLD HF_FIX_OUT HF_WRIST_WEIGHT HF_MARGIN HF_TABLE；--pilot
5	verify_fix_interpolation.py	.venv	视频率 / 400 Hz 检查投影	HF_FIX_OLD HF_FIX_OUT HF_TABLE；--video --buffer
5	audit_collision_fix.py	.venv	独立审计 → validation.json	HF_FIX_OLD HF_FIX_OUT HF_TABLE
5	smooth_project_reference.py	.venv	修复参考 → 平滑投影参考	HF_FIX_OLD HF_FIX_OUT HF_SMOOTH_OUT HF_TABLE HF_SIGMA_POS HF_SIGMA_ROT HF_SG_WINDOW HF_CLEARANCE
5/6	render_collision_fix.py	.venv	三栏对比视频	SPIDER_TASK_OUT HF_FIX_OLD；--physics
6	configure_spider_task.py	.venv	参考目录 → SPIDER 任务 + 物理参数	SPIDER_SRC SPIDER_TASK_OUT HF_FINGER_KP/KV/TORQUE SPIDER_CONFIG_OVERRIDES
6	run_yesterday_spider.py	.spider	任务目录 → trajectory_mjwp_act.npz	SPIDER_TASK_OUT；--pilot --steps
6	audit_collision_physics.py、check_spider_dynamics_replay.py	.spider	物理轨迹审计 / 控制量重放	SPIDER_TASK_OUT
6	audit_spider_dynamic_surfaces.py	.venv	精确 CAD 探针	SPIDER_TASK_OUT
6	play_spider_result.py	.venv	交互回放	--directory --mode {reference,physics} --check

5. 历史 / 对照目录（不要误用）

目录	说明
output/20260915_171525/	HandFlow 分支的双手初版（镜像左手 + ICP 物体位姿），已被 Dyn-HaMR + FoundationPose 链路取代
output/foundationpose_spider_20260915/	首次全链路（配准前）。手物错位 12.6 cm，Spider 红盒误差 61 mm
output/collision_fix_20260915/	配准前的碰撞修复，腕修正中位 82 / 100 mm；其 collision_v2/、hand_collision/ 资产仍被后续目录符号链接
output/registered_collision_fix_*_20260915/	配准后三个修复变体，推荐 w200m25（腕先验 200 + 内置 2.5 mm 间隙）
output/desktop_smooth_fix_20260915/	smooth_table_constrained.py 只抬腕出桌面，手盒穿透回到 24.5 mm，失败对照
output/final_smooth_c05_20260915/、output/final_spider_run_v2_20260915/	间隙 0.5 mm + 接触奖励 8 + 128 样本变体，无实质变化
output/spider_dynamics_fix_20260915/	Codex 的 SPIDER 动力学修复轮（物理参数从这里选出）