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）。
• 第零轮、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。