osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
190013c901cb4f3bb1790c103261b5a7d3ff287c
SuperBizAgent-java/openspec/changes/archive/2026-07-20-chat-diagnosis-stategraph-cleanup-docs/design.md
T

7.6 KiB
Raw Blame History

Context

ISS-011 的运行时和测试迁移已经完成：复杂 Chat 通过真实 Diagnosis StateGraph，Graph Nodes 使用显式 RunnableConfig/verified state，Run 保存 orchestration trace，三层权威 tests 已建立。剩余工作跨越代码清理、current docs、demo script、eval、live process、日志、数据库和 Issue 生命周期，必须按“静态/自动化先完成，live E2E 最后执行”的顺序收口。

全仓引用证明旧闭包为 VerifierInputHook -> VerifierContextHolder + ToolTraceSummaryService，外加 ToolTraceSummaryServiceTest。新 Graph 不依赖该闭包。current architecture docs 仍描述 Sequential/Hook/full trace；历史 issues/design-notes/fixtures 则应保留当时语义或历史兼容数据。

Goals / Non-Goals

Goals:

  • 删除旧闭包且保持 Graph parser/Gatekeeper/projection/evaluation 行为。
  • 把 architecture index 声明的 current docs、active eval/demo docs 与真实 StateGraph/Run trace 对齐。
  • 让 interview demo check 将 exact run.orchestrationTrace 作为强制验收字段和 summary 输出。
  • 运行确定性 Graph/test/eval gates，再启动 Maven 完成唯一最终 live E2E。
  • 对本次 E2E 的日志和数据库做 exact session/run 证据核验并清理进程。
  • 全部通过后关闭/归档 ISS-011 和阶段 5 OpenSpec。

Non-Goals:

  • 不修改 Graph 路由、Prompt、公开 API、DTO 或 DB schema。
  • 不重写历史 archived/design-note 文档和 legacy eval fixtures。
  • 不删除 UI/eval 对历史 tool_trace_summary 的兼容读取。
  • 不治理仓库凭据、外部基础设施或其他 active issues。

Decisions

1. 删除完整旧闭包，不留下空壳 Hook

删除 VerifierInputHook.java、VerifierContextHolder.java、ToolTraceSummaryService.java 和 ToolTraceSummaryServiceTest.java。保留空类或 deprecated wrapper 会继续让维护者误认为存在第二条 Verifier 输入路径，也会让 Spring component 扫描注册无消费者 service。

删除前后以全仓 definition/import/instantiation/type-use 搜索、test compilation、Graph suite、Gatekeeper/protocol tests 证明闭包；负向契约 test 可保留名称字符串，任何可执行类型依赖都视为 cleanup blocker。

2. current docs 改为显式 StateGraph，历史 docs 保留

必须更新：

  • mvp/architecture/README.md
  • agent-orchestration.md
  • session-trace-lifecycle.md
  • current-mvp-architecture.md
  • executor-evidence-pipeline-refactor.md
  • harness-quality-gates.md
  • feedback-architecture.md
  • retrieval-observability.md
  • mvp/eval/README.md
  • mvp/demo/README.md / trace checklist

历史 archived issues/design-notes 和 legacy fixtures不批量替换：它们记录演进阶段或兼容旧 Trace。current docs 若提到 tool_trace_summary，只能标注为历史读取兼容，不能描述为新 Verifier 输入/持久化源。

3. Demo script 是 final E2E executable contract

扩展 run-interview-demo-check.ps1：

  1. 从 Chat response 获取 runId。
  2. 查询 exact Trace。
  3. 要求 trace.data.run.orchestrationTrace 非空。
  4. 要求 version/final_node/termination_reason 非空，transitions 为数组。
  5. 把 finalNode、terminationReason、degraded、transitionCount、evidenceRetryCount 写入 summary。
  6. 保留 feedback 和 Prompt/Gatekeeper summary。

脚本必须 fail fast，不能用 session self-evaluation 或日志合成缺失的 Graph trace。

4. 自动化门禁先于 live E2E

顺序固定：cleanup source check → docs/script tests → Graph/Chat/Trace/Gatekeeper/Composer/Controller/Repository tests → diagnosis eval baseline/diff → test compilation → OpenSpec/static gates → live startup/E2E → logs → DB → process cleanup。

