Metadata-Version: 2.4
Name: ff-privaterag
Version: 0.13.0
Summary: 本地私有知识库 MCP 工具：把文档与代码仓库导入本地向量库，供 Claude 等 MCP 客户端语义检索；纯本地、数据不出机，支持后台导入、80+ 文件类型与 Office 文档
Project-URL: Homepage, https://gitee.com/fanmengfei/ff_PrivateRag
Project-URL: Repository, https://gitee.com/fanmengfei/ff_PrivateRag.git
Project-URL: Issues, https://gitee.com/fanmengfei/ff_PrivateRag/issues
Author: fanmf
License-Expression: MIT
License-File: LICENSE
Keywords: chromadb,claude,code-search,embeddings,knowledge-base,mcp,office,private,rag,vector-search,本地知识库,语义检索
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Requires-Dist: chromadb
Requires-Dist: fastmcp
Requires-Dist: gitpython
Requires-Dist: pathspec
Requires-Dist: pdfplumber
Requires-Dist: sentence-transformers
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: fast
Requires-Dist: optimum[onnxruntime]; extra == 'fast'
Provides-Extra: markitdown
Requires-Dist: markitdown[docx,outlook,pdf,pptx,xlsx]; extra == 'markitdown'
Provides-Extra: office
Requires-Dist: openpyxl; extra == 'office'
Requires-Dist: python-docx; extra == 'office'
Requires-Dist: python-pptx; extra == 'office'
Description-Content-Type: text/markdown

# 🧠 ff_PrivateRag – 本地私有知识库 MCP 工具

> 基于 MCP（Model Context Protocol）的本地知识库服务：把**文档与整个代码仓库**导入本地向量库，让 **Claude Code / Claude Desktop / Cursor** 等 AI 助手直接语义检索你的私人资料。**所有数据与模型都在本地运行，不上传任何内容**。

```bash
pip install ff-privaterag                  # 基础安装
claude mcp add ff-privaterag -- ff-privaterag   # 注册到 Claude Code
```

## ✨ 核心能力

- 🔒 **纯本地 / 隐私不出机**：本地嵌入（`bge-small-zh`）+ 本地向量库（ChromaDB），数据不上云。
- 📁 **文档 + 代码仓库导入**：单文件或整个目录递归导入；自动剪枝 `node_modules`/`.git`/`dist` 等、跟随 `.gitignore`。
- 📄 **80+ 文件类型**：文档/前端/Python/各类后端语言/脚本/SQL/配置 + 按文件名（`Dockerfile`/`Makefile` 等）；**可选 Office**（`.docx/.xlsx/.pptx`）。
- 🚀 **后台导入 + 进度可见**：大仓库后台导入不阻塞、不断连；`ingest_status`/`wait_ingest` 看**块级百分比 + 当前文件 + 活性/卡死检测**。
- ⚡ **CPU 提速**：可选 ONNX int8 量化（`[fast]`），纯 CPU 约 3× 加速。
- 🔎 **变更可追溯**：每个文本块记录来源路径、修改时间、Git 作者。
- 🛡️ **健壮自救**：并发导入互斥、僵死锁超时快速失败、`reset_ingest` 一键重置。

## 🧰 MCP 工具一览（7 个）

| 工具 | 作用 |
|------|------|
| `ingest_document` | 导入单个文件 |
| `ingest_directory` | 递归导入整个目录/代码仓库（后台执行） |
| `ingest_status` | 查看导入进度（即时快照） |
| `wait_ingest` | long-poll 持续跟踪进度（分级文案） |
| `reset_ingest` | 重置卡住的导入（清锁/状态，不删数据） |
| `query_knowledge` | 自然语言语义检索 |
| `list_knowledge` | 列出知识库已导入的全部内容 |

## 📦 安装选项

```bash
pip install ff-privaterag              # 基础（文档 + 代码 + 配置类）
pip install "ff-privaterag[markitdown]" # + 富文档（docx/xlsx/pptx/pdf/html/msg，统一转 Markdown，推荐）
pip install "ff-privaterag[office]"    # + Office（仅 docx/xlsx/pptx，markitdown 的轻量替代）
pip install "ff-privaterag[fast]"      # + ONNX int8 加速（纯 CPU 约 3×）
```
> 🇨🇳 中国大陆会自动回退到 `hf-mirror.com` 镜像下载嵌入模型，无需手动配置。

---

## 📌 项目目标

