docs(architecture): align evidence pipeline design

mvp/architecture/harness-quality-gates.md

@@ -1,7 +1,7 @@
 # Harness 与质量门禁架构
 
-**更新日期**：2026-07-05  
-**状态**：当前可运行架构 + 后续门禁规划  
+**更新日期**：2026-07-08
+**状态**：当前可运行架构 + 后续门禁规划
 **参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`
 
 ## 1. 设计目标
@@ -21,6 +21,7 @@ Prompt contract
   + Tool boundary
   + Agent hooks
   + Trace persistence
+  + Gatekeeper deterministic validation
   + Verifier / rule evaluation
   + Eval baseline
 ```
@@ -30,15 +31,19 @@ Prompt contract
 ```mermaid
 flowchart TB
     Input["User / AIOps input"] --> Prompt["Prompt contract"]
-    Prompt --> Agent["Planner / Executor / Verifier"]
+    Prompt --> Agent["Planner / Executor / Verifier / Composer"]
     Agent --> Tools["Evidence tools"]
     Tools --> Invocation["tool_invocation"]
     Agent --> StepHook["AgentLoggingHook"]
     StepHook --> Step["agent_step"]
     Agent --> Session["diagnosis_session"]
 
+    Invocation --> EvidenceRefs["retrieval_details.evidence_refs"]
+    EvidenceRefs --> Gatekeeper["ExecutorGatekeeperService"]
+    Agent --> Gatekeeper
     Invocation --> TraceSummary["ToolTraceSummaryService"]
-    TraceSummary --> Verifier["chat_verifier"]
+    Gatekeeper --> Verifier["chat_verifier"]
+    TraceSummary --> Verifier
     Verifier --> SelfEval["self_evaluation.verifier_evaluation"]
 
     Invocation --> AiOpsRule["AiOpsRuleEvaluationService"]
@@ -63,15 +68,18 @@ flowchart TB
 | `planner-prompt.md` | AIOps Planner 规划、再规划、输出告警报告 |
 | `executor-prompt.md` | AIOps Executor 按步骤调用工具 |
 | `chat-planner-prompt.md` | Chat 复杂问题规划 |
-| `chat-executor-prompt.md` | Chat 执行工具并形成诊断答复 |
-| `chat-verifier-prompt.md` | 校验 Executor 答案是否被工具证据支撑 |
+| `chat-executor-prompt.md` | Chat 执行工具并输出 `executor_evidence_v2` 微观事实 |
+| `chat-verifier-prompt.md` | 基于 Gatekeeper 已验真的证据判断 claims 是否可推出 |
+| `chat-composer-prompt.md` | 基于 Verifier 允许表达的内容生成最终用户答复 |
 
 Prompt 层当前承担的门禁：
 
 - 禁止凭记忆回答错误码、接口定义、排障步骤。
 - 需要外部信息时必须调用工具。
 - 工具连续失败或返回空结果时，最终报告必须诚实说明。
-- Chat Verifier 不允许做新检索，只能校验已有证据。
+- Chat Executor 不允许在窄范围问题中扩展根因、风险或修复建议。
+- Chat Verifier 不允许做新检索，只能判断已验真证据是否可推出 claims。
+- Chat Composer 不允许补事实，尤其不能把 `$.no_evidence` 表达为“已排除/确认没有”。
 - AIOps payload 模式必须聚焦输入告警。
 
 ## 4. Trace Hooks
@@ -115,6 +123,7 @@ retrieval_layer
 l0_match_count
 l1_match_count
 retrieval_details
+  -> evidence_refs
 relevance_level
 dedup_reason
 duration_ms
@@ -128,23 +137,42 @@ error_message
 - 检索结果归一化为 `PRECISE`、`HIGHLY_RELEVANT`、`REFERENCE`。
 - 同 session 内重复文档会被 `RetrievedDocTracker` 去重。
 - dedup、no evidence、failed 等状态进入 `retrieval_details.evidence_status`。
+- `retrieval_details.evidence_refs` 记录可被 Executor 引用的最小证据文本，格式为 `raw_path + text`。
+- no-hit / no-evidence 工具结果会生成 `raw_path=$.no_evidence` 的负向证据引用，语义仅限“本次查询未检索到匹配证据”。
 
-## 6. Verifier 门禁
+## 6. Gatekeeper 与 Verifier 门禁
 
-Chat Verifier 的输入不是原始工具日志，而是 `ToolTraceSummaryService` 构造的证据索引。
+Chat Verifier 前置一层 Gatekeeper。Gatekeeper 不调用 LLM，只用代码检查 Executor 输出的证据引用是否真实存在。
 
 ```mermaid
 flowchart LR
