112 lines
10 KiB
Markdown
112 lines
10 KiB
Markdown
# Decisions: single-react-cleanup-e2e
|
||
|
||
## Discover Status
|
||
|
||
- Checkpoint: Discover
|
||
- Capability source: `sm-flow` + `grill-with-docs` + `gitnexus-refactoring`。
|
||
- GitNexus index 停在 `2362665`，当前为 `bc36248`；刷新会改写用户已修改的 `AGENTS.md`，因此不安全。使用 OpenSpec/devflow、`rg` 全引用扫描、源码阅读、编译和测试作为 fallback。
|
||
- AGENTS.md 指定的 `codebase-retrieval` 与 LSP 工具在当前环境不可用，已显式记录限制。
|
||
- Scale: complex。涉及 L4 endpoint 删除、跨模块物理清理、Tool/Trace ownership、安全持久化和 live E2E。
|
||
|
||
## Question Pool
|
||
|
||
| # | 维度 | 问题 | 模式 | 状态 |
|
||
|---|---|---|---|---|
|
||
| Q1 | 范围 | 哪些旧 Agent/Service/Hook/Session 只有自引用测试，哪些仍在生产可达？ | evidence-driven | 已解决 |
|
||
| Q2 | 协议 | 阶段 7 是否必须删除 `/api/ai_ops` 与旧 Session endpoints？ | evidence-driven | 已解决 |
|
||
| Q3 | Tool | RAG/log 旧实现哪些可复用，哪些 Agent-facing contract/副作用必须删除？ | evidence-driven | 已解决 |
|
||
| Q4 | Trace | 新 Harness 如何在不泄漏 raw/prompt/thought 的前提下满足 AgentStep/ToolInvocation E2E？ | evidence-driven | 已解决 |
|
||
| Q5 | 文档 | ISS-012/ISS-013 和现有架构/Demo 文档如何收口？ | evidence-driven | 已解决 |
|
||
| Q6 | 验收 | 最终 live E2E 必须证明哪些 exact-run 事实，哪些外部系统明确不声称 live？ | evidence-driven | 已解决 |
|
||
| Q7 | 回滚 | L4 endpoint 删除如何迁移与回滚？ | evidence-driven | 已解决 |
|
||
|
||
## Evidence-driven
|
||
|
||
| 结论 | 证据来源 | 是否已汇报用户 |
|
||
|---|---|---|
|
||
| `ChatService` 没有生产调用方，只剩自身单元/Smoke tests。 | `rg ChatService` | 已汇报 |
|
||
| `/api/ai_ops` 仍由 bundled frontend 按钮调用，并运行 Supervisor + Planner + Executor 多 Agent。 | `AiOpsController`、`AiOpsService`、`app.js`、`index.html` | 已汇报 |
|
||
| ISS-014 总体验收要求旧多 Agent/Graph 不存在，阶段 6B 只暂时保持 AiOps，阶段 7 负责清理/处置。 | ISS-014、阶段 6B design/acceptance | 已汇报 |
|
||
| `/api/chat/clear` 与 session info/runs 没有 frontend caller；Redis SessionManager 只由该 Controller 和测试使用。 | controller/frontend/session 引用扫描 | 已汇报 |
|
||
| `LookupKnowledgeTool` 和 `QueryLogsTools` 被新 Harness adapter 复用，但仍携带旧 `@Tool`、ThreadLocal/recorder 副作用。 | `HarnessChatConfiguration`、Tool source | 已汇报 |
|
||
| 新 ToolBoundary 写 Redis canonical invocation，但没有 `tool_invocation` durable audit；最终 DB E2E 会缺 Tool rows。 | Harness boundary/config 引用扫描 | 已汇报 |
|
||
| 旧 `AgentLoggingHook` 仍回退 ThreadLocal，并持久化 thought/model正文；不满足新安全边界。 | `AgentLoggingHook.java` | 已汇报 |
|
||
| 当前架构、Agent、Harness 和 lifecycle 文档仍描述 Planner/Executor/Verifier/Composer 与 AIOps 双入口。 | `mvp/architecture/*.md` | 已汇报 |
|
||
|
||
## User-interview
|
||
|
||
- 无新增 user-interview。唯一公开 Chat、旧多 Agent/Graph 物理删除、无兼容分支、最终 E2E 和外部 Mock 边界均已由 ISS-014 与用户的逐阶段自动执行授权冻结。
|
||
|
||
## Key Decisions
|
||
|
||
- 删除 legacy AiOps endpoint 而不是迁移到第二个 use case；所有诊断统一进入 `/api/chat` 的 Intent Router。
|
||
- 删除旧 Session endpoints/Redis conversation context；安全 PreviousTurn 只来自 `diagnosis_run.published_result`。
|
||
- RAG/log 查询实现保留为 Harness backend，移除 `@Tool` 和旧 recorder/session dedup；Agent 只看 ACI callbacks。
|
||
- 新 Agent audit hook 只写角色/数量/Tool 名称/耗时等 metadata，不写模型输入正文、输出正文、Thought 或 Tool arguments。
|
||
- Tool durable audit 通过 Harness port + JPA adapter fail-open 写入；Redis canonical store failure 仍 fail-closed，DB audit failure 只记录日志，不改变 Tool observation。
|
||
- 删除 endpoint 的迁移无兼容层；bundled frontend 同 commit 删除按钮/consumer，回滚整体回滚 commit。
|
||
- 不创建 ADR：方向已由 ISS-014 冻结，本 change 只完成最终落地与验收。
|
||
|
||
## OpenSpec Backfill
|
||
|
||
- 需进入 design/spec/tasks：删除清单、唯一 endpoint、Harness-native trace、Tool durable audit schema/safety、Tool backend 解耦、文档/issue 收口、strict validation、live E2E/log/DB acceptance 与回滚。
|
||
|
||
## Cross-artifact Alignment
|
||
|
||
| 上游 -> 下游 | 检查内容 | 状态 |
|
||
|---|---|---|
|
||
| ISS-014/brief -> proposal | 阶段 7 物理清理、文档、最终 Maven/log/DB E2E、Mock 外部 Tool 边界 | 已对齐 |
|
||
| proposal -> design | 删除闭包、Tool backend 复用、安全 Agent/Tool audit、L4 migration/rollback | 已对齐 |
|
||
| design -> specs/tasks | ownership、禁止泄漏、exact identity、strict validation、live E2E 均有 requirement 与切片 | 已对齐 |
|
||
| specs -> tasks | 8 组可观察 requirements 覆盖删除、audit、docs、verification 和最终 E2E | 已对齐 |
|
||
|
||
## Architecture Audit
|
||
|
||
- Capability source: `zoom-out`，使用 Diagnosis Harness、Diagnosis Agent、Canonical Invocation、Durable Audit、Diagnosis Trace 和 Chat SSE Contract 术语。
|
||
- 最终链路为 `browser -> ChatController -> ChatApplicationUseCase -> Harness -> Diagnosis Agent -> ACI Tools -> Guards -> SSE`，没有第二业务入口或业务 Graph。
|
||
- Redis canonical invocation 是短期完整 Tool 真理源；MySQL ToolInvocation 是长期有界 metadata audit，两者禁止双写 raw payload。
|
||
- `chat_session` JPA entity 属于当前 Run/PreviousTurn 目录，Redis SessionContext 属于旧 conversation memory；删除时必须区分。
|
||
- 最大风险是 backend 的旧 Tool annotation/recorder 隐式暴露和 audit 内容泄漏；design/tasks 已加入独占 discovery、negative serialization、context startup 与 live DB inspection。
|
||
|
||
## Interface Impact
|
||
|
||
- Level: L4 breaking HTTP/frontend contract。
|
||
- 删除 `/api/ai_ops`、`/api/chat/clear`、`/api/chat/session/{sessionId}` 和 `/runs`；保留唯一 `/api/chat` SSE 与 Trace API。
|
||
- bundled frontend 同 commit 删除 AiOps 按钮/consumer；外部 caller 迁移到 `/api/chat`，无兼容 branch。
|
||
- 回滚必须整体回滚阶段 7 commit，不能单独恢复旧 endpoint/Tool annotations。
|
||
|
||
## Apply Verification Status
|
||
|
||
- Follow-up current-document audit found and corrected stale runtime semantics in the tracked payment-timeout PowerShell demo and `mvp/tables`: old JSON Chat parsing, Redis SessionContext history, Planner/Verifier identities, full Tool payload persistence, and Chat/AiOps Run descriptions are no longer presented as current behavior.
|
||
- `mvp/demo/scripts/run-payment-timeout-demo.ps1` now strictly validates `metadata -> status* -> content|failure -> done`, captures exact session/run identity, and fetches exact Trace without writing feedback. PowerShell parser validation and two in-memory SSE contract samples passed.
|
||
- Current architecture/demo/table scan excluding explicit `archive/` and ignored local `output/` artifacts: 0 legacy runtime matches.
|
||
- Follow-up `openspec validate --all --strict`: 22 passed, 0 failed; `git diff --check`: passed.
|
||
- Initial environment checks reported missing injected variables. Per user direction, credentials were restored to ignored `application-local.yml`; no credential was added to Git or emitted in the archive.
|
||
- `mvn -q -DskipTests compile`: passed.
|
||
- `node --check src/main/resources/static/app.js`: passed.
|
||
- `openspec validate --all --strict`: 22 passed, 0 failed.
|
||
- Deterministic regression suite excluding credential-dependent MySQL/Redis/Milvus tests: 60 suites, 221 tests, 0 failures, 0 errors, 3 skipped.
|
||
- `SemanticGuardTest` interruption assertion failed once under the credential-dependent full-suite run, then passed three isolated repetitions and the deterministic regression suite; classified as load-sensitive test timing, not a reproduced product regression.
|
||
- `mvn -q -DskipTests package`: passed.
|
||
- Production legacy path scan, audit sensitive-payload scan, and legacy backend Tool contract scan: 0 matches.
|
||
- The approved external-network run connected to MySQL/Redis/Milvus/model services. Flyway repair aligned the old V012 checksum and V013 reconciled the missing release-contract columns/index.
|
||
- Maven startup validated all 13 migrations, passed JPA schema validation and started Tomcat 9900 with Harness/Audit beans.
|
||
- Final exact live run: session `mvp-demo-payment-timeout-stage7-20260722-1741`, run `363f481c-33b8-42e7-8699-428a6ec61806`, SSE `metadata -> status -> status -> status -> content -> done`, outcome `FALLBACK`.
|
||
- Exact MySQL evidence: one `DIAGNOSIS/SUCCESS/FALLBACK` run, two metadata-only `diagnosis_agent` steps with null Thought, and two READY/EVIDENCE_FOUND Tool audits for `lookup_knowledge` and Mock `query_logs`.
|
||
- Tasks 4.2-4.5 are complete. Real CLS and production business MySQL Tool datasource remain explicit non-goals.
|
||
|
||
## Apply Conflict Classification
|
||
|
||
- **Code deviation**: `DiagnosisRun` enum mapping expected native ENUM while V012/V013 define VARCHAR. Fixed ORM column definitions; OpenSpec unchanged.
|
||
- **Code deviation**: production `ObjectMapper` lacked Java Time modules, causing canonical Redis `STORE_ERROR`. Fixed mapper registration and bound the store test to the production mapper.
|
||
- **Code deviation**: Mock empty log results used `success=false`, conflicting with the specified `NO_EVIDENCE` projection. Fixed backend success semantics and the stale test assertion.
|
||
- **Code deviation**: RAG backend logs exposed raw query/rewritten query content. Replaced with bounded counts/category metadata and verified the final Tool execution window contains no prohibited payload.
|
||
- **Acceptance fixture drift**: the payment-timeout demo requested the removed metrics Tool and encouraged an unbounded investigation. Updated the fixture to the current two-Tool Mock acceptance scope and explicit stopping boundary.
|
||
|
||
## Commit Gate Preflight
|
||
|
||
- proposal、design、两份 specs 和 tasks 完整；新 capability 与 modified capability 的范围无 gap。
|
||
- Question pool 全部 evidence-driven 并已汇报，无 user-interview、未判级接口或未接受架构风险。
|
||
- 删除清单区分 current JPA metadata 与 legacy Redis Session，Tool backend 与 Agent-facing contract，canonical truth 与 durable audit。
|
||
- live E2E 明确要求真实应用/模型链和 exact ID；真实 CLS/生产业务 MySQL 明确不在验收声称范围。
|