docs(architecture): align evidence pipeline design

mvp/architecture/agent-orchestration.md

@@ -1,14 +1,14 @@
 # Agent 编排架构
 
-**更新日期**：2026-07-05  
-**状态**：当前可运行架构  
+**更新日期**：2026-07-08
+**状态**：当前可运行架构
 **参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`
 
 ## 1. 设计定位
 
 旧版 Agent 架构把系统描述为 Supervisor、Planner、SubAgent、Verifier 的团队协作。当前 MVP 保留这个核心思想，但实现更收敛：
 
-- Chat 链路使用固定顺序工作流：`Planner -> Executor -> Verifier`。
+- Chat 链路使用固定顺序工作流：`Planner -> Executor -> Gatekeeper -> Verifier -> Composer`。
 - AIOps 链路使用 `SupervisorAgent` 调度 `Planner + Executor`，最终由规则评估器做轻量验证。
 - 当前没有拆分 ExternalApiSubAgent、InternalErrorSubAgent、DatabaseSubAgent；这些作为后续演进方向保留。
 - 证据工具不直接散落在各个 Agent 里，而是通过 Spring AI ToolCallback / `@Tool` 统一暴露。
@@ -23,9 +23,11 @@ flowchart TB
         ChatPlanner --> ChatExecutor["chat_executor"]
         ChatExecutor --> ChatTools["evidence tools"]
         ChatTools --> ChatExecutor
-        ChatExecutor --> ChatVerifier["chat_verifier"]
+        ChatExecutor --> ChatGatekeeper["ExecutorGatekeeperService"]
+        ChatGatekeeper --> ChatVerifier["chat_verifier"]
         ChatVerifier --> ChatDecision{"PASS / LOW_CONFID / REJECT"}
-        ChatDecision --> ChatAnswer["final answer"]
+        ChatDecision --> ChatComposer["chat_composer"]
+        ChatComposer --> ChatAnswer["final answer"]
     end
 
     subgraph AiOps["AIOps diagnosis"]
@@ -49,9 +51,11 @@ flowchart TB
     ChatService --> Session
     ChatPlanner --> Step
     ChatExecutor --> Step
+    ChatGatekeeper --> SelfEval
     ChatVerifier --> Step
     ChatTools --> Invocation
     ChatDecision --> SelfEval
+    ChatComposer --> Step
 
     AiOpsService --> Session
     AiOpsPlanner --> Step
@@ -68,9 +72,13 @@ Chat 复杂诊断采用 `SequentialAgent`，顺序固定：
 chat_planner
   -> chat_executor
       -> lookup_knowledge / query_logs / query_metrics / date_time
+      -> outputs executor_evidence_v2
+  -> VerifierInputHook / ExecutorGatekeeperService
+      -> validates source_invocation_id / raw_path / evidence_excerpt
   -> chat_verifier
-      -> reads tool_trace_summary
-      -> outputs verifier JSON
+      -> judges whether verified evidence can derive claims
+  -> chat_composer
+      -> writes final user-facing answer
 ```
 
 关键行为：
@@ -78,8 +86,10 @@ chat_planner
 | 角色 | 当前职责 | 输出 |
 |---|---|---|
 | `chat_planner` | 拆解问题，注入知识域地图和对话历史，给出排查方向 | `planner_plan` |
-| `chat_executor` | 按计划调用证据工具，组合工具返回形成诊断答复 | `executor_feedback` |
-| `chat_verifier` | 只基于已有证据校验 Executor 答案，不做新检索 | `verifier_output` |
+| `chat_executor` | 按计划调用证据工具，抽取带 `source_invocation_id + raw_path + evidence_excerpt` 的微观事实 | `executor_evidence_v2` |
+| `ExecutorGatekeeperService` | 在 Verifier 前做代码级引用验真，拒绝伪造 ID、错配 raw_path、错配 excerpt | `gatekeeper_result` |
+| `chat_verifier` | 只判断已验真 evidence excerpt 是否能推出 claim，不做新检索 | `verifier_output` |
+| `chat_composer` | 只表达 Verifier 允许输出的 claims、缺口和建议，生成最终用户答复 | `composer_output` |
 
 Chat 链路最多支持两轮验证：
 
