本地文档检索 Huajijunbilibili/dsh-localrag

localrag-mcp — 本地文档 RAG 检索插件（DeepSeek Harness）

一个给 DeepSeek Harness 的 agent 提供本地知识检索能力的 MCP 工具插件： agent 在对话中可以直接调用 mcp__localrag__search 等工具，对本地文档做语义检索并带来源引用的回答。

生态贡献：这是 DeepSeek Harness 官方贡献指南中"创建插件并分享"的实践项目，发布到 GitHub 后打上 dsh-plugin 话题即可被社区发现。

架构

DeepSeek Harness (dsh web)
│ --patch localrag.cordis.yml
▼
@deepseek-ai/dsh-mcp-client (官方通用 MCP 客户端)
│ 启动 stdio 子进程 ▼
server.py (Python, FastMCP)
├── index_documents(path) # 扫描目录，分块 + 向量化，写入 Chroma ├── search(query, k) # 语义检索，返回文本 + 来源路径 + 分数 └── list_documents() # 列出知识库中的文档 │ ├── 向量模型：fastembed / BAAI/bge-small-zh-v1.5（本地 ONNX，无需 API key） └── 向量库：Chroma（持久化到 ./data/chroma）

快速开始

1. 安装依赖（Python 3.10+）
cd localrag-mcp
pip install -r requirements.txt

2. 独立冒烟测试（不依赖 Harness）
python test-client.py
预期输出：tools: [...]; index: indexed 2 files, N chunks; search: 命中结果

3. 接入 DeepSeek Harness（在 harness 仓库根目录）
pnpm dsh web --patch D:\programing\python\LangChain\models\localrag-mcp\localrag.cordis.yml
首次会下载 bge-small-zh 模型（约 95MB，仅一次）

4. 在对话里使用 "先索引 D:\...\docs，然后检索：LangGraph 多 agent 是怎么协作的？"
agent 会依次调用 index_documents → search，并基于检索结果回答

✅ 验证结果（真实运行）

独立测试（python test-client.py）：

tools: ['index_documents', 'search', 'list_documents']
index: indexed 2 files, 4 chunks into 'documents'
search: 命中 langgraph-multiagent.md（top score 0.537，带 source 路径）

Harness 集成（pnpm dsh web --patch localrag.cordis.yml）实测：agent 按提示依次调用 index_documents → search，最终回答带来源与得分引用：

主要来源：langgraph-multiagent.md（chunk 0、1，检索得分 0.4851 / 0.2863）补充背景：langchain-basics.md（得分 0.1219）

工具清单（agent 视角）

| MCP 工具名 | 说明 |
| mcp__localrag__index_documents | 索引目录下的 .md/.txt（递归），分块 + 向量化入库 |
| mcp__localrag__search | 语义检索 top-k，返回文本、来源路径、相关性分数 |
| mcp__localrag__list_documents | 列出知识库全部来源文档 |

设计要点

- 检索带来源：每个 chunk 记录 source（文件绝对路径），agent 回答可溯源——这是区别于普通聊天的关键能力
- 全本地运行：embedding 用 ONNX 本地推理，不依赖外部 embedding API，无需任何密钥
- 分块策略：512 字符滑动窗口 + 64 重叠，中文文档友好（v2 可升级为语义分块）
- 增量索引：upsert 按文件去重，重复索引同一目录不会产生重复向量

Roadmap（v2）

- [ ] PDF / Word 支持（pdfplumber + python-docx）
- [ ] 语义分块（基于段落/标题，而非固定窗口）
- [ ] 用 LangChain 封装成标准 RAG 流程（多路召回 + 重排）
- [ ] 与多 agent 深度研究系统整合（检索 worker 复用本插件）
- [ ] 评估：用 RAGAS 对检索质量打分

简历用法

为 DeepSeek Harness 生态开发 dsh-plugin：本地文档 RAG 检索 MCP 插件（Python + Chroma + fastembed）
- 实现 index/search/list 三个 MCP 工具，agent 对话中可直接调用，检索结果带来源引用
- 全本地向量化（bge-small-zh，ONNX）与持久化存储，无需外部 API
- 通过官方 --patch 机制挂载，并完成独立冒烟测试与 Harness 集成验证

相关链接

- DeepSeek Harness 官方贡献指南（插件分享路径）：https://github.com/deepseek-ai/deepseek-harness
- 社区插件踩坑总结：Discussion #380
- MCP 通用客户端：@deepseek-ai/dsh-mcp-client