refactor(trace): enforce run-only diagnosis model

2026-07-20 14:11:34 +08:00
parent 190013c901
commit 4b9cf7c5cc
63 changed files with 583 additions and 909 deletions
@@ -1,6 +1,6 @@
 # MVP 架构文档

-**更新日期**：2026-07-17
+**更新日期**：2026-07-20

 这里是 MVP 当前架构的唯一入口。旧版设计、早期拆解和已经被新实现替代的方案已归档到：

@@ -13,6 +13,7 @@
 | 文档 | 用途 |
 |---|---|
 | [current-mvp-architecture.md](current-mvp-architecture.md) | 当前可运行 MVP 的总体架构、链路、持久化和质量门禁 |
+| [stategraph-runtime-architecture.md](stategraph-runtime-architecture.md) | 最新复杂 Chat StateGraph 运行时权威快照，覆盖 Node 路由、状态边界、Run/Trace 持久化和验收层次 |
 | [interview-one-pager.md](interview-one-pager.md) | 面试一页式架构讲解，包含总图、亮点、取舍和追问回答 |
 | [agent-orchestration.md](agent-orchestration.md) | Agent 编排细节，覆盖 Chat bounded StateGraph、AIOps SupervisorAgent、工具边界 |
 | [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md) | Chat 证据链路当前数据契约，覆盖 Executor V2、Gatekeeper、Verifier、Composer、`evidence_refs` |
@@ -34,15 +35,16 @@ SuperBizAgent MVP 是一个面向故障诊断的可追踪 Agent 系统：复杂
 ## 阅读顺序

 1. 先读 [current-mvp-architecture.md](current-mvp-architecture.md)，理解系统边界和主链路。
-2. 面试前读 [interview-one-pager.md](interview-one-pager.md)，准备 2-5 分钟讲解。
-3. 再读 [agent-orchestration.md](agent-orchestration.md)，理解当前 Agent 如何协作。
-4. 接着读 [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md)，理解 Chat 证据链路的数据结构和验真边界。
-5. 然后读 [harness-quality-gates.md](harness-quality-gates.md)，理解为什么系统可追踪、可验证。
-6. 再读 [rag-architecture.md](rag-architecture.md)，理解当前 RAG 为什么保留显式 `lookup_knowledge`，以及 Spring AI VectorStore 如何接入。
-7. 继续读 [modular-rag-pipeline.md](modular-rag-pipeline.md)，看 `lookup_knowledge` 的模块化落地和 evidence-first contract。
-8. 再读 [rag-eval-closure.md](rag-eval-closure.md)，看 RAG baseline 如何形成质量闭环。
-9. 然后读 [retrieval-observability.md](retrieval-observability.md)，看检索细节和质量回归方式。
-10. 再读 [feedback-architecture.md](feedback-architecture.md)，理解 self_evaluation、用户反馈和案例沉淀。
-11. 按需读 [session-trace-lifecycle.md](session-trace-lifecycle.md)、[knowledge-base-authoring.md](knowledge-base-authoring.md)、[data-model.md](data-model.md)，补齐运行生命周期、知识库维护和数据关系。
-12. 最后读 [evolution-roadmap.md](evolution-roadmap.md)，区分后续演进和当前实现。
-13. 需要追溯旧方案时，再进入 `archive/2026-07-05-legacy/`。
+2. 再读 [stategraph-runtime-architecture.md](stategraph-runtime-architecture.md)，理解复杂 Chat 的真实运行时和路由边界。
+3. 面试前读 [interview-one-pager.md](interview-one-pager.md)，准备 2-5 分钟讲解。
+4. 再读 [agent-orchestration.md](agent-orchestration.md)，理解当前 Agent 如何协作。
+5. 接着读 [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md)，理解 Chat 证据链路的数据结构和验真边界。
+6. 然后读 [harness-quality-gates.md](harness-quality-gates.md)，理解为什么系统可追踪、可验证。
+7. 再读 [rag-architecture.md](rag-architecture.md)，理解当前 RAG 为什么保留显式 `lookup_knowledge`，以及 Spring AI VectorStore 如何接入。
+8. 继续读 [modular-rag-pipeline.md](modular-rag-pipeline.md)，看 `lookup_knowledge` 的模块化落地和 evidence-first contract。
+9. 再读 [rag-eval-closure.md](rag-eval-closure.md)，看 RAG baseline 如何形成质量闭环。
+10. 然后读 [retrieval-observability.md](retrieval-observability.md)，看检索细节和质量回归方式。
+11. 再读 [feedback-architecture.md](feedback-architecture.md)，理解 self_evaluation、用户反馈和案例沉淀。
+12. 按需读 [session-trace-lifecycle.md](session-trace-lifecycle.md)、[knowledge-base-authoring.md](knowledge-base-authoring.md)、[data-model.md](data-model.md)，补齐运行生命周期、知识库维护和数据关系。
+13. 最后读 [evolution-roadmap.md](evolution-roadmap.md)，区分后续演进和当前实现。
+14. 需要追溯旧方案时，再进入 `archive/2026-07-05-legacy/`。
@@ -1,6 +1,6 @@
 # Agent 编排架构

-**更新日期**：2026-07-17
+**更新日期**：2026-07-20
 **状态**：当前可运行架构
 **参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`

@@ -74,7 +74,7 @@ flowchart TB

 ## 3. Chat 编排

-Chat 复杂诊断采用 `ChatDiagnosisGraphRuntime` 编译的 bounded StateGraph。它有一条正常路径和显式条件边，不再依赖固定顺序 Agent 或 Verifier Hook：
+Chat 复杂诊断采用 `ChatDiagnosisGraphRuntime` 执行、`DiagnosisGraphFactory` 编译的 bounded StateGraph。它有一条正常路径和显式条件边，不再依赖固定顺序 Agent 或隐式前置校验：

 ```text
 START -> PLANNER -> EXECUTOR -> GATEKEEPER -> VERIFIED_INPUT -> VERIFIER -> COMPOSER -> END
