第 7 章 evaluator：怎么给 LLM 的产出打分
本章目标：理解质量评估体系。学完你能回答：没有标准答案的考试怎么批卷？
三段评估各看什么？看门狗和 geval 双轨怎么配合？overall 怎么算、怎么判读？
7.1 评估的难题：没有标准答案的考试
测试用例生成没有"标准答案"——同一份文档可以有多套同样合格的用例集。所以评估不是"对答案"，
而是从多个可判定的侧面量质量：提的全不全（覆盖率）、结构对不对（层级/归属）、
内容忠不忠（没编造文档里没有的东西）、能不能执行（步骤规范）。
evaluator 的输入是"四件套"：策划文档（planning，必填 SRC md）+ ENT/PNT/CAS 三件产物（可选）。
读 PNT/CAS 走 modules/common/artifact_io.py 双格式分派（JsonLoader 单点内部处理）——
新批次 .db 与旧批次 JSON 对评估链完全透明，调用方零改。一个关键设计：
评估的对照基准（B 集合）永远从策划文档原文重新解析——不信任上游产物自报家门，
分母不受产物质量污染（产物说提取了 600 实体没用，评估自己从文档里解析出段落实体集合来对照）。
7.2 三段评估：实体 / 要点 / 用例
引擎 AssessmentEngine 把三类产物合并进一个实体集合，按 EntityType 过滤出三段分别评估：
实体段（提得全不全）——五维加权：
| 维度 | 权重 | 量什么 |
|---|---|---|
| 段落实体覆盖 | 30% | 文档每个段落能在实体集合里找到对应物吗（4 路匹配 + 语义兜底） |
| 文档覆盖 | 30% | 文档标题考核点逐个对齐（根节点强制对齐防系统性误判） |
| 结构完整 | 20% | 孤立节点（无任何关系）占比 |
| 属性完整 | 10% | description/priority 完备率 |
| LLM 辅助 | 10% | deep 模式走 LLM 裁判；fast 模式常数占位 |
要点段（测点想全没全）——权重最重的是覆盖率（30%）：分母 = 原子功能实体，
分子 = 被 TESTS 关系按精确 id 命中的原子实体数。这里有一段必知的修复史：
旧版分母取 priority≤3 全功能实体（默认 priority=3 即全体，包含 33 个非原子容器——
生成器只对原子生成要点，容器永不被测却计入分母），覆盖率被系统性低估（实测 20%→97.6% 的修复落差）。
教训：指标分母必须与生成目标集口径锁步。
用例段（用例合格没合格）——字段级契约检查：完整性（缺步骤/缺预期）、层级归属（没挂 TESTS）、
规范性（priority 越界/status 非法词表）、映射（source 双字段悬空）。注意：四象限分布是生成端 metadata，
用例评估器不评它——A/B 判读要统计四象限时从 CAS 产物自行汇总。
7.3 双轨：看门狗（确定性）与 geval（LLM 评审）
看门狗（StaticWatchdogEvaluator）——零 LLM 的确定性扣分器，是"优先于一切 LLM 指标的可信基准"：
score = max(0, 100 − 5×未覆盖原子实体(cap 20) − 3×违规步(cap 15) − 1×缺句柄(cap 5))
overall −= (100 − score)/100 # 后置折算
它直接复用生成端的契约校验代码（动作断言契约那套）而非重新实现——单一真相源，双端永不漂移。
判读纪律（实证教训）：violations 按绝对步数计罚，8126 步里 6 步（0.07%）瑕疵会被放大成
watchdog −12 的总分级摆动——判读 overall 波动必须先看 deductions 子分与 per-step 比例。
geval（GEvalEvaluator）——LLM 评审轨：对采样 20 条用例逐条评三维
（faithfulness 忠实度 40% / relevance 相关性 30% / executability 可执行性 30%），
与启发式分凸组合（0.3 权重）叠进要点/用例两段。三个值得学的细节：
- 判定标准领域中文重写——用 DeepEval 只取壳，不吃 QA 向内置指标；
- 契约信号 ground 化——确定性契约合规率注入 executability 维度，LLM 判断不悬空；
- flakiness 根治——LLM 偶发输出坏 JSON 曾让整评估任务 1/60 概率炸掉，修复链 = 剥围栏取 JSON → 空响应重试 → 单维失败只剔除出均值（可观测）→ 全失败才降级回退。
一个诚实的定性：faithfulness 是有天花板的指标（多源合法参考对照单一文档永难满分，
实测 14.5-59 分是通病）——防幻觉的主力已转向来源标注（provenance）而非追求 faithfulness 满分。
7.4 overall 与评估报告
overall = (实体段 + 要点段 + 用例段) 各 1/3 加权
− 看门狗扣分（后置折算）
→ 四档评级：≥0.9 优秀 / ≥0.8 良好 / ≥0.7 一般 / <0.7 不足
落盘四件 JSON（EVAL_ENT/PNT/CAS/SUMMARY），SUMMARY 内嵌三段完整输出 + retry_advice
（score<70 或有问题 → retry_required=true + 建议动作——dashboard 的生成链读这个分数线决定要不要自动重评一次）。
判读量级感：人工验收批次 overall 72.49 算"一般偏上"（对照早期版本 52.19）；历史全量批次 62~83 区间。
双层分数空间要记住：引擎内部是 0-1 学术分，落盘是 0-100 业务分，阈值判读先确认在哪层。
7.5 小结
- 评估 = 侧面量质量（覆盖率/结构/忠实/可执行），对照基准永远从原文重解析（分母干净）；
- 三段评估各五维加权；覆盖率分母必须与生成目标集（原子实体）口径锁步；
- 看门狗是零 LLM 确定性基座（复用生成端契约代码）；geval 是 LLM 评审轨（三维中文标准 + flakiness 修复）；
- overall = 三段均分 − 看门狗扣分；判读先看 deductions 子分；<70 触发链上自动重试；
- faithfulness 有天花板，防幻觉主力是 provenance 来源标注。
深入阅读：《技术实现说明.md》04 章（评估八小节）；
evaluator_测试评估指标体系.md
（指标速查手册含全部权重附录）。