SuperBizAgent-java/openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-routing-skeleton/design.md

Context

阶段 0 已归档 StateGraph 设计基线，当前仓库仍没有 Graph 实现。阶段 1 只引入可编译、可用 Fake Node 执行的内部骨架，不连接 Spring Bean、ChatService、真实 Agent 或数据库。

锁定依赖 spring-ai-alibaba-graph-core:1.1.2.0 已通过本地 JAR 验证：

• StateGraph.addNode(... AsyncNodeActionWithConfig)
• StateGraph.addConditionalEdges(... AsyncEdgeActionWithConfig, mappings)
• CompileConfig.builder().recursionLimit(...)
• KeyStrategyFactoryBuilder、ReplaceStrategy、AppendStrategy
• CompiledGraph.invoke(input, RunnableConfig)
• RunnableConfig.builder().threadId(...)

阶段 2 将消费 Node action ports，阶段 3 将消费 compiled graph。阶段 1 自身没有生产调用方。

Goals / Non-Goals

Goals:

• 建立明确的状态、状态枚举、节点、route 和 reason code 常量。
• 建立 config-aware Node action ports 和可编译 Graph 工厂。
• 以冻结计数和 guard 实现完整条件边。
• 验证 AppendStrategy 和实际 CompiledGraph 行为。
• 从有界 events 构造确定性的 orchestration trace。
• 用 Fake Node 测试所有路由和终止边界。

Non-Goals:

• 不接 ReactAgent、Gatekeeper Service、ToolTrace 或 Prompt。
• 不修改 ChatService、Hook、ThreadLocal 或生产 Spring 配置。
• 不持久化 trace，不修改 DB/DTO/API。
• 不删除旧 Sequential 实现或测试。
• 不运行 Maven E2E。

Decisions

1. Package and class boundaries

新代码位于 com.superbiz.agent.graph.diagnosis：

类型	职责
DiagnosisGraphState	26 个 state key、默认 Replace + events Append strategy、typed reads
DiagnosisGraphStatus	Planner/Executor/Gatekeeper/Verifier/Composer status、Verdict、PlannerMode
DiagnosisGraphTopology	Node id、route key、reason code 常量
DiagnosisGraphActions	八个 AsyncNodeActionWithConfig ports
DiagnosisGraphRouter	纯确定性 edge guard，不修改 state
DiagnosisGraphFactory	注册 Node/Edge、retry wrapper、evidence retry wrapper、recursion limit
OrchestrationEvent	node/outcome/reasonCode/attempt
OrchestrationTransition	from/to/reasonCode/attempt
DiagnosisOrchestrationTrace	version/transitions/finalNode/terminationReason/degraded/evidenceRetryCount
DiagnosisOrchestrationTraceBuilder	events → transitions/summary

Fake Node 和 script fixture 只存在于 test 源集。

替代方案：把 router 和状态读取放进 ChatService 或每个 Adapter。拒绝，因为会复制 guard 并阻碍 Fake Node 独立验证。

1.1 Direct dependency ownership

代码直接 import Graph Core API，因此 pom.xml 显式声明 com.alibaba.cloud.ai:spring-ai-alibaba-graph-core。版本继续由现有 Spring AI Alibaba BOM 管理为 1.1.2.0，不重复写版本。依赖 Agent Framework 的传递依赖虽可编译，但会让上游依赖图调整无意中破坏本模块，拒绝。

2. State strategy and typed reads

KeyStrategyFactoryBuilder.defaultStrategy(new ReplaceStrategy())，仅对 orchestration_events 使用 new AppendStrategy()。Node 每次返回 List.of(event)，Graph 合并后保持有序列表。

typed reads 对 absent、null、错误类型和未知 enum 返回安全默认，不抛出边路由异常。未知 status/verdict 的路由默认 Fallback。

3. Config-aware action ports

所有 port 使用 AsyncNodeActionWithConfig，即使 Fake Node 当前只需要 state。原因是阶段 2 必须读取 RunnableConfig.threadId/metadata 并向 Agent 传递 run context；现在锁定接口可以避免随后重写 Graph topology。

DiagnosisGraphActions 构造时对八个 action 做 non-null 校验。

4. Retry counter ownership

Edge 只选 route，不修改 state。Factory 用 wrapper 管理计数：

