英文 writeup 体例

阶段: B18 · OSS 收口 + 英文 + 全局 SOTA 复核（Day 171-180） 标签: #technical-writeup #problem-repro-fix-eval #cohens-kappa #bootstrap-ci

今日导引（由浅入深）

Day 174 学了 OSS 选题方法论、复现了一个外部 bug。今天把「复现/去循环」这类素材转成可对外的英文技术 writeup——学标准体例 problem → repro → fix → eval，并把本仓最干净的一个真实叙事（evalBaseline.ts 循环自评 → groundTruthEval.ts 独立 ground-truth）写成英文 README 段落。

在 B1→B18 曲线上，这一天是「内功 → 对外可读资产」的关键一跳：前 174 天积累的真值（A/B Δ+10.3pp、judge-human κ harness）只有写成外人能核验的英文叙事，才算「能力外显」。上承 Day 174 的复现 log，下接 Day 176-178 的「抽独立 repo + 真实提 PR」（英文 README 是 PR 描述的底稿）。

最小可判定产出：README.en.md 草稿 + 1 张 κ-harness 数据流图，committed（纯文档产物，可立即落地）。

1. 机理精读

技术 writeup 的标准结构：problem → repro → fix → eval。 四段，每段配可核验证据（命令、数字、图），不靠主观形容词：

• problem：问题是什么、为什么是问题（量化或可复现）。
• repro：怎么重现这个问题（命令 + 观察到的现象）。
• fix：改了什么、为什么这样改。
• eval：改完后用什么数字证明它真的好了（before/after，带样本量/CI）。

依据：Anthropic "Demystifying evals" (2026-01) 的「以可核验证据论证」原则。

为什么这套体例长青：把「我觉得」换成「这是数字」。 reviewer / 读者不信形容词（"more robust"、"cleaner"），信可核验证据。

problem→repro→fix→eval 强制每一步落到证据上：problem 必须可复现、fix 必须有 eval 数字背书。这正是本仓贯穿 B14-B18 的母题——不报裸结论，报带 CI 的数字。

本仓的真实 problem→fix 叙事：循环自评 → 独立 ground-truth。 这是写英文 README 的最佳素材，因为它是一个真实发生过的修复：

• problem：src/aml/evalBaseline.ts 用同一个规则引擎（assessCase 的 topTypology）预测，又拿同一作者写的合成金标评——predict 与 label 同源，分数虚高、不可信（循环自评）。
• fix：迁到 src/aml/groundTruthEval.ts 的 prediction-source-agnostic 评测——binaryEval 只吃 {label, predicted} 对，两者都可来自外部源（label 来自公开标注集、predicted 来自真实 LLM），切断同源循环。
• eval：用 binaryEvalWithCI 给 recall/precision/FPR 配 bootstrap 95% CI；A/B 案例段引真值 Δ+10.3pp、95% CI[0,20.7]、not-sig@N=29 作为「eval 严谨性」示范——方向性正但不显著，诚实标「需 ~70 任务才有 power」。

κ-harness 数据流：judge 不被信任、被校准。 README 配的那张图讲清一件事——hand labels → cohensKappa.ts → judge-human κ：

人手标 ≥50 条金标，judge 的判定与人标配对算 Cohen's κ + bootstrap CI，量化「judge 比偶然一致多多少」。这是「LLM-as-judge 不能当唯一信号」的可视化落点，也是 README 里 eval-rigor 段的核心图。

边界：英文 writeup ≠ 翻译笔记。 writeup 是给外部 reviewer 看的「可独立核验的故事」，不是中文笔记的逐句英译。它必须自带 repro 命令与数字，让读者不依赖本仓上下文就能判断对错——这是它和内部学习笔记的根本区别。

2. 推导 / 手算 / 代码走读

今天是文档日，但引用的全是本仓真实文件（已用 Read 打开）。κ-harness 与 binary eval 的真实符号：

1. src/agent/eval/cohensKappa.ts 的 cohensKappa(a, b)（line 22）：算 po（observed agreement，line 34）、pe（chance-expected agreement，line 42-43）、κ=(po−pe)/(1−pe)（line 48）。退化 margins（pe==1）按约定：完全一致报 1，否则 0。
2. cohensKappaWithCI(a, b, opts)（line 53）：对 N 个配对重采样 B 次（默认 2000）算 κ 分布，取 percentile 2.5 / 97.5 当 95% CI（line 79）。头注（line 4）直说「small N => wide CI — the reason P1 wants N>=50」——这是 README 里「为什么 κ 还不能下结论」的数学依据。RNG 可注入 ⇒ 确定性可单测。
3. src/aml/groundTruthEval.ts 的 binaryEval(items, normalLabel)（line 38）：把多类 typology 折叠成二分类（suspicious vs normal），算 tp/fp/tn/fn + recall/precision/fpr/f1。注释（line 36-37）提醒：分母为 0 时这些率返回 0，要查原始 tp/fp/tn/fn 区分「无支撑」与「真 0 率」。
4. binaryEvalWithCI(items, opts)（line 65）：对 recall/precision/fpr 各配 percentile bootstrap 95% CI（line 89-90），RNG 可注入。这是 README eval 段「带 CI 的外部 ground-truth 指标」的引擎。
5. 数学一致性：cohensKappa.ts 与 groundTruthEval.ts 都用同一套 percentile bootstrap（后者 import { percentile } from '../agent/eval/stats'，line 9）——README 里说「所有区间都是同一套 bootstrap 方法」是真的，不是话术。

