# Executor Structured Output V2 可执行设计与实施 Issue

> 归档说明：本文记录旧的分阶段实施方案，其中的兼容期和待启动状态不再适用。当前实现以 `mvp/architecture/executor-evidence-pipeline-refactor.md` 和 OpenSpec 主规格为准。

**状态**：阶段四待启动，前三阶段已归档并提交
**严重程度**：高  
**创建日期**：2026-07-07  
**最后更新**：2026-07-08  
**文档类型**：可执行设计 issue / 分阶段实施说明  
**范围**：Chat Executor 输出结构、Gatekeeper、Verifier、Composer 数据契约调整  
**关联问题**：

- `executor-evidence-attribution-hallucination`
- `executor-self-evidence-loop-design-note`
- `chat-verifier-agent`
- `executor-evidence-output-contract`

---

## 0. 执行摘要

这份文档是 `Executor Structured Output V2` 的可执行设计 issue，用来指导后续 agent 按阶段实施，不是单纯的数据结构草案。

后续 agent 接手时，应先读完本节，确认“为什么做、做到哪、下一步做什么、如何验收”，再进入后面的字段契约和 prompt 细节。

### 0.0 这次改造要解决什么

当前 Chat 复杂诊断链路中，Executor 已经会调用 `lookup_knowledge`、`query_metrics`、`query_logs` 等证据工具，但它在最终输出时容易把三类内容混在一起：

1. 本轮工具真实返回的事实。
2. runbook、skill、知识库里的通用模式。
3. 模型基于经验补全的推断。

这会导致 Executor 把“可能方向”写成“确认结论”，甚至在 `user_facing_answer` 中夹带未被 Verifier 校验过的根因、错误码、指标值或修复建议。Verifier 虽然会拦截一部分，但它被迫同时处理“事实抽取”和“事实校验”，职责边界不稳定。

本 issue 的核心目标是切断这条风险链路：

```text
Executor 只负责收集证据并输出结构化材料；
Gatekeeper 先用代码拦截物理级幻觉；
Verifier 只判断 claim 是否能由证据合理推出；
Composer 只根据 Verifier 允许的材料生成最终用户答案。
```

### 0.1 当前实现与目标链路

当前复杂 Chat 链路：

```text
chat_planner -> chat_executor -> chat_verifier -> final answer
```

目标链路：

```text
chat_planner
  -> chat_executor
  -> VerifierInputHook 内 Gatekeeper
  -> chat_verifier
  -> chat_composer
  -> final answer
```

本次不改 Planner，不新增 Controller，不改现有 retry 机制。改造重点只放在 Executor 输出契约、Gatekeeper 确定性校验、Verifier claim 可推导性校验、Composer 最终表达。

### 0.2 当前接手快照

截至 2026-07-08，仓库状态应以 `git status --short`、`openspec/changes` 和最近提交为准。当前已知阶段状态如下：

| 阶段 | 状态 | 记录 |
|---|---|---|
| 阶段一：Executor V2 输出契约 | 已完成、已归档、已提交 | `050cbc8 feat(agent): add executor evidence v2 contract` |
| 阶段二：Gatekeeper 接入 VerifierInputHook | 已完成、已归档、已提交 | `c5e496e feat(agent): add executor gatekeeper hook` |
| 阶段三：Verifier V2 可推导性校验 | 已完成、已归档、已提交 | `1b31e78 feat(agent): add verifier claim checks` |
| 阶段四：Composer 输出最终答案 | 下一阶段，待启动 | 建议 change id：`executor-composer-final-answer` |
| 阶段五：回归评测与审计闭环 | 未开始 | 等 Composer 链路稳定后补齐 |

接手时的第一动作：

1. 运行 `git status --short`，确认工作区是否干净。
2. 运行 `Get-ChildItem openspec\changes`，确认是否存在未完成 active change。
3. 如果没有 active change，下一步应创建阶段四 OpenSpec change：`executor-composer-final-answer`。
4. 阶段四完成后，必须先验证、归档 OpenSpec、回填 devflow、单独 commit，再进入阶段五。

### 0.3 推荐阅读顺序

1. 先读 `0A - 0I`：理解背景、问题、目标、范围、阶段和执行纪律。
2. 再读 `0.5 当前下一阶段执行卡片`、`19. Composer 设计`、`20. 当前代码影响面`、`21. 实施阶段`：理解当前下一阶段如何落地。
3. 最后按需查阅 `2 - 18`：这些是已经讨论过的数据契约、Gatekeeper 规则和 Verifier 输入输出。

### 0.4 阶段实施纪律

后续实施必须按阶段串行推进：

```text
阶段一 archive + commit
  -> 阶段二 archive + commit
  -> 阶段三 archive + commit
  -> 阶段四 archive + commit
  -> 阶段五 archive + commit
```

执行约束：

- 每个阶段都要先有 OpenSpec change，再实现、验证、归档到 devflow，并单独提交。
- 阶段未归档、未提交前，不进入下一阶段。
- 每个阶段只解决该阶段的问题，不顺手做下一阶段。
- 每个阶段至少要有主成功路径和新增失败路径测试。
- 提交前必须确认 diff 只包含当前阶段内容。
- 验收失败如果是代码问题，agent 自行修复；如果是设计决策不明确，停下来问用户。
- 不推送，除非用户明确要求。

### 0.5 当前下一阶段执行卡片

当前下一阶段是：

```text
阶段四：Composer 输出最终答案
```

建议 OpenSpec change id：

```text
executor-composer-final-answer
```

阶段四要做的事情：

- 新增 `chat_composer` Agent 或等价 Composer 调用。
- 新增 `chat-composer-prompt.md`。
- 在 `ChatService` 中，Verifier 完成后组装 Composer 输入。
- Composer 输入只能包含 Verifier 允许材料：`allowed_claims`、`allowed_hypotheses`、`missing_info`、`recommended_actions`、`rationale`。
- PASS、LOW_CONFID、REJECT 的最终用户答案都不能再读取 Executor 的 `user_facing_answer`。
- Composer 输出必须是严格 JSON，包含 `answer_summary`、`recommended_actions`、`user_facing_answer`。
- Composer malformed 时必须走安全降级，不得向用户泄露 raw JSON 或 Executor 原文。

阶段四明确不做：

- 不改 Planner。
- 不改 Gatekeeper 规则集。
- 不扩展 Verifier 判定枚举。
- 不新增数据库表。
- 不让 Composer 调用工具。
- 不让 Composer 重新判断根因。
- 不提前做阶段五 eval fixture 大扩展。

阶段四最小验收：

- Composer 输入不包含 raw tool output。
- 未通过 Verifier 的 claim 不进入最终答案。
- `REJECT` 最终答案不出现根因结论，`allowed_hypotheses=[]`。
- `LOW_CONFID` 最终答案区分已确认信息、可能方向和证据缺口。
- `PASS` 只有在存在允许输出的 root cause claim 时，才表达根因已确认。
- `ChatService` 不再依赖阶段一临时 V2 renderer 生成 PASS 用户答案。

---

## 0A. 背景与问题定义

### 0A.1 背景

近期 Chat 复杂诊断链路中，多条诊断会话被 Verifier 判为 `LOW_CONFID`。这些会话并不是没有调用工具；Executor 通常已经调用了 `lookup_knowledge`、`query_metrics`、`query_logs` 等 evidence tools。

真正的问题是：Executor 在综合输出阶段把三类内容混在一起写成“当前事故结论”：

1. 本轮工具真实返回的事实。
2. runbook、skill 或知识库里的通用模式。
3. 模型基于经验补全的推断。

当前 Executor 输出中还包含最终面向用户的自然语言字段：

```text
diagnosis_summary
user_facing_answer
```

这会诱导 Executor 提前进入“诊断报告 / 用户表达”模式，在证据不充分时把“可能方向”写成“确认结论”。后续 Verifier 虽然会拦截，但它面对的是自然语言答案和结构化字段混在一起的输出，校验边界不稳定。

典型风险包括：

- Executor 编造不存在的 `source_invocation_ids`。
- Executor 使用真实 invocation id，但 `evidence_excerpt` 与真实工具输出不一致。
- Executor 把 hypothesis 写成 confirmed claim。
- Executor 在 `user_facing_answer` 里夹带 claims 中没有的根因、错误码、指标值或修复建议。
- Verifier 被迫从自然语言里逐字抽事实，校验边界不稳定。

因此，本次改造不是为了“多加几个 Agent 显得完整”，而是为了收紧证据归因链路：Executor 只产出可校验材料，Verifier 只判断材料是否被证据支撑，最终表达交给 Composer。

---

### 0A.2 当前问题定义

本 issue 要解决的是：

```text
Executor 证据归因幻觉
```

更具体地说，Executor 已经调用了工具，但在最终输出时没有严格区分：

| 类型 | 定义 | 应进入哪里 |
|---|---|---|
| direct evidence | 本轮工具直接观测到的事实 | `claims` |
| reasonable inference | 能由证据合理推出但不是逐字出现的判断 | `claims`，但需要标注 `indirect`，并由 Verifier 判断是否说重 |
| hypothesis | 值得排查但尚未被当前证据确认的方向 | `hypotheses` |
| missing evidence | 还缺少哪些证据才能确认 | `missing_info` |
| user expression | 面向用户的自然语言答案 | Composer 输出，不由 Executor 输出 |

如果不拆开这些边界，Verifier 会长期承担两个不同任务：

1. 从自然语言中抽事实。
2. 判断事实是否有证据支撑。

这会让 Verifier 的职责过重，也让最终答案容易夹带未经校验的内容。

---

### 0A.3 当前实现

当前代码中的复杂 Chat 链路是三 Agent 顺序执行：

```text
chat_planner -> chat_executor -> chat_verifier
```

对应入口在：

```text
ChatService.executeChatComplex(...)
```

当前数据流：

```text
用户问题
  -> Planner 生成 planner_plan
  -> Executor 调用工具并输出 executor_evidence_v1
  -> VerifierInputHook 构造 verifier payload
  -> Verifier 输出 facts_checked/verdict
  -> ChatService 根据 verdict 生成最终 answer
```

当前关键问题在 Executor 与 Verifier 之间：

```text
Executor 同时输出结构化 claims 和 user_facing_answer
Verifier 既要校验 structured output，又要扫描自然语言答案
```

这会让最终答案和证据归因之间出现缝隙。

---

## 0B. 目标设计

目标链路仍保持单条顺序链路，不新增 Controller，不改 Planner：

```text
chat_planner
  -> chat_executor
  -> VerifierInputHook 内 Gatekeeper
  -> chat_verifier
  -> chat_composer
  -> final answer
```

职责边界：

| 组件 | 职责 |
|---|---|
| Planner | 选择 skill、拆解计划；本次不改 |
| Executor | 调用工具收集证据，输出结构化 claims/hypotheses/actions/missing_info |
| Gatekeeper | 在 Verifier 前做确定性校验，拦截伪造 ID、工具名不匹配、明显张冠李戴、非法 schema |
| Verifier | 判断 claims 是否能由证据合理推出，不再逐字扫描最终答案 |
| Composer | 只根据 Verifier 允许的材料生成最终用户答案 |

目标数据流：

```text
Executor raw JSON
  -> parse JSON
  -> Gatekeeper.validate(...)
  -> Verifier claim-level validation
  -> ChatService 过滤 allowed_claims/allowed_hypotheses
  -> Composer 生成 user_facing_answer
```

核心原则：

- 单智能体优先：不为了抽象而新增 Controller；只有已经明确的职责边界才拆 Agent。
- Planner 不改：本 issue 的问题不在计划拆解，而在 Executor 输出和 Verifier 校验边界。
- Gatekeeper 不做诊断：只做确定性校验，拦截伪造 ID、字段退化、明显张冠李戴。
- Verifier 不再逐字扫描最终答案：主校验对象是结构化 `claims`。
- Composer 不补事实：只把 Verifier 允许的材料组织成中文答案。

---

## 0C. 分阶段实施总览

| 阶段 | 名称 | 目标 | 状态 | 退出条件 |
|---|---|---|---|---|
| 1 | Executor V2 输出契约 | 移除 Executor 最终表达字段，只输出结构化诊断材料 | 已完成并归档 | `executor_evidence_v2` 可运行，最终用户不再看到 raw JSON |
| 2 | Gatekeeper 接入 VerifierInputHook | 在 Verifier 前加入确定性拦截与审计 | 已完成并归档 | `gatekeeper_result` 进入 Verifier payload 和 `self_evaluation` |
| 3 | Verifier V2 可推导性校验 | 从 `facts_checked` 转向 `claim_checks`，判断 claims 是否可由证据推出 | 已完成并归档 | Verifier 不再从自然语言答案抽取额外事实 |
| 4 | Composer 最终表达 | 由 Composer 根据 Verifier 允许材料生成最终用户答案 | 下一阶段 | PASS/LOW_CONFID/REJECT 都不读取 Executor `user_facing_answer` |
| 5 | 回归评测与审计闭环 | 用测试和 eval fixtures 证明幻觉拦截链路有效 | 未开始 | 伪造 ID、张冠李戴、hypothesis 写成事实等场景都有回归覆盖 |

更详细的实施拆解见 `21. 实施阶段`。

阶段推进顺序必须串行：

```text
阶段一 archive + commit
  -> 阶段二 archive + commit
  -> 阶段三 archive + commit
  -> 阶段四 archive + commit
  -> 阶段五 archive + commit
```

不能在 Composer 未稳定时把回归评测阶段提前做成大杂烩。

---

## 0D. 范围与非目标

### In scope

- 调整 Executor 输出契约，从 `executor_evidence_v1` 演进到 `executor_evidence_v2`。
- 在 `VerifierInputHook` 中接入 Gatekeeper。
- 将 Gatekeeper 结果写入 Verifier payload 和 `diagnosis_session.self_evaluation`。
- 将 Verifier 主输出从 `facts_checked` 迁移到 `claim_checks`，兼容期保留旧字段。
- 新增 Composer 表达层，最终用户答案只来自 Verifier 允许材料。
- 补齐关键回归测试和 eval fixtures。

### Out of scope

本 issue 第一版明确不做以下事情：

- 不改 Planner 的输入输出。
- 不引入 Controller 或新的编排层。
- 不改变现有 retry 机制。
- 不要求 Gatekeeper 失败后自动回退 Executor 重试。
- 不新增数据库表。
- 不让 Gatekeeper 做根因判断。
- 不让 Composer 调用工具或重新诊断。

---

## 0E. 关键设计决策

| 决策 | 结论 | 原因 |
|---|---|---|
| 是否改 Planner | 不改 | 当前问题主要在 Executor 输出和 Verifier 校验边界 |
| Gatekeeper 放在哪里 | 放在 `VerifierInputHook` | 保持当前 workflow，不改 Executor hook 和编排 |
| Gatekeeper 失败是否重试 | 第一版不重试 | 先建立拦截和审计闭环，避免扩大改动面 |
| Executor 是否继续输出最终答案 | 不输出 | 防止未经 Verifier 的自然语言结论泄露 |
| Verifier 是否逐字扫描答案 | 不扫描 | 主校验对象改为 `claims` |
| Composer 是否可以新增事实 | 不可以 | Composer 只是表达层，不是诊断层 |
| `facts_checked` 是否保留 | 兼容期保留 | 当前低置信模板、retry_context、评测可能依赖 |

---

## 0F. 实现约束

实现时必须遵守：

- 优先保持现有三 Agent 复杂链路可运行。
- 每个阶段都应能单独测试和回滚。
- 第一版以“降低幻觉风险”为目标，不追求一次性重构所有历史字段。
- 所有最终用户可见答案都必须来自 Verifier 允许输出的材料。
- 所有 Gatekeeper 校验结果都必须进入审计，至少能回溯到 `self_evaluation.verifier_evaluation.gatekeeper_result`。
- 如果结构化输出 malformed，不允许回退到自然语言逐字抽取后给 PASS。

---

## 0G. OpenSpec / devflow 落地要求

这个 issue 后续按 OpenSpec-first 的方式实施。每个阶段都必须留下可审计痕迹：

```text
OpenSpec proposal/design/spec/tasks
  -> 实现代码
  -> 最小验证
  -> archive 到 openspec/changes/archive
  -> 回填 devflow/projects
  -> git commit
```

阶段交付物：

| 交付物 | 要求 |
|---|---|
| OpenSpec change | 每个阶段一个独立 change，不能复用上个阶段的 active change |
| tests | 至少覆盖该阶段的新增失败路径和主成功路径 |
| devflow | 记录 brief、decisions、evidence、acceptance |
| commit | 每个阶段单独提交，提交前确认 diff 只包含本阶段内容 |

推荐验证命令：

```powershell
mvn "-Dtest=VerifierInputHookTest,ChatServiceSequentialAgentTest" test
cmd /c openspec validate --specs
```

如阶段新增专门测试，应把测试类加入 Maven `-Dtest` 列表。

后续 agent 每个阶段的固定执行清单：

1. 确认当前阶段：读取本 issue、`git status --short`、`openspec status`。
2. 确认 OpenSpec：没有 active change 时先创建；已有当前阶段 active change 时继续使用。
3. 实现阶段内代码：只改该阶段要求的 prompt/service/hook/test，不夹带下一阶段。
4. 验证：运行该阶段建议测试和 `cmd /c openspec validate ...`。
5. 回填任务：更新 OpenSpec `tasks.md`、`decisions.md`，记录实际验证命令和结果。
6. 归档：创建或更新 `devflow/projects/<date>-<change-id>/`，然后 `cmd /c openspec archive <change-id> -y`。
7. 复验：归档后再次运行最小测试和 `cmd /c openspec validate --specs`。
8. 提交：检查 `git diff --cached --stat`，确认只包含当前阶段，再单独 commit。

若步骤 4 或 7 失败：

- 代码或测试问题：自行修复并重新验证。
- 阶段边界或协议设计问题：停止，向用户说明阻塞点，不进入下一阶段。

---

## 0H. 推荐实现切片

建议不要把所有改动塞进一个大 PR。推荐拆成以下可独立验收的切片：

| 切片 | 内容 | 可单独合入条件 |
|---|---|---|
| PR-1 | Executor V2 prompt + parse-only 边界调整 | Executor 能输出 V2 JSON；不会再通过 Executor 直接生成最终用户答案 |
| PR-2 | Gatekeeper 基础框架 + schema/invocation 规则 | Verifier payload 和审计中出现 `gatekeeper_result`；伪造 invocation id 可被拦截 |
| PR-3 | Verifier V2 claim_checks + facts_checked 兼容 | Verifier 主校验 `claims`；现有低置信模板和 retry_context 不坏 |
| PR-4 | Composer 接入 + 最终答案渲染 | PASS/LOW_CONFID/REJECT 最终答案都不再读取 Executor `user_facing_answer` |
| PR-5 | eval fixtures + 回归测试补齐 | 覆盖伪造 ID、工具名不匹配、excerpt 张冠李戴、hypothesis 写成事实 |

每个切片都应保留当前复杂 Chat 链路可运行。若某个切片失败，优先回滚该切片，不要连带回滚已经稳定的前置切片。

---

## 0I. 为什么这样拆阶段

本 issue 的改造目标不是一次性重写 Chat 诊断链路，而是逐步切断“证据不足但自然语言先下结论”的通道。阶段拆分按风险来源分层：

| 阶段 | 切断的风险 | 为什么不能合并 |
|---|---|---|
| 阶段一 | Executor 提前输出最终诊断话术 | 先移除污染源，否则后面 Verifier/Composer 仍会被旧答案影响 |
| 阶段二 | 伪造 ID、工具名不匹配、非法 schema 等物理级幻觉 | 这类问题不需要 LLM 判断，先用代码低成本拦截 |
| 阶段三 | claim 与证据之间是否可推导 | 这是 Verifier 的语义职责，必须在 Gatekeeper 之后处理 |
| 阶段四 | 最终用户答案夹带未验证事实 | 只有 Verifier 输出稳定后，Composer 才知道哪些材料可用 |
| 阶段五 | 新链路是否真的防住历史幻觉场景 | 等链路完整后再做系统化回归，避免测试绑死临时实现 |

每个阶段的设计都必须满足两个条件：

- 可以独立验证，不依赖后续阶段已经完成。
- 失败时可以独立回滚，不破坏已经归档提交的前置阶段。

因此后续实现时不要把“顺手移除临时 renderer”“顺手扩展 Gatekeeper 规则”“顺手接 Composer”混进阶段三。阶段三只解决 Verifier `claim_checks` 和有效 verdict guardrail。

---

## 1. 设计目标

当前 `executor_evidence_v1` 同时包含结构化诊断材料和自然语言表达字段：

- `diagnosis_summary`
- `user_facing_answer`

这两个字段容易让 Executor 提前进入“总结报告 / 用户表达”模式，并可能把未证实内容写成确认结论。

V2 的目标是让 Executor 只输出结构化诊断材料，不负责最终用户表达。

---

## 2. 输出结构

```json
{
  "answer_version": "executor_evidence_v2",
  "claims": [
    {
      "claim_id": "claim-1",
      "claim_type": "symptom",
      "claim_text": "payment-service 出现请求超时日志。",
      "support_level": "direct",
      "evidence_bindings": [
        {
          "source_type": "tool_trace",
          "source_id": "trace-1",
          "tool_name": "query_logs",
          "source_invocation_ids": [394],
          "evidence_excerpt": "request timeout"
        }
      ]
    }
  ],
  "hypotheses": [
    {
      "hypothesis_text": "连接池压力可能参与了超时问题。",
      "basis": "当前已有超时现象，但缺少连接池 active/idle/pending 指标。",
      "needed_evidence": ["HikariCP active/idle/pending 指标"]
    }
  ],
  "recommended_actions": [
    {
      "action_text": "补充查询连接池 active/idle/pending 指标。",
      "reason": "用于确认连接池是否达到上限。",
      "evidence_bindings": []
    }
  ],
  "missing_info": [
    "缺少连接池指标，无法确认连接池耗尽是根因。"
  ]
}
```

---

## 3. 字段定义

| 字段 | 类型 | 必填 | 定义 |
|---|---|---:|---|
| `answer_version` | string | 是 | 固定为 `executor_evidence_v2` |
| `claims` | array | 是 | 已确认或有明确支撑的事实断言 |
| `hypotheses` | array | 否 | 合理怀疑但未被当前证据确认的方向 |
| `recommended_actions` | array | 否 | 建议补证据、排查或处理动作 |
| `missing_info` | array | 否 | 当前无法确认结论所缺少的证据 |

## 4. claims

```json
{
  "claim_id": "claim-1",
  "claim_type": "symptom",
  "claim_text": "payment-service 出现请求超时日志。",
  "support_level": "direct",
  "evidence_bindings": []
}
```

| 字段 | 类型 | 必填 | 定义 |
|---|---|---:|---|
| `claim_id` | string | 是 | claim 唯一标识 |
| `claim_type` | string | 是 | claim 类型，例如 `symptom` / `root_cause` / `impact` / `risk` |
| `claim_text` | string | 是 | 已确认或有限确认的事实断言 |
| `support_level` | string | 是 | `direct` / `indirect` |
| `evidence_bindings` | array | 是 | 支撑该 claim 的证据绑定，不能为空 |

## 5. evidence_bindings

```json
{
  "source_type": "tool_trace",
  "source_id": "trace-1",
  "tool_name": "query_logs",
  "source_invocation_ids": [394],
  "evidence_excerpt": "request timeout"
}
```

| 字段 | 类型 | 必填 | 定义 |
|---|---|---:|---|
| `source_type` | string | 是 | 证据来源类型，例如 `tool_trace` |
| `source_id` | string | 否 | evidence block id、trace_ref 或可定位标识；第一版不作为硬校验依据 |
| `tool_name` | string | 是 | 来源工具名 |
| `source_invocation_ids` | array | 是 | 来源 `tool_invocation.id` |
| `evidence_excerpt` | string | 是 | 从工具返回中摘取的原话、指标值、日志片段或关键数据 |

## 6. hypotheses

```json
{
  "hypothesis_text": "连接池压力可能参与了超时问题。",
  "basis": "当前已有超时现象，但缺少连接池 active/idle/pending 指标。",
  "needed_evidence": ["HikariCP active/idle/pending 指标"]
}
```

| 字段 | 类型 | 必填 | 定义 |
|---|---|---:|---|
| `hypothesis_text` | string | 是 | 未证实但值得排查的方向 |
| `basis` | string | 是 | 它基于哪些已知证据，以及为什么仍只是推测 |
| `needed_evidence` | array | 是 | 要确认该假设还缺少的证据 |

## 7. recommended_actions

```json
{
  "action_text": "补充查询连接池 active/idle/pending 指标。",
  "reason": "用于确认连接池是否达到上限。",
  "evidence_bindings": []
}
```

| 字段 | 类型 | 必填 | 定义 |
|---|---|---:|---|
| `action_text` | string | 是 | 建议动作 |
| `reason` | string | 是 | 建议原因 |
| `evidence_bindings` | array | 否 | 建议动作关联的证据绑定，可为空 |

## 8. 移除字段

V2 移除以下字段：

| 字段 | 移除原因 |
|---|---|
| `diagnosis_summary` | 容易让 Executor 提前总结诊断故事 |
| `user_facing_answer` | 容易夹带 claims 之外的确认式事实 |

最终用户答案应由 ChatService 或后续专门渲染阶段基于结构化字段生成。

---

## 9. Gatekeeper 设计

Executor 输出后、Verifier 接收前，增加一层确定性校验：

```text
Executor raw output
  -> parse JSON
  -> Gatekeeper
  -> Verifier payload
```

Gatekeeper 的目标是拦截物理级幻觉，而不是替代 Verifier 做语义判断。

### 9.1 职责边界

| 组件 | 职责 |
|---|---|
| Gatekeeper | schema、引用 ID、工具名、excerpt、黑名单措辞等确定性校验 |
| Verifier | 判断 claim 是否被证据语义支撑、是否说重、是否缺关键证据 |

Gatekeeper 不判断根因是否正确，也不做新的检索。

### 9.2 接入位置

V1 接入位置保持在 `VerifierInputHook` 内，不改 Executor hook，不改 Chat workflow 编排：

