SuperBizAgent-java/devflow/projects/2026-07-17-chat-diagnosis-stategraph-chatservice-cutover/decisions.md

# Chat Diagnosis StateGraph ChatService Cutover Decisions

## Entry Summary

- 问题：复杂 Chat 仍使用 SequentialAgent + ThreadLocal/Hook 隐式状态机，真实 Graph 尚未成为生产入口，也没有 Run 级 orchestration trace 持久化和 API 投影。
- 期望：阶段 3 独立完成生产 cutover、Run/Trace 映射和必要测试，归档并提交后才进入阶段 4。
- 分档：complex。
- Change：`chat-diagnosis-stategraph-chatservice-cutover`。
- 授权：用户已要求后续阶段直接实现，不再逐 checkpoint 等待；阶段门禁、独立 archive/commit 与阶段 5 才 E2E 约束不变。

## Context Sources

- `mvp/issues/active/ISS-011-chat-diagnosis-stategraph-orchestration.md` 阶段 3、协议影响、Run 状态和验收章节。
- 阶段 0–2 OpenSpec archives、devflow acceptance/decisions 与当前四份 Graph 主 specs。
- `devflow/glossary/CONTEXT.md` 中 Chat Session、Diagnosis Run、Diagnosis Trace、Diagnosis Orchestration Trace 的边界。
- `ChatService` 生产调用链、四个 Agent builder、Run persistence/self-evaluation/metrics 逻辑。
- `DiagnosisRun`、V011 migration、`DiagnosisTraceResponse`、`DiagnosisTraceService` 与相关 tests。
- `DiagnosisGraphFactory`、真实 action factory、Node adapters、final trace builder 和本地 CompiledGraph API。

## Question Pool

| # | 维度 | 问题 | 模式 | 状态 |
|---|---|---|---|---|
| Q1 | 术语 | orchestration trace 是否属于 self-evaluation 或完整 Trace event log？ | evidence-driven | 已解决 |
| Q2 | 边界 | 阶段 3 是否改变 `/api/chat`，以及 Trace 字段出现在哪一层？ | user-interview（既有冻结决策） | 已确认 |
| Q3 | 生命周期 | LOW_CONFID/REJECT/Fallback 是否应使用 FAILED 或新增 DEGRADED？ | user-interview（既有冻结决策） | 已确认 |
| Q4 | 错误处理 | Graph 异常时如何 best-effort 保存已有编排事实而不伪造 event？ | evidence-driven | 已解决 |
| Q5 | 技术实现 | 是否复用现有 Agent factory/Hook/ToolCallback 与真实 Node assembly？ | evidence-driven | 已解决 |
| Q6 | 安全 | Graph Verifier Prompt/self-evaluation 是否可继续使用 raw Executor 和完整 tool trace？ | evidence-driven | 已解决 |
| Q7 | 验收 | 阶段 3 是否需要新增测试，是否现在运行 live E2E？ | user-interview（用户最新规则） | 已确认 |

## Evidence-driven Findings

- Q1：glossary 与阶段 0 spec 已定义 orchestration trace 为 Run 级紧凑编排摘要，与 self-evaluation、AgentStep/ToolInvocation 和 checkpoint 分离；无需新增术语或 ADR。
- Q4：所有已定义 Agent/Java 失败应由 Graph 路由到 handled Fallback 并返回 final state；只有真实可取得的 final/partial state 才可构造 trace。无法取得 state 的未处理异常标记 Run FAILED，不得生成虚假 transition。
- Q5：`DiagnosisRealGraphActionsFactory` 已提供真实 Node assembly；ChatService 现有四个 builder、AgentLoggingHook、Skills hooks、method tools 和 ToolCallbacks 可直接构造 ReactAgent，再通过 `ReactAgentDiagnosisInvoker` 注入，不得复制 Prompt/Agent factory。
- Q6：阶段 2 spec 已禁止 Graph Verifier 使用 raw Executor/full tool trace；当前 `chat-verifier-prompt.md` 仍描述旧 Hook payload，是阶段 3 必须同步的明确 gap。self-evaluation 可保存 Graph 的 verified output、Gatekeeper audit 和 Composer audit，但不能重新引入 raw 输入。

