# DocMap — MemoryBear RAG 文档目录大纲

> **定位**：Sprint-2 深度文档化的任务拆解输入。每行 = 一篇待写文档，标题格式与 [S1-T1] 统一模板兼容。
> **责任人草拟**：基于当前 Sprint-1 分工建议，实际分配由项目经理确认。
> **目录结构**：`docs/rag/<stage>/<topic>.md`

---

## 文档目录总览

```
docs/rag/
├── _meta/                          # [S1-T1] 模板与评分卡（由 @知识运营与治理专家 维护）
├── 01-loader/
│   ├── 01-web-crawler.md           # Web 爬虫：URL 发现、内容提取、速率控制
│   ├── 02-feishu-integration.md    # 飞书集成：API 调用、鉴权、文档导出
│   ├── 03-yuque-integration.md     # 语雀集成：知识库同步、文档下载
│   └── 04-file-upload.md           # 文件上传与预处理（本地文件系统、NFS 兼容）
├── 02-parser/
│   ├── 01-pdf-parser.md            # PDF 解析：OCR + Layout + Table 流水线
│   ├── 02-docx-parser.md           # DOCX 解析：段落提取、图片嵌入
│   ├── 03-html-md-parser.md        # HTML / Markdown / TXT 解析
│   ├── 04-excel-parser.md          # Excel 解析：行列转表格结构
│   └── 05-vision-pipeline.md       # 视觉模块：OCR、布局识别、表格结构识别
├── 03-chunking/
│   ├── 01-chunking-strategies.md   # 分块策略全景：naive_merge、层级分块、树分块
│   ├── 02-task-type-adapters.md    # 文档类型适配器：book / paper / laws / qa / one
│   ├── 03-tokenizer.md             # RagTokenizer：中文分词、英文处理、fine_grained
│   └── 04-multimodal-chunking.md   # 多模态分块：图片 VLM 描述、音频转文本
├── 04-embedding/
│   ├── 01-embedding-model-arch.md  # Embedding 模型架构：Base 接口 + 10+ Provider
│   ├── 02-provider-guide.md        # Provider 接入指南：OpenAI / HuggingFace / 国产模型
│   └── 03-auto-questions.md        # 自动问题生成：并发策略、LLM 缓存
├── 05-vdb/
│   ├── 01-elasticsearch-schema.md  # ES 索引 Schema：字段定义、mapping、analyzer
│   ├── 02-hybrid-search.md         # 混合检索：BM25 + Vector 加权融合
│   └── 03-storage-connections.md   # 存储连接层：ES、Redis、DocStore
├── 06-graphrag/
│   ├── 01-graphrag-overview.md     # GraphRAG 总览：Light vs General 对比
│   ├── 02-entity-relation-extraction.md  # 实体关系抽取：Extractor 流程、Prompt 工程
│   ├── 03-graph-merge-and-rank.md  # 图合并与 PageRank：子图合并、实体消歧
│   ├── 04-community-reports.md     # 社区报告：Leiden 聚类、LLM 报告生成（General only）
│   └── 05-knowledge-graph-search.md # KG 检索：Query 分析、实体匹配、N-hop 扩展
├── 07-retrieval/
│   ├── 01-retrieval-api.md         # 检索 API：knowledge_retrieval()、Dealer.search()
│   ├── 02-query-understanding.md   # Query 理解：关键词提取、同义词扩展
│   └── 03-multi-kb-retrieval.md    # 多知识库检索：结果合并、去重策略
├── 08-reranking/
│   ├── 01-rerank-architecture.md   # 重排序架构：内置评分 vs 外部 Rerank 模型
│   └── 02-rerank-providers.md      # Rerank Provider：Jina / DashScope / Xinference
├── 09-prompt/
│   ├── 01-prompt-system.md         # Prompt 模板系统：template.py + generator.py
│   ├── 02-citation-prompts.md      # 引用标注 Prompt：citation_prompt / citation_plus
│   └── 03-toc-prompts.md           # 目录相关 Prompt：TOC 检测、提取、相关性
├── 10-llm/
│   ├── 01-llm-chat-model.md        # Chat 模型架构：Base.chat() / chat_streamly()
│   ├── 02-llm-providers.md         # Chat Provider 全景：OpenAI / Azure / 国产模型
│   └── 03-vision-model.md          # 视觉模型：VLM 描述、图片理解
├── 11-e2e/
│   ├── 01-indexing-pipeline.md     # 端到端入库流程：Celery 任务链、错误处理、进度追踪
│   ├── 02-query-pipeline.md        # 端到端检索流程：Workflow Node → 检索 → 生成
│   └── 03-answer-postprocess.md    # 回答后处理：引用插入、缓存、流式输出
└── 12-architecture-evolution/
    ├── 01-modularization-roadmap.md  # 模块化拆分建议
    ├── 02-performance-optimization.md # 性能优化方向
    └── 03-future-extensions.md       # 未来扩展：多模态检索、混合搜索、对话记忆
```

