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 负责各自的语义任务或确定性校验。

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 运行按以下顺序执行：

ChatService 解析或创建 sessionId，生成唯一 runId。
确保 chat_session 元数据存在，并创建 diagnosis_run，初始状态为 RUNNING、agent_flow=CHAT。
构建 Planner、Executor、Verifier、Composer 四个 ReactAgent，再由 DiagnosisRealGraphActionsFactory 组合 Java Nodes。
ChatDiagnosisGraphRuntime 以 runId 作为 Graph threadId，将 sessionId/runId 放入 RunnableConfig.metadata。
DiagnosisGraphFactory 编译 StateGraph 并执行，Graph recursion limit 固定为 32。
Graph 返回非空 final_answer 后，DiagnosisGraphResultMapper 生成 verifier evaluation，DiagnosisOrchestrationTraceBuilder 压缩路由摘要。
ChatService 保存答案、耗时、步骤数、工具数、自评估和编排摘要，将 Run 标记为 SUCCESS。
未处理异常会尽力保存 partial state/partial trace，再将 Run 标记为 FAILED；能够生成安全 Fallback 的路径仍是 SUCCESS，并通过 degraded=true 表达质量降级。
finally 清理本轮检索追踪和 session/run ThreadLocal，避免跨 Run 污染。

3. Graph 拓扑

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. 证据信任边界

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 当前结构：

{
  "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

9.5 KiB Raw Blame History Unescape Escape