feat(eval): add executor audit closure checks

2026-07-08 10:21:39 +08:00
parent 6015bcbf6f
commit a08672b31e
20 changed files with 1142 additions and 188 deletions
@@ -1,203 +1,150 @@
 # Diagnosis Eval Data Schema

-这份文档记录评测基准里的数据结构。口语化理解就是：
+这份文档记录 `mvp/eval` 固定评测集的数据结构。评测器读取保存好的 trace fixture，用确定性规则判断这次 Agent 运行是否满足预期。

 ```text
-用例文件说“我要考什么”
-trace 文件说“Agent 实际做了什么”
-评测结果说“这次有没有跑偏”
-汇总报告说“整体稳定性怎么样”
+case 文件：我要考什么
+fixture 文件：Agent 实际做了什么
+评测结果：这条 case 是否通过，哪里失败
+baseline report：整套固定集当前认可的结果
 ```

-当前这套评测是代码规则判断，不是再调用一个 LLM 来打分。
+当前评测不调用 LLM 打分。

-## 1. 用例定义
+## 1. Case 定义

 文件：`mvp/eval/cases/diagnosis-cases.json`

-每一条 case 是一个固定考题，告诉评测器“这个问题应该看哪些点、需要哪些证据、哪些结论可以接受”。
+每条 case 定义一个固定诊断场景。

 ```json
 {
-  "id": "payment-timeout",
-  "title": "Payment API timeout",
-  "question": "支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。",
-  "traceFixture": "payment-timeout-pass.json",
-  "expectedRootCauseKeywords": ["支付", "超时", "连接池"],
+  "id": "unsupported-claim-filtering",
+  "title": "Unsupported claim filtering",
+  "question": "订单超时是否可以确认由数据库主库故障导致？",
+  "traceFixture": "unsupported-claim-filtering-low-confid.json",
+  "expectedRootCauseKeywords": ["超时", "证据"],
  "minKeywordMatches": 2,
-  "requiredEvidenceTools": ["lookup_knowledge", "query_logs", "query_metrics"],
-  "allowedVerdicts": ["PASS", "LOW_CONFID"],
-  "forbiddenAnswerKeywords": ["无证据确定"]
+  "requiredEvidenceTools": ["query_logs"],
+  "allowedVerdicts": ["LOW_CONFID"],
+  "forbiddenAnswerKeywords": ["已经确认"],
+  "requireV2AuditClosure": true,
+  "requireClaimChecks": true,
+  "requireComposerOutput": true,
+  "expectedGatekeeperStatuses": ["pass"],
+  "expectedComposerStatuses": ["valid"],
+  "forbiddenConfirmedClaimKeywords": ["主库故障"]
 }
 ```

 字段说明：

-| 字段 | 意思 | 评测器怎么用 |
+| 字段 | 含义 | 评测器怎么用 |
 | --- | --- | --- |
