docs: reorganize MVP interview documentation

2026-07-05 15:29:28 +08:00
parent b22f2d22c8
commit 88e0a6c944
51 changed files with 4352 additions and 1318 deletions
@@ -1,162 +1,116 @@
-# 数据库设计文档
+# SuperBizAgent MVP 文档

-> 当前架构快照：[mvp/architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md)
+**更新日期**：2026-07-05

-## 📚 文档导航
+本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前架构入口已经整理到 `mvp/architecture/`，旧版架构材料已归档，避免继续把历史方案当成当前实现。

-### 核心表设计
- [diagnosis_record](tables/diagnosis_record.md) - 诊断记录表（核心）
- [case_library](tables/case_library.md) - 案例库表
- [api_document](tables/api_document.md) - 文档元数据表
+## 当前入口

-### 架构设计
- [Agent 架构设计](architecture/agent-architecture.md) - Agent 协作 + Skill + Harness
- [知识库检索架构](architecture/knowledge-retrieval-architecture.md) - L0+L1 混合检索架构 ⭐新增
- [知识库检索使用指南](architecture/knowledge-retrieval-usage.md) - 文档编写和使用说明 ⭐新增
- [会话管理](architecture/session-management.md) - Redis + MySQL 会话管理
- [实施规划](architecture/implementation-plan.md) - 分阶段实施计划
- [会话级去重与知识域地图](architecture/session-dedup-knowledge-map.md) - 文档级去重 + Planner 知识域地图注入解决 ISS-001 ⭐新增
- [证据评分与用户反馈](architecture/confidence-feedback.md) - evidence_score 规则引擎 + feedback API ⭐新增
- [行动记忆与检索归一化](architecture/action-memory-relevance.md) - Executor 行动记忆 + 归一化质量等级解决 ISS-002 ⭐新增
+| 目录/文档 | 用途 |
+|---|---|
+| [architecture/README.md](architecture/README.md) | 当前 MVP 架构入口 |
+| [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/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) | 检索与可观测性架构 |
+| [architecture/feedback-architecture.md](architecture/feedback-architecture.md) | 反馈与自评估架构 |
+| [architecture/session-trace-lifecycle.md](architecture/session-trace-lifecycle.md) | 会话与 Trace 生命周期 |
+| [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 重构计划和阶段拆解 |
+| [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 索引 |

---
+## 当前系统一句话

-## 一、设计原则
+SuperBizAgent MVP 是一个可追踪的故障诊断 Agent：Chat 和 AIOps 入口进入 Agent 编排，Executor 显式调用知识库、日志、指标等工具收集证据，诊断过程落到 `diagnosis_session`、`agent_step`、`tool_invocation`，最终通过 Trace API、Verifier 和评测脚本证明结果可解释、可回放、可对比。

-### 1.1 核心原则
- ✅ **简单优先**：满足诊断流程需要，避免过度设计
- ✅ **渐进增强**：先实现核心功能，再逐步扩展
- ✅ **数据分离**：诊断结果持久化（MySQL），会话上下文临时化（Redis）
- ✅ **适度冗余**：避免过度范式化，适当冗余提升查询性能
+## 文档结构

-### 1.2 系统定位
-**自动化诊断系统**
- 核心：一键诊断 → 返回完整报告
- 辅助：支持追问，但不是主要场景
- 特点：大部分用户单次诊断即结束，少数用户会追问细节
-
---
-
-## 二、表结构总览
-
-### 2.1 核心表关系
-
-```
-┌─────────────────────┐
-│  diagnosis_record   │  诊断记录（核心）
-│  - 每次诊断一条     │
-└──────────┬──────────┘
-           │ 1:1
-           ↓
-┌─────────────────────┐
-│  case_library       │  案例库（知识沉淀）
-│  - 诊断成功→案例    │
-└─────────────────────┘
-
-┌─────────────────────┐
-│  api_document       │  文档元数据（管理层）
-│  - 状态追踪/去重     │
-└──────────┬──────────┘
-           │ doc_id
-           ↓
-┌─────────────────────┐
-│  Milvus             │  文档内容（检索层）
-│  - 向量检索          │
-└─────────────────────┘
-
-┌─────────────────────┐
-│  Redis Session      │  会话管理（临时）
-│  - 30分钟过期        │
-│  - 支持追问          │
-└─────────────────────┘
+```text
+mvp/
+  architecture/
+    README.md
+    current-mvp-architecture.md
+    interview-one-pager.md
+    agent-orchestration.md
+    harness-quality-gates.md
+    rag-architecture.md
+    retrieval-observability.md
+    feedback-architecture.md
+    session-trace-lifecycle.md
+    knowledge-base-authoring.md
+    data-model.md
+    evolution-roadmap.md
+    archive/2026-07-05-legacy/
+  issues/
+    README.md
+    rag-refactor-plan.md
+    ISS-*.md
+    rag-*.md
+  demo/
+    README.md
+    ten-minute-interview-demo.md
+    requests/
+    scripts/
+    output/
+  eval/
+    README.md
+    schema.md
+    cases/
+    fixtures/
+    reports/
+  notes/
+  plan/
+  tables/
 ```

-### 2.2 表统计
+## 当前核心设计

-| 表名 | 类型 | 预估数据量 | 用途 |
-|------|------|-----------|------|
-| diagnosis_record | 核心 | 3.6万/年 | 诊断记录 |
-| case_library | 核心 | 500-1000 | 案例库 |
-| api_document | 核心 | 100-200 | 文档管理 |
+- `lookup_knowledge` 保持显式 Agent Tool，不隐藏到 Chat Advisor。
+- L0 降级为 domain/entity hint，不再默认承担最终召回决策。
+- `VectorSearchService` 是检索稳定门面。
+- Spring AI VectorStore 是当前读取主路径，Milvus SDK 保留为 fallback。
+- AIOps payload 会生成推荐知识库 query，保留业务语义。
+- Trace API 聚合 session、step、tool invocation 和 self evaluation。
+- RAG 行为通过 offline baseline 和 live acceptance 脚本做回归验证。

---
+## 关键运行链路

-## 三、技术栈
+```text
+Chat
+  -> ChatService
+  -> Planner / Executor / Verifier
+  -> evidence tools
+  -> diagnosis_session / agent_step / tool_invocation
+  -> DiagnosisTraceService

-### 3.1 数据存储
-```
-MySQL 8.0+
-├─ 元数据管理
-├─ 事务支持
-└─ JSON 字段支持
+AIOps
+  -> AiOpsService
+  -> PAYLOAD_TARGETED or AUTO_DISCOVERY
+  -> Planner / Executor
+  -> Prometheus / logs / lookup_knowledge
+  -> AiOpsRuleEvaluationService
+  -> DiagnosisTraceService

-Redis 6.0+
-├─ 会话存储
-├─ 缓存
-└─ TTL 自动过期
-
-Milvus 2.6+
-├─ 向量存储
-├─ 语义检索
-└─ 混合检索
+RAG
+  -> lookup_knowledge
+  -> L0 domain/entity hint
+  -> VectorSearchService
+  -> Spring AI VectorStore / Milvus SDK fallback
+  -> relevance normalization
+  -> tool_invocation
 ```

-### 3.2 开发框架
-```
-Spring Boot 3.2
-Spring AI Alibaba 1.1.0
-Milvus SDK Java 2.6.10
-DashScope SDK
-```
+## 旧文档说明

---
+旧版架构文档已移动到：

-## 四、快速开始
+- [architecture/archive/2026-07-05-legacy/](architecture/archive/2026-07-05-legacy/)

-### 4.1 创建数据库
-
-```sql
-- 1. 创建数据库
-CREATE DATABASE diagnosis_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-
-- 2. 执行建表脚本（按顺序）
-SOURCE tables/diagnosis_record.sql;
-SOURCE tables/case_library.sql;
-SOURCE tables/api_document.sql;
-```
-
-### 4.2 初始化 Milvus
-
-```java
-// 创建 Collection
-MilvusClientFactory.createCollection();
-```
-
-### 4.3 配置 Redis
-
-```yaml
-spring:
-  redis:
-    host: localhost
-    port: 6379
-    database: 0
-```
-
---
-
-## 五、版本历史
-
-| 版本 | 日期 | 变更内容 |
-|------|------|---------|
-| v1.0 | 2024-06-15 | 初版，定义核心表结构 |
-| v2.0 | 2024-06-15 | diagnosis_record 字段泛化，支持多种故障类型 |
-| v2.1 | 2024-06-22 | 文档拆分，增加 api_document 表 |
-
---
-
-## 六、维护说明
-
- 每个表的详细设计在 `tables/` 目录下
- 架构设计文档在 `architecture/` 目录下
- 修改表结构时，同步更新对应的 Markdown 文档
- 重大变更需记录在版本历史中
+归档文档只用于追溯设计历史。当前实现和后续规划以 `architecture/current-mvp-architecture.md` 与 `architecture/rag-architecture.md` 为准。