ZeKaiNie/universal-examprep-skill / full
universal-exam-cram-coach-full
Verified帮助学生在临考前进行结构化极速复习:解析课程资料/大纲/重点,按章节生成 wiki 知识库与标准题库,组织针对性刷题与判分,并记录复习进度和错题。当用户即将考试、需要快速复习计划、练习题、错题复盘或考前小抄时使用(关键词:期末/备考/复习/刷题/划重点/错题;exam, cram, study plan, quiz, review)。不适用于长期学习规划、与考试无关的写作或编程任务。
benchmark/docs/测试流程详解.md
View on GitHub# 测试流程详解:这个「防幻觉 benchmark」到底在测什么、怎么测
[English](testing-walkthrough.en.md) · 中文
> 面向第一次接触的人,一步步、通俗地讲清楚 `benchmark/` 这套东西。读完你应该能回答三个问题:
> **我们想证明什么?用什么数据证明?数字是怎么算出来的、为什么可信?**
>
> 配套文件:总览看 [`../README.md`](../README.md),指标出处看 [`related_benchmarks.md`](related_benchmarks.md),数据来源看 [`materials_sources.md`](materials_sources.md)。
---
## 0. 一句话总览
我们要用**真实公开课的数据**,测出一个结论:
> 给 AI 装上这个备考 skill(把课件先建成「知识库 / wiki」,答题时**按需检索**而不是凭记忆乱编),
> 它在「基于你自己课件的问答」上,**是不是真的更少胡编、更老实地承认「材料里没有」**。
README 里那种「90% / 100%」的宣传数字,谁都能写。这个 benchmark 的意义就是:**用可复现的实验和统计,把宣传换成证据。**
---
## 1. 先建立直觉:三种「考试方式」
整套测试的核心,是让**同一批题目**用三种不同的「考试方式」去答,再比谁答得好、谁更少瞎编。这三种方式就是**主对照三臂(primary matrix arms)**:
| 臂 | 代号 | 通俗比喻 | 实际做法 |
| :-- | :-- | :-- | :-- |
| **闭卷** | `closedbook` | 不给书,全凭脑子里记得的 | 提示里**不给任何课程材料**,只靠模型自己的知识答 |
| **裸文件 + 通用 agent** | `rawfiles` | 把一堆讲义丢桌上,自己翻 | 原始讲义/习题文件放进一个文件夹,模型用通用文件读取/检索工具**按需查阅,但不装本技能** |
| **skill(惰性检索)** | `skill` | 开卷,且有一个会查目录的助教 | 课件先被建成 `references/wiki/` 知识库,模型**按需检索相关章节**再答 |
`rawfiles` 是**最公平的对照**——直接回答「丢个文件夹给 AI 自己读不就行了,还要技能干嘛」;`skill` 与它的差距,才是技能的真实增量。
> **遗留/压力臂(legacy / stress footnote,非主对照):`material` / dump-all。**
> 早期还设过一个「给全材料」对照臂(`material`,把**整门课全文一股脑塞进提示**)。它**不是公平对照**,现仅保留为**压力脚注**:
> **实测发现,把 20 讲全文 dump 给弱模型(Haiku),它反而被淹没、答得更差**,且超大提示常触发上下文/用量上限而**根本跑不出答案**——这恰好印证「整本贴进去」不可行,而非一个值得并列的方案。早期 `run_benchmark.py` 的 `baseline`(只给原始材料)也属此类,已被更公平的 `rawfiles` 取代。
---
## 2. 关键材料:「金标题集」和「越界探针」
要打分,先得有**标准答案**。我们为每门课手工编了一套**金标题集(gold set)**,每道题是一行 JSON:
```json
{"id": "psyc_01",
"question": "According to Lecture 2, which Nobel Prize-winning biologist described ...?",
"gold_answer": "Francis Crick",
"supporting_span": "the Nobel Prize winning biologist, Francis Crick, described as \"The Astonishing Hypothesis.\"",
"source_file": "materials/psych_yale_psyc110/lecture02.md",
"answer_type": "factual",
"answerable": true}
```
逐字段解释:
- **`question`**:题面(英文题面对标英文原始讲义,避免翻译损耗)。
- **`gold_answer`**:标准答案。
- **`supporting_span`**:**这道题的答案在原讲义里的出处原文**。判分时只拿这段当依据——这是「防瞎判」的关键。
- **`answer_type`**:`factual`(事实)/ `definition`(定义)/ `numeric`(计算题,会用确定性判分)。
- **`answerable`**:**是否可答**。
### 越界探针(out-of-scope probe):`answerable: false`
这是整套测试**最能体现「防幻觉」**的设计。我们故意混入一批**材料里根本没有答案**的题,比如:
```json
{"id": "psyc_p01",
"question": "How many students were enrolled in PSYC 110 when it was recorded?",
"gold_answer": "", "answerable": false}
```
对这种题,**唯一正确的行为是老实说「材料中未涵盖」**。
- 如果模型老实弃答 → 加分(它没有瞎编)。
- 如果模型硬编一个数字 → 这**就是一次幻觉**,扣分。
> 6.006 那门课:65 题 = **55 道可答题 + 10 道越界探针**。
### 两份题集:带答案的(本地) vs 只有题面的(盲测/可公开)
- `items_*_full.jsonl`:**带标准答案**的完整金标,**不进公开仓库**(可能逐字引用了版权讲义)。
- `items_*_full_q.jsonl`:**只有题面、没有答案**的版本,喂给被测模型时用——保证模型是「真答」而不是「抄答案」,这一份可以公开。
---
## 3. 五个指标:分别在量什么(通俗版)
| 指标 | 箭头 | 大白话 | 严格定义 |
| :-- | :-- | :-- | :-- |
| **正确率 correctness** | ↑越高越好 | 答对了几道 | 对金标的整体正确比例 |
| **忠实度 faithfulness** | ↑ | 「有出处的话」占多少 | 答案拆成原子论断后,**能被 `supporting_span` 支持的**比例 |
| **幻觉率 hallucination** | ↓越低越好 | 「张口就编」的题占多少 | 含 ≥1 条**无依据/与材料矛盾**论断的题的占比 |
| **越界弃答率 abstention(OOS)** | ↑ | 不会的题里,**老实说不会**的比例 | 越界探针上正确弃答的比例 |
| **多轮收敛 convergence** | ↑ | 知识库越全,是不是答得越好 | skill 臂随 wiki 章节增多,正确率的变化 |
每个指标都**对标了业界权威基准**(FACTS Grounding、Vectara HHEM、RAGAS、RGB 等,见 [`related_benchmarks.md`](related_benchmarks.md)),这样数字不是我们自己拍脑袋定义的。
---
## 4. 判分(judge):数字怎么从一句答案里抠出来
判分逻辑全在 [`../judge.py`](../judge.py),分三种情况:
### (a) 越界探针 → 看它弃没弃答
检查答案里有没有「材料中未涵盖 / not covered / 无法确定」这类**弃答标记**(`ABSTAIN_MARKERS`)。
弃答 = 正确、零幻觉;硬答 = 一次幻觉。**全程不用 LLM,确定性判。**
### (b) 计算题(`numeric`)→ 确定性数值比对
把答案里的**最后一个数字**抠出来,和 `gold_answer` 在容差内比大小(`check_numeric`)。
**也不用 LLM**——真值是精确的,就不该引入裁判噪声。
### (c) 事实/定义题 → 「逐条论断」式 LLM 裁判
这是唯一用到 AI 裁判的地方,但做了几层防偏置设计:
1. **拆成原子论断**:让裁判把答案拆成一条条「最小事实陈述」,逐条判断**能不能由 `supporting_span` 推出**(1=能 / 0=不能或矛盾)。`忠实度 = 支持的条数 / 总条数`。
2. **只许看依据、不许用自己的知识**:prompt 明确要求裁判**只依据给定 span** 判断,杜绝「裁判自己也记得答案所以放水」。
3. **盲判**:裁判**不知道这条答案来自哪个臂**(闭卷?skill?),避免偏向。
4. **多次复评 + 多数投票**:同一题判 `judge_repeats` 次,取多数;并记录**裁判自一致性** `judge_self_consistency`(多次判得一不一致,反映裁判稳不稳)。
5. **裁判≠生成器**:尽量用**不同家族**的模型当裁判。本轮 6.006 用 **Sonnet** 判分(被测的有 Opus/Sonnet/Haiku——所以这点还不完美,见第 9 节诚实边界)。
---
## 5. 统计(stats):为什么不是「算个平均就完事」
小样本最容易犯的错就是「看见 72% > 70% 就宣布 skill 赢了」。[`../stats.py`](../stats.py) 用三件工具把这种过度宣称挡住:
- **McNemar 检验** `mcnemar()`:因为同一道题过了所有臂,是**配对数据**,只有「两臂答得不一样」的题才携带信息。它检验「skill 比对照少幻觉」是不是统计上真实,而非运气。
- **配对 bootstrap 置信区间** `paired_bootstrap_ci()`:对「差值」给一个 95% 区间,告诉你这个提升的不确定范围有多大。
- **Cohen's kappa** `cohen_kappa()`:算「人工判 vs AI 裁判」的一致性,是**信任裁判数字之前的一道闸**。
**显著性铁律**(`significant()`):只有当**置信区间下界 > 0** 且 **McNemar p < 0.05** 时,才敢说「显著」。否则就老老实实按「描述性 + 区间 + 样本有限」来写——**这恰恰是学术上站得住的写法**。
---
## 6. 端到端完整流程(7 步)
这是真正「跑一次测试」的全流程:
```
1. 备课件 ──→ 2. 真 ingest 建 wiki ──→ 3. 出金标(含越界探针) ──→ 4. 三臂×各模型盲测
│
7. 整合报告 ←── 6. 多轮反馈循环 ←── 5. 判分(数值确定性 + 盲判 + 人工kappa)
```
1. **备完整课件**:把一门公开课的全部讲义放进 `materials/<课程>/`(版权内容,**不入公开仓库**)。
2. **真 ingest 建知识库**:用 skill 的 `scripts/ingest.py` 把讲义切成 `skill_workspace/.../references/wiki/ch01..N.md`——这是 skill 臂真正会去检索的东西。
3. **编金标**:手写 40~55 道可答题(覆盖各讲)+ 10 道越界探针,存成 `items/items_*_full.jsonl`,并生成只含题面的 `_q.jsonl`。
4. **三臂盲测**:每道题分别用三个臂、各个模型(Opus/Sonnet/Haiku)答一遍。驱动方式是 **Claude Code 无头模式 `claude -p`**,用你登录的**订阅**身份,**不需要 API key**(三臂×多模型矩阵由 [`gen.py`](../gen.py) 逐格生成、可断点续跑;[`run_benchmark.py`](../run_benchmark.py) 是早期的两臂脚手架)。
5. **判分**:按第 4 节的三种判分逻辑给每条答案打分。
6. **多轮反馈循环**:把 skill 的知识库从「残缺」逐步补全(wiki 7 章 → 14 章 → 20 章),看正确率是不是随之爬升——证明「知识库越全,答得越准」这条因果。
7. **整合报告**:所有数字汇总成中英双语 HTML 报告 + 对比图。
> **想先不花额度看看管线长什么样?** 用 mock(占位答案,假数字,纯验证流程):
> ```
> cd benchmark
> python run_benchmark.py --mock --items items/items.example.jsonl
> ```
> 然后浏览器打开 `results_mock/report.html`(mock 默认写 `results_mock/`,绝不覆盖已提交的真报告 `results/report.html`)。**真跑**则去掉 `--mock` 并配 `config.json`。
---
## 7. 生成、判分、报告:谁产数据、谁只渲染
**生成路径(谁真的跑模型、产答案):**
- [`run_benchmark.py`](../run_benchmark.py):较早的**两臂脚手架**(baseline vs skill),`--mock` 可空跑验证管线。
- [`gen.py`](../gen.py):较新的**矩阵答案生成**路径,按 `课程 × 模型 × 臂` 生成答案、**可断点续跑、记录每格成本**(写 `results/matrix/gen_answers.jsonl`)。注意它是**按可行性排序的增量补齐器**(rawfiles 两门课 + PSYC closedbook/skill + 仅 algo material 报错重跑 + PSYC material),**依赖既有 `answers.jsonl`**,并非从零重建整张矩阵——故已发布矩阵无法仅凭本仓库脚本从零复现。
- [`rejudge.py`](../rejudge.py):用修正后的 `judge.py` **重判已存答案**,写 `results/matrix/summary_corrected.json`。
**报告器(只渲染,不计算):**
- [`report.py`](../report.py):早期**两臂**(baseline vs skill)的报告器,产出 `results/report.html`。
- [`report_matrix.py`](../report_matrix.py):矩阵报告器,产出 `results/matrix/report.html` + 一组独立对比图 SVG(正确率/幻觉率/越界弃答/收敛各一张,中英各一份)。主对照臂定义(`closedbook` / `rawfiles` / `skill`)写在它的 `ARMS` 常量里。
- [`rounds.py`](../rounds.py):画**多轮收敛折线图**(`results/convergence.html`),展示第 6 步「逐轮补全知识库」的效果。
所有数字的「单一事实来源」是 `results/matrix/summary.json`,报告器只是把它渲染成图表。
> **诚实标注**:`report_matrix.py` 只**渲染** `summary.json`,本身不计算。从**显式**的 answer/score 行聚合出 `summary.json` 的提交版聚合器 [`aggregate_matrix.py`](../aggregate_matrix.py) 已补上(配 [`run_matrix.py`](../run_matrix.py) 通用三臂 runner),**流水线机制**用微型 fixture 即可从干净 checkout 复现(见 [`matrix_pipeline.md`](matrix_pipeline.md))。但已发布的 `summary.json` 仍是**预先计算**的产物——聚合器只复现机制、不复现已发布的付费跑数字。
---
## 8. 真实结果速读(MIT 6.006 算法,n=65,Sonnet 判分)
数据来自 `results/matrix/summary.json`。怎么读:**对每个模型,比较它在各臂下的表现。** 判分由 Sonnet 完成、数值题程序精确比对,并经人工 16 题抽查校准(见第 9 节,Cohen's kappa = 0.875)。
> **注(臂口径)**:下面这张早期速读表的对照列是**遗留/压力臂 `给全材料`(material)**,不是主对照臂。当前**主对照三臂是 `closedbook` / `rawfiles` / `skill`**——含 `rawfiles`(裸文件 + 通用 agent)的完整三臂×三模型矩阵见 [`../README.md`](../README.md) 与 [`../results/matrix/report.html`](../results/matrix/report.html)。此处数字保留原样以存档,仅作历史速读。
**正确率(↑)**
| 模型 | 闭卷 | 给全材料¹ | skill |
| :-- | :-- | :-- | :-- |
| Opus | 16% | 88% | **91%** |
| Sonnet | 49% | 93% | **85%** |
| Haiku | 18% | —² | **93%** |
¹ material 仅在真答案上计分(剔除限流报错):Opus n=50、Sonnet n=27。 ² Haiku 的 material 65 题仅 2 题跑通,样本太小不列。
**越界弃答率(↑,越界题上老实说「不会」的比例)**
| 模型 | 闭卷 | 给全材料 | skill |
| :-- | :-- | :-- | :-- |
| Opus | 60% | 100% | **100%** |
| Sonnet | 50% | —² | **100%** |
| Haiku | 60% | —² | **100%** |
**怎么解读这两张表(这就是结论):**
1. **skill 臂三个模型正确率都最高(85–93%),且都 > 闭卷。**
2. **「给全材料」不是好办法**:它**跑通时**正确率与 skill 相当(Opus 88%、Sonnet 93%),但把整门课(~10万 token)塞进提示会**频繁超出模型一次处理的量、触发用量限制**——Haiku 上 65 题仅 **2 题跑通**(其余无法返回有效作答,故不计分)。这种工程上的不可行,正是 skill **章节化按需检索**(每次提问短小、稳定、便宜)的实际价值。
3. **越界弃答:skill 三个模型都 100%**(材料没有的题,零瞎编)。
4. **幻觉率要诚实读**:skill 的 claim 级幻觉 20–29% 不是最低——因为严判会把「正确但补充了出处段落没写的细节」也记一次幻觉,这不等于编造(真·捏造看越界探针,skill=100% 老实)。
**多轮收敛**:skill 臂随知识库 7→14→20 章补全,正确率 **28% → 62% → 87%**——知识库越全,答得越准,因果链清楚。
**另一门:Yale PSYC 110(文科,真实跑、三模型)** 闭卷 vs skill 正确率:Opus **60%→98%**、Sonnet **55%→92%**、Haiku **55%→80%**;越界弃答 skill **三模型全 100%**(闭卷 80–90%)。文科课同样大幅占优。(PSYC 的 material 臂 ~24万 token 超上下文、跑不起来——本身印证「dump 全课」不可行。)
---
## 9. 诚实边界(哪些还不能当定论)
做实验最值钱的就是这一节。当前结果**已知的局限**:
- **判分已做两次独立人工校准**:① 抽查 16 题、人工与判分结果逐题对照,Cohen's kappa = **0.875**;② 用 B5 的通用校准方法学(`calibrate_matrix` 同款流程:可答判对/判错 + 越界弃答/未弃答**四层分层**、判分对人**隐藏**、先过滤配额错误答案)再标 **24 题**,一致率 91.7%、Cohen's kappa = **0.833**。两次均高度一致(≥0.8)互相印证;两次里观察到的人机分歧**全部是判分偏严**(把正确答案判错,如 OCEAN 题的 Extraversion 拼写变体被判错)——这是抽样迹象(不构成对全部判分的证明),提示数字倾向保守而非虚高。**判分仍只用单一家族(Sonnet)**,是已知局限。
- **幻觉率指标偏严**:claim 级严判会惩罚「正确但展开充分」的答案(见上),所以 skill 的幻觉率不是它的强项——它的强项是正确率 + 越界弃答。
- **样本偏小**:6.006 n=65、PSYC n=50,统计功效有限——按「描述性 + 区间」呈现,不硬称显著。
- **重判后仍有极少数 judge_error**(~9/495 道 LLM 仍返回空,保守算未对)。
> 这些不是「藏起来的缺点」,而是**故意写明的边界**——一个会说清「我这个数字在什么条件下才成立」的报告,比一个只喊「100%」的报告可信得多。
---
## 10. 隐私 / 版权边界:什么入库、什么不入库
由 [`../.gitignore`](../.gitignore) 把关:
- **绝不进公开仓库**(本地保留):版权讲义原文(MIT/Yale 转录)、含答案 key 的完整金标 `items_*_full.jsonl`、原始逐题日志 `raw*.jsonl` / `answers` / `scores`、skill 生成的知识库、人工校准标注。
- **可入库**:只含题面的金标 `_q.jsonl`、聚合汇总 `summary.json`、报告 `report.html` 与对比图 SVG、全部测试代码。
原则:**能复现、能背书的都公开;可能侵犯版权或泄露答案的都本地留存。**
---
## 11. 文件地图(一句话记住每个文件)
```
benchmark/
run_benchmark.py # 较早的两臂脚手架(baseline vs skill);--mock 可空跑验证管线
gen.py # 较新的矩阵答案生成:按可行性增量补齐(依赖既有 answers.jsonl)、可续跑、记录每格成本
judge.py # 判分:越界看弃答 / 计算题确定性 / 事实题逐条论断 LLM 盲判
rejudge.py # 用修正后的 judge 重判已存答案 → summary_corrected.json
stats.py # 配对统计:McNemar + bootstrap 置信区间 + Cohen's kappa
report.py # 两臂报告器(中英双语 HTML + 引用)
report_matrix.py # 矩阵报告器:只渲染预先算好的 summary.json(主对照臂 closedbook/rawfiles/skill)
rounds.py # 多轮收敛折线图(知识库逐轮补全的效果)
items/ # 金标题集(_full 带答案=本地;_q 仅题面=可公开)
materials/ # 原始课件(版权,全本地)
skill_workspace/ # skill 臂的运行目录(references/wiki + quiz_bank)
calibration/ # 人工标注子集(裁判 kappa 校准用)
results/ # 运行产物(summary.json + 报告 + 对比图)
tests/ # 脚本自测:cd benchmark && python -m unittest discover -s tests
docs/ # 方法学与引用(本文件 + 指标出处 + 数据来源)
```
---
## 12. 一句话总结
> **同一批题、三种考法、盲judge打分、配对统计兜底、再用越界探针专门抓瞎编。**
> 结论不靠形容词,靠**可复现的数字 + 写明边界的诚实**——这才是给一个「防幻觉」主张该有的背书方式。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |