# Agent Quality Evaluation

> 智能体做出来之后，怎么证明它够好、改动之后有没有退步——建黄金测试集 + pytest + 基线报告的方法论。 适用场景：AI 智能体已经能跑了，需要建立可重复、可自动化的验收标准；或者改了 prompt/守卫后想知道有没有改坏。 触发关键词：质量评估、黄金测试集、评测集、基线报告、pass率、SMART标准、防退步、回归测试、这个智能体好不好。 不适用：项目还没开工、判断值不值得做（那是 data-readiness-assessment 技能管的前置阶段）。

- Skill: `oopsoops618/agent-quality-evaluation` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add oopsoops618/agent-quality-evaluation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oopsoops618/agent-quality-evaluation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oopsoops618 (https://skillmd.com/u/oopsoops618)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oopsoops618/agent-quality-evaluation

---


# 质量评估方法论 — 做出来的东西好不好、准不准

## 开跑准入检查（缺项立即停）

**硬门槛**（缺了跑不了/跑了也白跑）：
- [ ] 评估集非空且合法：有用例、id 不重复、格式合法
- [ ] 被测对象装配得起来：能正常实例化/调用，import 不了就停
- [ ] 运行环境齐：API key、依赖都在，缺了 NLU/判定全降级，基线不可信
- [ ] 金标别全是自己编的：每条期望有来源等级（业务确认 > 数据反推 > 自己编），全自编 → 停，先拿真实数据锚定

**软风险**（能跑，但报告要标注、别当铁结论）：金标未经业务确认、覆盖度不足、只跑单次没纳入随机性。

## 两种数据集

| | 开发集 | 黄金测试集 |
|---|---|---|
| 数量 | 10-20 条 | 40-90+ 条 |
| 用途 | 改 prompt/守卫时快速验证 | 最终验收，衡量真实水平 |
| 能不能看着它改代码 | 能，就是拿来调的 | **不能**，看着答案改就失去考试意义 |

**核心纪律**：改 prompt 只看开发集结果，改完跑黄金集。黄金集不通过，不要针对黄金集具体用例改代码——回开发集加类似用例，调好了再跑黄金集。

## 黄金数据集构建五原则

1. **覆盖性优先于数量**——不是越多越好，是覆盖维度矩阵里"有区分度"的组合点（这个case过了/挂了，能精确定位问题在哪）
2. **测边界，不测正常**——正常case容易过，真正有价值的是相邻类别的边界（关键词歧义、相邻意图、情绪误判、多意图交叉）。AI生成用例倾向于"典型"数据，边界case需要人来设计
3. **期望必须可判定**——不能是"回复应该合理"，必须能写成断言（含XX、不出现XX），可判定才能自动化验证
4. **数据来源三层**（重要性递减）：真实数据筛选（60-70%，最真实）> 人工构造（20-30%，补边界）> AI辅助扩展（可选，扩量用）
5. **评估分规则判和语义判**——规则判（字符串/正则，高可靠性）优先做好，语义判（LLM Judge，中等可靠性）是锦上添花

## 评估方式优先级

| 优先级 | 方式 | 适用 | 可靠性 |
|---|---|---|---|
| 1 代码判 | 字符串匹配/正则/JSON Schema/流程断言 | 有明确对错标准的 | 最高 |
| 2 LLM判 | 另一个LLM按Rubric打分 | 回复质量/语气/自然度 | 中等 |
| 3 人工判 | 人看回复打分 | 复杂主观评估、争议case | 最高但最慢 |

**LLM Judge 最佳实践**：写详细评分标准（每个分数对应什么）、输出数字不输出文字、先思考再打分、用不同模型当裁判避免自己判自己、能用二元判断就别用连续评分。详见 `references/methodology.md`。

## SMART 标准 + 八维评估

上线前先定义 3-5 条 SMART 标准（Specific/Measurable/Achievable/Relevant/Time-bound），标准驱动数据集设计，不是反过来。八维评估体系（任务保真度/一致性/相关性/语气风格/隐私保护/上下文利用/延迟/成本）详见 `references/methodology.md`。

**现阶段重点**：任务保真度、相关性与连贯、隐私保护、上下文利用（可规则判的4个维度）；一致性/语气风格/延迟后续加入；成本视场景决定要不要考核。

## 迭代路径

```
第一阶段：规则判 100% → 建立可自动化、可重复的基线
第二阶段（规则判跑通后）：规则判 + LLM Judge → 覆盖"好不好"
第三阶段（线上后）：+ 线上监控 → 从实验室成绩过渡到真实战场表现
```

上一阶段通过率稳定在 85% 以上才进入下一阶段，不要规则判还没跑通就急着加 LLM Judge。

## 复用到其他智能体：统一抽象

一切智能体评估都归到同一个原子结构：**输入 → 智能体输出 → 期望断言集**。区别只在输入形态（对话的turns / 批处理的document）和断言类型（文本判：含/不含关键词、意图正确 / 集合判：期望集合 vs 实际集合 → 命中/漏报/误报三态）。

换场景要替换的三样东西：**维度矩阵**（这个场景的意图×情绪×通道×边界该怎么列）、**断言规则**（文本判/集合判/数值判/流程判）、**黄金数据来源**（真实历史数据在哪）。加载→执行→断言→报告的框架不用重新设计，选断言类型、换三样东西即可。

从批处理型实例反向吸收的三个通用机制：
1. **known limitation 台账**——用例标记"已知局限"不算失败、不掩盖，持续跟踪
2. **基准样本制**——每个智能体钉一个基准样本，任何质量改动必回跑，成绩写在看板上
3. **对照评估**——同一输入喂竞品打分，三用途：回归防退步、验收定达标、对照出卖点

案例数字（某客服场景基线报告脱敏摘要）见 `references/case-baseline.md`；业界工具对标（DeepEval/OpenAI Evals/τ-bench/promptfoo/Ragas 各吸收了什么、什么时候引入）见 `references/industry-benchmark.md`。

## 用这个技能时该做什么

被邀请做质量评估时：
1. 先过开跑准入检查
2. 定 3-5 条 SMART 标准
3. 按五原则建黄金集+开发集（真实数据优先，AI生成的边界case要人审）
4. 规则判先跑通，再考虑加 LLM Judge
5. 出基线报告，含分维度/失败明细，作为"当前成绩单"，后续改动回跑对比