InfoRSI/任务书/09-materials.md

# 任务书 09：materials（材料）

写 materials 模块：每个任务给模型看什么、第一条消息怎么写、查询工具能查到什么，以及给 submissions 对号用的清单。顺带搬提示词文件。

本任务书已由用户和监督者在 2026-10-03 一起确定。下面说的"监督者"，是在参考项目目录里和用户讨论设计的另一个会话。下一份任务书 10 写 submissions，它直接用这里定下的清单。

## 开工前先读

- `CLAUDE.md`：全部，尤其是"研究方法上不能变的约束"（当前轮没公开的提案和范围不能提前泄露）、"罕见情况怎么办"、"不设默认值"、"Pi 与三个角色"（提示词只引导怎么想，不设必填栏目）。
- `docs/结构.md`：
  - 第一部分第 7 问；
  - 第二部分 materials 一行和"几条边界"里"给模型看什么只归 materials"；
  - 第三部分步骤清单、第四部分账本记录（尤其第 10 种"模型调用开始，附这次任务的全部材料"）；
  - 第八部分 vocab、rules、ledger、config、workspace、tasks、agents、jev 各节。
- `docs/方法.md`：
  - 第三部分全部：角色、谁在什么时候能看到什么、给研究者的材料顺序、私人笔记；
  - 4.2、4.3：每一步的"能看到什么""材料"；
  - 第五部分：每种提交、答案路径；
  - 6.10：信念本写什么。
- `WORK_LOG.md`："未完成"里"给 materials"的几条，以及"答案路径、保障名字在不在位置表里由以后拿得到位置表的模块现算"。
- 参考项目（只读，不要改）：
  - `/home/iomgaa/Projects/RivalBits/src/rounds/stage-material.ts`：每种任务的材料怎么排、写成什么样；
  - `/home/iomgaa/Projects/RivalBits/src/rounds/belief-book.ts`：信念本写成文字；
  - `/home/iomgaa/Projects/RivalBits/src/rounds/metric-catalog.ts`：指标清单；
  - `/home/iomgaa/Projects/RivalBits/src/agents/prompts.ts`：读提示词、拼第一条消息、收尾段；
  - `/home/iomgaa/Projects/RivalBits/prompts/`：3 份角色提示词、17 份任务说明。

## 一、这个模块做什么

用"第 2 轮，研究者 A 写解释"举例：

1. flow 告诉 materials：这是哪种任务（`explanation`）、给谁（A）、第几轮，以及只有 flow 拿得到的东西（例如本批各版本代码的比较结果，见第三部分）。
2. materials 从账本里挑出这个任务该看的记录，交回一份**任务材料**，里面有：
   - **给模型看的材料**：A 自己的入口、笔记、自己候选的结果；公共的任务说明、基线、信念本、上一轮收尾；这一步要处理的因子清单、本批运行分数、要给三个数的格；
   - **第一条消息**：任务说明加材料加"现在交什么"，拼好的文字；
   - **对号清单**：这次要覆盖的格（p1、p2、p3）、每人最多交 M 条等，submissions 拿它判收不收；
   - **能读的代码版本**：研究者、核验员能读哪几个版本的代码，由 flow 取出到目录、交给 agents。
3. flow 把整份任务材料存进账本的"模型调用开始"记录（结构.md 第三部分第 10 种），再把第一条消息交给 agents。
4. 模型调"查询"时，materials 只在这份材料里找，找不到就答"看不到"。

## 二、谁能看什么：每种任务一个函数，不写通用判定

- 一种提交种类（vocab `SUBMISSION_KINDS`，16 种）一个材料函数。每个函数明明白白写出从账本里取哪几样，对着方法.md 第三部分、4.2、4.3 逐条写，注释里引用方法的小节。
- **不写参考项目那种通用的"谁能看见什么"判定函数**（参考项目 `board/visibility.ts` 的 `canSee`，加上截止序号、"本轮重来"被取代的不给等）。通用判定要对每种记录、每个阶段都给出答案，就会长出一堆特殊情况。用户 2026-10-02 定：给模型的材料按任务定。
- 下面几条是方法里明文写的，每条都要有测试：
  - 同一阶段的提交，全部应交者交齐、阶段关闭之前，别人看不到；
  - 作者自评一直封存，到本轮结束解封前，任何任务的材料里都没有它（方法.md 第三部分、4.3 ⑱）；
  - 第一次预测只有本人看得到（方法.md 第三部分、4.3 ⑦）；
  - 第二次预测看不到别人第一次的数（4.3 ⑦）；
  - 第零轮闭门写入口时看不到别人的入口（4.2 表格）；
  - 别人的"退回"记录不放进任何研究者的材料（WORK_LOG"给 materials"：退回的提案原样带着作者自评）；
  - 信念本只写已经公开的记录。
- 实验员、核验员只看分给他的那个候选：冻结协议、基线代码、要实现或核验的东西。参考项目 `assignedBlocks`、`ablationBlocks` 的排法可以借。

## 三、任务材料长什么样