@@ -139,7 +139,17 @@ sequenceDiagram
 |---|---|
 | `PASS` | 把 Verifier 允许表达的 claims 交给 Composer 输出 |
 | `LOW_CONFID` | 如果分数低于阈值且仍有轮次，构造 `retry_context` 补证据；否则输出低置信提示 |
-| `REJECT` | 输出降级答复，只保留已确认信息和下一步建议 |
+| `REJECT` | Verifier 完成后仍进入 Composer，但 Composer 只能表达允许材料和诊断限制；Gatekeeper REJECT 才直接进入 Fallback |
+
+### 3.1 运行时边界
+
+- 外层 Graph 使用 `runId` 作为 `RunnableConfig.threadId`，metadata 只承载 `sessionId/runId` 等业务身份。
+- `ReactAgentDiagnosisInvoker` 为 nested Agent 创建独立 config，不传播外层 human-feedback、state-update、checkpoint/resume 控制 metadata。
+- Graph State 默认 replace，只有 `orchestration_events` append；事件使用 portable Map，避免 DevTools classloader 的 record identity 问题。
+- Planner、Verifier、Composer 各最多一次技术重试；evidence retry 独立计数且最多一次；Graph recursion limit 为 32。
+- `DiagnosisGraphResultMapper` 负责质量评估，`DiagnosisOrchestrationTraceBuilder` 负责路由摘要，两者分别写入 `self_evaluation` 和 `orchestration_trace`。
+
+完整运行时拓扑、路由表和失败语义见 [stategraph-runtime-architecture.md](stategraph-runtime-architecture.md)。

 ## 4. AIOps 编排

@@ -212,7 +222,7 @@ flowchart LR
 | Planner | 只看 skill name / description，并输出 `selected_skill` | 不暴露 `read_skill` |
 | Executor | 读取 Planner 选中的 skill 正文 | 暴露官方 `read_skill` 和证据工具 |
 | Gatekeeper | 不看 skill catalog，也不读 skill 正文 | 只读取 Executor 输出和 `tool_invocation.retrieval_details.evidence_refs` |
-| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 Gatekeeper 结果、结构化 claims 和 trace summary |
+| Verifier | 不看 skill catalog，也不读 skill 正文 | 只读取 Verified Input 投影和 Gatekeeper audit |
 | Composer | 不看 skill catalog，也不读 skill 正文 | 只读取 Verifier 允许表达的内容 |

 ## 7. 与旧版设计的差异
@@ -1,6 +1,6 @@
 # 当前 MVP 架构

-**更新日期**：2026-07-17
+**更新日期**：2026-07-20
 **状态**：当前可运行架构
 **适用范围**：Demo、面试讲解、后续迭代规划

@@ -96,8 +96,8 @@ flowchart TB
    RAG --> Store
    Tools --> Invocation
    Agent --> Step
-    App --> Session
-    TraceService --> Session
+    App --> ChatSession
+    TraceService --> ChatSession
    TraceService --> Step
    TraceService --> Invocation
 ```
@@ -167,7 +167,8 @@ sequenceDiagram
    participant Planner as Planner Agent
    participant Executor as Executor Agent
    participant Tool as Evidence Tools
-    participant Gatekeeper as Gatekeeper Hook
+    participant Gatekeeper as Gatekeeper Node
+    participant Projection as Verified Input Node
    participant Verifier as Verifier Agent
    participant Composer as Composer Agent
    participant DB as Trace Tables
@@ -184,11 +185,12 @@ sequenceDiagram
    Tool-->>Executor: 返回证据
    Executor->>Gatekeeper: 输出 executor_evidence_v2
    Gatekeeper->>DB: 读取 tool_invocation.evidence_refs 并校验引用
-    Gatekeeper->>Verifier: 传入已验真的 claims / excerpts
+    Gatekeeper->>Projection: 输出通过验真的 bindings
+    Projection->>Verifier: 只传入 verified claims / evidence
    Verifier->>DB: 合并 diagnosis_run.self_evaluation.verifier_evaluation
    Verifier->>Composer: 传入 allowed_claims / missing_info / actions
    Composer->>Chat: 生成最终用户答复
-    Chat->>DB: 保存 diagnosis_run.answer
+    Chat->>DB: 保存 answer / self_evaluation / orchestration_trace
    User->>Trace: GET /api/diagnosis/{sessionId}/trace?runId=...
    Trace->>DB: 聚合 run / step / tool
    Trace-->>User: 返回可回放诊断链路
@@ -204,19 +206,21 @@ POST /api/chat
              -> lookup_knowledge
              -> query_logs
              -> query_metrics
-          -> Gatekeeper 校验 Executor 证据引用真实性
-          -> Verifier 判断 claim 是否能由已核验证据推出
+          -> Gatekeeper Node 校验 Executor 证据引用真实性
+          -> Verified Input Node 只投影通过验真的 claims/evidence
+          -> Verifier 判断 claim 是否能由已验真证据推出
          -> Composer 生成最终用户答复
      -> 保存 chat_session metadata
      -> 保存 diagnosis_run
      -> 保存 agent_step.run_id
      -> 保存 tool_invocation.run_id
      -> 合并 diagnosis_run.self_evaluation.verifier_evaluation
+      -> 保存 diagnosis_run.orchestration_trace
 ```

-Chat 链路的质量门禁由三段组成：Gatekeeper 先做代码级引用验真，Verifier 再做 LLM 可推导性判断，Composer 最后控制对用户的表达边界。Gatekeeper、Verifier、Composer 的输出合并到当前 `diagnosis_run.self_evaluation.verifier_evaluation`，Trace API 会展示该验证结果。
+Chat 链路的质量门禁由四段组成：Gatekeeper 先做代码级引用验真，Verified Input 再隔离未通过的 binding，Verifier 做 LLM 可推导性判断，Composer 最后控制对用户的表达边界。结构化质量结果合并到 `diagnosis_run.self_evaluation.verifier_evaluation`；Node 路由、重试和降级摘要独立写入 `diagnosis_run.orchestration_trace`。

-Agent 编排细节见 [agent-orchestration.md](agent-orchestration.md)。
+最新运行时、路由和状态边界见 [stategraph-runtime-architecture.md](stategraph-runtime-architecture.md)，Agent 职责见 [agent-orchestration.md](agent-orchestration.md)。

 关键代码：

