From 4dc7ac9d62f9c19dcda055246aead70d0e3b2960 Mon Sep 17 00:00:00 2001
From: iomgaa <iomgaaycz@gmail.com>
Date: Fri, 2 Oct 2026 07:40:27 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E4=BB=BB=E5=8A=A1?=
 =?UTF-8?q?=E4=B9=A6=2004-config?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 WORK_LOG.md         |   2 +-
 任务书/04-config.md | 157 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 158 insertions(+), 1 deletion(-)
 create mode 100644 任务书/04-config.md

diff --git a/WORK_LOG.md b/WORK_LOG.md
index e4c5ee0..2e182b1 100644
--- a/WORK_LOG.md
+++ b/WORK_LOG.md
@@ -77,4 +77,4 @@
 
 ## 下一步
 
-任务书 03（ledger）已核对通过（716f4b8）。下一个模块待监督者与用户商定。
+任务书 03（ledger）已核对通过（716f4b8）。`任务书/04-config.md` 已写好（含 ledger 两处顺手改），等用户另开 Agent 执行，监督者核对。
diff --git a/任务书/04-config.md b/任务书/04-config.md
new file mode 100644
index 0000000..fe40bc4
--- /dev/null
+++ b/任务书/04-config.md
@@ -0,0 +1,157 @@
+# 任务书 04：config（配置）
+
+写 config 模块：`research.json` 有哪些字段、怎么校验、怎么翻译成这份研究的步骤清单。顺带改 ledger 里的两处小地方。
+
+本任务书已由用户和监督者在 2026-10-02 一起确定。下面说的"监督者"，是在参考项目目录里和用户讨论设计的另一个会话。
+
+## 开工前先读
+
+- `CLAUDE.md`：全部，尤其是新加的"不设默认值"一节（提交 64e4fd8）和"罕见情况怎么办"。
+- `docs/结构.md`：
+  - 第二部分（config 的职责和依赖）；
+  - **第三部分"步骤清单"**；
+  - **第五部分"可替换点"**，尤其是"为了让换规则的实验做得对"那五条；
+  - 第八部分（vocab、rules、ledger 已导出的东西）。
+- `docs/方法.md`：
+  - 第三部分（角色）；
+  - 4.1、4.2（第零轮）、4.3 ⑨（修复次数上限）；
+  - 6.11（常数与参数）；
+  - 第七部分（轻量检查的次数和时长）；
+  - 第九部分（开发入口）；
+  - **第十一部分"方法的开关与对照流程"**。
+- `WORK_LOG.md`。
+- 参考项目（只读，不要改）：
+  - `/home/iomgaa/Projects/RivalBits/src/config/research.ts`：旧的配置字段，下面"保留与删除"说明哪些要、哪些不要；
+  - `/home/iomgaa/rb-acceptance/15-real-1/research.json`：一份真实用过的配置，只能读。
+
+## 一、原则
+
+- **所有字段都必填，代码里不补任何值**（CLAUDE.md"不设默认值"）。可以没有的值写 `null`，不靠省略。不认识的字段报错。
+- `research.json` 是用户写的配置，属于系统边界（CLAUDE.md"罕见情况怎么办"），要严格检查。报错时写清是哪一项（字段路径）、错在哪里，一次列出全部错误。
+- **能用数据表示挡住的错误，就不写检查代码。** 例如"朴素循环里又写了开关"、"关了消融却写了选格规则"，用联合类型让这些组合根本写不出来，不另写冲突检查（见第三部分）。
+
+## 二、字段
+
+字段名、怎么分组由你来定。下面是要有的内容：
+
+**用户配置**：以后配置对话会逐项问用户。
+- 研究编号：种子由它和轮次、版本算出，格式用 vocab 的 `Id`。
+- 任务：用哪个任务，写任务目录的路径。任务本身的事实，比如最终指标、方向、ε、已知最好、单次时限和核数、镜像，都不写在这里，归 tasks 模块、放在任务目录里（方法.md 6.11"精度 ε、已知最好：任务配置"，第十部分"任务需要提供什么"）。config 只检查它是一个字符串，不去读任务目录。
+- 研究者：一个列表，每一项是这位研究者用的模型。列表长度就是 N，不另设 N 字段，这样"N 和模型个数对不上"根本写不出来。
+- 实验员的模型、核验员的模型。
+- 每个模型写三样：provider、model、思考档位。思考档位必须写明，不允许写 `null` 表示"用 Pi 自己的默认"。
+- 每人每轮提案上限 M、每批上限、运行次数。
+
+**方法参数**：以后配置对话按方法.md 6.11 的现行值写进文件，不逐项问。
+- 开放预留 λ、u、衰减 r、因子数上限。
+- 修复次数上限（方法.md 4.3 ⑨）。
+- 轻量检查的次数上限和单次时长（方法.md 第七部分）。
+- 提示词目录。
+- 开发入口开还是关（方法.md 第九部分）。
+
+**流程**：见第三部分。
+
+每个字段都写字段说明（中文），并标明它属于用户配置还是方法参数。以后的配置对话照着这些说明问，不另写一份。
+
+## 三、流程：预设、开关、规则
+
+方法.md 第十一部分有两种流程，用联合类型表示，每一种只写它用得到的字段：
+
+- **完整流程**：
+  - 第零轮：要么"关"，要么"开 + 讨论次数（1 或 2）"；
+  - 第一次预测：开或关；
+  - 挑刺与回应：开或关；
+  - 消融：要么"关"，要么"开 + 选格规则名"；
+  - 选批规则名。
+- **朴素循环**：方法.md 第十一部分整套照搬，不能再写任何开关或规则。它不预测，选批固定是均匀随机。只写它用得到的方法参数，用不到的（比如 λ、u、衰减）不出现在这个分支里。
+
+规则名必须是 rules 登记表里有的名字（`BATCH_RULES`、`CELL_RULES`），从 rules 取，不另抄一份名单。为此 config 要依赖 rules（rules 是更下层的纯计算，依赖方向向下）。请同时改：
+- `docs/结构.md` 第二部分模块表里 config 的"依赖"一栏；
+- `.dependency-cruiser.cjs` 里 config 允许依赖的模块。
+
+## 四、步骤清单
+
+一个纯函数：输入校验过的配置，输出这份研究的步骤清单（结构.md 第三部分）。
+
+- 包括整份研究的步骤和每一轮的步骤。
+- 每一步标明：执行，还是按配置跳过。被跳过的步骤也列出来，flow 据此在账本里记一条"按配置跳过"。
+- 每个决策点写明用哪条规则：规则名和版本，从 rules 登记表取。
+- 朴素循环的步骤清单按方法.md 第十一部分写：
+  - 不挑刺、不回应、不预测，提案直接冻结；
+  - 判重和输入检查照常；
+  - 均匀随机选批；
+  - 实现、核验、运行照常，采纳规则和完整流程相同；
+  - 不做消融，没有信念本、第零轮、私人笔记、收尾，候选不留池；
+  - 下一轮的材料只有任务说明、当前基线代码，以及之前全部运行的提案正文与分数。
+
+  其中"没有信念本、私人笔记""材料只有什么"不是步骤，以后归 materials。步骤清单里要能读出"这是朴素循环"，让 materials 据此决定给什么。
+
+flow 以后只读这份清单，不再读配置里的开关。
+
+## 五、对外提供什么
+
+经 `src/config/index.ts` 导出：
+
+1. 读取并校验 `research.json`，返回配置；不合格就报错，并列出全部错误。
+2. 配置的字段定义（TypeBox），带字段说明，标明用户配置还是方法参数。
+3. 步骤清单函数，以及步骤清单的类型。
+
+账本里"研究配置"那条记录仍然只存 Json：ledger 在更下层，不能引用 config。以后 flow 从账本读回配置时，用这里的校验函数再检查一遍。
+
+## 六、参考项目的保留与删除
+
+| 处理 | 内容 |
+|---|---|
+| 借鉴 | 用 TypeBox 写字段定义、不认识的字段报错；模型的写法（provider、model、思考档位） |
+| 不搬，归 tasks | `task` 整节（目录、镜像、时限、核数、环境变量、`taskOptions`）、`environment` 整节、`evaluation` 整节（指标、方向、ε、已知最好）、`taskDocument`、`materials` |
+| 删除 | `maxRounds`（不设轮数上限）、`budgets.compute.cpuSeconds` 和 `wallSeconds`（计算时间不再是预算）、`seed`（种子由研究编号算） |
+| 删除 | `models.audit`、`agent.onSuspectedRun`（Jev 审查观测量、命令审查都已删除） |
+| 删除 | `REMOVED_CONFIG_KEYS`（专门给已删字段报说明；不认识的字段本来就报错） |
+| 删除 | `naiveConflicts` 一类逐项比对的冲突检查，改用第三部分的联合类型 |
+| 删除 | `outputDir`（导出放在研究目录下）、`researcherNotes` 开关（朴素循环整套关掉） |
+| 删除 | 所有 `Type.Optional` 加"不写就是……"的写法 |
+| 改名 | `splitMode` 改为消融开关，`pointLimit` 改为因子数上限，`implementationReview.maxRepairs`、`checks` 并入方法参数 |
+| 先不搬 | `agent` 一节（并发数、单次回复最长多少）：写 agents 模块时再加。Jev 用哪个模型，写 jev 模块时再加 |
+| 不归 config | 配置对话（`config/dialog.ts`、`extensions/config-tool.ts`）归 plugin；提示词文件的哈希由读提示词的模块算 |
+
+## 七、顺带改 ledger 的两处
+
+这两处已写进 `docs/结构.md` 第四部分（提交 655f5bb），代码还没改：
+
+1. **消融结算按轮次唯一**：每轮最多采纳一个改法，所以最多一次消融。结算记录用轮次代替消融编号，唯一约束跟着改。
+2. **私人笔记去掉版本号**：笔记不属于任何阶段，以最后写入的一条为准。序号本身就是先后，版本号是程序推得出的栏目。
+
+表结构变了，把表结构版本号加 1。改完相应的测试。这两处属于账本，测试要能看出改对了：同一轮结算两次报错；笔记取最后写入的一条。
+
+## 八、测试
+
+- 一份写全的合法配置能通过：完整流程一份，朴素循环一份。
+- 缺任何一个必填字段报错，报错里有字段路径。逐个字段删掉试，不用手写每一条。
+- 不认识的字段报错；类型不对报错；一次列出多处错误。
+- 写不出来的组合确实写不出来：
+  - 朴素循环里写了开关；
+  - 消融关着却写了选格规则；
+  - 规则名不在 rules 登记表里。
+- 步骤清单：完整流程全开一份；四个开关各关一个；朴素循环一份。每份对照结构.md 第三部分、方法.md 第十一部分逐条写预期，不从实现里推。
+
+config 属于"其余部分"的原型标准，不另派子 Agent 审阅。第七部分的 ledger 改动属于账本，改完自己对照结构.md 第四部分核对一遍。
+
+## 九、规模与文档
+
+- config 预期 300–500 行（不含测试）。超过 500 行就停下来检查。
+- 完成后更新：
+  - `docs/结构.md` 第八部分：补 config 对外的函数和类型，每项一句话；ledger 那段按第七部分的改动更新；
+  - `docs/结构.md` 第二部分 config 的依赖（第三部分要求的）；
+  - `WORK_LOG.md`：从"ledger 待顺手改"里删掉已做的两条。
+- 不新建其他 md 文件。
+
+## 十、验收与报告
+
+做完后本地提交，然后在回复里交一份报告，监督者会对着实际文件逐项核对：
+
+1. 提交号，新增和修改的文件列表，每个文件的行数，config 的总行数。
+2. `npm run check` 和 `npm test` 的完整输出。
+3. 最终的字段表：每个字段属于用户配置还是方法参数，取值范围。另附一份写全的完整流程配置样例。
+4. 三种步骤清单（完整全开、关掉消融、朴素循环）的实际输出。
+5. 你和这份任务书、结构.md、方法.md 不一致的地方，以及为什么。
+6. **规则不清楚的地方**：读 CLAUDE.md、结构.md、方法.md 时，哪里让你犹豫、哪里两份文件说法不一致、哪里你是靠猜的。没有就写"没有"。