## User-interview Confirmations

| 问题 | 用户原话/既有确认 | 确认状态 | OpenSpec 回写 |
|---|---|---|---|
| Q2 外部协议与 Trace 层级 | ISS-011 已冻结 `/api/chat` 不变，Trace 只在 `run.orchestrationTrace` 增解析对象 | 已确认 | proposal |
| Q3 Run 生命周期 | ISS-011 已冻结安全 Fallback 为 SUCCESS，不新增 DEGRADED；只有无法生成安全响应的未处理失败为 FAILED | 已确认 | proposal |
| Q7 验收节奏 | “端到端只在最后阶段全部完成后才验证；每个阶段如果有必要添加单元测试验收的话，就加” | 已确认 | proposal |

## Interface Impact

- 等级：L4。
- 原因：复杂 Chat 内部状态机正式切换；DiagnosisRun 增加数据库 JSON 契约；Trace run 对象新增字段；旧固定顺序消费者/测试不再成立。
- 保持兼容：`/api/chat` request/response、sessionId/runId、Executor/Verifier/Composer 输出契约不变。
- 加法变化：只新增 `diagnosis_run.orchestration_trace` 和 `run.orchestrationTrace`。
- 回滚：revert 阶段 3 代码/Prompt/spec，数据库列可保留 nullable；不保留运行时双轨开关。

## Discover Status

- `devflow/index.md`：命中阶段 0–2 archives 和 Run/Trace 历史项目。
- Glossary：相关术语已存在且无冲突，不需更新。
- ADR：阶段 0 已记录难以逆转的状态机/Trace 决策，本阶段没有新的三条件 ADR。
- 未解决问题：0。
- Draft 产物：当前只创建 proposal + decisions；design/specs/tasks 留到 Commit checkpoint。

## Grill-with-docs Review

### Domain model stress test

- 同一 session 连续两个复杂 Chat run：每次编译/执行使用自己的 runId threadId 和 metadata；orchestration trace 只写各自 DiagnosisRun，session 投影不复制，符合 Session/Run/Trace 领域边界。
- Gatekeeper REJECT 或 Planner/Executor 技术失败：Graph 进入确定性 Fallback，返回安全非空答案；Run 为 SUCCESS，trace `degraded=true`，不会把诊断质量塞进 Run status。
- Composer 成功但 verdict=LOW_CONFID/REJECT：Run 仍为 SUCCESS；self-evaluation 保存 effective verdict，orchestration trace 保存实际路径，两者职责不混合。
- Graph 未处理异常：使用流式 NodeOutput 捕获最后一个真实 state，只有其中已有 events 时才 best-effort 构造 partial trace；没有 event 时不伪造 transition，Run 标记 FAILED。
- 历史/AI_OPS run：新增列 nullable，Trace DTO 对旧 run 可返回 null；不增加历史回填或跨 flow 假数据。

### Design tree conclusions

- 生产切换采用单轨，不增加 feature flag 或保留 Sequential/Graph 双运行；回滚依靠 Git revert，nullable 列可保留。
- ChatService 负责 Run 生命周期和调用一个专用 Graph runtime/orchestrator；复杂 Agent 构造从旧 Sequential 私有流程中搬移或封装复用，不复制第二套 builder。
- Graph 执行优先使用可观察的 `CompiledGraph.stream(..., config)` 收集最后真实 state，以支持异常时 best-effort trace；正常终止仍以 END state 的 `final_answer` 为唯一答案来源。
- Graph result mapping 形成独立组件：final answer、Verifier evaluation、Composer audit、Gatekeeper audit、trace JSON 均从显式 final state读取，不再访问 VerifierContextHolder。
- Verifier Prompt 必须更新为 `diagnosis_context`、`verified_executor_output`、`verified_evidence`、`gatekeeper_audit`、`verdict_ceiling` 和可选 retry context；删除 raw Executor/full tool trace/Hook Gatekeeper 说明。
- 阶段 3 必须有 production cutover 与 Trace DTO/Service tests；阶段 4 再做测试体系全面改名、夹具收敛和旧测试删除。

### Documentation result

