78 lines
4.9 KiB
Markdown
78 lines
4.9 KiB
Markdown
# Chat Diagnosis StateGraph Design Freeze
|
||
|
||
## Why
|
||
|
||
ISS-011 将复杂 Chat 诊断从 `SequentialAgent + ChatService` 隐式状态机迁移到 Spring AI Alibaba `StateGraph`。在进入任何运行时代码实现前，需要先把跨节点状态、全部条件边、有限重试、安全降级、审计边界和旧测试替换范围冻结为单一、可引用的设计契约，避免后续五个独立 sm-flow 对同一行为产生不同解释。
|
||
|
||
## What Changes
|
||
|
||
本 change 只交付阶段 0 的设计冻结：
|
||
|
||
- 冻结最小 Graph State 及 Replace/Append 更新策略。
|
||
- 冻结 Planner、Executor、Gatekeeper、Verifier、Composer、Evidence Retry、Fallback 的全部条件边和终止路径。
|
||
- 冻结 Planner/Verifier/Composer 技术重试与 evidence retry 的独立计数和最大次数。
|
||
- 冻结 Gatekeeper 后的 Verifier 白名单输入、安全 Fallback 和 Run 状态语义。
|
||
- 冻结 `orchestration_events -> diagnosis_run.orchestration_trace -> run.orchestrationTrace` 的审计边界。
|
||
- 冻结旧 Sequential 测试的替换范围和必须保留的安全回归边界。
|
||
- 形成供阶段 1–5 各自独立 OpenSpec change 引用的长期决策记录。
|
||
|
||
本 change 不修改 Java、SQL、Prompt、配置或运行时行为。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `chat-diagnosis-stategraph-design-freeze`：为阶段 1–5 提供版本化、可审计的 StateGraph 设计基线，覆盖状态、路由、重试、安全降级、审计和测试迁移边界。
|
||
|
||
### Modified Capabilities
|
||
|
||
- 无。当前运行时 capabilities 只在对应实现阶段修改，避免阶段 0 归档后主规格提前宣称代码已切换。
|
||
|
||
|
||
## Scope
|
||
|
||
### In Scope
|
||
|
||
- `mvp/issues/active/ISS-011-chat-diagnosis-stategraph-orchestration.md` 中阶段 0 的设计结论。
|
||
- `devflow/glossary/CONTEXT.md` 中 Diagnosis Orchestration Trace 和 Verifier verified-evidence 边界。
|
||
- 阶段 0 的 OpenSpec 设计、设计验收 spec、可执行文档任务和 devflow/ADR 档案。
|
||
- 对最终目标的 L4 接口影响、迁移、回滚、兼容性与消费者边界做设计级记录。
|
||
|
||
### Out of Scope
|
||
|
||
- 创建 StateGraph、Node、Adapter、路由或测试代码。
|
||
- 修改 ChatService、Hook、Gatekeeper、Agent、Prompt 或工具。
|
||
- 数据库迁移和 Trace DTO/API 修改。
|
||
- 运行 Maven E2E、日志核验或数据库核验。
|
||
- 把阶段 1–5 的实现任务放入本 change。
|
||
- SupervisorAgent、持久 Checkpointer、HITL、并行 Agent/工具或 AIOps 公共 Graph。
|
||
|
||
## Context Constraints
|
||
|
||
- `runId` 是一次 Diagnosis Run 与 Trace 的所有权边界；编排摘要不得写入 session 级数据。
|
||
- Gatekeeper 引用真实性检查和 `checked_bindings` 是 verified evidence 的唯一事实来源，不得在 Verifier Input Builder 重复实现另一套验真规则。
|
||
- Composer 只能消费 Verifier 允许材料；前置验证失败的固定 Fallback 不得泄漏 Executor claim。
|
||
- `/api/chat`、`executor_evidence_v2`、Verifier 输出协议和 Composer 输出协议保持兼容。
|
||
- 最终 Trace API 只在 `run.orchestrationTrace` 增加解析对象；数据库只新增 nullable JSON `diagnosis_run.orchestration_trace`。
|
||
- 不保留长期 Sequential/StateGraph 双轨或运行时切换开关。
|
||
- 锁定依赖版本 `spring-ai-alibaba-graph-core:1.1.2.0` 已通过本地 JAR API 核验，后续实现不得使用未经锁定版本验证的示例签名。
|
||
|
||
## Acceptance
|
||
|
||
- 最小 Graph State 中每个字段都有所有权、用途和更新策略。
|
||
- 每个节点状态都有唯一条件边；所有循环均有显式上限和终止路径。
|
||
- Planner、Verifier、Composer 技术重试各自最多一次，且与最多一次 evidence retry 分开计数。
|
||
- Executor 不重试；Gatekeeper REJECT 与零可信 binding 直接进入不泄漏 claim 的固定 Fallback。
|
||
- PASS 与可继续的 LOW_CONFID 都经过 verified-input builder；Verifier 不接收完整 `tool_trace_summary`。
|
||
- `orchestration_trace`、`self_evaluation`、`agent_step`、`tool_invocation` 和 Graph checkpoint 的职责不重叠。
|
||
- 旧测试替换清单明确区分应替换的实现测试与必须保留/扩展的契约测试。
|
||
- 不存在“待讨论决策”、未定义循环或没有终止路径的分支。
|
||
- 本阶段无运行时变化，因此不新增或运行单元测试；使用 OpenSpec strict validation、结构检查与文档一致性检查验收。
|
||
|
||
## Risks
|
||
|
||
- 阶段 0 只冻结设计，主分支运行时仍是 Sequential；后续阶段不得把设计文档状态误认为已实现状态。
|
||
- 六个独立 changes 可能发生契约漂移；每个后续 Discover 必须读取本 change 的 archive 和 devflow 决策，并在 Commit gate 对照冻结契约。
|
||
- 现有主 OpenSpec 仍描述旧 `tool_trace_summary` 和外层 LOW_CONFID round；只有对应运行时切换阶段才能修改并归档这些运行时 specs。
|
||
- 最终设计属于 L4 影响；阶段 0 必须记录迁移/回滚，但不能以文档完成替代后续代码和最终 E2E 证据。
|