From 841437fa06579828f29c2d660fb1314ffaa19357 Mon Sep 17 00:00:00 2001
From: zhuyongxin <zhuyongxin@aspirecn.com>
Date: Thu, 9 Jul 2026 13:40:08 +0800
Subject: [PATCH] docs(mvp): organize mvp documentation

---
 .../acceptance.md                             |   2 +-
 .../decisions.md                              |   4 +-
 .../acceptance.md                             |   2 +-
 .../evidence.md                               |   2 +-
 .../brief.md                                  |   2 +-
 mvp/README.md                                 |  37 +-
 .../2026-07-05-legacy/confidence-feedback.md  |   2 +-
 mvp/architecture/rag-architecture.md          |   2 +-
 mvp/archive/2026-07-09-doc-cleanup/README.md  |  17 +
 .../discuss/Executor_Prompt.md                |   0
 .../discuss/L0_plan.md                        |   0
 .../discuss/rag_plan.md                       |   0
 .../notes/agent-engineering-decisions.md      |   0
 .../notes/mvp-demo-trace-acceptance.md        |   0
 .../plan/session-storage-design.md            |   0
 mvp/issues/README.md                          |  93 +++--
 ...SS-003-mvp-design-implementation-review.md |   0
 .../ISS-004-executor-domain-hard-limit.md     |   0
 ...utor-evidence-attribution-hallucination.md |   0
 mvp/issues/{ => active}/rag-refactor-plan.md  |  26 +-
 .../ISS-001-duplicate-retrieval.md            |   2 +-
 .../ISS-002-executor-unconstrained-lookup.md  |   0
 .../ISS-005-evidence-trace-hardening.md       |   0
 .../ISS-006-diagnosis-eval-harness.md         |   0
 ...-007-verifier-evidence-summary-fidelity.md |   0
 ...ISS-008-executor-narrow-scope-overreach.md |   0
 ...ative-observation-no-evidence-reference.md |   0
 .../diagnosis-eval-baseline-diff.md           |   0
 .../expand-diagnosis-eval-fixtures.md         |   0
 .../mvp-demo-interview-runbook.md             |   0
 ...executor-self-evidence-loop-design-note.md |   0
 .../executor-structured-output-v2.md          |   0
 .../{ => rag}/rag-breadcrumb-embedding-gap.md |   0
 .../rag-chunk-context-reconstruction.md       |   0
 .../rag-context-packing-and-reranking.md      |   0
 .../{ => rag}/rag-l0-domain-entity-hint.md    |   0
 .../rag-l0-keyword-matching-quality.md        |   0
 .../{ => rag}/rag-l0-l1-fusion-ranking.md     |   0
 .../{ => rag}/rag-l1-score-calibration.md     |   0
 mvp/issues/{ => rag}/rag-query-rewrite-gap.md |   0
 .../rag-spring-ai-advisor-boundary.md         |   0
 .../rag-spring-ai-document-postprocessor.md   |   0
 .../rag-spring-ai-query-transformer.md        |   0
 .../rag-spring-ai-vectorstore-migration.md    |   0
 .../rag-upload-chunk-parameter-drift.md       |   0
 mvp/tables/Agent步骤表-agent_step.md          |  41 +++
 mvp/tables/README.md                          |  40 +++
 mvp/tables/api_document.md                    | 332 ------------------
 .../旧诊断记录表-diagnosis_record.md}         |   4 +-
 mvp/tables/case_library.md                    | 265 --------------
 mvp/tables/工具调用表-tool_invocation.md      |  66 ++++
 mvp/tables/文档元数据表-api_document.md       |  51 +++
 mvp/tables/案例库表-case_library.md           |  50 +++
 mvp/tables/知识域表-knowledge_domain.md       |  36 ++
 mvp/tables/诊断会话表-diagnosis_session.md    |  47 +++
 .../decisions.md                              |   2 +-
 .../decisions.md                              |   2 +-
 57 files changed, 452 insertions(+), 675 deletions(-)
 create mode 100644 mvp/archive/2026-07-09-doc-cleanup/README.md
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/discuss/Executor_Prompt.md (100%)
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/discuss/L0_plan.md (100%)
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/discuss/rag_plan.md (100%)
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/notes/agent-engineering-decisions.md (100%)
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/notes/mvp-demo-trace-acceptance.md (100%)
 rename mvp/{ => archive/2026-07-09-doc-cleanup}/plan/session-storage-design.md (100%)
 rename mvp/issues/{ => active}/ISS-003-mvp-design-implementation-review.md (100%)
 rename mvp/issues/{ => active}/ISS-004-executor-domain-hard-limit.md (100%)
 rename mvp/issues/{ => active}/executor-evidence-attribution-hallucination.md (100%)
 rename mvp/issues/{ => active}/rag-refactor-plan.md (90%)
 rename mvp/issues/{ => archived}/ISS-001-duplicate-retrieval.md (97%)
 rename mvp/issues/{ => archived}/ISS-002-executor-unconstrained-lookup.md (100%)
 rename mvp/issues/{ => archived}/ISS-005-evidence-trace-hardening.md (100%)
 rename mvp/issues/{ => archived}/ISS-006-diagnosis-eval-harness.md (100%)
 rename mvp/issues/{ => archived}/ISS-007-verifier-evidence-summary-fidelity.md (100%)
 rename mvp/issues/{ => archived}/ISS-008-executor-narrow-scope-overreach.md (100%)
 rename mvp/issues/{ => archived}/ISS-009-negative-observation-no-evidence-reference.md (100%)
 rename mvp/issues/{ => archived}/diagnosis-eval-baseline-diff.md (100%)
 rename mvp/issues/{ => archived}/expand-diagnosis-eval-fixtures.md (100%)
 rename mvp/issues/{ => archived}/mvp-demo-interview-runbook.md (100%)
 rename mvp/issues/{ => design-notes}/executor-self-evidence-loop-design-note.md (100%)
 rename mvp/issues/{ => design-notes}/executor-structured-output-v2.md (100%)
 rename mvp/issues/{ => rag}/rag-breadcrumb-embedding-gap.md (100%)
 rename mvp/issues/{ => rag}/rag-chunk-context-reconstruction.md (100%)
 rename mvp/issues/{ => rag}/rag-context-packing-and-reranking.md (100%)
 rename mvp/issues/{ => rag}/rag-l0-domain-entity-hint.md (100%)
 rename mvp/issues/{ => rag}/rag-l0-keyword-matching-quality.md (100%)
 rename mvp/issues/{ => rag}/rag-l0-l1-fusion-ranking.md (100%)
 rename mvp/issues/{ => rag}/rag-l1-score-calibration.md (100%)
 rename mvp/issues/{ => rag}/rag-query-rewrite-gap.md (100%)
 rename mvp/issues/{ => rag}/rag-spring-ai-advisor-boundary.md (100%)
 rename mvp/issues/{ => rag}/rag-spring-ai-document-postprocessor.md (100%)
 rename mvp/issues/{ => rag}/rag-spring-ai-query-transformer.md (100%)
 rename mvp/issues/{ => rag}/rag-spring-ai-vectorstore-migration.md (100%)
 rename mvp/issues/{ => rag}/rag-upload-chunk-parameter-drift.md (100%)
 create mode 100644 mvp/tables/Agent步骤表-agent_step.md
 create mode 100644 mvp/tables/README.md
 delete mode 100644 mvp/tables/api_document.md
 rename mvp/tables/{diagnosis_record.md => archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md} (96%)
 delete mode 100644 mvp/tables/case_library.md
 create mode 100644 mvp/tables/工具调用表-tool_invocation.md
 create mode 100644 mvp/tables/文档元数据表-api_document.md
 create mode 100644 mvp/tables/案例库表-case_library.md
 create mode 100644 mvp/tables/知识域表-knowledge_domain.md
 create mode 100644 mvp/tables/诊断会话表-diagnosis_session.md

diff --git a/devflow/projects/2026-06-30-session-dedup-knowledge-map/acceptance.md b/devflow/projects/2026-06-30-session-dedup-knowledge-map/acceptance.md
index 6699f29..8290942 100644
--- a/devflow/projects/2026-06-30-session-dedup-knowledge-map/acceptance.md
+++ b/devflow/projects/2026-06-30-session-dedup-knowledge-map/acceptance.md
@@ -48,7 +48,7 @@
 
 ## 遗留问题
 
-ISS-002：Executor 无约束重复调用 `lookup_knowledge`（单会话 20+ 次），knowledge map 和检索约束只注入了 Planner 未注入 Executor。详见 `mvp/issues/ISS-002-executor-unconstrained-lookup.md`。
+ISS-002：Executor 无约束重复调用 `lookup_knowledge`（单会话 20+ 次），knowledge map 和检索约束只注入了 Planner 未注入 Executor。详见 `mvp/issues/archived/ISS-002-executor-unconstrained-lookup.md`。
 
 ## 已知限制
 
diff --git a/devflow/projects/2026-07-03-mvp-demo-trace-acceptance/decisions.md b/devflow/projects/2026-07-03-mvp-demo-trace-acceptance/decisions.md
index 71c63ec..a790bad 100644
--- a/devflow/projects/2026-07-03-mvp-demo-trace-acceptance/decisions.md
+++ b/devflow/projects/2026-07-03-mvp-demo-trace-acceptance/decisions.md
@@ -9,8 +9,8 @@
 ## Context
 
 - `devflow/index.md` was checked. Relevant history includes `session-storage`, `confidence-feedback`, `executor-action-memory-relevance`, and `chat-verifier-agent`.
-- `mvp/notes/agent-engineering-decisions.md` already recommends the next phase as "可复现 MVP Demo", including `mvp-demo` profile, fixed diagnosis case, one-click request, and `GET /api/diagnosis/{sessionId}/trace`.
-- `mvp/issues/ISS-003-mvp-design-implementation-review.md` identifies test stability, session traceability, verifier evidence chain, upload path, and SupervisorAgent consistency as recent MVP concerns. Security cleanup is intentionally deferred by user decision.
+- `mvp/archive/2026-07-09-doc-cleanup/notes/agent-engineering-decisions.md` already recommends the next phase as "可复现 MVP Demo", including `mvp-demo` profile, fixed diagnosis case, one-click request, and `GET /api/diagnosis/{sessionId}/trace`.
+- `mvp/issues/active/ISS-003-mvp-design-implementation-review.md` identifies test stability, session traceability, verifier evidence chain, upload path, and SupervisorAgent consistency as recent MVP concerns. Security cleanup is intentionally deferred by user decision.
 
 ## Question Pool
 
diff --git a/devflow/projects/2026-07-07-executor-evidence-output-contract/acceptance.md b/devflow/projects/2026-07-07-executor-evidence-output-contract/acceptance.md
index 84218e1..d8a41e8 100644
--- a/devflow/projects/2026-07-07-executor-evidence-output-contract/acceptance.md
+++ b/devflow/projects/2026-07-07-executor-evidence-output-contract/acceptance.md
@@ -2,7 +2,7 @@
 
 ## Draft Acceptance
 
