L001：先认识 Eval，再为 course-builder 写一份最小 Contract
目标：理解 Eval 的基本组成及其与 Demo、测试、Benchmark 和监控的区别，并能写出一份最小 Evaluation Contract。
为什么这一课是下一步
你已经有丰富的 LLM 产品、Pi 插件和 Skill 开发经验，但“会构建”不自动等于“会系统评测”。原版本直接让你写 Evaluation Contract，跳过了 Eval 的背景、结构和示例。修订后的这一课先建立共同语言，再让你完成一个更小的练习。
0–6 分钟：什么是 Eval
在这门课里，Eval 是一套可重复的测量过程，用来判断一个 LLM 系统在一组有代表性的任务上表现如何，并支持一个具体决策。
一套最小 Eval 通常包含六部分：
- Decision：结果要支持什么决定，例如是否采用新版 prompt。
- Cases：系统要面对哪些输入和情境。
- Target：被评测的 prompt、Skill、Agent 或完整工作流。
- Outputs / traces：系统最终输出了什么，过程中做了什么。
- Graders：如何判断每个输出是否满足标准。
- Report：如何汇总结果、不确定性、失败样例和成本，并作出决定。
OpenAI 的 Eval 工作流把测试数据与 testing criteria，也就是 graders，连接起来。[S01] 对会调用工具的 Agent 或 Skill，仅看最终文本可能不够，还需要区分 task、trial、trajectory、outcome 和 harness。[S03]
可以把它写成：
Eval = 明确决策 + 代表性 cases + 可观察输出 + 合适 graders + 可解释报告
Eval 不等于什么
- 不是 Demo：Demo 证明系统有一次能工作，Eval 测量它在一组条件下多大程度上可靠。
- 不只是单元测试：确定性测试可以成为 grader，但开放式质量通常还需要 rubric、模型判断或人工判断。
- 不只是 Benchmark：Benchmark 通常用于标准化比较；你的 Eval 应围绕自己的用户、风险和产品决策设计。
- 不只是线上监控：监控告诉你线上发生了什么；Eval 还可以在发布前比较候选版本并阻止回归。
6–11 分钟：为什么 LLM 系统特别需要 Eval
传统代码在相同输入和环境下通常得到稳定结果，而 LLM 系统可能受到模型采样、上下文、工具环境、prompt 细节和模型版本影响。
更重要的是，“质量”不是一个单一维度。一个回答可以语言流畅，却引用错误政策；一个 Skill 可以生成漂亮课程，却错误地把“看过”当作“掌握”。如果把安全、正确性、成本和延迟压成一个平均分，严重失败可能被大量普通 case 掩盖。[S07]
Eval 主要解决四类问题：
- 发布前比较：新版是否真的优于当前版？
- 防止回归：修复一种失败时，是否破坏了原本正常的行为？
- 定位问题：失败来自 cases、target、grader、harness，还是系统本身？
- 积累证据：团队为什么保留、修改或回滚一个版本？
一个 Eval 不需要从几千条 case 开始。第一轮可以很小，但 case 必须与真实决策和失败模式相连。
11–18 分钟：例子一，评测 System Prompt
假设有一个 LLM，需要把客服消息转换成 JSON：
{
"category": "refund | delivery | account | other",
"urgency": "low | medium | high",
"summary": "一句话摘要"
}
候选改动是给 system prompt 增加更详细的退款和紧急程度规则。我们要决定是否从 prompt-v1 切换到 prompt-v2。
Cases
至少包含：
- 明确的退款请求；
- 信息不完整的配送问题；
- 同时涉及账户和退款的冲突请求；
- 带有 prompt injection 的用户消息；
- 不属于任何已知类别的请求。
Graders
可以组合使用：
- JSON 是否可以解析；
- 字段是否完整，枚举值是否合法；
- 已有人类标签时，category 是否匹配；
- summary 是否忠实于原消息；
- 是否错误服从用户消息中的 system prompt 覆盖指令。
决策
不能只问“平均准确率是否提高”。还要检查：
prompt-v2是否减少重要退款误判；- 是否产生新的 injection 回归；
- 输出 token 和延迟是否明显增加；
- 提升是否足以抵消成本和风险。
这个例子中，JSON 检查和 enum 检查适合确定性 grader；摘要忠实度可能需要 rubric、模型 grader 或人工校准。Eval 的关键不是尽量使用复杂 grader，而是为每项标准选择足够可靠且主观性最低的方法。[S01]
18–25 分钟：例子二，评测 Pi Skill
Pi 会根据 Skill 的名称和 description 发现能力，在任务匹配时加载 SKILL.md，也可以通过 Skill command 显式调用。[S08] 因此 Skill Eval 至少有两个不同层面。
层面一，是否正确触发
以 course-builder 为例：
应该触发：
“帮我创建一门持续八周的 LLM Eval 课程。”
“继续上次课程的下一课。”
不应该触发：
“Eval 这个英文单词是什么意思？”
“把这段 release note 改得更自然。”
这里可以测量：
- 应触发 case 中成功触发的比例；
- 不应触发 case 中避免误触发的比例；
- 修改 description 后出现了哪些新增错误。
层面二，触发后是否做对
即使 Skill 正确触发，也可能违反行为约束。例如：
- 没有先创建完整路线；
- 只生成第一课，导致静态部署缺少后续 Lesson；
- 没有证据就提升知识状态；
- 对时间敏感的内容没有检查主要来源；
- 修改了 Skill 自身，而不是课程状态。
这些标准中，有些可以通过 Python 检查文件和 JSON 状态，有些需要查看最终课程是否真正符合学习目标。对会使用工具的 Skill，还需要关注它执行了哪些操作以及最终产物是否正确。[S03]
一个可能的评测决策
是否修改 course-builder 的 description，
让“持续学习 / 创建课程”请求更稳定地触发，
同时不增加一次性事实问答的误触发？
这比“新版 description 感觉更清楚”更适合 Eval，因为它明确了候选改动、正向行为、负向行为和最终决策。
25–28 分钟：快速理解检查
请先不回看上文，回答三个问题。每题完成后再展开参考答案，不要先看答案再作答。
问题 1
为什么一次成功 Demo 不能证明系统可靠？
完成后查看参考答案
Demo 只能说明系统在某一次输入、环境和随机结果下成功。它没有覆盖代表性 cases，也没有使用一致标准重复测量，因此不能估计系统在正常、边界和失败条件下的可靠程度。
问题 2
Cases 和 Graders 分别解决什么问题？
完成后查看参考答案
Cases 定义这次 Eval 抽样覆盖哪些输入和情境。Graders 根据明确标准判断每个输出是否满足要求，可以给出标签、分数或解释。Cases 不能保证覆盖所有情形，Graders 也不能弥补缺失的重要 case。
问题 3
如果新版总体分数更高，但出现一次“无证据提升学习状态”，是否应该直接采用？为什么？
完成后查看参考答案
不应该直接采用。总体分数提高是正向证据，但“无证据提升学习状态”违反不可妥协约束。严重回归不能被大量普通 case 的平均分抵消，应先修复、重新评测，再决定采用、修改或回滚。
这三题用于判断概念解释是否清楚，不要求使用标准术语。
通过标准
- 能解释 Eval 与一次 Demo 的差异。
- 能区分 Cases、Target、Outputs 和 Graders 的作用。
- 最小 Contract 对应一个真实的
keep / revise / rollback决策。 - 至少给出两个正向触发和两个负向触发输入。
- 三个失败模式具体、可观察，并能说明影响。
- 不可妥协约束不会被平均分抵消。
- 不确定信息被明确保留给后续课程，而不是伪装成事实。