commit

docs/analysis/essence-report-rag-chunking.md

@@ -0,0 +1,342 @@
+# Essence Report: SuperBizAgent-java — RAG 切片流程
+
+> **Lens:** mechanical  
+> **Design analyzed:** 四层递进式文档分块算法——标题→章节→段落→句子边界的逐级切割策略  
+> **Files examined:** 3 (`DocumentChunkService.java`, `DocumentChunkConfig.java`, `DocumentChunk.java`)  
+> **Pattern:** Hierarchical Splitter with Sentence-Boundary-Aware Overlap  
+> **Status:** complete
+
+---
+
+## Phase 2: Deep Dive
+
+### 核心文件
+
+| # | 文件 | 行数 | 角色 |
+|---|------|------|------|
+| 1 | `service/DocumentChunkService.java` | 229 | 分块引擎本身 |
+| 2 | `config/DocumentChunkConfig.java` | 32 | 参数契约 `maxSize=800, overlap=100` |
+| 3 | `dto/DocumentChunk.java` | 59 | 分块数据载体 |
+
+### 完整调用链
+
+```
+VectorIndexService.indexSingleFile()
+  └─ chunkService.chunkDocument(content, filePath)        [L35]
+       │
+       ├─ splitByHeadings(content)                         [L44]
+       │    ├─ 正则: ^(#{1,6})\s+(.+)$                    [L65]
+       │    ├─ 迭代 matcher.find() 找到每个标题位置
+       │    ├─ 标题之间的内容 → Section(title, content, startIndex)
+       │    └─ → List<Section>
+       │
+       └─ for each Section:
+            └─ chunkSection(section, globalChunkIndex)     [L49]
+                 │
+                 ├─ if content.length() ≤ maxSize (800):
+                 │    └─ 直接作为一个分块                      [L110-119]
+                 │
+                 ├─ else (需要进一步切割):
+                 │    ├─ splitByParagraphs(content)         [L124]
+                 │    │    └─ content.split("\n\n+")        [L178]
+                 │    │
+                 │    ├─ for each paragraph:                [L130-167]
+                 │    │    ├─ 当前缓冲区 + 新段落 ≤ maxSize?  → 继续追加
+                 │    │    └─ 当前缓冲区 + 新段落 > maxSize?  → 触发切分:
+                 │    │         ├─ 保存当前分块
+                 │    │         ├─ getOverlapText(当前分块内容) [L147]
+                 │    │         │    ├─ 取末尾 overlap(100) 字符
+                 │    │         │    ├─ 在重叠文本中找最后一个句子终止符
+                 │    │         │    │   max(lastIndexOf('。'), lastIndexOf('？'), lastIndexOf('！'))
+                 │    │         │    ├─ if 句子边界 > overlapSize/2 (50字符):
+                 │    │         │    │   └─ 从句子边界后截取（保证新块以完整句开头）
+                 │    │         │    └─ else:
+                 │    │         │        └─ 直接用 overlap 末尾截取
+                 │    │         └─ 新缓冲区 = 重叠文本 + 当前段落
+                 │    │
+                 │    └─ 最后一个分块: 保存缓冲区剩余内容
+                 │
+                 └─ → List<DocumentChunk>
+```
+
+### 算法的四层递进结构
+
+```
+第1层：标题分割
+  输入："# CPU高负载\n内容...\n## 排查步骤\n内容..."
+  输出：Section("CPU高负载", "内容..."), Section("排查步骤", "内容...")
+  作用：保持文档结构，同一主题的内容不被拆散
+
+第2层：容量判断
+  if section.length() ≤ 800: 整个章节 = 一个分块
+  else: 进入段落级切割
+  作用：短章节保持完整，不破坏语义
+
+第3层：段落边界切割
+  输入：超长章节的全部段落
+  算法：逐个追加段落到缓冲区，超过 maxSize 时触发一次切分
+  作用：不在段落中间截断
+
+第4层：重叠窗口 + 句子边界对齐
+  输入：即将被切断的分块末尾
+  算法：取末尾100字符 → 找最近的。？！ → 从该位置之后截取作为下一块的"种子"
+  作用：相邻分块在语义上是"连续"的，检索时召回更完整
+```
+
+### 架构图
+
+```mermaid
+flowchart TD
+    DOC[/"原始文档"/] --> L1{"第1层: splitByHeadings()"}
+    
+    L1 --> S1["Section 1<br/>title: CPU高负载<br/>content: ..."]
+    L1 --> S2["Section 2<br/>title: 排查步骤<br/>content: ..."]
+    L1 --> S3["Section N"]
+    
+    S1 --> L2{"第2层: 容量判断"}
+    S2 --> L2
+    S3 --> L2
+    
+    L2 -->|"≤800字符"| CHUNK["作为1个分块<br/>继承 title"]
+    L2 -->|">800字符"| L3{"第3层: splitByParagraphs()<br/>在段落边界切分"}
+    
+    L3 --> BUF["逐段追加到缓冲区"]
+    BUF --> CHECK{"buf + para<br/>&gt; maxSize?"}
+    CHECK -->|否| APPEND["追加段落<br/>继续累积"]
+    CHECK -->|是| L4{"第4层: getOverlapText()<br/>句子边界校准"}
+    
+    APPEND --> CHECK
+    
+    L4 --> FIND["在重叠区末尾100字符<br/>找最近的 。？！"]
+    FIND --> EVAL{"句子边界位置<br/>&gt; overlapSize/2?"}
+    EVAL -->|是| ALIGN["从句号后截取<br/>保证新块以完整句开头"]
+    EVAL -->|否| RAW["退回原始截取<br/>直接用末尾100字符"]
+    
+    ALIGN --> SEED["种子 + 当前段落<br/>→ 新缓冲区"]
+    RAW --> SEED
+    SEED --> CHECK
+    
+    CHUNK --> RESULT[/"List&lt;DocumentChunk&gt;<br/>每个携带: content + title + startIndex + endIndex + chunkIndex"/]
+```
+
+### 关键代码证据
+
+#### 第1层——标题正则
+
+```java
+// DocumentChunkService.java:65
+Pattern headingPattern = Pattern.compile("^(#{1,6})\\s+(.+)$", Pattern.MULTILINE);
+```
+
+支持 H1-H6，`MULTILINE` 模式让 `^` 匹配行首而非仅字符串首。
+
+#### 第2层——容量判断（短路）
+
+```java
+// DocumentChunkService.java:110-119
+if (content.length() <= chunkConfig.getMaxSize()) {
+    DocumentChunk chunk = new DocumentChunk(content, startIndex, endIndex, chunkIndex);
+    chunk.setTitle(title);
+    chunks.add(chunk);
+    return chunks;  // 直接返回，不进入段落切割
+}
+```
+
+#### 第3层——段落级触发切分
+
+```java
+// DocumentChunkService.java:132-148
+if (currentChunk.length() > 0 &&
+    currentChunk.length() + paragraph.length() > chunkConfig.getMaxSize()) {
+    // 触发切分：保存当前块
+    String overlap = getOverlapText(chunkContent);          // 提取重叠文本
+    currentChunk = new StringBuilder(overlap);               // 新块以重叠文本开头
+    currentStartIndex = currentStartIndex + chunkContent.length() - overlap.length();
+}
+currentChunk.append(paragraph).append("\n\n");  // 继续追加
+```
+
+#### 第4层——句子边界检测（核心巧思）
+
+```java
+// DocumentChunkService.java:193-213
+private String getOverlapText(String text) {
+    int overlapSize = Math.min(chunkConfig.getOverlap(), text.length());
+    String overlap = text.substring(text.length() - overlapSize);
+
+    // 在重叠文本中找最近的句子终止符
+    int lastSentenceEnd = Math.max(
+        overlap.lastIndexOf('。'),
+        Math.max(overlap.lastIndexOf('？'), overlap.lastIndexOf('！'))
+    );
+
+    // 质量阈值：只有句子边界在重叠区后半段才采用
+    if (lastSentenceEnd > overlapSize / 2) {
+        return overlap.substring(lastSentenceEnd + 1).trim();
+    }
+    return overlap.trim();  // 退回普通重叠
+}
+```
+
+`overlapSize / 2` 条件是一个**质量阈值**。如果最近的句子边界在重叠区的前半段（即离截断点太远），说明分块点本身就接近句子边界，不需要特殊处理。只有句子边界明显位于重叠区后半段时才调整——避免把半个句子作为新块的"种子"。
+
+### 数据流契约
+
+```
+chunkDocument(content, filePath)
+  │
+  │ IN:  String content          — 原始文档全文
+  │      String filePath         — 仅用于日志
+  │
+  │ INNER CLASS: Section
+  │      String title            — 所在标题（可为 null）
+  │      String content          — 标题下的所有文本
+  │      int startIndex          — 在原文档中的字符偏移
+  │
+  │ OUT: List<DocumentChunk>
+  │      String content          — 分块文本
+  │      int startIndex          — 在原文档中的起始位置
+  │      int endIndex            — 在原文档中的结束位置
+  │      int chunkIndex          — 分块序号 (0, 1, 2, ...)
+  │      String title            — 所属章节标题（继承自 Section）
+  │
+  └─ 消费者: VectorIndexService.indexSingleFile():142
+              → 遍历 chunks → embeddingService.generateEmbedding(chunk.content)
+```
+
+---
+
+## Phase 3: Extract Pattern
+
+### 模式名：Hierarchical Splitter with Sentence-Boundary-Aware Overlap
+
+**一句话：** 从粗到细逐级切割——先按文档结构（标题）分章，再按语义边界（段落）分块，最后在切分点用句子终止符校准重叠窗口。
+
+### 问题
+
+固定长度切割的典型失败场景：
+
+```
+切在句子中间：  "CPU使用率达到 95%，建议" | "立即重启相关服务"
+                ↑ 检索"CPU问题"时召回这块——后半句完全脱离上下文，LLM 误判
+
+切在段落中间："## 排查步骤\n1. 查看监控\n2. 检" | "查日志\n3. 重启服务"
+                ↑ 步骤 2 被切断，Agent 拿着残缺的排查步骤执行操作
+```
+
+### 替代方案对比
+
+| 方案 | 切分依据 | 优势 | 劣势 |
+|------|----------|------|------|
+| **固定字符切割**（最简陋） | maxSize，不关心内容 | 实现简单 | 句子截断、丢失语义 |
+| **递归字符切割**（LangChain RecursiveTextSplitter） | `\n\n` → `\n` → ` ` → `` | 通用性好 | 不理解 Markdown 结构 |
+| **语义切割**（用 LLM 判断切点） | LLM 标注切分位置 | 理论上最优 | 慢、贵、不可预测 |
+| **本项目：层级式+句子校准** | 标题→段落→句子终止符 | 快速 + 保留文档结构 | 仅支持 Markdown，非标题文档退化为段落切割 |
+
+### 为什么标题分割放在第一步？
+
+```java
+// DocumentChunkService.java:43-44
+// 1. 首先尝试按标题分割（Markdown格式）
+List<Section> sections = splitByHeadings(content);
+```
+
+看本项目的知识库文档就懂了：
+
+```markdown
+# CPU高负载问题排查           ← 一个独立主题
+## 问题现象
+...
+## 排查步骤                    ← 这些步骤必须完整才能被 Agent 执行
+1. 使用 top 命令确认 CPU 使用率最高的进程
+2. 检查对应服务的日志
+3. ...
+## 解决方案
+...
+
+# 内存高负载问题排查           ← 另一个独立主题
+...
+```
+
+如果把「CPU 排查步骤」和「内存排查步骤」混在一个分块里，Agent 查询"CPU 高"时会召回包含内存排查步骤的分块——噪声干扰判断。
+
+标题优先分割 = **用文档作者自己标注的结构来界定语义边界**，比任何算法都准确。
+
+---
+
+## Phase 4: Migrate
+
+### 可迁移性
+
+这个切分策略**直接可用**于任何需要为 Markdown 文档建 RAG 的项目。三个参数全部可配置：
+
+```yaml
+# application.yml — 按文档类型调整
+document:
+  chunk:
+    max-size: 800    # 短文档(API文档)可设500，长文档(周报)可设1200
+    overlap: 100      # 800的12.5%，保持比例即可
+```
+
+### Steal-it 示例（17 行）
+
+```java
+/**
+ * 四层递进分块：标题 → 章节 → 段落 → 句子校准
+ * 依赖：maxSize / overlap 两个参数
+ */
+public List<Chunk> chunk(String doc) {
+    List<Chunk> result = new ArrayList<>();
+    int globalIdx = 0;
+
+    // 第1层：按标题分章
+    for (Section sec : splitByHeadings(doc)) {
+        if (sec.content.length() <= maxSize) {
+            // 第2层：短章节直接作为一个分块
+            result.add(new Chunk(sec.content, sec.title, globalIdx++));
+        } else {
+            // 第3层：超长章节在段落边界切分
+            String overlap = "";
+            for (String para : sec.content.split("\n\n+")) {
+                String candidate = overlap + para;
+                if (candidate.length() > maxSize && !overlap.isEmpty()) {
+                    result.add(new Chunk(overlap, sec.title, globalIdx++));
+                    overlap = tailOverlap(overlap);  // 第4层：句子校准
+                }
+                overlap = (overlap.isEmpty() ? "" : overlap + "\n\n") + para;
+            }
+            if (!overlap.isEmpty()) result.add(new Chunk(overlap, sec.title, globalIdx++));
+        }
+    }
+    return result;
+}
+```
+
+### 落地陷阱
+
+| 陷阱 | 原因 | 规避 |
+|------|------|------|
+| **非 Markdown 文档退化为单块** | `splitByHeadings()` 找不到标题时整个文档作为一个 Section | L93-96：返回一个 Section，后续段落切割仍生效 |
+| **代码块内的 `#` 被误识别为标题** | 正则不区分代码块和正文 | 未规避——可加反引号检测 `` ``` `` |
+| **overlap=0 时句子校准无效** | `getOverlapText` 第一行 `Math.min(0, length)=0` 返回空串 | L194：直接返回空字符串，跳过校准 |
+| **单段落超过 maxSize 不做切割** | `splitByParagraphs` 后每个段落作为一个单位 | L132 条件要求 `currentChunk.length() > 0`，首段落即使超长也会被单独保存为一块 |
+
+---
+
+### Self-review
+
+- [x] 设计真实——每层切割均有代码行号证据
+- [x] 深度足够——追溯到正则、条件分支、句子校准的数学逻辑
+- [x] 迁移示例 17 行——提取了四层递进的核心骨架
+- [x] 陷阱具体到代码行——非 Markdown 退化为单块(L93)、单段落超长不切割(L132)
+
+```
+Essence Report: SuperBizAgent-java — RAG 切片流程
+Lens: mechanical
+Design analyzed: 四层递进式文档分块算法
+Files examined: 3
+Pattern: Hierarchical Splitter with Sentence-Boundary-Aware Overlap
+Migration: 17-line steal-it skeleton
+HTML generated: no
+Status: complete
+```

docs/analysis/essence-report-rag.md

@@ -0,0 +1,314 @@
+# Essence Report: SuperBizAgent-java — RAG 实现
+
+> **Lens:** mechanical（机械论——结构、接口、数据流）  
+> **Design analyzed:** RAG 管道——从文档上传到 Agent 辅助检索的完整写入/读取双路径  
+> **Files examined:** 12  
+> **Pattern:** Pipeline-as-Services + Agent-Mediated Retrieval  
+> **Status:** complete
+
+---
+
+## Phase 1: 定位 — 设计目标确认
+
+来自 `/explore` 报告的「设计二：完整的 RAG 管道（5 级流水线）」。用户指定深入 RAG 实现部分。
+
+涉及 12 个核心文件，跨越 controller → service → client → constant 四层。
+
+---
+
+## Phase 2: Deep Dive — 逐文件追踪
+
+### 核心文件清单
+
+| # | 文件 | 角色 | 暴露接口 |
+|---|------|------|----------|
+| 1 | `constant/MilvusConstants.java` | Schema 契约常量 | `VECTOR_DIM=1024`, `COLLECTION_NAME="biz"` |
+| 2 | `client/MilvusClientFactory.java` | 数据库初始化 | `createClient()` → 自动建表+建索引 |
+| 3 | `config/DocumentChunkConfig.java` | 分块参数 | `maxSize=800`, `overlap=100` |
+| 4 | `dto/DocumentChunk.java` | 分块实体 | `content`, `startIndex/endIndex`, `chunkIndex`, `title` |
+| 5 | `service/DocumentChunkService.java` | 智能分块器 | `chunkDocument(content, filePath)` → `List<DocumentChunk>` |
+| 6 | `service/VectorEmbeddingService.java` | 向量化网关 | `generateEmbedding(text)` → `List<Float>` (1024-dim) |
+| 7 | `service/VectorIndexService.java` | 写入管道编排 | `indexSingleFile(path)` → 读→删旧→分块→向量化→写 |
+| 8 | `service/VectorSearchService.java` | 语义检索 | `searchSimilarDocuments(query, topK)` → `List<SearchResult>` |
+| 9 | `service/RagService.java` | 全栈 RAG 问答 | `queryStream(question, history, callback)` → SSE流式 |
+| 10 | `agent/tool/InternalDocsTools.java` | Agent 工具桥 | `queryInternalDocs(query)` → JSON（仅检索，不生文） |
+| 11 | `controller/FileUploadController.java` | 写入入口 | `POST /api/upload` → 文件存储 + 自动索引 |
+| 12 | `controller/ChatController.java` | 读取入口 | `POST /api/chat(_stream)` → ReactAgent + 工具调用 |
+
+### 完整的调用链（双路径）
+
+#### 写入路径（索引管道）
+
+```
+POST /api/upload
+  └─ FileUploadController.upload()                          [L34]
+       ├─ Files.copy() → 保存文件到 uploadPath
+       └─ VectorIndexService.indexSingleFile()              [L124]
+            ├─ Files.readString()                            [L135]
+            ├─ deleteExistingData()                          [L173]
+            │    └─ milvusClient.delete()                    [L198]
+            │         expr: metadata["_source"] == "/path/to/file"
+            ├─ chunkService.chunkDocument()                  [L142]
+            │    ├─ splitByHeadings()                        [L61]
+            │    │    └─ 正则: ^(#{1,6})\s+(.+)$
+            │    ├─ chunkSection() × N                       [L104]
+            │    │    ├─ splitByParagraphs()                 [L174]
+            │    │    └─ getOverlapText()                    [L193]
+            │    └─ → List<DocumentChunk>
+            └─ for each chunk:                               [L146]
+                 ├─ embeddingService.generateEmbedding()     [L76]
+                 │    └─ DashScope TextEmbedding API → List<Float>[1024]
+                 └─ insertToMilvus()                         [L255]
+                      └─ UUID(source+chunkIndex) + vector + content + metadata(JSON)
+```
+
+#### 读取路径（Agent 中介检索）
+
+```
+POST /api/chat_stream
+  └─ ChatController.chatStream()                            [L143]
+       └─ chatService.createReactAgent()                     [L183]
+            └─ tools: [DateTimeTools, InternalDocsTools, QueryMetricsTools, QueryLogsTools]
+       └─ agent.stream(question)                             [L189]
+            └─ Agent 自主决策 → 调用 queryInternalDocs
+                 └─ InternalDocsTools.queryInternalDocs()    [L53]
+                      └─ VectorSearchService.searchSimilarDocuments()  [L42]
+                           ├─ embeddingService.generateQueryVector()    [L47]
+                           ├─ milvusClient.search()                    [L51]
+                           │    └─ L2距离, IVF_FLAT, nprobe=10
+                           └─ → List<SearchResult>{id, content, score, metadata}
+                      └─ return JSON to Agent
+                           └─ Agent 融合检索结果 + LLM推理 → 最终回答
+```
+
+### 架构图
+
+```mermaid
+graph TB
+    subgraph 写入路径
+        UPLOAD[POST /api/upload]
+        FC[FileUploadController]
+        VIS[VectorIndexService]
+        DCS[DocumentChunkService]
+        VES[VectorEmbeddingService]
+        MV_W[(Milvus)]
+    end
+
+    subgraph 读取路径
+        CHAT[POST /api/chat_stream]
+        CC[ChatController]
+        AGENT[ReactAgent]
+        IDT[InternalDocsTools<br/>@Tool注解]
+        VSS[VectorSearchService]
+        MV_R[(Milvus)]
+        LLM[DashScope LLM]
+    end
+
+    UPLOAD --> FC
+    FC --> VIS
+    VIS --> DCS --> VIS
+    VIS --> VES --> VIS
+    VIS --> MV_W
+
+    CHAT --> CC
+    CC --> AGENT
+    AGENT -->|自主决策调用| IDT
+    IDT --> VSS
+    VSS --> VES --> VSS
+    VSS --> MV_R
+    IDT -->|JSON结果| AGENT
+    AGENT --> LLM
+    LLM -->|SSE流式| CC
+```
+
+### 关键设计决策（代码证据）
+
+#### 1. 幂等上传——元数据驱动的去重策略
+
+```java
+// VectorIndexService.java:138-139
+// 删除该文件的旧数据（如果存在）
+deleteExistingData(path.toString());
+```
+
+`deleteExistingData()` (L173-215) 使用 `metadata["_source"] == filePath` 作为删除表达式。每次上传同一文件时，先清空旧向量再写入新数据，保证数据一致性。
+
+#### 2. 路径标准化——跨平台一致性
+
+```java
+// VectorIndexService.java:176-178
+Path path = Paths.get(filePath).normalize();
+String normalizedPath = path.toString().replace(File.separator, "/");
+```
+
+Windows `\` 和 Unix `/` 统一为正斜杠，避免 Milvus 表达式解析错误。在 `deleteExistingData()` 和 `buildMetadata()` 中均有应用。
+
+#### 3. 重叠窗口 + 句子边界感知
+
+```java
+// DocumentChunkService.java:132-148
+if (currentChunk.length() > 0 && 
+    currentChunk.length() + paragraph.length() > chunkConfig.getMaxSize()) {
+    // 保存当前分片
+    String overlap = getOverlapText(chunkContent);  // 提取重叠文本
+    currentChunk = new StringBuilder(overlap);       // 新分片以重叠文本开头
+```
+
+`getOverlapText()` (L193-213) 更进一步：在重叠文本中寻找句子边界（`。？！`），避免在句子中间截断。当句子边界超过 `overlapSize/2` 时才使用，否则退回原始重叠策略。
+
+#### 4. 检索与生成分离
+
+`InternalDocsTools.queryInternalDocs()` 只做检索，不做生成。它将搜索结果序列化为 JSON 返回给 Agent，由 Agent 的 LLM 自行判断如何使用这些信息。
+
+```java
+// InternalDocsTools.java:68
+String resultJson = objectMapper.writeValueAsString(searchResults);
+return resultJson;
+```
+
+对比 `RagService.queryStream()` 则完整执行「检索→构建上下文→LLM 生成」三步，是一个独立的全栈 RAG 备用路径。
+
+#### 5. Milvus Schema 设计
+
+```java
+// MilvusClientFactory.java:109-142
+// 四个字段:
+//   id        VarChar(256)    主键 — UUID(source + chunkIndex)
+//   vector    FloatVector(1024) — text-embedding-v4 输出
+//   content   VarChar(8192)   — 分块后的文本内容
+//   metadata  JSON            — {_source, _extension, _file_name, chunkIndex, totalChunks, title}
+// 索引: IVF_FLAT, L2距离, nlist=128
+```
+
+---
+
+## Phase 3: Extract Pattern
+
+### 设计模式：Pipeline-as-Services + Agent-Mediated Retrieval
+
+**问题：** 如何将知识库文档转化为 AI Agent 可检索、可利用的语义记忆？
+
+**传统方案的问题：**
+- 关键词检索：无法理解语义相似的查询
+- 硬编码 FAQ：无法应对未见过的问题
+- 直接向量检索 + 固定提示词：所有问题都触发检索，浪费资源
+
+**本项目的方案：两阶段架构**
+
+```
+┌──────────────────────────────────────────────────┐
+│  STAGE 1: 写入管道 (离线/上传时触发)                │
+│                                                    │
+│  文档 ──→ 智能分块 ──→ 向量化 ──→ Milvus存储      │
+│         (标题+段落     (text-embedding  (IVF_FLAT   │
+│          边界感知)      -v4, 1024-dim)   L2索引)     │
+│                                                    │
+│  接口契约:                                         │
+│    IN:  File → OUT: N × (vector + content + meta)  │
+└──────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────┐
+│  STAGE 2: 读取管道 (Agent 决策时触发)               │
+│                                                    │
+│  用户问题 ──→ Agent 思考 ──→ 决定查知识库          │
+│                              │                     │
+│                              ▼                     │
+│              向量检索 (L2距离) ──→ Top-K 文档片段   │
+│                              │                     │
+│                              ▼                     │
+│              Agent 融合检索结果 + LLM推理 → 回答    │
+│                                                    │
+│  接口契约:                                         │
+│    IN:  query(自然语言) → OUT: JSON(检索结果)       │
+│    Agent 自主决定: 是否调用 / 如何使用结果           │
+└──────────────────────────────────────────────────┘
+```
+
+### 接口契约（隐式——通过 Spring DI 实现）
+
+| 契约 | 生产者 | 消费者 | 数据形状 |
+|------|--------|--------|----------|
+| `List<DocumentChunk>` | DocumentChunkService | VectorIndexService | `{content, startIndex, endIndex, chunkIndex, title}` |
+| `List<Float>[1024]` | VectorEmbeddingService | VectorIndexService, VectorSearchService | DashScope text-embedding-v4 输出 |
+| `List<SearchResult>` | VectorSearchService | InternalDocsTools, RagService | `{id, content, score, metadata}` |
+| `StreamCallback` | RagService | (外部调用者) | `{onSearchResults, onContentChunk, onComplete, onError}` |
+
+### 替代方案对比
+
+| 方案 | 本项目 | LangChain4j | 纯 DashScope API |
+|------|--------|--------------|-------------------|
+| 分块策略 | 标题感知 + 段落边界 + 句子重叠 | 多种内置 Splitter | 无，需自建 |
+| 向量库 | Milvus (IVF_FLAT) | 多后端支持 | 无 |
+| Agent 集成 | Spring AI @Tool 注解，Agent 自主决策 | AiServices + @Tool | 无 Agent 框架 |
+| 去重 | metadata["_source"] 匹配删除 | 需自定义 | 不适用 |
+
+### 为什么选择这种设计？
+
+1. **「检索」和「生成」分离**：`InternalDocsTools` 只返回检索结果，生成由 Agent 的 LLM 完成。Agent 可以选择**不使用**检索结果（如果检索质量不高），或者**交叉验证**多次检索的结果
+2. **工具化 RAG**：将 RAG 暴露为 Agent 工具而非独立 API，让 Agent 在合适的时机触发检索——而非对所有问题都做 RAG
+3. **5 个独立 Service**：每个阶段可单独替换。想换分块策略？只改 `DocumentChunkService`。想换向量库？只改 `VectorSearchService` + `VectorIndexService`
+
+---
+
+## Phase 4: Migrate — 可迁移的设计
+
+### 可迁移性评估
+
+这个 RAG 设计**高度可迁移**到任何需要「知识库 + AI Agent」的 Java 项目。核心依赖是 Spring AI 生态 + 一个向量数据库。
+
+### Steal-it 示例（12 行）
+
+```java
+// 核心思想：Pipeline-as-Services + Agent Tool Bridge
+// 以下骨架可直接用于任何 Spring Boot 项目
+
+// 1. 分块器：语义感知分割
+public List<Chunk> chunk(String doc) {
+    return splitByHeadings(doc).stream()
+        .flatMap(s -> splitToFit(s, MAX_SIZE, OVERLAP))
+        .toList();
+}
+
+// 2. Agent 工具桥：检索但不生文
+@Component
+class KnowledgeBaseTool {
+    @Tool(description = "搜索内部知识库获取相关信息")
+    public String search(@ToolParam(description="查询内容") String query) {
+        List<Float> qv = embedder.embed(query);         // 向量化
+        var results = vectorDB.search(qv, TOP_K);        // 语义检索
+        return toJson(results);                          // 返回给Agent
+    }
+}
+```
+
+### 落地陷阱
+
+| 陷阱 | 说明 | 本项目如何规避 |
+|------|------|----------------|
+| **路径分隔符不一致** | Windows `\` vs Unix `/` 导致 Milvus 表达式解析失败 | `VectorIndexService.java:177` 强制 `replace(File.separator, "/")` |
+| **重复上传污染数据** | 同一文件多次上传产生重复向量 | `VectorIndexService.java:138-139` delete-before-insert |
+| **分块边界截断语义** | 固定长度切割可能切断句子 | `DocumentChunkService.java:203-206` 在重叠区找句子边界 |
+| **Agent 未触发工具** | Agent 不知道何时该查知识库 | `InternalDocsTools.java:49-52` @Tool description 用英文详细描述触发场景 |
+| **向量维度不匹配** | embedding 模型输出维度与 Milvus schema 不一致 | `MilvusConstants.java:18` 集中管理 `VECTOR_DIM=1024` |
+| **API Key 未初始化** | 静态 Constants 被其他线程覆盖 | `VectorEmbeddingService.java:86-89` 每次调用前检查并修复 |
+
+### Self-review
+
+- [x] 设计真实存在 — 每个声明均有文件+行号证据
+- [x] 分析深度足够 — 完整追踪了写入/读取两条全路径
+- [x] 迁移示例≤20行 — 仅提取 Pipeline + Tool Bridge 骨架
+- [x] 陷阱具体 — 每个都有代码规避证据
+- [x] 可解释为什么优于替代方案 — Agent 自主决策 vs 强制 RAG
+
+---
+
+```
+Essence Report: SuperBizAgent-java
+Lens: mechanical
+Design analyzed: RAG 管道 — Pipeline-as-Services + Agent-Mediated Retrieval
+Files examined: 12
+Pattern: Pipeline-as-Services + Agent Tool Bridge
+Migration: 12-line steal-it skeleton
+HTML generated: no
+Status: complete
+```

docs/analysis/explore-report.md

@@ -0,0 +1,352 @@
+# Explore Report: SuperBizAgent-java
+
+> 生成时间: 2026-04-30  
+> Project type: **code repository**  
+> Phases completed: 4/4  
+> Diagram included: yes  
+> Core designs: 3  
+> Status: complete
+
+---
+
+## Phase 1: Positioning & Structure
+
+### 这是什么项目
+
+SuperBizAgent-java 是一个基于 **Spring AI + Alibaba DashScope (Qwen)** 的智能运维 AI Agent 平台。它将大语言模型、向量检索增强生成（RAG）和多智能体协作（Planner-Executor-Replanner）整合为一体，面向企业 IT 运维场景提供：
+
+- **智能文档问答**：上传运维知识库文档（Markdown/TXT），通过 RAG 管道实现向量化检索 + LLM 流式生成回答
+- **告警分析自动化**：多 Agent 协作分析 Prometheus 告警，结合日志查询（腾讯云 CLS）和内部知识库，生成结构化的告警分析报告
+- **MCP 协议集成**：通过 Spring AI MCP Client 连接外部工具服务，扩展 Agent 能力边界
+
+### 为什么值得研究
+
+| 维度 | 价值 |
+|------|------|
+| **AI 框架落地** | Spring AI Alibaba 生态的完整实践——ReactAgent、SupervisorAgent、Tool 注册、流式对话 |
+| **多 Agent 协作** | 非玩具级的 Planner-Executor-Replanner 监督循环，实际解决告警分析这种开放性问题 |
+| **RAG 工程化** | 完整的文档分块→向量化→Milvus 存储→语义检索→流式生成的端到端管道 |
+| **MCP 协议** | 业界较早将 MCP (Model Context Protocol) 用于生产场景的 Java 案例 |
+
+### 适合谁
+
+- Spring Boot / Java 开发者学习 AI Agent 框架的落地模式
+- AIOps / SRE 工程师了解智能运维 Agent 的架构设计
+- 对 Spring AI Alibaba 生态感兴趣的技术决策者
+
+### 项目规模
+
+| 指标 | 数值 |
+|------|------|
+| Java 源文件 | ~25 个 |
+| 代码行数 | ~2500 行 |
+| API 端点 | 7 个 |
+| Agent 工具 | 4 个 |
+| 知识库文档 | 5 篇 |
+
+### 技术栈
+
+```
+应用层     Spring Boot 3.2 / Java 17
+AI 层     Spring AI Alibaba 1.1.0 / Qwen3-Max / text-embedding-v4
+存储层    Milvus 2.5 (向量库) / MinIO (对象存储)
+集成层    MCP Client (WebFlux SSE) / Prometheus
+部署      Docker Compose (Milvus + etcd + MinIO + Attu)
+```
+
+### 与替代方案的对比
+
+| 方案 | 优势 | 劣势 |
+|------|------|------|
+| 本项目 (Spring AI Alibaba) | 完整生态、国产模型、Java 原生 | 社区相对年轻 |
+| LangChain4j | 社区活跃、模型支持广 | 多 Agent 模式需自行构建 |
+| Python LangChain | 生态最丰富 | 非 Java 技术栈 |
+| 纯 DashScope API | 简单直接 | 缺乏 Agent 编排、工具调用框架 |
+
+---
+
+## Phase 2: Flow
+
+### 架构总览
+
+```mermaid
+graph TB
+    subgraph 前端
+        WEB[Web UI<br/>index.html + app.js]
+    end
+
+    subgraph 控制层
+        CC[ChatController<br/>/api/chat /api/chat_stream]
+        AO[AIOpsController<br/>/api/ai_ops]
+        UP[FileUploadController<br/>/api/upload]
+        HC[MilvusCheckController<br/>/milvus/health]
+    end
+
+    subgraph 服务层
+        CS[ChatService<br/>ReactAgent 编排]
+        AIS[AiOpsService<br/>多Agent 协作]
+        RS[RagService<br/>RAG 流式问答]
+        VIS[VectorIndexService<br/>文件索引管道]
+        VSS[VectorSearchService<br/>向量相似搜索]
+        VES[VectorEmbeddingService<br/>文本向量化]
+        DCS[DocumentChunkService<br/>智能文档分块]
+    end
+
+    subgraph Agent工具
+        DT[DateTimeTools]
+        IDT[InternalDocsTools]
+        QMT[QueryMetricsTools]
+        QLT[QueryLogsTools]
+    end
+
+    subgraph 外部服务
+        DS[DashScope API<br/>Qwen3-Max / Embedding]
+        MV[Milvus<br/>向量数据库]
+        PM[Prometheus<br/>监控告警]
+        CLS[腾讯云CLS<br/>MCP SSE]
+    end
+
+    WEB --> CC
+    WEB --> AO
+    WEB --> UP
+    WEB --> HC
+
+    CC --> CS
+    CC --> RS
+    AO --> AIS
+    UP --> VIS
+
+    CS --> DT & IDT & QMT & QLT
+    AIS --> DT & IDT & QMT & QLT
+
+    CS --> DS
+    RS --> DS
+    RS --> VSS
+    VIS --> DCS --> VES --> MV
+    VSS --> MV
+    QMT --> PM
+    QLT --> CLS
+
+    VES --> DS
+```
+
+### 主要运行时流程
+
+#### 流程 A：RAG 智能问答（文档→检索→生成）
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Ctrl as FileUploadController
+    participant VIS as VectorIndexService
+    participant DCS as DocumentChunkService
+    participant VES as VectorEmbeddingService
+    participant MV as Milvus
+    participant RS as RagService
+    participant DS as DashScope
+
+    Note over User,DS: === 索引阶段 ===
+    User->>Ctrl: POST /api/upload (file.md)
+    Ctrl->>VIS: indexSingleFile(file)
+    VIS->>VIS: 删除旧向量(按source路径匹配)
+    VIS->>DCS: chunkDocument(content)
+    DCS-->>VIS: List<DocumentChunk>
+    loop 每个分块
+        VIS->>VES: generateEmbedding(chunk)
+        VES->>DS: text-embedding-v4 API
+        DS-->>VES: float[1024]
+        VES-->>VIS: 向量
+    end
+    VIS->>MV: insert(向量 + 原文 + metadata)
+    MV-->>VIS: OK
+
+    Note over User,DS: === 问答阶段 ===
+    User->>Ctrl: POST /api/chat (question)
+    Ctrl->>RS: generateAnswerStream(question)
+    RS->>VES: 向量化问题
+    VES->>DS: text-embedding-v4
+    DS-->>RS: query_vector[1024]
+    RS->>MV: search(query_vector, topK=3)
+    MV-->>RS: 3条最相似文档片段
+    RS->>DS: Generation API (提示词 + 上下文 + 问题)
+    DS-->>User: SSE 流式生成回答
+```
+
+#### 流程 B：AIOps 多 Agent 告警分析
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Ctrl as ChatController
+    participant AIS as AiOpsService
+    participant Sup as SupervisorAgent
+    participant P as PlannerAgent
+    participant E as ExecutorAgent
+    participant Tools as Agent Tools
+    participant DS as DashScope
+
+    User->>Ctrl: POST /api/ai_ops (告警信息)
+    Ctrl->>AIS: executeAiOpsAnalysis(request)
+
+    Note over AIS, DS: 启动监督循环
+    AIS->>Sup: 启动，传入 Planner + Executor
+
+    loop Planner-Executor-Replanner
+        Sup->>P: 分析当前状态，决定下一步
+        alt 需要制定/修订计划
+            P-->>User: SSE: 📋 分析计划...
+        else 需要执行步骤
+            P-->>Sup: EXECUTE
+            Sup->>E: 执行计划第一步
+            E->>Tools: 调用工具收集证据
+            Tools-->>E: 日志/告警/文档信息
+            E-->>User: SSE: 🔍 执行结果...
+            E-->>Sup: 反馈 + 证据
+            Note over Sup: 将执行结果反馈给Planner
+        else 分析完成
+            P-->>Sup: FINISH
+        end
+    end
+
+    Sup-->>User: SSE: ✅ Markdown 告警分析报告
+```
+
+---
+
+## Phase 3: Start Path
+
+### 最小启动步骤
+
+```bash
+# 1. 启动基础设施（Milvus + etcd + MinIO）
+cd D:\zhu\project\SuperBizAgent-java
+docker compose -f vector-database.yml up -d
+
+# 2. 设置 API Key 环境变量
+export DASHSCOPE_API_KEY="your-dashscope-api-key"
+
+# 3. 启动应用
+mvn spring-boot:run
+# 应用启动在 http://localhost:9900
+
+# 4. 打开 Web 测试页面
+# http://localhost:9900/index.html
+```
+
+### 学习起点
+
+1. **第一入口**：`src/main/java/org/example/Main.java` — Spring Boot 启动类，了解组件扫描范围
+2. **核心对话**：`src/main/java/org/example/controller/ChatController.java` — 所有 API 端点定义，理解请求路由
+3. **Agent 编排**：`src/main/java/org/example/service/ChatService.java` — ReactAgent 如何注册工具、处理对话
+4. **多 Agent 协作**：`src/main/java/org/example/service/AiOpsService.java` — Planner-Executor-Replanner 模式完整实现
+5. **RAG 管道**：按 `VectorIndexService → DocumentChunkService → VectorEmbeddingService → RagService` 顺序阅读
+
+### 建议的第一个修改
+
+在 `QueryMetricsTools.java` 的 `queryPrometheusAlerts()` 方法中添加一个 Mock 数据，观察 Agent 如何将新的工具输出整合到对话中。修改后重新提问相关问题即可看到效果。
+
+---
+
+## Phase 4: Core Designs
+
+### 设计一：Planner-Executor-Replanner 监督循环
+
+**位置**：`src/main/java/org/example/service/AiOpsService.java`
+
+**是什么**：一个三层多 Agent 协作模式，用监督者控制循环来解决开放性的告警分析问题。
+
+```
+SupervisorAgent (监督者)
+  ├── PlannerAgent (规划者)
+  │     └── 决策三个状态: PLAN → 制定/修订计划
+  │                      EXECUTE → 交给执行者
+  │                      FINISH → 输出最终报告
+  └── ExecutorAgent (执行者)
+        └── 执行计划中的第一步
+        └── 调用工具获取真实数据
+        └── 返回反馈给 Planner 重新规划
+```
+
+**为什么重要**：
+- 不是简单的单次 Agent 调用，而是通过**循环反馈**逐步逼近准确分析
+- Planner 根据 Executor 返回的证据**动态调整计划**（即 Replan 机制）
+- 通过 SSE 将每一步的中间结果实时推送给前端，用户体验好
+- 工具调用是**实际的**：Prometheus 查询、日志搜索、知识库检索，不是 mock 玩具
+
+**关键实现细节**：
+```java
+// SupervisorAgent 创建并传入子 Agent
+SupervisorAgent supervisor = SupervisorAgent.builder()
+    .supervisorAgent(supervisor)
+    .subAgents(plannerAgent, executorAgent)
+    .build();
+```
+
+### 设计二：完整的 RAG 管道（5 级流水线）
+
+**位置**：`VectorIndexService` → `DocumentChunkService` → `VectorEmbeddingService` → `VectorSearchService` → `RagService`
+
+**是什么**：从原始文档到流式问答输出的完整 RAG 管道，涉及 5 个松耦合的服务组件。
+
+| 阶段 | 组件 | 关键技术点 |
+|------|------|------------|
+| 1. 智能分块 | DocumentChunkService | 按 Markdown 标题层级 + 段落边界分割，800 字符/块，100 字符重叠 |
+| 2. 向量化 | VectorEmbeddingService | DashScope text-embedding-v4，1024 维，支持批量 |
+| 3. 向量存储 | MilvusClientFactory | IVF_FLAT 索引，L2 距离，自动去重（按 source 路径） |
+| 4. 语义检索 | VectorSearchService | Top-K 配置化（default 3），返回原文 + 相似度分数 |
+| 5. 流式生成 | RagService | DashScope Generation API，SSE 流式输出，支持 system prompt |
+
+**为什么重要**：
+- 每个阶段**独立可替换**——可以换分块策略、换向量库、换 LLM
+- **幂等上传**：同一文件重新上传时，先删除旧向量再写入，保证数据一致性
+- 分块策略考虑了 Markdown 的文档结构（标题层级），而不是简单的固定长度切割
+
+### 设计三：工具即插即用的 Agent 工具系统
+
+**位置**：`src/main/java/org/example/agent/tool/*.java`
+
+**是什么**：基于 Spring AI `@Tool` 注解的工具系统，Agent 自动发现并可调用。
+
+```java
+// 工具定义示例
+@Component
+public class DateTimeTools {
+    @Tool(description = "获取当前日期和时间")
+    public String getCurrentDateTime() { ... }
+}
+```
+
+**核心设计决策**：
+
+| 决策 | 做法 | 原因 |
+|------|------|------|
+| Mock 开关 | `QueryMetricsTools` 和 `QueryLogsTools` 都有 `mockEnabled` 配置 | 开发/演示时不需要真实 Prometheus/CLS 环境 |
+| MCP 优先 | 当 MCP Client 可用时，自动排除 `QueryLogsTools` | 避免工具重复，MCP 提供更丰富的日志能力 |
+| JSON Schema 生成 | 使用 `jsonschema-generator` 为工具参数生成 schema | 让 LLM 理解工具的参数类型和约束 |
+| 工具注册 | `ChatService` 和 `AiOpsService` 各自注册工具集 | Agent 只获得需要的能力，避免干扰 |
+
+**ChatService 工具注册**：
+```java
+// 构建时注册所有可用工具
+ReactAgent agent = ReactAgent.builder()
+    .tools(dateTimeTools, internalDocsTools, 
+           queryMetricsTools, queryLogsTools)
+    .build();
+```
+
+**为什么重要**：
+- Agent 工具系统是 AI Agent 的**能力边界**——定义了 Agent 能做什么
+- Mock/Real 模式切换体现了**开发友好性**
+- MCP 协议的集成展示了**可扩展性**——Agent 可以从外部获取新能力
+
+---
+
+## 总结
+
+SuperBizAgent-java 是一个小而完整的 AI Agent 实践项目。它的三个核心竞争力是：
+
+1. **多 Agent 协作**（Planner-Executor-Replanner）——不是玩具，是真正解决问题的模式
+2. **工程化的 RAG 管道**——5 级流水线、幂等上传、智能分块
+3. **Spring AI 生态的完整实践**——从 @Tool 注解到 MCP 协议，展示了 Java 生态做 AI Agent 的成熟路径
+
+对于想将 AI Agent 引入企业运维场景的 Java 团队，这是一个很好的学习起点和脚手架。