Shared Physics Studio 夜间迁移（2026-08-01 历史 runbook）

状态说明：本文记录 2026-08-01 当晚迁移窗口，保留其历史 gate 与时间边界， 不再作为当前 ours residual integration 的训练授权。当前实现以 docs/project/ours_residual_architecture.md 和用户已确认的执行合约为准： 三个 canonical case 先分别完成 fresh 200-epoch partial gate，满足 gate 后可自动 进入各自 fresh 1200-epoch full train；trainer/checkpoint/RMS/eval 均使用 Studio CommonAgent 路径，不复用 reference runtime 或 residual checkpoint。

目标是在 2026-08-01 00:00–07:00（Asia/Shanghai） 内，把当前 Physics Studio 和 xuyuan 的 PHC-X teacher + residual policy 收敛到唯一共享工程 /mnt/cvda_mnt/projects/arthoi4d/。该历史窗口只证明迁移后的代码、算法和统一接口正确； 当晚未跑 full train，不整理全部历史结果，也不删除任何旧路径。当前 full-train 规则见 页首状态说明。

完成条件

07:00 前必须能用证据回答下表。只有产物真实存在才能标记 PASS。

Gate	完成条件
Shared root	共享根可导入 Studio，配置和 submodule 路径不依赖旧工程绝对路径
Ours integration	PHC-X teacher + residual policy 位于 pipeline/physics/ours/，复用作者 trainer/PPO
Tensor parity	固定 fixture 的 teacher/residual observation、action、reward 通过数值对照
Update parity	同一 PPO batch 的 loss、gradient 和一次 parameter update 通过对照
Reload	Studio 保存的 checkpoint 可 reload，reload 前后固定输入输出一致
D3D smoke	一个 canonical D3D case 完成 5 个原生 PPO outer iterations 和短 eval
Common output	短 eval 写出合法 common_rollout.npz、二元 evaluation 和 common-renderer 视频
ARCTIC	必要 ARCTIC 数据已迁入共享根，至少一个固定样本可由新工程读取
Safety	两个源工程没有被修改或删除，现有训练没有被覆盖或中断

本轮不以 reward 收敛或最终 Success 为验收条件。5 iterations 只验证完整训练路径、参数更新、 checkpoint 和统一下游；正式训练在本轮通过后另行启动。

固定路径与边界

只读源路径：

/DATA/intern/hoi4d/projects/zhanbaiting/ArtHOI4D
/mnt/cvda_mnt/xuyuan/project/intermimic-phcx

唯一写入目标：

/mnt/cvda_mnt/projects/arthoi4d

关键数据源：

/DATA/intern/hoi4d/projects/zhanbaiting/ArtHOI4D/data/d3dhoi
/DATA/intern/hoi4d/projects/zhanbaiting/ArtHOI4D/data/partnet
/mnt/cvda_mnt/xuyuan/data/hoi/ARCTIC

当前 D3D canonical full20 入口：

/DATA/intern/hoi4d/projects/zhanbaiting/ArtHOI4D/output/runs/
  d3dhoi_shared_ground_v40_default_hoi_align_s100k_m10k_full20_v001

xuyuan 算法审查入口：

/mnt/cvda_mnt/xuyuan/project/intermimic-phcx/isaacgym/src/intermimic/env/tasks/phcx_base.py
/mnt/cvda_mnt/xuyuan/project/intermimic-phcx/isaacgym/src/intermimic/env/tasks/articulated_target_ext.py
/mnt/cvda_mnt/xuyuan/project/intermimic-phcx/scripts/run_ig_ablation_studio3.py

严格遵守：

• 不对两个源路径执行代码编辑、格式化、Git 操作、移动或删除。
• 不使用 rsync --delete，目标路径已有内容先列清单，不覆盖来源不明文件。
• 两台机器使用各自本地 Conda。源代码和 config 不能硬编码 Python executable。
• TORCH_EXTENSIONS_DIR、Python cache 和 adapter 临时文件写本机 /tmp。
• 不停止当前 CoDA/InterMimic 队列；GPU smoke 只能使用检查后确认空闲的 0–5 号卡。
• 不复制全部 output/、data/prev、legacy、wandb、cache、临时目录或失败 run。
• 不在迁移过程中顺手重构无关代码。

最终代码边界

Studio 继续唯一负责：