-- [x] Issue exists: `mvp/issues/executor-evidence-attribution-hallucination.md`.
+- [x] Issue exists: `mvp/issues/active/executor-evidence-attribution-hallucination.md`.
 - [x] OpenSpec change artifacts exist.
 - [x] devflow tracking files exist.
 - [x] OpenSpec validation passes.
diff --git a/devflow/projects/2026-07-07-executor-v2-output-contract/evidence.md b/devflow/projects/2026-07-07-executor-v2-output-contract/evidence.md
index 8b14339..40eeac6 100644
--- a/devflow/projects/2026-07-07-executor-v2-output-contract/evidence.md
+++ b/devflow/projects/2026-07-07-executor-v2-output-contract/evidence.md
@@ -5,7 +5,7 @@
 - `devflow/projects/2026-07-07-executor-evidence-output-contract`: V1 evidence-attribution contract kept `user_facing_answer`.
 - `devflow/projects/2026-07-02-chat-verifier-agent`: Verifier consumes explicit inputs and should not see intermediate reasoning.
 - `devflow/projects/2026-07-04-evidence-trace-hardening`: evidence summaries and tool invocation references are the evidence foundation.
-- `mvp/issues/executor-structured-output-v2.md`: staged implementation design; stage one is Executor V2 output contract.
+- `mvp/issues/design-notes/executor-structured-output-v2.md`: staged implementation design; stage one is Executor V2 output contract.
 
 ## Code Evidence
 
diff --git a/devflow/projects/2026-07-08-verifier-evidence-reference-fidelity/brief.md b/devflow/projects/2026-07-08-verifier-evidence-reference-fidelity/brief.md
index 730e8bb..5b7c00f 100644
--- a/devflow/projects/2026-07-08-verifier-evidence-reference-fidelity/brief.md
+++ b/devflow/projects/2026-07-08-verifier-evidence-reference-fidelity/brief.md
@@ -41,4 +41,4 @@ Make Executor cite concrete tool evidence, make Gatekeeper validate that citatio
 ## OpenSpec
 
 - Change: `openspec/changes/verifier-evidence-reference-fidelity`
-- Source issue: `mvp/issues/ISS-007-verifier-evidence-summary-fidelity.md`
+- Source issue: `mvp/issues/archived/ISS-007-verifier-evidence-summary-fidelity.md`
diff --git a/mvp/README.md b/mvp/README.md
index 4285955..00c19a4 100644
--- a/mvp/README.md
+++ b/mvp/README.md
@@ -1,8 +1,8 @@
 # SuperBizAgent MVP 文档
 
-**更新日期**：2026-07-05
+**更新日期**：2026-07-09
 
-本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前架构入口已经整理到 `mvp/architecture/`，旧版架构材料已归档，避免继续把历史方案当成当前实现。
+本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。
 
 ## 当前入口
 
@@ -12,6 +12,7 @@
 | [architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md) | 当前可运行系统架构 |
 | [architecture/interview-one-pager.md](architecture/interview-one-pager.md) | 面试一页式架构讲解 |
 | [architecture/agent-orchestration.md](architecture/agent-orchestration.md) | Agent 编排架构 |
+| [architecture/executor-evidence-pipeline-refactor.md](architecture/executor-evidence-pipeline-refactor.md) | Executor 证据链路改造记录 |
 | [architecture/harness-quality-gates.md](architecture/harness-quality-gates.md) | Harness 与质量门禁 |
 | [architecture/rag-architecture.md](architecture/rag-architecture.md) | RAG/知识检索新架构 |
 | [architecture/retrieval-observability.md](architecture/retrieval-observability.md) | 检索与可观测性架构 |
@@ -20,11 +21,12 @@
 | [architecture/knowledge-base-authoring.md](architecture/knowledge-base-authoring.md) | 知识库文档编写与维护 |
 | [architecture/data-model.md](architecture/data-model.md) | 数据模型总览 |
 | [architecture/evolution-roadmap.md](architecture/evolution-roadmap.md) | Agent 架构演进路线 |
-| [issues/rag-refactor-plan.md](issues/rag-refactor-plan.md) | RAG 重构计划和阶段拆解 |
+| [issues/README.md](issues/README.md) | MVP issue 索引 |
+| [issues/active/rag-refactor-plan.md](issues/active/rag-refactor-plan.md) | RAG 重构计划和阶段拆解 |
+| [tables/README.md](tables/README.md) | 当前 MySQL 表说明 |
 | [demo/README.md](demo/README.md) | Demo 运行和面试演示材料 |
 | [demo/ten-minute-interview-demo.md](demo/ten-minute-interview-demo.md) | 10 分钟面试演示脚本 |
 | [eval/README.md](eval/README.md) | 诊断评测材料 |
-| [issues/README.md](issues/README.md) | MVP issue 索引 |
 
 ## 当前系统一句话
 
@@ -39,6 +41,7 @@ mvp/
     current-mvp-architecture.md
     interview-one-pager.md
     agent-orchestration.md
+    executor-evidence-pipeline-refactor.md
     harness-quality-gates.md
     rag-architecture.md
     retrieval-observability.md
@@ -47,12 +50,17 @@ mvp/
     knowledge-base-authoring.md
     data-model.md
     evolution-roadmap.md
-    archive/2026-07-05-legacy/
+    archive/
   issues/
     README.md
-    rag-refactor-plan.md
-    ISS-*.md
-    rag-*.md
+    active/
+    archived/
+    design-notes/
+    rag/
+  tables/
+    README.md
+    *表-*.md
+    archive/
   demo/
     README.md
     ten-minute-interview-demo.md
@@ -65,9 +73,7 @@ mvp/
     cases/
     fixtures/
     reports/
-  notes/
-  plan/
-  tables/
+  archive/
 ```
 
 ## 当前核心设计
@@ -107,10 +113,11 @@ RAG
   -> tool_invocation
 ```
 
-## 旧文档说明
+## 归档说明
 
-旧版架构文档已移动到：
+历史材料分两类：
 
-- [architecture/archive/2026-07-05-legacy/](architecture/archive/2026-07-05-legacy/)
+- 旧架构文档：[architecture/archive/2026-07-05-legacy/](architecture/archive/2026-07-05-legacy/)
+- 本次文档清理归档：[archive/2026-07-09-doc-cleanup/](archive/2026-07-09-doc-cleanup/)
 
-归档文档只用于追溯设计历史。当前实现和后续规划以 `architecture/current-mvp-architecture.md` 与 `architecture/rag-architecture.md` 为准。
+归档文档只用于追溯设计历史。当前实现和后续规划以 `architecture/`、`issues/README.md`、`tables/README.md` 和 OpenSpec/devflow 的最新记录为准。
diff --git a/mvp/architecture/archive/2026-07-05-legacy/confidence-feedback.md b/mvp/architecture/archive/2026-07-05-legacy/confidence-feedback.md
index 24d3016..db2f046 100644
--- a/mvp/architecture/archive/2026-07-05-legacy/confidence-feedback.md
+++ b/mvp/architecture/archive/2026-07-05-legacy/confidence-feedback.md
@@ -154,4 +154,4 @@ ALTER TABLE diagnosis_session ADD COLUMN answer LONGTEXT COMMENT 'Agent 返回
 
 - **LLM 观点层**：在 `selfEvaluation` 的 `llm_opinion` 字段叠加 LLM 结构化观点（has_root_cause、has_solution 等），作为独立 factors，不改变现有规则逻辑
 - **案例结构化字段**：useful 触发时自动提取 faultCategory / errorCode，替代暂时的 GENERAL
-- **重复召回问题**：Executor Prompt 约束或工具层 session 维度去重（见 [ISS-001](../issues/ISS-001-duplicate-retrieval.md)）
+- **重复召回问题**：Executor Prompt 约束或工具层 session 维度去重（见 [ISS-001](../../../issues/archived/ISS-001-duplicate-retrieval.md)）
diff --git a/mvp/architecture/rag-architecture.md b/mvp/architecture/rag-architecture.md
index 21eba38..149f51a 100644
--- a/mvp/architecture/rag-architecture.md
+++ b/mvp/architecture/rag-architecture.md
@@ -2,7 +2,7 @@
 
 **更新日期**：2026-07-06
 **状态**：当前主架构 + 后续演进边界  
-**关联计划**：`mvp/issues/rag-refactor-plan.md`
+**关联计划**：[`mvp/issues/active/rag-refactor-plan.md`](../issues/active/rag-refactor-plan.md)
 
 ## 1. 架构目标
 
diff --git a/mvp/archive/2026-07-09-doc-cleanup/README.md b/mvp/archive/2026-07-09-doc-cleanup/README.md
new file mode 100644
index 0000000..045e3e8
--- /dev/null
+++ b/mvp/archive/2026-07-09-doc-cleanup/README.md
@@ -0,0 +1,17 @@
+# 2026-07-09 MVP 文档清理归档
+
+本目录保存本次清理中从当前入口移出的历史设计材料。这些文档仍有追溯价值，但不再代表当前可运行实现。
+
+## 归档内容
+
+| 目录 | 内容 | 归档原因 |
+|---|---|---|
+| `discuss/` | 早期 Executor Prompt、L0、RAG 讨论稿 | 已被当前 architecture、OpenSpec change 和 issue 取代 |
+| `plan/` | `session-storage-design.md` | 会话存储已实现，当前表以 Flyway 和 `mvp/tables/` 为准 |
+| `notes/` | 早期工程决策和 Demo Trace 验收笔记 | 相关内容已沉淀到 architecture、demo、eval 和 devflow |
+
+## 使用原则
+
+- 当前架构以 `mvp/architecture/` 为准。
+- 当前表结构以 `mvp/tables/`、Flyway migration 和实体类为准。
+- 当前问题入口以 `mvp/issues/README.md` 为准。
diff --git a/mvp/discuss/Executor_Prompt.md b/mvp/archive/2026-07-09-doc-cleanup/discuss/Executor_Prompt.md
similarity index 100%
rename from mvp/discuss/Executor_Prompt.md
rename to mvp/archive/2026-07-09-doc-cleanup/discuss/Executor_Prompt.md
diff --git a/mvp/discuss/L0_plan.md b/mvp/archive/2026-07-09-doc-cleanup/discuss/L0_plan.md
similarity index 100%
rename from mvp/discuss/L0_plan.md
rename to mvp/archive/2026-07-09-doc-cleanup/discuss/L0_plan.md
diff --git a/mvp/discuss/rag_plan.md b/mvp/archive/2026-07-09-doc-cleanup/discuss/rag_plan.md
similarity index 100%
rename from mvp/discuss/rag_plan.md
rename to mvp/archive/2026-07-09-doc-cleanup/discuss/rag_plan.md
diff --git a/mvp/notes/agent-engineering-decisions.md b/mvp/archive/2026-07-09-doc-cleanup/notes/agent-engineering-decisions.md
similarity index 100%
rename from mvp/notes/agent-engineering-decisions.md
rename to mvp/archive/2026-07-09-doc-cleanup/notes/agent-engineering-decisions.md
diff --git a/mvp/notes/mvp-demo-trace-acceptance.md b/mvp/archive/2026-07-09-doc-cleanup/notes/mvp-demo-trace-acceptance.md
similarity index 100%
rename from mvp/notes/mvp-demo-trace-acceptance.md
rename to mvp/archive/2026-07-09-doc-cleanup/notes/mvp-demo-trace-acceptance.md
diff --git a/mvp/plan/session-storage-design.md b/mvp/archive/2026-07-09-doc-cleanup/plan/session-storage-design.md
similarity index 100%
rename from mvp/plan/session-storage-design.md
rename to mvp/archive/2026-07-09-doc-cleanup/plan/session-storage-design.md
diff --git a/mvp/issues/README.md b/mvp/issues/README.md
index f337c1c..bb46471 100644
--- a/mvp/issues/README.md
+++ b/mvp/issues/README.md
@@ -1,47 +1,64 @@
-# 已知问题记录
+# MVP Issues 索引
 
