4.5 KiB
4.5 KiB
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_eventsAppend 策略和紧凑 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.0API，不依赖未锁定版本示例。 - 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 是保险，不替代显式计数。