```text
parseExecutorOutput(...)
  -> buildVerifierTraceSummary(...)
  -> Gatekeeper.validate(...)
  -> verifierInput.put("gatekeeper_result", ...)
```

`VerifierInputHook` 的职责收敛为：

- 解析 Executor raw output。
- 构造 `executor_output_parse_status`。
- 构造 `tool_trace_summary`。
- 调用 Gatekeeper。
- 组装 Verifier payload。

除 JSON parse 与最小可解析性判断外，`VerifierInputHook` 不再维护独立校验规则。

后续持久化时，将 `gatekeeper_result` 写入：

```text
diagnosis_session.self_evaluation.verifier_evaluation.gatekeeper_result
```

---

## 10. Gatekeeper 规则加载

Gatekeeper 采用“规则代码稳定、规则配置可调”的设计。

```text
Rule Index
  -> Rule Metadata
  -> Rule Implementation
```

### 10.1 索引层

索引层列出所有可用规则名和一句话描述，用于加载、展示和审计。

```yaml
rules:
  - id: schema.executor_v2
    name: Executor V2 Schema
    description: 校验 Executor 输出是否符合 V2 schema
    enabled: true

  - id: evidence.invocation_ref
    name: Invocation Reference Check
    description: 校验 source_invocation_ids 是否属于当前 session 且工具名匹配
    enabled: true

  - id: evidence.excerpt_similarity
    name: Excerpt Similarity Check
    description: 校验 evidence_excerpt 与真实工具输出是否相似
    enabled: true

  - id: claim.hallucination_phrases
    name: Hallucination Phrase Check
    description: 禁止 confirmed claims 使用经验化、推测化措辞
    enabled: true

  - id: claim.evidence_utilization
    name: Evidence Utilization Check
    description: 检查 claim_text 与 evidence_excerpt 的关键词覆盖率
    enabled: false
```

### 10.2 元数据层

元数据层定义规则参数、阈值、严重级别和适用字段。调整阈值或黑名单时只改元数据，不改代码。

```yaml
ruleMetadata:
  schema.executor_v2:
    severity: error
    verdictImpact: low_confid_on_fail
    params:
      requiredFields:
        - answer_version
        - claims
      deprecatedFields:
        - diagnosis_summary
        - user_facing_answer

  evidence.excerpt_similarity:
    severity: error
    verdictImpact: low_confid_on_fail
    params:
      passThreshold: 0.5
      warnThreshold: 0.3
      compareAgainst:
        - output_preview
        - retrieval_details
        - tool_trace_summary

  claim.hallucination_phrases:
    severity: error
    verdictImpact: low_confid_on_fail
    params:
      targetFields:
        - claims[].claim_text
      blacklist:
        - 通常情况下
        - 根据经验
        - 一般来说
        - 我认为
        - 理论上
        - 可能是
        - 推测
      allowInFields:
        - hypotheses[].hypothesis_text
        - hypotheses[].basis

  claim.evidence_utilization:
    severity: warning
    verdictImpact: warn_only
    params:
      minKeywordCoverage: 0.5

  evidence.invocation_ref:
    severity: error
    verdictImpact: reject_on_fail
```

### 10.3 规则实现层

规则实现使用代码中的固定接口。新增全新类型规则需要代码；调整阈值、词表、启用状态不需要改代码。

```text
GatekeeperRule
  id()
  validate(context, metadata)
  -> RuleResult
```

### 10.4 与 VerifierInputHook 原有校验的关系

V2 中，`VerifierInputHook` 原有的结构判断只保留 parse-only 能力：

```text
raw text
  -> sanitized JSON
  -> JsonNode / Map
  -> parse status
```

以下校验统一迁移到 Gatekeeper：

- schema 字段是否完整。
- `answer_version` 是否正确。
- `claims` 是否为空或类型错误。
- `claims[].evidence_bindings` 是否为空。
- `source_invocation_ids` 是否存在。
- `tool_name` 是否匹配。
- `evidence_excerpt` 是否可信。
- 是否出现已移除字段 `diagnosis_summary` / `user_facing_answer`。

这样避免 `VerifierInputHook` 和 Gatekeeper 出现两套规则、两套错误口径。

---

## 11. 推荐规则集

### 11.1 Schema 校验

规则 id：

```text
schema.executor_v2
```

校验内容：

- 输出必须是 JSON object。
- `answer_version` 必须为 `executor_evidence_v2`。
- `claims` 必须存在且为 array。
- `hypotheses`、`recommended_actions`、`missing_info` 缺省时按空数组处理。
- 不允许出现 `diagnosis_summary`。
- 不允许出现 `user_facing_answer`。

Gatekeeper 输出给 Verifier 前应 normalize 结构：

```text
missing hypotheses -> []
missing recommended_actions -> []
missing missing_info -> []
```

也就是说，Verifier 和 Composer 可以假定这三个字段存在且为数组。

### 11.2 Invocation 引用校验

规则 id：

```text
evidence.invocation_ref
```

校验内容：

- `claims[].evidence_bindings` 不能为空。
- `source_invocation_ids` 必须为非空数组。
- 每个 invocation id 必须属于当前 session。
- `tool_name` 必须和对应 `tool_invocation.tool_name` 匹配。
- 不允许引用其它 session 的工具调用。

该规则只检查 `claims[].evidence_bindings`。`recommended_actions[].evidence_bindings` 可以为空，不参与硬失败判定。

### 11.3 Excerpt 相似度校验

规则 id：

```text
evidence.excerpt_similarity
```

校验内容：

- 将 `evidence_excerpt` 与真实工具输出进行相似度比对。
- 可比较来源包括：
  - `tool_invocation.output_preview`
  - `tool_invocation.retrieval_details`
  - `tool_trace_summary.output_summary`

建议阈值：

| 相似度 | 结果 |
|---:|---|
| `>= 0.5` | pass |
| `0.3 - 0.5` | warn |
| `< 0.3` | fail |

如果只是 excerpt 相似度低，第一版判为 `LOW_CONFID` 级风险，不直接 `REJECT`，因为 `output_preview` 可能被截断，`tool_trace_summary` 也可能是摘要。

只有以下情况才进入 `REJECT` 级别：

- invocation id 不存在。
- invocation id 不属于当前 session。
- `tool_name` 与 invocation 的真实工具名不匹配。
- invocation 存在但 excerpt 明显指向另一个服务、错误码或指标值。

### 11.4 幻觉措辞校验

规则 id：

```text
claim.hallucination_phrases
```

校验内容：

- `claims[].claim_text` 不允许出现经验化、推测化措辞。
- `hypotheses` 中允许出现推测措辞。

默认黑名单：

```json
[
  "通常情况下",
  "根据经验",
  "一般来说",
  "可能是",
  "推测",
  "我认为",
  "理论上"
]
```

### 11.5 证据利用率校验

规则 id：

```text
claim.evidence_utilization
```

校验内容：

- 提取 `claim_text` 中的实词。
- 提取 `evidence_excerpt` 中的实词。
- 计算关键词覆盖率。

伪代码：

```python
def check_evidence_utilization(claim_text, excerpt):
    claim_keywords = extract_keywords(claim_text)
    excerpt_keywords = extract_keywords(excerpt)
    overlap = claim_keywords & excerpt_keywords
    utilization = len(overlap) / len(claim_keywords)
    return utilization >= 0.5
```

第一版建议作为 warning，不作为硬拒绝条件。

---

## 12. Gatekeeper 输出

Gatekeeper 第一版只保留必要审计字段。

```json
{
  "gatekeeper_result": {
    "status": "fail",
    "failed_rules": ["evidence.invocation_ref"],
    "warnings": ["evidence.excerpt_similarity"],
    "errors": [
      {
        "rule_id": "evidence.invocation_ref",
        "target": "claims[0].evidence_bindings[0]",
        "message": "source_invocation_ids not found in current session"
      }
    ]
  }
}
```

### 12.1 字段定义

| 字段 | 类型 | 定义 |
|---|---|---|
| `status` | string | `pass` / `warn` / `fail` |
| `failed_rules` | array | 失败规则 id 列表 |
| `warnings` | array | warning 规则 id 列表 |
| `errors` | array | 最小错误明细 |
| `errors[].rule_id` | string | 失败规则 id |
| `errors[].target` | string | 出问题的字段路径 |
| `errors[].message` | string | 人类可读原因 |

### 12.2 总状态计算

```text
任一规则 fail -> gatekeeper status = fail
否则任一规则 warn -> gatekeeper status = warn
否则 gatekeeper status = pass
```

第一版不记录 `version`、`rule_set`、`summary`、`severity`、`details`、`checked_at` 等字段，避免审计结构过重。

Verifier 如需判断 Gatekeeper fail 是否应导致 `REJECT`，使用规则元数据中的 `verdictImpact`，不依赖落库字段。

---

## 13. 审计落点

Gatekeeper 结果需要进入两处：

### 13.1 Verifier payload

```json
{
  "executor_structured_output": {},
  "executor_output_parse_status": {},
  "tool_trace_summary": [],
  "gatekeeper_result": {}
}
```

Verifier 可根据 `gatekeeper_result` 调整判定，尤其是：

- `gatekeeper_result.status=fail` 时，不应输出 `PASS`。
- schema 或 invocation 引用失败时，应倾向 `LOW_CONFID` 或 `REJECT`。

### 13.1.1 parse status 与 schema status 边界

`executor_output_parse_status` 只表示 JSON 解析结果：

| parse status | 含义 |
|---|---|
| `valid` | raw output 可解析为 JSON object |
| `missing` | raw output 为空或不是 JSON |
| `malformed` | raw output 像 JSON 但解析失败 |

schema 合法性不再由 parse status 表达，统一交给 Gatekeeper：

```text
JSON parse valid but schema invalid
  -> executor_output_parse_status.status = valid
  -> gatekeeper_result.status = fail
  -> failed_rules contains schema.executor_v2
```

### 13.2 self_evaluation

持久化位置：

```text
diagnosis_session.self_evaluation.verifier_evaluation.gatekeeper_result
```

审计链路：

```text
executor_raw_output
  -> executor_output_parse_status
  -> gatekeeper_result
  -> verifier_evaluation
  -> final_answer
```

---

## 14. Verifier 输入结构

V2 中 Verifier 以结构化输出为主输入，不再逐字抽取自然语言事实。

```json
{
  "original_query": "用户原始问题",
  "executor_raw_output": "{raw executor output, debug/fallback only}",
  "executor_structured_output": {
    "answer_version": "executor_evidence_v2",
    "claims": [],
    "hypotheses": [],
    "recommended_actions": [],
    "missing_info": []
  },
  "executor_output_parse_status": {
    "status": "valid",
    "detail": "parsed executor evidence contract"
  },
  "tool_trace_summary": [],
  "gatekeeper_result": {
    "status": "pass",
    "failed_rules": [],
    "warnings": [],
    "errors": []
  },
  "retry_context": null
}
```

| 字段 | 用途 |
|---|---|
| `original_query` | 判断结构化诊断是否围绕用户问题 |
| `executor_raw_output` | 原始输出，仅用于 debug/fallback，不作为主校验来源 |
| `executor_structured_output` | Verifier 主校验对象 |
| `executor_output_parse_status` | 判断结构化输出是否可用 |
| `tool_trace_summary` | 证据索引 |
| `gatekeeper_result` | Gatekeeper 物理级校验结果 |
| `retry_context` | 第二轮时判断缺口是否被补足 |

兼容期可以保留旧字段名：

```text
executor_final_answer
```

第一期 payload 可以同时包含 `executor_raw_output` 和 `executor_final_answer`，二者内容相同。`executor_final_answer` 语义上视为 deprecated；Verifier 不应在结构化输出合法时从该字段抽取额外事实。

---

## 15. Verifier 字段使用规则

### 15.1 executor_structured_output

Verifier 主要校验：

- `claims`
- `hypotheses`
- `recommended_actions`
- `missing_info`

重点是 `claims`：

```text
claim_text 是否能由 evidence_bindings 指向的证据合理推出？
support_level 是否说重？
是否引入证据外的新实体、新指标、新错误码或新根因？
```

### 15.2 tool_trace_summary

`tool_trace_summary` 用于判断 evidence binding 是否有语义支撑。

Verifier 不要求 claim 与证据逐字一致，而是判断可推导性：

```text
证据：payment-service CPU 92%，线程数 245
claim：payment-service 当前存在 CPU 使用率过高现象
=> direct_observation

claim：CPU 过高可能导致支付接口超时
=> reasonable_inference

claim：CPU 过高是支付超时的唯一根因
=> overstated
```

### 15.3 gatekeeper_result

Gatekeeper 负责物理合法性，Verifier 消费结果：

```text
status = pass
  -> 正常校验 claims

status = warn
  -> 正常校验 claims，但 rationale 可提及 warning

status = fail
  -> 不允许 PASS
  -> 相关 claim 至少应判 unsupported / external_unknown / contradicted
```

### 15.4 executor_output_parse_status

```text
status = valid
  -> 使用结构化可推导性校验

status = missing / malformed
  -> 不再回退到自然语言逐字抽取
  -> verdict = LOW_CONFID
  -> groundedness_score = 0
```

### 15.5 executor_raw_output

`executor_raw_output` 只用于审计和 debug。

当 `executor_structured_output` 合法时，Verifier 不应从 `executor_raw_output` 中抽取额外事实。

---

## 16. Verifier 输出结构

V2 Verifier 输出从 `facts_checked` 转向 `claim_checks`。

```json
{
  "verdict": "LOW_CONFID",
  "groundedness_score": 0.62,
  "claim_checks": [
    {
      "claim_id": "claim-1",
      "verification": "direct_observation",
      "detail": "query_metrics 显示 CPU 使用率为 92%，可直接支撑 CPU 过高现象。",
      "evidence_refs": [
        {
          "trace_ref": "trace-1",
          "tool_name": "query_metrics",
          "source_invocation_ids": [394],
          "note": "指标摘要包含 CPU=92%"
        }
      ]
    }
  ],
  "hypothesis_checks": [
    {
      "hypothesis_index": 0,
      "verification": "reasonable_hypothesis",
      "detail": "该假设明确标注为未证实，并列出需要补充的证据。"
    }
  ],
  "rationale": "已有证据支持超时现象，但根因仍缺少直接证据。"
}
```

兼容期建议同时保留 `facts_checked`：

- `claim_checks` 作为 V2 主字段。
- `facts_checked` 由 `claim_checks` 映射生成，供现有 Trace Workbench、eval 和降级输出继续使用。
- 待前端和评测全部迁移后，再移除 `facts_checked`。

### 16.1 字段定义

| 字段 | 类型 | 定义 |
|---|---|---|
| `verdict` | string | `PASS` / `LOW_CONFID` / `REJECT` |
| `groundedness_score` | number | 结构化 claim 的证据支撑评分 |
| `claim_checks` | array | 对 `claims` 的可推导性校验结果 |
| `claim_checks[].claim_id` | string | 被校验的 claim id |
| `claim_checks[].verification` | string | 可推导性判定 |
| `claim_checks[].detail` | string | 判定说明 |
| `claim_checks[].evidence_refs` | array | 使用的证据引用 |
| `hypothesis_checks` | array | 对 hypotheses 的边界校验 |
| `hypothesis_checks[].hypothesis_index` | number | hypothesis 数组下标 |
| `hypothesis_checks[].verification` | string | `reasonable_hypothesis` / `unsupported_hypothesis` / `overstated_as_fact` |
| `hypothesis_checks[].detail` | string | 判定说明 |
| `rationale` | string | 总体判定理由 |

### 16.1.1 facts_checked 兼容映射

兼容期内，ChatService 需要从 `claim_checks` 生成旧字段 `facts_checked`。

映射规则：

| `claim_checks[].verification` | `facts_checked[].verification` |
|---|---|
| `direct_observation` | `direct_evidence` |
| `reasonable_inference` | `indirect_support` |
| `overstated` | `indirect_support` |
| `unsupported` | `no_evidence` |
| `external_unknown` | `no_evidence` |
| `contradicted` | `contradicted` |

`facts_checked[].fact` 建议格式：

```text
{claim_id}: {claim_text}
```

`facts_checked[].is_critical` 规则：

```text
claim_type in ["root_cause", "symptom", "impact", "risk"] -> true
其它 -> false
```

`facts_checked[].evidence_refs` 直接复用 `claim_checks[].evidence_refs`。

### 16.2 claim verification 枚举

| verification | 含义 |
|---|---|
| `direct_observation` | 证据直接观测到该事实 |
| `reasonable_inference` | 证据没有逐字说明，但可以合理推出 |
| `overstated` | 有部分依据，但 claim 说得太满 |
| `unsupported` | 证据不足 |
| `external_unknown` | 引入证据外的新服务、数值、错误码、根因等 |
| `contradicted` | 与证据冲突 |

`external_unknown` 需要区分严重程度：

| 场景 | 建议 verdict |
|---|---|
| 引入证据外的核心服务名、订单号、错误码、关键指标值、根因 | `REJECT` |
| 引入非核心背景实体或表达不清 | `LOW_CONFID` |

---

## 17. Verifier 判定矩阵

### PASS

必须同时满足：

- `gatekeeper_result.status != fail`
- 所有核心 claims 均为 `direct_observation` 或 `reasonable_inference`
- 至少一个关键 claim 为 `direct_observation`
- 不存在 `overstated`
- 不存在 `unsupported`
- 不存在 `external_unknown`
- 不存在 `contradicted`

### LOW_CONFID

满足任一条件：