-| `id` | 这条用例的唯一名字 | 出现在报告里，方便定位是哪条 case 挂了 |
-| `title` | 给人看的标题 | 出现在结果里，方便快速理解场景 |
-| `question` | 要问 Agent 的问题 | fixture 模式下不会真的发送给 Agent，但它记录了这条 case 的原始输入 |
-| `traceFixture` | 对应的 trace 文件名 | 评测器会去 `fixtures/` 目录加载这个文件 |
-| `expectedRootCauseKeywords` | 最终回答里希望看到的关键点 | 评测器会在 `session.answer` 里做关键词命中检查 |
-| `minKeywordMatches` | 至少要命中几个关键词 | 命中数低于这个值，就认为根因覆盖不够 |
-| `requiredEvidenceTools` | 这条 case 至少应该用到哪些证据工具 | 评测器会检查 trace 里是否出现这些工具 |
-| `allowedVerdicts` | Verifier 允许给出的结论 | 比如 `PASS` 或 `LOW_CONFID`，不在列表里就失败 |
-| `forbiddenAnswerKeywords` | 回答里不应该出现的危险说法 | 命中这些词，说明回答可能过度自信或不符合降级策略 |
+| `id` | case 唯一标识 | 出现在报告中 |
+| `title` | 可读标题 | 出现在报告中 |
+| `question` | 原始用户问题 | 用于说明场景，fixture 模式不会真实发送给 Agent |
+| `traceFixture` | 对应 fixture 文件名 | 从 `mvp/eval/fixtures` 加载 |
+| `expectedRootCauseKeywords` | 最终答案应覆盖的关键词 | 在 `session.answer` 中做包含判断 |
+| `minKeywordMatches` | 最少命中关键词数 | 低于该值则失败 |
+| `requiredEvidenceTools` | 必须出现的证据工具 | 从 `toolInvocations` 和 `tool_trace_summary` 中收集 |
+| `allowedVerdicts` | 允许的 Verifier verdict | verdict 不在列表中则失败 |
+| `forbiddenAnswerKeywords` | 最终答案禁止出现的词 | 用于拦截过度自信或危险表达 |
+| `requireV2AuditClosure` | 是否要求 V2 审计闭环字段 | 要求 `gatekeeper_result`、`claim_checks`、`composer_output` 存在，并检查 raw JSON 泄漏 |
+| `requireClaimChecks` | 是否要求 `claim_checks` | 要求 claim check 数组存在且非空 |
+| `requireComposerOutput` | 是否要求 `composer_output` | 要求 Composer 审计存在并带 `status` |
+| `expectedGatekeeperStatuses` | 允许的 Gatekeeper 状态 | 实际 `gatekeeper_result.status` 不在列表中则失败 |
+| `expectedComposerStatuses` | 允许的 Composer 状态 | 实际 `composer_output.status` 不在列表中则失败 |
+| `forbiddenConfirmedClaimKeywords` | 不得进入最终答案的未支持结论关键词 | 用于证明 unsupported/external_unknown claim 被过滤 |

 ## 2. Trace Fixture

 目录：`mvp/eval/fixtures/*.json`

-trace fixture 是一次 Agent 运行后的“留痕快照”。评测器不会关心整个 trace 的所有字段，只读取当前能支撑基准判断的字段。
+fixture 是一次 Agent 运行后的 trace 快照。评测器只读取当前规则需要的字段。

-当前会读取这些字段：
-
-| Trace 字段 | 意思 | 评测器怎么用 |
+| Trace 字段 | 含义 | 评测器怎么用 |
 | --- | --- | --- |
-| `session.answer` | Agent 最终给用户的回答 | 用来检查根因关键词和禁用词 |
-| `session.totalDurationMs` | 这次运行耗时 | 进入报告，帮助观察性能是否明显变差 |
-| `session.selfEvaluation.verifier_evaluation.verdict` | Verifier 对最终回答的判断 | 必须存在，并且要落在 case 的 `allowedVerdicts` 里 |
-| `session.selfEvaluation.verifier_evaluation.executor_structured_output.claims[*].evidence_bindings` | Executor 结构化输出里的确认事实证据绑定 | 如果 trace 中存在结构化 Executor 输出，每条 confirmed claim 必须有证据绑定 |
-| `session.selfEvaluation.verifier_evaluation.tool_trace_summary[*].tool_name` | Verifier 总结里看到的工具证据 | 用来补充判断证据工具是否出现 |
-| `toolInvocations[*].toolName` | Agent 实际调用过的工具名 | 用来检查 `requiredEvidenceTools` 是否满足 |
-| `toolInvocations[*].success` | 工具调用是否成功 | 当前主要保留在 trace 里，后续可以升级成更严格的成功率检查 |
-
-简单说，trace 里最重要的是三类信息：
-
-```text
-最终回答：它说了什么
-工具证据：它查了什么
-Verifier：它自己有没有承认这个结论可靠
-```
+| `session.answer` | 最终用户答案 | 检查关键词、禁用词、unsupported claim 泄漏、raw JSON 泄漏 |
+| `session.totalDurationMs` | 运行耗时 | 进入报告 |
+| `session.selfEvaluation.verifier_evaluation.verdict` | Verifier 判定 | 必须存在并符合 case 的 `allowedVerdicts` |
+| `session.selfEvaluation.verifier_evaluation.gatekeeper_result.status` | Gatekeeper 结果 | V2 case 必须存在；`fail` 不允许搭配 `PASS` |
+| `session.selfEvaluation.verifier_evaluation.claim_checks` | Verifier V2 claim 级校验 | V2 case 必须存在；每项需要 `claim_id`、`verification`、`detail` |
+| `session.selfEvaluation.verifier_evaluation.composer_output.status` | Composer 渲染状态 | V2 case 必须存在；记录 `valid`、`composer_malformed` 等 |
+| `session.selfEvaluation.verifier_evaluation.executor_structured_output.claims[*].evidence_bindings` | Executor claim 证据绑定 | 如果结构化输出存在，每条 claim 需要证据绑定 |
+| `session.selfEvaluation.verifier_evaluation.tool_trace_summary[*].tool_name` | Verifier 看到的工具证据 | 用于补充证据工具覆盖 |
+| `toolInvocations[*].toolName` | 实际调用工具名 | 用于检查 `requiredEvidenceTools` |
+| `toolInvocations[*].success` | 工具调用是否成功 | 当前主要保留在 trace 中 |

 ## 3. 单条评测结果

 Java 类型：`DiagnosisEvalResult`