@@ -343,6 +347,7 @@ diagnosis_run
  -> run_id / session_id
  -> query / status / agent_flow / answer
  -> self_evaluation
+  -> orchestration_trace
  -> step_count / tool_call_count / duration

 agent_step
@@ -365,7 +370,7 @@ tool_invocation
 说明：

 - 旧的 `diagnosis_record` 已不是当前主模型。
- `diagnosis_session` 已降级为历史兼容和回滚表，新执行写入 `chat_session + diagnosis_run`。
+- 当前运行时只使用 `chat_session + diagnosis_run`，不再映射、读取或写入 `diagnosis_session`。
 - `api_document` 仍用于文档元数据管理。
 - 文档向量内容存放在 Milvus/Zilliz collection 中。

@@ -384,7 +389,7 @@ Trace API 聚合：
 - Agent step 序列。
 - 工具调用和检索细节。
 - Chat Gatekeeper / Verifier / Composer 结果。
- Chat `run.orchestrationTrace` 路由摘要，独立于 self-evaluation 和步骤/工具明细。
+- Chat `run.orchestrationTrace` 路由摘要，解析自 `diagnosis_run.orchestration_trace`，独立于 self-evaluation 和步骤/工具明细。
 - AIOps rule evaluation 结果。

 Trace 是本项目区别于普通问答系统的关键：答案不是孤立文本，而是可以追溯到 Agent 决策、工具调用和证据来源。
@@ -412,7 +417,7 @@ Prompt、StateGraph、Gatekeeper、Verifier、Composer 和评测门禁的完整
 已经完成：

 - Chat 和 AIOps 两条入口链路。
- Chat 复杂诊断已单轨切换到 bounded StateGraph，并持久化 Run-owned `orchestration_trace`。
+- Chat 复杂诊断已单轨切换到 bounded StateGraph，并持久化 Run-owned `orchestration_trace`；Graph event 使用 portable Map，nested ReactAgent config 与外层 checkpoint/resume 控制信息隔离。
 - 显式 `lookup_knowledge` Agent Tool。
 - L0 从最终决策降级为 domain/entity hint。
 - `VectorSearchService` 作为稳定检索门面。
@@ -437,14 +442,16 @@ Prompt、StateGraph、Gatekeeper、Verifier、Composer 和评测门禁的完整
 - VectorStore 写入路径全面迁移。
 - 完整 LLM-based AIOps verifier。

-后续 Agent 拆分、Skill/Playbook、MCP 工具协议化和进程隔离等方向见 [evolution-roadmap.md](evolution-roadmap.md)。
+后续 Agent 拆分、Playbook 版本化增强、MCP 工具协议化和进程隔离等方向见 [evolution-roadmap.md](evolution-roadmap.md)。

 ## 10. 关键代码索引

 | 能力 | 代码 |
 |---|---|
 | Chat 入口与编排 | `ChatController`, `ChatService` |
-| Chat StateGraph | `ChatDiagnosisGraphRuntime`, `DiagnosisGraphFactory`, `DiagnosisRealGraphActionsFactory` |
+| Chat StateGraph runtime | `ChatDiagnosisGraphRuntime`, `DiagnosisGraphFactory`, `DiagnosisGraphRouter`, `DiagnosisGraphState` |
+| Chat Node assembly/config isolation | `DiagnosisRealGraphActionsFactory`, `ReactAgentDiagnosisInvoker` |
+| Graph result/audit mapping | `DiagnosisGraphResultMapper`, `DiagnosisOrchestrationTraceBuilder` |
 | AIOps 入口与编排 | `ChatController.aiOps`, `AiOpsService` |
 | AIOps 规则验证 | `AiOpsRuleEvaluationService` |
 | 知识库工具 | `LookupKnowledgeTool` |
@@ -1,6 +1,6 @@
 # 数据模型总览

-**更新日期**：2026-07-10
+**更新日期**：2026-07-20
 **状态**：当前可运行架构

 ## 1. 定位
@@ -13,7 +13,7 @@
 - 知识库：`api_document`、`knowledge_domain`、Milvus/Zilliz metadata
 - 反馈沉淀：`case_library`

-`diagnosis_session` 仍保留为历史兼容和回滚表，不再是新执行写入的主模型。
+当前运行时只使用 `chat_session + diagnosis_run`；旧 `diagnosis_session` 表不属于当前版本契约。

 ## 2. 总体关系

@@ -44,6 +44,7 @@ erDiagram
        varchar agent_flow
        longtext answer
        json self_evaluation
+        json orchestration_trace
        varchar feedback
    }

@@ -111,6 +112,7 @@ erDiagram
 | `agent_flow` | `CHAT` / `AI_OPS` |
 | `answer` | 本次运行最终答复或告警报告 |
 | `self_evaluation` | 本次运行的 rule/verifier/aiops 自评估容器 |
+| `orchestration_trace` | nullable JSON；复杂 Chat 的 StateGraph 路由摘要，非 StateGraph Run 可为空 |
 | `feedback` | 本次运行的用户反馈 |

 同一个 `sessionId` 可以有多个 `runId`。Trace、反馈、评测和案例沉淀都应优先使用 `runId`，避免多轮同 session 下的数据混合。
@@ -139,7 +141,19 @@ erDiagram

 `$.no_evidence` 只表示“本次工具查询未检索到匹配证据”，不能被解释为“问题不存在”或“根因已排除”。

-## 5. 反馈沉淀模型
+## 5. Run 级审计分层
+
+一次 Run 的可审计信息分为三层，不能互相替代：
+
+| 层次 | 存储 | 语义 |
+|---|---|---|
+| 执行明细 | `agent_step`、`tool_invocation` | 模型步骤、工具输入输出、检索细节和证据事实 |
+| 质量评估 | `diagnosis_run.self_evaluation` | rule/verifier/aiops 判断、Gatekeeper 审计、Prompt 版本和允许输出材料 |
+| 编排摘要 | `diagnosis_run.orchestration_trace` | StateGraph transitions、final node、termination reason、degraded、evidence retry count |
+
+`orchestration_trace` 只通过 exact Run 的 `run.orchestrationTrace` 暴露，Trace 响应不再包含兼容 `session` 投影。Run 状态仍只表达执行生命周期：安全 Fallback 是 `SUCCESS + degraded=true`，只有无法生成安全响应或未处理失败才是 `FAILED`。
+
+## 6. 反馈沉淀模型

 `useful` 反馈会触发 `CaseLibraryService.createFromRun`。