- 存在 `unsupported`
- 存在 `external_unknown`
- 存在 `overstated`
- 所有核心 claims 都只是 `reasonable_inference`
- `executor_output_parse_status.status` 为 `missing` 或 `malformed`
- `gatekeeper_result.status = fail`，但失败不属于严重伪造

### REJECT

满足任一条件：

- 任一核心 claim 为 `contradicted`
- Gatekeeper 发现严重伪造：
  - 编造 `source_invocation_ids`
  - 跨 session 引用
  - `tool_name` 与 invocation 不匹配
  - 使用真实 id 但 excerpt 明显张冠李戴
- Verifier 发现核心 `external_unknown`：
  - 新增证据外服务名
  - 新增证据外订单号
  - 新增证据外错误码
  - 新增证据外关键指标值
  - 新增证据外根因

严重伪造由 Gatekeeper 规则元数据中的 `verdictImpact=reject_on_fail` 定义。

---

## 18. 与 V1 Verifier 的差异

| 项目 | V1 | V2 |
|---|---|---|
| 主校验对象 | `executor_final_answer` 和 structured output | `executor_structured_output` |
| 校验方式 | 从自然语言中抽取 facts 并逐条校验 | 对 claims 做可推导性校验 |
| 原始文本作用 | 事实抽取来源之一 | debug/fallback only |
| 输出字段 | `facts_checked` | `claim_checks` |
| Gatekeeper | 无 | 前置物理级校验 |
| malformed 输出 | 可回退自然语言校验 | 直接 LOW_CONFID |

---

## 19. Composer 设计

Composer 是最终表达层。它不负责诊断，不调用工具，不补充新事实。

```text
Executor structured output
  -> Gatekeeper
  -> Verifier
  -> Composer
  -> final answer
```

### 19.1 职责边界

| 组件 | 职责 |
|---|---|
| Executor | 输出结构化诊断材料 |
| Gatekeeper | 做物理级确定性校验 |
| Verifier | 判断 claims 是否可由证据合理推出 |
| Composer | 将 Verifier 允许输出的材料组织成用户可读中文答案 |

Composer 禁止：

- 调用工具。
- 重新诊断。
- 重新判断根因。
- 新增服务名、订单号、时间、指标值、错误码、根因。
- 把 hypothesis 写成 confirmed claim。
- 把相关性写成因果。

### 19.2 Composer 输入

Composer 输入应由 ChatService 根据 Executor、Gatekeeper、Verifier 的结果过滤得到。

```json
{
  "original_query": "用户原始问题",
  "verdict": "LOW_CONFID",
  "allowed_claims": [
    {
      "claim_id": "claim-1",
      "claim_type": "symptom",
      "claim_text": "订单123支付失败期间出现 ERR_TIMEOUT，请求耗时 5.3 秒。"
    }
  ],
  "allowed_hypotheses": [
    {
      "hypothesis_text": "网关超时阈值可能偏低。",
      "needed_evidence": ["网关超时阈值配置"]
    }
  ],
  "missing_info": [
    "缺少网关侧具体配置参数，无法确认阈值是否过低。"
  ],
  "recommended_actions": [
    {
      "action_text": "检查网关侧超时阈值配置",
      "reason": "当前缺少网关配置参数，需确认阈值是否低于实际请求耗时。"
    }
  ],
  "rationale": "已有证据支持请求超时现象，但根因仍缺少直接证据。"
}
```

| 字段 | 类型 | 定义 |
|---|---|---|
| `original_query` | string | 用户原始问题 |
| `verdict` | string | Verifier verdict |
| `allowed_claims` | array | Verifier 允许作为确认事实输出的 claims |
| `allowed_hypotheses` | array | Verifier 允许作为合理推测输出的 hypotheses |
| `missing_info` | array | 证据缺口 |
| `recommended_actions` | array | 允许输出的建议动作 |
| `rationale` | string | Verifier 总体判定理由 |

Composer 不应接收 raw tool output，也不应接收未经筛选的完整 Executor 输出。

### 19.2.1 Composer 输入组装规则

ChatService 根据 Verifier 输出组装 Composer 输入：

| Verifier 结果 | Composer 输入 |
|---|---|
| `claim_checks[].verification = direct_observation` | 放入 `allowed_claims` |
| `claim_checks[].verification = reasonable_inference` | 可放入 `allowed_claims`，但表达时不得写成唯一根因 |
| `claim_checks[].verification = overstated` | 不放入 `allowed_claims`，可降级为 `allowed_hypotheses` 或 `missing_info` |
| `claim_checks[].verification = unsupported` | 不输出为事实，放入 `missing_info` |
| `claim_checks[].verification = external_unknown` | 不输出，必要时放入 `missing_info` |
| `claim_checks[].verification = contradicted` | 不输出，触发 `REJECT` 降级表达 |

`allowed_hypotheses` 只允许来自：

- 原始 `hypotheses`。
- `hypothesis_checks` 判为 `reasonable_hypothesis` 的条目。
- 被 Verifier 判为 `overstated` 后降级的 claim。

Composer 执行条件：

```text
Verifier 输出有效 verdict 后才执行 Composer。
executor_output_parse_status = missing/malformed 时，可跳过 Composer，直接使用固定低置信模板。
gatekeeper_result.status = fail 且 verdict = REJECT 时，Composer 只能接收 allowed_claims、missing_info、recommended_actions，不接收 allowed_hypotheses。
```

REJECT 场景下：

- `allowed_hypotheses` 必须为空。
- `user_facing_answer` 不得出现根因结论。
- 推荐动作只能是补证据或人工复核类动作。

### 19.3 Composer 输出

Composer 输出严格 JSON。

```json
{
  "answer_summary": "当前已确认订单123支付失败期间出现 ERR_TIMEOUT，请求耗时 5.3 秒；网关阈值是否过低尚未确认。",
  "recommended_actions": [
    {
      "action_text": "检查网关侧超时阈值配置",
      "reason": "当前缺少网关配置参数，需确认阈值是否低于实际请求耗时。"
    }
  ],
  "user_facing_answer": "您的订单123在支付失败期间出现了请求超时，记录显示 ERR_TIMEOUT，耗时约 5.3 秒。目前还不能确认网关阈值配置就是根因，因为缺少网关侧具体配置参数。建议下一步检查网关超时阈值，并与该请求耗时进行比对。"
}
```

| 字段 | 类型 | 定义 |
|---|---|---|
| `answer_summary` | string | 一句话摘要，只能总结 Verifier 允许输出的内容 |
| `recommended_actions` | array | 面向用户的建议动作 |
| `recommended_actions[].action_text` | string | 建议动作 |
| `recommended_actions[].reason` | string | 建议原因 |
| `user_facing_answer` | string | 最终面向用户的中文答案 |

### 19.4 Verdict 表达规则

#### PASS

- 可以表达确认结论。
- 只能使用 `allowed_claims` 和 `recommended_actions`。
- 只有当 `allowed_claims` 中存在 root cause 类型 claim 时，才能使用“根因已确认”类表述。

#### LOW_CONFID

- 必须说明当前证据仍有缺口。
- 必须区分“已确认信息”和“可能方向”。
- 不得把 `allowed_hypotheses` 写成确认结论。
- 必须包含至少一个证据缺口或下一步建议。

#### REJECT

- 必须说明当前无法基于已获取证据生成可靠结论。
- 不得输出根因结论。
- 只输出已确认信息和下一步建议。

### 19.5 Composer Prompt 草案

```text
你是 Answer Composer。你的职责是把 Verifier 允许输出的结构化材料，组织成用户可读的中文答案。

边界：
- 你不负责诊断。
- 你不调用工具。
- 你不补充新事实。
- 你不重新判断根因。
- 你只能使用输入中的 allowed_claims、allowed_hypotheses、missing_info、recommended_actions、rationale。

输入字段：
- original_query：用户原始问题
- verdict：PASS / LOW_CONFID / REJECT
- allowed_claims：允许作为确认事实输出的结论
- allowed_hypotheses：允许作为合理推测输出的内容
- missing_info：证据缺口
- recommended_actions：建议动作
- rationale：Verifier 判定理由

表达规则：
1. 如果 verdict=PASS：
   - 可以表达确认结论。
   - 只能使用 allowed_claims 和 recommended_actions。
2. 如果 verdict=LOW_CONFID：
   - 必须说明当前证据仍有缺口。
   - 必须区分“已确认”和“可能方向”。
   - 不得把 allowed_hypotheses 写成确认结论。
3. 如果 verdict=REJECT：
   - 必须说明当前无法基于已获取证据生成可靠结论。
   - 不得输出根因结论。
   - 只输出已确认信息和下一步建议。

禁止：
- 禁止新增输入中不存在的服务名、订单号、时间、指标值、错误码、根因。
- 禁止把相关性写成因果。
- 禁止把假设写成事实。
- 禁止输出 Markdown。
- 禁止输出 JSON 之外的任何文字。

输出格式：
{
  "answer_summary": "...",
  "recommended_actions": [
    {
      "action_text": "...",
      "reason": "..."
    }
  ],
  "user_facing_answer": "..."
}
```

