eval-harness-first

评估框架优先

整个插件的 Phase 0 关口： finetuning-method-selection 及所有下游 技能都假定在编写训练配置之前，该框架已经存在。 该框架不是运行结束时的 附属产物——它是数据整理引擎。用于构建 goldens 的同一批带标注轨迹也提供训练数据， 只是要减去一个显式的留出集。

输入： 生产/Agent 轨迹（如果存在），或者 任务规格（如果不存在），再加上愿意标注 ≥100 个样本的标注人员。 输出格式： 下面的 eval/ 目录—— goldens、评分器、漂移测试套件，以及后续阶段 用于把关的基座模型基线。

关口

没有评估框架，就没有微调。直接跳到训练 配置，就没有任何可供衡量的基准， 无法捕获回归，也没有带标注的数据 可供训练。飞轮：

1. 收集轨迹——生产/Agent span，或者 如果尚不存在，则使用合成任务。
2. 错误分析——对 ≥100 条轨迹进行开放式编码， 再通过轴心编码归纳为 4–8 个失败分桶。
3. 每个分桶一个评分器——优先使用确定性方法； 仅对真正主观的标准使用经过校准的 LLM 评审。
4. 按频率 × 严重程度 × 价值排序优先级。
5. 带标注的轨迹为数据集整理提供数据，减去 一个显式的留出集。 每个 eval/goldens.jsonl ID 都按 ID 排除在训练数据之外。
6. 训练。
7. 在检查点上重新运行同一套框架—— 而不是另一套更宽松的框架。
8. 漂移检测反馈到第 2 步——新的 生产失败模式会重新开启错误分析。

第 2–4 步构建框架；第 5–8 步说明为什么 它必须首先存在——它既是训练数据 来源，也是检查点的出口关口。

构建 Goldens

• 有轨迹时，从轨迹构建： 运行错误 分析——对 ≥100 条真实轨迹进行开放式编码（阅读 它们，用自己的话标记失败，暂时不使用固定 分类法），然后通过轴心编码将这些 标签归纳为 4–8 个命名的失败分桶。少于 4 个 意味着编码过程过于粗略；多于 8 个 意味着分桶需要合并。例外： 单一失败面的任务（例如严格的 schema 抽取）可能落在 1–2 个分桶，并在一个评分器内使用逐字段 子指标——不要在没有证据的情况下 人为拆分。
• 尚无轨迹时，使用合成数据： 基于 维度的生成——枚举重要 轴（任务类型、难度、边缘情况、 人物设定），并对叉积进行采样；自由 生成的提示词会聚集在最容易编写的 内容附近。
• Goldens 像代码一样进行版本控制——提交 eval/goldens.jsonl，在评审中对其进行 diff，按 发布打标签。它同时充当 CI 回归测试套件。

评分器

错误分析得出的每个失败分桶对应一个评分器—— 而不是整个评估集共用一个。单一的混合 分数会掩盖哪个分桶出现了回归。

• 优先使用确定性方法。 正则、schema 校验 或执行检查更便宜、可复现，而且 无需校准。
• 仅对真正主观的标准使用 LLM 评审—— 语气、忠实度、“哪个回答 更好”——这些没有确定性检查能够 表达。
• 使用二元通过/失败而非 Likert 量表。 1–5 或 1–10 量表校准起来噪声更大，也更难一致地 应用；应折叠为通过/失败。
• 漂移测试套件的 MMLU 风格评分：优先使用 logprob 而非生成后抽取——紧张的 token 预算 会让生成后抽取对带有前置说明的模型 解析脆弱，将格式合规性与 所测知识混为一谈。全部 四种评分器形态的模板以及这条评分说明： references/grader-templates.md。

评判器校准是前提条件

任何路由到 LLM 评判器的分桶，在其判定结果能用于 探索之外的任何用途之前，都需要校准——这是硬性前提， 而非锦上添花。当没有任何分桶路由到评判器时为 N/A——全确定性的测试框架没有任何需要校准的 东西；应明确说明这一点，而不是对本节避而不谈。

• 标注 ≥100 个条目，划分为 train/dev/sealed test（只报告一次，之后不再改动）。
• 报告 TPR 和 TNR，而不是一个混合的准确率 数字——在偏斜的数据集上，评判器只要一直说 “通过”就能达到 90%。
• 将评判器固定到某个固定的模型快照，并在评判器 模型变更时重新校准，无论如何每季度一次。
• 评判器必须来自与被测模型不同的模型家族。
• 未达到约定 TPR/TNR 门槛的评判器只能以 仅建议模式发布——仅供人工审查标记，绝不作为 晋升的门禁。完整协议、偏差校正和重新校准清单： references/judge-calibration.md。

基线

在阶段 1（方法选择）开始之前，针对未经修改的基础 模型运行完整测试框架——goldens 加上能力漂移 套件。这是后续每个检查点都要与之比较的数字。

eval/baseline-<model>.json 是门禁令牌。没有基线 文件，checkpoint-promotion 就没有比较基准—— 一个相对于“未测量任何东西”而“看起来更好”的 检查点算不上发现。

目录约定

eval/
├── goldens.jsonl          # labeled traces + synthetic goldens, versioned
├── graders/                # one module per failure bucket
│   ├── schema_compliance.py
│   ├── exact_match.py
│   └── rubric_judge.py
├── drift-suite.yaml        # frozen benchmarks + 200-500 domain-adjacent items
└── baseline-<model>.json   # gate token: harness + drift suite vs the base model
runs/
└── <run-id>/
    └── results.json         # per-run harness output, one per checkpoint

eval/ 跨运行持久存在，且位于 runs/ 之外—— 它是固定的量尺，而非运行产物。runs/ 是可丢弃的； eval/ 不是。绝不要让运行脚本写入 eval/。规范 位置： 每个逐 trace 的 results.json——包括阶段 0 基线——都位于 runs/<run-id>/results.json，绝不 位于 eval/runs/... 之下；要求后者的指令是错误的， 而不是本约定。

阶段 0 退出清单

在 finetuning-method-selection 之前，确认：

1. ≥100 个 trace 已完成开放编码；4–8 个失败分桶 （对于单一失败面任务上的合成 goldens，N/A 为 下限——参见 Building Goldens 例外；此时分桶数量 改由基线后的错误分析得出）。
2. eval/goldens.jsonl 已提交并纳入版本管理。
3. 每个分桶一个评分器，优先确定性评分器。
4. 评判器已校准——TPR/TNR、快照已固定、 不同家族（当没有任何分桶路由到 LLM 评判器时 为 N/A；需明确说明）。
5. eval/drift-suite.yaml 已冻结。
6. eval/baseline-<model>.json 已写入。

缺少这六项中的任何一项（或其所述的 N/A）？则阶段 0 未完成——/finetune 会在运行前检查基线文件。

相关技能

通用评估指导（仪表盘、A/B 测试、非微调测试框架） 位于 llm-application-dev 插件的 llm-evaluation 技能中——本技能仅涵盖微调耦合部分：兼作训练数据的 goldens，以及作为检查点门禁的基线。

• finetuning-method-selection——首先路由到这里。
• dataset-curation——将这些 trace 格式化为 训练行。
• trace-to-training-data——将已评分的 trace 转为 训练样本。
• checkpoint-promotion——消费 baseline-<model>.json，在每个候选检查点上重新 运行本测试框架。

参考资料

• references/grader-templates.md——每种形态的可运行 评分器示例，外加一个 drift-suite.yaml 示例和 MMLU logprob 评分说明。
• references/judge-calibration.md——校准协议， 包括全确定性的 N/A 路径。