SuperBizAgent-java/openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-chatservice-cutover/design.md

Context

复杂 Chat 的公开调用链为 ChatController -> ChatService.executeChatWithStrategy -> executeChatComplex。阶段 2 已提供真实 Node adapters、显式 Gatekeeper、verified input、evidence retry、Composer/Fallback 和 DiagnosisGraphFactory，但 executeChatComplex 仍维护 SequentialAgent 两轮循环、VerifierInputHook/ThreadLocal 状态和私有 Composer 调用。阶段 3 要在不改变 /api/chat 的前提下切换唯一生产编排，并增加 Run 级 orchestration trace 数据契约。

当前 Run 通过 SessionContextHolder(sessionId, runId) 绑定 AgentStep/ToolInvocation；DiagnosisRun 使用字符串 JSON 保存 self evaluation；TraceService 将 Run 映射为 run 和兼容 session 投影。DiagnosisOrchestrationTraceBuilder 已能从有界 events 生成无 Prompt/raw output 的摘要。数据库由 Flyway 管理且 Hibernate 使用 validate，因此实体、V012 migration 和 Trace 映射必须同批对齐。

本 change 是 L4：内部状态机从固定顺序改为条件图，Trace run 对象和 DB 增加字段。/api/chat、sessionId/runId、Agent 输出协议保持兼容。用户已冻结单轨切换、安全 Fallback=SUCCESS、只有未处理失败=FAILED、阶段 5 才 live E2E。

Goals / Non-Goals

Goals:

• 让复杂 Chat 一次执行真实 CompiledGraph，删除 ChatService 的细粒度 Sequential/round 状态机。
• 保持现有 Agent prompt/tool/skill/logging 组装能力，但 Graph Verifier 不注册 VerifierInputHook。
• 用 runId 同时作为 Graph threadId 和 Run 审计边界，用 sessionId/runId metadata 维持 AgentStep/ToolInvocation 归属。
• 将 final state 显式映射为 answer、verifier evaluation、composer audit、orchestration trace 和 Run lifecycle。
• 在正常/handled fallback 路径持久化非空、紧凑、安全的 orchestration trace，并只在 Trace run 对象暴露解析结果。
• 更新 Verifier Prompt/self-evaluation 到 verified-only 数据模型。
• 用阶段 3 focused tests证明生产 cutover、Run/Trace/API/Prompt 边界，且不留下已知失败测试。

Non-Goals:

• 不改简单 Chat/AIOps 编排。
• 不删除 VerifierInputHook/VerifierContextHolder 类型；它们在阶段 5 清理，但复杂 Chat 不再引用。
• 不增加持久 Graph checkpoint、恢复、并行分支或新 Run status。
• 不回填历史 run，不给历史 null orchestration trace 设计兼容伪值。
• 不在本阶段全面重命名/收敛测试夹具；阶段 4 完成测试体系替换。
• 不运行 Maven live E2E、日志或数据库验收。

Decisions

1. 单轨生产 cutover，不增加 feature flag

executeChatComplex 只构造当前 Run、RunnableConfig 和 diagnosis context，然后调用真实 Graph runtime。旧 SequentialAgent loop、score/feature-flag retry 和 ChatService 私有 Verifier/Composer 路由方法从生产类移除；不保留双运行、shadow compare 或 runtime fallback 到 Sequential。

选择单轨而不是 feature flag，因为用户冻结的阶段门禁已经提供 Git commit 回滚边界，双轨会继续维护两套重试、Gatekeeper 和安全材料真理源。数据库新列 nullable，因此代码回滚时列可保留，无需破坏性 migration down。

2. Agent builder 只迁移职责，不复制实现

新增专用复杂 Chat Graph runtime/factory，复用当前 Planner/Executor/Verifier/Composer Prompt、knowledge map、history、method tools、ToolCallbacks、skill hooks 和 AgentLoggingHook 组装规则。ChatService 只向它提供本次 ChatModel、callbacks、history 和 Run 上下文。Graph Verifier hooks 只有 AgentLoggingHook，不包含 VerifierInputHook；Gatekeeper 只由显式 Node 调用。