---

## 文档详细定义

### 01-loader

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 01-01 | Web 爬虫 | **写**：URL 规范化、robots.txt 检查、速率限制、HTTP 抓取、内容提取、去重策略。**不写**：搜索引擎索引、分布式爬虫、JS 渲染。 | `crawler/web_crawler.py`, `crawler/http_fetcher.py`, `crawler/content_extractor.py`, `crawler/rate_limiter.py`, `crawler/robots_parser.py` | Python 工程师 | 需覆盖 CrawledDocument 数据结构 |
| 01-02 | 飞书集成 | **写**：App 鉴权、文件夹遍历、文档导出（PDF/DOCX/Sheet）、异步轮询下载。**不写**：飞书审批流、机器人消息推送。 | `integrations/feishu/client.py`, `integrations/feishu/retry.py`, `integrations/feishu/models.py` | Python 工程师 | 需说明 `_export_file` vs `_download_file` 区别 |
| 01-03 | 语雀集成 | **写**：个人 Token 鉴权、知识库遍历、文档详情获取、多种格式下载（MD/HTML/Excel）。**不写**：语雀协作编辑、版本管理。 | `integrations/yuque/client.py`, `integrations/yuque/retry.py`, `integrations/yuque/models.py` | Python 工程师 | lakesheet 解压逻辑需重点说明 |
| 01-04 | 文件上传 | **写**：文件上传接口、NFS 同步等待、binary 读取策略、进度追踪。**不写**：CDN 分发、大文件分片上传。 | `controllers/document_controller.py`, `utils/file_utils.py`, `tasks.py:213` | Python 工程师 | 30s NFS 等待逻辑是 MemoryBear 特有 |

### 02-parser

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 02-01 | PDF 解析 | **写**：PDF 渲染、OCR 文本检测、布局分类、表格结构识别、文本合并策略。**不写**：PDF 生成/编辑、数字签名验证。 | `deepdoc/parser/pdf_parser.py`, `deepdoc/vision/ocr.py`, `deepdoc/vision/layout_recognizer.py`, `deepdoc/vision/table_structure_recognizer.py` | Python 工程师 | 核心中的核心，需重点投入 |
| 02-02 | DOCX 解析 | **写**：段落提取、图片提取、超链接提取、OLE 嵌入文件。**不写**：DOCX 生成、样式渲染。 | `deepdoc/parser/docx_parser.py`, `utils/file_utils.py:extract_embed_file` | Python 工程师 | 需与 `app/naive.py` 的 vision_figure_parser 联动说明 |
| 02-03 | HTML/MD/TXT 解析 | **写**：HTML 标签清洗、Markdown 结构化解析、纯文本处理。**不写**：CSS 样式解析、JS 执行。 | `deepdoc/parser/html_parser.py`, `deepdoc/parser/markdown_parser.py`, `deepdoc/parser/txt_parser.py` | Python 工程师 | 合并为一篇即可 |
| 02-04 | Excel 解析 | **写**：行列读取、Sheet 遍历、表头检测、Markdown 表格转换。**不写**：公式计算、图表提取。 | `deepdoc/parser/excel_parser.py` | Python 工程师 | 轻量 |
| 02-05 | 视觉流水线 | **写**：OCR 模型（ONNXRuntime）、布局识别模型、表格结构模型、图像预处理。**不写**：模型训练、模型量化。 | `deepdoc/vision/*.py` | Python 工程师 | 含模型加载、推理、后处理 |

