跳转至

Implementation Details

最后更新：2026-07-26。

本页记录复现实验所需的源码位置、训练目录和 artifact 布局。它不定义实验问题、 baseline 排名或论文结论；这些内容只在 Teacher Model 和 Results 中维护。

Teacher Model artifacts

用途 路径
InterMimic official woodchair reproduction output/auto_experiments/20260717_intermimic_official_single_woodchair_5000e/
strict OmniGrasp epoch 500 output/auto_experiments/20260724_v20_human400_strict_hmean25_et50cm_500e/
strict OmniGrasp epoch 600 output/auto_experiments/20260724_v20_human400_strict_hmean25_et50cm_resume500_600e/
strict OmniGrasp epoch 700 output/auto_experiments/20260724_v20_human400_strict_hmean25_et50cm_resume600_700e/
historical frozen PHC-X direct tracking diagnostic output/auto_experiments/20260711_free_object_phcx_full/
current full-sequence InterMimic output/auto_experiments/20260724_intermimic_latest_motion_full_0_596_scratch_5000e/
InterMimic official teacher-specialist zero-shot output/auto_experiments/20260725_intermimic_cup_full_sub2_zero_shot/
InterMimic official teacher-specialist fine-tune 500e output/auto_experiments/20260725_intermimic_cup_full_sub2_warm_500e/
InterMimic student_new zero-shot output/auto_experiments/20260725_intermimic_cup_full_student_new_zero_shot/
InterMimic student_new fine-tune 500e output/auto_experiments/20260725_intermimic_cup_full_student_new_warm_500e/
InterMimic student_new fine-tune 1000e output/auto_experiments/20260725_intermimic_cup_full_student_new_warm_1000e/
RePHO upstream source submodules/RePHO/
RePHO real-input adapter smoke output/auto_experiments/20260725_repho_cup_adapter/

这些目录保存 checkpoint、log、metrics、rollout 或 adapter artifact。路径存在不等于 实验通过；具体输入 contract、分母、失败原因和可支持的结论回到 Teacher Model 页面 核对。

A2 tracker-correction implementation contracts

本节只说明 A2-R / A2-G 如何在工程上构成、哪些代码实际承担该合同，以及训练前还 缺什么运行时证据。两者都消费同一条冻结的 canonical SMPL-X motion、layout 和 dynamic object identity；它们的 pretrained controller、observation、action composition、reward、termination、PPO runtime 是各自上游方法的合同，不能为了 表面一致而互相改写。因此二者最终是同一任务上的 system-level baseline 比较， 不是只改变 "scene awareness" 的单因素消融。

A2-R: ResMimic-style PHC-X adaptation

当前实现状态： 静态实现和 source-surface 测试已具备；没有 current canonical case 的 Isaac Gym runtime、deterministic rollout 或训练结果。

canonical SMPL-X motion + layout
  -> tools/prepare_omnigrasp_reference.py -> reference.pkl
  -> HumanoidSageResMimicStrictPHCX (Isaac Gym / SMPL-X scene)
  -> frozen PHC-X: human obs [2026] -> base action [153]
  + residual actor: [2026 human + 7 object pose] -> residual [153]
  -> clip(base + residual, -1, 1) -> SMPL-X PD target
  • Actor observation 固定为 2026 + 7 = 2033D：PHC-X human tracking observation 加当前 object xyz + xyzw。它没有 OmniGrasp 的 future/contact feature；1024 object surface points 只用于 ResMimic 的 object tracking reward，不进入 actor。
  • Action 是 released-style 直接 153D normalized residual；没有 latent、tanh gate 或 GRAIL 的 hand primitive。最终 action 为 clip(base + residual)。
  • Reward/termination 固定为 PHC-X human imitation（human termination 0.25 m）与 ResMimic point-cloud object reward：exp(-10 * mean point distance)，object reward weight 2.0，object-far termination 0.3 m。support object 保留，不使用 pregrasp/contact observation。
  • 训练入口强制 4096 env；frozen PHC-X PNN、normalizer、primitive index 均由 task 验证为不可训练。它处于 Omnigrasp/Isaac Gym/rl_games 链内，不依赖 GRAIL/SONIC。
层 实现位置
runner 与 reference conversion tools/run_resmimic_strict_phcx.py；tools/prepare_omnigrasp_reference.py
task、PHC-X bridge、reward/reset submodules/Omnigrasp/phc/env/tasks/humanoid_sage_resmimic_strict_phcx.py；submodules/Omnigrasp/phc/learning/resmimic_strict_phcx.py
residual policy / PPO submodules/Omnigrasp/phc/learning/resmimic_strict_{network_builder,model,ppo}.py；submodules/Omnigrasp/phc/data/cfg/learning/resmimic_strict_phcx.yaml
static contract regression tests/test_resmimic_strict_phcx.py