如果为控制改动风险暂时保留简单 Chat 的工具/Hook builder，复杂 Agent builder 仍只存在一份。不得在 Graph Node 或 runtime 内复制 prompt 文本或第二套 tool catalog。

3. Graph 初始 state 和 RunnableConfig 使用最小白名单

初始 state 包含：

• diagnosis_context={query, original_query}；不把完整 history 放入 Graph State，history 仅注入 Planner/Executor system prompt。
• planner_mode=NORMAL。
• planner/verifier/composer/evidence retry count 全部为 0。
• orchestration_events 初始为空。

RunnableConfig 使用 threadId(runId)，metadata 包含 sessionId 和 runId。这同时满足 Graph 隔离、AgentLoggingHook/ToolCallback 的 Run ownership 和 Gatekeeper current-run validation。

4. 流式执行捕获最后真实 state

Graph runtime 使用 CompiledGraph.stream(initialState, config) 顺序消费 NodeOutput，并保存最后一个真实 OverAllState。正常 END 以最后 state 的非空 final_answer 为成功条件。流式消费与原同步 invoke 一样在当前请求线程阻塞，但允许在未处理异常时取得已真实产生的 partial state。

若异常前已有 events，failure handler 可以 best-effort 构造/persist partial trace；若没有 event，不生成虚假 node/transition。Agent invocation failures已经由 adapters 转为显式 status，正常预期失败都应走 Graph Fallback 而不是抛出。

5. Graph result mapper 是唯一运行结果翻译层

新增显式 mapper 从 final/partial state读取：

• final_answer。
• Verifier status/model/effective verdict、score、claim/fact checks、rationale、round。
• Gatekeeper raw audit、verified Executor output/evidence。
• Composer audit。
• DiagnosisOrchestrationTraceBuilder 结果。

ChatService 不再读取 VerifierContextHolder。self-evaluation 继续写 verifier_evaluation container 以兼容 Trace/Eval 消费者，但数据来自 Graph State：executor_structured_output 只保存 verified projection；新增 verified_evidence 和显式 statuses；不保存 raw Executor 或完整 tool_trace_summary。若 Verifier 从未完成，evaluation 只记录可用 status/audit/prompt 信息，不伪造 verdict。

6. Run lifecycle 和持久化顺序按执行结果分离

成功路径：Graph 返回非空安全 answer -> 构造 trace/evaluation -> 设置 Run SUCCESS、answer、orchestrationTrace、duration/metrics -> 保存 -> 调用 evaluateRun。

handled Fallback 与 Composer 正常路径使用相同成功顺序；可信度由 effective verdict 或 trace degraded 表达。失败路径：未处理异常、final state/answer 缺失、trace invariant 失败或成功结果持久化失败 -> Run FAILED，保存错误答案、duration、已有可构造 partial trace 和 metrics；不调用 success Eval。若 failure save 本身失败，只记录明确 error，不能声称持久化成功。

7. Orchestration trace 是独立 nullable JSON 数据契约

新增 V012，仅执行：

ALTER TABLE diagnosis_run ADD COLUMN orchestration_trace JSON NULL ... AFTER self_evaluation。

DiagnosisRun 使用 @JdbcTypeCode(SqlTypes.JSON) + String orchestrationTrace，与 selfEvaluation 写法一致。nullable 只服务无回填 migration/历史 run；每个成功的新 StateGraph Chat run 应用层必须非空。序列化使用 DiagnosisOrchestrationTrace.toMap()，字段保持 snake_case JSON。

8. Trace API 只在 RunTrace 增加解析对象

DiagnosisTraceResponse.RunTrace 新增 Map<String,Object> orchestrationTrace。DiagnosisTraceService 从 DiagnosisRun.orchestrationTrace 解析后映射；顶层 response、ChatSessionTrace、兼容 SessionTrace 和 raw string 均不新增字段。Run list 也不扩展该字段。

历史/AIOps run 的 null 值原样返回 null，不进行 fallback synthesis。解析非法 JSON 时 fail closed 为 null，并由数据/测试暴露问题；本阶段不增加历史兼容分支。

