From aff2418c3c882dc36edc7c44c865834a51a4d707 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Sat, 3 Oct 2026 01:35:47 -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=2008-jev=EF=BC=8C=E6=96=B9=E6=B3=95.md=20=E8=A1=A5?= =?UTF-8?q?=E9=BD=90=20Jev=20=E4=B9=9D=E9=97=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- WORK_LOG.md | 3 +- docs/方法.md | 4 +- docs/结构.md | 4 +- 任务书/08-jev.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 162 insertions(+), 5 deletions(-) create mode 100644 任务书/08-jev.md diff --git a/WORK_LOG.md b/WORK_LOG.md index 8df9226..59b8d71 100644 --- a/WORK_LOG.md +++ b/WORK_LOG.md @@ -43,6 +43,7 @@ - workspace（任务书 06）用 git：一份研究一个裸仓库，版本号是目录树编号；存版本时自己列文件、用 hash-object 存，不用 `git add`（实测 `.gitignore` 会让它悄悄漏存）；git 子进程不读用户配置；实验员目录里除了 task.json 的"不存"清单都算候选，符号链接等特殊文件退回实验员；预期 200–300 行。先派全新上下文子 Agent 独立分析过。用户原话："都同意，写任务书 06 吧"。 - 实验员会话里的 shell 命令不测 CPU，只记每次模型调用的墙钟时间；正式运行的资源用量照记。用户原话："那要不就不测了？本来cpu就不重要，现在又可能测不准"。 - agents（任务书 07）：只收拼好的提示词和第一条消息（读提示词归 materials），不碰账本；提交工具去掉 slot；保留参考项目两处有真实证据的提交特殊处理（非法 JSON 被截半、null 变 "null"）和子会话加载核对；删 Jev 审命令、上下文估算、输出上限配置；预期 400–600 行。用户原话："同意，写任务书 07 吧"。 +- jev（任务书 08）：方法里三处 Jev 判别共九问（判重 1、冻结条款 3、实现改动 5），比原方法多出的"条款太含糊""算指标方式与定义不符""比登记的停止条件更早结束"三问已补进方法.md；九问的问法和阈值全部在新材料上重新校准，样本沿用参考项目三组、标签不动；Jev 模型名进 config；不做"永远判不同"的空实现。用户原话："九个都问，并把多出的三个补进 docs/方法.md。所有阈值、prompt等涉及到校正到地方都全部重新校正，我们不在乎钱"。 ## 未完成 @@ -89,4 +90,4 @@ ## 下一步 -任务书 07 已核对通过（3600b5c、96abc6f）。下一个模块待和用户商量。 +任务书 08（jev，`任务书/08-jev.md`）已写好，等用户另开新 Agent 执行；完成后监督者核对。 diff --git a/docs/方法.md b/docs/方法.md index e4186ab..a41722d 100644 --- a/docs/方法.md +++ b/docs/方法.md @@ -230,7 +230,7 @@ - **回应**：逐条答复挑刺，只交改动了的部分，并给出实现条款。作者自评不能改；作者看完挑刺后怎么想，由他在第二次预测里自己交的范围来体现。 - **统一**：合并而成的候选，由编号最小的作者写成一份完整的冻结协议。它仍然按因子写，因子数上限照样适用；要逐条写明每份原提案在哪里体现，不能在原提案和挑刺之外加新改动。 -- Jev 检查冻结条款有没有改动评测、有没有自相矛盾，有问题就退回。 +- Jev 检查冻结条款有三类问题：改动了评测、自相矛盾、写得太含糊没法照着实现。有就退回。 - 回应阶段关闭时，协议冻结。冻结协议包括：因子清单、保障清单、协议正文、因子之间的关系、指标、实现条款。 **⑦ 第二次预测（每位研究者，各自独立）** @@ -252,7 +252,7 @@ - 代码； - 因子位置表：每个因子、每条保障分别在哪几行。同一行既属于某个因子又属于某条保障时，两边都写；不属于任何因子的改动，写一句说明； - `concerns`：照冻结原文实现、但认为会出问题的地方，尤其是某条保障会挡掉或改变什么。没有就写"无"。它不阻止运行，也不改动协议。 -- 程序检查实验员有没有改不许改的文件。Jev 检查改动里有没有这几类问题：用了不固定种子的随机数、协议没登记就读时钟、测不到的量写成 0。有就退回。 +- 程序检查实验员有没有改不许改的文件。Jev 检查改动里有没有这几类问题：用了不固定种子的随机数、协议没登记就读时钟、算登记指标的方式与定义不符、比协议登记的停止条件更早结束、测不到的量写成 0。有就退回。 - 程序把两类情况交给核验员：没有归到任何因子或保障的改动，核验员逐条判断是否越界；同一行同时出现在因子和保障里，核验员在说明里写一句，只是提醒，不判越界。 - 核验员只交逐项结果：每条实现条款、每个因子、每条保障，找没找到、在哪里；没有归属的改动，逐条判断是否越界。只要有一项"没落实"或者判为越界，程序就判不通过，退回实验员修复。修复次数有上限，可配置。 diff --git a/docs/结构.md b/docs/结构.md index eed0757..aa11cc0 100644 --- a/docs/结构.md +++ b/docs/结构.md @@ -145,7 +145,7 @@ Jev 是一个判别器，和程序检查地位相同，不单独成一种记录 | 种类 | 例子 | 换法 | |---|---|---| -| 外部服务 | Pi 会话、Docker 运行器、任务、Jev | 接口。Jev 另配一个"永远判不同"的空实现，用来关掉判重 | +| 外部服务 | Pi 会话、Docker 运行器、任务、Jev | 接口 | | 决策规则 | 选批：批内最好期望、均匀随机。选格：信息价值减成本、全测、随机同格数、都不测。以后可能加合并方式 | 纯函数，登记在 rules 里的"名字 → 函数"表里，配置写名字 | | 方法参数 | N、M、批量、运行次数、因子数上限、u、衰减、开放预留 | 配置值，不写成常数，也不用环境变量，每个都必须写在配置文件里。分两层：用户配置（配置对话逐项问）；方法参数（做实验时才改，配置对话按方法.md 6.11 的现行值写进文件、给用户看过） | | 模型与提示词 | 每个角色、每位研究者用哪个模型；提示词目录 | 配置值；账本记下每份提示词文件的哈希 | @@ -188,7 +188,7 @@ Jev 是一个判别器，和程序检查地位相同，不单独成一种记录 | ledger | 500–900 | | rules | 1500–2500 | | submissions | 600–1000 | -| jev | 300–500 | +| jev | 400–600（不含校准脚本） | | materials | 1000–1800 | | agents | 600–700 | | workspace | 200–300 | diff --git a/任务书/08-jev.md b/任务书/08-jev.md new file mode 100644 index 0000000..199ce6f --- /dev/null +++ b/任务书/08-jev.md @@ -0,0 +1,156 @@ +# 任务书 08：jev（Jev 判别） + +写 jev 模块：问 Jev 的问法、阈值和校准。全部问题和阈值在新项目的材料上**从头重新校准**。顺带改账本的三处、config 的一处。 + +本任务书已由用户和监督者在 2026-10-03 一起确定。下面说的"监督者"，是在参考项目目录里和用户讨论设计的另一个会话。 + +用户原话："九个都问，并把多出的三个补进 docs/方法.md。所有阈值、prompt等涉及到校正到地方都全部重新校正，我们不在乎钱"。 + +## 开工前先读 + +- `CLAUDE.md`：全部，尤其是"罕见情况怎么办""不设默认值""错误怎么处理"（外部错误有限次重试）、"Pi 与三个角色"里 Jev 那一条。 +- `docs/结构.md`： + - 第二部分 jev、submissions 两行； + - 第三部分：账本记录第 3 种（退回带 Jev 的原始概率和结论）、第 8 种（判重合并的输入带 Jev 的原始概率），以及"Jev 不单独成记录"那一段； + - 第八部分：vocab、ledger、config、workspace 几节。 +- `docs/方法.md`：4.3 ③（判重）、⑥（冻结条款检查）、⑨（实现改动检查）。 +- `WORK_LOG.md`。 +- 参考项目（只读，不要改）： + - `/home/iomgaa/Projects/RivalBits/research-wiki/参考-Jev使用指南.md`：**先通读**。问法怎么写、材料怎么给、抖动怎么测、阈值怎么定，都以它为准； + - `/home/iomgaa/Projects/RivalBits/src/judge/`：`jev.ts`、`judge.ts`、`questions.ts`、`calibration.ts`、`types.ts`； + - `/home/iomgaa/Projects/RivalBits/src/tasks/audit.ts` 的传输层：只看怎么发请求、怎么带密钥； + - `/home/iomgaa/Projects/RivalBits/tests/calibration/`：`README.md`，以及 `dedup/`、`feasibility/`、`prescan/` 三组的样本、记录和脚本。 + +## 一、问哪些问题 + +方法里一共三处、九个问题（`docs/方法.md` 4.3，监督者已按用户的决定补齐）： + +| 哪一处 | 问题（概率高 = 有问题，或"是同一个"） | 参考项目里的名字 | +|---|---|---| +| ③ 判重：两条提案 | 是不是同一个改法 | `same_change` | +| ⑥ 冻结条款 | 改动了评测 | `changes_measurement` | +| | 自相矛盾 | `self_contradictory` | +| | 写得太含糊，没法照着实现 | `too_vague` | +| ⑨ 实验员的一段代码改动 | 用了不固定种子的随机数 | `unseeded_randomness` | +| | 协议没登记就读时钟 | `reads_clock` | +| | 算登记指标的方式与定义不符 | `touches_measurement` | +| | 比协议登记的停止条件更早结束 | `early_exit` | +| | 测不到的量写成 0 | `zero_for_unmeasured` | + +参考项目另有"指标换说法""指标规格具体性"两处，方法里没有，不搬。 + +## 二、问法和材料 + +- 问题措辞、判"是"和判"否"的说明与示例句，以参考项目 `questions.ts` 为起点，改成新项目的说法： + - "点"改成"因子"； + - 协议、提案的字段按 vocab 现在的字段定义； + - 改动的形状按 workspace 的比较结果。 +- 材料由 jev 从带类型的输入拼出来。jev 的函数收的是：两条提案的因子清单；一份冻结协议的条款；一段代码改动加协议。不收拼好的 JSON。材料里放什么、字段叫什么，只在 jev 一处定（结构.md 第一部分第 7 问）。 +- 示例句只有填圆一套。参考项目"填圆、C1 两套示例句、按任务覆盖阈值"的机制不搬。以后加第二个任务时再说。 +- 代码改动按参考项目，**一段改动（一个差异块）一次请求**，五问在同一份材料里。差异块的正文从 workspace 的比较结果里取，怎么切由你定。 +- 冻结条款三问、判重一问各自怎么分请求，照参考项目的做法，或者按指南重新定，在校准记录里写明理由。 + +## 三、校准：全部重新做 + +参考项目的阈值是在参考项目的材料格式上定的，材料和问法变了就不能沿用（指南第三部分 3.5 节）。九个问题全部重新校准： + +1. **样本**：把参考项目三组样本（判重 84 条、冻结条款 53 条、代码改动 61 条，各含校准集和留出集）转成新项目的材料格式。**标签不动**：标签是事先写死的"这条应当判出哪几问"，转换只改材料的写法。哪条样本转不过来，写明原因，不要编一条新的顶上。 +2. **按参考项目的四步走**（`tests/calibration/README.md`、指南第七节）： + - 测抖动：挑几条，同一输入各问 5 次； + - 丢掉区分不开的问题，或者改问法：跨输入标准差 < 0.05、两类重叠、零错区间不比抖动宽两倍，都算区分不开；**改了问法就从第一步重来**； + - 在零错区间里定阈值，写明依据； + - 阈值定下以后才跑留出集，只报对错，不回头调。 +3. 某一问怎么改都分不开时，停下来写清楚，交给监督者，不要硬定一个阈值。 +4. 校准脚本、样本和记录放在 `tests/calibration/` 下，三组各一个目录。不进 `npm test`，另起一个命令。`npm test` 里只用假 Jev 验证脚本能跑通。 +5. 校准结果写在代码里阈值旁边的注释里：零错区间、抖动、取值理由、留出集对错数。参考项目 `questions.ts` 头上那段就是这种写法。每组的完整记录写在该组目录的 `README.md` 里。这是校准数据的一部分，不算新建文档。 + +**花钱**：用户说"我们不在乎钱"，校准该问几次就问几次，不用为省钱少问。 + +**密钥**：Jev 的密钥是环境变量 `TYPESAFE_API_KEY`，值在 `/home/iomgaa/Projects/RivalBits/.env`。跑校准时用 `set -a && . /home/iomgaa/Projects/RivalBits/.env && set +a` 加载，不要打印，不要复制进新项目。 + +## 四、对外提供什么 + +经 `src/jev/index.ts` 导出，函数名由你定： + +1. **判重**：两条提案，交回一条判断。 +2. **查冻结条款**：一份冻结协议，交回三问各自的判断，以及"有没有问题"。 +3. **查一段代码改动**：一段改动加协议，交回五问各自的判断，以及"有没有问题"。 + +每条判断都包含： +- 问题名； +- 问题全文的哈希：措辞、示例、阈值一起算，改了措辞就能从记录里看出来； +- 阈值、原始概率、结论； +- Jev 返回的请求编号。 + +这个类型放进 vocab，名字你定：jev 交出它，ledger 的记录里存它，两个模块互不引用（见第五部分）。 + +- **Jev 用哪个模型**：作为参数传入，来自 config（见第五部分）。 +- **调不通**：网络断开、超时、服务返回错误，在发请求那一处有限次重试（CLAUDE.md"错误怎么处理"）；仍然失败就报错停下，不能把"没判"当成"没问题"。重试次数和间隔写在代码里，写明理由。 +- **Jev 回的内容读不懂**：比如没有概率、概率不在 0 到 1 之间，这是外部服务的返回，属于系统边界，报错停下，带上请求编号。 +- **几对提案判完以后怎么合成几组**：纯计算，以后归 rules，这次不写。参考项目的 `dedup.ts` 不搬。 + +## 五、顺带改 ledger、vocab、config + +**ledger**（表结构变了，`SCHEMA_VERSION` 加 1）： +1. "模型调用结束"（`callEnded`）加一个墙钟时间字段，单位秒。结构.md 第三部分第 10 种和任务书 07 都要求 flow 把墙钟时间写进去（WORK_LOG"未完成"里那一条）。 +2. `callEnded` 的结束方式对上 agents 的四种结局：交了、没交（带原因）、出错（带原因）、被停下。现在只有 completed / failed 两种。 +3. "退回"（`rejection`）加一个字段，存这次退回用到的 Jev 判断。程序检查退回的，写 `null`。结构.md 第三部分第 3 种要求"退回理由含 Jev 的原始概率和结论"，现在退回记录只有一段文字。 + +判重合并是"决定"记录，它的输入本来就是 JSON，不用改。 + +这三处属于账本，写完派一个全新上下文的子 Agent 审阅（见第七部分）。 + +**config**： +- 加"Jev 用哪个模型"，属于用户配置，必填。配置对话以后照字段说明问。参考项目默认是 `jev-latest`，新项目不设默认值。 +- 密钥不进配置，照参考项目从环境变量读。 + +## 六、参考项目的保留与删除 + +| 处理 | 内容 | +|---|---| +| 借鉴，改说法后重新校准 | `questions.ts` 里判重、可行性、预扫三处的问法和示例句 | +| 借鉴 | `jev.ts` 读回答的做法；`audit.ts` 的发请求、带密钥 | +| 借鉴，改造后用 | `calibration.ts` 的校准流程；三组样本（标签不动） | +| 删除 | 指标换说法、指标规格具体性两处的问法、样本和校准 | +| 删除 | `C1_JEV_EXAMPLES`、`thresholdOverrides`、`UNCALIBRATED_JEV_SITES`：只有一个任务，阈值全部重新校准 | +| 删除 | `dedup.ts`：合成几组归 rules，以后再写 | +| 删除 | `httpAuditTransport` 里 `endpoint ?? AUDIT_ENDPOINT`、`fetchImpl ?? fetch` 这类可选参数：不设默认值，也不为测试给产品代码加参数 | +| 删除 | 发请求前检查"正文里有没有密钥"：密钥只从环境变量读进请求头，材料由 jev 自己从带类型的输入拼，没有路径会把它带进正文 | +| 不搬 | 结构.md 原来写的"永远判不同的空实现"：对照组已推迟，测试要用假 Jev 时在测试里自己写（结构.md 第五部分已删掉这句） | + +## 七、测试与审阅 + +- `npm test`，不花钱： + - 用假 Jev 测：概率超过阈值判"是"，不超过判"否"；回答读不懂时报错；调不通时重试到上限再报错； + - 问题哈希：改一个字，哈希就变； + - 材料：从带类型的输入拼出的材料，字段和校准时用的一致。用同一个函数拼，不另写一份； + - ledger 的三处改动各有测试：墙钟时间存得进、读得出；四种结束方式；退回记录带 Jev 判断或 `null`； + - config 少了 Jev 模型时报错。 +- 校准：另起的命令，花钱，见第三部分。 +- **审阅**：ledger 的三处改动属于账本，写完派一个全新上下文的子 Agent 审阅一轮。告诉审阅者： + - 每条意见先回答"不写会怎样"； + - 只防三类：没人操作也会发生的、模型正常工作时就会做的、出错后发现不了的； + - 模块之间传错参数、有人用 shell 故意破坏，只列出不改。 + + jev 本身按原型标准，校准本身就是对它最强的检查，不另审。 + +## 八、规模与文档 + +- jev 预期 400–600 行，不含校准脚本和样本。问题措辞和示例句会占一半左右。超过 600 行就停下来检查。 +- 完成后更新： + - `docs/结构.md` 第八部分：补 jev 对外的函数和类型；ledger、vocab、config 几节按第五部分改； + - `WORK_LOG.md`：在"已完成"补一条；删掉"未完成"里 `callEnded` 那一条。 +- 不新建 md 文件。校准目录里的 `README.md` 是校准记录，见第三部分第 5 条。 + +## 九、验收与报告 + +做完后本地提交，然后在回复里交一份报告，监督者会对着实际文件逐项核对： + +1. 提交号，新增和修改的文件列表，每个文件的行数，jev 的总行数。 +2. `npm run check`、`npm test` 的完整输出。 +3. 校准结果，九个问题每问一行：零错区间、抖动、阈值、留出集对错数，以及改过问法的问题改了什么、为什么。 +4. 转换不过来的样本：哪几条、为什么。 +5. 校准一共问了多少次 Jev。 +6. 审阅意见逐条：内容、采纳或不采纳、理由。 +7. 你和这份任务书、结构.md、方法.md 不一致的地方，以及为什么。 +8. **规则不清楚的地方**：读 CLAUDE.md、结构.md、方法.md、Jev 使用指南时，哪里让你犹豫、哪里两份文件说法不一致、哪里你是靠猜的。没有就写"没有"。没有真实证据的可能情况，在这里提一句就够，不写进 WORK_LOG。