From 99c64fec46db73ea93dfc1dfcd2c6e931ddcb6ec Mon Sep 17 00:00:00 2001
From: windyboy <windyboy@gmail.com>
Date: Mon, 24 Aug 2026 17:52:43 +0800
Subject: [PATCH] add go-docs-qa practice project: project overview and
 task-and-rubric

---
 .../00-Foundations/04-Concepts-and-Theory.md  | 2665 +++++++++++++++--
 .../LLM_Evaluation/00-Foundations/README.md   |    2 +-
 .../01-go-docs-qa/00-project-overview.md      |   56 +
 .../01-go-docs-qa/01-task-and-rubric.md       |   49 +
 .../LLM_Evaluation/99-Attachments/.gitkeep    |    1 -
 5 files changed, 2600 insertions(+), 173 deletions(-)
 create mode 100644 01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/00-project-overview.md
 create mode 100644 01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/01-task-and-rubric.md
 delete mode 100644 01_Projects/Personal-Tech/LLM_Evaluation/99-Attachments/.gitkeep

diff --git a/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/04-Concepts-and-Theory.md b/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/04-Concepts-and-Theory.md
index df8b9a1..e80cdc7 100644
--- a/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/04-Concepts-and-Theory.md
+++ b/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/04-Concepts-and-Theory.md
@@ -5,229 +5,2552 @@ tags:
   - foundations
 status: active
 created: 2026-08-24
+updated: 2026-08-24
 ---
 
 # LLM 评测基础概念与理论：系统讲解
 
-**定位：** 本文是前三篇概念笔记的**教学整合**——以 [[01-What-Is-LLM-Evaluation]]、[[02-Annotation-Human-Data-and-Evaluation]]、[[03-Core-Concept-Map]] 为骨架，补全背后的理论逻辑，并加入"信度 / 效度"这一贯穿性测量学视角。目标不是记住术语，而是理解**每个概念为什么必须存在**。
+**定位：** 本文是 [[01-What-Is-LLM-Evaluation]]、[[02-Annotation-Human-Data-and-Evaluation]]、[[03-Core-Concept-Map]] 的教学整合版。重点不是堆术语，而是建立一套可以继续承载 RAG Eval、Agent Eval、LLM-as-a-Judge、Benchmark Design 等主题的基础框架。
 
-> 术语速查仍以 [[03-Core-Concept-Map]] 为准；本文负责"讲清楚为什么"。
+> [[03-Core-Concept-Map]] 负责术语速查；本文负责解释：**为什么要这样测、结果为什么可信、结果又能支持什么结论。**
 
-## 一、评测的定义与最小结构
+---
 
-**LLM Evaluation = 用一组明确的任务、测试数据和评分逻辑，系统地判断模型或 AI 系统是否满足预期行为。**
+## 0. 先建立总框架：评测是一条“构念 → 测量 → 决策”的链
 
-最小的不变结构是五段：
+假设产品需求是：
+
+> “这个客服 Agent 要可靠、合规，而且真的能把事情办成。”
+
+这里的“可靠”“合规”“办成”都不是可以直接观测的数字。评测首先要把这些抽象目标转成可执行条件，再通过测试取得证据。
 
 ```text
-Task / Case（测什么）
-    ↓
-System under test（被测系统：可能是裸模型，也可能是完整产品链路）
-    ↓
-Output / Trace / Outcome（系统产生的东西）
-    ↓
-Grader（评分逻辑：代码、人或另一个模型）
-    ↓
-Result（可比较、可解释的结果）
+Product Requirement
+        ↓
+Construct（想测的抽象属性）
+        ↓
+Operationalization（操作化）
+        ↓
+Success Criteria / Rubric
+        ↓
+Eval Cases / Dataset
+        ↓
+System Execution
+        ↓
+Output / Trace / Outcome
+        ↓
+Grader / Measurement
+        ↓
+Metrics + Uncertainty
+        ↓
+Diagnosis
+        ↓
+Decision
 ```
 
-用测试工程的语言说：这就是"测试用例 → 被测对象 → 实际行为 → 断言 → 测试报告"。OpenAI 与 Anthropic 的官方评测框架都采用这个结构。**评测不是一门"给 AI 打分的学问"，而是给 AI 系统建立的测试与测量体系。**
+因此，LLM 评测不是单纯“给模型打分”，而是在做三件事：
 
-## 二、理论根基：LLM 评测为什么本质上很难
+1. **定义正确**：什么行为才算满足需求？
+2. **测量正确**：我们怎样稳定、有效地观察这种行为？
+3. **使用正确**：这个结果足以支持选模型、上线、回滚或修复吗？
 
-这是理解后面所有概念的钥匙。传统软件测试的三个隐含假设，在 LLM 系统上全部失效。
-
-### 困难一：没有唯一正确答案
-
-`add(1, 2)` 必须等于 3，但"解释什么是缓存"有无数个可接受答案。评测的核心问题从"输出是否等于标准答案"变成"**输出是否落在可接受集合内**"。
-
-由此直接推导出两个结论：
-
-1. **Rubric（判定集合成员资格的规则）比 reference answer（集合中的一个样本）更根本**；
-2. 字符串比较只在确定性任务上有效。
-
-### 困难二：非确定性
-
-模型带采样温度、Agent 的工具调用路径每次可能不同。"这个 case 通过了吗"这个问题本身不严谨，严格的问法是"**这个 case 在 N 次尝试中通过了几次**"——这就是 trial 概念的由来。
-
-### 困难三：评分器本身会出错
-
-代码断言不会撒谎，但 LLM Judge 有偏差（偏好长答案、偏好位置 A），人工标注者会疲劳误判。于是评测有一个递归问题：**谁来评判评判者？** 这就是校准（calibration）、一致率（IAA）、混淆矩阵存在的原因。
-
-### 应对策略：操作化定义
-
-面对这三个困难，整个学科的应对主线只有一条：
-
-> **操作化定义（Operational Definition）**：把模糊的构念（"回答专业""有用"）改写为可被第三方执行和复现的判定条件（"每一条可核验事实均可由给定上下文支持，否则 fail"）。
-
-这个词来自测量理论。一个测量要成立，必须同时满足两件事：
-
-| 测量学概念 | 含义 | 对应的评测实践 |
-|---|---|---|
-| **信度（Reliability）** | 不同的人（或同一人不同时间、不同的 Judge）依据同一规则，能否得出相同结论 | 双人独立标注、盲评、一致率（IAA）、多次 trial |
-| **效度（Validity）** | 你测的是不是你真正想测的东西 | rubric 从产品需求推导、Judge 与人工校准、失败归因 |
-
-记住这对概念，就能给所有零散实践找到理论坐标：**盲评和 IAA 提升信度；校准和需求追溯提升效度。** [[01-LLM-Evaluation-Roadmap]] 中"标注即规格工程"的说法，规格工程的本质就是操作化定义。
-
-## 三、核心对象词汇：按"测什么 / 怎么判 / 怎么跑"三组记忆
-
-### A 组：测什么（数据侧对象）
-
-| 概念 | 含义 | 关键理解 |
-|---|---|---|
-| **Task** | 一个测试问题 + 成功条件 | 最小测试单元 |
-| **Eval Case** | 一条具体测试数据，含 input、expected behavior、metadata（类别/难度/风险/版本） | 相当于一条测试用例；metadata 让失败可分组分析 |
-| **Dataset / Eval Set** | 一组 case | 不是"很多问题"，而是有设计意图的分布：正常、负例、边界、对抗、历史回归 |
-| **Eval Suite** | 围绕一个产品目标组织的一组 dataset | 如客服套件 = 退款 + 取消 + 升级 + 合规 |
-
-### B 组：怎么判（规格侧对象）
-
-三个概念必须严格区分：
-
-- **Rubric**：判定规则本身（"Groundedness = fail，如果回答包含至少一个上下文未支持的事实"）。它是**规格（specification）**，不是分数。好的 rubric 的检验标准是：独立评审能得出相近结论。
-- **Reference Answer**：一个可接受答案的**示例**。它是集合中的一个成员，不是集合的定义。
-- **Grader**：真正执行评分的**组件**（人或程序或模型）。同一份 rubric 可以被不同 grader 执行。
-
-三者的关系：**rubric 是法律条文，reference 是判例，grader 是法官。** 混淆它们是新手最常见的概念错误——比如拿 reference 当 rubric 用（只做相似度比较），或以为换一个更强的模型当 Judge 就不需要 rubric。
-
-Grader 分三类，各有适用域：
-
-| 类型 | 适用 | 例子 |
-|---|---|---|
-| **Code-based** | 确定性条件 | JSON Schema 校验、SQL 是否可执行、单元测试是否通过、状态断言 |
-| **Human** | 复杂业务判断、rubric 校准、高风险仲裁 | 盲评、分歧仲裁 |
-| **Model-based（LLM-as-a-Judge）** | 难以硬编码的语义判断 | 相关性、完整性、是否遵从复杂规则——**但必须先与人工校准** |
-
-实践原则是混合使用：能写代码判的绝不麻烦人，必须人判的用来建立基准和校准，模型 Judge 只在校准通过后用于规模化。
-
-### C 组：怎么跑（执行侧对象）
-
-- **Run**：某系统版本在某数据集版本上的一次执行记录。必须保存版本三元组（system/prompt version、dataset version、rubric version）+ 输出 + 时间戳，否则两次 run 的差异无法归因。
-- **Trial**：同一 task 的一次独立尝试（应对非确定性）。
-- **Trace / Transcript**：Agent 的完整执行轨迹（输入 → 推理 → 工具调用 → 工具结果 → …… → 最终回答）。
-- **Outcome**：执行结束后**环境的真实最终状态**。
-- **Harness**：端到端跑评测的基础设施：装载 case → 调用系统 → 记录 trace → 运行 grader → 汇总报告，即 LLM 版的 test runner。
-
-最重要的理论区分是 **Trace ≠ Outcome ≠ 最终文本**。Agent 说"会议已取消"只是文本；trace 记录它声称做了什么；outcome 才是日历里那个事件是否真的没了。**Agent 评测的第一原则：评价真实结果，不评价最终文本。**
-
-## 四、评测的四个层级：从 Output 到 Outcome
+可以进一步压缩成六个动词：
 
 ```text
-Level 1 — Output     最终文本是否正确
-Level 2 — Component  检索/工具/路由等组件是否正确
-Level 3 — Trace      执行路径是否合理、安全
-Level 4 — Outcome    真实环境最终状态是否满足目标
+Define → Sample → Execute → Measure → Validate → Improve
 ```
 