9. Verifier Prompt 与 verified-only input 对齐

chat-verifier-prompt.md 输入改为：diagnosis_context、verified_executor_output、verified_evidence、gatekeeper_audit、verdict_ceiling、可选 retry_context。删除 executor_final_answer、完整 tool_trace_summary、Hook parse status 和“再次执行 Gatekeeper”语义。

Verifier 仍输出原 JSON contract。evidence_refs 通过 claim_id/source_invocation_id/tool_name/raw_path 对 verified_evidence 建立审计关联，不要求不可用的 tool_trace_summary.trace_ref。Prompt audit catalog/version 随输入契约升级并在所有 handled paths 持久化。

10. 测试分阶段但不允许已知失败

阶段 3 新增最小生产 cutover测试：Graph runtime/final mapping、threadId/metadata、SUCCESS/Fallback/FAILED lifecycle、trace storage/API location、Prompt forbidden fields、no Verifier step on pre-verification failure。运行相关 Graph/Trace/Controller/Eval 回归和 test compilation。

旧 ChatServiceSequentialAgentTest 若因单轨语义失效，阶段 3 必须删除/改写冲突断言或由 focused Graph integration 替代，不能留到阶段 4 才让测试恢复绿色。阶段 4 继续完成命名、夹具、分支矩阵和旧 Hook tests 的全面清理。

Interface Impact

• 等级：L4。
• 外部兼容：/api/chat request/response 与 run identity 不变。
• 加法协议：Trace run.orchestrationTrace；DB diagnosis_run.orchestration_trace。
• 内部行为：Executor/Planner/Gatekeeper failure 可提前 Fallback，不再保证固定 Agent 顺序；score flag 不再控制 LOW_CONFID retry。
• 消费者：Trace UI/demo/eval 可读取新 run 字段但不强制历史值；阶段 5 demo script 才增加最终 E2E 断言。
• 回滚：revert 本阶段代码/Prompt/spec；保留 nullable DB 列。无双轨开关、无数据回填回滚。

Risks / Trade-offs

• [流式 API 与同步 invoke 的终止语义不同] → focused test断言最后 state、END、事件顺序和异常 partial state；不依赖实现私有字段。
• [self-evaluation 字段变化影响 Eval fixture] → 保留 container、verdict/claim/fact/gatekeeper/composer/prompt audit 兼容键；新增 verified 字段，移除不安全 full summary 前同步 specs/tests。
• [Agent factory 移动破坏 skill/tool hooks] → 复用现有 buildHooks/buildMethodTools 规则，并断言 Planner/Executor/Verifier/Composer hooks和当前 Run metadata。
• [JSON 字段三层漂移] → V012、entity、DTO/service 和 tests同批提交；Maven test compilation + strict specs。
• [无法取得 partial state] → 不伪造 trace；标记 FAILED 并记录明确原因。预期 Agent failures 全部由 Node adapters handled。
• [阶段 3/4 测试边界重叠] → 阶段 3只保证 cutover 可验收且现有 suite 不红；阶段 4负责全面测试架构替换。

Migration Plan

1. 先加 V012、entity/Trace DTO/service 与 isolated mapping tests。
2. 实现 Graph runtime/result mapper和 Prompt verified-only 更新，先用 fake agents验证 final/partial state。
3. 将 executeChatComplex 单轨切换并删除旧私有 Sequential 状态机逻辑，保留 Run、metrics、Eval和简单 Chat路径。
4. 运行 production cutover、Graph、Trace、Controller/Eval 回归与 test compilation；证明 DB schema diff 只有一个字段。
5. 归档、提交阶段 3；阶段 4 再全面替换测试体系。

部署时 Flyway 先加 nullable 列，随后新代码写入。回滚为 Git revert；旧代码忽略新增列，数据库不删除列。

Open Questions

无。所有产品/协议边界均由 ISS-011 与用户确认冻结；实现期若发现 Graph API 无法提供真实 partial state，只能回写本 design/tasks 后使用不伪造的 FAILED 处理，不能扩大协议。