feat(graph): complete stategraph cleanup and acceptance

mvp/architecture/agent-orchestration.md

@@ -1,6 +1,6 @@
 # Agent 编排架构
 
-**更新日期**：2026-07-08
+**更新日期**：2026-07-17
 **状态**：当前可运行架构
 **参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`
 
@@ -8,7 +8,7 @@
 
 旧版 Agent 架构把系统描述为 Supervisor、Planner、SubAgent、Verifier 的团队协作。当前 MVP 保留这个核心思想，但实现更收敛：
 
-- Chat 链路使用固定顺序工作流：`Planner -> Executor -> Gatekeeper -> Verifier -> Composer`。
+- Chat 复杂诊断使用有递归上限的显式 StateGraph；正常路径是 `Planner -> Executor -> Gatekeeper -> Verified Input -> Verifier -> Composer`，条件边负责有限技术重试、一次补证据和安全 Fallback。
 - AIOps 链路使用 `SupervisorAgent` 调度 `Planner + Executor`，最终由规则评估器做轻量验证。
 - 当前没有拆分 ExternalApiSubAgent、InternalErrorSubAgent、DatabaseSubAgent；这些作为后续演进方向保留。
 - 证据工具不直接散落在各个 Agent 里，而是通过 Spring AI ToolCallback / `@Tool` 统一暴露。
@@ -19,15 +19,19 @@
 flowchart TB
     subgraph Chat["Chat diagnosis"]
         ChatIn["POST /api/chat"] --> ChatService["ChatService"]
-        ChatService --> ChatPlanner["chat_planner"]
+        ChatService --> ChatGraph["ChatDiagnosisGraphRuntime / StateGraph"]
+        ChatGraph --> ChatPlanner["Planner Node"]
         ChatPlanner --> ChatExecutor["chat_executor"]
         ChatExecutor --> ChatTools["evidence tools"]
         ChatTools --> ChatExecutor
-        ChatExecutor --> ChatGatekeeper["ExecutorGatekeeperService"]
-        ChatGatekeeper --> ChatVerifier["chat_verifier"]
+        ChatExecutor --> ChatGatekeeper["Gatekeeper Node"]
+        ChatGatekeeper --> VerifiedInput["Verified Input Node"]
+        VerifiedInput --> ChatVerifier["Verifier Node"]
         ChatVerifier --> ChatDecision{"PASS / LOW_CONFID / REJECT"}
-        ChatDecision --> ChatComposer["chat_composer"]
+        ChatDecision --> ChatComposer["Composer Node"]
+        ChatDecision --> ChatFallback["Fallback Node"]
         ChatComposer --> ChatAnswer["final answer"]
+        ChatFallback --> ChatAnswer
     end
 
     subgraph AiOps["AIOps diagnosis"]
@@ -54,6 +58,7 @@ flowchart TB
     ChatPlanner --> Step
     ChatExecutor --> Step
     ChatGatekeeper --> SelfEval
+    ChatGraph --> Run
     ChatVerifier --> Step
     ChatTools --> Invocation
     ChatDecision --> SelfEval
@@ -69,19 +74,13 @@ flowchart TB
 
 ## 3. Chat 编排
 
-Chat 复杂诊断采用 `SequentialAgent`，顺序固定：
+Chat 复杂诊断采用 `ChatDiagnosisGraphRuntime` 编译的 bounded StateGraph。它有一条正常路径和显式条件边，不再依赖固定顺序 Agent 或 Verifier Hook：
 
 ```text
-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
-      -> judges whether verified evidence can derive claims
-  -> chat_composer
-      -> writes final user-facing answer
+START -> PLANNER -> EXECUTOR -> GATEKEEPER -> VERIFIED_INPUT -> VERIFIER -> COMPOSER -> END
+          |             |             |                         |          |
+          + retry       + fallback    + fallback                + retry    + retry/fallback
+                                                               + EVIDENCE_RETRY -> PLANNER (最多一次)
 ```
 
 关键行为：
@@ -90,16 +89,18 @@ chat_planner
 |---|---|---|
 | `chat_planner` | 拆解问题，注入知识域地图和对话历史，给出排查方向 | `planner_plan` |
 | `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` |
+| `GatekeeperNode` / `ExecutorGatekeeperService` | 按当前 `runId` 做代码级引用验真，拒绝伪造 ID、错配 raw_path、错配 excerpt | `gatekeeper_result` |
+| `VerifiedInputNode` | 只投影 Gatekeeper 通过的 claims 与 matched evidence，隔离完整工具 Trace | `verified_executor_output`、`verified_evidence` |
+| `chat_verifier` | 只判断已验真的 evidence excerpt 是否能推出 claim，不做新检索、不读取完整工具 Trace | `verifier_output` |
 | `chat_composer` | 只表达 Verifier 允许输出的 claims、缺口和建议，生成最终用户答复 | `composer_output` |
+| `FallbackNode` | 在不可恢复失败或路由上限触发时生成非空安全答复 | `final_answer`、degraded trace |
 
-Chat 链路最多支持两轮验证：
+Chat Graph 支持有限技术重试，并只允许一次 evidence retry；所有分支最终进入 Composer 或 Fallback：
 
 ```mermaid
 sequenceDiagram
     autonumber
-    participant C as ChatService
+    participant C as ChatService / StateGraph
     participant P as chat_planner
     participant E as chat_executor
     participant T as tools
@@ -114,18 +115,22 @@ sequenceDiagram
     E->>T: 调用证据工具
     T-->>E: 证据结果
     E-->>C: executor_evidence_v2
-    C->>G: executor_structured_output + tool_invocation.evidence_refs
+    C->>G: executor_output + run-owned tool_invocation.evidence_refs
     G-->>C: gatekeeper_result
-    C->>V: executor_structured_output + gatekeeper_result + tool_trace_summary
+    C->>C: VerifiedInputNode projects passed claims/evidence
+    C->>V: verified_executor_output + verified_evidence + gatekeeper_audit
     V-->>C: PASS / LOW_CONFID / REJECT
     C->>R: 写入 verifier_evaluation
-    alt LOW_CONFID 且允许补证据
+    alt LOW_CONFID 且允许一次补证据
         C->>P: retry_context: 仅补缺失证据
-    else PASS 或 REJECT
+    else PASS / LOW_CONFID 可输出
         C->>M: allowed_claims + missing_info + recommended_actions
         M-->>C: composer_output
         C->>R: 保存 Composer 最终 answer
+    else 不可恢复失败
+        C->>R: Fallback 安全答复
     end
+    C->>R: 保存 orchestration_trace(version/transitions/final_node/termination_reason/degraded/evidence_retry_count)
 ```
 
 决策语义：