• case.json + result.pt canonical input；
• shared humanoid、full-J articulated asset、ground/support 和 reset；
• reference timeline、contact、common rollout；
• Success/Fail evaluator、common renderer 和 Viser。

xuyuan 中只迁移 PHC-X teacher + residual policy 的算法部分：

pipeline/physics/ours/
  __init__.py
  policy.py     # frozen PHC-X teacher 与 residual network
  task.py       # residual observation、reward、action composition
  train.py      # 调用作者 InterMimic trainer/PPO/buffer/GAE
  run.py        # Studio train/eval/checkpoint 边界

允许直接 import InterMimic/PHC-X 的作者实现；禁止复制或重写简化版 PPO/trainer。不要迁入 xuyuan 的独立 manifest、scene loader、asset loader、renderer、evaluation 或 result.pkl 下游。算法代码如果 依赖这些旧边界，应在 run.py/task.py 做最小输入替换，不能在 Studio 内保留第二条 runtime。

00:00–07:00 执行表

00:00–00:20：冻结证据

1. 记录两个源工程的 Git HEAD、branch、submodule commit、git status --short 和 dirty diff checksum。
2. 记录必要 checkpoint 的路径、大小和 SHA256。
3. 检查目标路径是否已有文件；非空时只记录并增量补齐，不删除。
4. 检查 GPU 0–5 和现有训练进程；把可用 GPU 写进状态报告。
5. 创建本轮产物目录：

/mnt/cvda_mnt/projects/arthoi4d/output/verification/shared_migration_20260801/

产物至少包括 source_inventory.txt、checksums.txt 和 gpu_inventory.txt。

00:20–01:10：后台迁移，前台不停工

并行启动两类 rsync，先 --dry-run，确认目标后再正式执行。局域网/NFS 迁移不使用压缩。

代码白名单：

.git/ .gitmodules configs/ docs/ pipeline/ scripts/ tests/

submodule 只复制本轮导入和 smoke 所需的源码、配置、asset 与 checkpoint；排除其 outputs、wandb、 cache 和编译产物。数据白名单：

data/d3dhoi/
data/partnet/
data/contact_regions/
data/physics_cache/
ARCTIC 必要数据与 PHC-X teacher/residual checkpoint
当前 canonical full20 的 case.json/result.pt 及它们实际引用的 contact/chunk 文件
当前有效、后续仍需比较的 physics checkpoints/results

代码复制结束后立即进入下一阶段；大数据继续后台传输，不等待无关历史数据。

00:40–01:20：共享 Studio 基线 smoke

与数据迁移并行：

1. 从共享根导入 pipeline.physics。
2. 严格加载一个 D3D case.json + result.pt。
3. 校验 full-J articulated scene、shared humanoid 和 reference timeline。
4. 加载一个现有 common rollout，执行 evaluator 和 renderer。
5. 搜索新工程正式运行路径中的两个旧绝对工程路径；测试 fixture/迁移记录可以包含，runtime/config 不得包含。

这个阶段若失败，先修共享路径和缺失文件，不能开始改算法来掩盖基础迁移错误。

01:20–03:20：迁移 ours 算法

1. 先从 xuyuan 原代码画出最短调用链：teacher obs/action → residual obs/network/action → reward → 作者 PPO update。
2. 原样迁移算法数学和 checkpoint layout，不做命名美化、结构大改或超参数调整。
3. 使用 Studio 提供的 canonical human/object/contact tensors 替换其独立 loader。
4. 使用 Studio full-J object；active joint 只决定监督目标，inactive free joints 保持被动物理，不固定， drift 只诊断、不判 Fail。
5. reset 必须复现训练协议：采样参考帧 t 时，人和对象都重置到 reference 的绝对状态 q(t)； stateInit=Start eval 从 case.json 的绝对初始值开始。
6. 保留作者 PHC-X teacher、normalizer、action scale、PPO/GAE/buffer、horizon、minibatch、curriculum 和 checkpoint 语义；本轮只把 env 数量和 outer iterations 缩小用于 smoke。

03:20 时必须已有可 import、可构造 task/network 的 Studio ours 路径。若还在大规模重写，立即停止重写， 改为直接复用作者模块并只写边界 adapter。

03:20–04:40：固定 fixture 数值等价

