158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
# 任务书 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 时，哪里让你犹豫、哪里两份文件说法不一致、哪里你是靠猜的。没有就写"没有"。
|