-越简单的系统越可以停在 Level 1（裸模型答 trivia）；越接近 Agent，越必须下沉到 Level 4。因为 Agent 的典型失败模式是"**话说得对，事没办成**"——只看 Level 1 会完全漏检。
+---
 
-与层级互补的是横向划分——**Model Evaluation vs. System Evaluation**。前者测 `Prompt → Model → Response`；后者测完整链路（路由 → 检索 → 模型 → 工具 → 状态变更 → 后处理）。系统评测的铁律：**一条失败不能直接归因"模型不行"**。RAG 答错可能因为检索根本没取回 gold context——那是检索组件的问题，换再强的模型也没用。
+## 一、什么是 LLM Evaluation
 
-## 五、三种评测形态：Benchmark、Product Eval、Monitoring
+一个实用定义是：
 
-| 形态 | 回答的问题 | 特点 |
-|---|---|---|
-| **Benchmark** | 模型一般能力有多强？ | 固定任务集、对外可比较、通用能力指标（数学/代码/知识） |
-| **Product Eval** | 对**我的**产品任务，它是否满足要求？ | 真实成功标准、真实用户路径、风险与边界 case、历史回归 |
-| **Monitoring** | 生产环境**现在**发生了什么？ | 用户反馈、失败日志、A/B test、用户重新提问/纠正行为 |
+> **LLM Evaluation 是针对模型或 AI 系统设计可重复测试，通过明确的成功标准和评分方法取得行为证据，并据此判断系统是否满足目标要求的过程。**
 
-关键理论点：**benchmark 分数高 ≠ 适合你的产品**。benchmark 测的是通用能力分布，你的产品关心的是特定任务分布上的表现。三者的成熟闭环：
+最小结构：
 
 ```text
-Benchmark 筛选候选模型 → Product Eval 决定是否适用于产品
-→ Monitoring 发现真实失败 → 固化为回归 case → 回流 Eval Set
+Task / Case
+    ↓
+System Under Test
+    ↓
+Observed Behavior
+    ↓
+Grader
+    ↓
+Result
 ```
 
-由此引出另一组二分法：**Offline Eval vs. Online Eval**。Offline 在冻结数据集上重复运行，用于方案比较和发布门禁，优点是可复现、可归因；Online 信号来自真实使用环境，优点是真实、能发现你想不到的失败，缺点是噪声大、不可控。两者不是替代关系——online 的最大价值之一是为 offline 持续供应新 case。
+如果是 Agent，还要把“Observed Behavior”拆开：
 
-## 六、人工数据理论：Annotation、Human Data、Evaluation 的关系
+```text
+Output      最终输出
+Trace       执行过程
+Outcome     最终环境状态
+```
 
-三个词经常被当成一回事，实际是包含关系：
+用传统软件测试语言类比：
 
-- **Annotation（标注）**：人按给定规则把原始数据转换为带结构化意义的数据。传统 ML 是打标签（cat/dog）；LLM 场景的"标注"经常是**执行复杂 rubric 的判断工作**——比较两个回答、给 trace 做失败分类、把差答案改写成理想答案。
-- **Human Data**：更大的集合，为训练/对齐/评测/产品改进而产生的一切人类判断与示范数据。四种形态：Demonstration（示范，SFT 用）、Preference（偏好对）、Critique（带理由的批评）、Evaluation Labels（pass/fail、severity、failure type）。
-- **Evaluation**：用数据 + 规则判断系统表现。它**使用**标注，但不等于标注。
+```text
+Requirement
+→ Test Case
+→ System Under Test
+→ Actual Behavior
+→ Test Oracle / Assertion
+→ Test Result
+```
 
