agent-evaluation

name	agent-evaluation
description	当你要判断 Agent 变好还是变坏、选择模型、决定是否上线某项改动时使用；当需要区分"模型能力不足"还是"Harness 设计缺陷"、或需要构建回归测试和评估数据集时使用。不适用于评估环境的代码实现细节（那是工程任务），聚焦于评估方法与决策。

Agent 评估（Agent Evaluation）

子 Skill 索引（渐进式披露：目录常驻，正文按需加载）

子 Skill	目录	何时深入加载
评估指标体系	eval-metrics	定义"什么算成功"、选 Pass@k/Pass^k、过程指标与安全指标
评估数据集设计	eval-dataset	搭评估环境、设计任务、防泄漏、可验证性
自动化评估方法	eval-llm-judge	Rubric 四准则、失败归因、配对比较、统计显著性

角色与读者

面向 Agent 开发者与决策者。本 Skill 服务的目标：把 Agent 的迭代从"经验判断"变成"可比较、可复现的工程过程"。核心认识：评估的对象是模型 + Harness 的组合体，而不是模型本身。评估的首要价值不是给当前系统打分，而是让你能快速可靠地跟上模型演进。

核心原则（配正例/反例）

1. 先分清指标口径：Pass@k（能力上限）vs Pass^k（业务可靠性）

   • Pass@k = 跑 k 次至少成功一次（适合科研发现、漏洞挖掘、开放式创作）；Pass^k = 连续 k 次每次都成功（适合支付、退款、生产部署）。
   • 例：单次成功率 0.6、k=5 时，Pass@5≈99%（看似"几乎总能成功一次"），但 Pass consecutive@5≈7.8%（连续五次不出错仍很难）。
   • 报告必须写清 k 次尝试口径（独立采样 vs 连续 k 个任务）。

2. 区分瓶颈在模型还是在 Harness：用模型替换实验（model swap）

   • 固定 Harness 只换模型：换强模型分数不涨 → 瓶颈在 Harness；分数随模型大幅波动 → 瓶颈在模型能力。
   • 与消融实验区分：消融是关闭 Harness 某组件看变化（定位 Harness 内部哪个部件重要）；模型替换是固定 Harness 只换模型（区分瓶颈在哪层）。

3. Rubric 四准则（LLM-as-a-Judge 的依据）

   • ① 基于专家指导（反映领域知识）；② 全面覆盖（含陷阱 Pitfall）；③ 按重要性加权（必要/重要/可选/陷阱，支持一票否决 Veto）；④ 评价标准自包含（可验证，避免"展示了深刻理解"这种抽象描述）。
   • 幻觉、安全违规、数据外泄必须设为一票否决项——它与其他质量维度正交。

4. 失败归因：定位首个错误，而非最后一个报错

   • 后续错误往往是连锁反应。归因记录结构化（错误类别、首个错误步骤、对应工具调用/输出、证据），区分根因与后果。
   • 例：edit_file 连续三次失败是后果（同一根因），不是三个独立根因。

5. 统计显著性：配对分析 + 分差超噪声 + 能复现

   • 标准误 SE≈√(p(1-p)/n)。100 用例 70% 成功率，95% 置信区间约 ±9 个百分点——"73% vs 70%"不足以支持切换。
   • 优先配对分析（逐题记录谁胜出，McNemar/配对 bootstrap），而非直接相减独立成功率；每配置多个随机种子。

执行流程（SOP 检查清单）

1. 定义"什么算成功"：选对指标口径（Pass@1/Pass@k/Pass^k/Best@k），建立多维 Rubric + 一票否决项。
2. 搭评估环境（工具调用型 Verifiers / 人机交互型 τ-bench 用户模拟）。
3. 设计数据集（明确性 vs 开放性、真实 vs 可控、防泄漏）。
4. 跑评估 + LLM-as-a-Judge 打分（多源异构评判防古德哈特定律）。
5. 失败归因 → 生成回归任务（端到端 + 轨迹前缀边界）。
6. 决策：分差超噪声、配对成立、能复现才切换/发布。

禁止清单（写清合法例外）

• 禁止只看最终结果不看过程（轨迹 trajectory 与结果 outcome 双重覆盖）。例外：结果可自动验证的简单任务可只验结果，但仍需过程指标防 reward hacking。
• 禁止把评估集与训练数据混用（红线，只能复用环境构造机制）。例外：参数化动态生成（τ²-bench、AndroidWorld）可缓解泄漏。
• 禁止"73% vs 70%"就切换模型（在噪声带宽内）。例外：扩大样本（标准误按 1/√n 缩小）后分差仍显著。
• 禁止用同源模型评判（Agent 用 Claude，评判就用 GPT-5+Gemini）。例外：部署阶段可单一模型快速评估，定期用完整多源评判质量审计。
• 禁止看到分数下降就改 Agent 代码（先检查评测系统本身：资源不足/评分器 bug/测试用例与生产脱节）。例外：审查完整轨迹确认是 Agent 问题后再动。

参考资料

• 本书第 7 章《Agent 的评估》（评估指标、评估环境、数据集设计、LLM-as-a-Judge、失败归因、统计显著性、可观测性）。
• 笔记 07-Agent的评估.md。
• Scale AI "Rubrics as Rewards"（Rubric 四准则）。