训练前的最小工程顺序仍是：

  • R0 source-contract audit：记录 ResMimic upstream commit 和 G1/GMT → SMPL-X/PHC-X 的 allowlist；逐项确认 2033D observation、153D direct residual、 point-cloud reward 和 reset/termination 常数。
  • R1 zero-residual parity：在 Isaac Gym runtime 用 residual=0 采样完整 episode，保存 base/final action、PD target、reference time 和 termination trace； 确认 final action 等于 frozen PHC-X base action（允许 only clip-equivalent 差异）。
  • R2 PPO smoke：2 env、1 iteration、24 steps，验证 reward、optimizer 和 checkpoint save/load；它不是新的训练条件。
  • R3 deterministic evaluation：在 canonical full sequence 写出 human/object/ contact/task telemetry，之后才可启动 4096-env 正式训练。

A2-G: GRAIL-style PULSE-X adaptation (GRAIL-Min)

2026-07-26 设计修订： canonical A2-G 改为 GRAIL observation/reward/PPO + frozen PULSE-X reference encoder/decoder + 48D latent residual。完整代码修改计划、 文件清单与验收门槛见 GRAIL–PULSE-X Integration。

当前 canonical path 已实现：

GRAIL actor observation
  -> PPO actor raw residual [48]
  -> 0.1 * residual
canonical SMPL-X current/reference state
  -> PULSE observation [2026]
  -> frozen reference encoder / posterior mean [48]
  -> latent addition
  -> frozen decoder action [153]
  -> name permutation
  -> ActionManager single PD affine
  -> SMPL-X articulated body + 90D hands
层 Canonical 实现位置
frozen encoder/RMS/decoder submodules/GRAIL/imports/SONIC/gear_sonic/envs/wrapper/pulsex_controller.py
GRAIL ↔ PULSE connection submodules/GRAIL/imports/SONIC/gear_sonic/envs/wrapper/manager_env_wrapper.py
actor/config submodules/GRAIL/imports/SONIC/gear_sonic/config/actor_critic/hoi_staged_mlp_aux_pulsex.yaml；gear_sonic/config/exp/manager/universal_token/hoi/advanced_manip_table_smplx_pulsex_minimal.yaml
config/parity/runtime/PPO evidence tools/audit_grail_pulsex_config.py；tools/run_grail_pulsex_acceptance.py；utils/tracking_adapters/grail/pulsex_evidence.py
train preflight/runtime gate/launcher tools/audit_grail_pulsex_preflight.py；tools/audit_grail_pulsex_runtime_config.py；tools/run_grail_pulsex_train.py

advanced_manip_table_smplx_pulsex_minimal 是唯一 canonical A2-G。它保留 official 的 20 policy / 22 critic scene-aware terms、object density 300、mass null、 contact-before sampling、dense object term 20、primary/assist grasp 40/20，以及 0.25 m object gate 与 50-frame contact-failure grace。G1 的 right-primary / left-assist 被 metadata active_hand 的 primary / counterpart assist 路由替换；它不 hard-code 当前 canonical motion 的 left_hand。

human tracking 由 manager_env.config.human_tracking_reward_mode 选择：默认 grail 将当前 six 个 GRAIL human reward 精确合并成一个 runtime term；phcx_global 只替换该 human term 为 PHC-X global imitation formula，并继续使用同一个 GRAIL 14-body command set。它不改变 scene-aware observation、object/grasp reward、 termination、PULSE-X controller 或 PPO；由于 PHC-X 分支的总权重是 1.0 而默认 GRAIL sum 的峰值是 11.5，必须作为单独的 reward-adaptation run 记录。

旧 pnp-table / PHC-X 63D direct residual + 2D primitive path 只保留为 legacy diagnostic。其所有 E0/E1/P0/P1/S0 或旧 Seed-0 evidence 均不能转记为本 A2-G 的 PULSE-X runtime 或训练结果；新的 canonical Seed-0 从 frozen PULSE-X 开始。

手部角色范围与双手边界（reviewed 2026-07-26）

当前 canonical A2-G 只保证单一主操作手任务：canonical pick–carry–place 的 task_roles.json 当前以 active_hand: left_hand 表示左手承担主操作手语义。 这里的「主操作手」是任务语义，而不是把 GRAIL 的官方 right-hand 常数直接换成 left-hand。primary_hand 是后续双手合同中将新增的显式字段；reference 的左右手 contact label 只给出各手何时应接触，不能单独决定哪只手承担任务。

  • 当前固定维度的 role-aware observation（hand–object transform 与 filtered fingertip force）只选择主操作手。因此它保持 GRAIL-Min 的 observation contract， 但不等价于已支持双手 manipulation policy。
  • 当前单手 reward/termination 的等价映射只作用于该主操作手。现有 role_object_tracking_reward 分别计算左右手的 contact-gated GRAIL object reward， 再选择 active_hand 对应结果；这与单手语义等价，但不是“双手平均”。canonical A2-G 的 advanced recipe 以 weight: 20 启用该项；旧 pnp run 的 weight: 0.0 不构成 object-tracking 证据。后续双手改造应重构为一次 object formula，并以实际 simulator contact 的 required-hands logical OR 作 gate；这只适用于“任一任务手 接触即可允许 object tracking”的任务定义。若语义要求双手持续持物，gate 必须为 AND。
  • 后续 GraspFailureAfterContact 的 role-aware 版本只依赖每只任务手的 reference contact label、对应 object–hand contact sensor 和 grace window；它不依赖 current support，不引入 phase graph 或 wrapper 层。advanced canonical 现已为当前单主操作手 实现 primary-role version；完整双手 required-hand version 仍未实现。

后续真正的双手任务是一个独立 work package，不得仅把 active_hand 改为两个手或 用任一 incidental contact label 触发。其最小改动合同为：

  1. 将当前单手 active_hand 合同迁移为显式 primary_hand 与 required_grasp_hands: ["left_hand", "right_hand"]。单手 canonical 使用只含一只 手的列表，双手共同抓取使用两只手；任务 metadata 决定该集合，contact label 只决定 各手的时间 gate。
  2. 实现时，每只 required hand 单独保存 first-reference-contact / has-ever-grasped 状态；任一 required hand 越过 grace window 仍未形成 grasp 即 failure。object tracking 的 contact gate 改为 required hands 的 logical OR。
  3. grasp、finger-direction 与 contact-center shaping 先按手计算，再以新合同中显式 声明的 primary/assist 权重合成；不要使用无条件平均。该权重是 future role contract， 不能声称为 upstream advanced_manip_table 已有的 primary/auxiliary metadata。
  4. 将 policy/critic 的单手 role observation 扩为两手显式项或经过审计的对称编码，并 重新冻结 actor/critic input dimensions、network config、normalizer、static parity 与 PPO smoke。仅修改 reward/termination 而保持单手 observation 不得宣称为双手支持。

因此，A2-G 当前的 minimal scope 是任意单主操作手、单目标物体任务；未来的双手 共同操控、交接或多物体分工均不在该 scope 内。多物体双手任务还需要 [hand, object] 责任合同，不能由上述 2-bit mask 推断。

层 实现位置
conversion、E0/E1/P0/P1/S0 runners tools/convert_grail_smplx_motion_to_grail.py；tools/run_grail_minimal_{e0,e1,p0,p1,s0}.py
runtime binding、reference/trace/gate collectors utils/tracking_adapters/grail/
PHC-X normalizer, body/hand scatter and composition submodules/GRAIL/imports/SONIC/gear_sonic/envs/wrapper/phcx_action_adapter.py
role binding and manager action path submodules/GRAIL/imports/SONIC/gear_sonic/envs/manager_env/task_roles.py；submodules/GRAIL/imports/SONIC/gear_sonic/envs/wrapper/manager_env_wrapper.py
static/runtime contract regression tests/test_grail_*.py

该 legacy PHC-X diagnostic 原计划按顺序通过：

  • E0：frozen config/checkpoint/USD/reference 的 preflight 与 formal clean exit。
  • E1：修复或明确拒绝 loader defect 后，完成 canonical reference replay 与 formal clean exit。
  • P0 / P1 / S0：先验证 PHC-X tensor/PD parity，再验证 zero-residual closed-loop，最后运行 2 env / 1 iteration / 24 steps PPO smoke。
  • train：仅在上述 gates 都通过后运行相同配置的 seeds 0/1/2；各 gate 和 seed 都不构成额外方法条件。

Upstream sanity checks

InterMimic official WoodChair reproduction

该运行只验证 InterMimic 官方训练、packing 与 PPO 路径可以在其官方 WoodChair corrected reference 上收敛；它不使用 PhysHSI canonical motion，也不是 Teacher Model 的 baseline 或结果。4096 env / 500 epochs / 65.01M transitions 的 deterministic evaluation 为 268/268，human MPJPE 为 14.54 cm，object position mean/RMSE 为 7.27 / 8.35 cm，contact P/R/F1 为 0.960 / 1.000 / 0.979。

它的唯一工程意义是：上游环境与训练链路可运行。不得用它支持 current generated motion 的 tracking、contact 或 teacher-success claim。

使用边界

  • 输出目录是 provenance，不是下游 runtime 的状态总线。
  • 新实验先在对应 Experiment 页面冻结输入、gate 和输出 artifact，再把稳定路径补到此页。
  • 不以 checkpoint、log 或目录名单独声明成功；必须有完整 human/object/contact/task telemetry 与固定分母。