-关键理论区分：**同样的标注工作，用途决定性质。**
+这里有一个特别重要、但经常被 LLM 教程省略的概念：
+
+### Test Oracle（测试判据）
+
+**Oracle 是“我们凭什么知道结果对不对”的依据。**
+
+它可能是：
+
+- 唯一正确答案；
+- 数据库最终状态；
+- 单元测试；
+- 业务规则；
+- Rubric；
+- 人类专家判断；
+- 经过校准的 LLM Judge。
+
+`Grader` 是执行判断的组件；`Oracle` 是判断成立所依赖的正确性依据。
+
+因此：
+
+```text
+Oracle = 正确性的依据
+Grader = 执行判断的机制
+```
+
+这个区分很重要，因为**代码 grader 也可能错**：代码本身可以完全确定地执行一个错误的 specification。
+
+---
+
+## 二、为什么 LLM 评测比普通单元测试困难
+
+### 2.1 开放任务没有唯一正确答案
+
+例如：
+
+```text
+add(1, 2)
+```
+
+只有一个正确结果：
+
+```text
+3
+```
+
+但：
+
+> “向初学者解释什么是缓存。”
+
+可能存在很多合格答案。
+
+于是问题从：
+
+> 输出是否等于 reference？
+
+变成：
+
+> 输出是否属于“可接受行为集合”？
+
+可以把它想成：
+
+```text
+所有可能输出
+├── 不可接受
+└── 可接受集合
+    ├── 合格答案 A
+    ├── 合格答案 B
+    └── 合格答案 C
+```
+
+因此开放任务中：
+
+- **Rubric** 更像集合边界；
+- **Reference Answer** 更像集合里的一个实例。
+
+但不能绝对化。
+
+在以下任务中，reference 本身就可能是最好的 oracle：
+
+- 数值答案；
+- 分类标签；
+- JSON 结构；
+- SQL 执行结果；
+- 文件状态；
+- 单元测试结果。
+
+所以准确的原则是：
+
+> **开放任务优先定义行为标准；确定性任务优先使用可验证结果。**
+
+---
+
+### 2.2 系统行为具有随机性
+
+同一个 case 重复执行：
+
+```text
+Trial 1 → PASS
+Trial 2 → FAIL
+Trial 3 → PASS
+```
+
+所以“这个 case 是否通过”有时只是一次采样。
+
+更完整的问题是：
+
+> **这个系统在这个任务上的成功概率和稳定性如何？**
+
+这就是 `trial` 和重复测量存在的工程原因。
+
+但这里必须区分两个不同概念：
+
+#### 被测系统的行为稳定性
+
+例如 Agent 同一任务十次成功八次。
+
+这是：
+
+```text
+system behavior variability
+```
+
+它反映系统本身的随机性和可靠性。
+
+#### 测量工具的稳定性
+
+例如同一份回答：
+
+```text
+Judge Run 1 → PASS
+Judge Run 2 → FAIL
+```
+
+这是：
+
+```text
+measurement reliability
+```
+
+它反映 grader / annotator 是否稳定。
+
+**不要把这两类波动都笼统叫“信度”。**
+
+---
+
+### 2.3 Grader 本身也会错
+
+Human grader 可能：
+
+- 对 rubric 理解不同；
+- 疲劳；
+- 标准漂移；
+- 缺少领域知识。
+
+LLM Judge 可能：
+
+- 受位置影响；
+- 偏好某种表达风格；
+- 对冗长回答评分偏高；
+- 对模糊标准判断不稳定；
+- 被待评内容中的指令干扰。
+
+Code grader 也可能：
+
+- assertion 写错；
+- 环境假设错误；
+- reference solution 错；
+- 只验证了一个过窄实现路径。
+
+所以评测存在一个元问题：
+
+> **我们怎样验证测量工具本身？**
+
+这才是 Calibration、IAA、Human Reference Set、Confusion Matrix、Eval QA 存在的原因。
+
+---
+
+### 2.4 产品目标往往是多维的
+
+一个 Agent 可能同时要求：
+
+```text
+Task Success
+Safety
+Policy Compliance
+Groundedness
+Latency
+Cost
+User Experience
+```
+
+这些维度可能互相冲突。
+
+例如：
+
+```text
+更积极调用工具
+→ 任务成功率可能提高
+→ 成本和风险也可能提高
+```
+
+因此一个单一总分经常不足以表达真实产品质量。
+
+成熟做法通常是：
+
+```text
+多个独立指标
++
+必要的聚合
++
+关键风险 Hard Gate
+```
+
+而不是把所有东西压成一个 0–100 分。
+
+---
+
+### 2.5 评测结果依赖测试分布和执行环境
+
+一个模型得到：
+
+```text
+Benchmark A = 92%
+```
+
+只说明它在：
+
+```text
+Benchmark A 的任务分布
++
+对应 prompt / harness / grader / environment
+```
+
+下取得了这个结果。
+
+不能自动推出：
+
+> “它在所有真实业务上都有 92% 的能力。”
+
+这就是后面 Coverage、Product Eval、Holdout、Production Monitoring 都必须存在的原因。
+
+---
+
+## 三、操作化定义：把“好”变成“可测”
+
+### 3.1 Construct（构念）
+
+Construct 是我们真正想讨论、但不能直接观测的属性。
+
+例如：
+
+```text
+有用
+可靠
+安全
+忠实
+专业
+```
+
+这些词不能直接作为 grader。
+
+---
+
+### 3.2 Operationalization（操作化）
+
+操作化是把抽象构念转换成可观察条件。
+
+例如：
+
+```text
+“回答忠实”
+```
+
+改写成：
+
+> 回答中所有可外部核验的事实性陈述，都必须得到给定证据支持；否则 groundedness = FAIL。
+
+于是：
+
+```text
+Construct
+    ↓
+Operational Definition
+    ↓
+Observable Criteria
+```
+
+评测设计最核心的工作，往往就在这里。
+
+---
+
+## 四、测量学视角：Reliability 与 Validity
+
+### 4.1 Reliability：测量结果稳定吗？
+
+这里的 Reliability 指的是**测量过程的可靠性**。
+
+典型问题：
+
+> 不同标注者依据同一 rubric，会得到相近判断吗？
+
+> 同一个 Judge 对同一输入重复评分，会稳定吗？
+
+常见证据：
+
+- raw agreement；
+- Cohen's Kappa；
+- Krippendorff's Alpha；
+- 重复 Judge 运行；
+- 双人独立标注。
+
+需要注意：
+
+> **IAA 衡量的是评分者间一致性，不是模型本身的生产可靠性。**
+
+---
+
+### 4.2 Validity：这个测量支持我们想做的解释吗？
+
+Validity 更深一层。
+
+假设产品真正关心：
+
+> “退款有没有成功。”
+
+但 grader 只检查最终回答有没有说：
+
+```text
+退款成功。
+```
+
+这个 grader 可以做到 100% 稳定，却仍然测错东西。
+
+所以：
+
+```text
+Reliability 高
+≠
+Validity 高
+```
+
+---
+
+### 4.3 三个常用的效度视角
+
+下面采用经典测量学中常见的三个学习视角。它们不是唯一分类，但对 LLM Eval 很有帮助。
+
+#### Content Validity：内容覆盖够吗？
+
+问：
+
+> 测试内容有没有覆盖目标能力的重要部分？
+
+例如客服 Eval 全部都是正常退款，却完全没有：
+
+```text
+越权退款
+身份验证失败
+恶意用户
+边界金额
+重复请求
+```
+
+那么即使通过率很高，也可能存在 coverage 缺口。
+
+---
+
+#### Construct Validity：真的测到目标构念了吗？
+
+例如声称测：
+
+```text
+Groundedness
+```
+
+但 Judge 实际上主要因为：
+
+```text
+答案长
+语言正式
+引用很多
+```
+
+而给高分。
+
+这说明测量可能混入了别的因素。
+
+---
+
+#### Criterion-related Validity：与外部标准或真实结果有关吗？
+
+例如：
+
+```text
+Offline Eval Score ↑
+```
+
+是否对应：
+
+```text
+真实任务成功率 ↑
+用户投诉 ↓
+生产故障 ↓
+```
+
+如果完全脱节，就要重新检查 eval 是否代表真实业务。
+
+---
+
+### 4.4 一个重要提醒：效度不是“某个 rubric 天生拥有的属性”
+
+更准确地说：
+
+> **我们为某个测量结果及其用途提供多少有效证据。**
+
+同一个 benchmark：
+
+- 用于比较某类数学题能力，可能合理；
+- 用来证明“通用智能”，就可能过度外推。
+
+因此：
+
+```text
+Score
++
+Evaluation Context
++
+Intended Interpretation
+```
+
+必须一起看。
+
+---
+
+## 五、核心对象：Task、Case、Dataset、Suite
+
+不同框架术语并不完全统一。
+
+Anthropic 把：
+
+```text
+task ≈ problem ≈ test case
+```
+
+作为近义词。
+
+为了自己的 Obsidian 知识库更清晰，可以采用以下**本地约定**：
+
+### Task
+
+一个抽象测试意图。
+
+例如：
+
+> 测试 Agent 是否会拒绝越权删除。
+
+---
+
+### Eval Case
+
+Task 的具体实例。
+
+例如：
+
+```yaml
+task: unauthorized_delete
+input:
+  user_id: U1
+  request: "删除 U2 的文件"
+expected_behavior:
+  - refuse
+  - explain_permission_boundary
+metadata:
+  risk: high
+```
+
+于是：
+
+```text
+Task = 测什么类型的能力
+Case = 用什么具体实例来测
+```
+
+这是教学约定，不是行业强制标准。
+
+---
+
+### Dataset / Eval Set
+
+一组 cases。
+
+真正好的 Eval Set 不是“很多问题”，而是一个经过设计的测试分布。
+
+---
+
+### Eval Suite
+
+围绕某个能力或产品目标组织的一组 tasks / cases / datasets。
+
+例如：
+
+```text
+Customer Support Suite
+├── Refund
+├── Cancellation
+├── Authentication
+├── Escalation
+└── Policy Compliance
+```
+
+---
+
+## 六、规格侧对象：Rubric、Reference、Oracle、Grader
+
+这是最值得严格区分的一组概念。
+
+### Rubric
+
+**Rubric = 判定规则。**
+
+例如：
+
+```text
+Groundedness = FAIL
+if at least one externally verifiable factual claim
+is unsupported by the supplied evidence.
+```
+
+Rubric 是 specification 的一部分。
+
+---
+
+### Reference Answer / Reference Solution
+
+**Reference = 已知合格实例。**
+
+它可以用于：
+
+- 给 human / judge 提供 anchor；
+- 做相似度判断；
+- 验证 task 是否可解；
+- 验证 grader 是否配置正确。
+
+对于 Agent / coding eval，`reference solution` 还有很重要的 Eval QA 作用：
+
+> 如果一个已知正确方案都不能通过 grader，那么首先应该修 eval。
+
+---
+
+### Test Oracle
+
+**Oracle = 判断正确性的依据。**
+
+例如：
+
+```text
+expected database state
+unit tests
+business rules
+rubric
+expert consensus
+```
+
+Reference 可以是 oracle 的一部分，但二者不等价。
+
+---
+
+### Grader
+
+**Grader = 实际执行判断的组件。**
+
+可以记成：
+
+```text
+Rubric     = 规则
+Reference  = 合格实例
+Oracle     = 正确性依据
+Grader     = 执行判断
+```
+
+类比：
+
+```text
+法律条文 → Rubric
+判例     → Reference
+法律标准 → Oracle
+法官     → Grader
+```
+
+这个类比只是帮助记忆，不要把它当严格定义。
+
+---
+
+## 七、Grader 的三种基本类型
+
+### 7.1 Code-based
+
+适用于存在明确、可程序验证条件的任务。
+
+例如：
+
+- exact match；
+- regex；
+- JSON Schema；
+- SQL execution；
+- unit tests；
+- static analysis；
+- database state；
+- file existence；
+- tool arguments；
+- latency / token count。
+
+优点：
+
+```text
+便宜
+快
+稳定
+易调试
+```
+
+缺点：
+
+```text
+可能过度刚性
+容易漏掉有效变体
+实现错误时会稳定地判错
+```
+
+---
+
+### 7.2 Human
+
+适用于：
+
+- rubric 开发；
+- 专业领域判断；
+- 主观质量；
+- 高风险仲裁；
+- Judge 校准；
+- ambiguous case 分析。
+
+Human grader 最重要的作用不是“大规模生产标签”，而是：
+
+> **帮助建立可信的 reference standard。**
+
+主观任务里应该叫 `reference standard`，而不是轻易叫 `ground truth`。
+
+---
+
+### 7.3 Model-based / LLM-as-a-Judge
+
+适用于难以硬编码的语义条件：
+
+- completeness；
+- relevance；
+- style；
+- groundedness；
+- instruction following；
+- policy compliance。
+
+原则：
+
+> **LLM Judge 是 measurement instrument，不是天然真值。**
+
+使用前要验证：
+
+- 与 human reference 的一致性；
+- 关键失败的 recall；
+- 对 prompt / position / wording 的敏感性；
+- 重复运行稳定性。
+
+---
+
+### 7.4 Composite Grading
+
+复杂任务通常需要多个 grader。
+
+例如退款 Agent：
+
+```text
+Task Success
+├── State Grader
+│   └── refund.status == processed
+├── Policy Grader
+│   └── refund_amount <= allowed_limit
+├── Trace Grader
+│   └── identity_verified == true
+└── Communication Grader
+    └── explanation satisfies rubric
+```
+
+注意：
+
+> 多 grader 不等于一定要平均。
+
+常见组合方式：
+
+```text
+binary gate
+weighted score
+partial credit
+hybrid
+```
+
+高风险条件更适合作为：
+
+```text
+Hard Gate
+```
+
+---
+
+## 八、执行侧对象：Run、Trial、Trace、Outcome、Harness
+
+### Trial
+
+同一个 task / case 的一次尝试。
+
+```text
+Case A
+├── Trial 1
+├── Trial 2
+└── Trial 3
+```
+
+---
+
+### Run
+
+`Run` 更常表示一次版本化的评测执行。
+
+它可能包含：
+
+```text
+很多 cases
+×
+每个 case 的一个或多个 trials
+```
+
+建议保存：
+
+```text
+system version
+model version
+prompt version
+dataset version
+rubric version
+grader version
+sampling parameters
+environment version
+timestamp
+```
+
+否则：
+
+```text
+Run A = 82%
+Run B = 87%
+```
+
+无法判断变化来自哪里。
+
+> `run` 是框架相关术语，不同平台粒度可能不同；知识库中最好明确自己的约定。
+
+---
+
+### Trace / Transcript / Trajectory
+
+Agent 执行过程的记录，例如：
+
+```text
+User
+ ↓
+Model
+ ↓
+Tool Call
+ ↓
+Tool Result
+ ↓
+Model
+ ↓
+...
+ ↓
+Final Response
+```
+
+它回答：
+
+> **系统是怎么完成任务的？**
+
+---
+
+### Outcome
+
+执行结束后环境中的真实结果。
+
+例如：
+
+```text
+Output:
+"会议已经取消。"
+
+Trace:
+calendar.cancel(event_id)
+
+Outcome:
+event.status == cancelled
+```
+
+因此：
+
+```text
+Output ≠ Trace ≠ Outcome
+```
+
+---
+
+## 九、Agent Eval：结果与过程分别什么时候重要
+
+一个实用原则是：
+
+> **如果任务目标是改变外部世界，优先验证可观察的最终状态；如果路径本身属于安全、合规或资源约束，则同时验证 Trace。**
+
+例如删除文件：
+
+```text
+最终文件不存在
+```
+
+通常比：
+
+```text
+必须调用 rm
+```
+
+更重要。
+
+过度规定工具调用顺序会产生 brittle eval。
+
+但以下过程不能忽略：
+
+- authentication；
+- authorization；
+- policy checks；
+- prohibited tools；
+- secret access；
+- irreversible actions；
+- cost budget；
+- turn limit；
+- mandatory confirmation。
+
+所以可以记：
+
+```text
+Outcome:
+事情做成了吗？
+
+Trace:
+事情是以允许的方式做成的吗？
+```
+
+---
+
+## 十、一个教学用的四层评测视图
+
+下面的四层是**本文的教学框架，不是行业统一标准**：
+
+```text
+Level 1 — Output
+Level 2 — Component
+Level 3 — Trace
+Level 4 — Outcome
+```
+
+### Level 1：Output
+
+检查：
+
+```text
+文本正确性
+格式
+风格
+回答质量
+```
+
+### Level 2：Component
+
+检查：
+
+```text
+retrieval
+reranking
+routing
+tool selection
+SQL generation
+```
+
+### Level 3：Trace
+
+检查：
+
+```text
+步骤
+工具调用
+权限
+循环
+成本
+```
+
+### Level 4：Outcome
+
+检查：
+
+```text
+数据库状态
+文件
+订单
+日历
+真实执行结果
+```
+
+并不是所有系统都必须“做到 Level 4”。
+
+例如：
+
+- 纯问答任务的 outcome 可能就是答案本身；
+- research agent 的主要产物可能就是报告；
+- 只有真正改变外部状态的 Agent，Outcome 才特别关键。
+
+所以不要记成：
+
+> “越高层越专业。”
+
+应该记成：
+
+> **选择最接近产品真实成功条件的观测层。**
+
+---
+
+## 十一、Agent Harness 与 Eval Harness
+
+### Agent Harness / Scaffold
+
+负责让模型能够作为 Agent 行动：
+
+```text
+context management
+agent loop
+tool orchestration
+state handling
+```
+
+可以粗略写成：
+
+```text
+Model + Agent Harness = Agent System
+```
+
+---
+
+### Eval Harness
+
+负责测试 Agent System：
+
+```text
+Load Cases
+     ↓
+Initialize Environment
+     ↓
+Run Agent
+     ↓
+Capture Trace
+     ↓
+Inspect Outcome
+     ↓
+Run Graders
+     ↓
+Aggregate Results
+```
+
+因此：
+
+```text
+Agent Harness ≠ Eval Harness
+```
+
+而且：
+
+> Agent Eval 测到的通常是 `model + prompt + harness + tools + environment` 的组合，而不只是模型。
+
+---
+
+## 十二、Dataset Design：Coverage 比 case 数量更重要
+
+### 12.1 Coverage
+
+Eval 不可能覆盖整个输入空间。
+
+所以要问：
+
+> **测试集覆盖了哪些重要行为区域？**
+
+常见维度：
+
+```text
+task type
+difficulty
+risk
+user type
+language
+tool
+edge case
+failure mode
+environment condition
+```
+
+因此：
+
+> **Eval score 永远是特定测试分布上的表现。**
+
+---
+
+### 12.2 Positive 与 Negative Case
+
+只测试：
+
+```text
+应该搜索
+```
+
+可能把系统优化成：
+
+```text
+什么都搜索
+```
+
+所以还要测试：
+
+```text
+不应该搜索
+```
+
+同理：
+
+```text
+应该拒绝 / 不应该拒绝
+应该升级 / 不应该升级
+应该调用工具 / 不应该调用工具
+```
+
+这可以防止：
+
+```text
+one-sided optimization
+```
+
+---
+
+### 12.3 Capability Eval 与 Regression Eval
+
+#### Capability Eval
+
+问：
+
+> 目前能力边界在哪里？
+
+通常应该包含不少难题和失败。
+
+它提供：
+
+```text
+hill to climb
+```
+
+---
+
+#### Regression Eval
+
+问：
+
+> 以前已经可靠通过的能力有没有退化？
+
+目标通常接近：
+
+```text
+100% pass
+```
+
+所以成熟体系会同时有：
+
+```text
+Capability Suite
++
+Regression Suite
+```
+
+当 capability eval 接近饱和时，其中稳定通过的部分可以逐渐转入 regression suite。
+
+---
+
+### 12.4 Eval Saturation
+
+如果：
+
+```text
+Pass Rate ≈ 100%
+```
+
+可能意味着：
+
+1. 系统确实很好；
+2. 测试已经失去区分能力。
+
+饱和后的 suite 仍可以发现 regression，却很难继续测 capability improvement。
+
+---
+
+## 十三、Dev / Eval / Holdout 与 Contamination
+
+### Dev Set
+
+允许开发期频繁查看，用于：
+
+```text
+debug
+prompt iteration
+rubric development
+```
+
+### Eval Set
+
+用于正式比较和 release decision。
+
+在一次正式比较窗口中：
+
+```text
+dataset version
+grader version
+rubric version
+```
+
+应该固定。
+
+### Holdout
+
+更严格隐藏，用于检查：
+
+```text
+是否对已知 eval 过拟合
+```
+
+---
+
+### Evaluation Contamination
+
+当系统开发过程反复针对正式测试样本优化时：
+
+```text
+score ↑
+```
+
+可能只是：
+
+```text
+overfitting to eval
+```
+
+而不是：
+
+```text
+general capability ↑
+```
+
+公开 benchmark 还存在额外问题：
+
+> 模型预训练过程中可能已经见过题目或高度相似的数据。
+
+因此关键产品决策通常更值得依赖：
+
+```text
+private
+recent
+representative
+versioned
+```
+
+的产品 eval。
+
+---
+
+### 关于“冻结”的正确说法
+
+不要记成：
+
+> Eval Set 永远不能改。
+
+应该记成：
+
+> **一次比较所使用的版本必须冻结；长期 Eval Suite 则需要持续维护和版本化。**
+
+这同时服务于：
+
+```text
+reproducibility
++
+continued relevance
+```
+
+---
+
+## 十四、非确定性指标：pass@1、pass@k、pass^k
+
+假设某任务每次独立尝试成功概率都是 `p`。
+
+### pass@1
+
+就是单次成功概率。
+
+对于：
+
+> 用户通常只有一次真实交互机会
+
+首先应该关注：
+
+```text
+pass@1
+```
+
+---
+
+### pass@k
+
+k 次尝试至少成功一次：
+
+```text
+1 - (1-p)^k
+```
+
+适合：
+
+> 系统允许生成多个候选，只要一个成功即可。
+
+例如某些代码生成、搜索、候选方案场景。
+
+---
+
+### pass^k
+
+k 次尝试全部成功：
+
+```text
+p^k
+```
+
+它是一个更严格的**连续成功压力指标**。
+
+适合回答：
+
+> 如果重复执行很多次，这个行为能否持续稳定？
+
+---
+
+### 重要限制
+
+上面的简式公式假设：
+
+```text
+每次 trial 独立
++
+成功概率相同
+```
+
+实际 Agent 中可能不成立：
+
+- shared cache；
+- shared environment；
+- rate limit；
+- correlated tool failure；
+- task 难度不同。
+
+所以这些公式主要帮助理解概念。
+
+真实 benchmark 统计时，应区分：
+
+```text
+per-task empirical trials
+```
+
+与：
+
+```text
+across-task aggregate estimator
+```
+
+不要把一个简单的 `p` 当成所有 case 的共同成功率。
+
+---
+
+## 十五、结果是估计，不是真值
+
+假设：
+
+```text
+100 cases
+83 pass
+```
+
+我们观察到：
+
+```text
+83%
+```
+
+但这不是一个无限精确的“真实能力值”。
+
+可以用一个概念式理解：
+
+```text
+Observed Result
+=
+System Performance
++
+Sampling Variation
++
+Measurement Error
++
+Environment Noise
+```
+
+所以：
+
+```text
+A = 83%
+B = 84%
+```
+
+并不足以自动证明 B 更好。
+
+还要考虑：
+
+- sample size；
+- paired cases；
+- confidence interval；
+- bootstrap；
+- trial variability；
+- grader variability。
+
+---
+
+### 15.1 为什么 Paired Comparison 很重要
+
+比较两个系统时，最好让：
+
+```text
+System A
+System B
+```
+
+跑同一批 cases。
+
+这样可以直接观察：
+
+```text
+哪些 case 从 fail → pass
+哪些 case 从 pass → fail
+```
+
+比比较两个完全不同样本的平均分更容易归因。
+
+---
+
+### 15.2 Slice Analysis
+
+总分：
+
+```text
+Overall = 90%
+```
+
+可能隐藏：
+
+```text
+Normal = 99%
+Edge   = 88%
+Safety = 45%
+```
+
+所以必须按 metadata 切分：
+
+```text
+risk
+task
+difficulty
+language
+tool
+failure type
+```
+
+---
+
+### 15.3 Micro / Macro / Weighted
+
+#### Micro
+
+所有 case 放在一起计算。
+
+大类别自然占更大权重。
+
+#### Macro
+
+先按类别算，再对类别平均。
+
+适合：
+
+> 各类别业务意义接近，但样本数量不平衡。
+
+#### Weighted
+
+按产品价值人为赋权。
+
+例如：
+
+```text
+Task Success × 3
+Quality      × 2
+Style        × 1
+```
+
+但高风险指标通常不应该只靠加权：
+
+```text
+Safety Critical Failure = 0
+```
+
+往往比：
+
+```text
+Safety × 5
+```
+
+更符合真实发布决策。
+
+---
+
+## 十六、Human Data、Annotation 与 Evaluation
+
+### Annotation
+
+人按照规则对数据做结构化判断。
+
+例如：
+
+```text
+Answer A vs B → A better
+Trace → wrong_tool
+Response → pass / fail
+```
+
+---
+
+### Human Data
+
+范围更广，包括：
+
+#### Demonstration
+
+```text
+Instruction
+    ↓
+Human Ideal Response
+```
+
+常用于 SFT。
+
+#### Preference
+
+```text
+A > B
+```
+
+#### Critique
+
+指出：
+
+```text
+哪里错
+为什么错
+怎么改
+```
+
+#### Evaluation Labels
+
+例如：
+
+```text
+pass/fail
+severity
+failure_type
+score
+```
+
+---
+
+### Evaluation
+
+Evaluation 使用数据和规则衡量系统表现。
+
+所以：
+
+```text
+Annotation ≠ Evaluation
+```
+
+也不能简单说：
+
+```text
+Annotation ⊂ Evaluation
+```
+
+因为 annotation 还可以服务于训练、研究和数据治理。
+
+更准确的是：
+
+> **Annotation 是生产结构化 human judgment 的一种过程；Evaluation 可以使用这些判断。**
+
+---
+
+## 十七、Training Data 与 Evaluation Data
+
+同一条：
+
+```text
+Prompt + Ideal Answer
+```
+
+既可能用于训练，也可能用于评测。
+
+区别首先在用途：
 
 | | Training Data | Evaluation Data |
 |---|---|---|
-| 目的 | 改变模型行为 | 测量系统行为 |
-| 模型可以学它吗 | 可以，这正是目的 | 原则上不可以 |
-| 版本要求 | 训练集可演化 | 正式 eval 集需要冻结 |
-| 泄漏后果 | 数据质量问题 | **evaluation contamination**——结果彻底失真 |
+| 目的 | 改变系统行为 | 测量系统行为 |
+| 是否用于学习 | 是 | 正式评测原则上避免 |
+| 版本管理 | 同样需要版本化 | 比较窗口必须冻结 |
+| 泄漏问题 | 影响训练质量或泛化 | 直接损害评测解释 |
 
-Contamination（评测污染）指系统在开发中已经"见过并针对"了正式测试集，测出的分数过度乐观。这和 ML 里 train/test 不分家是同一个错误，对策也一样：dev / eval / holdout 分离，正式比较期间冻结。
+所以不要把二者说成：
 
-本部分最重要的一句话：**人工标注不是评测的低级阶段**，它承担两个不可跳过的职责——帮助定义"什么叫正确"（rubric 的来源），以及校准自动 grader 是否可信（暂定真值）。评测体系的演化路径是：人工判断 → 发现规则歧义 → 修 rubric → 建立稳定人工基准 → 规则自动化 / LLM Judge。跳过前面直接上 Judge，等于用一把没校准过的尺子量所有东西。
+> “训练集可以随便变，评测集必须永远不变。”
 
-## 七、判定方式与测量质量：一致率、校准、仲裁
+它们都需要严谨的数据治理，只是目标不同。
 
-### 四种评测形态（按比较方式）
+---
 
-- **Pointwise**：单独判一个输出 pass/fail。
-- **Pairwise**：比较 A/B，输出 A 更好 / B 更好 / tie。偏好数据和盲评都用它，因为人做相对判断比绝对打分更稳定。
-- **Absolute Score**：给单个输出打分（0/1/2 或 1–5）。**只有评分锚点足够清楚时才有意义**——这是 [[01-LLM-Evaluation-Roadmap]] 坚持第一版用 pass/fail 和 0/1/2、不用 1–5 分的理论依据：人无法稳定区分 3 分和 4 分，这样的量表没有信度。
-- 按**判定机制**分：**Deterministic**（程序可判：schema、exact match、unit test）vs. **Semantic**（必须理解语义：完整性、忠实度），后者必然依赖 human 或 model grader。
+## 十八、Calibration、Blind Review、IAA、Adjudication
 
-### 测量质量的三个概念
+这几个词解决不同问题。
 
-1. **Calibration（校准）**：多个标注者对同一批样本独立判断，再分析分歧。目的不是"凑一致率"，而是**通过分歧发现规格的漏洞**。
-2. **Inter-Annotator Agreement（IAA，标注者间一致率）**：量化信度的指标。入门用 raw agreement（相同标签数/总数）即可；成熟项目用 Cohen's Kappa、Krippendorff's Alpha——它们会扣除"随机也能一致"的部分。
-3. **Adjudication（仲裁）**：分歧无法通过修规则解决时（真实专业争议），由更高权限或领域专家裁决，并将该类 case 标记为不适合自动评分。
+### Blind Review
 
-对 LLM-as-a-Judge，校准理论落地为混淆矩阵：以人工盲评为暂定真值，报告 failure precision / failure recall / raw agreement 三个数。安全场景优先看 failure recall（漏放行的比例）而不是 precision，因为 **FN（危险输出被 Judge 放行）的代价远高于 FP（好输出被误拦）**——这是一个效度问题：测量工具必须对你最在乎的误差方向敏感。
-
-## 八、失败分析理论：Taxonomy、Severity、Root Cause
-
-测量只完成了一半，评测的产出价值在于失败分析。三个概念构成递进：
-
-1. **Failure Taxonomy（失败分类学）**：预先定义的失败类型集合。RAG 例：retrieval miss / unsupported claim / wrong citation / over-refusal；Agent 例：wrong tool / wrong arguments / authorization failure / state mismatch。没有分类学，你只有一堆 "fail"，无法统计分布。
-2. **Severity（严重度）**：区分失败的量级。理论依据：**格式问题 ≠ 数据误删 ≠ 权限泄漏**，平均通过率会把不可接受的失败稀释成可接受的平均数。所以高危失败必须单独门禁，不允许被平均。
-3. **Root Cause Analysis（根因分析）**：把"模型答错了"拆解到具体层——retrieval? prompt? model? tool? permission? post-processing? grader?。不同根因对应完全不同的修复动作和责任方；这是评测从"打分"升级为"工程决策依据"的关键一步。
-
-## 九、总图：把所有概念串成一条链
-
-[[03-Core-Concept-Map]] 第 10 节的主线图，逐环读法：
+尽量隐藏与任务无关但可能影响评分的信息，例如：
 
 ```text
-Product Requirement（产品需求）
-        ↓  操作化定义
-Rubric（判定规则）
-        ↓  实例化
-Eval Case → Dataset / Suite（测试数据）
-        ↓  执行
-Run / Trial → Trace + Outcome（执行记录与真实结果）
-        ↓  判定
-Grader → Result（评分与结果）
-        ↓  分析
-Failure Taxonomy → Root Cause（失败分类与根因）
-        ↓  改进与防回归
-Fix → Regression（修复与永久回归）
+模型品牌
+系统名称
+实验组身份
 ```
 
-**上半段是"定义正确"（需求→规则→数据），中段是"测量与暴露失败"（运行→判定），下半段是"区分根因、验证修改、防止回归"。** [[01-LLM-Evaluation-Roadmap]] 的 72 小时闭环和 12 周计划，本质就是把这条链的最小版本先跑通，再逐环加固。
+它主要用于：
 
-## 十、自测：十个检验理解的问题
+```text
+reduce bias
+```
 
-读完能不看书回答这些，概念层就过关了：
+并不等于“自动提高信度”。
 
-1. 为什么 rubric 比 reference answer 更根本？各自对应"可接受集合"的什么角色？
-2. 信度和效度分别指什么？盲评提升哪个，Judge 校准提升哪个？
-3. Task、Trial、Run、Trace、Outcome 五个词分别指什么，两两的区别是什么？
-4. 为什么 Agent 评测必须下沉到 Level 4？举一个"文本正确但 outcome 错误"的例子。
-5. Benchmark 分数更高的模型为什么可能不适合你的产品？
-6. Training data 和 evaluation data 在冻结要求上为何相反？
-7. Evaluation contamination 是怎么发生的？dev/eval/holdout 三分如何防它？
-8. 什么任务该用 code grader，什么任务必须用 human/model grader？
-9. 为什么第一版 rubric 不要用 1–5 分量表？
-10. 安全场景下 Judge 校准为什么优先看 failure recall 而不是 precision？
+---
+
+### Calibration
+
+多个评审者先独立判断同一批样本：
+
+```text
+Annotator A
+Annotator B
+Annotator C
+```
+
+然后分析分歧：
+
+```text
+rubric ambiguous?
+example missing?
+domain knowledge missing?
+case genuinely ambiguous?
+```
+
+所以 Calibration 的重要价值是：
+
+> **发现 specification 和 measurement 的问题。**
+
+---
+
+### IAA
+
+Inter-Annotator Agreement 衡量评分者的一致程度。
+
+#### Raw Agreement
+
+```text
+一致样本数 / 总样本数
+```
+
+直观，但不考虑类别分布和随机一致。
+
+#### Cohen's Kappa
+
+核心思想：
+
+```text
+(observed agreement - expected agreement)
+/
+(1 - expected agreement)
+```
+
+它尝试扣除按边际分布产生的 chance agreement。
+
+但不要记成：
+
+> “Kappa 永远比 raw agreement 更诚实。”
+
+Kappa 会受到类别 prevalence 和边际分布影响，并存在著名的 **kappa paradox**：
+
+```text
+raw agreement 很高
+但 kappa 可能很低
+```
+
+因此实践中应该同时查看：
+
+```text
+raw agreement
+class prevalence
+confusion pattern
+kappa / alpha 等指标
+```
+
+而不是迷信一个数字。
+
+---
+
+### Adjudication
+
+当分歧无法直接通过 rubric 修订解决时：
+
+```text
+Reviewer A
+   ↘
+   Expert
+   ↗
+Reviewer B
+```
+
+由更高权限或领域专家仲裁。
+
+真正没有明确答案的样本应该允许：
+
+```text
+ambiguous
+```
+
+而不是强行创造假“ground truth”。
+
+---
+
+## 十九、LLM-as-a-Judge：怎样校准
+
+假设 Human Reference Label：
+
+```text
+PASS / FAIL
+```
+
+并把 `FAIL` 定义成正类：
+
+| | Human FAIL | Human PASS |
+|---|---:|---:|
+| Judge FAIL | TP | FP |
+| Judge PASS | FN | TN |
+
+### Failure Recall
+
+```text
+TP / (TP + FN)
+```
+
+含义：
+
+> 所有真实 failure 中，有多少被 Judge 检出。
+
+### Failure Precision
+
+```text
+TP / (TP + FP)
+```
+
+含义：
+
+> Judge 判 failure 的样本中，有多少真的 failure。
+
+### False Negative Rate
+
+```text
+FN / (TP + FN)
+```
+
+所以：
+
+```text
+FNR = 1 - Failure Recall
+```
+
+安全场景常常更重视：
+
+```text
+high failure recall
+low false negative rate
+```
+
+因为真正危险的是：
+
+```text
+危险输出
+→ Judge PASS
+```
+
+注意正确表述：
+
+> **Failure Recall 不是“漏放行比例”；漏放行比例是 False Negative Rate。**
+
+---
+
+### 不要只看 Agreement
+
+如果：
+
+```text
+95% PASS
+5% FAIL
+```
+
+一个 Judge 永远预测：
+
+```text
+PASS
+```
+
+仍然可能得到：
+
+```text
+95% raw agreement
+```
+
+但：
+
+```text
+failure recall = 0%
+```
+
+所以 Judge 校准至少要看：
+
+```text
+confusion matrix
+precision / recall
+class distribution
+agreement
+```
+
+---
+
+### Multi-Judge Consensus 的边界
+
+多个 Judge 可以减少部分单模型随机性，但：
+
+> **多个相关模型可能共享同样的系统性偏差。**
+
+所以：
+
+```text
+3 个 Judge 同意
+```
+
+不等于：
+
+```text
+Human Validity 已证明
+```
+
+multi-judge 是工具，不是 human calibration 的替代品。
+
+---
+
+## 二十、Benchmark、Product Eval、Monitoring
+
+### Benchmark
+
+问：
+
+> 模型在一个标准化任务分布上的表现怎样？
+
+适合：
+
+- 横向比较；
+- 通用能力研究；
+- 筛选候选模型。
+
+---
+
+### Product Eval
+
+问：
+
+> 对我的产品和真实成功标准，它是否够好？
+
+例如客服系统真正可能关心：
+
+```text
+refund success
+unauthorized action rate
+false refusal rate
+escalation quality
+latency
+cost
+```
+
+因此：
+
+```text
+Benchmark 高
+≠
+Product Fit 高
+```
+
+---
+
+### Production Monitoring
+
+问：
+
+> 真实环境现在发生了什么？
+
+例如：
+
+- user feedback；
+- tool errors；
+- task completion；
+- repeated questions；
+- manual transcript review；
+- support escalation；
+- production incidents。
+
+---
+
+## 二十一、Offline Eval 与 Online Evidence
+
+### Offline
+
+优势：
+
+```text
+controlled
+repeatable
+fast
+safe
+```
+
+适合：
+
+```text
+CI
+model comparison
+prompt changes
+release gate
+```
+
+### Online
+
+优势：
+
+```text
+real users
+real distribution
+unexpected failure modes
+```
+
+但：
+
+```text
+noise high
+ground truth sparse
+user impact real
+```
+
+两者应该形成闭环：
+
+```text
+Offline Eval
+    ↓
+Deploy
+    ↓
+Monitoring / Feedback
+    ↓
+New Failure
+    ↓
+Curated Eval Case
+    ↓
+Regression Suite
+```
+
+---
+
+## 二十二、Goodhart's Law：作为警告，而不是绝对定律
+
+常见表述：
+
+> When a measure becomes a target, it ceases to be a good measure.
+
+它提醒我们：
+
+> 团队如果长期只优化一个公开指标，就可能逐渐优化“指标本身”，而不是原本真正关心的目标。
+
+但不要推导成：
+
+> “指标只有不当目标时才有意义。”
+
+工程团队当然可以围绕指标优化。
+
+更合理的防护是：
+
+```text
+多维指标
+private holdout
+真实生产信号
+定期更新 cases
+anti-gaming checks
+```
+
+所以 Goodhart 在 Eval 中更像：
+
+> **不要让 proxy metric 取代原始产品目标。**
+
+---
+
+## 二十三、Failure Taxonomy、Severity、Root Cause
+
+### Failure Taxonomy
+
+回答：
+
+> **发生了什么？**
+
+例如 RAG：
+
+```text
+retrieval_miss
+wrong_document
+unsupported_claim
+citation_error
+```
+
+Agent：
+
+```text
+wrong_tool
+wrong_arguments
+permission_failure
+planning_loop
+state_mismatch
+false_success_claim
+```
+
+---
+
+### Severity
+
+回答：
+
+> **有多严重？**
+
+例如：
+
+```text
+S0 Cosmetic
+S1 Minor
+S2 Major
+S3 Critical
+```
+
+这样：
+
+```text
+格式错误
+```
+
+和：
+
+```text
+越权删除数据
+```
+
+不会被当成同一种 fail。
+
+---
+
+### Root Cause Analysis
+
+回答：
+
+> **为什么发生？应该在哪一层修？**
+
+例如：
+
+```text
+Unsupported Answer
+```
+
+可能来自：
+
+```text
+retrieval miss
+context truncation
+prompt
+generation
+post-processing
+grader bug
+```
+
+所以：
+
+```text
+Observed Failure
+≠
+Model Failure
+```
+
+---
+
+### 一个重要修正：“根因是模型”并非永远错误
+
+如果已经排除了：
+
+```text
+data
+prompt
+retrieval
+tool
+environment
+grader
+```
+
+而模型在清晰、可解、稳定的任务上仍持续失败，那么：
+
+```text
+model capability limitation
+```
+
+完全可以是有效结论。
+
+根因分析的目标不是“永远不要怪模型”，而是：
+
+> **避免在没有证据时把系统失败直接归给模型。**
+
+---
+
+## 二十四、Eval Failure 也是 Failure
+
+成熟的 Eval 系统应该允许：
+
+```text
+eval_bug
+```
+
+例如：
+
+```text
+bad rubric
+broken grader
+incorrect reference
+unsolvable task
+environment issue
+harness issue
+```
+
+特别是：
+
+```text
+frontier model
++
+大量 trials
++
+始终 0%
+```
+
+首先应该检查：
+
+```text
+task 是否可解
+grader 是否公平
+environment 是否正常
+reference solution 是否能过
+```
+
+而不是马上断言：
+
+```text
+model incapable
+```
+
+---
+
+## 二十五、真正的 Eval Flywheel
+
+评测的价值不止是产生分数。
+
+完整工程闭环应该是：
+
+```text
+Production Failure
+       ↓
+Reproduce
+       ↓
+Create Eval Case
+       ↓
+Classify Failure
+       ↓
+Root Cause
+       ↓
+Fix
+       ↓
+Verify
+       ↓
+Add Regression Case
+```
+
+这件事的本质是：
+
+> **把一次偶然发现的失败，转成永久可执行的质量知识。**
+
+---
+
+## 二十六、十个常见错误心智模型
+
+### 1. Benchmark 高 = 产品一定好
+
+错误。
+
+正确：
+
+```text
+performance is distribution- and setup-dependent
+```
+
+---
+
+### 2. Reference Answer = 唯一正确答案
+
+只适用于部分确定性任务。
+
+---
+
+### 3. Code Grader = Ground Truth
+
+错误。
+
+代码可以稳定执行一个错误 oracle。
+
+---
+
+### 4. Judge 模型越强 = Judge 越可信
+
+错误。
+
+Judge 仍然需要 calibration。
+
+---
+
+### 5. IAA 高 = Eval 一定有效
+
+错误。
+
+所有评分者可以非常一致地测错东西。
+
+---
+
+### 6. 多次 Trial = 在测 grader 信度
+
+不一定。
+
+Trial 首先用于观察被测系统本身的行为随机性。
+
+---
+
+### 7. 用户只有一次机会，所以应该看 pass^k
+
+不准确。
+
+一次真实机会首先看：
+
+```text
+pass@1
+```
+
+`pass^k` 是更严格的连续成功指标。
+
+---
+
+### 8. Agent Eval 必须做到 Level 4
+
+错误。
+
+应该选择与真实任务成功条件最接近的观测层。
+
+---
+
+### 9. Eval Set 应该永久冻结
+
+错误。
+
+```text
+comparison version 要冻结
+suite 生命周期要维护
+```
+
+---
+
+### 10. Score 提高 = 系统一定提高
+
+不一定。
+
+还可能来自：
+
+```text
+sampling noise
+dataset change
+grader drift
+environment change
+eval overfitting
+```
+
+---
+
+## 二十七、用五个问题审查任何 Eval
+
+以后看到任何评测体系，先问：
+
+### 1. What are we trying to measure?
+
+```text
+真正的 construct 是什么？
+```
+
+### 2. What evidence represents it?
+
+```text
+哪些 cases / outcomes 能代表这个 construct？
+```
+
+### 3. What makes an answer correct?
+
+```text
+oracle / rubric / reference 是什么？
+```
+
+### 4. Can we trust the measurement?
+
+```text
+grader 稳定吗？
+和 human reference 对齐吗？
+样本量够吗？
+```
+
+### 5. What decision does the result support?
+
+```text
+选模型？
+上线？
+回滚？
+诊断？
+```
+
+如果这五个问题答不清楚：
+
+> **一个精确到小数点后三位的分数，也可能没有实际意义。**
+
+---
+
+## 二十八、最终概念图
+
+```text
+Product Requirement
+        ↓
+Construct
+        ↓
+Operationalization
+        ↓
+Success Criteria / Rubric
+        ↓
+Task / Eval Case
+        ↓
+Dataset / Suite
+        ↓
+System Under Test
+        ↓
+Run
+        ↓
+Trial
+        ├───────────────┐
+        ↓               ↓
+      Trace           Outcome
+        └───────┬───────┘
+                ↓
+              Grader
+                ↓
+        Score / Label / Metrics
+                ↓
+     Reliability + Validity Check
+                ↓
+       Statistical Analysis
+                ↓
+ Failure Taxonomy + Severity
+                ↓
+           Root Cause
+                ↓
+              Fix
+                ↓
+       Regression Suite
+                ↓
+      Production Monitoring
+                └────────→ New Cases
+```
+
+---
+
+## 二十九、术语速查
+
+| 概念对 | 核心区别 |
+|---|---|
+| Construct vs Operationalization | 想测的抽象属性 vs 把它变成可观察条件 |
+| Rubric vs Reference | 判定规则 vs 合格实例 |
+| Oracle vs Grader | 正确性的依据 vs 执行判断的机制 |
+| Task vs Case | 本文约定：抽象测试意图 vs 具体实例 |
+| Run vs Trial | 一次版本化评测执行 vs 某个 task/case 的一次尝试 |
+| Output vs Trace vs Outcome | 最终输出 vs 执行过程 vs 最终环境状态 |
+| Agent Harness vs Eval Harness | Agent 运行脚手架 vs 测试基础设施 |
+| System Variability vs Measurement Reliability | 被测系统自己波动 vs 测量工具是否稳定 |
+| Blind Review vs Calibration vs IAA | 降低偏差 vs 对齐/发现分歧 vs 量化一致性 |
+| Capability vs Regression | 探索能力边界 vs 防止已知能力回退 |
+| pass@1 vs pass@k vs pass^k | 单次成功 vs 多次至少一次成功 vs 多次全部成功 |
+| Benchmark vs Product Eval vs Monitoring | 标准化能力比较 vs 产品适配性 vs 生产真实表现 |
+| Failure Type vs Severity vs Root Cause | 发生什么 vs 多严重 vs 为什么发生 |
+
+---
+
+## 三十、自测
+
+1. Construct 与 operationalization 分别是什么？
+2. 为什么开放任务通常更依赖 rubric，而确定性任务可以直接使用 reference / state oracle？
+3. Oracle 和 grader 有什么区别？为什么 code grader 也可能稳定地判错？
+4. 被测系统的随机性与 measurement reliability 有什么区别？
+5. Reliability 高为什么不能证明 Validity 高？
+6. Content validity、construct validity、criterion-related validity 分别在问什么？
+7. Task、Case、Run、Trial 的层级关系是什么？哪些只是本文的本地术语约定？
+8. Output、Trace、Outcome 分别回答什么问题？
+9. 哪些 Agent 任务应该重点看 Outcome？哪些情况必须同时检查 Trace？
+10. 为什么“Agent Eval 必须 Level 4”是不准确的？
+11. Capability Eval 和 Regression Eval 为什么要分开？
+12. Eval Saturation 是什么？
+13. 为什么 positive / negative cases 应该成对设计？
+14. 为什么一次正式比较要冻结版本，而 Eval Suite 长期又必须维护？
+15. pass@1、pass@k、pass^k 分别回答什么问题？它们的简单公式依赖什么假设？
+16. 为什么 A=83%、B=84% 不能自动证明 B 更好？
+17. Blind review、Calibration、IAA、Adjudication 分别解决什么问题？
+18. Cohen's Kappa 为什么不能简单理解成“永远比 raw agreement 更好”？
+19. Failure Recall 和 False Negative Rate 是什么关系？
+20. 为什么 multi-judge consensus 不能代替 human calibration？
+21. Benchmark 高为什么不代表 Product Eval 高？
+22. Goodhart's Law 在 Eval 中真正提醒我们什么？
+23. Failure Taxonomy、Severity、Root Cause 各回答什么？
+24. 为什么 `eval_bug` 应该进入 failure taxonomy？
+25. 为什么一个好的 Eval 最终应该产生 Regression Case，而不只是一个 score？
+
+---
 
 ## 参考资料
 
