docs: 新增任务书 09-materials

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 02:25:08 -04:00
parent db67965af0
commit 74d743eeb7
2 changed files with 166 additions and 1 deletions
@@ -45,6 +45,7 @@
 - 实验员会话里的 shell 命令不测 CPU，只记每次模型调用的墙钟时间；正式运行的资源用量照记。用户原话："那要不就不测了？本来cpu就不重要，现在又可能测不准"。
 - agents（任务书 07）：只收拼好的提示词和第一条消息（读提示词归 materials），不碰账本；提交工具去掉 slot；保留参考项目两处有真实证据的提交特殊处理（非法 JSON 被截半、null 变 "null"）和子会话加载核对；删 Jev 审命令、上下文估算、输出上限配置；预期 400–600 行。用户原话："同意，写任务书 07 吧"。
 - jev（任务书 08）：方法里三处 Jev 判别共九问（判重 1、冻结条款 3、实现改动 5），比原方法多出的"条款太含糊""算指标方式与定义不符""比登记的停止条件更早结束"三问已补进方法.md；这次不校准：问法以参考项目为基础只改说法，阈值暂用参考项目的值并注明未校准；账本存下每次 Jev 判断（退回、收下、判重都存）；Jev 模型名进 config；不做"永远判不同"的空实现。用户原话："九个都问，并把多出的三个补进 docs/方法.md"；后来改为不校准："我们到时候应该是通过真实的运行收集一批真实的数据，然后由claude或者gpt亲自打标签作为集合……jev这次的验收应该也不以效果为主，因为还没有数据校准，prompt还是用原本的prompt作为基础就好"。
 - materials 与 submissions 一起设计、分两份任务书（09 materials 先、10 submissions 后）：materials 对每个任务产出"给模型看的材料 + 对号清单 + 能读的代码版本"，整份存进"模型调用开始"记录，submissions 只拿清单对号；谁能看什么每种任务一个函数，不写通用判定；提示词以参考项目为底稿只做必要改动；materials 预期 1200–1800 行，submissions 500–800 行。用户原话："我建议submissions和materials一起做你觉得可以吗？"、"可以"、"都同意"。
 - 中断的模型调用，恢复时补写"出错、原因'进程中断'、墙钟时间测不到"（`callEnded` 的墙钟时间用 `Measured`）。用户原话："墙钟时间改用 Measured，恢复时写出错加测不到（原因'进程中断'）"。
 ## 未完成
@@ -93,4 +94,4 @@
 ## 下一步
-任务书 08 已核对通过（0ac1e01）。下一个模块待和用户商量（剩 submissions、materials、flow、export、plugin）。
+任务书 09（materials，`任务书/09-materials.md`）已写好，等用户另开新 Agent 执行；完成后监督者核对，再写任务书 10（submissions，并带上判重材料加关键设定）。
@@ -0,0 +1,164 @@
 # 任务书 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`）。
 - 第零轮、naive 之外，参考项目材料里的"放不下时逐轮压缩，压完还超就报错"不搬：没有真实超长过的证据。真超了，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。