• Planner 重入前，如果上次 planner_status 是 INVALID_OUTPUT/RETRYABLE_FAILED，count + 1。
• Verifier/Composer 同理。
• 第一次失败后的 state count 为 0，允许 self-loop；重入执行后 count 为 1，再失败则 Fallback。
• Evidence Retry Node 完成时将 evidence_retry_count + 1、planner_retry_count=0、planner_mode=EVIDENCE_GAP_ONLY。
• Verified Input Node 完成时重置 verifier_retry_count=0，因为它产生新的 verified input。
• 技术重试不修改 evidence count。

替代方案：由每个 Fake/real action 自行维护计数。拒绝，因为遗漏会造成无限 self-loop，骨架必须拥有控制计数。

5. Conditional routing

Source	Route keys
Planner	executor / retry_planner / fallback
Executor	gatekeeper / fallback
Gatekeeper	verified_input / fallback
Verifier	composer / retry_verifier / evidence_retry / fallback
Composer	end / retry_composer / fallback

Verified Input 固定到 Verifier，Evidence Retry 固定到 Planner，Fallback 固定到 END。

Verifier evidence-retry guard 同时要求：

• verifier_status=COMPLETED
• effective_verdict=LOW_CONFID
• verifier_verdict_ceiling=PASS
• verifier_output.facts_checked 至少一项具有非空 fact 且 verification 为 no_evidence 或 indirect_support
• evidence_retry_count < 1

否则 LOW_CONFID 到 Composer。router 只检查现有 Verifier 输出，不选择工具或构造 retry context；后者属于阶段 2 Evidence Retry Node。

6. Recursion limit

合法最坏路径低于 20 次 Node 执行；compile recursion limit 固定 32。测试断言 compiled graph 的 max iterations/compile config，并覆盖第二次技术失败和第二次 LOW_CONFID 均终止。

recursion limit 是最后保险，不替代业务 guard。

7. Event and trace contract

OrchestrationEvent 构造时拒绝 blank node/outcome/reason 或 attempt<1。每个 Fake/真实 Node attempt 返回一个 event；AppendStrategy 累积实际路径。

Builder：

1. 要求 events 非空且类型正确。
2. 相邻 events 生成 transition，transition reason/attempt 取 source event。
3. 最后 event 决定 finalNode 和 terminationReason。
4. final node 为 Fallback 时 degraded=true；其他质量由 effective verdict 表达。
5. evidence retry count 从 state 读取。
6. toMap() 使用冻结 snake_case 字段，transition 同样提供 map。

不从应用日志推导路径，也不在 state 维护第二份 transitions。

8. Test architecture

DiagnosisGraphRoutingTest 使用真实 CompiledGraph + scriptable Fake actions：

• 每个 node 有 outcome 队列和调用计数。
• Fake action 只输出本 node 的状态字段、必要 guard payload 和一个 event。
• 每个用例使用唯一 RunnableConfig.threadId。
• 断言 node sequence、调用次数、最终 state、events、trace transitions。
• 参数化覆盖同类技术失败，独立用例覆盖 evidence retry/counter reset 和 unknown fail-closed。

DiagnosisOrchestrationTraceBuilderTest 覆盖空 events、非法 event、顺序、fallback degraded 和 map shape。

Interface Impact

• 等级：L2 internal interface。
• 新接口消费者：阶段 2 adapters、阶段 3 orchestrator、阶段 4 test suite。
• 构建消费者：Maven 直接声明 Graph Core，版本仍由既有 BOM 统一管理。
• 当前生产消费者：无。
• 外部 API/DTO/数据库/状态：无变化。
• 兼容策略：后续 actions 实现 ports；Graph State 不直接传给 Agent。
• 回滚：revert 本阶段提交，无数据迁移。

Risks / Trade-offs

• [Graph merge 行为与假设不同] → 使用真实 CompiledGraph 单元测试，不 mock StateGraph。
• [计数 wrapper 与 action 更新冲突] → wrapper 最后写入控制计数，actions 不拥有 retry counters。
• [Verifier gap 解析过早耦合] → router 只识别现有 facts_checked 最小字段，retry context 构造留到阶段 2。
• [未接生产入口被误认为完成] → proposal/spec/acceptance 明确 skeleton-only，阶段 3 才切换。
• [事件无限追加] → 所有业务循环有硬上限且 recursion limit=32。

Migration Plan

1. 添加纯 Java 状态、router、actions、factory 和 trace types。
2. 先用 Fake actions 编译和执行完整 Graph。
3. 阶段 1 archive + commit 后，阶段 2 基于 ports 实现真实 nodes。
4. 如需回滚，revert 阶段 1 commit；当前生产路径不受影响。

Open Questions

无。