From 30d3296043dfb82c91502eded106422938b449a8 Mon Sep 17 00:00:00 2001 From: zhuyongxin Date: Sat, 11 Jul 2026 16:35:25 +0800 Subject: [PATCH] docs(mvp): archive session run trace issue --- mvp/README.md | 11 ++++--- mvp/architecture/harness-quality-gates.md | 8 +++-- mvp/architecture/interview-one-pager.md | 2 +- mvp/demo/evidence-pipeline-scenarios.md | 4 +-- mvp/demo/interview-q-and-a.md | 2 +- mvp/issues/README.md | 4 +-- .../ISS-010-session-run-trace-isolation.md | 33 +++++++++++++++++-- 7 files changed, 49 insertions(+), 15 deletions(-) rename mvp/issues/{active => archived}/ISS-010-session-run-trace-isolation.md (91%) diff --git a/mvp/README.md b/mvp/README.md index 00c19a4..704c686 100644 --- a/mvp/README.md +++ b/mvp/README.md @@ -1,6 +1,6 @@ # SuperBizAgent MVP 文档 -**更新日期**：2026-07-09 +**更新日期**：2026-07-10 本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。 @@ -30,7 +30,7 @@ ## 当前系统一句话 -SuperBizAgent MVP 是一个可追踪的故障诊断 Agent：Chat 和 AIOps 入口进入 Agent 编排，Executor 显式调用知识库、日志、指标等工具收集证据，诊断过程落到 `diagnosis_session`、`agent_step`、`tool_invocation`，最终通过 Trace API、Verifier 和评测脚本证明结果可解释、可回放、可对比。 +SuperBizAgent MVP 是一个可追踪的故障诊断 Agent：Chat 和 AIOps 入口进入 Agent 编排，Executor 显式调用知识库、日志、指标等工具收集证据；多轮会话元数据落到 `chat_session`，每次诊断运行落到 `diagnosis_run`，步骤和工具明细通过 `agent_step.run_id`、`tool_invocation.run_id` 关联，最终通过 Trace API、Verifier 和评测脚本证明结果可解释、可回放、可对比。 ## 文档结构 @@ -83,7 +83,8 @@ mvp/ - `VectorSearchService` 是检索稳定门面。 - Spring AI VectorStore 是当前读取主路径，Milvus SDK 保留为 fallback。 - AIOps payload 会生成推荐知识库 query，保留业务语义。 -- Trace API 聚合 session、step、tool invocation 和 self evaluation。 +- `sessionId` 表示多轮会话上下文，`runId` 表示一次可回放诊断运行。 +- Trace API 聚合 `diagnosis_run`、`agent_step.run_id`、`tool_invocation.run_id` 和 self evaluation。 - RAG 行为通过 offline baseline 和 live acceptance 脚本做回归验证。 ## 关键运行链路 @@ -93,7 +94,8 @@ Chat -> ChatService -> Planner / Executor / Verifier -> evidence tools - -> diagnosis_session / agent_step / tool_invocation + -> chat_session / diagnosis_run + -> agent_step.run_id / tool_invocation.run_id -> DiagnosisTraceService AIOps @@ -102,6 +104,7 @@ AIOps -> Planner / Executor -> Prometheus / logs / lookup_knowledge -> AiOpsRuleEvaluationService + -> diagnosis_run(agent_flow=AI_OPS) -> DiagnosisTraceService RAG diff --git a/mvp/architecture/harness-quality-gates.md b/mvp/architecture/harness-quality-gates.md index d228a26..b91d4e3 100644 --- a/mvp/architecture/harness-quality-gates.md +++ b/mvp/architecture/harness-quality-gates.md @@ -110,10 +110,10 @@ sequenceDiagram participant H as AgentLoggingHook participant DB as agent_step - A->>H: before_model(messages, sessionId) - H->>DB: 写入 model_input / step_index / agent_name + A->>H: before_model(messages, sessionId, runId) + H->>DB: 写入 session_id / run_id / model_input / step_index / agent_name A-->>A: LLM 推理 - A->>H: after_model(messages, sessionId) + A->>H: after_model(messages, sessionId, runId) H->>DB: 回填 model_output / thought / has_tool_call / duration / token_count ``` @@ -126,6 +126,8 @@ sequenceDiagram - token count。 - Verifier 的 JSON 输出摘要。 +新写入必须带 `run_id`；`session_id` 仍保留用于粗粒度排查和历史兼容。 + ## 5. Tool Invocation 门禁 工具调用记录由 `ToolInvocationRecorder` 和具体工具共同完成。 diff --git a/mvp/architecture/interview-one-pager.md b/mvp/architecture/interview-one-pager.md index e7c0641..2536eeb 100644 --- a/mvp/architecture/interview-one-pager.md +++ b/mvp/architecture/interview-one-pager.md @@ -5,7 +5,7 @@ ## 1. 一句话 -SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：它把用户问题或 AIOps 告警转换成 Planner、Executor、Gatekeeper、Verifier、Composer 的诊断链路，所有工具证据、模型步骤、最终答案、自评估和用户反馈都能通过同一个 `sessionId` 回放。 +SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：它把用户问题或 AIOps 告警转换成 Planner、Executor、Gatekeeper、Verifier、Composer 的诊断链路，`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行；所有工具证据、模型步骤、最终答案、自评估和用户反馈都能按 `sessionId + runId` 回放。 ## 2. 一张图 diff --git a/mvp/demo/evidence-pipeline-scenarios.md b/mvp/demo/evidence-pipeline-scenarios.md index d882ad9..67d8745 100644 --- a/mvp/demo/evidence-pipeline-scenarios.md +++ b/mvp/demo/evidence-pipeline-scenarios.md @@ -52,12 +52,12 @@ Invoke-RestMethod ` -Body $body ``` -然后查询同一 session： +然后保留响应里的 `runId`，查询同一 run 的 Trace： ```powershell Invoke-RestMethod ` -Method Get ` - -Uri "http://localhost:9900/api/diagnosis/mvp-demo-narrow-highcpu-001/trace" + -Uri "http://localhost:9900/api/diagnosis/mvp-demo-narrow-highcpu-001/trace?runId=$runId" ``` 注意：除 payment-timeout 主路径外，其它 live 请求是“可尝试”的演示入口；稳定验收以 `mvp/eval` fixture 和 baseline 为准。 diff --git a/mvp/demo/interview-q-and-a.md b/mvp/demo/interview-q-and-a.md index 5d57085..b049817 100644 --- a/mvp/demo/interview-q-and-a.md +++ b/mvp/demo/interview-q-and-a.md @@ -2,7 +2,7 @@ ## 为什么不用普通 Chatbot？ -这个项目的重点不是生成一段诊断文本，而是把诊断拆成可审计链路：Planner 拆解问题，Executor 调工具拿证据，Gatekeeper 用代码核验证据引用，Verifier 判断可推导性，Composer 生成最终表达。每次运行都能通过同一个 `sessionId` 回放。 +这个项目的重点不是生成一段诊断文本，而是把诊断拆成可审计链路：Planner 拆解问题，Executor 调工具拿证据，Gatekeeper 用代码核验证据引用，Verifier 判断可推导性，Composer 生成最终表达。`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行，Trace 和 Feedback 都可以按 `sessionId + runId` 回放和定位。 ## 为什么 RAG 要做成显式工具？ diff --git a/mvp/issues/README.md b/mvp/issues/README.md index 7cf8484..b7cbe2d 100644 --- a/mvp/issues/README.md +++ b/mvp/issues/README.md @@ -1,6 +1,6 @@ # MVP Issues 索引 -**更新日期**：2026-07-09 +**更新日期**：2026-07-10 **状态**：按活跃问题、设计笔记、RAG 问题集和已归档问题整理 ## 目录约定 @@ -18,7 +18,6 @@ |---|---|---|---|---| | ISS-003 | MVP 设计与实现 Review 收敛 | 高 | 待规划 | [active/ISS-003-mvp-design-implementation-review.md](active/ISS-003-mvp-design-implementation-review.md) | | ISS-004 | Executor 域级检索水位控制 | 低 | 待规划 | [active/ISS-004-executor-domain-hard-limit.md](active/ISS-004-executor-domain-hard-limit.md) | -| ISS-010 | 同 session 多轮诊断 Trace 隔离 | 高 | 方案已确认，待 OpenSpec | [active/ISS-010-session-run-trace-isolation.md](active/ISS-010-session-run-trace-isolation.md) | | executor-evidence-attribution-hallucination | Executor 证据归因幻觉 | 高 | 待规划 | [active/executor-evidence-attribution-hallucination.md](active/executor-evidence-attribution-hallucination.md) | | rag-refactor-plan | RAG 检索重构计划 | 高 | 待规划 | [active/rag-refactor-plan.md](active/rag-refactor-plan.md) | @@ -60,6 +59,7 @@ | ISS-007 | Verifier 证据摘要保真与工具命中质量问题 | 已实施 | [archived/ISS-007-verifier-evidence-summary-fidelity.md](archived/ISS-007-verifier-evidence-summary-fidelity.md) | | ISS-008 | Executor 窄范围查询越界 | 已修复 | [archived/ISS-008-executor-narrow-scope-overreach.md](archived/ISS-008-executor-narrow-scope-overreach.md) | | ISS-009 | negative_observation 精确引用 no-evidence 结果 | 已修复 | [archived/ISS-009-negative-observation-no-evidence-reference.md](archived/ISS-009-negative-observation-no-evidence-reference.md) | +| ISS-010 | 同 session 多轮诊断 Trace 隔离 | 已归档 | [archived/ISS-010-session-run-trace-isolation.md](archived/ISS-010-session-run-trace-isolation.md) | | diagnosis-eval-baseline-diff | 诊断评测 baseline diff 与回归判断 | 已归档 | [archived/diagnosis-eval-baseline-diff.md](archived/diagnosis-eval-baseline-diff.md) | | expand-diagnosis-eval-fixtures | 补齐固定诊断评测 fixture 与 baseline | 已归档 | [archived/expand-diagnosis-eval-fixtures.md](archived/expand-diagnosis-eval-fixtures.md) | | mvp-demo-interview-runbook | Plan C 面试可复现 Demo 包 | 已归档 | [archived/mvp-demo-interview-runbook.md](archived/mvp-demo-interview-runbook.md) | diff --git a/mvp/issues/active/ISS-010-session-run-trace-isolation.md b/mvp/issues/archived/ISS-010-session-run-trace-isolation.md similarity index 91% rename from mvp/issues/active/ISS-010-session-run-trace-isolation.md rename to mvp/issues/archived/ISS-010-session-run-trace-isolation.md index e79cae1..995cc97 100644 --- a/mvp/issues/active/ISS-010-session-run-trace-isolation.md +++ b/mvp/issues/archived/ISS-010-session-run-trace-isolation.md @@ -1,15 +1,22 @@ # ISS-010 同 session 多轮诊断 Trace 隔离 -**状态**：OpenSpec 已创建，Phase 1-3 已提交，Phase 4 正在收口 gate / commit +**状态**：已归档 **严重程度**：高 **发现时间**：2026-07-10 **来源**：同一 `sessionId` 多轮 Chat E2E 验证 +**归档日期**：2026-07-10 +**OpenSpec**：`openspec/changes/archive/2026-07-10-session-run-trace-isolation` +**实现提交**：`52bf030`、`26d5529`、`027aed1`、`d928a19`、`78c1477`、`f9df943` +**归档提交**：`3578709` + --- ## 背景 -当前 Chat 链路同时存在两类“会话”语义： +归档结论：当前 MVP 已将“会话态”和“运行态”拆开。`sessionId` 表示多轮会话目录和 Redis 上下文；`runId` 表示一次可回放诊断执行。Trace、Feedback、Evaluation、AIOps 和案例沉淀的新路径都按 `runId` 隔离。 + +原问题中 Chat 链路同时存在两类“会话”语义： ```text Redis SessionContext @@ -25,6 +32,26 @@ MySQL diagnosis_session / agent_step / tool_invocation 当前实现只按 `sessionId` 关联 Trace，导致同一个 `sessionId` 下多轮诊断的 step/tool 记录混在一起。 +当前实现已改为： + +```text +chat_session(sessionId) + -> diagnosis_run(runId) + -> agent_step.run_id + -> tool_invocation.run_id +``` + +旧 `diagnosis_session` 保留为历史兼容和回滚表，新 Chat/AIOps 执行不再写入新的运行态。 + +## 归档结果 + +- OpenSpec 已归档到 `openspec/changes/archive/2026-07-10-session-run-trace-isolation`。 +- 主规格已同步到 `openspec/specs/session-run-trace-isolation/spec.md`。 +- `mvp/architecture/` 和 `mvp/tables/` 已更新为 `chat_session -> diagnosis_run -> agent_step/tool_invocation(run_id)` 模型。 +- Demo 脚本和 Trace UI 已支持 `sessionId + runId` 精确 Trace 和 Feedback。 +- Maven E2E、`scripts/query_mysql.py` DB 检查、`logs/` 日志检查和 baseline drift 检查均已通过；未观察到 baseline drift。 +- `devflow/projects/2026-07-10-session-run-trace-isolation/` 已保存 brief、evidence、decisions、acceptance。 + --- ## E2E 证据 @@ -540,6 +567,8 @@ tool_invocation(run_id, id) - `mvp/architecture/session-trace-lifecycle.md` - `mvp/architecture/data-model.md` +- `mvp/tables/聊天会话表-chat_session.md` +- `mvp/tables/诊断运行表-diagnosis_run.md` - `mvp/tables/诊断会话表-diagnosis_session.md` - `mvp/tables/Agent步骤表-agent_step.md` - `mvp/tables/工具调用表-tool_invocation.md`