κ 手算小例（写进 README 图注）： 人标 vs judge 在 N=50 上 po=0.86，若 pe=0.5，则：

κ = (0.86 − 0.5) / (1 − 0.5) = 0.72（substantial agreement）。

但 N=50 的 bootstrap CI 仍可能跨 0.6——所以 README 诚实写「κ harness 已建，hand-label 仍待补（≥50）」，不报未测的 κ 值。

README.en.md 骨架（four-section，写进今日产出）：

# agent-evals

## Problem
The rule engine that *predicts* (assessCase→topTypology) was graded against
a gold set authored by the *same* generator — a circular self-eval. Scores
were inflated and untrustworthy.

## Repro
`pnpm test` over evalBaseline.ts shows recall computed from same-source labels.

## Fix
Move to groundTruthEval.ts — binaryEval scores {label, predicted} pairs where
BOTH come from EXTERNAL sources (public labeled set + a real LLM).

## Eval
binaryEvalWithCI reports recall/precision/FPR with a bootstrap 95% CI.
A/B (V4-Pro vs V4-Flash, N=29): Δ +10.3pp, 95% CI [0, 20.7] — directionally
better but NOT significant (needs ~70 tasks for power).

骨架里每段都挂一个可核验锚点：problem 挂 evalBaseline.ts、fix 挂 groundTruthEval.ts、eval 挂带 CI 的真值数字。reviewer 顺着锚点能自己核验，不依赖我口述。

3. 今日实战

按 seed 落地（指向真实路径）：

1. 写 agent-evals 英文 README.en.md 草稿，按 problem → repro → fix → eval 四段组织。
2. problem/fix 段写循环自评 → 独立 ground-truth 迁移：引 src/aml/evalBaseline.ts（循环）与 src/aml/groundTruthEval.ts（binaryEval/binaryEvalWithCI，recall/precision/FPR + bootstrap CI）。
3. eval 段引真值 A/B Δ+10.3pp、95% CI[0,20.7]、not-sig@N=29 作 eval-rigor 案例。
4. 配 1 张 κ-harness 数据流图：hand labels → src/agent/eval/cohensKappa.ts → judge-human κ。
5. README.en.md 草稿 + 图 committed。

4. 今日实测 / 产出

• README.en.md draft + 1 diagram committed（文档产物，可立即落地）。
• 可引真实数（逐字保留）：A/B Δ +10.3pp、95% CI[0,20.7]、not-sig@N=29 作为 eval-rigor 案例段。
• κ-harness 的 hand-label 仍待补（≥50）——README 诚实标「待补」，不报未测的 κ 数值。

5. 常见误区 / 陷阱

1. 用形容词代替数字："more robust"/"cleaner" 不可核验；每个论断须配命令/数字/图（problem→repro→fix→eval 的强制项）。
2. 报未测的 κ：κ harness 已建但 hand-label ≥50 仍待补，README 不能写出一个具体 κ 值假装测过。
3. eval 段漏样本量/CI：只贴 Δ+10.3pp 不贴 CI[0,20.7]/N=29，会掩盖「方向性正但不显著」的真相。
4. 把 fix 写成「重写」而非「去循环」：fix 的核心是切断 predict/label 同源（prediction-source-agnostic），不是泛泛的「代码更干净」。

6. 学习资源（每条带 YYYY-MM）

• Anthropic, Demystifying evals（以可核验证据论证 + grade outcome）— 2026-01
• 本仓 src/aml/groundTruthEval.ts（binaryEval/binaryEvalWithCI，prediction-source-agnostic + bootstrap CI）— 2026
• 本仓 src/agent/eval/cohensKappa.ts（Cohen's κ + percentile bootstrap CI，κ harness）— 2026
• 本仓 src/aml/evalBaseline.ts（循环自评反面教材，problem 段引用）— 2026

SOTA检查 (2026-06 更新)

• 当前主流：problem → repro → fix → eval 体例长青，是技术 writeup 的标准结构。
• 是否仍 SOTA：是。bootstrap CI / Cohen's κ 为评测严谨性标准做法，非过时——本仓 cohensKappaWithCI / binaryEvalWithCI 即其实现。
• 过时黑名单：避免无 CI / 无样本量的裸 pass-rate 叙事；避免用形容词代替可核验证据。
• 下次复查点：κ harness 的 hand-label 仍待补（≥50）——补齐后 README eval 段需回填真实 κ + CI；A/B 扩到 ~70 任务后回填显著性结论。

衔接

• 昨天：Day 174 — OSS PR 选题与 good-first-issue 定位（复现 log 是 writeup 的 repro 段素材）
• 今天：学 problem→repro→fix→eval 体例，把循环自评→独立 ground-truth 写成英文 README + κ-harness 数据流图
• 明天：Day 176 — 抽独立公开 repo 工程化（把 agent-evals 纯 TS 闭包抽成独立 repo，README.en.md 即其门面）