# 实验规范

创建人员：Codex  
文件职责：定义通用实验体系的文档结构、实验设计流程、实验执行流程、审计入口和模板使用规则。  
管理规范/模板：项目通用实验体系架构文档；本文件不是模板文档，模板文档放在 `common/exp-doc/*模版.md`。  
引用文件：../../管理系统说明.md；../../体系说明.md；../pro-doc/需求规范.md；../dev-doc/编码规范.md；历史实验总纲、实验设计、实验计划、执行约定已去项目化抽象。

统一依赖：本规范必须同时遵守 `../../全局规范.md` 和 `../project-doc/项目规范.md`；项目本地实验规范可补充流程，但不得违反全局规范、全局项目规范和本体系硬约束。

## 1. 定位

实验是一种事项类型。

实验不是单纯跑脚本，也不是只看 summary。实验必须把一个问题从“为什么要做”推进到“怎么验证、怎么执行、证据在哪里、结论能读到什么程度、是否通过审核”。

实验体系的目标：

1. 让实验目标、背景、原理来源可追踪。
2. 让实验设计能证明总纲里的目标。
3. 让实验执行过程、关键数据、结果包可复核。
4. 让设计和执行都经过审核，具体审核规则见 `实验审核规范.md`。
5. 让总纲、设计、执行日志、审计报告能用统一 ID 串成证据链。
6. 让结论能回写到方法论、需求、代码、数据或下一轮实验。

## 1A. 全局规范和项目本地规范

`common/exp-doc/实验规范.md` 是全局通用实验规范。

所有项目的实验员都必须遵守本文件。每个项目创建实验环境时都必须创建项目本地 `exp-doc/实验规范.md`。项目本地规范默认可以很短，只引用本文件并声明必须遵守；如果补充项目特化规则，不能违反本文件的硬约束。具体流程可以按 1A.1 设计本地版本。

项目本地 `实验规范.md` 即使没有额外项目规则，也必须说明本项目核心实验文档的作用和入口，至少覆盖：`实验总纲.md`、`实验设计.md`、`实验执行日志.md`、`实验存储体系.md`、`实验审计报告.md`、`实验问题记录.md`。这样实验员进入项目后，不需要回头翻 common 文档也能知道本项目实验证据链怎么走。

项目本地规范允许补充：

1. 项目目录映射。
2. 项目专用数据源和结果包路径。
3. 项目专用命名规则。
4. 项目专用实验类型和轻重流程区分。
5. 项目专用角色分工。

项目本地规范不得削弱：

1. 实验必须有目标和边界。
2. 实验设计和执行必须可追踪。
3. 设计和执行必须有审核闭环。
4. 关键来源聊天记录必须能被审核员看到。
5. 结论不得超过证据范围。

如果项目本地规范与 common 规范冲突，必须先修项目本地规范；冲突未解决前，不应把对应实验标为完成。

### 1A.1 本地实验流程优先级

common 实验规范规定底线和默认流程，项目本地 `实验规范.md` 可以设计更贴合项目的实验流程。

本地流程设计必须先满足 common 硬约束：目标和边界清楚、来源聊天记录可见、设计和执行可追踪、设计和执行有审核闭环、结论不过读。

本地流程可以做两类调整：

1. 新增流程：例如新增项目专用样本验收流程、人工复核流程、案例回放流程。
2. 修改默认流程：例如把 common 默认步骤拆分、合并、替换为项目内更合适的步骤。

如果只是新增流程，只要不违反 common 硬约束即可放行。  
如果是修改默认流程，必须在本地 `实验规范.md` 或对应实验设计中写清楚覆盖范围、替换原因、输入输出、关键证据链和审核点。

本地流程一旦设计完成并通过审核，执行时以本地流程为准；审核员也应按已通过的本地流程审计执行结果。只有发现本地流程违反 common 硬约束时，才回到 common 规范要求整改。

## 2. 适用范围

适用于以下事项：

