# 任务书 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。