Chat Diagnosis StateGraph Routing Skeleton Decisions
Question Pool
| # |
维度 |
问题 |
模式 |
状态 |
| Q1 |
术语 |
阶段 1 的 Graph State、event、trace 含义从哪里继承？ |
evidence-driven |
已解决 |
| Q2 |
边界 |
阶段 1 是否接入 ChatService 或真实 Agent/Service？ |
evidence-driven |
已解决 |
| Q3 |
技术 |
锁定 1.1.2.0 是否支持所需 Node/Edge、策略和 recursion limit？ |
evidence-driven |
已解决 |
| Q4 |
技术 |
Node action port 是否需要 RunnableConfig？ |
evidence-driven |
已解决 |
| Q5 |
验收 |
阶段 1 是否有必要添加单元测试？ |
evidence-driven + user rule |
已解决 |
| Q6 |
接口 |
新骨架的接口影响等级与消费者是什么？ |
evidence-driven |
已解决 |
| Q7 |
循环 |
recursion limit 应取多少，是否替代业务计数？ |
evidence-driven |
已解决 |
| Q8 |
阶段 |
是否在本 change 实现真实 nodes、DB、Trace API 或旧代码清理？ |
user-interview（已由六阶段口径确认） |
已解决 |
Evidence-driven
| 结论 |
证据来源 |
是否已汇报用户 |
| 阶段 1 必须完整继承阶段 0 baseline |
archived design/spec/ADR |
已汇报 |
| 本阶段只做 Fake Node 骨架，不接真实模型 |
ISS-011 阶段 1/2 边界 |
已汇报 |
| 1.1.2.0 支持 AsyncNodeActionWithConfig、AsyncEdgeActionWithConfig、conditional edges、Replace/Append、recursionLimit 和 threadId |
本地 JAR javap / javap -c |
已汇报 |
| AppendStrategy 将 list/collection 追加为有序列表，可用于 node terminal events |
本地 AppendStrategy bytecode |
已汇报 |
| 路由是新增行为且分支多，单元测试有必要 |
阶段 1 完成标准与用户“必要则加”规则 |
已汇报 |
| 最坏合法路径少于 20 次 Node 执行，limit 32 有安全余量 |
冻结路由矩阵的路径计数 |
已汇报 |
| 当前仓库没有 Graph 包或实现 |
rg / package 目录核查 |
已汇报 |
| 生产代码将直接 import Graph Core，必须从传递依赖提升为 BOM 管理的直接依赖 |
pom 与 dependency tree / 架构审计 |
已汇报 |
User-interview
| 问题原文 |
用户原话 |
确认状态 |
OpenSpec 回写 |
| 阶段 1 是否应独立执行 sm-flow？ |
“iss-011里每个阶段，都是一个sm-flow” |
已确认 |
本 change 独立边界 |
| 阶段 1 是否执行 E2E？ |
“端到端只在最后阶段全部完成后才验证” |
已确认 |
Out of Scope / Acceptance |
| 阶段 1 是否添加单元测试？ |
“如果有必要添加单元测试验收的话，就加” |
已确认规则；本阶段判定必要 |
Acceptance |
| 是否可提前实现阶段 2–5？ |
“每个阶段需要归档完并提交才能进入下一个阶段” |
已确认不可提前 |
Out of Scope |
Context And Handoff
- 前置 archive：
openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-design-freeze/
- 前置 commit：
581daff
- 当前 change：
chat-diagnosis-stategraph-routing-skeleton
- 后续 change：
chat-diagnosis-stategraph-real-nodes，只能在本阶段 archive + commit 后创建。
Technical Decisions
Package and API
- 新包：
com.superbiz.agent.graph.diagnosis。
pom.xml 显式声明 Graph Core，版本继续由现有 BOM 管理。- Graph 工厂接收 config-aware Node action ports，不依赖 Spring Bean 或真实 Agent。
- Fake actions 只放
src/test。
- 状态读取集中在 typed helper/router，避免各 edge 复制字符串解析。
Retry ownership
- Planner/Verifier/Composer Node wrapper 根据进入节点前的上次技术失败状态增加各自 retry count。
- 第一次失败时 count=0，允许 self-loop；重入后 count=1，第二次失败直接 Fallback。
- Evidence Retry Node 将 run-level evidence count 增加一次并重置 planner retry count。
- Edge 只选择 route，不隐式修改状态。
Event and trace
- 每个 Fake/后续真实 Node 返回一个 event list，AppendStrategy 负责累积。
- event 包含 node/outcome/reasonCode/attempt，不包含 payload。
- trace builder 由相邻 events 生成 transition；final node/reason 来自最后 event。
- events 为空时拒绝构造 trace，避免伪造路径。
Interface impact
- 等级：L2 internal interface。
- 新消费者：阶段 2 Node adapters、阶段 3 ChatService orchestrator、阶段 4 tests。
- 外部 API/DB/运行路径：无变化。
- 回滚：revert 本阶段提交即可；因为未接生产入口，没有数据迁移。
- 兼容：后续 action adapters 必须实现已冻结 ports，不得传递父 State 全量数据。
Risks Accepted
- Stage 1 skeleton 会暂时存在但未被生产调用，这是阶段边界要求，不是死代码最终状态。
- 真实 Agent 状态映射尚未验证，由阶段 2 独立 change 负责。
- Maven E2E 不运行，生产路径完全未改变。
Apply Evidence
- Task 1.1：显式声明 BOM 管理的 Graph Core；新增 26 个 state keys、状态枚举、拓扑/route/reason 常量、默认 Replace + events Append 策略和安全 typed reads。
- Task 1.2：新增不可变 event/transition/trace records，构造期拒绝空 routing metadata 和非法计数，map 输出只有冻结字段。
- Task 2.1：新增八个 non-null config-aware action ports，Fake/真实 Node 共用同一 Graph 接入面。
- Task 2.2：新增纯 router；所有未知/缺失状态 fail closed，LOW_CONFID guard 只读 facts_checked，不构造 retry context。
- Task 2.3：Graph Factory 注册八节点和全部条件边；wrapper 独占 retry/evidence control state，compile recursion limit=32。
- 首模块 Maven compile：passed（31s），锁定 1.1.2.0 API 假设成立。
- Task 3.1：trace builder 从 event 单向派生 transitions/final reason/degraded/evidence count，空或异类 events 显式失败。
- Task 4.1：新增严格 FIFO Fake Node fixture，记录 sequence/calls/threadId，每 attempt 只追加一个 terminal event，意外调用立即失败。
- Task 4.2：真实 CompiledGraph normal/Planner/Executor/Gatekeeper focused tests 首轮通过（Maven exit 0，约 67s）。
- Task 4.3：Verifier/evidence/Composer 路由与独立计数测试通过（Maven exit 0，约 12s）。
- Task 4.4：routing + trace focused suite 通过（Maven exit 0，约 28s），覆盖事件顺序、degraded、map 白名单、不可变性和非法输入。
- Task 5.1：35 tests（29 routing + 6 trace）全通过；Maven test compilation、change strict 1/1、主 specs 12/12、diff check 均通过。
- Task 5.2：现有 production refs=0，新 Graph 对真实 Service/DB/Trace refs=0，23 个 changed paths 全部命中阶段白名单；Maven E2E/log/DB 按用户口径保留到阶段 5。
- Review：补齐所有正常节点 threadId 传播、Verifier REJECT→Composer 和 completed-without-verdict fail-closed 用例；增强后 focused suite exit 0。
Cross-Artifact 对齐检查
| 上游 → 下游 |
检查内容 |
状态 |
| brief/prd → proposal |
阶段 1 目标、Fake Node 边界、测试口径和 E2E 非目标 |
已对齐 |
| proposal → 设计产物 |
direct dependency、状态、ports、router、counter、trace、测试架构 |
已对齐 |
| 设计产物 → specs/tasks |
所有可观察路由、终止、安全默认和实现模块 |
已对齐 |
| specs → tasks |
编译、全路由、trace、focused tests、生产隔离检查 |
已对齐 |
Gap：无。
Architecture Audit
输入是 run-scoped 初始 state 与 RunnableConfig，处理链是 CompiledGraph → config-aware action ports → deterministic router/counters，输出是最终 state 与纯路由 trace；阶段 1 没有 Controller/Service/DB 消费者。Graph State 由单次 invoke 所有，events 只由 Node append，transitions 只由 builder 派生，避免双写。阶段 2 只实现 action ports，阶段 3 才将 orchestrator 交给 ChatService，因此当前未接生产入口是刻意生命周期边界。审计发现的唯一缺口是 Graph Core 直接依赖所有权，已回写 proposal/design/tasks。与阶段 0 archive 无冲突，L2 风险可由 Fake Node CompiledGraph tests 和 revert 单提交控制。