-| # | 标题 | 严重程度 | 状态 | 文件 |
-|---|---|---|---|---|
-| ISS-001 | Executor 重复召回同一文档 | 中 | 已修复 | [ISS-001-duplicate-retrieval.md](ISS-001-duplicate-retrieval.md) |
-| ISS-002 | Executor 无约束重复调用 lookup_knowledge | 中 | 已修复 | [ISS-002-executor-unconstrained-lookup.md](ISS-002-executor-unconstrained-lookup.md) |
-| ISS-003 | MVP 设计与实现 Review 收敛 | 高 | 待规划 | [ISS-003-mvp-design-implementation-review.md](ISS-003-mvp-design-implementation-review.md) |
-| ISS-004 | Executor 域级检索水位控制（Phase 2） | 低 | 待规划 | [ISS-004-executor-domain-hard-limit.md](ISS-004-executor-domain-hard-limit.md) |
-| ISS-005 | 证据链补齐与降级契约收敛 | 高 | 已归档 | [ISS-005-evidence-trace-hardening.md](ISS-005-evidence-trace-hardening.md) |
-| ISS-006 | 固定诊断评测集与回归 Harness | 高 | 已归档 | [ISS-006-diagnosis-eval-harness.md](ISS-006-diagnosis-eval-harness.md) |
-| ISS-007 | Verifier 证据摘要保真与工具命中质量问题 | 高 | 已实施 | [ISS-007-verifier-evidence-summary-fidelity.md](ISS-007-verifier-evidence-summary-fidelity.md) |
-| ISS-008 | Executor 窄范围查询越界 | 中 | 已修复 | [ISS-008-executor-narrow-scope-overreach.md](ISS-008-executor-narrow-scope-overreach.md) |
-| ISS-009 | negative_observation 精确引用 no-evidence 结果 | 中 | 已修复 | [ISS-009-negative-observation-no-evidence-reference.md](ISS-009-negative-observation-no-evidence-reference.md) |
-| executor-evidence-attribution-hallucination | Executor 证据归因幻觉 | 高 | 待规划 | [executor-evidence-attribution-hallucination.md](executor-evidence-attribution-hallucination.md) |
-| executor-self-evidence-loop-design-note | Executor 自证循环与证据摘要链路设计记录 | 高 | 已形成方向 | [executor-self-evidence-loop-design-note.md](executor-self-evidence-loop-design-note.md) |
-| expand-diagnosis-eval-fixtures | 补齐固定诊断评测 fixture 与 baseline | 中 | 已归档 | [expand-diagnosis-eval-fixtures.md](expand-diagnosis-eval-fixtures.md) |
-| diagnosis-eval-baseline-diff | 诊断评测 baseline diff 与回归判断 | 中 | 已归档 | [diagnosis-eval-baseline-diff.md](diagnosis-eval-baseline-diff.md) |
-| mvp-demo-interview-runbook | Plan C 面试可复现 Demo 包 | 中 | 已归档 | [mvp-demo-interview-runbook.md](mvp-demo-interview-runbook.md) |
+**更新日期**：2026-07-09  
+**状态**：按活跃问题、设计笔记、RAG 问题集和已归档问题整理
 
-## RAG 重构计划
+## 目录约定
+
+| 目录 | 用途 |
+|---|---|
+| [active/](active/) | 仍需要规划或实现的问题 |
+| [design-notes/](design-notes/) | 已形成方向、用于指导后续实现的设计记录 |
+| [rag/](rag/) | RAG 子问题集合；多数已合并到 RAG 重构计划 |
+| [archived/](archived/) | 已修复、已实施或已归档的问题 |
+
+## 活跃问题
 
 | 名称 | 标题 | 严重程度 | 状态 | 文件 |
 |---|---|---|---|---|
-| rag-refactor-plan | RAG 检索重构计划 | 高 | 待规划 | [rag-refactor-plan.md](rag-refactor-plan.md) |
+| 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) |
+| 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) |
 
-## RAG 检索问题
+## 设计笔记
 
-| 名称 | 标题 | 严重程度 | 状态 | 文件 |
-|---|---|---|---|---|
-| chunk-context-reconstruction | RAG 切片上下文重建缺失 | 高 | 已合并到重构计划 | [rag-chunk-context-reconstruction.md](rag-chunk-context-reconstruction.md) |
-| breadcrumb-embedding-gap | RAG breadcrumb 未参与向量语义 | 高 | 已合并到重构计划 | [rag-breadcrumb-embedding-gap.md](rag-breadcrumb-embedding-gap.md) |
-| l0-l1-fusion-ranking | RAG L0 和 L1 未真正融合排序 | 中 | 已合并到重构计划 | [rag-l0-l1-fusion-ranking.md](rag-l0-l1-fusion-ranking.md) |
-| l0-keyword-matching-quality | RAG L0 关键词匹配质量不足 | 中 | 已合并到重构计划 | [rag-l0-keyword-matching-quality.md](rag-l0-keyword-matching-quality.md) |
-| l1-score-calibration | RAG L1 分数阈值未校准 | 中 | 已合并到重构计划 | [rag-l1-score-calibration.md](rag-l1-score-calibration.md) |
-| context-packing-and-reranking | RAG 缺少上下文打包和 Rerank | 中 | 已合并到重构计划 | [rag-context-packing-and-reranking.md](rag-context-packing-and-reranking.md) |
-| upload-chunk-parameter-drift | RAG 上传切片参数未真正生效 | 低 | 已合并到重构计划 | [rag-upload-chunk-parameter-drift.md](rag-upload-chunk-parameter-drift.md) |
-| query-rewrite-gap | RAG 查询改写能力薄弱 | 中 | 已合并到重构计划 | [rag-query-rewrite-gap.md](rag-query-rewrite-gap.md) |
+| 名称 | 标题 | 状态 | 文件 |
+|---|---|---|---|
+| executor-self-evidence-loop-design-note | Executor 自证循环与证据摘要链路设计记录 | 已形成方向 | [design-notes/executor-self-evidence-loop-design-note.md](design-notes/executor-self-evidence-loop-design-note.md) |
+| executor-structured-output-v2 | Executor 结构化输出 V2 阶段设计 | 部分已实施，保留为后续改造参考 | [design-notes/executor-structured-output-v2.md](design-notes/executor-structured-output-v2.md) |
 
-## RAG 框架化改造
+## RAG 问题集
 