### 03-chunking

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 03-01 | 分块策略全景 | **写**：naive_merge、naive_merge_with_images、hierarchical_merge、tree_merge 的实现与选择策略。**不写**：通用 NLP 分词算法原理。 | `nlp/__init__.py:562+`, `nlp/rag_tokenizer.py` | Python 工程师 | 需附决策树：何时用哪种策略 |
| 03-02 | 文档类型适配器 | **写**：book/paper/manual/laws/qa/one/picture/audio 各自的分块逻辑、数据结构差异。**不写**：业务场景适配（如医疗/法律专有分块）。 | `app/naive.py:508`, `app/book.py`, `app/paper.py`, `app/manual.py`, `app/laws.py`, `app/qa.py`, `app/one.py`, `app/picture.py`, `app/audio.py` | Python 工程师 | 核心章节，需逐一说明 |
| 03-03 | RagTokenizer | **写**：中文分词（Huqie/datrie）、英文处理（nltk/Porter/WordNet）、fine_grained_tokenize、分词对检索的影响。**不写**：分词算法数学推导。 | `nlp/rag_tokenizer.py` | Python 工程师 | 与 ES ik_max_word 的对比 |
| 03-04 | 多模态分块 | **写**：图片 VLM 描述调用链、音频 sequence2txt 转录、视频处理（如有）。**不写**：VLM/ASR 模型内部原理。 | `app/picture.py`, `app/audio.py`, `llm/cv_model.py`, `llm/sequence2txt_model.py`, `deepdoc/parser/figure_parser.py` | Python 工程师 | 需说明 vision_model 注入机制 |

### 04-embedding

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 04-01 | Embedding 模型架构 | **写**：Base.encode() 接口、批次处理、Token 截断（8000/2048）、返回格式。**不写**：Embedding 模型原理（Word2Vec/BERT 等）。 | `llm/embedding_model.py` | Python 工程师 | 重点讲接口契约 |
| 04-02 | Provider 接入指南 | **写**：10+ Provider 的配置方式、API Key 管理、Base URL 设置、批次大小差异。**不写**：各厂商 API 的通用文档。 | `llm/embedding_model.py` 各子类 | Python 工程师 | 表格形式列出即可 |
| 04-03 | 自动问题生成 | **写**：并发生成策略（ThreadPoolExecutor）、LLM 缓存机制（redis）、问题注入到 chunk metadata。**不写**：问题生成质量评估。 | `tasks.py:323+`, `prompts/generator.py:question_proposal()` | Python 工程师 | 与检索效果的关系 |

### 05-vdb

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 05-01 | ES 索引 Schema | **写**：字段定义、mapping 类型、ik_max_word analyzer、dense_vector cosine 配置、动态维度。**不写**：ES 集群运维、分片策略。 | `vdb/field.py`, `vdb/elasticsearch/elasticsearch_vector.py:653+` | Python 工程师 | 需附完整 mapping 示例 |
| 05-02 | 混合检索 | **写**：BM25 + Vector 加权融合（0.05:0.95）、FusionExpr、score 归一化、降级策略。**不写**：BM25 算法数学推导、近似最近邻算法。 | `nlp/search.py:439`, `vdb/elasticsearch/elasticsearch_vector.py:374`, `utils/doc_store_conn.py:FusionExpr` | Python 工程师 | 核心章节，需讲清楚为什么权重是 0.05:0.95 |
| 05-03 | 存储连接层 | **写**：ES 连接、Redis 缓存、DocStore 抽象。**不写**：连接池调优、网络安全配置。 | `utils/es_conn.py`, `utils/redis_conn.py`, `utils/doc_store_conn.py` | Python 工程师 | 轻量 |