-这是每条 case 跑完之后的判断结果。
-
-| 字段 | 意思 |
+| 字段 | 含义 |
 | --- | --- |
-| `caseId` | 对应的 case id |
+| `caseId` | 对应 case id |
 | `title` | case 标题 |
-| `passed` | 这条 case 是否通过 |
-| `failedChecks` | 没通过的具体原因，比如缺工具、关键词不够、verdict 不允许 |
-| `verdict` | 从 trace 里读出来的 Verifier verdict |
-| `matchedKeywordCount` | 最终回答命中的关键词数量 |
-| `requiredKeywordCount` | case 定义里一共有多少个关键词 |
-| `evidenceCoverage` | 每个必需工具是否出现，例如 `{ "query_logs": true }` |
-| `toolCallCount` | 本次 trace 里工具调用总数 |
-| `durationMs` | 本次 trace 的耗时 |
-
-判断通过的口语化规则：
-
-```text
-回答要说到关键点
-该查的证据工具要查到
-Verifier 的结论要在可接受范围内
-回答不能出现危险的过度自信表达
-如果是 REJECT，就必须走降级模板
-```
+| `passed` | 该 case 是否通过 |
+| `failedChecks` | 失败原因列表 |
+| `verdict` | 从 trace 中读到的 Verifier verdict |
+| `matchedKeywordCount` | 最终答案命中的关键词数量 |
+| `requiredKeywordCount` | case 配置的关键词数量 |
+| `evidenceCoverage` | 每个必需工具是否出现 |
+| `gatekeeperStatus` | 读到的 `gatekeeper_result.status` |
+| `composerStatus` | 读到的 `composer_output.status` |
+| `claimCheckCount` | `claim_checks` 数量 |
+| `toolCallCount` | trace 中工具调用总数 |
+| `durationMs` | trace 总耗时 |

 ## 4. 汇总报告

 Java 类型：`DiagnosisEvalReport`

-这是整个基准集跑完之后的总结果。
-
-| 字段 | 意思 |
+| 字段 | 含义 |
 | --- | --- |
-| `totalCases` | 总共评测了多少条 case |
-| `passedCases` | 通过了多少条 |
-| `passRate` | 通过率，范围是 `0.0` 到 `1.0` |
-| `verdictDistribution` | Verifier verdict 的分布，比如有几个 `PASS`、几个 `LOW_CONFID` |
-| `averageToolCallCount` | 平均每条 case 调用了多少次工具 |
+| `totalCases` | case 总数 |
+| `passedCases` | 通过数 |
+| `passRate` | 通过率，范围 `0.0` 到 `1.0` |
+| `verdictDistribution` | Verifier verdict 分布 |
+| `averageToolCallCount` | 平均工具调用数 |
 | `averageDurationMs` | 平均耗时 |
-| `results` | 每条 case 的详细结果列表 |
+| `results` | 单条 case 结果列表 |

-## 5. 怎么看这个基准
+## 5. Stage 5 V2 审计闭环规则