- **私有化**：所有数据、模型均运行在本地，无需联网，确保隐私安全。
- **本地检索增强**：为 AI 助手提供本地文件（文档、代码）的语义检索能力，提升问答准确性。
- **轻量易用**：通过 MCP 协议无缝集成到主流 AI 客户端，操作简单。
- **可追溯**：记录文档来源、变更时间，支持审计与版本回溯。

---

## 🧩 技术选型

| 组件 | 选型 | 说明 |
|------|------|------|
| **编程语言** | Python 3.10+ | 生态成熟，AI/ML 库丰富 |
| **MCP 框架** | FastMCP | 简化 MCP 服务器开发，装饰器风格 |
| **向量数据库** | ChromaDB | 轻量级，持久化，易用 |
| **嵌入模型** | BAAI/bge-small-zh-v1.5 | 本地运行，无需 API，面向中文检索，体积小 |
| **答案生成** | 由 MCP 客户端自身 LLM 完成 | 工具只做本地检索、返回片段；纯本地、隐私不出机 |
| **文档解析** | 按扩展名/文件名分发，80+ 类型 + 可选 Office | 纯文本零依赖；Office 走 `[office]` 可选依赖 |
| **版本控制集成** | GitPython | 读取文件变更历史（用于追溯，Git 非必需） |

---

## 🏗️ 系统架构

```mermaid
graph TD
    A[AI 客户端<br>Claude Desktop / Cursor] -->|MCP协议 stdio| B[ff_PrivateRag MCP Server]
    B --> C[FastMCP 路由]
    C --> D1[工具: ingest_document]
    C --> D2[工具: query_knowledge]
    D1 --> E[文本分块 Chunking]
    E --> F[嵌入模型 Embedding]
    F --> G[ChromaDB 向量存储]
    D2 --> H[向量检索]
    H --> G
    H --> I[返回相关片段]
    I --> J[LLM 生成答案（由客户端调用）]
```

---

## 🚀 安装

```bash
pip install ff-privaterag
```

安装后会注册命令行入口 `ff-privaterag`，用于以 stdio 方式启动 MCP 服务器。

> 首次执行检索/导入时会自动下载嵌入模型 `BAAI/bge-small-zh-v1.5`（约 95MB）并缓存到本地，之后离线可用。
>
> 🇨🇳 **中国大陆网络**：`huggingface.co` 通常无法直连。工具会**自动探测并回退到镜像 `https://hf-mirror.com`**，一般无需手动设置。
> - 想指定其他端点：`export HF_ENDPOINT=https://your-mirror`（PowerShell：`$env:HF_ENDPOINT="..."`）
> - 想禁用自动回退：`export FF_PRIVATERAG_NO_HF_MIRROR=1`

---

## 🔌 在 Claude Code CLI 中集成

```bash
claude mcp add ff-privaterag -- ff-privaterag
```

注册后重启 / 新开 Claude Code 会话，即可在对话中调用 `ingest_document` 与 `query_knowledge` 两个工具。

> 其他 MCP 客户端（Claude Desktop / Cursor）也兼容，在其配置中把 `ff-privaterag` 注册为本地 stdio server 即可。

### 数据目录

向量库默认持久化在全局目录 `~/.ff_privaterag/chroma`，与启动目录无关（适配被客户端作为子进程拉起的场景）。如需自定义：

```bash
export FF_PRIVATERAG_DATA_DIR=/your/custom/path   # 覆盖默认持久化目录
```

---

## 💡 使用示例

在 Claude Code 对话中用自然语言即可，由模型自动调用工具：

**导入文档**

```
你：把 D:\docs\需求文档.md 导入知识库
→ 工具 ingest_document(file_path="D:\\docs\\需求文档.md")
← 成功导入文档 '需求文档.md'，共 8 个文本块。
```

**导入整个代码仓库（v0.2 新增）**
```
你：把 D:\Workspace\my-vue-app 这个仓库导入知识库
→ 工具 ingest_directory(dir_path="D:\\Workspace\\my-vue-app")
← 目录 'my-vue-app' 导入完成：新增 187 个、更新 0 个文件，共 1432 个文本块；跳过 23984 个文件（gitignored 23800，unsupported_ext 150，too_large 20，binary 14）。
```

