开发资源分配器

Name: 开发资源分配器
Author: tomohiro-owada

作者：tomohiro-owada10 星标更新：2025-10-25

安装使用来源：spider==github.com

项目介绍

DevRag

专为Claude Code开发者的免费本地RAG系统 - 节省令牌与时间

日语版请点击此处 | Japanese Version

DevRag是一款专门为使用Claude Code的开发者设计的轻量级RAG（检索增强生成）系统。停止通过阅读整个文档浪费令牌——让向量搜索找到你需要的确切信息。

为什么需要DevRag？

在使用Claude Code时，通过“读取”工具阅读文档会消耗大量的令牌：

❌ 浪费上下文：每次阅读整个文档（每个文件超过3,000个令牌）
❌ 搜索性差：Claude不知道哪个文件包含什么信息
❌ 重复性：跨会话多次阅读相同的文档

使用DevRag：

✅ 令牌减少40倍：向量搜索仅检索相关片段（约200个令牌）
✅ 速度提升15倍：搜索耗时100毫秒，而阅读则需30秒
✅ 自动发现：Claude Code无需知道文件名即可找到文档

功能

🤖 简易RAG - 适用于Claude Code的检索增强生成
📝 Markdown支持 - 自动索引.md文件
🔍 语义搜索 - 使用自然语言查询，例如“JWT认证方法”
🚀 单二进制文件 - 不需要Python，模型在首次运行时自动下载
🖥️ 跨平台 - 支持macOS / Linux / Windows
⚡ 快速 - 自动检测GPU/CPU，增量同步
🌐 多语言 - 支持包括日语和英语在内的100多种语言

快速开始

1. 下载二进制文件

从Releases获取适合您环境的二进制文件：

平台	文件
macOS (Apple Silicon)	`devrag-macos-apple-silicon.tar.gz`
macOS (Intel)	`devrag-macos-intel.tar.gz`
Linux (x64)	`devrag-linux-x64.tar.gz`
Linux (ARM64)	`devrag-linux-arm64.tar.gz`
Windows (x64)	`devrag-windows-x64.zip`

macOS/Linux:

tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/devrag

Windows:

解压zip文件
将其放置在您喜欢的位置（例如：C:\Program Files\devrag\）

2. 配置Claude Code

在~/.claude.json或.mcp.json中添加：

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag"
    }
  }
}

3. 添加您的文档

mkdir documents
cp your-notes.md documents/

就这样！文档会在启动时自动被索引。

4. 使用Claude Code进行搜索

在Claude Code中：

"搜索JWT认证方法"

配置

创建config.json：

{
  "documents_dir": "./documents",
  "db_path": "./vectors.db",
  "chunk_size": 500,
  "search_top_k":  5,
  "compute": {
    "device": "auto",
    "fallback_to_cpu": true
  },
  "model": {
    "name": "multilingual-e5-small",
    "dimensions": 384
  }
}

配置选项

documents_dir: 包含markdown文件的目录
db_path: 向量数据库文件路径
chunk_size: 文档片段大小（字符数）
search_top_k: 返回的搜索结果数量
compute.device: 计算设备（auto, cpu, gpu）
compute.fallback_to_cpu: 如果没有GPU，则回退到CPU
model.name: 嵌入模型名称
model.dimensions: 向量维度

MCP工具

DevRag通过Model Context Protocol提供了以下工具：

search

执行语义向量搜索

参数:

query (string): 搜索查询

返回值: 包含文件名、片段内容和相似度分数的搜索结果数组

index_markdown

索引一个markdown文件

参数:

filepath (string): 要索引的文件路径

list_documents

列出所有已索引的文档

返回值: 包含文件名和时间戳的文档列表

delete_document

从索引中删除一个文档

参数:

filepath (string): 要删除的文件路径

reindex_document

重新索引一个文档

参数:

filepath (string): 要重新索引的文件路径

团队开发

非常适合拥有大量文档存储库的团队：

在Git中管理文档：正常的Git工作流程
每位开发者运行DevRag：每台机器上的本地设置
通过Claude Code搜索：每个人都可以搜索所有文档
自动同步：git pull自动更新索引

为项目文档目录配置：

{
  "documents_dir": "./docs",
  "db_path": "./.devrag/vectors.db"
}

性能

环境：MacBook Pro M2，100个文件（总计1MB）

操作	时间	令牌
启动	2.3秒	-
索引化	8.5秒	-
搜索（1个查询）	95毫秒	~300
传统读取	25秒	~12,000

搜索速度提高260倍，令牌减少40倍

开发

运行测试

# 所有测试
go test ./...

# 特定包
go test ./internal/config -v
go test ./internal/indexer -v
go test ./internal/embedder -v
go test ./internal/vectordb -v

# 集成测试
go test . -v -run TestEndToEnd

构建

# 使用构建脚本
./build.sh

# 直接构建
go build -o devrag cmd/main.go

# 跨平台发布构建
./scripts/build-release.sh

创建发布

# 创建版本标签
git tag v1.0.1

# 推送标签
git push origin v1.0.1

GitHub Actions会自动：

为所有平台构建
创建GitHub Release
上传二进制文件
生成校验和

项目结构

devrag/
├── cmd/
│   └── main.go              # 入口点
├── internal/
│   ├── config/              # 配置管理
│   ├── embedder/            # 向量嵌入
│   ├── indexer/             # 索引逻辑
│   ├── mcp/                 # MCP服务器
│   └── vectordb/            # 向量数据库
├── models/                  # ONNX模型
├── build.sh                 # 构建脚本
└── integration_test.go      # 集成测试

故障排除

模型下载失败

原因：互联网连接或Hugging Face服务器问题

解决方法：

检查互联网连接

对于代理环境：

export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

手动下载（参见models/DOWNLOAD.md）
重试（不完整的文件会被自动移除）

GPU未被检测到

在config.json中明确设置为CPU：

{
  "compute": {
    "device": "cpu",
    "fallback_to_cpu": true
  }
}

无法启动

确保安装了Go 1.21+（用于从源码构建）
检查CGO是否启用：go env CGO_ENABLED
确认依赖项已安装
首次运行时需要互联网连接（用于模型下载）

搜索结果不符合预期

调整chunk_size（默认：500）
重建索引（删除vectors.db并重启）

内存使用量过高

GPU模式下，模型加载到VRAM
切换到CPU模式以降低内存使用量

必要条件

Go 1.21+（用于从源码构建）
启用CGO（用于sqlite-vec）
macOS, Linux, 或 Windows

许可证

MIT License

致谢

嵌入模型: intfloat/multilingual-e5-small
向量数据库: sqlite-vec
MCP协议: Model Context Protocol
ONNX Runtime: onnxruntime-go

贡献

欢迎提交Issue和Pull Requests！

作者

towada