### 06-graphrag

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 06-01 | GraphRAG 总览 | **写**：Light vs General 架构对比、适用场景、配置开关（use_graphrag/resolution/community）。**不写**：图数据库选型对比（已选 ES）。 | `graphrag/light/`, `graphrag/general/`, `graphrag/search.py` | Python 工程师 | 必须包含对比表格 |
| 06-02 | 实体关系抽取 | **写**：Extractor 基类、_process_single_content 流程、Gleaning Loop、Prompt 工程、LLM 输出解析。**不写**：信息抽取的通用 NLP 方法。 | `graphrag/light/graph_extractor.py`, `graphrag/general/graph_extractor.py`, `graphrag/general/extractor.py` | Python 工程师 | 核心章节 |
| 06-03 | 图合并与 PageRank | **写**：merge_subgraph 流程、nx.Graph 操作、PageRank 计算、实体消歧（EntityResolution）。**不写**：PageRank 数学推导。 | `graphrag/general/index.py`, `graphrag/entity_resolution.py` | Python 工程师 | 需附图数据结构示例 |
| 06-04 | 社区报告 | **写**：Leiden 层次聚类、社区报告 Prompt、报告数据结构、存储方式。**不写**：社区发现算法数学原理。 | `graphrag/general/leiden.py`, `graphrag/general/community_reports_extractor.py`, `graphrag/general/community_report_prompt.py` | Python 工程师 | General only |
| 06-05 | KG 检索 | **写**：KGSearch.retrieval() 流程、Query Rewrite、实体匹配、N-hop 扩展、社区报告检索。**不写**：图遍历算法通用理论。 | `graphrag/search.py:130` | Python 工程师 | 与标准检索的交互关系 |

### 07-retrieval

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 07-01 | 检索 API | **写**：knowledge_retrieval() 接口、Dealer.search() 内部实现、MatchDenseExpr / MatchTextExpr / FusionExpr。**不写**：信息检索通用理论。 | `nlp/search.py:36`, `nlp/search.py:349`, `utils/doc_store_conn.py` | Python 工程师 | 核心章节 |
| 07-02 | Query 理解 | **写**：关键词提取、同义词扩展、查询改写、min_match 阈值调整。**不写**：NLP 句法分析。 | `nlp/query.py`, `nlp/synonym.py`, `nlp/term_weight.py` | Python 工程师 | 轻量 |
| 07-03 | 多知识库检索 | **写**：Folder 类型递归检索、跨 KB 结果去重、权限过滤。**不写**：权限系统的 RBAC 设计。 | `workflow/nodes/knowledge/node.py:195`, `knowledge_repository.py` | Python 工程师 | 需说明 Folder 类型的特殊处理 |

### 08-reranking

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 08-01 | 重排序架构 | **写**：内置重排（token+vector 相似度融合）vs 外部 Rerank 模型、调用时机、容错降级。**不写**：Learning-to-Rank 通用理论。 | `nlp/search.py:606`, `models/rerank.py` | Python 工程师 | 需对比两种方式的适用场景 |
| 08-02 | Rerank Provider | **写**：JinaRerank、DashScopeRerank 的 API 调用、参数映射。**不写**：各厂商 API 通用文档。 | `models/rerank.py:57+` | Python 工程师 | 轻量 |

