feat(graph): add diagnosis routing skeleton

2026-07-17 11:17:13 +08:00
parent 581daffdad
commit 42ba204532
26 changed files with 2455 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 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 是保险，不替代显式计数。