2.3 KiB
ADR-001: StateGraph owns run-scoped diagnosis control
状态：已接受 日期：2026-07-17
复杂 Chat 使用 Spring AI Alibaba StateGraph 管理一次 Diagnosis Run 内的顺序、条件边、有限重试、终止和降级；ReactAgent 只执行 Planner、Executor、Verifier、Composer 的语义任务，Gatekeeper、verified-input builder、evidence retry prepare 和固定 Fallback 使用确定性 Java Node。这样可以精确恢复失败位置并形成可审计路径，同时继续复用现有 Agent、工具和证据协议。
Gatekeeper 从 VerifierInputHook 的隐式执行迁为显式且唯一的 Graph Node。Verifier 只能消费 Gatekeeper passed checked bindings 投影出的 verified_executor_output 和 verified_evidence；前置验证失败的 Fallback 不得输出 Executor claim。
编排审计只属于当前 runId：有界 orchestration_events 压缩后写入 diagnosis_run.orchestration_trace，Trace API 只在 run.orchestrationTrace 暴露解析对象。它不替代 self evaluation、AgentStep、ToolInvocation 或持久 Graph checkpoint，也不新增 trace 明细表。
Considered Options
- 继续在
ChatService外层叠加for/if：拒绝，失败恢复位置、循环上限和路由原因仍然隐式。 - 使用 SupervisorAgent：拒绝，当前是固定诊断 Pipeline，不需要动态选择专科 Agent。
- 直接将父 Graph State 交给
ReactAgent.asNode(...)：首版拒绝，无法证明 messages、outputKey 和私有执行上下文隔离。 - 长期保留 Sequential/StateGraph feature flag 双轨：拒绝，会形成两个编排真理源并增加安全规则漂移。
Compatibility And Migration
/api/chat、executor_evidence_v2、Verifier 和 Composer 输出协议保持不变。Trace API 只增加 run-scoped 字段；数据库只增加 nullable JSON 列，历史 Run 不回填。
实施必须按六个独立 sm-flow/change 依次完成：设计冻结、路由骨架、真实节点、ChatService/Trace 切换、测试体系、清理与最终验收。阶段 1–5 必须读取阶段 0 archive，偏离本 ADR 时通过当阶段 OpenSpec 显式修正。
Rollback
每阶段使用独立 Git commit，可整体 revert 当前阶段。生产切换后回滚代码时允许保留 nullable orchestration_trace 列；不得用配置重新形成长期双轨。