- 术语与 `devflow/glossary/CONTEXT.md` 完全一致，无需修改 glossary。
- 状态机、Run status 和 orchestration trace 隔离均来自阶段 0 已归档 ADR/规格，不创建重复 ADR。
- proposal 已反映单轨切换、L4 接口影响、流式 partial-state 处理、Prompt 安全边界和阶段 5 E2E 延期。
- Grill question pool 全部关闭；无需要再次询问用户的产品取舍。

## Architecture Audit

### Module and caller map

`ChatController` 的 normal/SSE 两个入口都调用 `ChatService.executeChatWithStrategy`，复杂分支进入 `executeChatComplex`；对外仍只消费 `ChatResult(answer, sessionId, runId)`。阶段 3 将内部链路变为 `ChatService Run lifecycle -> complex Chat Graph runtime/Agent assembly -> real Diagnosis Nodes -> Graph result mapper -> DiagnosisRun persistence -> DiagnosisTraceService`。Trace UI/Eval 当前读取兼容 `session.selfEvaluation`，它仍由 Run self-evaluation 投影；新增 orchestration trace 只属于 `run`。AIOps、Feedback、CaseLibrary 和 Run list 继续使用 DiagnosisRun 既有字段，不消费新增 orchestration trace。

| 模块 | 所有权 | 允许的依赖/影响 |
|---|---|---|
| ChatController | `/api/chat` normal/SSE 协议 | 继续只依赖 ChatResult；无字段变化 |
| ChatService | Chat Session/Diagnosis Run 生命周期、成功/失败保存、metrics、Eval、finally cleanup | 调用一个 Graph runtime/result mapper；不再拥有条件边/重试/Gatekeeper/Composer 路由 |
| Complex Chat Graph runtime | 每请求 Agent assembly、initial state、RunnableConfig、CompiledGraph stream | 复用现有 Prompt/tool/skill/logging；不持久化跨 Run 状态 |
| Diagnosis Graph | Node status、verified material、events、final answer | 保持阶段 1/2 路由和 counter 所有权 |
| Graph result mapper | final/partial state 到安全 evaluation/trace DTO | 不读 ThreadLocal，不查询其他 run，不持久化 raw material |
| DiagnosisRun/Flyway | 当前 Run 的 orchestration JSON | 仅一个 nullable JSON 列；历史/AIOps 可为 null |
| DiagnosisTraceService/DTO | exact/latest Run 查询和 API 投影 | 只在 RunTrace 加 parsed map；session/top-level/run-list 不重复 |

### Lifecycle and coupling audit

ReactAgent 与 CompiledGraph 都按请求构造，因为 Planner/Executor system Prompt 含本次 history/knowledge map；Graph State 和 runtime last-state holder 也是 invocation-scoped，不进入 singleton 可变字段。SessionContextHolder 仍只包围当前请求并在 finally 清理；Graph Node config 以 runId threadId + metadata 绑定 AgentStep、ToolInvocation 和 Gatekeeper。success persistence 在 Eval 之前完成，EvaluationService 再按 runId 合并 rule channel；handled Fallback 与 Composer 使用同一 SUCCESS 路径。Trace JSON 与 self-evaluation 分栏，避免把路线、质量和完整 Agent/tool 明细耦合到一个容器。

### Consumer impact audit

- ChatController normal/SSE：ChatResult 协议不变，L4 内部切换不要求调用方迁移。
- Trace UI/demo：继续读取兼容 `session.selfEvaluation`；新的 `run.orchestrationTrace` 是加法字段，最终脚本断言留到阶段 5。
- DiagnosisTraceEvaluator：现有 fixtures 不变；工具覆盖仍可从 `toolInvocations` 读取，兼容 `executor_structured_output` 保存 verified projection。pre-verification Fallback 质量未来应以 trace degraded 而非伪 verdict 判断，属于阶段 4 测试体系/阶段 5文档收尾。
- AIOps/Feedback/CaseLibrary/Run list：实体新增 nullable 字段不改变 builder call sites或查询语义。
- 数据库：Hibernate validate 要求 V012 与 entity 同批；回滚代码可忽略保留列。

### Cross-artifact alignment

