145 lines
13 KiB
Markdown
145 lines
13 KiB
Markdown
# Decisions: single-react-evidence-semantic-guards
|
||
|
||
## Discover Status
|
||
|
||
- Checkpoint: Discover
|
||
- Capability source: `sm-flow`，使用 `grill-with-docs` 做 evidence-driven 澄清；`codebase-retrieval`、LSP 和 GitNexus MCP 在当前会话不可用，降级为既有 GitNexus 研究结论、`rg` 调用点核对和逐文件源码阅读。
|
||
- Scale: complex。变更跨 canonical store、三类 Tool projection、模型预算、超时/取消、结构修复、语义审查和释放边界，但不切换公开协议。
|
||
- `devflow/index.md` 命中阶段 0-4 的设计冻结、RunContext、canonical store、Tool projection 和 Diagnosis Agent；没有与当前 OpenSpec 冲突的 ADR。
|
||
|
||
## Question Pool
|
||
|
||
| # | 维度 | 问题 | 模式 | 状态 |
|
||
|---|---|---|---|---|
|
||
| Q1 | 术语 | EvidenceGuard 是否判断证据足以推出结论？ | evidence-driven | 已解决 |
|
||
| Q2 | 边界 | verified snapshot 能读取哪些 canonical 字段，并向 SemanticGuard 暴露哪些内容？ | evidence-driven | 已解决 |
|
||
| Q3 | 边界 | `NO_EVIDENCE` 能支持哪类 Analysis？ | evidence-driven | 已解决 |
|
||
| Q4 | 修复 | 首次 EvidenceGuard 失败允许如何修复，是否可重跑 Agent 或 Tool？ | evidence-driven | 已解决 |
|
||
| Q5 | 语义 | SemanticGuard 是否拥有 Tool、记忆、ReAct loop 或报告写作能力？ | evidence-driven | 已解决 |
|
||
| Q6 | 重试 | 哪些 SemanticGuard 结果允许第二次 attempt？ | evidence-driven | 已解决 |
|
||
| Q7 | 超时 | 单轮模型超时和 Run 取消如何终止后台调用？ | evidence-driven | 已解决 |
|
||
| Q8 | 释放 | 三种 Fallback 能否包含 Draft、reason 或未验真来源？ | evidence-driven | 已解决 |
|
||
| Q9 | 接口 | 阶段 5 是否切换公开入口或修改 SSE/持久化协议？ | evidence-driven | 已解决 |
|
||
| Q10 | 验收 | 如何证明不存在隐式 Agent/repair/retry loop？ | evidence-driven | 已解决 |
|
||
|
||
## Evidence-driven
|
||
|
||
| 结论 | 证据来源 | 是否已汇报用户 |
|
||
|---|---|---|
|
||
| EvidenceGuard 只验证结构、引用和 canonical invocation 真实性，不判断 Analysis/Conclusion 的语义充分性。 | ISS-014 4.3、阶段 5；glossary `EvidenceGuard` | 已汇报 |
|
||
| Store 只能按 `ToolCallKeyFactory.create(runId, toolCallId)` 查找；可引用记录必须是当前 Run、`READY`、含 `agent_result` 且状态为 `EVIDENCE_FOUND|NO_EVIDENCE`。 | `CanonicalInvocationStore`、`CanonicalToolInvocation.isReferencableBy` | 已汇报 |
|
||
| Snapshot 解析 `agent_result` 和必要的有界 request 字段，不读取 `raw_response`；输出按 `analysis_id` 分组且不包含 Tool Call ID。 | ISS-014 4.4、10.2、已冻结 Tool contracts | 已汇报 |
|
||
| `NORMAL` 只绑定 `EVIDENCE_FOUND`；`NEGATIVE_OBSERVATION` 只绑定 `NO_EVIDENCE`，且零结果范围来自投影/请求。 | ISS-014 4.3、10.2；`EvidenceStatus` glossary | 已汇报 |
|
||
| Evidence repair 只在首次物理验真失败后执行一次无 Tool单轮模型调用，不重跑 Diagnosis Agent 或 Tool loop。 | ISS-014 10.3、阶段 5、重试边界决策 | 已汇报 |
|
||
| SemanticGuard 复用同一 `ChatModel`，使用全新 `Prompt` 单轮调用，无 Tool/记忆/ReAct；只返回二元 verdict 和审计 reason。 | ISS-014 4.4、阶段 5；Spring AI `ChatModel.call(Prompt)` | 已汇报 |
|
||
| 仅超时、传输、解析或 Schema 技术失败可重试一次；`UNSUPPORTED` 是有效业务结果，不重试。 | `HarnessRetryPolicies.strict().semanticGuard()`、ISS-014 重试策略 | 已汇报 |
|
||
| `ChatResponseMetadata.Usage` 可复用 Core 的 model/Token 预算；受控 `Future.get(timeout)` 可在超时或 Run 取消时取消任务。 | `HarnessModelInterceptor`、`DiagnosisHarnessCore`、`RunCancellation` | 已汇报 |
|
||
| `EVIDENCE_VALIDATION_FAILED` 的来源必须为空；其余 Fallback 只能包含已验真来源，不包含 Draft 或 SemanticGuard reason。 | ISS-014 10.3、阶段 5；`SafeFallback`/`FallbackType` | 已汇报 |
|
||
| 阶段 5 只新增内部用例，公开入口切换留到阶段 6B。 | ISS-014 阶段顺序和 6B 门禁 | 已汇报 |
|
||
|
||
## User-interview
|
||
|
||
- 本阶段没有新增 user-interview 问题。上述方向、范围、修复次数、模型复用、超时/重试、Fallback 和阶段串行规则均已在 ISS-014 评审及前序对话中由用户确认。
|
||
|
||
## Key Decisions
|
||
|
||
- Snapshot 使用 Tool-specific adapter 严格解析冻结 projection；未知 Tool、ID 不一致、projection 反序列化失败或 projection 的 EvidenceStatus 与 canonical record 不一致均 fail closed。
|
||
- MySQL 的逻辑数据源和查询范围来自 canonical `request`，行/列和值来自 `agent_result`；RAG/log 以 `agent_result` 自带的稳定来源和范围为准。
|
||
- SemanticGuard 使用直接 `ChatModel.call(Prompt)`，不创建第二个 `ReactAgent`；模型调用由受控 Executor 执行，超时/取消时调用 `Future.cancel(true)`。
|
||
- Evidence repair 与 SemanticGuard 共用同一模型抽象，但各自拥有独立 prompt、严格输出类型和预算；repair 策略固定一次 attempt，不能嵌套 retry executor。
|
||
- Release use case 只在 EvidenceGuard 成功后调用 SemanticGuard；SUPPORTED 返回原 Draft 对象，所有其他路径只返回固定 `SafeFallback`。
|
||
- 不创建 ADR：这些是 ISS-014 已冻结架构的阶段实现，不产生新的难逆转跨项目决策。
|
||
|
||
## OpenSpec Backfill
|
||
|
||
- 需进入 proposal/design/spec/tasks：EvidenceGuard 规则、Tool-specific snapshot、无 raw/ID 泄漏、repair 单次边界、SemanticGuard 隔离/预算/超时/重试、原样发布与三类 Fallback、L2/公开隔离。
|
||
- 不进入本阶段：公开 Chat/SSE 装配、Run 持久化、旧多 Agent 删除和 live E2E。
|
||
|
||
## Cross-artifact Alignment
|
||
|
||
| 上游 -> 下游 | 检查内容 | 状态 |
|
||
|---|---|---|
|
||
| ISS-014/brief -> proposal | 物理验真、结构修复、隔离语义审查、固定 Fallback、阶段边界 | 已对齐 |
|
||
| proposal -> design | Store ownership、Tool-specific snapshot、timeout/cancel/retry、唯一报告作者和 L2 影响 | 已对齐 |
|
||
| design -> specs/tasks | 每个关键决策均有可观察 requirement 和对应实现/测试切片 | 已对齐 |
|
||
| specs -> tasks | 9 组 requirements 覆盖为 Evidence、model boundary、repair/release 和回归验证任务 | 已对齐 |
|
||
|
||
## Architecture Audit
|
||
|
||
- 能力来源：`zoom-out`，使用 glossary 的 Diagnosis Harness、EvidenceGuard、SemanticGuard、RunContext、Invocation Status 和 Evidence Status 术语。
|
||
- 链路为 `query + Draft + RunContext -> EvidenceGuard/store -> optional repair/shared model boundary -> SemanticGuard/shared model boundary -> original Draft or fixed Fallback`，没有外层 Graph 或第二个 Tool loop。
|
||
- Store 拥有物理调用记录，EvidenceGuard 只读并生成 snapshot；Diagnosis Agent 拥有报告语义，repair 只修 ID，SemanticGuard 只审查，release 只做二选一，数据所有权没有重叠。
|
||
- 最大运行风险是 provider 忽略 interrupt；design 要求 Future cancel、迟到 Token 记录和 `core.checkActive` 丢弃迟到结果，阶段 6A 再负责 Run 终态。
|
||
- 架构审计未发现与阶段 0-4 或 ADR 冲突；所有风险缓解已回写 design/spec/tasks。
|
||
|
||
## Interface Impact
|
||
|
||
- 级别：L2 内部接口。
|
||
- 变更对象：新增 guard/release records、interfaces、use cases、prompts 和 tests；现有方法签名不变。
|
||
- 消费者：本阶段只有 focused tests，阶段 6A 才接入 production application use case。
|
||
- 兼容性：公开 HTTP/SSE、Controller DTO、数据库、Redis key schema 和旧 Chat/AiOps 路径不变。
|
||
|
||
## Commit Gate Preflight
|
||
|
||
- proposal、design、specs、tasks 完整，`openspec status` 为 complete，`openspec validate single-react-evidence-semantic-guards --strict` 通过。
|
||
- Question pool 全部为已汇报的 evidence-driven 结论；无未确认 user-interview、接口等级或风险接受问题。
|
||
- Cross-artifact 四段对齐无 gap；架构审计的数据所有权、模型取消和唯一报告作者约束已进入 design/spec/tasks。
|
||
- 接口影响为 L2，仅新增内部 Java API；公开 Controller/SSE/JPA/Redis schema/旧 ChatService 保持不变。
|
||
- Apply、Archive 和阶段 Git commit 使用用户对 ISS-014 各阶段的持续授权；实现必须严格限制为 Committed OpenSpec。
|
||
- `.committed` 已创建，Committed OpenSpec 可进入 Apply。
|
||
|
||
## Pre-apply Research
|
||
|
||
### Reference Implementations
|
||
|
||
- `harness/tool/store/CanonicalInvocationStore.java`、`CanonicalToolInvocation.java`、`ToolCallKeyFactory.java`：当前 Run 物理验真和 lifecycle 真理源。
|
||
- `harness/tool/projection/RagResultProjector.java`、`QueryLogsResultProjector.java`、`harness/tool/mysql/MysqlResultProjector.java`：三类 `agent_result` 的唯一生产者和有界字段来源。
|
||
- `harness/agent/HarnessModelInterceptor.java`：模型调用前预算、响应 Usage 记账和 late-result active check 模式。
|
||
- `harness/retry/HarnessRetryExecutor.java`、`HarnessRetryPolicies.java`：SemanticGuard 两次技术 attempt 与 repair 一次 attempt 的装配边界。
|
||
- `harness/core/RunCancellation.java`：取消 callback 注册和 first-cancel 语义。
|
||
- `service/ExecutorGatekeeperService.java`：仅参考报告内部引用检查思想，不复用旧 Map/JPA/session DTO 或规则目录。
|
||
|
||
### Technology Stack
|
||
|
||
- Jackson strict `ObjectReader` 解析 frozen Draft/Tool projections；Tool-specific adapter 生成 typed snapshot，不透传 JsonNode/raw response。
|
||
- Spring AI `ChatModel.call(Prompt)` 执行无 Tool 单轮 guard；`ChatResponseMetadata.Usage` 接入现有 Core Token 预算。
|
||
- Java 17 `ExecutorService/Future.get(timeout)` 提供 per-attempt timeout，`Future.cancel(true)` 接入 Run cancellation；Semantic 总时限由 monotonic elapsed time 控制。
|
||
- JUnit 5 scripted `ChatModel` 和 in-memory canonical store 作为外部边界 fake；测试只通过 EvidenceGuard/SemanticGuard/Release use case 公共接口断言行为。
|
||
- 无 Controller、MQ、JPA、Flyway 或新 Maven dependency；不需要新共享基础设施。
|
||
|
||
## Apply Progress
|
||
|
||
- 首模块对齐：EvidenceGuard typed contracts、Draft/reference checks、current-Run canonical validation 和 RAG/log/MySQL snapshot adapters 已完成，tasks 1.1-1.4 完成。
|
||
- 8 个 `EvidenceGuardTest` 行为测试通过；快照序列化不含 Tool Call ID 或 `raw_response`，`NO_EVIDENCE` 仅在 `NEGATIVE_OBSERVATION` 下进入带 scope/zero-match 的快照。
|
||
- TODO：tasks 2.1-4.2，尚未实现模型边界、SemanticGuard、repair/release 和综合回归。
|
||
- REVIEW 发现 corrupted Store key 下 record ID 可能与 Draft reference 不同；分类为代码偏离，已增加 exact canonical ID 校验和回归测试，无需改变规格方向。
|
||
- REVIEW 发现 fallback `DiagnosisReleaseResult` 携带完整 snapshot 会通过 `analysis_text` 间接泄漏 Draft；分类为规格安全边界细化，已回写 design/spec，并让 fallback result 强制使用空 snapshot，安全来源只保留在 `SafeFallback.verified_sources`。
|
||
|
||
## Apply Result
|
||
|
||
- 新增确定性 EvidenceGuard：校验 typed Draft、唯一 Analysis ID、报告引用、exact current-Run Tool ID、READY lifecycle、agent result、Evidence Status 与 Analysis Kind，并严格展开 RAG/log/MySQL projection。
|
||
- verified snapshot 按 Analysis ID 分组，只含稳定 source/scope/timestamp/excerpt/values；SemanticGuard 输入不含 Tool Call ID、Redis key 或 raw response。
|
||
- 新增共享 `GuardModelCall`：复用系统 ChatModel，执行 Core model/Token/Run byte budget、per-attempt timeout、total timeout、Future cancellation 和 late-result active check。
|
||
- 新增无 Tool/无记忆/无 ReAct 的单轮 SemanticGuard，严格解析 `SUPPORTED|UNSUPPORTED + reason`；仅技术失败使用既有两次 attempt，业务 UNSUPPORTED 不重试。
|
||
- 新增一次 EvidenceRepair，只允许 ID/reference 修复；任何可见文本、kind、顺序、human-confirmation 或 limitations 变化都直接 Evidence fallback。
|
||
- 新增 DiagnosisReleaseUseCase 和固定 SafeFallbackFactory：SUPPORTED 原样返回 Draft；evidence failed、semantic unsupported/unavailable 均不返回 Draft、完整 snapshot 或审计 reason。
|
||
- 公开 Controller、ChatService、AiOpsService、SSE、JPA/Flyway 和旧多 Agent 链路无修改。
|
||
|
||
## Apply Verification
|
||
|
||
- 编译：`mvn -q -DskipTests compile` 通过。
|
||
- 阶段 5 focused：`EvidenceGuardTest` 9、`SemanticGuardTest` 4、`DiagnosisReleaseUseCaseTest` 6，共 19 tests，0 failure/error。
|
||
- 综合回归：阶段 5 + Harness Core/Retry/Tool boundary/store/projections/contracts + Diagnosis Agent，共 18 suites / 70 tests，0 failure/error/skipped。
|
||
- OpenSpec：`openspec validate single-react-evidence-semantic-guards --strict` 通过。
|
||
- 静态范围：公开 Controller/ChatService/AiOpsService diff 为空；SemanticGuard 无 Tool ID/raw response/ReactAgent/StateGraph/ThreadLocal/手写 while；新 guard/release 包无业务 Agent loop。
|
||
- 仓库级 `openspec validate --specs --strict` 为 16 passed / 2 failed；失败仍是前序 `mysql-readonly-tool`、`rag-log-projections` 的 scenario 标题格式，按计划阶段 7 统一修复。
|
||
- 未执行 live E2E：按 ISS-014 阶段门禁统一留到阶段 7。
|
||
|
||
## Archive Result
|
||
|
||
- 14/14 OpenSpec tasks 完成，`.archive-ready` 已创建。
|
||
- 主规格已同步至 `openspec/specs/single-react-evidence-semantic-guards/spec.md`，新增 9 个 requirements。
|
||
- Change 已归档至 `openspec/changes/archive/2026-07-21-single-react-evidence-semantic-guards`。
|
||
- `devflow/index.md` 和 ISS-014 阶段表已更新为阶段 0-5 archived，下一阶段为 6A。
|
||
- 未创建 ADR/compound knowledge：本阶段落实 ISS-014 已冻结边界，没有新的跨项目难逆转决策。
|