1. 理论验证实验。
2. 策略实验。
3. 数据实验。
4. 工程验证实验。
5. 性能实验。
6. 样本验收实验。
7. 案例分析实验。
8. 外部信息或人工反馈验证实验。

临时探索如果要被后续引用为结论，必须补齐为正式实验记录。

## 3. 核心文档

实验体系的正式文档分为核心文档和模板文档。

核心文档用于说明体系和记录具体实验。

模板文档用于创建新项目或新实验时实例化，不是具体实验结论。

### 3.1 实验规范

`实验规范.md` 是实验体系架构文档。

它负责说明：

1. 实验体系有哪些核心文档。
2. 实验设计和执行的标准流程。
3. 实验总纲、实验设计、执行日志、结果包、审计报告分别负责什么。
4. 什么情况下实验可以结束。

### 3.1A 实验环境创建指南

`实验环境创建指南.md` 是项目启用实验体系时的初始化手册。

它负责说明：

1. 新项目要创建哪些实验目录。
2. 项目级实验入口、实验存储体系、审计报告和问题记录怎么建。
3. 单个实验事项如何从总纲、设计、执行日志开始。
4. 什么情况下实验员环境算 ready。

如果一个 AI 要在新项目里创建实验员工作环境，应先读 `实验环境创建指南.md`，再实例化具体模板。

### 3.2 实验总纲

实验总纲是实验事项入口，对应管理系统里的“事项总纲”。

项目内默认只有一个 `exp-doc/实验总纲.md`，用于持续记录所有实验事项的背景、目标、边界、状态、结果包入口和结论。不要默认按实验 ID 创建多份 `<EXP-ID>_实验总纲.md`，否则 AI 和审核员容易漏看版本和上下文。

实验总纲必须采用滚动账本方式维护：新实验、新结论、新修订追加到文件末尾，最新内容在最后。文件开头可以维护“当前总览”和固定入口，但不得把最新实验插到前面，也不得覆盖历史记录。

实验总纲必须包含事项总纲要求的字段：

1. 实验事项 ID。
2. 实验名称。
3. 背景、由来和原理。
4. 创建人员。
5. 创建时间，精确到秒。
6. 希望达成的目标。
7. 当前状态。
8. 当前结论。
9. 唯一事项 ID。
10. 事项名称。
11. 完整来源聊天记录或来源记录路径。

实验总纲还应补充：

1. 原理来源。
2. 本轮边界。
3. 实验设计入口。
4. 结果包入口。
5. 审计入口。

### 3.3 实验设计

实验设计已经合并原“实验设计”和“实验计划”的职责。

原因：设计回答“如何验证目标”，计划回答“如何分步骤执行”。两者必须绑定，否则容易出现设计和执行脱节。

项目内默认只有一个 `exp-doc/实验设计.md`，用于持续记录所有实验的设计、步骤、依赖、产物和判定标准。新实验应追加到该文件，不要默认按实验 ID 创建多份设计文件。

实验设计必须采用滚动账本方式维护：新设计、新修订、执行结果回填追加到文件末尾，最新内容在最后。设计可以有顶部“当前设计总览”，但详细设计块必须按时间顺序追加，不能用单实验表单替代长期账本。

实验设计对应管理系统里的“事项计划”，必须包含事项计划要求的字段：

1. 所属事项名称。
2. 所属事项 ID。
3. 执行人。
4. 创建时间，精确到秒。
5. 目标。
6. 当前状态。
7. 当前结论。
8. 唯一步骤 ID。
9. 步骤名称。
10. 来源聊天记录，可为空。

实验设计还应包含：

1. 假设或要验证的问题。
2. 数据源和样本范围。
3. 实验组、对照组和边界样本。
4. 方法步骤。
5. 防偏差要求；是否需要防未来函数必须由实验目标决定。
6. 输出产物。
7. PASS / FAIL / HELD 判定。
8. 设计审核记录。

### 3.4 实验执行日志