@@ -148,7 +162,7 @@ erDiagram
 | 字段 | 来源 |
 |---|---|
 | `case_id` | UUID |
-| `diagnosis_id` | 新数据为 `diagnosis_run.run_id`；历史数据可能为 `diagnosis_session.session_id` |
+| `diagnosis_id` | `diagnosis_run.run_id` |
 | `source_type` | `AUTO` |
 | `fault_category` | 当前默认 `GENERAL` |
 | `title` | run query 前 100 字符 |
@@ -156,7 +170,7 @@ erDiagram
 | `solution` | run answer |
 | `created_by` | `system` |

-## 6. self_evaluation 结构
+## 7. self_evaluation 结构

 `diagnosis_run.self_evaluation` 是运行级 JSON 容器：

@@ -170,16 +184,19 @@ erDiagram

 Chat 通常写入 `rule_evaluation` 和 `verifier_evaluation`；AIOps 写入 `aiops_rule_evaluation`。

-## 7. 当前边界和后续
+`orchestration_trace` 不放入该 JSON，避免把答案质量和 Graph 路由混成同一审计维度。
+
+## 8. 当前边界和后续

 当前边界：

 - `chat_session` 只存会话元数据，不存完整正文历史。
 - `diagnosis_run` 存一次运行的长期审计状态。
 - `agent_step.run_id` 和 `tool_invocation.run_id` 是 Trace、Verifier、Eval 的运行边界。
+- `diagnosis_run.orchestration_trace` 是 nullable Run-owned Graph 摘要；非 StateGraph Run 可以为空。
 - 当前实现主要使用逻辑关联，不依赖数据库外键。
 - `case_library.diagnosis_id` 是过渡字段，新值按 `run_id` 解释，旧值可能按 `session_id` 解释。
- `diagnosis_session` 只作为历史兼容和回滚表保留。
+- 当前 Java 运行时不存在 `diagnosis_session` entity/repository 或 fallback。

 后续可增强：

@@ -1,12 +1,12 @@
 # Agent 架构演进路线

-**更新日期**：2026-07-05  
+**更新日期**：2026-07-20
 **状态**：后续演进设计，不代表当前已实现  
 **参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`

 ## 1. 为什么需要演进路线

-旧版 `agent-architecture.md` 包含很多生产级设想：专科 SubAgent、Skill 体系、进程隔离、回退路由、MCP 工具协议化、进化引擎。它们不应作为当前 MVP 事实写入主架构，但可以作为后续扩展路线。
+旧版 `agent-architecture.md` 包含很多生产级设想：专科 SubAgent、完整 Skill 治理、进程隔离、跨 Agent 回退、MCP 工具协议化、进化引擎。当前已经落地 bounded StateGraph、安全 Fallback 和基础 Skill/Playbook 接入；本文件只描述它们之上的后续增强。

 当前原则：

@@ -18,12 +18,12 @@

 ```mermaid
 flowchart TD
-    MVP["Current MVP: Planner + Executor + Verifier"] --> Split{"Executor 是否过载?"}
+    MVP["Current MVP: bounded StateGraph + evidence gates"] --> Split{"Executor 是否过载?"}
    Split -->|是| SubAgents["专科 SubAgent"]
    Split -->|否| Keep["继续强化通用 Executor"]

-    SubAgents --> Skills["Skill / Playbook 体系"]
-    Skills --> Fallback["回退路由"]
+    SubAgents --> Skills["Skill / Playbook 版本化治理"]
+    Skills --> Fallback["跨 SubAgent 回退路由"]
    Fallback --> Isolation["进程或 Pod 隔离"]

    MVP --> ToolGrowth{"工具数量和来源是否增长?"}
@@ -59,9 +59,9 @@ flowchart TD
 - 过早拆分会增加 Prompt、评测和 trace 分析成本。
 - 没有足够分类评测前，拆分可能只是移动复杂度。

-## 4. Skill / Playbook 体系
+## 4. Skill / Playbook 版本化治理

-旧版设计中的 Skill 可以在当前项目中演进为可版本化的诊断 Playbook。
+当前已经通过 Planner metadata selection + Executor `read_skill` 接入诊断 Playbook。下一阶段不是重新建设 Skill 入口，而是增加版本、评测、回退和审计治理。

 ```text
 fault_category
@@ -73,14 +73,14 @@ fault_category
      -> evaluation checks
 ```

-优先落地方向：
+当前已覆盖的方向：

 - AIOps 告警处理 Playbook。
 - 支付超时 Playbook。
 - MySQL 连接池风险 Playbook。
 - Redis timeout Playbook。

-落地前提：
+后续增强前提：

 - 每个 Playbook 至少有 3-5 个 eval case。
 - Playbook 失败时可以回退到通用 Executor。
@@ -423,7 +423,7 @@ Trace API 可用于回放：
 - Composer 最终如何表达给用户。
 - `run.orchestrationTrace` 如何经过条件边、有限重试并终止。

-历史 Run/fixture 的 `verifier_evaluation.tool_trace_summary` 仍可被 Trace UI 或离线评测只读解析，但它是旧链路兼容字段，不是当前 Verifier 输入，也不再由生产链路生成。
+当前版本不生成、读取或展示 `verifier_evaluation.tool_trace_summary`；Verifier 只消费 verified projection。

 ---

@@ -56,7 +56,7 @@ flowchart TD

 ## 3. self_evaluation JSON

-`SelfEvaluationMergeService` 统一维护当前运行的 `diagnosis_run.self_evaluation`。历史兼容数据可能仍存在于 `diagnosis_session.self_evaluation`，但新 Chat/AIOps 执行不再写旧表。
+`SelfEvaluationMergeService` 只维护当前运行的 `diagnosis_run.self_evaluation`，不再解析或写入旧 `diagnosis_session` 数据。

 当前结构：