| 对齐链 | 结果 | 证据 |
|---|---|---|
| brief/proposal 目标、范围、非目标 → proposal | 已对齐 | 单轨 cutover、Run/Trace、Prompt、阶段边界与 E2E 延期均明确 |
| proposal 承诺与约束 → design | 已对齐 | 10 项决策覆盖 runtime、state、config、partial state、result、persistence、DB/API/Prompt/tests |
| design 架构/接口结论 → specs/tasks | 已对齐 | L4、单轨、Run status、verified-only、Trace 唯一投影和 schema whitelist 均有 requirement/task |
| specs 可观察行为 → tasks 可执行切片 | 已对齐 | 6 组 26 个切片覆盖数据、runtime、Prompt、cutover、tests、handoff |

### Audit result

未发现与阶段 0–2、Run/Trace ADR 或 glossary 冲突。审计确认不能把 Agent factory 复制进 Node，也不能把 pre-verification Fallback 伪装为 Verifier verdict；两项已在 design/specs/tasks 固定。唯一跨阶段依赖是阶段 4 让测试/Eval 以 orchestration degraded 理解无 Verifier verdict 的安全 Fallback，已记录但不阻塞阶段 3 production correctness。架构风险可接受，cross-artifact gap=0，无未解决接口消费者。

## Commit Gate

- schema：spec-driven；proposal/design/specs/tasks 全部 done，applyRequires=`tasks` 已满足。
- OpenSpec：当前 change strict validation 通过；14 个主 specs 全部 strict pass。
- 规格结构：5 个 delta capabilities、23 条 requirements、72 个 scenarios；tasks 26 个可执行 checkbox。
- Cross-artifact：4/4 已对齐，gap=0。
- Interface impact：L4；design 已独立记录消费者、加法 DB/Trace 协议、单轨迁移和 Git revert 回滚。
- Question pool：所有 evidence-driven 已查证；所有 user-interview 已由 ISS-011/用户原话确认；无未决项。
- Preflight：`git diff --check` 通过；Commit checkpoint 尚未修改 Java、SQL、Prompt 或测试。
- 结论：Draft OpenSpec 已达到可执行状态，创建 `.committed`，阶段 3 Apply 只能以这些产物为依据。

## Apply Authorization

- 用户原话：“直接实现吧，不用找我授权了”。
- 本阶段在 Commit gate 后直接进入 Apply；不扩大到阶段 4 全面测试迁移或阶段 5 live E2E。

## Pre-apply Research

### Reference implementations read

- `ChatService.executeChatComplex`、四个 complex Agent builders、Run start/save、metrics、Prompt audit、self-evaluation merge：迁移源实现和外部兼容基线。
- `DiagnosisGraphFactory`、`DiagnosisRealGraphActionsFactory`、四个 Agent adapters、Gatekeeper/VerifiedInput/Fallback、`DiagnosisOrchestrationTraceBuilder`：Graph 路由/计数/安全材料唯一真理源。
- `DiagnosisRun`、V011 migration、`DiagnosisTraceResponse`、`DiagnosisTraceService`、`DiagnosisTraceServiceTest`：Run JSON 字段和 exact/latest Trace 映射标准。
- `ChatController` normal/SSE、`DiagnosisTraceController`：公开协议调用者与响应包装边界。
- `SelfEvaluationMergeService`、`EvaluationService`、`DiagnosisTraceEvaluator`：evaluation container、异步 rule merge 和兼容消费者。
- 本地 graph-core 1.1.2.0 `javap`：CompiledGraph `stream/invoke/state`、NodeOutput `state()`、RunnableConfig `threadId/metadata` 的真实 API。
- `chat-*-prompt.md`：现有 Prompt 组装与 Verifier 旧 Hook payload gap。

### Technology inventory