在 live 前发现的失败按 OpenSpec/code/test/documentation分类；live 后失败使用 diagnose loop，以 exact run evidence 定位，不通过放宽断言绕过。

5. Live E2E 使用唯一 identity 和可回收后台 Maven

  • sessionId：iss-011-stage5-<timestamp>。
  • Maven：spring-boot:run + mvp-demo profile，后台 hidden process，stdout/stderr 写入 target/ 临时文件。
  • readiness：轮询 9900，最长明确超时，不阻塞超过 60 秒且持续汇报。
  • 执行：复用 interview demo script，输出写入 target/iss-011-stage5-output/，避免覆盖已提交 demo sample。
  • 最终：停止应用进程树，确认 9900 无监听，删除临时启动/output文件。

如果 9900 启动前已被其他进程占用，先识别而不是杀掉未知进程；只有本轮启动的 PID 可被清理。

6. 日志与数据库证据只认本次 Run

启动前记录 logs/application.log、application-error.log、chat.log 长度和时间；E2E 后只读新增片段，并搜索 sessionId/runId、Graph执行、Flyway/JPA 和 ERROR。测试阶段写入的旧日志不计入 live 证据。

数据库通过 scripts/query_mysql.py 执行 read-only queries：

  • SHOW COLUMNS ... orchestration_trace。
  • exact diagnosis_run status/flow/answer/metrics/self_evaluation/orchestration trace/feedback。
  • JSON_EXTRACT version/final_node/termination_reason/degraded/evidence_retry_count。
  • exact run AgentStep/ToolInvocation count 和 distinct ownership。
  • wrong session ownership count=0。

所有查询必须带 E2E sessionId/runId 或 schema column 条件；不接受全局 latest 代替。

7. Issue 归档是最后一个实现动作

E2E/log/DB 任一失败时 ISS-011 保持 active。全部通过后更新验收 checkbox和状态，将文件 move 到 mvp/issues/archived/，并把 issues index 从 active 移到 archived。OpenSpec archive 在 Issue move 后执行，Git commit 是阶段 5最后门禁。

Interface Impact

  • 等级：L2 内部类型删除 + demo/docs 增强。
  • 外部 /api/chat、Trace、feedback、DB schema 和 JSON 字段：不变。
  • 内部消费者：旧 Hook/ThreadLocal/service 无消费者，删除无需迁移调用点。
  • Demo script 行为：新增 fail-fast orchestration trace contract和 summary 字段；旧 Chat/Trace/feedback outputs保留。
  • 回滚：revert 阶段 5代码/文档；DB/生产数据无变更。E2E产生的 demo Run 是正常审计数据，不执行破坏性回滚。

Risks / Trade-offs

  • [隐藏反射/配置消费者未被 rg发现] → test compilation + Spring startup 是最终验证；发现即恢复并修正规格。
  • [文档仍有历史术语] → current docs 白名单扫描；history/design-notes允许但索引明确非当前真理源。
  • [live LLM 输出波动] → mock logs/metrics提供稳定工具证据；Graph允许安全 Fallback，但验收仍要求非空真实 orchestration trace和一致 Run生命周期。
  • [外部 DB/Redis/Milvus/LLM不可用] → readiness/log/DB diagnose；不伪造通过，不修改验收口径。
  • [停止进程误伤] → 只记录和终止本轮 Maven/Java PID，结束后用端口复核。
  • [E2E output覆盖仓库样例] → 输出放 target临时目录，证据摘要提炼进 devflow 后删除临时文件。

Migration Plan

  1. 删除旧闭包，运行 source/test compilation/Graph安全回归。
  2. 更新 current docs 和 demo script/checklist，增加静态脚本契约 test。
  3. 运行完整 focused tests、diagnosis eval baseline/diff、OpenSpec/static gates。
  4. Maven mvp-demo startup，运行 unique session E2E。
  5. 检查新增日志片段和 exact DB数据，停止进程、清理临时文件。
  6. 更新/移动 ISS-011，回填 devflow，archive OpenSpec，独立提交。

运行时回滚为 Git revert；数据库 V012列和 E2E Run可安全保留。

Open Questions

无。清理闭包、current/history docs边界、E2E身份/证据和 Issue关闭门禁均已确定。

Reference in New Issue View Git Blame Copy Permalink