---

## 20. 代码影响面

本 issue 按当前三 Agent 实现增量落地，不改 Planner，不引入 Controller。本节描述整体改造影响面；已完成阶段见 `21. 实施阶段`，当前下一步以阶段四 Composer 为准。

| 模块 | 当前职责 | 本次改动 |
|---|---|---|
| `chat-planner-prompt.md` | 选择 skill、拆解计划 | 不改 |
| `chat-executor-prompt.md` | 执行工具并输出 `executor_evidence_v1` | 改为输出 `executor_evidence_v2`，移除最终表达字段 |
| `VerifierInputHook` | 解析 Executor 输出、构造 Verifier payload | 收敛为 parse + trace summary + Gatekeeper + payload |
| `ToolTraceSummaryService` | 从 `tool_invocation` 汇总证据索引 | 原则上不改；只有 Gatekeeper 缺少比对字段时才补最小字段 |
| `chat-verifier-prompt.md` | 校验 `executor_final_answer` 与证据 | 改为校验 `executor_structured_output.claims` 的可推导性 |
| `ChatService.parseVerifierDecision(...)` | 解析 `facts_checked` | 增加 `claim_checks` 解析和 `facts_checked` 兼容生成 |
| `ChatService.persistVerifierEvaluation(...)` | 写入 verifier 审计结果 | 增加 `gatekeeper_result`、`claim_checks`、Composer 结果 |
| `ChatService` 最终答案渲染 | PASS 使用 `user_facing_answer`，LOW_CONFID/REJECT 用模板 | 改为由 Composer 或固定降级模板生成最终答案 |

第一版落地原则：

- Planner 不改。
- Gatekeeper 仍放在 Verifier 的 hook，即 `VerifierInputHook`。
- `VerifierInputHook` 原有结构校验迁移到 Gatekeeper，hook 自身只保留 JSON parse。
- 兼容期保留 `executor_final_answer`，但只作为 raw debug 字段。
- 兼容期保留 `facts_checked`，但由 `claim_checks` 映射生成。

---

## 21. 实施阶段

每个阶段都必须作为独立 OpenSpec change 落地。后续 agent 不应直接从本节复制代码实现，而应把本节转成该阶段的 `proposal.md`、`design.md`、`spec.md` 和 `tasks.md`。

### 阶段一：Executor V2 输出契约

状态：已完成并归档。

已完成记录：

- OpenSpec archive：`openspec/changes/archive/2026-07-07-executor-v2-output-contract`
- devflow：`devflow/projects/2026-07-07-executor-v2-output-contract`
- commit：`050cbc8 feat(agent): add executor evidence v2 contract`

目标：先让 Executor 不再输出最终诊断话术，只输出结构化诊断材料。

改动范围：

- 更新 `chat-executor-prompt.md`。
- `answer_version` 从 `executor_evidence_v1` 改为 `executor_evidence_v2`。
- 移除 `diagnosis_summary` 和 `user_facing_answer`。
- 保留 `claims`、`hypotheses`、`recommended_actions`、`missing_info` 的整体形状。

验收标准：

- Executor 示例输出可被 JSON 解析。
- 输出中不再出现 `diagnosis_summary`、`user_facing_answer`。
- `claims[].evidence_bindings` 仍要求非空。
- 现有流程即使尚未接入 Composer，也不会把 Executor raw JSON 直接当最终答案泄露给用户。

已知阶段性债务：

- `ChatService` 仍有临时 V2 renderer，用于 Composer 上线前避免 raw JSON 外泄。
- Composer 上线后需要移除或降级阶段一临时 V2 renderer，避免 PASS 答案继续绕过 Composer。

### 阶段二：Gatekeeper 接入 VerifierInputHook

状态：已完成并归档。

已完成记录：

- OpenSpec archive：`openspec/changes/archive/2026-07-07-executor-gatekeeper-hook`
- devflow：`devflow/projects/2026-07-07-executor-gatekeeper-hook`
- commit：`c5e496e feat(agent): add executor gatekeeper hook`

目标：在 Verifier 之前用确定性规则拦截物理级幻觉。

改动范围：

- 新增 Gatekeeper 校验服务，第一版先覆盖必要规则。
- 在 `VerifierInputHook` 中调用 Gatekeeper。
- 将 `gatekeeper_result` 写入 Verifier payload。
- 将 `gatekeeper_result` 持久化到 `self_evaluation.verifier_evaluation`。
- 更新 `chat-verifier-prompt.md`，明确 Gatekeeper fail 时不得 PASS。

第一版规则范围：

| 规则 | 必须实现 | 说明 |
|---|---:|---|
| `schema.executor_v2` | 是 | 校验 V2 基础字段、移除字段、数组字段 |
| `evidence.invocation_ref` | 是 | 校验 invocation id 存在于当前 session 且工具名匹配 |
| `evidence.excerpt_similarity` | 否 | 可作为后续阶段或 warn-only 增强 |
| `claim.hallucination_phrases` | 否 | 可作为后续配置化规则增强 |
| `claim.evidence_utilization` | 否 | 第一版不建议硬启用，避免中文分词误杀 |

验收标准：

- JSON parse 成功但 schema 不合法时，`executor_output_parse_status.status=valid`，`gatekeeper_result.status=fail`。
- 编造不存在的 `source_invocation_ids` 时，`failed_rules` 包含 `evidence.invocation_ref`。
- `tool_name` 与真实 invocation 不匹配时，Gatekeeper fail。
- 缺省 `hypotheses`、`recommended_actions`、`missing_info` 时，传给 Verifier 前会 normalize 为 `[]`。
- 旧的 `VerifierInputHook` 结构校验不再和 Gatekeeper 重复维护。
- `diagnosis_session.self_evaluation.verifier_evaluation.gatekeeper_result` 可回溯到本轮校验结果。

建议测试：

- `ExecutorGatekeeperServiceTest`
- `VerifierInputHookTest`
- `ChatServiceSequentialAgentTest`

建议验证命令：

```powershell
mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
cmd /c openspec validate --specs
```

阶段退出条件：

- OpenSpec change 已 archive。
- devflow 已回填 brief、evidence、decisions、acceptance。
- 本阶段代码和文档已单独 commit。

### 阶段三：Verifier V2 可推导性校验

状态：已完成并归档。

已完成记录：

- OpenSpec archive：`openspec/changes/archive/2026-07-07-executor-verifier-claim-checks`
- devflow：`devflow/projects/2026-07-07-executor-verifier-claim-checks`
- commit：`1b31e78 feat(agent): add verifier claim checks`

目标：Verifier 不再逐字扫描自然语言，而是校验 claim 是否能由证据合理推出。

改动范围：

- 更新 `chat-verifier-prompt.md`。
- Verifier 主输入改为 `executor_structured_output`。
- 输出新增 `claim_checks`。
- 兼容期继续输出或由代码生成 `facts_checked`。
- `parseVerifierDecision(...)` 能处理 `claim_checks` 和旧 `facts_checked`。

核心设计：

- Verifier 主校验对象是 `executor_structured_output.claims`。
- `executor_raw_output` / `executor_final_answer` 只作为 debug/fallback 字段，不作为新增事实来源。
- Verifier 不要求 claim 与证据逐字一致，而是判断是否可以合理推出。
- Gatekeeper fail 时，Verifier 不允许输出 `PASS`。

验收标准：

- `direct_observation`、`reasonable_inference`、`overstated`、`unsupported`、`external_unknown`、`contradicted` 均有测试覆盖。
- `gatekeeper_result.status=fail` 时 Verifier 不允许输出 `PASS`。
- malformed/missing Executor 输出不回退自然语言抽事实，直接进入 `LOW_CONFID`。
- `facts_checked` 兼容字段能继续支撑现有低置信模板、retry_context 和评测用例。

建议测试重点：

- `parseVerifierDecision(...)` 能解析 `claim_checks`。
- `facts_checked` 能从 `claim_checks` 兼容映射。
- `gatekeeper_result.status=fail` + Verifier 返回 PASS 时，代码侧应降级或测试 prompt 禁止该行为。
- `unsupported` / `overstated` 能进入低置信模板需要的 missing evidence 语义。

建议验证命令：

```powershell
mvn "-Dtest=ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
cmd /c openspec validate --specs
```

阶段退出条件：

- Verifier prompt 已不再要求逐字扫描最终自然语言答案。
- 审计中同时可见 `claim_checks` 和兼容 `facts_checked`。
- 现有低置信重试链路不回归。
- OpenSpec change 已 archive。
- devflow 已回填 brief、evidence、decisions、acceptance。
- 本阶段代码和文档已单独 commit。

### 阶段四：Composer 输出最终答案

状态：下一阶段，待启动。

建议 OpenSpec change：

```text
openspec/changes/executor-composer-final-answer
```