> `ingest_directory` 会：
> - **递归**导入目录下所有受支持的文本/代码/配置文件
> - 自动**剪枝** `node_modules`、`.git`、`dist`、`build`、`__pycache__`、`.venv` 等无关目录
> - **跟随仓库 `.gitignore`** 跳过被忽略的文件
> - 跳过**超大文件**（默认 >1MB，可经 `FF_PRIVATERAG_MAX_FILE_BYTES` 调整）与**二进制文件**
> - 每个文件沿用幂等逻辑：内容未变跳过、变更覆盖
>
> 支持 80+ 种文件类型（v0.12）：
> - **文档/标记**：`.txt .md .pdf .rst .adoc .tex .csv .tsv`
> - **前端/模板**：`.js .mjs .cjs .ts .jsx .tsx .vue .svelte .astro .css .scss .less .html .ejs .hbs .pug .twig`
> - **Python**：`.py .pyi`
> - **后端/系统语言**：`.java .go .rs .cpp .c .h .cs .kt .rb .php .swift .scala .lua .dart .r .pl .groovy .clj .ex .erl .hs .jl .nim .zig`
> - **脚本**：`.sh .bash .zsh .bat .cmd .ps1`　**数据库**：`.sql .graphql .gql`
> - **配置/数据**：`.json .yaml .yml .toml .xml .ini .env .properties .conf .cfg .gradle .editorconfig`
> - **按文件名**（无扩展名）：`Dockerfile Makefile Jenkinsfile Procfile .gitignore .npmrc .babelrc .prettierrc .eslintrc` 等
> - **Office / 富文档（可选依赖）**：`.docx .xlsx .pptx .pdf .html .msg` —— 推荐装 **markitdown**（`pip install "ff-privaterag[markitdown]"`），统一转 Markdown、保留表格结构；未装时 Office 回退 python-docx 等、PDF 回退 pdfplumber。富文档单独放宽体积上限（默认 50MB，`FF_PRIVATERAG_MAX_DOC_BYTES`），大文档不会被代码文件的 1MB 上限误跳过。

> ⚡ **性能（v0.4）**：
> - **流式写入**：目录导入边嵌入边落盘（每满 `FF_PRIVATERAG_FLUSH_CHUNKS` 块写一次，默认 512），导入中库逐步增长、**中途中断已导入部分保留**、再次导入自动跳过未变文件（断点续传）。
> - **快速模式（int8 量化，约 3× 提速）**：纯 CPU 下嵌入慢的解法。
>   ```bash
>   pip install "ff-privaterag[fast]"      # 装 optimum/onnxruntime
>   export FF_PRIVATERAG_FAST_EMBED=1      # 启用 ONNX int8 量化后端
>   ```
>   实测 bge-small-zh 在 CPU 上约 21→72 块/秒（~3.4×），检索质量几乎无损（余弦 0.995）。首次会构建并缓存量化模型（约几十秒，仅一次，存于 `~/.ff_privaterag/onnx-int8/`）。未装 `[fast]` 或加载失败时**自动回退** PyTorch，不影响使用。
>   - 量化配置默认 `avx512_vnni`（现代 Intel/AMD）；老 CPU/ARM 可设 `FF_PRIVATERAG_QUANT_CONFIG=avx2`（或 `arm64`）。
> - **Git 元数据**：目录导入只打开一次仓库（约 2.8× 提速）；`FF_PRIVATERAG_NO_GIT_META=1` 可完全跳过（最快，但检索结果无作者信息）。
> - 进度与规模信息输出到 **stderr 日志**（Claude Code 的 MCP 日志面板可见）；MCP 协议下没有实时进度条。
> - 仓库很大时仍建议先导核心子目录（如 `src/`）。
> - 🔒 **并发导入**（v0.5）：同一知识库同一时刻只能有一个导入在写（ChromaDB 限制）。若已有导入在进行时再发起导入，会**立即收到友好提示**（不再无声卡死），等前一个完成再试即可。极端情况下进程崩溃残留的锁会被自动接管；如有需要也可手动删除 `<数据目录>/.import.lock`。查询不受影响。
> - 🚀 **后台导入**（v0.7）：`ingest_directory` 默认**提交后台任务并立即返回**，导入在后台持续进行——彻底避免大仓库长时间占用单次调用导致 `MCP error -32000: Connection closed`。
>   - 用 **`ingest_status`** 工具随时查看进度（已处理 X/Y 文件、已写入 N 块、完成/中断）。
>   - 用 **`wait_ingest`** 工具**持续跟踪**进度（v0.10）：它会等待（最多约 30 秒，`FF_PRIVATERAG_WAIT_SECONDS` 可调）到"有进展/完成"才返回，未完成时提示可再次调用——连续调用即形成每隔约 30 秒一段的自动进度。（MCP 协议下工具无法主动推送，这是逼近"自动进度"的方式。）
>   - 📈 **块级百分比进度**（v0.11）：进度以**块百分比 + 当前文件名**呈现（如"导入中 62%，当前：src/main.vue"），大文件导致文件计数停滞时仍能看出在推进；`wait_ingest` 文案**分级**——「+N 块（活跃）/ 暂无新块（处理大文件，正常）/ 疑似卡住 / ✅ 完成摘要」，一眼判断活性，不再"成功却像卡住"。
>   - 配合流式落盘 + 断点续传：进程退出/中断后已导入部分保留，再次导入自动续传。
>   - 需要同步执行（脚本/小目录、确定性）可设 `FF_PRIVATERAG_SYNC_INGEST=1`。
> - 📊 **进度活性与自救**（v0.8）：`ingest_status` 显示**已运行时长、最后更新距今、处理速率**，一眼看出在推进还是卡住；后台进程存活但超过 `FF_PRIVATERAG_STALE_PROGRESS_SECONDS`（默认 180 秒）无更新时会**警告"可能卡住"**。若导入异常退出/卡死导致无法再导入，用 **`reset_ingest`** 一键清理残留锁与状态（**不删除已导入数据**），即可重新导入。
> - 🛡️ **库占用韧性**（v0.9）：若上次导入残留**僵死进程**占着数据库锁，打开库会在 `FF_PRIVATERAG_DB_OPEN_TIMEOUT`（默认 15 秒）后**快速失败并给出恢复指引**，而非无限卡死——连只读的 `query_knowledge`/`list_knowledge` 也保证秒回提示。恢复方法：`reset_ingest`（会检测并提示是否仍有僵死进程），必要时**彻底关闭所有 Claude Code 窗口**再重开。
>   - 内置排除目录已扩充：`.claude`、`.idea`、`.vscode`、`.vs`、`.github`、`public`、`Pods`、`DerivedData`、`vendor`、`tmp`、`logs` 等，整目录导入更干净。
>   - 想只导核心代码：直接导子目录，如 `把 D:\项目\src 导入知识库`。

