docs(openspec): archive stategraph design freeze

2026-07-17 10:24:13 +08:00
parent a36fe72639
commit 581daffdad
15 changed files with 1167 additions and 57 deletions
@@ -103,6 +103,11 @@
 - 使用场景：Trace API、Trace UI、Verifier 审计、评测 fixture 和人工排查。
 - 边界：Diagnosis Trace 是聚合视图，不要求单独的 trace 主表；当前 trace 明细由 `agent_step` 和 `tool_invocation` 表承载。

+### Diagnosis Orchestration Trace
+- 定义：一次 Diagnosis Run 的紧凑编排审计摘要，记录实际节点路径、条件边原因、技术重试、降级和终止原因。
+- 使用场景：解释诊断编排为何进入某个节点、为何重试或为何提前终止，并支撑路由验收和人工审计。
+- 边界：它是 Diagnosis Trace 的编排维度，不是完整事件日志、自评估结果或持久恢复检查点；不保存 Prompt、模型思考、工具原文和完整编排上下文快照。
+
 ### Flyway
 - 定义：数据库版本迁移工具，管理 SQL 脚本的版本化执行
 - 配置：spring.flyway.enabled=true, baseline-on-migrate=true
@@ -156,14 +161,14 @@
 - 边界：最终诊断结论必须被 evidence tools 支撑，不能仅由 skill 正文支撑。

 ### Verifier Skill Isolation
- 定义：Chat Verifier 与 skill 系统隔离，只校验 Executor 答案和 `tool_trace_summary`。
+- 定义：Chat Verifier 与 skill 系统隔离，只校验 Gatekeeper 投影后的 `verified_executor_output` 和 `verified_evidence`。
 - 使用场景：防止 Verifier 把 playbook 指令当作事实证据；Verifier 只判断已有证据是否支持结论。
- 边界：Verifier 不接收 `skill_catalog`，不暴露 `read_skill`，不读取 `SKILL.md`。
+- 边界：Verifier 不接收 `skill_catalog`，不暴露 `read_skill`，不读取 `SKILL.md`、完整 `tool_trace_summary` 或未经验真的 Executor 自由文本。

 ## Diagnosis Playbook Business Rules

 - Planner 只看 skill metadata，输出 `selected_skill`、`selection_reason` 和 plan。
 - Executor 才能调用 `read_skill(selected_skill)`，并且读取 skill 后仍必须调用 evidence tools。
 - Skill 正文不得替代 `lookup_knowledge`、日志、指标或告警数据。
- Verifier 只基于 `tool_trace_summary` 校验事实，不基于 skill 正文校验事实。
+- Verifier 只基于 Gatekeeper 通过的 `verified_executor_output` 和 `verified_evidence` 校验事实，不基于 skill 正文、完整工具 Trace 或未验真输出校验事实。
 - 当前阶段保留单 active skill 白名单：`diagnose-mysql-connection-pool`。
@@ -4,6 +4,7 @@

 | 日期 | slug | 说明 | 领域 | 关键词 | 关联 OpenSpec | 状态 |
 |---|---|---|---|---|---|---|
+| 2026-07-17 | chat-diagnosis-stategraph-design-freeze | 冻结 ISS-011 的 Graph State、条件边、有限重试、安全降级、审计和测试迁移边界。 | Chat diagnosis orchestration/design | StateGraph, runId, Gatekeeper, verified evidence, fallback, orchestration trace, test migration | openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-design-freeze | archived |
 | 2026-07-10 | session-run-trace-isolation | 拆分会话态和运行态，引入 runId 隔离 Trace、Feedback、AIOps 和 demo 链路。 | Trace/session/run isolation | chat_session, diagnosis_run, runId, trace exact run, feedback fallback, AIOps SSE metadata, baseline drift | openspec/changes/archive/2026-07-10-session-run-trace-isolation | archived |
 | 2026-07-09 | interview-demo-quality-audit | 增加面试演示前置质量审计，覆盖 prompt、Gatekeeper 和评测基线。 | Agent eval/demo/Prompt audit | interview demo preflight, prompt_audit, gatekeeper rules, diagnosis baseline, 12 fixtures | openspec/changes/archive/2026-07-09-interview-demo-quality-audit | archived |
 | 2026-07-08 | executor-composer-final-answer | 引入 Composer 生成最终回答，只使用 Verifier 允许的结论材料。 | Chat quality gate/evidence attribution | chat_composer, final answer, allowed_claims, allowed_hypotheses, safe fallback, composer_output | openspec/changes/archive/2026-07-08-executor-composer-final-answer | archived |
