# 多格式文档支持 — 设计文档

**日期**: 2026-07-10
**版本**: 1.0

## 目标

将 md-vector-db 从"仅 Markdown"扩展为支持 `.txt`、`.pdf`、`.html` 的多格式文档向量数据库。

## 非目标

- 不支持 `.docx`、`.pptx`、`.epub` 等 Office/电子书格式（留待后续扩展）
- 不改变现有的嵌入和检索流程
- 不改变 HTTP API 的请求/响应模型

## 架构

### 模块结构

```
src/core/
├── splitters/                   # 新建目录
│   ├── __init__.py              # 导出 registry + 所有 Splitter
│   ├── base.py                  # Splitter Protocol + BaseTextSplitter (ABC)
│   ├── markdown.py              # MarkdownSplitter (从 ingest.py 移入)
│   ├── text.py                  # TextSplitter (纯文本按段落+标点硬切)
│   ├── pdf.py                   # PDFSplitter (pymupdf → TextSplitter)
│   ├── html.py                  # HTMLSplitter (bs4 → TextSplitter)
│   └── registry.py              # 工厂 + 扩展名→Splitter 映射表
├── ingest.py                    # 精简，用 registry.get_splitter() 自动选择
```

### 类继承

```
Splitter (Protocol)
   └── BaseTextSplitter (ABC)       # max_size, overlap, _split_single_paragraph
           ├── MarkdownSplitter     # 已有，从 ingest.py 移入
           ├── TextSplitter         # 纯文本：按 \n\n 切段落，超长按标点硬切
           ├── PDFSplitter          # 读取 PDF → extract_text() → 委托 TextSplitter
           └── HTMLSplitter         # 读取 HTML → get_text() → 委托 TextSplitter
```

`PDFSplitter` 和 `HTMLSplitter` **不继承** `BaseTextSplitter`，而是组合一个 `TextSplitter` 实例。它们实现 `Splitter` Protocol，在 `split()` 中：提取纯文本 → 委托 `TextSplitter.split()`。

### 注册表

`registry.py` 维护默认扩展名映射：

```python
_DEFAULT_MAP = {
    ".md": "markdown",
    ".markdown": "markdown",
    ".txt": "text",
    ".pdf": "pdf",
    ".html": "html",
    ".htm": "html",
}

def get_splitter(file_path: str, **config) -> Splitter:
    """根据扩展名自动选择 Splitter，未匹配回退到 TextSplitter."""
```

## 依赖策略

- `pymupdf` 和 `beautifulsoup4` 作为**可选依赖**
- 首次使用 PDF/HTML 格式时才 `import`，库缺失时抛 `ImportError` 带安装提示
- 安装方式：

```bash
uv sync --extra pdf     # PDF 支持
uv sync --extra html    # HTML 支持
uv sync --extra all     # 全部可选依赖
```

## ingest.py 改动

### DocumentIngestor.__init__

已有 `splitter` 可选参数，**保持不变**。显式传入的 splitter 覆盖自动选择。

### ingest_file()

改为使用 `get_splitter(file_path, ...)` 自动选择 splitter：

```python
def ingest_file(self, file_path: str) -> int:
    splitter = self.splitter or get_splitter(file_path,
        max_size=..., overlap=...)
    ...
```

### ingest_directory()

将 `rglob("*.md")` 改为遍历所有支持格式：

```python
_SUPPORTED_SUFFIXES = {".md", ".markdown", ".txt", ".pdf", ".html", ".htm"}

def ingest_directory(self, dir_path: str) -> dict[str, int]:
    for f in Path(dir_path).rglob("*"):
        if f.suffix.lower() in _SUPPORTED_SUFFIXES:
            ...
```

## 数据流

```
文件路径 → get_splitter(path)
           ├── .md  → MarkdownSplitter.split(text)
           ├── .txt → TextSplitter.split(text)
           ├── .pdf → PDFSplitter.split(binary)
           │            └── pymupdf 提取文字 → TextSplitter.split(text)
           └── .html → HTMLSplitter.split(html)
                        └── bs4 去标签 → TextSplitter.split(text)
                                   ↓
                               batch_embed(chunks)
                                   ↓
                              ChromaDB.add()
```

## 测试策略

- `tests/test_splitters_text.py` — TextSplitter 段落切分、硬切、overlap
- `tests/test_splitters_registry.py` — 扩展名映射、回退逻辑、自定义注册
- `tests/test_splitters_pdf.py` — PDF 提取文字 + 分块（需 pymupdf）
- `tests/test_splitters_html.py` — HTML 去标签 + 分块（需 bs4）
- `tests/test_ingest.py` — 补 `ingest_directory` 多格式遍历测试

## CLI/API 影响

- **CLI**：零改动。`ingest` 和 `ingest-dir` 自动获得多格式能力
- **API**：零改动。`POST /api/v1/ingest` 的 `file_path` 自动支持
- **`ingest_content()`**：仍默认使用 `MarkdownSplitter`（处理 Markdown 字符串），显式传入 content 时不变

## 风险

| 风险                                                     | 缓解                                                                                          |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| PDF 提取失败（扫描件/图片 PDF）                          | 抛明确异常，跳过该文件                                                                        |
| HTML 标签复杂导致去标签不干净                            | 用`soup.get_text(separator="\n")` 保留段落结构                                              |
| `ingest.py` 迁移 MarkdownSplitter 后旧 import 路径失效 | 在`ingest.py` 保留兼容 import：`from src.core.splitters.markdown import MarkdownSplitter` |