**放在哪个模块**：任务材料（尤其是对号清单）由 materials 产出、submissions 读，两个模块互不引用，所以类型放进 vocab，名字你定。

**给模型看的材料**：
- 按方法.md 第三部分"给研究者的材料顺序"排：任务说明 → 你自己的 → 公共材料 → 现在交什么。实验员、核验员的顺序照参考项目。
- 每一条能被查询到的记录都带一个编号。查询工具按编号回全文，只在这份材料里找。参考项目的 `queryRecord` 可以借，但去掉别名、"类别:编号"那些写法，除非你发现模型确实需要。
- 大块的原始内容，例如运行产物、代码全文，不放进第一条消息。代码由能读的版本给出，用"读代码"工具读；运行产物放查询。
- 答案路径、保障动手次数：tasks 只记了读到的原样内容，"在不在位置表里"在这里现算（WORK_LOG）。答案出自某条保障时，单独标一行（方法.md 第五部分"答案路径"最后一段）。

**对号清单**：按任务种类区分，每种只放它要用的。下面是 submissions 要对号的全部规则（WORK_LOG"留给 submissions 的跨字段规则"），清单要能回答它们：

| 任务 | 清单里要有 |
|---|---|
| 提案 | 因子数上限；看得到的因子编号（延续只能延续这些）；能引用的假设专用指标编号；M |
| 第一次、第二次预测 | 要给三个数的候选编号 |
| 挑刺 | 能挑的目标：每个候选及它的因子编号 |
| 回应 | 针对本候选的全部挑刺编号；因子数上限；能引用的指标编号 |
| 统一 | 同上，加上被合并的原提案编号 |
| 入口、讨论 | 入口个数的范围（2–3） |
| 志愿 | 全部入口编号；至少排几个，即 min(N, 入口总数) |
| 实现、修复 | 冻结协议的实现条款编号、因子编号、保障短名 |
| 核验 | 实现条款、因子、保障；以及"没有归属的改动"清单（见下） |
| 解释 | 要覆盖的格；M |
| 消融实现 | 这一格要关的因子；全部因子编号 |
| 消融核验 | 全部因子编号 |
| 收尾 | 无 |

- 只有在提交之后才知道的东西，不在清单里，例如实验员改了哪些文件、改动切成哪几块。它们随提交一起交给 submissions，那是任务书 10 的事。
- **没有归属的改动**：核验员要逐条判断。materials 用 flow 传进来的代码比较结果（workspace 的 `compareVersions`）和实验员交的位置表现算，按 workspace 文档的说明：块可以为空，空的按整个文件改了算。同一行既属于因子又属于保障的，列出来当提醒（方法.md 4.3 ⑨）。

**能读的代码版本**：研究者、核验员能读哪几个版本。只列已经公开的版本，例如基线、已经跑过的候选、被采纳的完整代码；flow 取出到目录。

## 四、信念本

- 按方法.md 6.10 的五条写成文字，数字全部用 rules 的函数现算，不另写公式，不存。
- 参考项目 `belief-book.ts` 的写法可以借：范围怎么换算成把握的说明、按因子分行、每次消融一句结论加一行押的因子、战绩。
- 它和材料里别的数字共用一套格式化函数。参考项目的数字格式化写了两份，精度还不一样，这里只写一份。

## 五、提示词

- 把参考项目 `prompts/roles/` 的 3 份和 `prompts/tasks/` 里的 16 份搬到新项目根目录的 `prompts/` 下。`proposal.naive.md` 不搬，对照组暂不实现。
  - 角色提示词按 vocab 的角色名：`researcher.md`、`experimenter.md`（原 `implementer.md`）、`verifier.md`；
  - 任务说明按 vocab 的提交种类名，一种一份。参考项目的文件名和提交种类的对应关系你对一下，比如 `predict-blind.md` 是第一次预测、`analysis.md` 是解释。
- **只做必要的改动**：点改成因子；字段名对上 vocab；删掉 naive、Jev 审命令、已删功能的说法；与方法.md 对不上的地方按方法改。不为"可能更好"重写，等真实运行有了数据再改。用户 9 月底专门改过一轮这些提示词。
- 不做模板变量替换。可变的内容全由程序拼。
- "现在交什么"那一段从 vocab `SUBMISSION_SCHEMAS` 的字段说明生成，不另写一份。参考项目 `composeClosing` 可以借。
- 读提示词时同时算每个文件原始字节的哈希。研究开始时 flow 把哈希冻结进研究配置记录（方法.md 4.1 第 1 条）。提示词目录来自配置的 `promptDir`。
- 研究者一次会话没交成、重新发起时，第一条消息里放上一次被退回的原因。参考项目有这一段（`composeTaskMessage`）。
- 参考项目材料里的"放不下时逐轮压缩，压完还超就报错"不搬：没有真实超长过的证据。真超了，agents 会报错停下，那时再处理。