@@ -90,7 +100,9 @@ sequenceDiagram
     participant P as chat_planner
     participant E as chat_executor
     participant T as tools
+    participant G as gatekeeper
     participant V as chat_verifier
+    participant M as chat_composer
     participant S as diagnosis_session
 
     C->>P: 原始问题 + history + retry_context
@@ -98,14 +110,18 @@ sequenceDiagram
     C->>E: planner_plan + 上下文
     E->>T: 调用证据工具
     T-->>E: 证据结果
-    E-->>C: executor_feedback
-    C->>V: executor_final_answer + tool_trace_summary
+    E-->>C: executor_evidence_v2
+    C->>G: executor_structured_output + tool_invocation.evidence_refs
+    G-->>C: gatekeeper_result
+    C->>V: executor_structured_output + gatekeeper_result + tool_trace_summary
     V-->>C: PASS / LOW_CONFID / REJECT
     C->>S: 写入 verifier_evaluation
     alt LOW_CONFID 且允许补证据
         C->>P: retry_context: 仅补缺失证据
     else PASS 或 REJECT
-        C-->>S: 保存最终 answer
+        C->>M: allowed_claims + missing_info + recommended_actions
+        M-->>C: composer_output
+        C->>S: 保存 Composer 最终 answer
     end
 ```
 
@@ -113,7 +129,7 @@ sequenceDiagram
 
 | Verdict | 行为 |
 |---|---|
-| `PASS` | 输出 Executor 答案 |
+| `PASS` | 把 Verifier 允许表达的 claims 交给 Composer 输出 |
 | `LOW_CONFID` | 如果分数低于阈值且仍有轮次，构造 `retry_context` 补证据；否则输出低置信提示 |
 | `REJECT` | 输出降级答复，只保留已确认信息和下一步建议 |
 
@@ -177,21 +193,25 @@ flowchart LR
     SkillBody --> Executor
     Executor --> EvidenceTools["lookup_knowledge / logs / metrics"]
     EvidenceTools --> ToolTrace["tool_invocation evidence"]
-    Executor --> Verifier["Verifier"]
+    Executor --> Gatekeeper["Gatekeeper"]
+    Gatekeeper --> Verifier["Verifier"]
     ToolTrace --> Verifier
+    Verifier --> Composer["Composer"]
 ```
 
 | 角色 | Skill 可见性 | 工具权限 |
 |---|---|---|
 | Planner | 只看 skill name / description，并输出 `selected_skill` | 不暴露 `read_skill` |
 | Executor | 读取 Planner 选中的 skill 正文 | 暴露官方 `read_skill` 和证据工具 |
-| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 `tool_trace_summary` |
+| Gatekeeper | 不看 skill catalog，也不读 skill 正文 | 只读取 Executor 输出和 `tool_invocation.retrieval_details.evidence_refs` |
+| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 Gatekeeper 结果、结构化 claims 和 trace summary |
+| Composer | 不看 skill catalog，也不读 skill 正文 | 只读取 Verifier 允许表达的内容 |
 
 ## 7. 与旧版设计的差异
 
 | 旧版设想 | 当前实现 |
 |---|---|
-| Supervisor + Planner + 多个专科 SubAgent + Verifier | Chat: Planner + Executor + Verifier；AIOps: Supervisor + Planner + Executor |
+| Supervisor + Planner + 多个专科 SubAgent + Verifier | Chat: Planner + Executor + Gatekeeper + Verifier + Composer；AIOps: Supervisor + Planner + Executor |
 | ExternalApiSubAgent / InternalErrorSubAgent / DatabaseSubAgent | 暂未拆分，能力通过通用 Executor + 工具 + Prompt 约束实现 |
 | 每个 SubAgent 专属工具集 | 当前 Executor 持有统一证据工具集合 |
 | Verifier 支持 PASS / REVISE / REJECT | 当前 Chat Verifier 输出 PASS / LOW_CONFID / REJECT |