fable-eval

Fable Eval

衡量 Agent 控制变更是否改善了其宣称要改善的行为，同时避免悄悄过拟合基准或破坏相邻行为。

使命

评估是一种决策工具，而不是排行榜。它需要固定的比较基准、具有代表性的语义类别、隔离的判定依据、明确的失败代价，以及回滚决策。

候选方案不应仅仅因为提示词与其指令相似、留出集泄漏到编写过程中，或某个平均分掩盖了严重回归而胜出。

适用场景

• 更改 Skills、提示词、路由器、钩子、Agent 配置、策略或模型控制逻辑时；
• 比较候选提示词／Agent 配置时；
• 衡量触发精确率／召回率或操作遵循度时；
• 验证新的行为成熟度声明时；
• 调查表面上的改进是否稳健，还是仅适用于特定基准时。

不适用场景

• 验证常规应用行为（fable-verify）；
• 在预期行为尚不明确时编写 Skill（skill-creator）；
• 运行没有验收决策的一次性主观提示词演示。

评估分类

变更	主要评估风险
路由器／触发器	误报、漏报、优先级
Skill 指令	操作正确性、违规捷径、边界行为
Spark／下一步操作	Top-1 操作、不安全建议、沉默精确率
钩子／防护	强制执行、错误拦截、绕过
提示词／角色设定	任务质量 + 回归 + 指令冲突
工具策略	工具选择正确性、不安全／遗漏操作
模型／配置	代表性任务中的质量／延迟／成本差异

流程

阶段 1 — 运行测试前先定义决策

说明：

• 正在评估的候选方案；
• 基准／对照组；
• 预期改善的具体行为；
• 指标和阈值；
• 不可接受的回归；
• 回滚操作。

避免在看到结果后才发明指标。

阶段 2 — 构建语义场景类别

覆盖不同的决策，而不是措辞变体。视情况纳入：

• 简单的正例；
• 不触发／边界案例；
• 存在竞争操作的模糊情况；
• 诱导走捷径的对抗性压力；
• 不完整／矛盾的证据；
• 失败／恢复路径；
• 旧版／受限环境；
• 未见过的留出案例。

单独记录类别覆盖情况，不要只记录提示词数量。

阶段 3 — 固定基准和语料库标识

将本次运行绑定到：

• 语料库哈希／版本；
• 候选方案／基准标识；
• 评估器／评分器版本；
• 提供方／模型／配置（如涉及外部服务）；
• 时间戳／仓库修订版本。

除非经过明确的标准化处理，否则更改评估对象、判定依据、语料库或评分逻辑都会使直接比较失效。

阶段 4 — 保护判定依据

面向提供方的请求不得泄露预期操作、禁止操作、类别标签、留出集标识、评分实现或包含答案的元数据。

不要反复阅读留出集的失败案例来编写候选方案。将发现的案例纳入后续的检查语料库，并保留一份新的未见留出集。

阶段 5 — 一致地执行基准和候选方案

在比较要求的范围内，使用相同的任务输入、工具可用性、上下文预算、温度／配置、超时策略和评分规则。

将提供方错误／超时记录为失败或明确的不可用状态；不要用判定依据填补缺失的输出。

阶段 6 — 按切片评分，而非只看平均值

检查：

• 总体指标；
• 每个语义类别；
• 负向／对抗案例中的违规情况；
• 高代价回归；
• 在随机性影响较大时的方差／重复运行稳定性；
• 适用时的路由混淆对。

如果平均分提升 1%，却引入了严重的发布／安全／恢复回归，这种提升就不可接受。

第 7 阶段 — 调查可疑的增益

检查以下事项：

• 提示词泄漏；
• 重复或近乎重复的场景；
• 针对基准测试的关键词匹配；
• 工具／上下文预算变更；
• 评分器偏移；
• 挑选种子／运行结果；
• 候选版本中复制了示例。

第 8 阶段 — 作出决定并保留回滚方案

结论：

• 接受：达到阈值，没有违规回退，证据具有代表性且足够新；
• 拒绝：候选版本导致必要行为回退或未达到阈值；
• 无法确定：证据缺乏广度、稳定性或留出数据完整性。

记录基线产物，确保仍可回滚。

决策规则

• 语义类别的覆盖广度比场景总数更重要。
• 对同一案例进行表面改写，不会形成独立覆盖。
• 留出数据一旦被反复用于调优候选版本，就不再是留出数据。
• 先比较各细分项，再看平均值；安全关键的违规行为可以否决更高的平均分。
• 如果随机波动可能改变决策，应重复运行足够次数以评估稳定性，而不是挑选一个种子。
• 如果候选版本与基线之间的提供方／运行时错误不同，应将基础设施故障与行为分数区分开。
• 如果经过评估的 Skill／语料库／判定标准发生变化，除非新鲜度验证证明其身份未变，否则绝不能沿用旧的成熟度结果。
• 候选版本未通过后，绝不能为了发布而降低阈值。

不变量

• 在评判候选版本之前，基线必须可复现且已冻结。
• 判定标准／留出数据必须对受评估的 Agent 保持隐藏。
• 在声称条件等效的情况下，候选版本与基线必须在等效条件下进行比较。
• 绝不能用预期答案替代缺失或失败的提供方输出。
• 每项接受决定都必须有回滚路径。
• 即使总体分数有所提升，高成本回退仍必须清晰可见。

失败类型

基准测试过拟合

候选版本在已检查的案例上有所改进，但在未见过的类别／留出数据上失败。应扩大语义覆盖范围，并拒绝该候选版本，或对其进行泛化。

判定标准泄漏

预期／禁止／类别数据进入提供方／候选版本的编写循环。丢弃受污染的证据，并创建新的盲测案例。

指标盲区

平均分有所提升，但重要细分项有所恶化。使用按类别划分的指标和否决指标。

运行不可比

模型／工具／上下文／评分器设置不同，导致增益看似成立。应在受控条件下重新运行。

高方差

重复运行导致结论变化。增加样本量／控制非确定性，或标记为无法确定。

语料库漂移

采集证据后，Skill／场景／判定标准发生变化。将证据标记为过时并重新运行。

反模式

• 将 5 个改写版本算作 5 个独立测试；
• 在调优每个候选版本时都查看留出数据；
• 仅凭平均分就接受；
• 看到失败后再更改阈值；
• 将提供方超时视为跳过，而不是失败／未完成；
• 只评估正向示例；
• 复制预期操作的词汇，导致每个案例泄露答案；
• 仅因存在证据 JSON 文件就声称达到 M4，尽管语料库哈希已更改。

评估报告

Candidate / baseline:
Corpus + hashes:
Provider/config:
Semantic families:
Metrics + thresholds:
Per-family results:
Forbidden/high-cost regressions:
Variance/repeats:
Leakage/comparability checks:
Verdict: ACCEPT | REJECT | INCONCLUSIVE
Rollback:
Evidence freshness:

完成标准

满足以下条件时，评估即告完成：

• 明确标识基线与候选版本；
• 语义覆盖范围和盲测留出数据的完整性可信；
• 按有意义的细分项检查指标；
• 回退／禁止操作没有被平均分掩盖；
• 结论和回滚方案均有证据支持；
• 证据的新鲜度与确切的受评估语料库／控制条件关联。

渐进式资源

• 深入指南：references/benchmark-design-and-overfit-control.md
• 现有协议：references/eval-harness-protocol.md
• 示例：examples/eval-regression-run.md