返回 AICAP-180
B18 · Day 178OSS 收口 + 英文 + 全局 SOTA 复核

提 PR + 英文沟通

B18 的能力曲线在这里到达「对外说服」的顶点：

阶段: B18 · OSS 收口 + 英文 + 全局 SOTA 复核（Day 171-180） 标签: #pull-request #before-after-evidence #confidence-interval #english-writeup

今日导引（由浅入深）

B18 的能力曲线在这里到达「对外说服」的顶点：

  • Day 176 让代码外部可验证（独立 repo + CI）；
  • Day 177 让一个修复物理上存在（fork branch + 单测）；
  • 今天要把它正式提成一个 状态 open 的上游 PR，并用英文写出能说服素未谋面 reviewer 的正文。

整套 AICAP 训练里最稀缺的能力不是写代码，而是用可核验的数字而非主观形容词去论证一个改动值得合入——这恰好是 AISA（AI Solutions Architect）面试官「四问」里反复考的：你怎么证明它更好？今天就把这套论证范式落到一个真实 PR 上。今日最小可判定产出：一条 open 状态的 PR 链接 + 英文正文，正文含 before/after 数字。

1. 机理精读

PR 描述的标准三段式：motivation / changes / test evidence。

  • motivation 说「为什么需要这个改动」（链到 issue、描述 bug 的现实影响）；
  • changes 说「具体改了什么」（文件、逻辑、API 影响）；
  • test evidence 说「怎么验证它有效」（新增测试、before/after 输出、命令可复跑）；
  • reviewer 的时间极其有限，这三段让他在 30 秒内判断「值不值得合」。依据：OSS PR best practices（2026）。

说服 reviewer 的关键是贴可核验数字，而非主观描述。

  • 「这让代码更健壮」是主观的、不可证伪的。
  • 「before: 503 路径下抛 unhandled，after: 退避重试 3 次后优雅降级，新增测试覆盖该路径」是可核验的。
  • 证据强度排序：带样本量与置信区间的数字 > 单点数字 > 形容词——这是 2026 eval 严谨性共识。

为什么本仓的真实 eval 数字是最好的论证范式？ seed 让我们复用本仓 A/B 结果作为论证模板：

  • V4-Pro vs V4-Flash，N=29，Δ +10.3pp，95% CI [0, 20.7]，3 wins / 0 losses / 26 ties → directionally better but NOT significant（需 ~70 任务才有 power）。
  • 这组数字本身就是一堂「如何诚实论证」的课：方向上更好（+10.3pp、3 胜 0 负），但 CI 下界触及 0、26 平局，所以不能宣称显著。
  • 必须如实说「directionally better, not significant」，并指出要 ~70 任务才有功效。
  • 把这种「贴 CI、标样本量、不夸大」的口吻搬进 PR 正文，比任何「significantly improves」的空话都更让 reviewer 信任。

为什么 CI[lo,hi] 而非单点均值是共识？

  • 单点均值（如「Δ=+10.3pp」）隐藏了不确定性——在 N=29 这种小样本下，真实差异可能落在 [0, 20.7] 的任何位置，甚至贴近 0。
  • 只报均值会诱导读者高估证据强度；报区间则诚实暴露「样本不够，结论待定」。
  • 这正是为什么本仓 abCompare.ts / ab-compare.ts 始终输出 ci95 而非裸均值。

与相邻概念的边界。

  • 今天是「提 PR + 写正文」，不是「PR 被 merge」（合入是后续不可控外部事件）。
  • 也不是「写一篇博客」——PR 正文是给 reviewer 看的工程文档，简洁、可核验、链到证据即可，不需要叙事铺陈。
  • 今天的判定边界：PR 状态 = open，正文含 before/after 数字。

2. 代码走读：本仓佐证脚本（就绪，可被 PR 正文引用为范式）

seed 点名两个「已就绪」的脚本，它们正是「贴可核验数字」论证范式的来源（均已 Read）：

  • scripts/ab-compare.ts（pnpm eval:ab）— 无 key，读 agent-evals/reports/ 下存好的两份报告（缺省取最新两份，最新=A、次新=B），调 abCompare(A, B)，打印：
    • completion A / completion B（百分比）
    • paired Δ(A-B): X pp 95% CI [lo pp, hi pp]
    • per-task: A wins W, B wins L, ties T
    • verdict：ci95[0] > 0 ? 'A significantly better' : ci95[1] < 0 ? 'B significantly better' : 'not significant (CI crosses 0)' —— 即显著性判定逻辑写死在代码里，CI 跨 0 即判 not significant。
    • 末尾输出一条 QUOTABLE 字符串："A vs B on N=…: Δ completion = …pp [95% CI …, …]"——这正是可以直接粘进 PR / 简历的句子模板。
    • 这解释了 N=29 那组数字的「not significant」从何而来：ci95 = [0, 20.7]，下界=0 不 >0，故判定 not significant。
  • scripts/eval-gate.ts（pnpm eval:gate，fail-closed）— 无 key，读最新报告对比 agent-evals/baseline.json，阈值 { maxCompletionDrop: 0.05, minKappa: 0.6, maxUnknownRate: 0.25 }，回归则 process.exit(1)。fail-closed 的体现：无报告时 process.exit(0) 跳过（不阻塞），但一旦有报告且违阈，非零退出阻断合入。这是「CI 门」如何用数字守护质量的真实样例，可在 PR 正文里作为「我们如何防回归」的论据。

