# Chat Diagnosis StateGraph Routing Skeleton ## Why 阶段 0 已归档 ISS-011 的 StateGraph 设计基线，但仓库尚无可编译的 StateGraph 实现，也没有证据证明锁定的 Graph Core `1.1.2.0` 能按冻结条件边、追加事件策略和循环上限工作。阶段 1 需要用 Fake Node 建立不接真实模型、不会进入生产入口的路由骨架，为后续真实 Node 接入提供稳定内部接口。 ## What Changes - 新增 Diagnosis Graph State key、Node、route、status/verdict 常量和类型。 - 在现有 Spring AI Alibaba BOM 管理下显式声明 Graph Core 直接依赖，避免依赖 Agent Framework 的传递关系。 - 新增可注入 config-aware Node action ports 的 StateGraph 编译工厂。 - 实现阶段 0 冻结的完整条件边、三类技术重试上限、一次 evidence retry 和 recursion limit。 - 为 `orchestration_events` 配置 AppendStrategy，其余字段默认 ReplaceStrategy。 - 新增有界 event、transition 和 orchestration trace builder。 - 使用 Fake Node 单元测试覆盖正常、重试、失败、Gatekeeper、LOW_CONFID、Fallback、循环上限和 trace 顺序。 本 change 不接入 ChatService 或任何真实 Agent/Service。 ## Capabilities ### New Capabilities - `chat-diagnosis-stategraph-routing-skeleton`：提供未接生产入口的 StateGraph 状态、拓扑、路由、有限循环和编排 trace 构造能力。 ### Modified Capabilities - 无。阶段 0 设计基线保持不变；如果实现发现 API 冲突，必须先回写本 change，而不是静默改变基线语义。 ## Scope ### In Scope - 包 `com.superbiz.agent.graph.diagnosis` 下的纯 Java Graph 骨架。 - `pom.xml` 中 Graph Core 的直接编译依赖；版本继续由现有 BOM 锁定为 1.1.2.0。 - Planner、Executor、Gatekeeper、Verified Input、Verifier、Evidence Retry、Composer、Fallback Node action ports。 - `orchestration_events` Append 策略和紧凑 trace builder。 - Fake Node route tests，使用 `RunnableConfig.threadId` 执行。 - recursion limit=32；业务计数仍是主要终止机制。 ### Out of Scope - ReactAgent Adapter、Prompt、ToolCallback、Skill 或模型调用。 - 调用 `ExecutorGatekeeperService` 或读取数据库 ToolInvocation。 - 修改 `ChatService`、`VerifierInputHook`、`VerifierContextHolder`。 - Flyway、`DiagnosisRun`、Trace DTO/API 或持久化。 - 删除旧 Sequential 实现或测试。 - Maven E2E、`logs/` 和数据库核验。 ## Context Constraints - 必须引用阶段 0 archive，不得改变其路由、安全或 run ownership 语义。 - 使用本地已验证的 Graph Core `1.1.2.0` API，不依赖未锁定版本示例。 - Graph action ports 使用 `AsyncNodeActionWithConfig`，为阶段 2 显式传递 run config 留出接口。 - Executor 不重试；Planner/Verifier/Composer 各最多一次技术重试；整个 Run 最多一次 evidence retry。 - Unknown/null status 必须 fail closed 到 Fallback。 - Fake nodes 只存在于测试代码，生产骨架不得包含模拟业务输出。 - 阶段 1 不改变任何外部 API 或当前生产路径。 ## Acceptance - Graph 可编译，默认 Replace、events Append，recursion limit 为 32。 - PASS 正常路径到 Composer/END，events 与 transitions 顺序一致。 - Planner INVALID_OUTPUT/RETRYABLE_FAILED 首次自重试，第二次或 NON_RETRYABLE_FAILED Fallback。 - Executor COMPLETED 进入 Gatekeeper；INVALID_OUTPUT/TOOL_BLOCKED/FAILED Fallback 且从不重试。 - Gatekeeper PASS 和有 binding 的 LOW_CONFID 进入 Verified Input；REJECT、unknown、零 binding LOW_CONFID Fallback。 - Verifier 技术失败首次自重试；PASS/REJECT 到 Composer；满足全部 guard 的 LOW_CONFID 只补证据一次；其余 LOW_CONFID 到 Composer。 - Composer 技术失败首次自重试，耗尽或不可重试进入 Fallback。 - Evidence retry 进入新 Planner 阶段时重置 planner retry count，且不影响其他技术计数。 - 每个测试路径能构造 bounded orchestration trace，无未定义条件边或无限循环。 - focused unit tests 和 Maven test-compile 通过；不运行 Maven E2E。 ## Risks - Graph Core 的 state merge/conditional-edge 细节可能与 API 签名表面不同；用真实 CompiledGraph Fake Node tests 验证。 - Node action 若忘记写 status/event，路由必须 fail closed，测试覆盖 null/unknown。 - 通用骨架若掺入真实 Agent 语义会污染阶段边界；本 change 只定义 ports 和确定性路由。 - 32 次 recursion limit 是保险，不替代显式计数。