实验执行日志记录实际执行过程。

项目内默认只有一个 `exp-doc/实验执行日志.md`，用于持续记录所有实验 run、输入、关键中间过程、中间数据路径、输出、异常、自检和重跑记录。新 run 应追加到该文件，不要默认按实验 ID 创建多份执行日志。

实验执行日志同样采用 append-only 方式维护；每次运行、重跑、失败、暂停、人工操作和复验都追加到文件末尾，最新内容在最后。

它负责回答：

1. 哪天、谁、运行了什么。
2. 用了什么输入。
3. 中间过程做了哪些关键处理。
4. 中间数据或中间表存在哪里。
5. 生成了什么输出。
6. 关键计数和关键异常是什么。
7. 是否偏离设计。

执行日志可以简洁，但不能只写“已跑完”。凡是会影响实验结论的关键节点，都要在执行日志中留下可追踪记录。

最低要求：

1. 记录输入冻结或输入快照路径。
2. 记录每个关键处理节点，例如清洗、特征生成、过滤、抽样、人工标注、模型运行、结果聚合、画图、summary/readout 生成。
3. 记录每个关键节点的输入、关键中间过程、中间数据路径和输出。
4. 记录关键计数，例如输入行数、过滤后行数、样本数、图数量、失败数、命中数。
5. 记录关键校验，例如 schema、路径存在、hash、样本覆盖、目标相关防偏差检查。
6. 记录异常、偏离设计、补跑、重跑、降读和复审需求。

如果中间数据是审计员或后续实验复核结论所必需的，应保存到 `exp-data/result/<run_id>/intermediate/` 或项目内等价正式结果包目录，并在执行日志中写明路径。`exp-data/tmp/` 只适合临时脚本和临时缓存，不能作为正式证据入口。

### 3.5 实验结果包

实验结果包是产物目录，不是必备模板文档。

结果包入口和状态应回写到实验总纲。

预期产物、实际产物、验收标准和关键读法应回写到实验设计。

数据文件、图表、日志、summary 等资产应符合项目内 `实验存储体系.md` 的规则。

如果某个结果包特别复杂，可以在结果包目录内临时放 readme，但它不是实验体系必备模板。

结果包应能回答：

1. 结果包在哪里。
2. 输入快照是什么。
3. 输出文件有哪些。
4. 关键指标是什么。
5. 自检结果是什么。
6. 哪些结论可以读，哪些不能读。
7. 如何复跑或复核。

### 3.6 实验存储体系

实验存储体系是项目级数据存储合同，不是单次实验模板。

项目启用实验体系时，应按 `实验存储体系创建指南.md` 创建项目内 `exp-doc/实验存储体系.md`。

它负责回答：

1. 实验数据存在哪里。
2. 结果包怎么组织。
3. 图片和图表怎么存。
4. 表清单是什么。
5. 每张表的 schema 和字段含义是什么。
6. 数据怎么读、怎么取、怎么追到原始来源。

### 3.7 实验审核和实验审计报告

实验审核的详细规则见 `实验审核规范.md`。

实验审计报告覆盖设计审核和执行审核。

设计和执行都必须审核。审核未通过时，不得把实验标为完成。

审核结果必须记录到对应项目的 `exp-doc/实验审计报告.md`。

实验审计报告采用 append-only 方式维护；每次设计审核、执行审核和复审都追加到文件末尾，最新内容在最后。

### 3.8 实验问题记录

实验问题记录用于记录非审计人员在实验过程中发现的问题，也用于登记需要跨轮跟踪的审计问题索引。

审核员在设计审核、执行审核和复审中发现的问题，主记录写入 `实验审计报告.md`；只有需要跨轮跟踪、跨实验汇总或由执行者长期处理时，才在 `实验问题记录.md` 中建立索引，不重复全文。

实验员、执行 AI、人工同事或其他非审计角色发现的问题，主记录写入 `实验问题记录.md`。