-| 名称 | 标题 | 严重程度 | 状态 | 文件 |
-|---|---|---|---|---|
-| spring-ai-vectorstore-migration | RAG 迁移到 Spring AI VectorStore 检索抽象 | 高 | 已合并到重构计划 | [rag-spring-ai-vectorstore-migration.md](rag-spring-ai-vectorstore-migration.md) |
-| spring-ai-query-transformer | RAG 接入 Spring AI Query Transformer | 中 | 已合并到重构计划 | [rag-spring-ai-query-transformer.md](rag-spring-ai-query-transformer.md) |
-| spring-ai-document-postprocessor | RAG 使用 DocumentPostProcessor 做后处理 | 中 | 已合并到重构计划 | [rag-spring-ai-document-postprocessor.md](rag-spring-ai-document-postprocessor.md) |
-| l0-domain-entity-hint | RAG 将 L0 降级为领域和实体 Hint | 中 | 已合并到重构计划 | [rag-l0-domain-entity-hint.md](rag-l0-domain-entity-hint.md) |
-| spring-ai-advisor-boundary | RAG 明确 Spring AI Advisor 与 Agent Tool 的边界 | 中 | 已合并到重构计划 | [rag-spring-ai-advisor-boundary.md](rag-spring-ai-advisor-boundary.md) |
+这些问题已经收敛到 [active/rag-refactor-plan.md](active/rag-refactor-plan.md)，单个文件保留用于追溯原始问题和设计背景。
+
+| 名称 | 标题 | 状态 | 文件 |
+|---|---|---|---|
+| breadcrumb-embedding-gap | RAG breadcrumb 未参与向量语义 | 已合并到重构计划 | [rag/rag-breadcrumb-embedding-gap.md](rag/rag-breadcrumb-embedding-gap.md) |
+| chunk-context-reconstruction | RAG 切片上下文重建缺失 | 已合并到重构计划 | [rag/rag-chunk-context-reconstruction.md](rag/rag-chunk-context-reconstruction.md) |
+| context-packing-and-reranking | RAG 缺少上下文打包和 Rerank | 已合并到重构计划 | [rag/rag-context-packing-and-reranking.md](rag/rag-context-packing-and-reranking.md) |
+| l0-domain-entity-hint | RAG 将 L0 降级为领域和实体 Hint | 已合并到重构计划 | [rag/rag-l0-domain-entity-hint.md](rag/rag-l0-domain-entity-hint.md) |
+| l0-keyword-matching-quality | RAG L0 关键词匹配质量不足 | 已合并到重构计划 | [rag/rag-l0-keyword-matching-quality.md](rag/rag-l0-keyword-matching-quality.md) |
+| l0-l1-fusion-ranking | RAG L0 和 L1 未真正融合排序 | 已合并到重构计划 | [rag/rag-l0-l1-fusion-ranking.md](rag/rag-l0-l1-fusion-ranking.md) |
+| l1-score-calibration | RAG L1 分数阈值未校准 | 已合并到重构计划 | [rag/rag-l1-score-calibration.md](rag/rag-l1-score-calibration.md) |
+| query-rewrite-gap | RAG 查询改写能力薄弱 | 已合并到重构计划 | [rag/rag-query-rewrite-gap.md](rag/rag-query-rewrite-gap.md) |
+| spring-ai-advisor-boundary | Spring AI Advisor 与 Agent Tool 边界 | 已合并到重构计划 | [rag/rag-spring-ai-advisor-boundary.md](rag/rag-spring-ai-advisor-boundary.md) |
+| spring-ai-document-postprocessor | 使用 DocumentPostProcessor 做后处理 | 已合并到重构计划 | [rag/rag-spring-ai-document-postprocessor.md](rag/rag-spring-ai-document-postprocessor.md) |
+| spring-ai-query-transformer | 接入 Spring AI Query Transformer | 已合并到重构计划 | [rag/rag-spring-ai-query-transformer.md](rag/rag-spring-ai-query-transformer.md) |
+| spring-ai-vectorstore-migration | 迁移到 Spring AI VectorStore 检索抽象 | 已合并到重构计划 | [rag/rag-spring-ai-vectorstore-migration.md](rag/rag-spring-ai-vectorstore-migration.md) |
+| upload-chunk-parameter-drift | 上传切片参数未真正生效 | 已合并到重构计划 | [rag/rag-upload-chunk-parameter-drift.md](rag/rag-upload-chunk-parameter-drift.md) |
+
+## 已归档问题
+
+| 名称 | 标题 | 状态 | 文件 |
+|---|---|---|---|
+| ISS-001 | Executor 重复召回同一文档 | 已修复 | [archived/ISS-001-duplicate-retrieval.md](archived/ISS-001-duplicate-retrieval.md) |
+| ISS-002 | Executor 无约束重复调用 lookup_knowledge | 已修复 | [archived/ISS-002-executor-unconstrained-lookup.md](archived/ISS-002-executor-unconstrained-lookup.md) |
+| ISS-005 | 证据链补齐与降级契约收敛 | 已归档 | [archived/ISS-005-evidence-trace-hardening.md](archived/ISS-005-evidence-trace-hardening.md) |
+| ISS-006 | 固定诊断评测集与回归 Harness | 已归档 | [archived/ISS-006-diagnosis-eval-harness.md](archived/ISS-006-diagnosis-eval-harness.md) |
+| 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) |
+| 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/ISS-003-mvp-design-implementation-review.md b/mvp/issues/active/ISS-003-mvp-design-implementation-review.md
similarity index 100%
rename from mvp/issues/ISS-003-mvp-design-implementation-review.md
rename to mvp/issues/active/ISS-003-mvp-design-implementation-review.md
diff --git a/mvp/issues/ISS-004-executor-domain-hard-limit.md b/mvp/issues/active/ISS-004-executor-domain-hard-limit.md
similarity index 100%
rename from mvp/issues/ISS-004-executor-domain-hard-limit.md
rename to mvp/issues/active/ISS-004-executor-domain-hard-limit.md
diff --git a/mvp/issues/executor-evidence-attribution-hallucination.md b/mvp/issues/active/executor-evidence-attribution-hallucination.md
similarity index 100%
rename from mvp/issues/executor-evidence-attribution-hallucination.md
rename to mvp/issues/active/executor-evidence-attribution-hallucination.md
diff --git a/mvp/issues/rag-refactor-plan.md b/mvp/issues/active/rag-refactor-plan.md
similarity index 90%
rename from mvp/issues/rag-refactor-plan.md
rename to mvp/issues/active/rag-refactor-plan.md
index 24eef56..d7e28ce 100644
--- a/mvp/issues/rag-refactor-plan.md
+++ b/mvp/issues/active/rag-refactor-plan.md
@@ -347,19 +347,19 @@ RAG、Agent、AIOps、数据库记录互相关联，必须分阶段推进，每
 
 本计划合并以下问题和改造方向：
 
-- [rag-chunk-context-reconstruction.md](rag-chunk-context-reconstruction.md)
-- [rag-breadcrumb-embedding-gap.md](rag-breadcrumb-embedding-gap.md)
-- [rag-l0-l1-fusion-ranking.md](rag-l0-l1-fusion-ranking.md)
-- [rag-l0-keyword-matching-quality.md](rag-l0-keyword-matching-quality.md)
-- [rag-l1-score-calibration.md](rag-l1-score-calibration.md)
-- [rag-context-packing-and-reranking.md](rag-context-packing-and-reranking.md)
-- [rag-upload-chunk-parameter-drift.md](rag-upload-chunk-parameter-drift.md)
-- [rag-query-rewrite-gap.md](rag-query-rewrite-gap.md)
-- [rag-spring-ai-vectorstore-migration.md](rag-spring-ai-vectorstore-migration.md)
-- [rag-spring-ai-query-transformer.md](rag-spring-ai-query-transformer.md)
-- [rag-spring-ai-document-postprocessor.md](rag-spring-ai-document-postprocessor.md)
-- [rag-l0-domain-entity-hint.md](rag-l0-domain-entity-hint.md)
-- [rag-spring-ai-advisor-boundary.md](rag-spring-ai-advisor-boundary.md)
+- [rag-chunk-context-reconstruction.md](../rag/rag-chunk-context-reconstruction.md)
+- [rag-breadcrumb-embedding-gap.md](../rag/rag-breadcrumb-embedding-gap.md)
+- [rag-l0-l1-fusion-ranking.md](../rag/rag-l0-l1-fusion-ranking.md)
+- [rag-l0-keyword-matching-quality.md](../rag/rag-l0-keyword-matching-quality.md)
+- [rag-l1-score-calibration.md](../rag/rag-l1-score-calibration.md)
+- [rag-context-packing-and-reranking.md](../rag/rag-context-packing-and-reranking.md)
+- [rag-upload-chunk-parameter-drift.md](../rag/rag-upload-chunk-parameter-drift.md)
+- [rag-query-rewrite-gap.md](../rag/rag-query-rewrite-gap.md)
+- [rag-spring-ai-vectorstore-migration.md](../rag/rag-spring-ai-vectorstore-migration.md)
+- [rag-spring-ai-query-transformer.md](../rag/rag-spring-ai-query-transformer.md)
+- [rag-spring-ai-document-postprocessor.md](../rag/rag-spring-ai-document-postprocessor.md)
+- [rag-l0-domain-entity-hint.md](../rag/rag-l0-domain-entity-hint.md)
+- [rag-spring-ai-advisor-boundary.md](../rag/rag-spring-ai-advisor-boundary.md)
 
 ---
 
diff --git a/mvp/issues/ISS-001-duplicate-retrieval.md b/mvp/issues/archived/ISS-001-duplicate-retrieval.md
similarity index 97%
rename from mvp/issues/ISS-001-duplicate-retrieval.md
rename to mvp/issues/archived/ISS-001-duplicate-retrieval.md
index 5f2c4a6..4326b1a 100644
--- a/mvp/issues/ISS-001-duplicate-retrieval.md
+++ b/mvp/issues/archived/ISS-001-duplicate-retrieval.md
@@ -4,7 +4,7 @@
 **严重程度**：中（影响 token 消耗和上下文质量，不影响功能正确性）
 **发现时间**：2026-06-30
 **修复版本**：session-dedup-knowledge-map
-**历史架构文档**：[会话级去重与知识域地图](../architecture/archive/2026-07-05-legacy/session-dedup-knowledge-map.md)
+**历史架构文档**：[会话级去重与知识域地图](../../architecture/archive/2026-07-05-legacy/session-dedup-knowledge-map.md)
 
 ---
 