目标：把最终用户表达从 Executor 中移出，由 Composer 基于 Verifier 允许的材料生成。

改动范围：

- 新增 `chat-composer-prompt.md` 或等价 Composer 调用。
- ChatService 在 Verifier 之后组装 Composer 输入。
- Composer 只接收 `allowed_claims`、`allowed_hypotheses`、`missing_info`、`recommended_actions`、`rationale`。
- PASS/LOW_CONFID/REJECT 均不再读取 Executor 的 `user_facing_answer`。

核心设计：

- Composer 是表达层，不是诊断层。
- Composer 不接收 raw tool output。
- Composer 不接收未经筛选的完整 Executor output。
- ChatService 负责根据 `claim_checks` 过滤出 `allowed_claims`。
- `overstated` claim 不得作为确认事实输出，可降级为 hypothesis 或 missing_info。

建议 OpenSpec 内容：

- `proposal.md`：说明为什么需要 Composer，重点写清“最终表达不能再读 Executor 输出”。
- `design.md`：说明 Composer 输入过滤、输出解析、malformed fallback、审计落点。
- `specs/.../spec.md`：补充 Composer 最终答案的行为场景，能力归属可沿用现有 `chat-verifier-agent` 或新增更合适的 capability，但必须保持命名清晰。
- `tasks.md`：按 prompt、ChatService 组装、输出解析、审计、测试、归档拆任务。
- `decisions.md`：记录 PASS/LOW_CONFID/REJECT 的降级策略和 Composer 失败 fallback。

建议代码入口：

- `src/main/resources/prompts/chat-composer-prompt.md`
- `src/main/java/com/superbiz/agent/service/ChatService.java`
- `src/test/java/com/superbiz/agent/service/ChatServiceSequentialAgentTest.java`
- 如需要新增专门测试，可新增 Composer 输入过滤或输出解析的 focused test。

验收标准：

- Composer 输出严格 JSON，包含 `answer_summary`、`recommended_actions`、`user_facing_answer`。
- Composer 不接收 raw tool output。
- `REJECT` 时 `allowed_hypotheses=[]`，最终答案不出现根因结论。
- `LOW_CONFID` 时必须区分已确认信息和可能方向。
- `PASS` 时只有存在 root cause 类型 allowed claim，才允许表达“根因已确认”。
- `ChatService` 不再依赖临时 V2 renderer 生成 PASS 用户答案。

建议测试重点：

- Composer 输入不包含 raw tool output。
- 未通过 Verifier 的 claim 不进入最终答案。
- `LOW_CONFID` 能输出已确认信息、缺口、下一步建议。
- `REJECT` 不输出 root cause 结论。
- Composer malformed 输出时有降级策略，不向用户泄露 raw JSON。

建议验证命令：

```powershell
mvn "-Dtest=ChatServiceSequentialAgentTest" test
cmd /c openspec validate executor-composer-final-answer
cmd /c openspec validate --specs
```

阶段退出条件：

- 最终用户答案唯一来源是 Composer 或固定降级模板。
- Executor 的 `user_facing_answer` 不再参与任何最终答案路径。
- Stage 1 的临时 renderer 被移除或明确只作为关闭 Composer 时的安全降级，不恢复 Executor 表达。
- OpenSpec change 已 archive。
- devflow 已回填 brief、evidence、decisions、acceptance。
- 本阶段代码和文档已单独 commit。

### 阶段五：回归评测与审计闭环

状态：未开始。

目标：确认新链路真的降低证据归因幻觉，而不是只改变字段名。

改动范围：

- 扩展 `VerifierInputHookTest`。
- 扩展 `ChatServiceSequentialAgentTest`。
- 增加诊断 eval fixtures，覆盖伪造 ID、张冠李戴、过度推断、缺证据降级。
- 检查 `diagnosis_session.self_evaluation` 中的审计字段。

验收标准：

- 伪造 invocation id 必须进入 `REJECT` 或至少不可 `PASS`。
- excerpt 相似度不足但 invocation 合法时，默认进入 `LOW_CONFID`，不直接误杀为严重伪造。
- Executor 把 hypothesis 写进 claim 时，Verifier 至少判 `overstated` 或 `unsupported`。
- 最终答案中不再出现未通过 Verifier 的 claim。
- 审计链路能从 final answer 回溯到 Composer 输入、Verifier 判定、Gatekeeper 结果、tool invocation。

建议 fixture 场景：

| 场景 | 预期 |
|---|---|
| 伪造不存在的 invocation id | Gatekeeper fail，最终不可 PASS |
| 引用真实 id 但 tool_name 不匹配 | Gatekeeper fail，倾向 REJECT |
| excerpt 与真实工具输出明显不符 | Gatekeeper fail 或 warn，最终不可 PASS |
| hypothesis 写成 root_cause claim | Verifier 判 `overstated` 或 `unsupported` |
| Composer 输入不含某错误码但输出包含该错误码 | 测试失败 |

阶段退出条件：

- 关键回归测试已进入 CI 可运行测试集合。
- eval fixture 覆盖证据归因幻觉的主路径。
- 文档、OpenSpec、devflow 与实际代码行为一致。

---

## 22. 兼容与回滚策略

### 22.1 兼容字段

第一版保留以下兼容字段，降低一次性改动风险：

| 字段 | 保留原因 | 后续处理 |
|---|---|---|
| `executor_final_answer` | 当前 Verifier payload、fallback、日志中仍使用该名称 | 作为 deprecated raw 字段保留一版 |
| `facts_checked` | 当前低置信模板、retry_context、评测可能依赖 | 从 `claim_checks` 映射生成 |
| `traceability_version` | 当前审计结构已有字段 | V2 可改为 `v2`，但不作为功能判断依据 |

### 22.2 回滚开关

建议保留最小运行时开关：

```text
structuredOutputV2.enabled
gatekeeper.enabled
composer.enabled
```

回滚策略：

- 仅 Executor V2 出问题：关闭 `structuredOutputV2.enabled`，回到 V1 prompt。
- Gatekeeper 误杀：关闭 `gatekeeper.enabled`，Verifier 仍可按 V2 claim 校验运行。
- Composer 输出异常：关闭 `composer.enabled`，回到固定 LOW_CONFID/REJECT 模板；PASS 暂不直接使用 Executor 输出。

即使回滚 Composer，也不能恢复使用 Executor 的 `user_facing_answer`，否则会重新引入本 issue 要解决的问题。

---

## 23. 数据库与审计最小字段

不新增表，第一版继续写入 `diagnosis_session.self_evaluation`。

建议结构：

```json
{
  "verifier_evaluation": {
    "verdict": "LOW_CONFID",
    "groundedness_score": 0.62,
    "critical_fact_count": 1,
    "claim_checks": [],
    "facts_checked": [],
    "rationale": "...",
    "round": 1,
    "traceability_version": "v2",
    "executor_output_parse_status": {},
    "executor_structured_output": {},
    "tool_trace_summary": [],
    "gatekeeper_result": {},
    "composer_output": {}
  }
}
```

字段控制原则：

- Gatekeeper 只落 `status`、`failed_rules`、`warnings`、`errors`。
- 不在数据库中保存规则元数据完整快照。
- 不新增 `checked_at`、`rule_set_version`、`details` 等重字段。
- 如果后续需要复盘规则版本，再单独设计审计版本字段。

---

## 24. 实施前待确认点

以下问题不阻塞第一阶段，但实施前需要明确默认答案：

| 问题 | 建议默认 |
|---|---|
| Composer 是第四个 Agent 还是普通服务调用？ | 作为 `chat_composer` Agent，但由 ChatService 在 Verifier 后过滤输入再调用 |
| `schema.executor_v2` 失败是否 REJECT？ | 第一版 `LOW_CONFID`，因为它可能是格式退化，不一定是伪造 |
| `evidence.excerpt_similarity` 失败是否 REJECT？ | 默认 `LOW_CONFID`；只有明显张冠李戴才 REJECT |
| `claim.evidence_utilization` 是否启用？ | 第一版禁用或 warn-only，避免中文分词误杀 |
| 是否改 Planner？ | 不改 |
| 是否改现有重试机制？ | 不改；Gatekeeper 失败第一版不触发自动回退重试 |

---

## 25. Definition of Done

本 issue 完成时，需要同时满足：

- Executor 不再输出 `diagnosis_summary` 和 `user_facing_answer`。
- Gatekeeper 已接入 `VerifierInputHook`，并进入 Verifier payload 与 `self_evaluation`。
- Verifier 以 `claim_checks` 为主输出，并保留 `facts_checked` 兼容。
- Composer 负责最终 `user_facing_answer`。
- PASS 答案不包含未通过 Verifier 的 claim。
- LOW_CONFID/REJECT 答案不泄露 Executor 原始结论。
- 关键回归测试覆盖伪造 ID、工具名不匹配、excerpt 张冠李戴、hypothesis 写成事实、schema 退化。