@@ -89,10 +89,7 @@ flowchart TD
 }
 ```

-兼容逻辑：
-
- 如果旧 JSON 根节点包含 `evidence_score`，会被包进 `rule_evaluation`。
- 如果旧 JSON 根节点包含 `verdict` / `groundedness_score`，会被包进 `verifier_evaluation`。
+输入必须使用当前分层 JSON：`rule_evaluation`、`verifier_evaluation`、`aiops_rule_evaluation`。旧扁平 JSON 不再自动包装。

 ## 4. 规则评分

@@ -175,7 +172,7 @@ ChatService 根据 verdict 决定：

 - `executor_final_answer` 只作为 debug/fallback 上下文；结构化输出有效时，Verifier 不得从中抽取额外确认事实。
 - `$.no_evidence` 只能表达“当前查询未检索到匹配证据”，不能表达“已排除/确认没有”。
- `run.orchestrationTrace` 是独立的 StateGraph 路由摘要，不属于 `self_evaluation`；历史 `tool_trace_summary` 仅用于旧 Run/fixture 只读兼容，不是当前 Verifier 输入。
+- `run.orchestrationTrace` 是独立的 StateGraph 路由摘要，不属于 `self_evaluation`；当前版本不生成或读取 `tool_trace_summary`。

 ## 6. AIOps 规则自评估

@@ -210,7 +207,6 @@ Content-Type: application/json
  "success": true,
  "message": "反馈已记录",
  "runId": "run-xxx",
-  "fallbackToLatestRun": false,
  "caseId": "uuid 或 null"
 }
 ```
@@ -223,11 +219,7 @@ Content-Type: application/json
 | `not_useful` | 写入 `DiagnosisRun.feedback`，不改变 run status |
 | 其他值 | 返回 HTTP 400 |

-兼容行为：
-
- 请求带 `runId` 时，后端验证 `runId` 属于 `sessionId`。
- 请求缺少 `runId` 且存在 run-backed 数据时，后端绑定 latest run，并返回 `fallbackToLatestRun=true` 和实际 `runId`。
- 仅当没有 `diagnosis_run` 但存在历史 `diagnosis_session` 时，才使用历史 fallback；该路径不声明 latest-run fallback。
+新版本要求请求必须携带 `sessionId + runId`。后端验证 `runId` 属于 `sessionId`；缺少 `runId`、Run 不存在或归属错误时直接拒绝，不绑定 latest run，也不回退历史表。

 ## 8. 案例沉淀

@@ -238,7 +230,7 @@ Content-Type: application/json
 | CaseLibrary 字段 | 来源 |
 |---|---|
 | `caseId` | UUID |
-| `diagnosisId` | 新数据为 `DiagnosisRun.runId`；历史数据可能为 `DiagnosisSession.sessionId` |
+| `diagnosisId` | `DiagnosisRun.runId` |
 | `sourceType` | `AUTO` |
 | `faultCategory` | 当前固定为 `GENERAL` |
 | `title` | `query` 前 100 字符 |
@@ -128,7 +128,7 @@ sequenceDiagram
 - token count。
 - Verifier 的 JSON 输出摘要。

-新写入必须带 `run_id`；`session_id` 仍保留用于粗粒度排查和历史兼容。
+新写入必须带 `run_id`；`session_id` 只用于会话归属和粗粒度排查，不能替代 Run 边界。

 ## 5. Tool Invocation 门禁

@@ -218,7 +218,7 @@ Verifier 不再逐字核验 excerpt 真伪；这由 Gatekeeper 完成。Verifier
 diagnosis_run.self_evaluation.verifier_evaluation
 ```

-其中持久化 verified `executor_structured_output`、`verified_evidence`、`gatekeeper_result`、`prompt_audit` 和 `composer_output`，用于 Trace 回放。Graph 路由另存 `diagnosis_run.orchestration_trace`；历史 `tool_trace_summary` 只作为旧 Run/fixture 的读取兼容字段，不属于当前 Verifier 输入。
+其中持久化 verified `executor_structured_output`、`verified_evidence`、`gatekeeper_result`、`prompt_audit` 和 `composer_output`，用于 Trace 回放。Graph 路由另存 `diagnosis_run.orchestration_trace`；当前版本不生成或读取 `tool_trace_summary`。

 ## 7. AIOps 规则门禁

@@ -1,11 +1,12 @@
 # 面试一页式架构讲解

+**更新日期**：2026-07-20
 **用途**：面试现场 2-5 分钟讲清项目  
 **适合场景**：开场介绍、架构追问、Demo 前铺垫

 ## 1. 一句话

-SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：它把用户问题或 AIOps 告警转换成 Planner、Executor、Gatekeeper、Verifier、Composer 的诊断链路，`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行；所有工具证据、模型步骤、最终答案、自评估和用户反馈都能按 `sessionId + runId` 回放。
+SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：复杂 Chat 通过 bounded StateGraph 编排 Planner、Executor、Gatekeeper、Verified Input、Verifier、Composer 和安全 Fallback，`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行；工具证据、模型步骤、Graph 路由、自评估、最终答案和用户反馈都能按 `sessionId + runId` 回放。

 ## 2. 一张图

@@ -16,7 +17,7 @@ flowchart TB
    API --> Chat["ChatService"]
    API --> AiOps["AiOpsService"]

-    Chat --> ChatFlow["Chat: Planner -> Executor -> Gatekeeper -> Verifier -> Composer"]
+    Chat --> ChatFlow["Chat StateGraph: Planner -> Executor -> Gatekeeper -> Verified Input -> Verifier -> Composer/Fallback"]
    AiOps --> AiOpsFlow["AIOps: Supervisor -> Planner / Executor"]

    ChatFlow --> Tools["Evidence Tools"]
@@ -39,10 +40,14 @@ flowchart TB
    Trace --> Step["agent_step"]
    Trace --> Invocation["tool_invocation"]

-    Invocation --> Verifier["Verifier / Rule Evaluation"]
+    Invocation --> Gate["Gatekeeper / Rule Evaluation"]
+    Gate --> Projection["Verified Input"]
+    Projection --> Verifier["Verifier"]
    Verifier --> SelfEval["self_evaluation"]

+    Run --> RouteTrace["orchestration_trace"]
    Run --> TraceAPI["GET /api/diagnosis/{sessionId}/trace?runId=..."]
+    RouteTrace --> TraceAPI
    Step --> TraceAPI
    Invocation --> TraceAPI
    SelfEval --> TraceAPI
@@ -56,21 +61,21 @@ flowchart TB
 ```text
 这个项目不是把问题直接丢给大模型，而是把诊断拆成可审计的执行链路。

