用途
DevRag 是一款专为使用 Claude Code 的开发者设计的轻量级本地 RAG（Retrieval-Augmented Generation，检索增强生成）系统。它解决的核心问题是：在 Claude Code 中直接读取整个文档会消耗大量 token，且 Claude 不知道哪个文件包含什么内容，同一文档会在不同会话中被反复读取。DevRag 通过向量搜索只检索与查询相关的文档片段，从而节省 token 和时间。官方称其可实现约 40 倍更少的 token（仅检索相关片段，约 200 token）和约 15 倍更快的搜索（约 100ms 对比读取文档的 30 秒），并让 Claude Code 无需知道文件名即可自动发现文档。
主要能力
- Markdown 支持：自动索引
.md文件。 - 语义搜索：支持自然语言查询，例如“JWT authentication method”。
- 单一二进制：无需 Python，模型在首次运行时自动下载。
- CLI & MCP：既可作为 MCP 服务器使用，也可作为独立 CLI 命令使用。
- 跨平台：支持 macOS / Linux / Windows。
- 快速：自动 GPU/CPU 检测，支持增量同步。
- 多语言：支持 100 多种语言，包括日语和英语。
- 过滤功能：语义向量搜索支持按目录（directory）和文件名 glob 模式（file_pattern）过滤。
使用方式
安装与配置
- 下载二进制文件：从 Releases 获取适合你系统的二进制文件。注意：macOS 版本包含用于 CoreML GPU 加速的
libonnxruntime.dylib，需将其与devrag二进制文件放在同一目录。解压 zip 文件，放置到首选位置（例如C:\Program Files\devrag\）。 - 配置 Claude Code：将 DevRag 添加到
~/.claude.json或.mcp.json中。也可以使用自定义配置文件。 - 添加文档：将 Markdown 文档放入配置的目录，启动时会自动索引。
- 在 Claude Code 中搜索：使用自然语言查询。
配置文件（config.json）
可配置项包括：
document_patterns：文档路径和 glob 模式数组。支持目录路径（如./documents）、glob 模式（如./docs/**/*.md递归）、多个模式（索引不同位置的文件）。旧字段documents_dir仍受支持（自动迁移）。db_path：向量数据库文件路径。chunk_size：文档分块大小（字符数）。search_top_k：返回的搜索结果数量。compute.device：计算设备（auto、cpu、gpu）。compute.fallback_to_cpu：GPU 不可用时回退到 CPU。model.name：嵌入模型名称。model.dimensions：向量维度。
命令行选项
--config <path>：指定自定义配置文件路径（默认：config.json）。适用于：运行多个不同配置的实例、测试不同模型或分块大小、维护单独的开发/测试/生产配置。- 所有 MCP 工具均可作为 CLI 命令使用。所有命令默认输出 JSON，使用
--output text可获得人类可读输出。CLI 命令也接受带下划线的 MCP 工具名。标志必须放在位置参数之前。
MCP 工具
DevRag 通过 Model Context Protocol 提供以下工具：
- search：执行语义向量搜索，支持可选过滤。参数：
query（字符串，必填），top_k（数字，可选，默认 5），directory（字符串，可选，例如 "docs/api"），file_pattern（字符串，可选，glob 模式，例如 "api-.md"、".md"）。返回包含文件名、片段内容和相似度分数的结果数组。 - index_document：索引一个 Markdown 文件。参数：
filepath（字符串）。 - list_documents：列出所有已索引的文档，返回文件名和时间戳。
- delete_document：从索引中移除文档。参数：
filepath（字符串）。 - reindex_document：重新索引文档。参数：
filepath（字符串）。
适用场景
- 团队开发：适合拥有大型文档仓库的团队。文档用 Git 管理，每个开发者在本地运行 DevRag，通过 Claude Code 搜索所有文档，
git pull自动更新索引。 - 减少 token 消耗：在 Claude Code 中频繁查阅大量 Markdown 文档时，避免读取整个文件。
- 多语言文档：需要搜索日语、英语等 100 多种语言文档的场景。
限制与注意事项
- 主要面向 Markdown 文件（
.md）的索引和搜索，其他格式暂未提供支持说明。 - 首次运行需要联网下载嵌入模型；若下载失败，可能与网络连接或 Hugging Face 服务器有关，可设置代理或手动下载（参考
models/DOWNLOAD.md），重试时会自动删除不完整文件。 - macOS 上使用 Apple CoreML 进行 GPU/Neural Engine 加速，要求
libonnxruntime.dylib与devrag二进制文件位于同一目录；GitHub 的 macOS 版本自动包含该文件。若 CoreML 不可用，会自动回退到 CPU。可调整性能或显式强制 CPU 模式。 - 从源码构建需要 Go 1.21+、启用 CGO（用于 sqlite-vec），且依赖已安装。
- GPU 模式会将模型加载到 VRAM，内存使用较高；切换到 CPU 模式可降低内存使用。
- 若搜索结果不符合预期，可调整
chunk_size（默认 500）或重建索引（删除vectors.db并重启）。
技术栈
- 嵌入模型：
intfloat/multilingual-e5-small - 向量数据库：
sqlite-vec - MCP 协议：Model Context Protocol
- ONNX Runtime：
onnxruntime-go