| 类别 | 项目标准 / 本阶段使用 |
|---|---|
| Graph execution | `CompiledGraph.stream(initial, config)` + NodeOutput.state，当前请求线程阻塞消费 |
| Run context | SessionContextHolder + RunnableConfig threadId/metadata；runId 是唯一执行边界 |
| Agent assembly | ReactAgent builder、AgentLoggingHook、PlannerSkillMetadataHook/SkillsAgentHook、现有 tools/callbacks |
| JSON persistence | Jackson map serialization；实体 String + `@JdbcTypeCode(SqlTypes.JSON)`；Flyway JSON column |
| Trace API | Lombok DTO builder + DiagnosisTraceService parsed Map；exact/latest Run 查询 |
| Evaluation | SelfEvaluationMergeService container；EvaluationService 按 runId 异步合并 rule channel |
| Tests | JUnit 5，通过 public service/runtime/Trace API；只 mock repository/model/tool 外部边界 |
| MQ/Consumer | 不涉及 |

### New infrastructure and reuse

- 新增一个深接口的 complex Chat Graph runtime/result mapper；复用既有 Graph/Node/Agent builders，不增加新依赖或第二套路由。
- 新增 V012、DiagnosisRun 字段和 RunTrace parsed map；不新增表、repository method 或历史 backfill。
- TDD tracer bullet 从 Trace DTO/Service 的唯一 Run 投影开始，再进入 runtime final-state mapping，最后切换 ChatService。
- 研究未发现 devflow/OpenSpec 冲突，技术清单足以开始实现。

## Apply Progress

- TDD Trace slice RED：DiagnosisTraceServiceTest 明确缺少 DiagnosisRun builder 字段和 RunTrace getter。
- GREEN：V012、DiagnosisRun JSON 字段、RunTrace parsed map、DiagnosisTraceService mapping 完成；10 个 Trace service tests 通过。
- 失败分类：首次 GREEN 运行仅测试夹具用裸 ObjectMapper 无法序列化 LocalDateTime，属于 test harness 偏差；改为项目可用的 `findAndRegisterModules()` 后原始 focused loop 通过，未改业务协议。
- Trace API JSON 断言证明顶层/session 无重复字段、run 为解析对象、无 raw 字段；null/invalid JSON fail closed。

## Apply Completion

- 复杂 Chat 已单轨切换到 `ChatDiagnosisGraphRuntime`；生产 `ChatService` 不再创建 `SequentialAgent`，不再读取 `VerifierContextHolder`，Graph Verifier 只保留 `AgentLoggingHook`。
- runtime 使用 query-only initial state、`threadId=runId` 和 sessionId/runId metadata，流式保留最后真实 state；异常只保存真实 partial state/trace。
- `DiagnosisGraphResultMapper` 只从 verified projection 构造兼容 self-evaluation；Verifier 未完成时不伪造 verdict，不持久化 full tool trace/raw Executor。
- Verifier Prompt 与 runtime payload 已统一为 verified-only，Prompt audit 更新为 `chat-prompts-v2` / `chat-verifier-v3`。
- 旧 `ChatServiceSequentialAgentTest` 因绑定已删除的固定顺序/ThreadLocal/score retry 实现而移除，由 public service/runtime/route tests 替代。
- V012 schema 白名单测试确认只新增 `diagnosis_run.orchestration_trace JSON NULL`，无其他 schema object。

## Verification Summary

- focused regression：27 suites / 119 tests，0 failures、0 errors、0 skipped。
- Maven test compilation：通过。
- OpenSpec：当前 change strict pass；主 specs 14/14 strict pass。
- 静态门禁：`git diff --check` 通过；cutover 禁用引用 0；核心 TODO/placeholder 0；schema whitelist 为 1 ALTER / 1 ADD COLUMN / 0 CREATE / 0 DROP。
- 实现期唯一失败分类：no-answer service test 曾错误期待 inner cause 文本，属于测试断言偏差；按公开 wrapper error + FAILED/partial trace 契约修正后通过，OpenSpec 与生产代码无需变更。
- 按阶段门禁未运行 Maven live E2E、未检查 `logs/`、未执行 `scripts/query_mysql.py`；统一保留到阶段 5。

## Archive Result

- 5 份 delta specs 已同步：新增 9、修改 13、删除 1 条 requirements。
- OpenSpec 已归档到 `openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-chatservice-cutover/`。
- CLI 对 proposal 结构给出非阻塞建议（大 change/delta 拆分与 SHALL/scenario 启发式）；tasks 26/26、delta specs 和 strict validation 均通过，未形成验收阻塞。