-- [OpenAI, *Working with evals*](https://developers.openai.com/api/docs/guides/evals)
+### 官方与工程实践
+
 - [Anthropic, *Demystifying evals for AI agents*](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
-- 操作化定义、信度与效度为经典测量学（measurement theory / psychometrics）概念，本文将其与 LLM 评测实践对应。
+  - task / trial / grader / transcript / outcome / evaluation harness / agent harness
+  - capability vs regression eval
+  - pass@k / pass^k
+  - reference solution
+  - balanced problem sets
+  - eval saturation
+  - production monitoring
+
+- [OpenAI, *Introducing AgentKit*](https://openai.com/index/introducing-agentkit/)
+  - datasets
+  - trace grading
+  - evaluation workflows
+  - **时效说明：OpenAI 已于 2026-06-03 更新公告，表示 Agent Builder 与 Evals 产品将在 2026-11-30 后不再提供。本文只借用其中的评测对象与方法论，不依赖该产品长期存在。**
+
+### 测量学与 AI Measurement
+
+- [NIST CAISI, *Accelerating AI Innovation Through Measurement Science*](https://www.nist.gov/blogs/caisi-research-blog/accelerating-ai-innovation-through-measurement-science)
+  - construct validity
+  - uncertainty
+  - benchmark design
+  - generalization
+  - LLM-as-a-Judge validation
+
+- NIST AI Risk Management Framework / TEVV 相关资料
+  - validity
+  - reliability
+  - documentation
+  - operating context
+
+### LLM-as-a-Judge
+
+- Chehbouni et al., *Neither Valid nor Reliable? Investigating the Use of LLMs as Judges*, 2025
+  - 从 measurement theory 角度讨论 LLM Judge 的 validity 与 reliability 风险
+  - [arXiv:2508.18076](https://arxiv.org/abs/2508.18076)
+
+### Agent Evaluation Survey
+
+- Yehudai et al., *A Survey on Evaluation of LLM-based Agents*, Findings of ACL 2026（[arXiv:2503.16416](https://arxiv.org/abs/2503.16416)）
+  - IBM Research / Yale / Hebrew University
+  - Agent evaluation 的能力、应用 benchmark、generalist agent、benchmark dimensions 与 evaluation frameworks 综述
+
+### Agreement Statistics
+
+- Cohen's Kappa、Krippendorff's Alpha 等属于 inter-rater agreement 工具。
+- 使用 Kappa 时需要注意 prevalence / marginal distribution 导致的 kappa paradox（经典讨论见 Feinstein & Cicchetti, 1990）；因此应与 raw agreement、类别分布和具体 confusion pattern 一起解释。
+
+---
+
+> **最后只记一句话：**
+>
+> **LLM Evaluation 的本质，是把“希望 AI 做什么”转成可观测、可重复的测试，用经过验证的测量方法取得证据，再把证据转化为可解释的工程决策和永久的回归知识。**
 
 ---
 
diff --git a/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/README.md b/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/README.md
index e4c602b..fc568c9 100644
--- a/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/README.md
+++ b/01_Projects/Personal-Tech/LLM_Evaluation/00-Foundations/README.md
@@ -16,7 +16,7 @@ created: 2026-08-21
 1. [[01-What-Is-LLM-Evaluation|什么是 LLM Evaluation]]
 2. [[02-Annotation-Human-Data-and-Evaluation|数据标注、Human Data 与 Evaluation]]
 3. [[03-Core-Concept-Map|LLM Evaluation 核心概念地图]]
-4. [[04-Concepts-and-Theory|LLM 评测基础概念与理论：系统讲解]]（前三篇的教学整合，补全"为什么"与信度/效度视角）
+4. [[04-Concepts-and-Theory|LLM 评测基础概念与理论：系统讲解]]（前三篇的教学整合：构念→测量→决策主线、信度/效度、pass@k 与 pass^k、capability/regression eval、统计不确定性与失败分析等）
 
 完成这一层后，继续阅读：
 
diff --git a/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/00-project-overview.md b/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/00-project-overview.md
new file mode 100644
index 0000000..101ad1f
--- /dev/null
+++ b/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/00-project-overview.md
@@ -0,0 +1,56 @@
+---
+type: project
+status: active
+project_type: rag-eval
+created: 2026-08-24
+---
+
+# Go 官方文档约束下的技术问答
+
+## 问题与范围
+
+- 任务名称：公开文档约束下的技术问答（Go 模块发布流程）
+- 用户输入：一个问题 + 一段 Go 官方文档片段（release-workflow 页）
+- 系统输出：简短回答 + 文档引用位置
+
+## 一句话成功条件
+
+> 回答中的关键事实均可由给定文档片段支持；资料不足时明确说明
+
+## 三类失败
+
+1. 无依据事实：回答包含上下文未支持的关键事实
+2. 过度肯定：把文档没保证的说成保证
+3. 引用错误：声称引用了文档但实际无此表述
+
+## 非目标
+
+- 不评价文档外的 Go 常识正确性（如 semver、/v2 后缀）
+
+## 数据来源 / 许可
+
+- 来源：Go 官方文档 Module release and versioning workflow ／ URL：https://go.dev/doc/modules/release-workflow ／ 日期：2026-08-24
+- 许可：Go 文档（BSD 风格）／ PII 政策：N/A（公开技术文档，无个人数据）
+
+## 主要风险
+
+- 无依据补全（幻觉）、凭常识硬答、引用错位
+
+## 当前版本
+
+- dataset_version：v0.1 ／ rubric_version：v0.1 ／ 最近 run：无
+
+## 关键链接
+
+- 工作表：[[02-First-Week-Worksheet|首周工作表]]
+- 代码仓库：TBD（尚未创建，创建后填入 GitHub URL）
+- 数据集：`datasets/eval-v0.1.jsonl`
+- 最近报告：`reports/report-v0.1.md`
+
+## 下一步最小动作
+
+- [ ] 填写 `01-task-and-rubric.md` 的 rubric 三维度（对应 [[02-First-Week-Worksheet]] 第 1 节）
+
+---
+
+返回 [[01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/README|项目实践入口]]。
diff --git a/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/01-task-and-rubric.md b/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/01-task-and-rubric.md
new file mode 100644
index 0000000..b6b3a3c
--- /dev/null
+++ b/01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/01-go-docs-qa/01-task-and-rubric.md
@@ -0,0 +1,49 @@
+---
+type: project
+status: active
+---
+
+# 01 · 任务与 Rubric
+
+> 权威版本：rubric 三维度的完整定义见 [[01-LLM-Evaluation-Roadmap]] 第六节；为什么这样设计见 [[02-Why-Guide]] 第 3 步。本文件只记录本项目的填写结果。
+
+## 任务边界（对应工作表第 0 节）
+
+| 项目        | 你的填写                                                                                                       |
+| --------- | ---------------------------------------------------------------------------------------------------------- |
+| 任务名称      | 公开文档约束下的技术问答（Go 模块发布流程）                                                                                    |
+| 用户输入      | 一个问题 + 上面这段 Common workflow steps 文档片段                                                                     |
+| 系统输出      | 简短回答 + 文档引用位置                                                                                              |
+| 一句话成功条件   | 回答中的关键事实均可由给定文档片段支持；资料不足时明确说明                                                                              |
+| 三类失败      | 无依据事实；过度肯定；引用错误                                                                                            |
+| 非目标       | 不评价文档外的 Go 常识（semver、/v2 后缀、go get 细节等）                                                                    |
+| 数据来源 / 许可 | 来源 Go 官方文档 release-workflow 页；URL https://go.dev/doc/modules/release-workflow；日期 2026-08-24；BSD 风格；PII：N/A |
+
+## Rubric v0.1（对应工作表第 1 节）
+
+| 维度                | 通过条件                                                    | 失败条件                  | 正例                                                                                                                                  | 反例                                                        |
+| ----------------- | ------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| 有据性（pass/fail）    | 每条可核验事实都能在给定片段里找到依据                                     | 出现至少一个片段不支持的事实        | 模型说"未发布的模块无法用 go get 走常规流程"——片段里 "it's unavailable for the typical dependency management workflow using commands such as go get" 支持 | 模型说"发 alpha 前必须先用 go test 跑一遍"——片段没有说"必须 go test"，属于无依据补全 |
+| 资料不足处理（pass/fail） | 片段没讲的事，模型明确说"文档未说明"，不瞎猜                                 | 把未知当确定                | 被问"beta 阶段具体要测什么"，模型答"此片段未说明具体测试项"                                                                                                  | 被问"发布正式 v1 的流程"（片段只讲到 v0 预发布），模型却编造 v1 发布步骤——片段根本没提 v1    |
+| 核心任务完成度（0/1/2）    | 覆盖用户问题必须回答的全部要点（顺序 + 关键限制），给 2 分；覆盖大部分但漏 1 个非关键点，给 1 分。 | 答非所问、漏掉关键限制或约束，给 0 分。 | 先组织好模块源码；发布前模块无法用 go get 走常规流程，可先在本地目录测试；代码就绪后开始发布 v0 预发布版（alpha/beta）。                                                             | 准备好代码后，用 go get 发布模块即可。                                   |
+
+> 0/1/2 评分定义见 [[01-LLM-Evaluation-Roadmap]] 第六节；第一版不要增加维度。
+
+### 一票否决项
+
+- 出现任何无证据事实 → 整体 fail，无论其他维度（这是最需要保护的行为边界）。
+
+### 无法判断时的升级路径
+
+- 两个片段对同一说法冲突 → 标记 low confidence，人工仲裁，不自动评分。你的项目目前单片段，可写：片段未覆盖该问题 → 若模型正确拒答则不扣分，若无法判定则人工复核。
+
+### Rubric 修改记录
+
+| 版本   | 日期         | 改了什么 | 为什么改 | 预期影响   | 实际结果 |
+| ---- | ---------- | ---- | ---- | ------ | ---- |
+| v0.1 | 2026-08-24 | 初版   | 首版   | rubric |      |
+|      |            |      |      |        |      |
+
+---
+
+返回 [[01_Projects/Personal-Tech/LLM_Evaluation/03-Practice/README|项目实践入口]]。
diff --git a/01_Projects/Personal-Tech/LLM_Evaluation/99-Attachments/.gitkeep b/01_Projects/Personal-Tech/LLM_Evaluation/99-Attachments/.gitkeep
deleted file mode 100644
index 9f9f912..0000000
--- a/01_Projects/Personal-Tech/LLM_Evaluation/99-Attachments/.gitkeep
+++ /dev/null
@@ -1 +0,0 @@
-# 本目录用于存放外部 PDF、截图、数据文件等二进制附件；也可统一使用全库 05_Attachments。