另外，`tasks/circle_packing/TASK.md` 里告诉实验员一句：`task.json` 里"不存的名字"那些东西（`__pycache__`、`solution.json` 等）不会存进代码版本（WORK_LOG"未完成"）。

## 六、对外提供什么

经 `src/materials/index.ts` 导出，函数名由你定：

1. **生成一份任务材料**：输入任务种类、给谁、轮次、账本，以及 flow 才拿得到的东西（代码比较结果、任务说明、研究配置）；交回第三部分说的任务材料。
2. **查询**：给一份任务材料和一个编号，交回全文或"看不到"。agents 的查询回调就是它。
3. **读提示词**：给提示词目录，交回各文件的文字和哈希。
4. **信念本**：给账本，交回写成文字的信念本。导出以后也要用。

依赖只有 ledger、rules，加上 vocab（结构.md 第二部分）。代码比较结果、任务说明这些由 flow 传进来，materials 不引用 workspace、tasks。

## 七、参考项目的保留与删除

| 处理 | 内容 |
|---|---|
| 借鉴 | `stage-material.ts` 各任务的排法和文字；`belief-book.ts` 的写法；`prompts.ts` 的收尾段；`metric-catalog.ts` 推出指标清单的做法 |
| 删除 | `board/visibility.ts` 的通用判定、截止序号、"本轮重来"相关：按任务定材料 |
| 删除 | naive 流程的材料（`naiveHistoryBlock` 等）、`proposal.naive.md`：对照组暂不实现 |
| 删除 | 逐轮压缩和 `MaterialTooLargeError`：没有真实证据 |
| 删除 | 重复写的东西：任务到角色的对应（以 vocab `SUBMISSION_KINDS` 为准）、数字格式化、留池判定、"冻结条款"对象的拼法，各只写一处 |
| 删除 | 对已经存进账本的记录再逐字段查形状（参考项目 `public-records.ts` 的大部分解析函数、`metric-catalog.ts` 的 `proposalOf`）：ledger 读出时已按种类检查过 |
| 删除 | `prompts.ts` 对提示词文件 frontmatter、二级标题的严格检查：文件是我们自己写的 |
| 删除 | 材料里"保底"再挡一次本来就不公开的东西（参考项目 `visibility.ts` 124–131 那类） |

## 八、测试与审阅

- 每种任务至少一个测试：在真实账本（临时文件）里写入一段研究进程，生成材料，检查该有的有、不该有的没有，对号清单对。预期值按方法.md 的条文写，不从实现里推。
- 第二部分列的七条可见性规则，每条至少一个"不该看到"的测试。
- 没有归属的改动：手写两个版本和一张位置表，算出预期的清单再比。
- 查询：材料里有的编号查得到，材料外的编号（包括同一账本里别的记录）查不到。
- 提示词：每种提交种类都有对应的任务说明文件；哈希是原始字节的哈希。
- **审阅**："当前轮没公开的提案和范围不能提前泄露"是 CLAUDE.md 里研究方法不能变的约束。写完派一个全新上下文的子 Agent，只审可见性：拿方法.md 第三部分、4.2、4.3 对照每个材料函数，找"该看不到却放进去了"的地方。告诉审阅者：
  - 每条意见先回答"不写会怎样"；
  - 只防三类：没人操作也会发生的、模型正常工作时就会做的、出错后发现不了的；
  - 模块之间传错参数只列不改。

## 九、规模与文档

- 预期 1200–1800 行，不含提示词文件和测试。超过 1800 行就停下来检查。
- 完成后更新：
  - `docs/结构.md` 第七部分：materials 的行数改成 1200–1800；
  - `docs/结构.md` 第八部分：补 materials 对外的函数和类型、vocab 新加的任务材料类型；
  - `WORK_LOG.md`：在"已完成"补一条；删掉"未完成"里已做的"给 materials"几条、答案路径对表那条、TASK.md 那条。
- 不新建其他 md 文件。`prompts/` 下的提示词是产品文件，不算文档。

## 十、验收与报告

做完后本地提交，然后在回复里交一份报告，监督者会对着实际文件逐项核对：

1. 提交号，新增和修改的文件列表，每个文件的行数，materials 的总行数。
2. `npm run check`、`npm test` 的完整输出。
3. 两份实际生成的第一条消息全文：第 2 轮某位研究者写解释的；某个实验员实现候选的。用测试里构造的研究进程就行。
4. 任务材料类型的定义（vocab 里新加的），以及每种任务的对号清单字段。
5. 提示词相对参考项目改了什么：每个文件列出改动，说明原因。
6. 审阅意见逐条：内容、采纳或不采纳、理由。
7. 你和这份任务书、结构.md、方法.md 不一致的地方，以及为什么。
8. **规则不清楚的地方**：读 CLAUDE.md、结构.md、方法.md 时，哪里让你犹豫、哪里两份文件说法不一致、哪里你是靠猜的。没有就写"没有"。方法.md 里材料没写清的地方，按参考项目的做法写，在这里列出来，不要自己发明。没有真实证据的可能情况，在这里提一句就够，不写进 WORK_LOG。