### 09-prompt

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 09-01 | Prompt 模板系统 | **写**：template.py 的 .md 文件加载机制、generator.py 的函数式 Prompt 组装、参数替换。**不写**：Prompt Engineering 通用方法论。 | `prompts/template.py`, `prompts/generator.py` | Python 工程师 | 需列出全部模板清单 |
| 09-02 | 引用标注 Prompt | **写**：citation_prompt / citation_plus 的输入输出、引用格式、上下文窗口管理。**不写**：学术论文引用规范。 | `prompts/generator.py:citation_prompt()` | Python 工程师 | 与 insert_citations 联动 |
| 09-03 | 目录相关 Prompt | **写**：TOC 检测、提取、层级分配、基于 TOC 的 chunk 相关性筛选。**不写**：目录生成算法。 | `prompts/generator.py` TOC 系列函数 | Python 工程师 | 轻量 |

### 10-llm

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 10-01 | Chat 模型架构 | **写**：Base.chat() / chat_streamly() / chat_with_tools() 接口、返回格式、流式输出。**不写**：Transformer 模型原理。 | `llm/chat_model.py` | Python 工程师 | 重点讲接口契约 |
| 10-02 | Chat Provider 全景 | **写**：各 Provider 配置、温度/TopP/MaxTokens 参数透传、错误处理。**不写**：各厂商 API 通用文档。 | `llm/chat_model.py` 各子类 | Python 工程师 | 表格形式 |
| 10-03 | 视觉模型 | **写**：CV 模型接口、VLM 描述调用、图片理解。**不写**：CNN/ViT 原理。 | `llm/cv_model.py` | Python 工程师 | 轻量 |

### 11-e2e

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 11-01 | 端到端入库流程 | **写**：Celery 任务链、parse_document 完整流程、进度追踪、错误处理、GraphRAG 异步触发。**不写**：Celery 分布式队列原理。 | `tasks.py` | Python 工程师 | 核心章节，需附时序图 |
| 11-02 | 端到端检索流程 | **写**：Workflow Knowledge Node 完整流程、检索模式选择、结果组装。**不写**：Workflow Engine 通用设计。 | `workflow/nodes/knowledge/node.py` | Python 工程师 | 核心章节 |
| 11-03 | 回答后处理 | **写**：引用插入、缓存策略、流式输出处理。**不写**：WebSocket 通用原理。 | `nlp/search.py:489`, `utils/redis_conn.py` | Python 工程师 | 轻量 |

### 12-architecture-evolution

| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
|------|------|----------|-------------|-----------|------|
| 12-01 | 模块化拆分建议 | **写**：当前耦合点识别、建议的接口抽象（如 ParserInterface、ChunkerInterface）、拆分优先级。**不写**：微服务拆分方案。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |
| 12-02 | 性能优化方向 | **写**：Embedding 批处理优化、ES 查询优化、GraphRAG 并发优化、缓存命中率提升。**不写**：通用性能优化方法论。 | 全局代码分析 | AI 知识库专家 | 需量化当前瓶颈假设 |
| 12-03 | 未来扩展 | **写**：多模态检索、混合搜索增强、对话记忆优化、知识图谱演进方向。**不写**：产品需求文档。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |

---

## 工作量估算

| 阶段 | 文档数 | 预估 Sprint-2 人天（每篇 0.5~1d） |
|------|--------|----------------------------------|
| 01-loader | 4 | 2d |
| 02-parser | 5 | 3d |
| 03-chunking | 4 | 2.5d |
| 04-embedding | 3 | 1.5d |
| 05-vdb | 3 | 2d |
| 06-graphrag | 5 | 3d |
| 07-retrieval | 3 | 2d |
| 08-reranking | 2 | 1d |
| 09-prompt | 3 | 1.5d |
| 10-llm | 3 | 1.5d |
| 11-e2e | 3 | 2d |
| 12-architecture-evolution | 3 | 1.5d |
| **合计** | **41** | **~23.5d** |

> 注：Python 工程师承担约 30 篇（技术实现细节），AI 知识库专家承担约 8 篇（架构/优化/扩展方向）。具体分配由项目经理确认。