diff --git a/mvp/issues/ISS-002-executor-unconstrained-lookup.md b/mvp/issues/archived/ISS-002-executor-unconstrained-lookup.md
similarity index 100%
rename from mvp/issues/ISS-002-executor-unconstrained-lookup.md
rename to mvp/issues/archived/ISS-002-executor-unconstrained-lookup.md
diff --git a/mvp/issues/ISS-005-evidence-trace-hardening.md b/mvp/issues/archived/ISS-005-evidence-trace-hardening.md
similarity index 100%
rename from mvp/issues/ISS-005-evidence-trace-hardening.md
rename to mvp/issues/archived/ISS-005-evidence-trace-hardening.md
diff --git a/mvp/issues/ISS-006-diagnosis-eval-harness.md b/mvp/issues/archived/ISS-006-diagnosis-eval-harness.md
similarity index 100%
rename from mvp/issues/ISS-006-diagnosis-eval-harness.md
rename to mvp/issues/archived/ISS-006-diagnosis-eval-harness.md
diff --git a/mvp/issues/ISS-007-verifier-evidence-summary-fidelity.md b/mvp/issues/archived/ISS-007-verifier-evidence-summary-fidelity.md
similarity index 100%
rename from mvp/issues/ISS-007-verifier-evidence-summary-fidelity.md
rename to mvp/issues/archived/ISS-007-verifier-evidence-summary-fidelity.md
diff --git a/mvp/issues/ISS-008-executor-narrow-scope-overreach.md b/mvp/issues/archived/ISS-008-executor-narrow-scope-overreach.md
similarity index 100%
rename from mvp/issues/ISS-008-executor-narrow-scope-overreach.md
rename to mvp/issues/archived/ISS-008-executor-narrow-scope-overreach.md
diff --git a/mvp/issues/ISS-009-negative-observation-no-evidence-reference.md b/mvp/issues/archived/ISS-009-negative-observation-no-evidence-reference.md
similarity index 100%
rename from mvp/issues/ISS-009-negative-observation-no-evidence-reference.md
rename to mvp/issues/archived/ISS-009-negative-observation-no-evidence-reference.md
diff --git a/mvp/issues/diagnosis-eval-baseline-diff.md b/mvp/issues/archived/diagnosis-eval-baseline-diff.md
similarity index 100%
rename from mvp/issues/diagnosis-eval-baseline-diff.md
rename to mvp/issues/archived/diagnosis-eval-baseline-diff.md
diff --git a/mvp/issues/expand-diagnosis-eval-fixtures.md b/mvp/issues/archived/expand-diagnosis-eval-fixtures.md
similarity index 100%
rename from mvp/issues/expand-diagnosis-eval-fixtures.md
rename to mvp/issues/archived/expand-diagnosis-eval-fixtures.md
diff --git a/mvp/issues/mvp-demo-interview-runbook.md b/mvp/issues/archived/mvp-demo-interview-runbook.md
similarity index 100%
rename from mvp/issues/mvp-demo-interview-runbook.md
rename to mvp/issues/archived/mvp-demo-interview-runbook.md
diff --git a/mvp/issues/executor-self-evidence-loop-design-note.md b/mvp/issues/design-notes/executor-self-evidence-loop-design-note.md
similarity index 100%
rename from mvp/issues/executor-self-evidence-loop-design-note.md
rename to mvp/issues/design-notes/executor-self-evidence-loop-design-note.md
diff --git a/mvp/issues/executor-structured-output-v2.md b/mvp/issues/design-notes/executor-structured-output-v2.md
similarity index 100%
rename from mvp/issues/executor-structured-output-v2.md
rename to mvp/issues/design-notes/executor-structured-output-v2.md
diff --git a/mvp/issues/rag-breadcrumb-embedding-gap.md b/mvp/issues/rag/rag-breadcrumb-embedding-gap.md
similarity index 100%
rename from mvp/issues/rag-breadcrumb-embedding-gap.md
rename to mvp/issues/rag/rag-breadcrumb-embedding-gap.md
diff --git a/mvp/issues/rag-chunk-context-reconstruction.md b/mvp/issues/rag/rag-chunk-context-reconstruction.md
similarity index 100%
rename from mvp/issues/rag-chunk-context-reconstruction.md
rename to mvp/issues/rag/rag-chunk-context-reconstruction.md
diff --git a/mvp/issues/rag-context-packing-and-reranking.md b/mvp/issues/rag/rag-context-packing-and-reranking.md
similarity index 100%
rename from mvp/issues/rag-context-packing-and-reranking.md
rename to mvp/issues/rag/rag-context-packing-and-reranking.md
diff --git a/mvp/issues/rag-l0-domain-entity-hint.md b/mvp/issues/rag/rag-l0-domain-entity-hint.md
similarity index 100%
rename from mvp/issues/rag-l0-domain-entity-hint.md
rename to mvp/issues/rag/rag-l0-domain-entity-hint.md
diff --git a/mvp/issues/rag-l0-keyword-matching-quality.md b/mvp/issues/rag/rag-l0-keyword-matching-quality.md
similarity index 100%
rename from mvp/issues/rag-l0-keyword-matching-quality.md
rename to mvp/issues/rag/rag-l0-keyword-matching-quality.md
diff --git a/mvp/issues/rag-l0-l1-fusion-ranking.md b/mvp/issues/rag/rag-l0-l1-fusion-ranking.md
similarity index 100%
rename from mvp/issues/rag-l0-l1-fusion-ranking.md
rename to mvp/issues/rag/rag-l0-l1-fusion-ranking.md
diff --git a/mvp/issues/rag-l1-score-calibration.md b/mvp/issues/rag/rag-l1-score-calibration.md
similarity index 100%
rename from mvp/issues/rag-l1-score-calibration.md
rename to mvp/issues/rag/rag-l1-score-calibration.md
diff --git a/mvp/issues/rag-query-rewrite-gap.md b/mvp/issues/rag/rag-query-rewrite-gap.md
similarity index 100%
rename from mvp/issues/rag-query-rewrite-gap.md
rename to mvp/issues/rag/rag-query-rewrite-gap.md
diff --git a/mvp/issues/rag-spring-ai-advisor-boundary.md b/mvp/issues/rag/rag-spring-ai-advisor-boundary.md
similarity index 100%
rename from mvp/issues/rag-spring-ai-advisor-boundary.md
rename to mvp/issues/rag/rag-spring-ai-advisor-boundary.md
diff --git a/mvp/issues/rag-spring-ai-document-postprocessor.md b/mvp/issues/rag/rag-spring-ai-document-postprocessor.md
similarity index 100%
rename from mvp/issues/rag-spring-ai-document-postprocessor.md
rename to mvp/issues/rag/rag-spring-ai-document-postprocessor.md
diff --git a/mvp/issues/rag-spring-ai-query-transformer.md b/mvp/issues/rag/rag-spring-ai-query-transformer.md
similarity index 100%
rename from mvp/issues/rag-spring-ai-query-transformer.md
rename to mvp/issues/rag/rag-spring-ai-query-transformer.md
diff --git a/mvp/issues/rag-spring-ai-vectorstore-migration.md b/mvp/issues/rag/rag-spring-ai-vectorstore-migration.md
similarity index 100%
rename from mvp/issues/rag-spring-ai-vectorstore-migration.md
rename to mvp/issues/rag/rag-spring-ai-vectorstore-migration.md
diff --git a/mvp/issues/rag-upload-chunk-parameter-drift.md b/mvp/issues/rag/rag-upload-chunk-parameter-drift.md
similarity index 100%
rename from mvp/issues/rag-upload-chunk-parameter-drift.md
rename to mvp/issues/rag/rag-upload-chunk-parameter-drift.md
diff --git a/mvp/tables/Agent步骤表-agent_step.md b/mvp/tables/Agent步骤表-agent_step.md
new file mode 100644
index 0000000..2336f6c
--- /dev/null
+++ b/mvp/tables/Agent步骤表-agent_step.md
@@ -0,0 +1,41 @@
+# Agent 步骤表：agent_step
+
+**状态**：当前表  
+**来源**：`V005__create_session_storage.sql`、`V006__fix_agent_step_json_to_text.sql`、`AgentStep`
+
+## 定位
+
+`agent_step` 记录一次诊断过程中每个 Agent 步骤的模型输入、输出、耗时和 Token 消耗。页面展示执行链路时应优先按 `step_index` 排序。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 关联 `diagnosis_session.session_id` |
+| `step_index` | INT | 是 | 步骤序号，从 0 开始 |
+| `agent_name` | VARCHAR(32) | 是 | Agent 名称，例如 planner、executor、verifier、composer |
+| `model_input` | TEXT | 否 | 模型输入摘要；`V006` 已从 JSON 改为 TEXT |
+| `model_output` | TEXT | 否 | 模型输出摘要；`V006` 已从 JSON 改为 TEXT |
+| `thought` | TEXT | 否 | Agent 思考过程或调试摘要 |
+| `has_tool_call` | BOOLEAN | 否 | 本步骤是否触发工具调用 |
+| `duration_ms` | INT | 否 | 本步骤耗时 |
+| `token_count` | INT | 否 | 本步骤 Token 消耗 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_session_step` | `session_id, step_index` | Trace 页面按会话和步骤顺序查询 |
+| `idx_agent_name` | `agent_name` | 按 Agent 类型筛选 |
+
+## 关系
+
+- `agent_step.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。
+
+## 注意点
+
+- 前端展示步骤时应按 `step_index` 排序，而不是按 `created_at` 或数据库返回顺序。
+- Verifier 应在 Executor 循环完成后出现；如果 `step_index` 中 Verifier 提前，通常意味着编排或记录顺序有问题。
diff --git a/mvp/tables/README.md b/mvp/tables/README.md
new file mode 100644
index 0000000..92d2001
--- /dev/null
+++ b/mvp/tables/README.md
@@ -0,0 +1,40 @@
+# MVP 数据表索引
+
+**更新日期**：2026-07-09  
+**状态**：当前表文档入口
+
+本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。
+
+## 当前表
+
+| 表 | 用途 | 文档 |
+|---|---|---|
+| `diagnosis_session` | 会话级主记录，保存 query、状态、最终答案和自评估 | [诊断会话表-diagnosis_session.md](诊断会话表-diagnosis_session.md) |
+| `agent_step` | Agent 步骤记录，按 `step_index` 回放执行链路 | [Agent步骤表-agent_step.md](Agent步骤表-agent_step.md) |
+| `tool_invocation` | 工具调用记录，支撑 Trace、Verifier 和评测 | [工具调用表-tool_invocation.md](工具调用表-tool_invocation.md) |
+| `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) |
+| `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) |
+| `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) |
+
+## 已归档表
+
+| 表 | 归档原因 | 文档 |
+|---|---|---|
+| `diagnosis_record` | 已由 `V007` 删除，被 `diagnosis_session + agent_step + tool_invocation` 替代 | [archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md](archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md) |
+
+## 核心关系
+
+```text
+diagnosis_session.session_id
+  -> agent_step.session_id
+  -> tool_invocation.session_id
+  -> case_library.diagnosis_id
+
+api_document.doc_id
+  -> vector chunk metadata.docId / doc_id
+
+knowledge_domain.domain_id
+  -> api_document metadata.category / vector chunk metadata.category
+```
+
+当前实现主要使用逻辑关联，不依赖数据库外键。
diff --git a/mvp/tables/api_document.md b/mvp/tables/api_document.md
deleted file mode 100644
index 2669213..0000000
--- a/mvp/tables/api_document.md
+++ /dev/null
@@ -1,332 +0,0 @@
-# api_document - 文档元数据表
-
-## 表定位
-
-**文档管理表**：管理接口文档的元信息，不负责文档检索（检索由 Milvus 负责）
-
-## 设计理念
-
-### 文档管理，不是文档检索
-
-**核心定位**：
-- MySQL 负责文档元数据管理（状态、版本、去重）
-- Milvus 负责文档内容存储和检索
-- 通过 doc_id 关联两者
-
-**MVP版本原则**：
-- ✅ 最简字段，满足基本管理需求
-- ✅ 文件去重（基于 file_hash）
-- ✅ 状态追踪（索引进度）
-- ✅ 硬删除（同步删除 Milvus 数据）
-- ❌ 暂不支持：软删除、启用开关、版本管理（Phase 2）
-
----
-
-## 表结构（MVP版）
-
-```sql
-CREATE TABLE api_document (
-    -- 主键
-    id BIGINT PRIMARY KEY AUTO_INCREMENT,
-    doc_id VARCHAR(64) UNIQUE NOT NULL COMMENT '文档唯一ID（UUID），关联Milvus',
-    
-    -- 文档分类
-    fault_category VARCHAR(32) DEFAULT 'EXTERNAL_API' COMMENT '文档类别',
-    fault_source VARCHAR(128) COMMENT '文档归属（省份/服务名）',
-    api_name VARCHAR(128) COMMENT '接口名称',
-    version VARCHAR(32) DEFAULT 'v1.0' COMMENT '文档版本',
-    
-    -- 文件信息
-    file_name VARCHAR(256) NOT NULL COMMENT '原始文件名',
-    file_path VARCHAR(512) COMMENT '文件存储路径',
-    file_hash VARCHAR(64) COMMENT '文件MD5 hash（用于去重）',
-    file_size BIGINT COMMENT '文件大小（字节）',
-    
-    -- 索引状态
-    status VARCHAR(16) DEFAULT 'PENDING' COMMENT '索引状态（PENDING/PROCESSING/INDEXED/FAILED）',
-    chunk_count INT DEFAULT 0 COMMENT '分块数量',
-    error_message TEXT COMMENT '失败原因',
-    
-    -- 时间字段
-    indexed_at DATETIME COMMENT '索引完成时间',
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-    
-    -- 索引
-    UNIQUE INDEX uk_file_hash (file_hash),
-    INDEX idx_doc_id (doc_id),
-    INDEX idx_fault_source (fault_source),
-    INDEX idx_status (status),
-    INDEX idx_created_at (created_at)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表（MVP版）';
-```
-
----
-
-## 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| doc_id | VARCHAR(64) | 是 | **核心**：文档唯一ID，关联 Milvus |
-| fault_category | VARCHAR(32) | 否 | 文档类别 |
-| fault_source | VARCHAR(128) | 否 | 文档归属（省份/服务名）|
-| api_name | VARCHAR(128) | 否 | 接口名称 |
-| version | VARCHAR(32) | 否 | 文档版本 |
-| file_name | VARCHAR(256) | 是 | 原始文件名 |
-| file_path | VARCHAR(512) | 否 | 文件存储路径 |
-| file_hash | VARCHAR(64) | 否 | **去重关键**：文件MD5 |
-| file_size | BIGINT | 否 | 文件大小 |
-| status | VARCHAR(16) | 是 | **状态追踪**：PENDING/PROCESSING/INDEXED/FAILED |
-| chunk_count | INT | 否 | 分块数量 |
-| error_message | TEXT | 否 | 失败原因 |
-| indexed_at | DATETIME | 否 | 索引完成时间 |
-
----
-
-## 核心设计决策
-
-### 1. doc_id：MySQL 与 Milvus 的桥梁
-
-```
-作用：
-- MySQL：通过 doc_id 管理文档元数据
-- Milvus：每个 chunk 的 metadata 中携带 doc_id
-
-关联关系：
-api_document (MySQL)
-    doc_id: doc-001
-    ↓ 1:N
-Milvus chunks
-    chunk_1: {doc_id: 'doc-001', text: '...', vector: [...]}
-    chunk_2: {doc_id: 'doc-001', text: '...', vector: [...]}
-
-管理操作：
-- 删除文档：
-  DELETE FROM milvus_collection WHERE metadata["doc_id"] == 'doc-001';
-  DELETE FROM api_document WHERE doc_id = 'doc-001';
-```
-
-### 2. file_hash：文件去重
-
-```
-去重流程：
-1. 用户上传文件
-   ↓
-2. 计算文件 MD5
-   file_hash = md5(file_content)
-   ↓
-3. 检查是否已存在
-   SELECT * FROM api_document WHERE file_hash = 'abc123...';
-   ↓
-4a. 如果存在 → 提示"文档已存在"
-4b. 如果不存在 → 继续导入
-
-唯一约束：UNIQUE INDEX uk_file_hash (file_hash)
-```
-
-### 3. status：状态追踪
-
-```
-状态流转：
-PENDING (待处理)
-    ↓
-PROCESSING (处理中)
-    ↓ 成功
-INDEXED (已索引)
-    ↓ 失败
-FAILED (失败)
-
-用途：
-- 批量导入时监控进度
-- 失败重试
-- 统计索引成功率
-```
-
-### 4. 硬删除策略（MVP）
-
-```
-删除文档时：
-1. 删除 Milvus 中的所有分块
-2. 删除 MySQL 元数据
-3. 可选：删除原始文件
-
-特点：
-- 简单直接
-- 数据彻底删除
-- 不可恢复（需谨慎）
-
-Phase 2 可增强：
-- 软删除（archived_at）
-- 启用开关（enabled）
-```
-
----
-
-## 数据流
-
-### 场景1：导入新文档
-
-```
-1. 用户上传文件
-   ↓
-2. 计算 hash
-   ↓
-3. 检查去重（MySQL）
-   ↓
-4. 插入元数据（status=PROCESSING）
-   ↓
-5. 后台处理：解析 → 分块 → 向量化 → 存入 Milvus
-   ↓
-6. 更新状态（status=INDEXED, chunk_count=15）
-```
-
-### 场景2：删除文档
-
-```
-1. 用户删除文档
-   ↓
-2. 删除 Milvus 数据（WHERE metadata["doc_id"] == 'xxx'）
-   ↓
-3. 删除 MySQL 元数据
-   ↓
-4. 可选：删除原始文件
-```
-
-### 场景3：重新索引
-
-```
-1. 删除旧数据（Milvus + MySQL）
-   ↓
-2. 重新导入（同场景1）
-```
-
----
-
-## 典型查询
-
-```sql
--- 查看文档列表
-SELECT doc_id, file_name, version, status, chunk_count, indexed_at
-FROM api_document
-WHERE fault_source = '广东'
-  AND status = 'INDEXED'
-ORDER BY indexed_at DESC;
-
--- 查询失败的文档
-SELECT doc_id, file_name, error_message
-FROM api_document
-WHERE status = 'FAILED';
-
--- 统计各状态文档数量
-SELECT status, COUNT(*) as count
-FROM api_document
-GROUP BY status;
-```
-
----
-
-## 与 Milvus 的协作
-
-### Milvus Collection Schema
-
-```python
-{
-  "collection_name": "api_doc_collection",
-  "fields": [
-    {"name": "id", "type": "VARCHAR", "is_primary": true},
-    {"name": "content", "type": "VARCHAR"},
-    {"name": "vector", "type": "FLOAT_VECTOR", "dim": 1536},
-    {"name": "metadata", "type": "JSON"}
-  ]
-}
-
-# metadata 结构
-{
-  "doc_id": "doc-001",           # 关联 MySQL
-  "_source": "/path/to/file",
-  "_file_name": "xxx.docx",
-  "chunkIndex": 0,
-  "totalChunks": 15
-}
-```
-
-### Java 代码示例
-
-```java
-// 插入时携带 doc_id
-Map<String, Object> metadata = new HashMap<>();
-metadata.put("doc_id", docId);  // 关联 MySQL
-metadata.put("_source", filePath);
-metadata.put("chunkIndex", chunkIndex);
-
-// 删除文档的所有分块
-String expr = String.format("metadata[\"doc_id\"] == \"%s\"", docId);
-milvusClient.delete(DeleteParam.newBuilder()
-    .withCollectionName(COLLECTION_NAME)
-    .withExpr(expr)
-    .build());
-```
-
----
-
-## 数据示例
-
-```sql
--- 外部接口文档
-INSERT INTO api_document VALUES
-(1, 'doc-001', 'EXTERNAL_API', '广东', '社保查询', 'v2.1',
- '广东社保查询v2.1.docx', '/docs/guangdong/social-v2.1.docx',
- 'abc123...', 1048576,
- 'INDEXED', 15, NULL, '2024-06-15 10:30:00', NOW(), NOW());
-
--- 内部服务文档
-INSERT INTO api_document VALUES
-(2, 'doc-002', 'INTERNAL_ERROR', 'order-service', '订单服务API', 'v1.0',
- '订单服务API文档.pdf', '/docs/internal/order-service-api.pdf',
- 'def456...', 2097152,
- 'INDEXED', 20, NULL, '2024-06-14 15:20:00', NOW(), NOW());
-
--- 处理失败的文档
-INSERT INTO api_document VALUES
-(3, 'doc-003', 'EXTERNAL_API', '江苏', '公积金查询', 'v1.5',
- '江苏公积金查询.html', '/docs/jiangsu/fund-v1.5.html',
- 'ghi789...', 512000,
- 'FAILED', 0, '不支持HTML格式', NULL, NOW(), NOW());
-```
-
----
-
-## 数据量预估
-
-```
-预估：100-200 条
-- 外部接口文档：50-100 条
-- 内部服务文档：20-50 条
-- 其他文档：30-50 条
-
-存储：
-- 单条记录：约 1KB
-- 200 条：约 200KB
-
-结论：数据量很小
-```
-
----
-
-## MVP 版本的简化
-
-```
-Phase 1（当前）：
-✅ 基础字段和表结构
-✅ 文件去重（file_hash）
-✅ 状态追踪（status）
-✅ 硬删除
-✅ 通过 doc_id 关联 Milvus
-
-Phase 2（未来增强）：
-❌ enabled（启用开关）
-❌ archived_at（软删除）
-❌ batch_id（批次管理）
-❌ status 细化
-❌ tags（标签分类）
-```
diff --git a/mvp/tables/diagnosis_record.md b/mvp/tables/archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md
similarity index 96%
rename from mvp/tables/diagnosis_record.md
rename to mvp/tables/archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md
index db43a9e..37b89cc 100644
--- a/mvp/tables/diagnosis_record.md
+++ b/mvp/tables/archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md
@@ -1,4 +1,6 @@
-# diagnosis_record - 诊断记录表
+# diagnosis_record - 旧诊断记录表
+
+> 归档说明：`diagnosis_record` 已在 `V007__drop_diagnosis_record.sql` 中删除，当前主模型是 `diagnosis_session + agent_step + tool_invocation`。本文只用于追溯早期设计。
 
 ## 表定位
 
diff --git a/mvp/tables/case_library.md b/mvp/tables/case_library.md
deleted file mode 100644
index 74c23f9..0000000
--- a/mvp/tables/case_library.md
+++ /dev/null
@@ -1,265 +0,0 @@
-# case_library - 案例库表
-
-## 表定位
-
-**知识沉淀表**：存储高质量诊断案例，支持相似案例推荐
-
-## 设计理念
-
-### 知识沉淀，系统越用越智能
-
-**核心价值**：
-- 质量过滤：只存储高质量案例（成功诊断 + 用户反馈有用）
-- 知识沉淀：历史诊断经验可复用
-- 提升准确率：相似问题提供历史参考
-- 加速诊断：快速推荐相似案例
-
-**MVP版本设计原则**：
-- ✅ 能用：满足基本案例推荐功能
-- ✅ 简单：字段不多，逻辑清晰
-- ✅ 可扩展：后续可增加字段
-
----
-
-## 表结构（MVP版）
-
-```sql
-CREATE TABLE case_library (
-    -- 主键
-    id BIGINT PRIMARY KEY AUTO_INCREMENT,
-    case_id VARCHAR(64) UNIQUE NOT NULL COMMENT '案例唯一ID（UUID）',
-    
-    -- 来源关联
-    diagnosis_id VARCHAR(64) COMMENT '关联诊断记录（可选，人工录入时为空）',
-    source_type VARCHAR(16) DEFAULT 'AUTO' COMMENT '来源类型（AUTO:自动生成/MANUAL:人工录入）',
-    
-    -- 案例分类
-    fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE...）',
-    fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名...）',
-    fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL...）',
-    error_code VARCHAR(64) COMMENT '错误码',
-    
-    -- 案例内容
-    title VARCHAR(256) NOT NULL COMMENT '案例标题（简短描述）',
-    root_cause TEXT NOT NULL COMMENT '根因分析',
-    solution TEXT NOT NULL COMMENT '解决方案',
-    
-    -- 简单统计
-    reference_count INT DEFAULT 0 COMMENT '引用次数（被推荐的次数）',
-    
-    -- 元数据
-    created_by VARCHAR(64) COMMENT '创建人',
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-    
-    -- 索引
-    INDEX idx_fault_category (fault_category),
-    INDEX idx_error_code (error_code),
-    INDEX idx_fault_source (fault_source),
-    INDEX idx_fault_target (fault_target(100)),
-    INDEX idx_diagnosis_id (diagnosis_id),
-    INDEX idx_reference_count (reference_count),
-    INDEX idx_created_at (created_at)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='案例库表（MVP版）';
-```
-
----
-
-## 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| case_id | VARCHAR(64) | 是 | 案例唯一标识（UUID）|
-| diagnosis_id | VARCHAR(64) | 否 | 关联诊断记录（人工录入时为空）|
-| source_type | VARCHAR(16) | 是 | 来源：AUTO（自动）/MANUAL（人工）|
-| fault_category | VARCHAR(32) | 否 | 故障类别 |
-| fault_source | VARCHAR(128) | 否 | 故障源 |
-| fault_target | VARCHAR(256) | 否 | 故障目标（与 diagnosis_record 一致）|
-| error_code | VARCHAR(64) | 否 | 错误码 |
-| title | VARCHAR(256) | 是 | 案例标题 |
-| root_cause | TEXT | 是 | 根因分析（核心内容）|
-| solution | TEXT | 是 | 解决方案（核心内容）|
-| reference_count | INT | 是 | 引用次数（用于排序）|
-
----
-
-## 核心设计决策
-
-### 1. 案例来源
-
-```
-来源1：自动生成（source_type=AUTO）
-├─ 触发条件：诊断成功 + 用户反馈"有用"
-├─ 关联诊断：diagnosis_id 不为空
-└─ 质量保证：用户验证过
-
-来源2：人工录入（source_type=MANUAL）
-├─ 运维团队总结的经典案例
-├─ diagnosis_id 为空
-└─ 质量最高
-
-注意：诊断失败或用户反馈"无用"的不自动生成案例
-```
-
-### 2. 简化的评分机制（MVP）
-
-```
-MVP版本：只按 reference_count 排序
-- 引用次数多的排前面
-- 简单有效
-
-Phase 2 可增强：
-- 增加 useful_count（用户反馈有用次数）
-- 增加 score（综合评分）
-- 增加 is_featured（人工标记的经典案例）
-```
-
-### 3. 与 diagnosis_record 的关系
-
-```
-关系：一对一（可选）
-- 一次诊断 → 可以生成一个案例
-- 通过 diagnosis_id 关联
-- diagnosis_id 可为空（人工录入案例）
-
-流程：
-diagnosis_record（成功）
-    ↓
-用户反馈"有用"
-    ↓
-自动生成 case_library
-    ↓
-后续可人工修正、合并相似案例
-```
-
----
-
-## 数据示例
-
-### 示例1：外部接口故障案例
-```sql
-INSERT INTO case_library VALUES
-(1, 'case-001', 'diag-001', 'AUTO', 'EXTERNAL_API', '广东', '/api/v1/guangdong/social-security', '40003', 
- '广东社保查询idCard字段缺失', 
- '请求报文中未传入idCard字段，导致参数校验失败', 
- '前端表单增加idCard必填校验；后端增加参数校验提示', 
- 15, 'system', NOW(), NOW());
-```
-
-### 示例2：内部错误案例
-```sql
-INSERT INTO case_library VALUES
-(2, 'case-002', 'diag-045', 'AUTO', 'INTERNAL_ERROR', 'order-service', 'OrderController.createOrder()', 'NullPointerException',
- '订单服务创建订单空指针异常',
- 'OrderController.createOrder()方法中user对象为null，未做空判断',
- '在第45行添加空判断：if (user == null) throw new BizException("用户信息不存在")',
- 8, 'system', NOW(), NOW());
-```
-
-### 示例3：人工录入案例
-```sql
-INSERT INTO case_library VALUES
-(3, 'case-003', NULL, 'MANUAL', 'DATABASE', 'mysql-master-01', 'UPDATE orders SET status=? WHERE order_id=?', '1213',
- '订单库存更新死锁通用处理',
- '两个事务互相等待对方释放锁',
- '调整事务加锁顺序：统一先锁订单，再锁库存；或使用乐观锁',
- 3, 'admin', NOW(), NOW());
-```
-
----
-
-## 典型查询
-
-### 精确匹配查询
-```sql
--- 按错误码查询
-SELECT * FROM case_library
-WHERE error_code = '40003'
-ORDER BY reference_count DESC
-LIMIT 5;
-
--- 按故障类别 + 错误码 + 故障目标查询
-SELECT * FROM case_library
-WHERE fault_category = 'INTERNAL_ERROR'
-  AND error_code = 'NullPointerException'
-  AND fault_target = 'OrderController.createOrder()'
-ORDER BY reference_count DESC
-LIMIT 5;
-```
-
-### 统计分析
-```sql
--- 统计案例分布
-SELECT 
-  fault_category,
-  COUNT(*) as count,
-  AVG(reference_count) as avg_reference
-FROM case_library
-GROUP BY fault_category
-ORDER BY count DESC;
-
--- Top 引用案例
-SELECT title, reference_count, created_at
-FROM case_library
-ORDER BY reference_count DESC
-LIMIT 10;
-```
-
----
-
-## 与 Milvus 的配合
-
-### 混合检索策略
-
-```
-1. 精确匹配（MySQL）
-   - 按 error_code 查询
-   - 按 fault_category + fault_source 查询
-   - 优点：快速、准确
-
-2. 语义检索（Milvus）
-   - 将案例内容向量化
-   - 按语义相似度查询
-   - 优点：能找到相似但不同错误码的案例
-
-3. 混合策略（推荐）
-   Step 1: 先精确匹配（MySQL）
-   Step 2: 如果结果 < 3 个，补充语义检索（Milvus）
-   Step 3: 合并去重，按 reference_count 排序
-   Step 4: 返回 Top 5
-```
-
----
-
-## 数据量预估
-
-```
-预估：500-1000 条
-- 初期：每月新增 10-20 条
-- 稳定期：每月新增 5-10 条
-- 总量：1-2 年达到稳定
-
-存储：
-- 单条记录：约 2KB
-- 1000 条：约 2MB
-
-结论：数据量很小
-```
-
----
-
-## MVP 版本的简化
-
-```
-Phase 1（当前）：
-✅ 基础字段和表结构
-✅ 自动生成案例
-✅ 人工录入案例
-✅ 按 reference_count 简单排序
-
-Phase 2（未来增强）：
-❌ useful_count + score（复杂评分）
-❌ 版本管理
-❌ 标签分类（tags）
-❌ 案例合并功能
-```
diff --git a/mvp/tables/工具调用表-tool_invocation.md b/mvp/tables/工具调用表-tool_invocation.md
new file mode 100644
index 0000000..b1475b9
--- /dev/null
+++ b/mvp/tables/工具调用表-tool_invocation.md
@@ -0,0 +1,66 @@
+# 工具调用表：tool_invocation
+
+**状态**：当前表  
+**来源**：`V005__create_session_storage.sql`、`V010__add_relevance_level_to_tool_invocation.sql`、`ToolInvocation`
+
+## 定位
+
+`tool_invocation` 记录 Agent 显式调用工具的事实，包括工具名、入参、输出摘要、检索层级、证据引用和失败信息。它是 Trace、Verifier、评测和人工排查的共同数据源。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 关联 `diagnosis_session.session_id` |
+| `step_id` | BIGINT | 否 | 可关联 `agent_step.id` |
+| `tool_name` | VARCHAR(64) | 是 | 工具名称，例如 `lookup_knowledge`、日志查询、指标查询 |
+| `input_params` | JSON | 是 | 工具入参 |
+| `output_preview` | TEXT | 否 | 工具输出摘要或前缀 |
+| `output_length` | INT | 否 | 工具输出字符数 |
+| `retrieval_layer` | VARCHAR(8) | 否 | 检索层级，例如 `L0`、`L1`、`L0+L1` |
+| `l0_match_count` | INT | 否 | L0 命中数量 |
+| `l1_match_count` | INT | 否 | L1 命中数量 |
+| `is_truncated` | BOOLEAN | 否 | 输出是否被截断 |
+| `relevance_level` | VARCHAR(20) | 否 | 归一化质量等级：`PRECISE`、`HIGHLY_RELEVANT`、`REFERENCE`、`DEDUPED` |
+| `dedup_reason` | VARCHAR(32) | 否 | 去重原因，例如 `doc_retrieved`、`domain_retrieved` |
+| `retrieval_details` | JSON | 否 | 检索明细、证据引用、Gatekeeper 可用导航信息 |
+| `duration_ms` | INT | 否 | 工具耗时 |
+| `success` | BOOLEAN | 否 | 工具是否成功 |
+| `error_message` | TEXT | 否 | 失败原因 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_session_id` | `session_id` | 按会话查询工具调用 |
+| `idx_tool_name` | `tool_name` | 按工具类型排查 |
+| `idx_retrieval_layer` | `retrieval_layer` | 观察 RAG L0/L1 行为 |
+
+## 关系
+
+- `tool_invocation.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前不强制。
+
+## 关键 JSON
+
+`retrieval_details` 是扩展字段。当前重要结构包括：
+
+```json
+{
+  "evidence_status": "supported",
+  "evidence_refs": [
+    {
+      "raw_path": "$.logs[0]",
+      "text": "工具返回中可核对的最小证据文本"
+    }
+  ]
+}
+```
+
+## 注意点
+
+- Verifier 不应只信任 RAG 证据；所有工具只要能提供 `evidence_refs`，都应该进入可校验证据链。
+- `output_preview` 只适合展示和排查，不应被当成完整原始输出。
+- `$.no_evidence` 只代表“本次工具未命中证据”，不能推导为“故障不存在”。
diff --git a/mvp/tables/文档元数据表-api_document.md b/mvp/tables/文档元数据表-api_document.md
new file mode 100644
index 0000000..b978a28
--- /dev/null
+++ b/mvp/tables/文档元数据表-api_document.md
@@ -0,0 +1,51 @@
+# 文档元数据表：api_document
+
+**状态**：当前表  
+**来源**：`V003__create_api_document.sql`、`V004__add_metadata_to_api_document.sql`、`ApiDocument`
+
+## 定位
+
+`api_document` 是知识库文档的 MySQL 元数据表。它不保存向量正文，正文切片和向量检索由 Milvus/Zilliz collection 承担；两侧通过 `doc_id` 和 chunk metadata 逻辑关联。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `doc_id` | VARCHAR(64) | 是 | 文档唯一 ID，关联向量库 chunk metadata |
+| `fault_category` | VARCHAR(32) | 否 | 文档类别，默认 `EXTERNAL_API`；实体侧使用 `FaultCategory` |
+| `fault_source` | VARCHAR(128) | 否 | 文档归属，例如服务名、省份或系统来源 |
+| `api_name` | VARCHAR(128) | 否 | 接口或文档主题名称 |
+| `version` | VARCHAR(32) | 否 | 文档版本，默认 `v1.0` |
+| `file_name` | VARCHAR(256) | 是 | 原始文件名 |
+| `file_path` | VARCHAR(512) | 否 | 文件存储路径 |
+| `file_hash` | VARCHAR(64) | 否 | 文件 MD5，用于去重 |
+| `file_size` | BIGINT | 否 | 文件大小，单位字节 |
+| `status` | VARCHAR(16) | 否 | 索引状态：`PENDING`、`PROCESSING`、`INDEXED`、`FAILED` |
+| `chunk_count` | INT | 否 | 向量库切片数量 |
+| `error_message` | TEXT | 否 | 索引失败原因 |
+| `metadata` | TEXT | 否 | frontmatter 元数据 JSON 字符串 |
+| `indexed_at` | DATETIME | 否 | 索引完成时间 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `uk_file_hash` | `file_hash` | 文件去重 |
+| `idx_doc_id` | `doc_id` | 按文档 ID 查询 |
+| `idx_fault_source` | `fault_source` | 按来源筛选 |
+| `idx_status` | `status` | 查看索引状态 |
+| `idx_created_at` | `created_at` | 按上传时间排序 |
+
+## 关系
+
+- `api_document.doc_id` 与向量库 chunk metadata 中的 `docId` / `doc_id` 逻辑关联。
+- `knowledge_domain.domain_id` 与文档 metadata 中的 `category` 形成领域聚合关系；当前没有数据库外键。
+
+## 注意点
+
+- 删除文档时需要同时处理 MySQL 元数据和向量库 chunk。
+- `metadata` 是 JSON 字符串，不是 MySQL JSON 列。
+- 表字段以 Flyway 为准；实体默认值和枚举可能与迁移脚本的 SQL 默认值存在历史差异，排查时优先看实际迁移和数据库结构。
diff --git a/mvp/tables/案例库表-case_library.md b/mvp/tables/案例库表-case_library.md
new file mode 100644
index 0000000..ed3315f
--- /dev/null
+++ b/mvp/tables/案例库表-case_library.md
@@ -0,0 +1,50 @@
+# 案例库表：case_library
+
+**状态**：当前表  
+**来源**：`V002__create_case_library.sql`、`CaseLibrary`
+
+## 定位
+
+`case_library` 保存高质量诊断案例，用于后续相似案例推荐和知识沉淀。当前自动沉淀路径来自 `useful` 用户反馈：系统把 `diagnosis_session` 中的 query 和 answer 映射为案例内容。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `case_id` | VARCHAR(64) | 是 | 案例唯一 ID |
+| `diagnosis_id` | VARCHAR(64) | 否 | 关联诊断会话；当前自动生成时存 `diagnosis_session.session_id` |
+| `source_type` | VARCHAR(16) | 否 | 来源类型：`AUTO` 或 `MANUAL` |
+| `fault_category` | VARCHAR(32) | 否 | 故障类别，实体侧使用 `FaultCategory` |
+| `fault_source` | VARCHAR(128) | 否 | 故障源，例如服务、系统或省份 |
+| `fault_target` | VARCHAR(256) | 否 | 故障目标，例如接口、方法、SQL 或组件 |
+| `error_code` | VARCHAR(64) | 否 | 错误码或异常类型 |
+| `title` | VARCHAR(256) | 是 | 案例标题 |
+| `root_cause` | TEXT | 是 | 根因分析 |
+| `solution` | TEXT | 是 | 解决方案 |
+| `reference_count` | INT | 否 | 被推荐次数 |
+| `created_by` | VARCHAR(64) | 否 | 创建人 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_fault_category` | `fault_category` | 按故障类别筛选 |
+| `idx_error_code` | `error_code` | 按错误码精确匹配 |
+| `idx_fault_source` | `fault_source` | 按故障源筛选 |
+| `idx_fault_target` | `fault_target(100)` | 按故障目标筛选 |
+| `idx_diagnosis_id` | `diagnosis_id` | 追溯来源会话 |
+| `idx_reference_count` | `reference_count` | 推荐排序 |
+| `idx_created_at` | `created_at` | 时间排序 |
+
+## 关系
+
+- `case_library.diagnosis_id` 当前逻辑关联 `diagnosis_session.session_id`，不是旧的 `diagnosis_record`。
+- 人工录入案例可以不填写 `diagnosis_id`。
+
+## 注意点
+
+- 旧文档里提到的 `diagnosis_record` 已被 `V007` 删除，不再是当前主模型。
+- 当前自动沉淀仍比较粗：`root_cause` 和 `solution` 都可能来自完整 answer。后续可从结构化结论中拆分根因、证据和修复建议。
diff --git a/mvp/tables/知识域表-knowledge_domain.md b/mvp/tables/知识域表-knowledge_domain.md
new file mode 100644
index 0000000..978e74d
--- /dev/null
+++ b/mvp/tables/知识域表-knowledge_domain.md
@@ -0,0 +1,36 @@
+# 知识域表：knowledge_domain
+
+**状态**：当前表  
+**来源**：`V009__add_knowledge_domain.sql`、`KnowledgeDomain`
+
+## 定位
+
+`knowledge_domain` 保存知识库领域级元数据，用来帮助 Planner/Executor 判断什么时候检索某一类知识，并为 RAG 的 domain hint、去重和可观测性提供基础信息。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `domain_id` | VARCHAR(64) | 是 | 领域 ID，通常对应文档 category，例如 `payment`、`infrastructure` |
+| `description` | VARCHAR(256) | 否 | 领域描述 |
+| `when_to_retrieve` | TEXT | 否 | 何时检索该领域的提示说明 |
+| `document_count` | INT | 是 | 当前领域文档数量 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| unique | `domain_id` | 保证领域 ID 唯一 |
+
+## 关系
+
+- `knowledge_domain.domain_id` 与 `api_document.metadata` 或向量库 chunk metadata 中的 `category` 逻辑关联。
+- 当前没有数据库外键，领域文档数量由服务逻辑维护。
+
+## 注意点
+
+- `when_to_retrieve` 是检索策略提示，不是事实证据。
+- Executor / Verifier 不能把领域描述当作诊断结论依据；事实仍应来自工具返回的证据块或证据引用。
diff --git a/mvp/tables/诊断会话表-diagnosis_session.md b/mvp/tables/诊断会话表-diagnosis_session.md
new file mode 100644
index 0000000..46b4ed0
--- /dev/null
+++ b/mvp/tables/诊断会话表-diagnosis_session.md
@@ -0,0 +1,47 @@
+# 诊断会话表：diagnosis_session
+
+**状态**：当前主表  
+**来源**：`V005__create_session_storage.sql`、`V008__add_answer_to_diagnosis_session.sql`、`DiagnosisSession`
+
+## 定位
+
+`diagnosis_session` 是一次 Chat 或 AIOps 诊断的会话级主记录，负责保存用户问题、执行状态、最终答案、总体统计和自评估结果。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 会话唯一 ID，Trace API 和反馈接口使用它 |
+| `query` | TEXT | 是 | 用户原始问题或 AIOps 输入摘要 |
+| `status` | VARCHAR(16) | 否 | `PENDING`、`RUNNING`、`SUCCESS`、`FAILED` |
+| `agent_flow` | VARCHAR(32) | 否 | `CHAT` 或 `AI_OPS` |
+| `total_duration_ms` | INT | 否 | 总耗时，单位毫秒 |
+| `total_token_count` | INT | 否 | 总 Token 消耗 |
+| `step_count` | INT | 否 | Agent 步骤数 |
+| `tool_call_count` | INT | 否 | 工具调用次数 |
+| `answer` | LONGTEXT | 否 | 返回给用户的最终答案 |
+| `self_evaluation` | JSON | 否 | rule、verifier、aiops 等自评估结果容器 |
+| `feedback` | VARCHAR(16) | 否 | 用户反馈：`useful`、`not_useful` 或空 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `session_id` unique | `session_id` | 会话唯一约束 |
+| `idx_created_at` | `created_at` | 按时间查询 |
+| `idx_status` | `status` | 按状态筛选 |
+| `idx_agent_flow` | `agent_flow` | 区分 Chat / AIOps |
+
+## 关系
+
+- `agent_step.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `case_library.diagnosis_id` 在自动生成案例时保存 `diagnosis_session.session_id`。
+
+## 注意点
+
+- 当前没有数据库外键，Trace 聚合依赖 `session_id`。
+- `self_evaluation` 是扩展容器，里面可能包含 `rule_evaluation`、`verifier_evaluation`、`aiops_rule_evaluation`。
diff --git a/openspec/changes/archive/2026-07-08-executor-composer-final-answer/decisions.md b/openspec/changes/archive/2026-07-08-executor-composer-final-answer/decisions.md
index 37befca..7d2a00a 100644
--- a/openspec/changes/archive/2026-07-08-executor-composer-final-answer/decisions.md
+++ b/openspec/changes/archive/2026-07-08-executor-composer-final-answer/decisions.md
@@ -30,7 +30,7 @@
 
 | Source | Alignment |
 |---|---|
-| Issue objective | Stage four in `mvp/issues/executor-structured-output-v2.md` requires Composer output final answer from Verifier-allowed material. Covered by proposal, design, specs, and tasks. |
+| Issue objective | Stage four in `mvp/issues/design-notes/executor-structured-output-v2.md` requires Composer output final answer from Verifier-allowed material. Covered by proposal, design, specs, and tasks. |
 | Proposal -> design | Proposal says Composer owns final expression; design defines input filtering, output parsing, fallback, and audit. |
 | Design -> specs | Design decisions are reflected in `chat-composer-agent` requirements and modified `chat-verifier-agent` routing requirements. |
 | Specs -> tasks | Each required behavior has implementation and test tasks, including malformed fallback and no raw output leakage. |
diff --git a/openspec/changes/archive/2026-07-08-verifier-evidence-reference-fidelity/decisions.md b/openspec/changes/archive/2026-07-08-verifier-evidence-reference-fidelity/decisions.md
index 6fb68c2..1b284c5 100644
--- a/openspec/changes/archive/2026-07-08-verifier-evidence-reference-fidelity/decisions.md
+++ b/openspec/changes/archive/2026-07-08-verifier-evidence-reference-fidelity/decisions.md
@@ -2,7 +2,7 @@
 
 ## Discover Context
 
-- Source issue: `mvp/issues/ISS-007-verifier-evidence-summary-fidelity.md`.
+- Source issue: `mvp/issues/archived/ISS-007-verifier-evidence-summary-fidelity.md`.
 - Related existing specs: `chat-verifier-agent`, `evidence-trace-hardening`.
 - Related devflow records: `executor-gatekeeper-hook`, `executor-verifier-claim-checks`, `executor-composer-final-answer`, `evidence-trace-hardening`.
 - Current repo instruction requested semantic code search and LSP confirmation before code changes; those tools are not exposed in this environment, so implementation will use `rg`, direct code reading, and focused tests as fallback evidence.