docs(mvp): organize mvp documentation
This commit is contained in:
zhuyongxin
+22
-15
@@ -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 的最新记录为准。
|
||||
|
||||
@@ -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)）
|
||||
|
||||
@@ -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. 架构目标
|
||||
|
||||
|
||||
@@ -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` 为准。
|
||||
+55
-38
@@ -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) |
|
||||
|
||||
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
+1
-1
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
@@ -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 提前，通常意味着编排或记录顺序有问题。
|
||||
@@ -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
|
||||
```
|
||||
|
||||
当前实现主要使用逻辑关联，不依赖数据库外键。
|
||||
@@ -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（标签分类）
|
||||
```
|
||||
+3
-1
@@ -1,4 +1,6 @@
|
||||
# diagnosis_record - 诊断记录表
|
||||
# diagnosis_record - 旧诊断记录表
|
||||
|
||||
> 归档说明：`diagnosis_record` 已在 `V007__drop_diagnosis_record.sql` 中删除，当前主模型是 `diagnosis_session + agent_step + tool_invocation`。本文只用于追溯早期设计。
|
||||
|
||||
## 表定位
|
||||
|
||||
@@ -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）
|
||||
❌ 案例合并功能
|
||||
```
|
||||
@@ -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` 只代表“本次工具未命中证据”，不能推导为“故障不存在”。
|
||||
@@ -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 默认值存在历史差异，排查时优先看实际迁移和数据库结构。
|
||||
@@ -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。后续可从结构化结论中拆分根因、证据和修复建议。
|
||||
@@ -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 不能把领域描述当作诊断结论依据；事实仍应来自工具返回的证据块或证据引用。
|
||||
@@ -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`。
|
||||
Reference in New Issue
Block a user