实验问题记录采用 append-only 方式维护；新问题、修复、复验和关闭记录都追加到文件末尾，最新内容在最后。

问题必须区分：

1. 设计问题。
2. 执行问题。
3. 数据问题。
4. 代码问题。
5. 结论过读。
6. 需要下一轮实验的问题。

### 3.9 结论回写

结论回写是实验收尾动作，不是必备独立模板文档。

结论回写应记录在实验总纲和实验审计报告里。

常见回写目标：

1. 方法论文档。
2. 需求文档。
3. 代码实现方案。
4. 数据存储规范。
5. 下一轮实验总纲。
6. 放弃或暂停说明。

如果某个实验产生大量跨文档回写动作，可以在项目内临时建立回写清单，但它不属于实验体系必备模板。

## 4. 模板文档

`common/exp-doc` 下应提供以下模板：

1. `实验环境创建指南.md`。
2. `实验总纲模版.md`。
3. `实验设计模版.md`。
4. `实验执行日志模版.md`。
5. `实验存储体系创建指南.md`。
6. `实验审核规范.md`。
7. `实验审计报告模版.md`。
8. `实验问题记录模版.md`。
实验体系不强制提供实验导读或实验总纲列表模板。项目如果需要实验目录索引，可在项目总索引里维护；AI 审查实验时直接读取实验总纲。

创建新项目或新实验体系时，应按这些模板实例化项目内的实验文档。默认实例化为项目级账本文件：`实验总纲.md`、`实验设计.md`、`实验执行日志.md`，而不是每个实验一份独立文件。

这些项目级账本默认学习长期滚动实验文档的写法：顶部保留当前总览和固定口径，正文按时间追加实验块。字段完整性服务于追踪和审计，不应把文档写成难读的厚重表单。

模板文档开头也必须保留管理系统要求的文件头：

1. 创建人员。
2. 文件职责。
3. 管理规范或模板。
4. 引用文件。

项目内文档引用项目内文件时，应默认使用相对路径，避免写入依赖个人机器的绝对路径。只有跨项目、跨磁盘或引用 common 规范时，才允许使用绝对路径，并应说明原因。

## 5. 实验状态

实验状态建议统一使用：

1. `未开始`：已登记，未设计。
2. `设计中`：正在写实验总纲或实验设计。
3. `待设计审核`：设计完成，等待审核。
4. `设计审核未通过`：设计存在阻断问题，需要修改。
5. `设计审核通过`：可以进入执行。
6. `执行中`：正在跑实验或整理结果。
7. `待执行审核`：执行完成，等待审核。
8. `执行审核未通过`：执行或结果存在阻断问题，需要修复或重跑。
9. `完成`：执行审核通过，结论和结果包已归档。
10. `暂停`：因数据、方向、资源或上游问题暂停。
11. `取消`：实验不再执行。

## 6. 实验设计流程

实验设计流程必须有审核闭环。

标准流程：

```text
提出实验问题
-> 创建实验总纲
-> 编写实验设计
-> 设计自检
-> 提交设计审核
-> 审核员审核
-> 审核通过：设计完成，进入执行
-> 审核不通过：修改总纲或实验设计，再次提交审核
```

设计审核的检查项、问题分级、通过条件和记录方式，按 `实验审核规范.md` 执行。

## 7. 实验执行流程

实验执行流程也必须有审核闭环。

标准流程：

```text
确认设计审核通过
-> 准备输入数据和执行环境
-> 执行实验步骤
-> 记录执行日志
-> 生成结果包
-> 执行自检
-> 提交执行审核
-> 审核员审核
-> 审核通过：实验完成，结论可归档
-> 审核不通过：修复、补证据或重跑，再次提交审核
```

执行审核的检查项、问题分级、通过条件和记录方式，按 `实验审核规范.md` 执行。

执行审核通过前，实验不得标记为完成。

## 8. 证据链要求

每个正式实验必须用统一 ID 串起证据链。

最低要求：

