78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# 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 是保险，不替代显式计数。
|