science-experiment-runbook

1# 从方案到一次可复现的执行
2 
3## 这一层要守住的三件事
4 
51. **原始数据只进 `data/`，只读。**
6   清洗结果放 `data/clean/`，分析产物放 `experiments/<slug>/<runId>/`。
7   一旦在原始文件上直接改，你永远回不到采集当天的状态——而审稿人问的第一个问题往往就是那个状态。
82. **每次执行都要能被别人重跑。**
9   `science_exp_run` 记的是：脚本内容指纹、输入文件 sha256、输出文件 sha256、
10   Python 与关键库版本、seed、是否允许网络。缺任何一项，这次执行就只是"你跑过一次"。
113. **Python 层默认无网。**
12   数据下载在采集阶段做完，分析阶段不该联网。要联网就显式 `network: true`，
13   记录里会写明——这是给自己留的证据，不是给别人看的仪式。
14 
15## 顺序
16 
17```
18science_study_coach { projectId }             ← 先确认 S2/S3 的门过了
19science_exp_plan  { projectId, effect: … }    ← 样本量与前置条件（若还没做）
20把数据放进 data/
21写 code/run.py                                ← 一个脚本一件事，参数从 argv 进来
22science_exp_run   { projectId, slug, script: 'code/run.py', inputs: ['data/raw.csv'], seed: 42 }
23science_exp_query { projectId, what: 'runs' } ← 确认状态、产物、耗时
24```
25 
26## `science_exp_run` 的字段怎么填
27 
28| 字段 | 什么时候用 | 坑 |
29| --- | --- | --- |
30| `script` | 已有脚本 | 路径必须在课题目录内；`../../x.py` 会被拒 |
31| `code` | 一次性验证 / 小实验 | 会写成 run 目录里的 `run.py`，同样留痕 |
32| `inputs` | 有输入文件 | 相对课题根；文件不存在直接报错，不静默跳过 |
33| `seed` | 任何有随机性的分析 | 写进 `seed.txt` 并导出 `DSH_SEED`；不传就用默认值并记录下来 |
34| `network` | 需要下载/调用 API | 默认 `false`。Python 层会被 hook 拦住；`curl` 子进程拦不住，这一点要在记录里自己注意 |
35| `timeoutMs` | 长任务 | 超时按失败记，不会假装成功 |
36 
37## 失败了怎么办
38 
39失败的执行**也进溯源链**，这是刻意的：一份只记录成功的历史没有诊断价值。
40 
411. 先读 `stderrTail` 和 run 目录里的 `stderr.log`。
422. 分类：代码错（改脚本重跑）／数据错（回去看采集）／环境错（`probeEnv` 对比版本）／超时（拆任务）。
433. **不要**为了让结果出来而降低检验标准、删样本、换主结局。那一步一旦迈出去，后面所有数字都要重做。
44 
45## 复现性检查（交给别人之前）
46 
47- 同一 seed 跑两次，输出文件的 sha256 应完全一致。不一致就说明有未受控的随机源（时间、字典序、并行度、浮点归约顺序）。
48…