-Chat 复杂问题走 Planner -> Executor -> Gatekeeper -> Verifier -> Composer：
-Planner 负责拆解，Executor 只负责调用知识库、日志和指标工具并提炼带证据引用的微观事实；Gatekeeper 用代码核对 invocation、raw_path 和 excerpt 是否真实；Verifier 判断这些事实能否由已验真的证据推出；Composer 只把允许表达的结论写成最终答案。
+Chat 复杂问题走 bounded StateGraph：
+Planner 负责拆解，Executor 调用知识库、日志和指标工具并提炼带证据引用的微观事实；Gatekeeper 用代码核对 invocation、raw_path 和 excerpt 是否真实；Verified Input 只投影通过的 binding；Verifier 判断这些事实能否由已验真的证据推出；Composer 只把允许表达的结论写成最终答案，不可恢复分支由 Fallback 生成安全答复。

 AIOps 告警入口走 Supervisor 调度 Planner/Executor：
 如果请求里有 alert payload，系统会进入 PAYLOAD_TARGETED 模式，报告必须聚焦这个告警，而不是被当前环境中的其他活跃告警带偏。

-会话元数据会落到 chat_session，每次诊断运行会落到 diagnosis_run，步骤和工具明细通过 run_id 关联。
-所以我可以用 sessionId + runId 精确回放：模型怎么规划、调了哪些工具、工具返回什么、Gatekeeper 怎么验真、Verifier 怎么判定、Composer 最后怎么表达、用户最后是否反馈有用。
+会话元数据会落到 chat_session，每次诊断运行会落到 diagnosis_run，步骤和工具明细通过 run_id 关联；证据质量写入 self_evaluation，Graph 路由独立写入 orchestration_trace。
+所以我可以用 sessionId + runId 精确回放：模型怎么规划、调了哪些工具、Gatekeeper 怎么验真、Graph 为什么重试或降级、Verifier 怎么判定、Composer/Fallback 如何结束、用户最后是否反馈有用。
 ```

 ## 4. 五个亮点

 | 亮点 | 怎么讲 |
 |---|---|
-| 可追踪 Agent | 每次诊断都有 `runId`，Trace API 可以回放 run、step、tool；同一 `sessionId` 可有多次独立 run |
+| 可追踪 StateGraph | 每次诊断都有 `runId`，Trace API 可以回放 run、step、tool 和 `run.orchestrationTrace`；同一 `sessionId` 可有多次独立 run |
 | 显式工具证据链 | `lookup_knowledge`、日志、指标都记录到 `tool_invocation` |
 | RAG 工程化 | L0 降级为 hint，Spring AI VectorStore 做主检索，SDK fallback 保底 |
 | 质量门禁 | Chat Gatekeeper 验引用、Verifier 判可推导、Composer 控表达，AIOps rule evaluation 控制告警聚焦 |
@@ -185,7 +185,7 @@ flowchart LR
    Invocation --> Eval["EvaluationService / RAG eval"]
 ```

-旧 Trace/fixture 中的 `tool_trace_summary` 只保留读取兼容；当前 StateGraph 不再生成它，也不会把完整工具调用摘要输入 Verifier。
+当前 StateGraph 不生成或读取 `tool_trace_summary`，也不会把完整工具调用摘要输入 Verifier。

 `tool_invocation` 中与检索相关的字段：

@@ -18,7 +18,7 @@ chat_session(sessionId)
 - `sessionId` 表示多轮会话目录和 Redis 上下文。
 - `runId` 表示一次可回放诊断执行。
 - `DiagnosisTraceService` 聚合一个 run 的主记录、步骤和工具调用，形成可回放 Trace。
- `diagnosis_session` 只保留为历史兼容和回滚表。
+- 运行时不再映射、读取或写入 `diagnosis_session`；数据库中的旧表不属于当前版本契约。

 ## 2. 生命周期总图

@@ -60,8 +60,7 @@ flowchart TD

 - 同一个 `sessionId` 可以贯穿多轮 Chat。
 - 每次有效 Chat/AIOps 执行都会创建新的 `runId`。
- Trace 和 Feedback 新客户端应传 `runId`；只传 `sessionId` 时兼容解析 latest run。
- latest run 排序使用 `diagnosis_run.created_at DESC, id DESC`，不使用 `updated_at`。
+- Trace 和 Feedback 必须同时传 `sessionId + runId`；后端不解析 latest run，也不回退旧表。

 ## 4. 运行状态流转

