实验驱动的文档追溯流程。在设计假设验证实验前，先将假设、实验方案、预期结果写入文档； 实验/测试完成后，将实际结果、分析、结论、next-step 写回文档。确保每一轮实验可追溯。 Use when running hypothesis-driven experiments, ablation studies, debugging investigations, or any iterative test-analyze-iterate workflow.
将"假设 → 实验设计 → 执行 → 结果 → 分析 → 下一步"全流程记录到项目文档中， 做到任何人（包括未来的自己）都能复现思路和决策依据。
在设计任何实验之前，必须先回答以下问题。如果 Phase 0 不通过，禁止进入 Phase 1。
核心问题：π(observation) → action 是单值函数吗？
Checklist：
π(s) 不是单值函数 → MSE 收敛到无意义的均值(obs, action) 与评估时的 流程是否匹配？
(obs → predict → execute)如果发现 observation 不完备：
教训来源：在 Franka pick-cube 实验中，cube 位置每 episode 随机化但未加入 observation， 导致 π(s)→a 不是单值函数。历经 10+ 组实验（DART、闭环 IK、noise aug、history、时序修复） 全部 0% 成功率，最终才追溯到 problem formulation 层面的缺陷。 所有后续调优都是在一个不可解的问题上做无用功。
在编写代码或启动实验之前，先更新实验文档：
模板：
## Exp-<ID>: <简短标题>
### Phase 0 确认
- 观测完备性: <observation 包含哪些信息，是否覆盖所有影响 action 的变量>
- 随机化变量: <哪些变量被随机化，是否在 observation 中>
### 假设
<一句话描述假设>
### 实验方案
- 脚本: `<path>`
- 关键参数: <table or list>
- 对照组: <baseline>
- 变量: <what changes>
### 预期
- 假设成立: <expected metrics>
- 假设不成立: <expected metrics>
### 结果
（待实验）
### 分析
（待实验）
### 结论与 Next Step
（待实验）
当实验预估运行时间 > 10 分钟 时，先用极小参数跑一次 smoke test：
n_episodes=2, max_steps=50, n_steps=10 等，保证 1-2 分钟内完成# 示例：全量实验前的 smoke test
python 03_eval_act.py \
--n-episodes 2 --max-steps 50 \
--save /output/smoke_test
# 检查：exit code=0, eval_summary.json 存在, 关键字段合理
只有 smoke test 通过后，才启动全量实验。如果 smoke test 失败， 在文档调试表格中记录问题并修复，避免浪费长时间等待。
| 轮次 | 问题 | 修复 | loss | eval 结果 |
|---|---|---|---|---|
| r1 | ... | ... | ... | ... |
| r2 | ... | ... | ... | ... |
实验完成后，必须回填文档中的"待实验"部分：
在文档顶部或专门章节维护一个实验总览表，方便快速回顾：
| Exp | 假设 | 状态 | 关键结果 | 结论 |
|---|---|---|---|---|
| F1 | IK 数据 100% 成功 | ✅ done | 200/200=100% | Franka IK 稳定 |
| F3 | BC E1 N=5 > SO-101 | ✅ done | 90% vs 0% | 7-DOF 冗余有效 |
| F4 | noise aug 改善 shift | ✅ done | 全部下降 | noise 有害 |
每次文档更新时，commit message 包含实验 ID：
F4 noise sweep: experiment design and hypothesisF4 noise sweep results: noise aug harmful on Franka, all sigma degrade E1