-    Invocation["tool_invocation"] --> Summary["ToolTraceSummaryService"]
+    Invocation["tool_invocation"] --> EvidenceRefs["retrieval_details.evidence_refs"]
+    ExecutorOutput["executor_evidence_v2"] --> Gatekeeper["ExecutorGatekeeperService"]
+    EvidenceRefs --> Gatekeeper
+    Gatekeeper --> GateResult["gatekeeper_result"]
+    Invocation --> Summary["ToolTraceSummaryService"]
     Summary --> EvidenceIndex["tool_trace_summary"]
-    EvidenceIndex --> Verifier["chat_verifier"]
-    ExecutorAnswer["executor_final_answer"] --> Verifier
+    GateResult --> Verifier["chat_verifier"]
+    ExecutorOutput --> Verifier
+    EvidenceIndex --> Verifier
     Verifier --> Verdict{"verdict"}
-    Verdict -->|PASS| Pass["输出原答案"]
+    Verdict -->|PASS| Composer["chat_composer"]
+    Composer --> Pass["输出最终答复"]
     Verdict -->|LOW_CONFID| Low["补证据或低置信输出"]
     Verdict -->|REJECT| Reject["降级输出"]
 ```
 
+Gatekeeper 检查：
+
+| 检查 | 失败语义 |
+|---|---|
+| `answer_version=executor_evidence_v2` | 非结构化或旧结构输出降为低置信 |
+| `source_invocation_id` 真实存在 | 伪造 ID 直接拒绝 |
+| `tool_name` 与 invocation 对齐 | 张冠李戴直接拒绝 |
+| `raw_path` 存在于 `evidence_refs` | 无中生有直接拒绝 |
+| `evidence_excerpt` 由 `evidence_refs[].text` 支撑 | excerpt 编造或错配直接拒绝 |
+| `negative_observation` 只能引用 `$.no_evidence` | 用正向日志证明“没查到”直接拒绝 |
+
 Verifier 输出：
 
 ```json
@@ -152,17 +180,22 @@ Verifier 输出：
   "verdict": "PASS|LOW_CONFID|REJECT",
   "groundedness_score": 0.8,
   "critical_fact_count": 2,
+  "claim_checks": [],
   "facts_checked": [],
   "rationale": "..."
 }
 ```
 
+Verifier 不再逐字核验 excerpt 真伪；这由 Gatekeeper 完成。Verifier 只回答一个问题：`claim_text` 是否能由已经验真的 `evidence_excerpt` 推导出来。
+
 结果写入：
 
 ```text
 diagnosis_session.self_evaluation.verifier_evaluation
 ```
 
+其中同时持久化 `executor_structured_output`、`gatekeeper_result`、`tool_trace_summary` 和 `composer_output`，用于 Trace 回放。
+
 ## 7. AIOps 规则门禁
 
 AIOps 当前不走 Chat Verifier，而是用 `AiOpsRuleEvaluationService` 做轻量检查。
@@ -197,9 +230,8 @@ diagnosis_session.self_evaluation.aiops_rule_evaluation
 - 工具参数 schema 校验。
 - 同一工具调用次数上限。
 - 工具超时的统一熔断。
-- 报告中的数值与工具返回值自动对齐校验。
+- Gatekeeper 规则三层分离：索引层、元数据层、规则实现层。
 - Prompt 版本记录和回滚。
 - Verifier 对 AIOps 报告的 LLM 级事实校验。
 
 这些应在评测集扩大后逐步加入，避免一次性把诊断流程卡得过死。
-