@@ -137,9 +136,9 @@ diagnosis_run by sessionId + runId
  -> DiagnosisTraceResponse
 ```

-当 `runId` 缺失时，Trace API 为兼容旧客户端解析最新 run，并在响应中返回 resolved `runId`。当 `runId` 属于其他 `sessionId` 时，API 必须拒绝，不能泄漏其他会话的 Trace。
+当 `runId` 缺失时，Trace API 直接拒绝请求。当 `runId` 属于其他 `sessionId` 时，API 同样拒绝，不能泄漏其他会话的 Trace。

-`run.orchestrationTrace` 只属于精确 Run 投影，不复制到顶层或 `session`。它解释 Graph 路由；`selfEvaluation` 解释证据/答案质量；`steps` 和 `toolInvocations` 保存详细执行证据，三者职责互不替代。历史 Run 的该字段可以为空。
+`run.orchestrationTrace` 只属于精确 Run 投影，响应不再提供兼容 `session` 对象。它解释 Graph 路由；`selfEvaluation` 解释证据/答案质量；`steps` 和 `toolInvocations` 保存详细执行证据，三者职责互不替代。非 StateGraph Run 的该字段可以为空。

 ## 8. Chat 与 AIOps 差异

@@ -164,4 +163,4 @@ Chat StateGraph 的权威自动化验收分三层：`DiagnosisGraphWorkflowTest`

 1. Trace API 增加更结构化的 `self_evaluation` 展示。
 2. `agent_step` 与 `tool_invocation.step_id` 建立更严格关联。
-3. 旧 `diagnosis_session` 只读观察期结束后，再评估数据库层面的约束收紧或归档策略。
+3. 数据库中的旧 `diagnosis_session` 表按独立数据治理任务决定是否物理删除；当前应用不再依赖它。
@@ -0,0 +1,199 @@
+# Chat StateGraph 运行时架构
+
+**更新日期**：2026-07-20
+**状态**：当前复杂 Chat 诊断的权威运行时架构
+**适用范围**：`POST /api/chat` 的复杂诊断路径；简单 Chat 和 AIOps 使用各自链路
+
+## 1. 架构定位
+
+复杂 Chat 已单轨切换为 Spring AI Alibaba bounded `StateGraph`。`ChatService` 负责 Run 生命周期和持久化，`ChatDiagnosisGraphRuntime` 负责执行 Graph，`DiagnosisGraphFactory` 负责声明 Node 与条件边，Agent/Java Node 负责各自的语义任务或确定性校验。
+
+```mermaid
+flowchart LR
+    API["POST /api/chat"] --> Chat["ChatService.executeChatComplex"]
+    Chat --> Session["chat_session"]
+    Chat --> Run["diagnosis_run: RUNNING"]
+    Chat --> Actions["DiagnosisRealGraphActionsFactory"]
+    Actions --> Runtime["ChatDiagnosisGraphRuntime"]
+    Runtime --> Factory["DiagnosisGraphFactory"]
+    Factory --> Graph["Compiled StateGraph"]
+
+    Graph --> Planner["PlannerNodeAdapter"]
+    Graph --> Executor["ExecutorNodeAdapter"]
+    Graph --> Gatekeeper["GatekeeperNode"]
+    Graph --> Projection["VerifiedInputNode"]
+    Graph --> Verifier["VerifierNodeAdapter"]
+    Graph --> Retry["EvidenceRetryPrepareNode"]
+    Graph --> Composer["ComposerNodeAdapter"]
+    Graph --> Fallback["FallbackNode"]
+
+    Executor --> Tools["lookup_knowledge / logs / metrics"]
+    Tools --> Invocations["tool_invocation"]
+    Planner --> Steps["agent_step"]
+    Executor --> Steps
+    Verifier --> Steps
+    Composer --> Steps
+
+    Graph --> Mapper["DiagnosisGraphResultMapper"]
+    Graph --> TraceBuilder["DiagnosisOrchestrationTraceBuilder"]
+    Mapper --> SelfEval["diagnosis_run.self_evaluation"]
+    TraceBuilder --> RouteTrace["diagnosis_run.orchestration_trace"]
+    Chat --> RunDone["diagnosis_run: SUCCESS / FAILED"]
+    RunDone --> TraceAPI["exact Run Trace API"]
+    SelfEval --> TraceAPI
+    RouteTrace --> TraceAPI
+    Steps --> TraceAPI
+    Invocations --> TraceAPI
+```
+
+## 2. 运行生命周期
+
+一次复杂 Chat 运行按以下顺序执行：
+
+1. `ChatService` 解析或创建 `sessionId`，生成唯一 `runId`。
+2. 确保 `chat_session` 元数据存在，并创建 `diagnosis_run`，初始状态为 `RUNNING`、`agent_flow=CHAT`。
+3. 构建 Planner、Executor、Verifier、Composer 四个 `ReactAgent`，再由 `DiagnosisRealGraphActionsFactory` 组合 Java Nodes。
+4. `ChatDiagnosisGraphRuntime` 以 `runId` 作为 Graph `threadId`，将 `sessionId/runId` 放入 `RunnableConfig.metadata`。
+5. `DiagnosisGraphFactory` 编译 StateGraph 并执行，Graph recursion limit 固定为 32。
+6. Graph 返回非空 `final_answer` 后，`DiagnosisGraphResultMapper` 生成 verifier evaluation，`DiagnosisOrchestrationTraceBuilder` 压缩路由摘要。
+7. `ChatService` 保存答案、耗时、步骤数、工具数、自评估和编排摘要，将 Run 标记为 `SUCCESS`。
+8. 未处理异常会尽力保存 partial state/partial trace，再将 Run 标记为 `FAILED`；能够生成安全 Fallback 的路径仍是 `SUCCESS`，并通过 `degraded=true` 表达质量降级。
+9. `finally` 清理本轮检索追踪和 session/run ThreadLocal，避免跨 Run 污染。
+
+## 3. Graph 拓扑
+
+```mermaid
+flowchart TD
+    Start([START]) --> Planner[Planner]
+    Planner -->|COMPLETED| Executor[Executor]
+    Planner -->|technical retry once| Planner
+    Planner -->|non-retryable / exhausted| Fallback[Fallback]
+
+    Executor -->|COMPLETED| Gatekeeper[Gatekeeper]
+    Executor -->|INVALID_OUTPUT / TOOL_BLOCKED / FAILED| Fallback
+
+    Gatekeeper -->|PASS| VerifiedInput[Verified Input]
+    Gatekeeper -->|LOW_CONFID + verified bindings| VerifiedInput
+    Gatekeeper -->|REJECT / no verified binding| Fallback
+
+    VerifiedInput --> Verifier[Verifier]
+    Verifier -->|technical retry once| Verifier
+    Verifier -->|LOW_CONFID + critical gap + retry allowed| EvidenceRetry[Evidence Retry]
+    EvidenceRetry -->|EVIDENCE_GAP_ONLY| Planner
+    Verifier -->|completed and no retry| Composer[Composer]
+    Verifier -->|non-retryable / exhausted| Fallback
+
+    Composer -->|COMPLETED| End([END])
+    Composer -->|technical retry once| Composer
+    Composer -->|non-retryable / exhausted| Fallback
+    Fallback --> End
+```
+
+路由规则：
+
+| 节点 | 继续条件 | 重试 | 安全终止 |
+|---|---|---|---|
+| Planner | `COMPLETED` 进入 Executor | `INVALID_OUTPUT` / `RETRYABLE_FAILED` 最多一次技术重试 | `NON_RETRYABLE_FAILED` 或重试耗尽进入 Fallback |
+| Executor | 只有 `COMPLETED` 进入 Gatekeeper | 不做 Graph 技术重试 | 非法输出、工具阻断或执行失败进入 Fallback |
+| Gatekeeper | `PASS`，或 `LOW_CONFID` 且至少一个 verified binding | 不重试 | `REJECT` 或零 verified binding 进入 Fallback |
+| Verifier | 完成后由 `effective_verdict` 决定 Composer 或补证据 | 技术失败最多一次；证据补查最多一次 | 不可重试失败或技术重试耗尽进入 Fallback |
+| Composer | `COMPLETED` 结束 | 技术失败最多一次 | 不可重试失败或重试耗尽进入 Fallback |
+| Fallback | 生成非空确定性安全答复 | 不重试 | 直接结束并标记 `degraded=true` |
+
+Evidence retry 只有同时满足以下条件才发生：
+
+- `evidence_retry_count < 1`。
+- Gatekeeper 给出的 verifier verdict ceiling 仍允许 `PASS`。
+- Verifier 输出包含可提取的 critical evidence gap。
+
+补证据时 Planner 进入 `EVIDENCE_GAP_ONLY`，`planner_retry_count` 重置；Executor 只执行增量查询，但重新输出完整 `executor_evidence_v2` 快照。
+
+## 4. 状态与执行边界
+
+### Graph State
+
+Graph State 只保存跨 Node 的控制信息和结构化结果：
+
+- `diagnosis_context`、`planner_plan`、`executor_output`。
+- `gatekeeper_result`、`verified_executor_output`、`verified_evidence`。
+- `verifier_output`、`composer_output`、`final_answer`。
+- Planner/Verifier/Composer 技术重试计数和 `evidence_retry_count`。
+- `orchestration_events` 有界追加事件。
+
+默认状态键使用 replace strategy，只有 `orchestration_events` 使用 append strategy。事件在 Graph 边界存为 classloader-neutral Map：`node/outcome/reason_code/attempt`，避免 DevTools restart classloader 造成 record 类型身份不一致。
+
+### RunnableConfig
+
+外层 Graph config 使用：
+
+- `threadId = runId`。
+- metadata 包含 `sessionId` 和 `runId`。
+
+调用 nested `ReactAgent` 时，`ReactAgentDiagnosisInvoker` 创建独立 config，只保留业务身份与 store，不向子 Agent 传播外层 Graph 的 human-feedback、state-update、checkpoint/resume 控制 metadata，避免父 Graph 恢复语义污染子 Graph。
+
+## 5. 证据信任边界
+
+```text
+Executor output
+  -> source_invocation_id + raw_path + evidence_excerpt
+  -> GatekeeperNode / ExecutorGatekeeperService
+      -> 按当前 runId 读取 tool_invocation
+      -> 验证 invocation ownership、raw_path、excerpt
+  -> VerifiedInputNode
+      -> 只投影通过的 claims/bindings/evidence
+  -> VerifierNodeAdapter
+      -> 只判断已验真证据是否支持 claim
+  -> ComposerNodeAdapter
+      -> 只表达允许输出的结论、限制和建议
+```
+
+Verifier 不读取完整工具 Trace，不执行新检索，也不读取 Skill 正文。当前版本不生成或读取 `tool_trace_summary`。
+
+## 6. Run 级审计模型
+
+| 审计层 | 存储/API | 回答的问题 |
+|---|---|---|
+| 执行明细 | `agent_step`、`tool_invocation` | 模型和工具实际做了什么？ |
+| 证据与答案质量 | `diagnosis_run.self_evaluation` | 引用是否真实、claim 是否可推导、Prompt/Gatekeeper 版本是什么？ |
+| Graph 路由 | `diagnosis_run.orchestration_trace` / `run.orchestrationTrace` | 走了哪些 Node、为何重试或降级、在哪里结束？ |
+
+`orchestration_trace` 当前结构：
+
+```json
+{
+  "version": "stategraph-v1",
+  "transitions": [
+    {"from": "planner", "to": "executor", "reason_code": "completed", "attempt": 1}
+  ],
+  "final_node": "composer",
+  "termination_reason": "composer_completed",
+  "degraded": false,
+  "evidence_retry_count": 0
+}
+```
+
+该字段只属于 exact Run 投影，响应不提供兼容 `session` 投影；非 StateGraph Run 可以为空。
+
+## 7. 验收层次
+
+| 测试层 | 权威测试 | 覆盖 |
+|---|---|---|
+| Workflow | `DiagnosisGraphWorkflowTest` | 全部分支、有限重试、补证据和 Fallback |
+| Node Contract | `DiagnosisGraphNodeContractTest` | 真实 Node 的输入投影、输出状态和证据边界 |
+| Runtime | `ChatDiagnosisGraphRuntimeTest` | config、最终状态、partial failure/trace |
+| Chat Integration | `ChatServiceGraphIntegrationTest` | Run 生命周期、答案、自评估、编排摘要和失败持久化 |
+| Trace Contract | `DiagnosisTraceServiceTest` | exact run ownership 和 `run.orchestrationTrace` 投影 |
+| Demo Contract | `InterviewDemoScriptContractTest` | exact runId、Graph 字段和 summary 输出 |
+
+## 8. 关键代码
+
+- `src/main/java/com/superbiz/agent/service/ChatService.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/ChatDiagnosisGraphRuntime.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisGraphFactory.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisGraphRouter.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisGraphState.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisRealGraphActionsFactory.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/ReactAgentDiagnosisInvoker.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisGraphResultMapper.java`
+- `src/main/java/com/superbiz/agent/graph/diagnosis/DiagnosisOrchestrationTraceBuilder.java`
+- `src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`