@@ -0,0 +1,70 @@
+# Chat Diagnosis StateGraph Design Freeze Acceptance
+
+## 结果
+
+已接受。阶段 0 完成设计冻结，没有修改运行时实现。
+
+## 验证
+
+### 静态验证
+
+- 命令：`git diff --check`
+- 结果：passed
+- 备注：仅有现有 LF/CRLF 提示，无 whitespace error。
+
+- 检查：Git changed/untracked 路径运行时拒绝列表。
+- 结果：passed，12 个路径，`src/`、Maven、运行配置、脚本、数据库迁移命中 0。
+- 备注：阶段 0 只包含 Issue、glossary、OpenSpec/devflow 和执行记录。
+
+- 检查：proposal → design → specs → tasks 四向对齐。
+- 结果：passed，gap=0。
+- 备注：状态、路由、Fallback、审计、测试迁移和六阶段边界均闭环。
+
+### 脚本验证
+
+- 命令：`openspec validate chat-diagnosis-stategraph-design-freeze --type change --strict --json`
+- 结果：passed，1/1。
+- 备注：当前 change 无结构或场景格式问题。
+
+- 命令：`openspec validate --specs --strict --json`
+- 结果：passed，11/11。
+- 备注：归档前主规格基线未回归。
+
+### 浏览器/人工验证
+
+- 结果：not run。
+- 原因：阶段 0 无 UI 或运行行为。
+
+### 未验证
+
+- 单元测试：not run。阶段 0 无代码行为，新增或运行单元测试没有新的验收价值。
+- Maven E2E：not run。用户明确要求仅阶段 5 在全部实现完成后统一执行。
+- `logs/`：not inspected for stage acceptance；保留到阶段 5。
+- 数据库：not queried for stage acceptance；保留到阶段 5。
+- 备注：此前改造前 live baseline 仅为 research，不计入本阶段验收。
+
+## 已完成范围
+
+- 冻结最小 Graph State、所有条件边、四类独立计数和终止路径。
+- 冻结 verified-input、两类 Fallback、Run 状态与 orchestration trace 边界。
+- 冻结 L4 消费者、兼容、迁移、回滚和测试替换策略。
+- 创建 ADR-001，并规定阶段 1–5 引用本阶段 archive。
+- OpenSpec apply tasks 7/7 完成。
+
+## 已知限制
+
+- 运行时仍为旧 Sequential 编排，这是阶段 0 的有意状态。
+- 新设计尚未经过 Graph 编译、Node 单测、Chat 集成或最终 E2E；后续阶段逐项证明。
+- 主运行时 specs 暂时仍描述旧行为，只新增设计基线 capability。
+
+## Bug 修复和诊断
+
+- 更正此前错误流程模型：删除未提交的总 change，改为六个独立 sm-flow/change。
+- 更正此前错误 E2E 门禁：阶段 0–4 不做 E2E，阶段 5 统一验证。
+
+## 交接
+
+- 下一步：阶段 0 Git commit；提交完成后才能创建阶段 1 change。
+- Delta sync：新增 `chat-diagnosis-stategraph-design-freeze` 主 spec，共 6 个 requirements，无现有 spec 修改/删除。
+- OpenSpec 归档确认：用户已在目标中明确要求每阶段 archive，并在后续澄清中再次确认，视为已授权。
+- OpenSpec 归档结果：已同步主 spec，并归档到 `openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-design-freeze/`。
@@ -0,0 +1,27 @@
+# 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` 列；不得用配置重新形成长期双轨。
@@ -0,0 +1,20 @@
+# Chat Diagnosis StateGraph Design Freeze Brief
+
+## 背景
+
+- 用户目标：将 ISS-011 阶段 0–5 分别作为独立 sm-flow，前一阶段 archive 并 Git commit 后才进入下一阶段。
+- 当前问题：复杂 Chat 的跨 Agent 状态机分散在 ChatService、SequentialAgent、VerifierInputHook 和 ThreadLocal 中；实现前需先冻结统一设计。
+- 关联 OpenSpec：`openspec/changes/chat-diagnosis-stategraph-design-freeze/`
+- devflow 分档：complex
+
+## 范围
+
+- 本次要做：冻结最小 Graph State、完整路由、有限重试、安全 Fallback、run-scoped 审计、L4 接口影响和测试替换边界。
+- 本次不做：任何 Java、SQL、Prompt、配置、运行时 spec 或运行行为修改；不运行 Maven E2E。
+- 影响区域：ISS-011、glossary、OpenSpec 设计基线、阶段 0 ADR 和后续五阶段交接契约。
+
+## OpenSpec 对齐
+
+- proposal 覆盖状态：已覆盖阶段 0 目标、范围、非目标、验收和风险。
+- specs 覆盖状态：新增设计基线 capability，不提前修改运行时 capabilities。
+- tasks 覆盖状态：7/7 完成，且仅包含文档、ADR 和静态验证。
@@ -0,0 +1,120 @@
+# Chat Diagnosis StateGraph Design Freeze Decisions
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | Diagnosis Orchestration Trace 与 Diagnosis Trace、self evaluation、Graph checkpoint 的边界是什么？ | evidence-driven | 已解决 |
+| Q2 | 边界 | ISS-011 是一个总 sm-flow，还是阶段 0–5 各自独立 sm-flow？ | user-interview | 已解决 |
+| Q3 | 验收 | Maven E2E 在每阶段执行还是只在最终阶段执行？ | user-interview | 已解决 |
+| Q4 | 验收 | 每阶段是否强制新增并运行单元测试？ | user-interview | 已解决 |
+| Q5 | 技术 | 锁定的 StateGraph 版本是否提供条件边、config-aware Node/Edge、recursion limit 和 threadId？ | evidence-driven | 已解决 |
+| Q6 | 架构 | Gatekeeper、Verifier 输入与 Composer 的可信材料边界应复用什么现有契约？ | evidence-driven | 已解决 |
+| Q7 | 接口 | 阶段 0 本身和最终设计分别属于什么接口影响等级？ | evidence-driven | 已解决 |
+| Q8 | 归档 | 每阶段是否应在进入下一阶段前独立 archive 和 Git commit？ | user-interview | 已解决 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| Orchestration Trace 是 run 级紧凑编排摘要，不是事件日志、自评估或 Graph checkpoint | `devflow/glossary/CONTEXT.md`、ISS-011 §7.5、session-run-trace-isolation decisions | 已汇报 |
+| Gatekeeper 从 Hook 迁为显式 Node 是有意替换旧内部架构，不允许双入口 | executor-gatekeeper-hook decisions、ISS-011 §2.3/§7.2/§14 | 已汇报 |
+| Verifier verified evidence 必须来自 Gatekeeper 通过的 checked bindings；Composer 不得读取 raw Executor/tool output | verifier-evidence-reference-fidelity、executor-composer-final-answer 历史档案、ISS-011 §7.4 | 已汇报 |
+| 本地 1.1.2.0 API 支持条件边、config-aware Node/Edge、recursion limit、RunnableConfig.threadId 和 ReactAgent.call(input, config) | Maven dependency tree 与本地 JAR `javap` 研究记录 | 已汇报 |
+| 阶段 0 是文档/规格交付，无运行时接口变化；其冻结的最终目标涉及状态机、DB 和 Trace API，属于 L4 | sm-flow operating-rules、ISS-011 §10/§14 | 已汇报 |
+| 主 OpenSpec 的外层 groundedness round、Hook Gatekeeper 和完整 tool_trace_summary 输入与冻结设计冲突 | `openspec/specs/chat-verifier-agent/spec.md` 等主规格 | 已汇报 |
+
+## User-interview
+
+| 问题原文 | 用户原话 | 确认状态 | OpenSpec 回写 |
+|---|---|---|---|
+| ISS-011 的阶段关系如何映射 sm-flow？ | “iss-011里每个阶段，都是一个sm-flow，而不是将一整个iss-011打包进一个sm-flow中” | 已确认 | 已回写 proposal 范围与非目标 |
+| Maven E2E 何时执行？ | “端到端只在最后阶段全部完成后才验证” | 已确认 | 已回写 acceptance 与 out of scope |
+| 阶段单元测试是否强制？ | “每个阶段如果有必要添加单元测试验收的话，就加，没有必要的话就跳过单元测试” | 已确认 | 已回写 acceptance |
+| 每阶段如何进入下一阶段？ | “每个阶段需要归档完并提交才能进入下一个阶段” | 已确认 | 已回写阶段门禁 |
+
+## OpenSpec Input Context
+
+### devflow index
+
+已命中并读取：
+
+- `session-run-trace-isolation`
+- `executor-gatekeeper-hook`
+- `verifier-evidence-reference-fidelity`
+- `executor-evidence-output-contract`
+- `executor-v2-output-contract`
+- `executor-verifier-claim-checks`
+- `executor-composer-final-answer`
+- `mvp-demo-trace-acceptance`
+
+### Historical constraints entering OpenSpec
+
+- `runId` 是运行态和 Trace 的所有权边界。
+- AgentStep、ToolInvocation 与 self evaluation 的既有 run 绑定必须保留。
+- checked binding 是 verified evidence 的复用来源。
+- Composer 的 allowed-material 安全边界不得削弱。
+- 旧 Gatekeeper-in-Hook 决策在本设计中被显式废止，不能保留并行入口。
+- 主 OpenSpec 的旧运行时要求只能在对应实现阶段修改，阶段 0 不提前宣称代码已切换。
+
+## Key Decisions
+
+### 六个独立交付单元
+
+阶段 0–5 分别使用独立 slug、OpenSpec change、devflow 项目、Archive 和 Git commit。前一 change 归档并提交后才创建下一 change。
+
+### 阶段 0 不承载后续实现
+
+阶段 0 只冻结设计并归档长期上下文。阶段 1–5 的代码、数据库、测试和清理任务不进入本 change 的 tasks。
+
+### 验收分层
+
+阶段 0 没有运行时行为变化，不新增或运行单元测试，也不运行 Maven E2E。验收使用 OpenSpec strict validation、结构检查和文档一致性检查。Maven E2E、`logs/` 与数据库只在阶段 5 统一执行。
+
+### 接口影响
+
+- 当前 change：L1 文档/设计交付，不改变调用方可观察行为。
+- 冻结目标：L4，涉及内部状态机语义、Trace API 加字段、数据库契约、迁移和回滚。
+- 兼容：保持 `/api/chat` 和 Agent 输出协议；Trace API 为加法式 run 字段。
+- 回滚：后续运行时代码可按阶段 Git revert；nullable DB 列可保留，不引入双轨配置。
+- 消费者：ChatController/ChatService、Trace DTO/Service/UI/demo、数据库迁移、评测与运维审计。
+
+## Risks Accepted
+
+- 阶段 0 archive 后，冻结设计已完成但运行时仍为旧 Sequential；这是有意的阶段性状态。
+- 六个 changes 的一致性由后续每次 context/commit gate 读取并审计本档案保证。
+- 不为阶段 0 的纯设计变更新增无行为价值的单元测试。
+
+## Cross-Artifact 对齐检查
+
+| 上游 → 下游 | 检查内容 | 状态 |
+|---|---|---|
+| brief/prd → proposal | Issue 的阶段 0 目标、范围、非目标和验收已进入 proposal | 已对齐 |
+| proposal → 设计产物 | 状态、路由、重试、Fallback、审计、测试迁移和六阶段边界均进入 design | 已对齐 |
+| 设计产物 → specs/tasks | L4 影响、安全边界、终止规则和阶段 0 文档工作均进入 spec 或 tasks | 已对齐 |
+| specs → tasks | 设计基线、源文档、ADR、严格验证和无运行时变更检查均有可执行任务 | 已对齐 |
+
+Gap：无。
+
+## Architecture Audit
+
+输入链为 `ChatController -> ChatService`，目标处理链为 Run 生命周期 → Graph orchestrator → 白名单 Agent/Java Nodes，输出仍为 `ChatResult + DiagnosisRun + exact RunTrace`。Graph State 只属于当前 run，verified evidence 只来自当前 run 的 passed checked bindings，编排摘要只写当前 Diagnosis Run。旧“Gatekeeper stays in VerifierInputHook”决策被 ISS-011 的显式 Node 有意替代，但旧 Gatekeeper 规则本身继续复用；旧“不新增 trace 主表”和 run ownership 决策保持成立。主要耦合风险是 Hook/Node 双执行、阶段性主 spec 漂移和 Trace 投影重复，design 已分别通过单入口迁移、按阶段修改运行时 specs、唯一 `run.orchestrationTrace` 投影缓解。架构风险已由用户确认的 ISS-011 冻结决策和六阶段交付口径接受，无需返回 grill。
+
+## Commit Preflight
+
+- proposal、design、specs、tasks 完整：通过。
+- 所有 user-interview 已确认：通过。
+- 未汇报 evidence-driven 结论：无。
+- L4 接口影响、消费者、兼容、迁移和回滚：已在 design 独立章节记录。
+- OpenSpec strict validation：change 1/1 通过，主 specs 11/11 通过。
+- Apply 授权：用户启动目标时要求分阶段完整执行、archive 和 Git commit，后续又确认六个独立 sm-flow；视为当前阶段连续执行授权。
+
+## Apply Evidence
+
+- Task 1.1：ISS-011 §3–14 与 committed design 的 State 字段、条件边、四类计数、Fallback、安全审计和测试迁移语义一致；未发现需回写 OpenSpec 的 drift，未修改运行时代码。
+- Task 1.2：将 glossary 中新 Orchestration Trace 的具体 StateGraph/Graph State 表述收敛为“诊断编排/编排上下文快照”；Verifier 的 verified-output/evidence 名称作为跨节点协议保留。
+- Task 2.1：创建 ADR-001，记录 StateGraph 控制边界、显式 Gatekeeper、run-scoped trace、替代方案、兼容、迁移和回滚。
+- Task 2.2：六个独立 change 的唯一边界已写入 design、design-baseline spec、ADR 和根计划；阶段 1–5 必须引用阶段 0 archive。
+- Task 3.1：最终 strict validation 为 change 1/1、主 specs 11/11；proposal/design/spec/tasks 对状态、Fallback、审计、运行时非目标和测试迁移均形成闭环，cross-artifact gap 为 0。
+- Task 3.2：Git 枚举 12 个 changed/untracked 路径，运行时拒绝列表命中 0；无 `src/`、Maven、运行配置、脚本或数据库迁移变更。
+- Task 3.3：单元测试未运行，因为阶段 0 无代码行为；Maven E2E、`logs/` 和数据库核验未运行，因为用户明确要求只在阶段 5 全部实现后统一执行。改造前 research baseline 不计入阶段验收。
@@ -0,0 +1,30 @@
+# Chat Diagnosis StateGraph Design Freeze Evidence
+
+## 证据
+
+| 来源 | 证据 | 结论 | 是否已汇报 |
+|---|---|---|---|
+| ISS-011 §3–14 | 已定义目标流程、26 个 State 字段、有限回边、Fallback、Trace 和测试策略 | 可形成无开放分支的阶段 0 设计基线 | 是 |
+| `ChatService` / Controller 引用核查 | 生产链为 Controller → ChatService → SequentialAgent，细粒度状态散布在 ChatService | StateGraph 应只接管 Run 内控制，ChatService 保留生命周期 | 是 |
+| `VerifierInputHook` / `VerifierContextHolder` 引用核查 | Gatekeeper、工具摘要和解析结果通过 Hook/ThreadLocal 隐式传播 | Gatekeeper 与 verified-input 必须迁为显式 Node，不能保留双入口 | 是 |
+| executor-gatekeeper-hook 历史 decisions | 旧阶段曾决定 Gatekeeper 留在 Hook 且不重试 | 本设计有意替换入口，但继续复用确定性规则 | 是 |
+| session-run-trace-isolation 历史 decisions | runId 是执行/Trace 所有权边界，AgentStep/ToolInvocation 已承载明细 | orchestration trace 只附着当前 Run，不新增明细主表 | 是 |
+| Verifier/Composer 历史档案 | checked bindings 和 allowed material 是可信边界 | Builder 不重复验真，Fallback 不泄漏 raw claim | 是 |
+| 本地 Graph Core 1.1.2.0 JAR | 已验证条件边、config-aware Node/Edge、recursion limit、threadId 与 Agent call API | 阶段 1 可基于锁定签名实现，不采用网上漂移示例 | 是 |
+| 主 OpenSpec 核查 | 旧 spec 仍描述 Hook Gatekeeper、完整 tool trace 和外层 groundedness round | 阶段 0 不提前改运行时 spec，后续对应实现阶段再修改 | 是 |
+| 用户原话 | 六个独立 sm-flow；仅阶段 5 E2E；单测按必要性 | 阶段门禁与测试口径已固定 | 是 |
+
+## Evidence-driven 结论
+
+- 结论：阶段 0 运行时影响为 L1，但冻结目标为 L4。
+  - 证据：本阶段 changed paths 无 `src/`/SQL/配置；最终目标改变状态机、Trace API 和 DB。
+  - 风险：设计完成不等于运行时完成。
+  - 用户确认：已确认分阶段交付。
+- 结论：旧 Gatekeeper-in-Hook 决策应被显式 Node 有意替代。
+  - 证据：当前 Hook 引用与 ISS-011 条件边要求冲突。
+  - 风险：迁移期双执行。
+  - 用户确认：ISS-011 冻结决策已确认。
+- 结论：阶段 0 不需要单元测试或 E2E。
+  - 证据：Git 运行时拒绝列表命中 0，OpenSpec strict 和文档一致性已覆盖本阶段可观察产物。
+  - 风险：运行时正确性仍未证明，将由阶段 1–5 测试和最终 E2E 证明。
+  - 用户确认：已确认。