eval-harness-first

用途

Eval Harness First 是整个微调插件的 Phase 0 门槛。finetuning-method-selection 以及所有下游技能都假设该评估框架先于训练配置存在。框架不是运行结束时的副产品，而是数据整理引擎：构建 goldens 的同一批带标签轨迹，在扣除显式留出集后，可直接用于训练数据。

输入：已有的生产/智能体轨迹，若不存在则为任务规格，外加愿意标注 ≥100 个示例的标注者。输出格式为下方的 eval/ 目录，包含 goldens、graders、漂移套件以及后续阶段用于把关的基座模型基线。

门槛逻辑（飞轮）

没有评估框架，就没有微调。跳过框架直接写训练配置，就没有可度量的基准、无法捕捉回归、也没有带标签数据可训练。流程如下：

收集轨迹——生产/智能体 span，若尚不存在则使用合成任务。
错误分析——对 ≥100 条轨迹做开放编码，再轴向编码归并为 4–8 个失败桶。
每个桶一个评分器——优先确定性；仅对真正主观的标准使用经校准的 LLM 评审。
按频率 × 严重度 × 价值排序。
带标签轨迹在扣除显式留出集后进入数据集整理。每个 eval/goldens.jsonl 的 ID 都在训练数据中按 ID 排除。
训练。
在检查点上重跑同一套框架——不是另一套更宽松的框架。
漂移检测反馈至第 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 而非 generate-and-extract——紧凑的 token 预算下，generate-and-extract 对会加开场白的模型解析脆弱，会把格式合规与被测知识混为一谈。四种评分器形态的模板及此评分说明见 references/grader-templates.md。

评审校准是前提

任何路由到 LLM 评审的桶，其裁决在超出探索用途前都需要校准——这是硬前提，而非锦上添花。当没有桶路由到评审时为 N/A——全确定性框架没有可校准对象；应明确说明，而非留空该节。

标注 ≥100 项，切分 train/dev/sealed test（sealed test 只报告一次，之后不再触碰）。
报告 TPR 与 TNR，而非单一混合准确率——在偏斜集上总说“通过”的评审也能达到 90%。
将评审固定到固定模型快照，评审模型更换时重新校准，无论如何每季度一次。
评审必须来自与被测模型不同的模型家族。
未达到约定 TPR/TNR 门槛的评审以仅咨询模式发布——标记供人工复核，绝不把关晋升。完整协议、偏差纠正与重新校准清单见 references/judge-calibration.md。

基线

在 Phase 1（方法选择）开始前，对未修改的基座模型运行完整框架——goldens 加能力漂移套件。这是后续每个检查点用于对比的数字。

eval/baseline-<model>.json 是门槛凭证。没有基线文件，就没有检查点晋升的对比基准——一个相对于“没有度量任何东西”而“看起来更好”的检查点不构成发现。

目录契约

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/。规范位置：每个逐轨迹 results.json——包括 Phase 0 基线——都放在 runs/<run-id>/results.json，绝不在 eval/runs/... 下；要求后者的指令是错误的，本契约才是对的。

Phase 0 退出清单

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

≥100 条轨迹完成开放编码；4–8 个失败桶（单失败面任务的合成 goldens 有 N/A 底线——见构建 Goldens 例外；此时桶数改由基线后错误分析得出）。
eval/goldens.jsonl 已提交并版本化。
每个桶一个评分器，确定性优先。
评审已校准——TPR/TNR、快照已固定、不同家族（无桶路由到 LLM 评审时为 N/A；需明确说明）。
eval/drift-suite.yaml 已冻结。
eval/baseline-<model>.json 已写入。

缺少这六项中的任何一项（或其声明的 N/A）？Phase 0 未完成——/finetune 在运行前检查基线文件。

参考资料

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

技能介绍

用途