走读结论（两脚本各自承担 PR 论证的一半）：

  • abCompare.ts 的 QUOTABLE 输出 —— 提供「before/after 数字怎么贴」的句子模板（N + Δ + CI + 显著性判定）。
  • eval-gate.ts 的阈值门（maxCompletionDrop 0.05 / minKappa 0.6 / maxUnknownRate 0.25，fail-closed）—— 提供「怎么证明不引回归」的机制论据。
  • 二者合起来正是 PR test-evidence 段的现成骨架：先用 QUOTABLE 给结论，再用 gate 说明回归防线。

3. 今日实战

  1. 把 Day 177 push 到 fork branch 的 fix 提成上游 PR（状态 open）。
  2. 正文按 motivation / changes / test evidence 三段写（英文）。
  3. test evidence 段贴 before/after：bug 触发路径在 patch 前/后的行为差异 + 新增测试名 + 本地 npm test 通过数。
  4. 论证口吻参照本仓 QUOTABLE 范式——若涉及性能/正确率类对比，贴「N + Δ + 95% CI」而非裸均值；如本仓 A/B：V4-Pro vs V4-Flash on N=29: Δ +10.3pp [95% CI 0, 20.7]，并诚实标 directionally better but not significant。
  5. 链到 Day 174 选定的 issue 与本地复现 log。
  6. 提交后记录 PR 链接。

4. 今日实测 / 产出

  • PR 链接 1 条（状态 open）+ 英文正文：外部动作（seed 状态「外部动作 → 将产出 PR 链接 1 条（状态 open）+ 英文正文」）。未完成、不升级。
  • 可在正文复用的本仓已落地真实数字（论证范式，逐字保留）：A/B V4-Pro vs V4-Flash，N=29，Δ +10.3pp，95% CI [0, 20.7]，3 wins / 0 losses / 26 ties → directionally better but NOT significant（需 ~70 任务才有 power）。
  • 本仓佐证脚本已就绪：pnpm eval:ab（scripts/ab-compare.ts）、pnpm eval:gate（scripts/eval-gate.ts fail-closed）。
  • Block 里程碑参照：上游 OSS PR = 外部动作（未完成，状态待 open/merged，正文须含 before/after eval 数字）。

5. 常见误区 / 陷阱

  • 只贴 pass-rate 不带样本量/CI：N=29 即不显著的教训——单点数字会让 reviewer 高估证据强度。永远 N + Δ + CI 三件套。
  • 用形容词代替证据：「significantly improves」「much more robust」都是不可核验的。改成「before X, after Y, test Z covers it」。
  • PR 正文写成叙事长文：reviewer 要的是 30 秒可判定的工程文档，不是博客。三段式、链到证据、收尾。
  • 夸大显著性：CI 跨 0 / 大量 ties 时，必须如实写「directionally better, not significant」。在 AML/合规语境下尤其，过度宣称会被立刻识破并失信。
  • 把提 PR 当成里程碑达成：open 只是中间态，merge 与否不可控；Block 里程碑明确「未完成」。
  • before/after 不可复跑：只贴一句「测试通过了」而不给命令/报告路径，reviewer 无法独立复现。贴 pnpm eval:ab 这类可复跑命令 + 报告文件名，让证据可被对方亲手验证。
  • 把验收逻辑写进散文：显著性结论应来自代码（abCompare.ts 里 ci95[0]>0 ? 显著 : 跨0则 not significant），而非手写判断——避免人为误判。

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

  • GitHub「About pull requests」+「Helpfully reviewing/writing PRs」官方文档，2026。
  • OSS PR best practices（motivation/changes/test-evidence 模板），2026 社区通行实践。
  • Anthropic「Demystifying evals」（2026-01）——「贴 CI 而非单点」的严谨性来源。
  • 本仓 scripts/ab-compare.ts（pnpm eval:ab，QUOTABLE 输出范式，本日已走读）。
  • 本仓 scripts/eval-gate.ts（pnpm eval:gate，fail-closed 门，阈值 maxCompletionDrop 0.05 / minKappa 0.6 / maxUnknownRate 0.25，本日已走读）。
  • 统计功效与置信区间科普（bootstrap CI、所需样本量），经典统计长青打底。

SOTA检查 (2026-06 更新)

  • motivation / changes / test-evidence 模板 长青，仍 SOTA。
  • 贴 CI[lo,hi] 而非单点均值 是 2026 eval 严谨性共识，仍 SOTA。
  • 当前主流做法：报告 N + Δ + 95% CI + 显著性判定（CI 跨 0 即 not significant），并附可复跑命令——abCompare.ts 的 QUOTABLE 输出即此范式的代码化。
  • 过时黑名单：
    • 避免只贴 pass-rate 不带样本量/CI（N=29 即不显著的教训）；
    • 避免用主观形容词替代可核验证据。
  • 下次复查点：
    • PR 提交后跟踪 reviewer 反馈，确认目标 repo 当周未冻结分支；
    • 若上游对 PR 模板有更新（部分 repo 用 .github/PULL_REQUEST_TEMPLATE.md），按其字段补齐。

衔接

  • 昨天：Day 177 — 真实 OSS PR 实现（fix + 1 单测，本地全套绿，push fork branch）
  • 今天：把修复提成 open 状态上游 PR，英文正文贴 before/after + N/Δ/CI 数字
  • 明天：Day 179 — HF Agents Course Unit4 GAIA（用本仓 provider-agnostic runner 跑 GAIA L1，取 leaderboard 分数）
上一篇 · Day 177
真实 OSS PR 实现
下一篇 · Day 179
HF Agents Course Unit4 GAIA