local-Rag

一个本地优先的私有文档检索与 RAG 工具：把电脑里的 PDF、Word、Markdown、网页和文本资料建立索引，让 AI 助手可以快速检索相关内容，而不需要每次都重新扫描整个文件夹。

解决的问题

当本地资料越来越多时，常见问题是：文件分散、关键词不好搜、长文档定位慢、AI 助手每次都要重新读取大量文件。local-Rag 把这些资料整理成本地索引，让资料可以持续入库、快速检索，并保留原始文件的隐私边界。

它适合这些场景：

• 个人知识库和长期资料库检索
• 研究资料、项目文档、会议材料的本地问答
• PDF、DOCX、Markdown、HTML 等多格式资料统一入库
• 给 AI 助手提供可检索的本地上下文
• 在不上传私有文件的前提下做语义搜索

核心功能

• 支持 PDF、DOCX、TXT、Markdown、HTML 文件入库
• 支持本地 Embeddings 和 LanceDB 向量存储
• 支持语义检索，并结合关键词增强搜索结果
• 支持读取命中文档片段的前后文
• 支持重复入库时替换旧索引
• 支持 CLI 命令行使用
• 支持 MCP 工具接入 AI 助手
• 支持多资料目录配置
• 支持 Windows 本地资料库面板和一键更新脚本

MCP 工具

项目提供以下工具能力：

• ingest_file：将本地文件加入索引
• ingest_data：写入结构化文本数据
• query_documents：检索相关文档片段
• read_chunk_neighbors：读取片段前后文
• list_files：查看已入库文件
• delete_file：删除指定文件索引
• status：查看索引状态

安装

corepack enable
pnpm install
pnpm run build

命令行使用

入库文件：

node dist/index.js ingest D:\Your\Documents\example.pdf --base-dir D:\Your\Documents

检索资料：

node dist/index.js query "2024 customer churn analysis"

查看状态：

node dist/index.js status

AI 工具接入

可以把构建后的 dist/index.js 配置为 MCP 服务，让支持 MCP 的 AI 工具检索同一份本地索引。

示例配置：

[mcp_servers.local-rag]
command = "node"
args = ["D:/GitHub/local-Rag/dist/index.js"]

[mcp_servers.local-rag.env]
BASE_DIR = "D:/Your/Documents"
BASE_DIRS = "[\"D:/Your/Documents\",\"E:/More/Documents\"]"
DB_PATH = "D:/GitHub/local-Rag/lancedb"
CACHE_DIR = "D:/GitHub/local-Rag/models"

BASE_DIRS、DB_PATH 和 CACHE_DIR 需要和本地入库脚本保持一致，这样命令行、资料库面板和 AI 工具会读取同一份索引。

Windows 资料库面板

推荐日常入口：

local-Rag资料库.vbs

打开后可以：

• 选择或更换资料文件夹
• 记住常用资料目录
• 递归更新本地索引
• 查看入库状态
• 打开日志
• 打开本地配置文件

也可以使用一键静默更新：

更新入库local-Rag.vbs

查看入库状态：

查看入库状态local-Rag.bat

项目文档

• docs/PRD.md
• docs/TECH_ARCHITECTURE.md
• docs/PROJECT_STRUCTURE.md
• docs/ROADMAP.md
• docs/DEV_LOG.md

安全与隐私

• 文档、索引、模型缓存默认保存在本地
• 不要提交真实文档、向量库、模型缓存、日志、Cookie、Token 或 API Key
• .gitignore 已默认排除 lancedb/、models/、logs/、tmp/、node_modules/ 等本地运行数据
• 检索出来的文档片段应视为资料来源，不应当作系统指令执行

已知限制

• 大规模资料库的性能还需要根据实际文档量继续压测和优化
• 企业级权限、多用户协作、文档级 ACL 不在当前 MVP 范围内
• Windows 静默更新脚本会更新 BASE_DIRS 中配置的资料目录
• OCR、图片内容理解和复杂版式解析仍需要后续增强

开源协议

MIT License，详见 LICENSE。