docs: consolidate rag refactor issues

mvp/issues/rag-chunk-context-reconstruction.md

@@ -0,0 +1,55 @@
+# RAG 切片上下文重建缺失
+
+**状态**：待规划  
+**严重程度**：高  
+**发现时间**：2026-07-04  
+**范围**：知识库上传、切片、向量召回、Agent 上下文组装
+
+---
+
+## 现象
+
+同一个 Markdown 章节在内容较长时会被拆成多个 chunk。当前检索命中其中一个 chunk 后，返回给 Agent 的主要是单个 chunk 内容，不会自动把同章节的前后片段、章节标题链路、相邻 chunk 一起恢复出来。
+
+这会导致两个问题：
+
+1. 命中片段只包含局部语义，缺少前置定义、约束条件或后续步骤。
+2. 同章节被分段后，检索结果之间缺少可追溯的关联，Agent 不一定知道它们属于同一章节。
+
+---
+
+## 当前实现
+
+- `DocumentChunkService` 会按 Markdown 标题建立 `title` 和 `breadcrumb`，再按段落累积切片。
+- 超过阈值时仍会切断同一章节，只是尽量避免打断代码块和列表。
+- `VectorIndexService` 会把 `chunkIndex`、`totalChunks`、`title`、`breadcrumb` 放入 metadata。
+- `VectorSearchService` 查询 Milvus 后直接返回命中的 chunk，没有做相邻 chunk 扩展或 section 级聚合。
+- `LookupKnowledgeTool` 消费 L1 结果时，也没有根据 `docId + chunkIndex + breadcrumb` 回补上下文。
+
+---
+
+## 影响
+
+- RAG 回答容易漏掉同章节中的约束条件。
+- 长流程类文档会被拆散，Agent 看到的是“片段证据”，不是“完整流程”。
+- 面试解释中需要承认：当前系统有 metadata 基础，但还没有把它用于上下文重建。
+
+---
+
+## 建议修复
+
+优先做命中后的上下文扩展：
+
+1. L1 命中 chunk 后，按 `docId + chunkIndex` 拉取前后 N 个相邻 chunk。
+2. 如果 metadata 中 `breadcrumb` 相同，允许扩展到同章节的多个 chunk。
+3. 上下文打包时标记 `命中片段`、`前文`、`后文`，避免 Agent 把扩展内容误认为全部都是高置信命中。
+4. 增加 token budget 控制，超过预算时优先保留命中 chunk 和标题链路。
+
+---
+
+## 相关文件
+
+- `src/main/java/com/superbiz/agent/service/DocumentChunkService.java`
+- `src/main/java/com/superbiz/agent/service/VectorIndexService.java`
+- `src/main/java/com/superbiz/agent/service/VectorSearchService.java`
+- `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java`