1. `experiment_id`：实验事项唯一 ID，必须出现在实验总纲、实验设计、执行日志、审计报告、结果包或 manifest。
2. `step_id`：实验设计里的步骤 ID，必须能在执行日志和审计报告里被引用。
3. `run_id`：每次实际执行的运行 ID，必须能从执行日志追到结果包。
4. `audit_id`：每次审核 ID，必须能追到对应实验、设计版本、执行 run 或复审对象。
5. `source_chat_record`：关键来源聊天记录，必须在实验总纲背景中保存原文或路径。

推荐证据链：

```text
实验总纲 experiment_id + source_chat_record
-> 实验设计 experiment_id + step_id
-> 执行日志 experiment_id + step_id + run_id
-> 结果包 run_id
-> 审计报告 audit_id + experiment_id + step_id/run_id
```

如果证据链断裂，审核员必须指出断在哪一环。

## 9. 来源聊天记录要求

实验总纲的背景中必须包含最重要的来源聊天记录。

可以保存原文，也可以保存明确路径，但必须能让审核员看到用户原始要求。

最低要求：

1. 实验总纲必须记录关键聊天原文或路径。
2. 实验设计必须说明如何承接这些聊天要求。
3. 审计报告必须检查聊天要求、实验目标、实验设计是否一致。
4. 不一致时必须提出，不能只按实验设计本身审核。

## 10. 防偏差要求

实验设计和执行中必须显式考虑以下风险：

1. 未来函数。
2. 样本污染。
3. 幸存者偏差。
4. 只看成功样本。
5. 源数据切换但未记录。
6. 规则执行和文档描述不一致。
7. 结论过读。
8. 把探索结果误读成正式结论。

不是每个实验都需要防未来函数。

是否必须防未来函数，应根据实验目标判断：

1. 如果实验目标涉及时序决策、预测、收益率、回放、实时筛选、自动动作，必须检查未来函数。
2. 如果实验目标是后验理解、图形归纳、案例复盘、方法论总结，可以不按实时决策时点安全要求审核，但结论必须降读，不能写成可实时使用或 prediction ready。
3. 如果实验目标没有说明是否需要时点安全，设计审核应要求补清楚。

其他偏差如果会影响结论，也必须记录处理方式。

## 11. 数据和结果归档

实验产物应尽量形成结果包。

结果包至少应包含：

1. `summary` 或结果说明。
2. 输入数据说明。
3. 输出数据说明。
4. 关键表或图。
5. 自检结果。
6. 审核入口或审核结论。

大文件可以只记录索引、路径和 hash，不要求全部塞进文档。

## 12. 结论边界

实验结论必须写清：

1. 本轮证明了什么。
2. 本轮没有证明什么。
3. 哪些结果可以进入下游。
4. 哪些结果只能作为观察。
5. 哪些问题需要下一轮实验。

禁止把“样本看起来不错”直接写成“规则已成立”。

## 13. 轻量实验

轻量实验可以减少文档数量，但不能没有目标、边界和结果记录。

轻量实验最低要求：

1. 在实验总纲或导读里登记。
2. 写清目标和边界。
3. 记录结果位置。
4. 写清结论不能读到什么程度。

如果轻量实验结果要进入正式决策，必须补齐实验设计、结果包入口和产物清单、审核报告。

## 14. 交付标准

一个正式实验完成的最低标准：

1. 实验总纲存在。
2. 实验设计存在，并通过设计审核。
3. 实验执行日志或等价执行记录存在。
4. 结果包存在，且入口已回写到实验总纲和实验设计。
5. 实验审计报告存在，并通过执行审核。
6. 结论边界明确。
7. 来源聊天记录、实验目标、实验设计已经由审核员确认一致，或已明确记录不一致及处理方式。
8. 必要结论已回写或记录待回写。

缺少执行审核通过结论时，实验状态只能是 `待执行审核`、`执行审核未通过`、`暂停` 或 `HELD`，不能标为 `完成`。