-这套结构不是为了证明 Agent 永远正确，而是为了在每次改 prompt、工具、检索、Verifier 之后，有一个固定尺子能回答：
+阶段 5 关注的是“前四段链路是否能被固定评测证明”：

 ```text
-以前能过的诊断题，现在还过不过？
-它是不是少查了某些证据？
-它是不是变得更自信但证据不足？
-它是不是开始输出不该说的话？
-它是不是明显变慢了？
+Executor structured output
+-> Gatekeeper deterministic audit
+-> Verifier claim_checks
+-> Composer filtered final answer
 ```

-所以面试里可以这样讲：
+新增确定性规则：

-```text
-我没有只看一次 demo 效果，而是把典型诊断场景固化成 case。
-每条 case 都定义预期关键点、必需证据工具和可接受的 verifier 结论。
-Agent 每次运行会留下 trace，评测器用代码规则读取 trace，输出结构化报告。
-这样我改 Agent 的时候，可以用同一套基准判断有没有行为回退。
-```
+- V2 case 必须有 `gatekeeper_result`、`claim_checks`、`composer_output`。
+- `gatekeeper_result.status = fail` 时，Verifier verdict 不能是 `PASS`。
+- `claim_checks[*].verification` 只能是 `direct_observation`、`reasonable_inference`、`overstated`、`unsupported`、`external_unknown`、`contradicted`。
+- Composer 输出必须记录 `status`。
+- 最终答案不能泄漏 `executor_evidence_v2`、`answer_version`、`evidence_bindings`、`claim_id`。
+- case 配置的 `forbiddenConfirmedClaimKeywords` 不能出现在最终答案里。

 ## 6. Baseline Diff

-Baseline diff 是拿两份 report 做对比：
+Baseline diff 比较两份 report：

 ```text
-baseline report：以前认可的基准结果
-current report：这次改动后跑出来的新结果
-diff report：告诉你哪里变好了、哪里变差了、哪里只是变了
+baseline report：已经认可的基准结果
+current report：当前代码/fixture 跑出的结果
+diff report：结构化列出退化、改善和普通变化
 ```

-Java 类型：
+主要退化信号：

- `DiagnosisEvalDiffReport`
- `DiagnosisEvalDiffItem`
-
-`DiagnosisEvalDiffReport` 字段：
-
-| 字段 | 意思 |
-| --- | --- |
-| `baselineTotalCases` | baseline 里有多少条 case |
-| `currentTotalCases` | current 里有多少条 case |
-| `baselinePassedCases` | baseline 通过了多少条 |
-| `currentPassedCases` | current 通过了多少条 |
-| `baselinePassRate` | baseline 通过率 |
-| `currentPassRate` | current 通过率 |
-| `regressionCount` | 退化项数量 |
-| `improvementCount` | 改善项数量 |
-| `changedCount` | 普通变化项数量 |
-| `hasRegression` | 是否存在退化 |
-| `items` | 具体 diff 明细 |
-
-`DiagnosisEvalDiffItem` 字段：
-
-| 字段 | 意思 |
-| --- | --- |
-| `type` | `REGRESSION`、`IMPROVEMENT` 或 `CHANGED` |
-| `scope` | `aggregate` 表示整体指标，`case` 表示单条 case |
-| `caseId` | 如果是单条 case 变化，这里记录 case id |
-| `metric` | 哪个指标变了，比如 `passRate` 或 `evidenceCoverage.query_logs` |
-| `baselineValue` | baseline 里的值 |
-| `currentValue` | current 里的值 |
-| `delta` | 数值变化量；非数值变化为空 |
-| `message` | 给人看的变化说明 |
-
-口语化判断规则：
-
-```text
-pass rate 下降：退化
-case 从通过变失败：退化
-证据工具从有变没有：退化
-关键词命中变少：退化
-工具调用或耗时升高：成本上升，记为退化信号
-verdict 分布变化：记录变化，供人工判断是否符合预期
-```
-
-面试里可以这样讲：
-
-```text
-我把 baseline report 和当前 report 做结构化 diff。
-它不是再问 LLM，而是用代码比较固定字段。
-如果某个 case 从 PASS 变 FAIL，或者 query_logs 证据没了，
-diff 会直接标成 regression。
-这样 Agent 改动可以用固定基准做回归判断。
-```
+- pass rate 下降。
+- case 从通过变失败。
+- 必需证据工具从有变无。
+- 关键词命中减少。
+- 工具调用或耗时明显上升。
+- verdict 分布变化。