Chat Diagnosis StateGraph ChatService Cutover

Why

阶段 2 已交付可构造、可测试的真实 Diagnosis StateGraph Nodes，但复杂 Chat 生产入口仍由 ChatService.executeChatComplex(...) 创建 SequentialAgent、维护 LOW_CONFID 外层循环，并依赖 VerifierInputHook/VerifierContextHolder 回传隐式状态。阶段 3 需要正式切换生产编排，让 ChatService 只管理 Run 生命周期、Agent 装配、Graph 调用和结果持久化，同时把 Graph 路由摘要作为当前 Run 的独立 Trace 维度保存和查询。

What Changes

将复杂 Chat 从 SequentialAgent 外层循环切换为一次 CompiledGraph invocation，初始 state 使用显式 diagnosis context 和独立计数器。
为 Planner、Executor、Verifier、Composer 构造现有 ReactAgent 实例，经 ReactAgentDiagnosisInvoker 注入真实 Node actions；Graph Verifier 不注册旧 VerifierInputHook。
使用 runId 作为 Graph threadId，并把 sessionId、runId 放入 RunnableConfig metadata，继续复用 AgentStep/ToolInvocation 的 Run 归属。
将 Graph 最终 state 映射为现有 ChatResult、Verifier self-evaluation、Run 指标和生命周期状态。
新增 diagnosis_run.orchestration_trace nullable JSON 列、实体字段和紧凑序列化；新 StateGraph Chat run 在应用契约上必须写入非空摘要。
Trace API 只在 run.orchestrationTrace 返回解析 JSON，不在顶层、兼容 session 投影或 raw 字段重复。
同步 Verifier Prompt 到 verified-only Graph 输入，移除完整 tool trace、raw Executor 和 Hook gatekeeper 输入说明。
增加生产 cutover、Run/Trace、safe Fallback、thread/metadata、Prompt 边界的必要单元/集成测试。

Capabilities

New Capabilities

chat-diagnosis-stategraph-chatservice-cutover：规定复杂 Chat 的 StateGraph 生产调用、Run 生命周期、结果映射、编排摘要持久化与 Trace API 投影。

Modified Capabilities

chat-diagnosis-stategraph-real-nodes：阶段 2 的生产隔离约束改为阶段 3 正式切换，真实 Nodes 成为复杂 Chat 唯一生产编排。
chat-verifier-agent：Verifier 输入改为 Gatekeeper passed binding 投影后的 verified-only payload；self-evaluation 以 Graph state 为来源。
chat-composer-agent：Composer 由 Graph Node 调用，但 allowed-material 与审计契约保持不变。
session-run-trace-isolation：Run 增加独立 orchestration trace，Trace API 只在精确 run 对象暴露解析结果。

Scope

In Scope

ChatService.executeChatComplex(...) 的完整生产 cutover 和不再使用 SequentialAgent 的私有编排逻辑清理。
现有 Prompt/Agent builder 的 Graph 适配；不复制第二套 Agent factory。
DiagnosisRun、Flyway、Trace DTO/Service 的加法式 orchestration trace 支持。
Graph final state 到 answer、verifier evaluation、composer audit、Run status/metrics 的映射。
阶段 3 风险所需的 focused tests 与现有 Controller/Trace/Eval 契约回归。

Out of Scope

不删除尚未被其他历史测试引用的 VerifierInputHook、VerifierContextHolder 类；阶段 5 统一清理。
不在阶段 3 完成整个测试体系命名/夹具迁移；阶段 4 负责全面替换旧 Sequential 测试体系，但阶段 3 不允许留下已知失败测试。
不修改 /api/chat 请求/响应结构或 Executor/Verifier/Composer 输出协议。
不新增 Run status，不做历史 run 的 orchestration trace 回填或兼容读取分支。
不运行 Maven live E2E、logs/ 或数据库查询；统一保留到阶段 5。

Context Constraints

阶段 0–2 archives 和主 specs 是实现基线；Graph 的 Node、条件边、计数所有权和安全 Fallback 边界不得在本阶段复制或放宽。
diagnosis_run.status 只表达执行生命周期；Composer、LOW_CONFID、Verifier REJECT 或固定安全 Fallback 只要生成安全答案均为 SUCCESS。
编排摘要必须由有界 orchestration_events 构造，不从日志反推，不保存 Prompt、reasoning、raw tool output 或 Graph State snapshot。
self-evaluation 与 orchestration trace 分离；AgentStep/ToolInvocation 继续作为详细 Trace 数据源。
新 Graph Verifier 只接收 verified_executor_output、verified_evidence、Gatekeeper audit/ceiling、query 和 retry context。
运行失败时不得伪造未发生的 events；可取得的部分 state 才允许 best-effort 持久化。

Acceptance

复杂 Chat 生产代码不再创建或调用 SequentialAgent，且只调用一次 CompiledGraph。
RunnableConfig 的 threadId 等于 runId，metadata 同时包含当前 sessionId/runId。
Graph final answer 非空时映射为现有 ChatResult，Run 为 SUCCESS；无法产生安全响应或未处理失败时 Run 为 FAILED。
每个新 StateGraph Chat run 都持久化非空、无敏感材料的 orchestration trace；Trace API 只在 run.orchestrationTrace 返回解析对象。
AgentStep、ToolInvocation、self-evaluation、answer、duration、token/step/tool count 和 Eval 仍绑定当前 runId。
Verifier Prompt 和实际 verified-only payload 一致，Graph Verifier 不注册旧 input Hook。
Executor/Gatekeeper 等前置失败的 Graph 路径不产生 Verifier AgentStep。
/api/chat 和证据协议保持不变；数据库 schema 只新增一个 nullable JSON 列。
阶段 3 focused tests、Trace/Controller/Eval 回归、test compilation 和 OpenSpec strict validation 通过；不运行 live E2E。

Risks

ChatService 当前同时承载 Agent factory、Run 生命周期和旧解析逻辑；cutover 必须做完整内部重构，避免留下双编排路径或死代码。
self-evaluation 旧字段曾依赖 ThreadLocal/full tool summary；Graph 映射必须明确兼容字段和安全边界，不能重新泄漏未验真材料。
Graph invoke 异常可能没有可用 final state；失败处理只能持久化真实可取得的 partial snapshot，不能编造路径。
JSON entity/DDL/Trace DTO 必须保持同一字段语义，否则 JPA validate、数据库迁移或 API 解析会漂移。

6.0 KiB Raw Blame History Unescape Escape