从同一份原始输入、seed、checkpoint 和 normalization statistics 分别运行旧 xuyuan 路径与新 Studio 路径，保存并比较：

对象	验收
teacher observation/action	shape、顺序一致；max_abs_error <= 1e-6
residual observation/action	shape、顺序一致；max_abs_error <= 1e-6
action composition	teacher、residual scale、最终 action 一致
reward	每个分量、权重、总和、termination boolean 一致
one PPO update	loss、gradient、parameter delta 一致；确定性张量 <=1e-6
short simulation	reset/done/event sequence 一致；PhysX state 目标 <=1e-4

不得只比较最终 scalar reward。遇到 PhysX 非确定性时，先要求进入 simulator 前的 canonical state、obs、 action 和 reward 数学严格一致，再记录 state tolerance；不能用“随机性”解释明显的坐标系、root height、 joint order 或 normalization 错误。

把比较结果写入：

output/verification/shared_migration_20260801/parity.json
output/verification/shared_migration_20260801/parity.md

04:40–06:10：端到端最小验证

优先并行运行：

• GPU A：一个 canonical D3D case，16–32 env，作者完整 PPO 路径，5 个 outer iterations。
• GPU B：固定 fixture/checkpoint reload 与 deterministic 32–64 frame eval。
• CPU/空闲 GPU：读取一个已迁移的 ARCTIC 样本，校验路径、shape、FPS、人体/对象 reference。

D3D smoke 必须完成以下整条链：

canonical input
→ Studio full-J env
→ PHC-X teacher + residual policy
→ author PPO 5 iterations
→ checkpoint save/reload
→ deterministic eval
→ common_rollout.npz
→ binary evaluation
→ common renderer video

检查 loss/reward 为有限数值、参数确实更新、checkpoint reload 前后固定输入输出一致。视频必须肉眼抽查 首帧、中间帧和末帧，排除 T-pose、黑屏、错误 reset 后继续录制、人体/物体错位和 joint order 错误。

06:10–06:40：共享运行检查

1. 再次搜索 runtime/config 中的旧工程绝对路径。
2. 验证所有 Python/cache/temp 路径均可由机器本地环境提供，没有写进源码。
3. 验证输出使用唯一 run 目录，不覆盖当前实验。
4. 若可登录第二台机器，从同一共享根执行 import、canonical load 和 checkpoint load smoke；否则明确记为 NOT_RUN，不得伪报 PASS。
5. 记录最终代码 HEAD/dirty diff 和 submodule commit；后续 full train 启动前冻结该状态。

06:40–07:00：结果封板

将最终报告写入：

/mnt/cvda_mnt/projects/arthoi4d/output/verification/shared_migration_20260801/report.md

报告只需要：

• 上述九个 Gate 的 PASS / FAIL / NOT_RUN；
• 实际运行命令；
• 关键数值误差；
• checkpoint、common rollout、evaluation、视频的绝对路径；
• 未完成项的真实 blocker 和下一条最短动作；
• 两个只读源路径的最终 Git 状态对照，证明没有被修改。

冲刺规则

• 单个问题连续 20 分钟没有缩小范围，就换成更直接的 A/B fixture 或原模块 import，不继续猜。
• 不因 smoke reward 低而启动长训练；先证明训练实现和数据流正确。
• 不因代码“丑”而重构。今晚只保留正确、最短、可验证的正式路径，清理另开任务。
• 不为旧输出增加 runtime fallback；缺失数据用一次性迁移补齐。
• 可并行做只读审查、数据复制和 GPU smoke，但共享 checkout 的代码编辑/Git 操作只允许一个 writer。
• 07:00 到达时不得用“正在训练”代替结果；停止新增工作，写出真实 Gate 状态和全部产物路径。

迁移后再做（仅指 2026-08-01 历史窗口）

以下内容明确不占用本轮 7 小时：

• full train 与收敛比较（当前任务已在 partial gate PASS 后授权自动执行）；
• full20 批量实验；
• 重复运行同一 case 的多-seed评测；
• 全量历史 output/legacy 搬运；
• 无关 Physics Studio 重构和测试清理；
• 删除 /DATA/.../ArtHOI4D 或 xuyuan 原工程。

只有用户检查本轮报告并明确确认后，才允许归档或删除旧路径。该限制不阻止当前任务按 页首状态说明执行 fresh partial/full train。