**检索知识**

```
你：知识库里关于"系统模块划分"是怎么说的？
→ 工具 query_knowledge(query="系统模块划分", n_results=3)
← 找到 3 条相关信息：
   --- 结果 1 (来自: D:\docs\需求文档.md, 作者: zhangsan, 修改: 2026-06-20, 相似度: 0.812) ---
   系统分为用户管理、订单管理...
```

**查看知识库内容（v0.5 新增）**

```
你：知识库里都导入了哪些东西？
→ 工具 list_knowledge()
← 知识库共 12 个文件、347 个文本块：
   1. D:\docs\需求文档.md（21 块, 作者: zhangsan, 修改: 2026-06-20）
   2. D:\src\order.vue（8 块, 作者: lisi, 修改: 2026-06-25）
   ...
```

---

## 🛠️ 本地开发

```bash
python -m venv .venv && .venv/Scripts/activate   # Windows
pip install -e .[dev]                            # 可编辑安装 + 测试依赖
pytest                                           # 运行测试
python -m build                                  # 构建分发包到 dist/
```

---

## 📜 版本历史

| 版本 | 亮点 |
|------|------|
| 0.13 | 富文档统一经 markitdown 转 Markdown（docx/xlsx/pptx/pdf/html/msg）+ 文档类放宽体积上限 |
| 0.12 | 文件类型扩展到 80+ 扩展名 + 文件名白名单 + 可选 Office（docx/xlsx/pptx） |
| 0.11 | 块级百分比进度 + `wait_ingest` 文案分级（解决"成功却像卡住"） |
| 0.10 | `wait_ingest` long-poll 进度跟踪 |
| 0.9 | 库占用韧性：僵死锁超时快速失败、扩充排除目录 |
| 0.8 | 进度活性（运行时长/速率/卡死检测）+ `reset_ingest` |
| 0.7 | 后台导入（根治大导入 `-32000` 断连）+ `ingest_status` |
| 0.6 | `list_knowledge` 列出知识库内容 |
| 0.5 | 并发导入互斥锁 |
| 0.4 | 流式写入 + 断点续传 |
| 0.3 | 跨文件批量嵌入提速 |
| 0.2 | `ingest_directory` 目录批量导入 + 智能排除 |
| 0.1 | 核心：`ingest_document` + `query_knowledge` |
