devrag (Tomohiro Owada)

DevRag

克劳德代码免费本地RAG-节省代币和时间

日语版在这里 | 日本版

DevRag是一个轻量级的RAG（检索增强生成）系统，专为使用Claude Code的开发人员设计。不要通过阅读整个文档来浪费代币——让矢量搜索准确地找到你需要的东西。

为什么是DevRag？

使用Claude Code时，使用Read工具读取文档会消耗大量令牌：

• ❌ 浪费上下文：每次读取整个文档（每个文件3000多个令牌）
• ❌ 搜索能力差：克劳德不知道哪个文件包含什么
• ❌ 重复的：同一文档在会话中被多次阅读

与DevRag合作：

• ✅ 代币减少40倍：矢量搜索仅检索相关块（约200个标记）
• ✅ 快15倍：在100毫秒内搜索，而阅读时间为30秒
• ✅ 自动发现：Claude Code在不知道文件名的情况下查找文档

特性

• 🤖 简单RAG -克劳德码的检索增强生成
• 📝 Markdown支持 -自动索引.md文件
• 🔍 语义搜索 -自然语言查询，如“JWT身份验证方法”
• 🚀 单一二进制 -没有Python，模型在第一次运行时自动下载
• 💻 CLI&MCP -用作MCP服务器或独立CLI命令
• 🖥️ 交叉平台的 -macOS/Linux/Windows
• ⚡ 快 -自动GPU/CPU检测，增量同步
• 🌐 多语言 -支持100多种语言，包括日语和英语

快速开始

1.下载二进制文件

从以下位置获取相应的二进制文件 发布:

macOS/Linux：

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

备注：macOS版本包括 libonnxruntime.dylib 用于CoreML GPU加速。将其保存在与 devrag 二元的。

窗户：

• 解压缩zip文件
• 放置在您喜欢的位置（例如。， C:\Program Files\devrag\)

2.配置克劳德代码

添加 ~/.claude.json 或 .mcp.json:

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

使用自定义配置文件：

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag",
      "args": ["--config", "/path/to/custom-config.json"]
    }
  }
}

3.添加您的文档

mkdir documents
cp your-notes.md documents/

就是这样！文档在启动时会自动编入索引。

4.使用克劳德代码搜索

在克劳德代码中：

"Search for JWT authentication methods"

配置

创建 config.json:

{
  "document_patterns": [
    "./documents",
    "./notes/**/*.md",
    "./projects/backend/**/*.md"
  ],
  "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
  }
}

配置选项

• 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

：指定自定义配置文件路径（默认值： config.json`)

例子：

devrag --config /path/to/custom-config.json

这有助于：

• 运行具有不同配置的多个实例
• 测试不同的模型或块大小
• 维护单独的开发/测试/产品配置

模式示例

{
  "document_patterns": [
    "./documents",                    // All .md files in documents/
    "./notes/**/*.md",                // Recursive search in notes/
    "./projects/*/docs/*.md",         // docs/ in each project
    "/path/to/external/docs"          // Absolute path
  ]
}

MCP工具

DevRag通过模型上下文协议提供以下工具：

搜索

使用可选过滤执行语义向量搜索

参数：

• query （字符串，必填）：自然语言搜索查询
• top_k （数字，可选）：最大结果数（默认值：5）
• directory （字符串，可选）：过滤到特定目录（例如“docs/api”）
• file_pattern （字符串，可选）：文件名的Glob模式（例如，“api-*.md“，”*.md”）

退货： 包含文件名、块内容和相似性得分的搜索结果数组

示例：

// Basic search
search(query: "JWT authentication")

// Search only in docs/api directory
search(query: "user endpoints", directory: "docs/api")

// Search only files matching pattern
search(query: "deployment", file_pattern: "guide-*.md")

// Combined filters
search(query: "authentication", directory: "docs/api", file_pattern: "auth*.md")

索引_降价

为markdown文件建立索引

参数：

• filepath （string）：要索引的文件的路径

list_文档

列出所有索引文档

退货： 包含文件名和时间戳的文档列表

删除文档

从索引中删除文档

参数：

• filepath （string）：要删除的文件的路径

reindex_document

重新索引文档

参数：

• filepath （string）：要重新索引的文件的路径

CLI使用情况

DevRag也可以用作独立的CLI工具。所有MCP工具都可以作为CLI命令使用。

# Start MCP server (default)
devrag
devrag serve

# Search documents
devrag search "JWT authentication"
devrag search "deployment" --top-k 10 --directory docs/api

# Index files
devrag index ./docs/api-spec.md
devrag index-code --directory ./src

# List indexed documents
devrag list
devrag list --fields filename

# Delete / Reindex
devrag delete ./docs/old-spec.md --dry-run
devrag reindex ./docs/updated-spec.md

# Code symbol relations
devrag search-relations handleAuth --type calls

# Build dictionary (Japanese-English mapping)
devrag build-dictionary

# Show CLI schema (machine-readable)
devrag schema

输出格式

默认情况下，所有命令都输出JSON。使用 --output text 用于人类可读的输出。

# JSON (default, suitable for scripts and AI agents)
devrag search "authentication"

# Text (human-readable)
devrag search "authentication" --output text

MCP工具名称兼容性

CLI命令还接受带下划线的MCP工具名称：

devrag index_markdown ./docs/api.md    # same as: devrag index
devrag list_documents                  # same as: devrag list
devrag delete_document ./docs/old.md   # same as: devrag delete
devrag reindex_document ./docs/api.md  # same as: devrag reindex

标志语法

必须放置旗帜 之前 位置参数：

# Correct
devrag delete --dry-run file.md

# Incorrect (--dry-run is ignored)
devrag delete file.md --dry-run

团队开发

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

1. 在Git中管理文档：常规Git工作流程
2. 每个开发人员都运行DevRag：每台机器上的本地设置
3. 通过克劳德代码搜索：每个人都可以搜索所有文档
4. 自动同步: git pull 自动更新索引

为项目的文档目录进行配置：

{
  "document_patterns": [
    "./docs",
    "./api-docs/**/*.md",
    "./wiki/**/*.md"
  ],
  "db_path": "./.devrag/vectors.db"
}

演出

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

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

发展

运行测试

# All tests
go test ./...

# Specific packages
go test ./internal/config -v
go test ./internal/indexer -v
go test ./internal/embedder -v
go test ./internal/vectordb -v

# Integration tests
go test . -v -run TestEndToEnd

构建

# Using build script
./build.sh

# Direct build
go build -o devrag cmd/main.go

# Cross-platform release build
./scripts/build-release.sh

创建发布

# Create version tag
git tag v1.0.1

# Push tag
git push origin v1.0.1

GitHub自动操作：

1. 为所有平台构建
2. 创建GitHub版本
3. 上传二进制文件
4. 生成校验和

项目结构

devrag/
├── cmd/
│   └── main.go              # Entry point
├── internal/
│   ├── cli/                 # CLI commands
│   ├── config/              # Configuration
│   ├── embedder/            # Vector embeddings
│   ├── indexer/             # Indexing logic
│   ├── mcp/                 # MCP server
│   └── vectordb/            # Vector database
├── models/                  # ONNX models
├── build.sh                 # Build script
└── integration_test.go      # Integration tests

故障排除

模型下载失败

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

解决方案:

1. 检查互联网连接
2. 对于代理环境：

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

1. 手动下载（参见 models/DOWNLOAD.md)
2. 重试（不完整的文件将自动删除）

GPU/CoreML不工作

在macOS上，DevRag使用Apple CoreML进行GPU/神经引擎加速。要求：

• libonnxruntime.dylib 必须与位于同一目录中 devrag 二进制
• GitHub上的macOS版本会自动包含此文件

如果CoreML不可用，DevRag会自动回退到CPU。要调整性能：

# Adjust CPU thread count (default: 4)
DEVRAG_THREADS=4 devrag

要明确强制CPU模式：

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

无法启动

• 确保安装Go 1.21+（用于建筑）
• 检查CGO是否启用： go env CGO_ENABLED
• 验证是否安装了依赖项
• 首次运行需要互联网（型号下载）

意外搜索结果

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

内存使用率高

• GPU模式将模型加载到VRAM中
• 切换到CPU模式以降低内存使用率

需求

• 转到1.21+（从源代码构建）
• CGO已启用（适用于sqlite-vec）
• macOS、Linux或Windows

许可证

MIT许可证

积分

• 嵌入模型： intfloat/多语言e5-small
• 矢量数据库： sqlite-vc
• MCP协议： 模型上下文协议
• ONNX运行时： onnxruntime go

贡献

欢迎问题和拉取请求！

贡献者

特别感谢所有帮助改进DevRag的贡献者：

您的贡献使DevRag对每个人都更好！

作者

附近

______________________________________________________________________

日本语版

为Claude Code节省免费本地RAG-令牌和时间

DevRag是为使用Claude Code的开发人员提供的轻量RAG（Retrieval-Agmented Generation）系统。不要读取整个文档而浪费令牌，只获取矢量搜索所需的信息。

为什么需要DevRag？

在Claude Code中读取文档会消耗大量的令牌：

• ❌ 上下文浪费：每次读取整个文档（超过3000个文件令牌）
• ❌ 缺少可搜索性：Claude不知道哪个文件写了什么
• ❌ 重复：跨会话多次阅读同一文档

使用DevRag：

• ✅ 令牌消耗1/40：仅检索向量检索所需的部分（约200个令牌）
• ✅ 15倍高速：搜索100ms vs读取30秒
• ✅ 自动発见：即使不知道文件名也能找到Claude Code

特徴

• 🤖 简易RAG - Claude Code用の検索扩张生成
• 📝 支持标记 -.md文件的自动索引
• 🔍 意味検索 -自然语言查询，如“如何验证JWT”
• 🚀 单二进制 -不需要Python，模型在首次启动时自动下载
• 💻 CLI&MCP -可作为MCP服务器或CLI命令使用
• 🖥️ 跨平台 -macOS/Linux/Windows
• ⚡ 高速 - GPU/CPU自动検出、差分同期
• 🌐 多言语 -支持100多种语言，包括日语和英语

快速启动

1.二进制下载

发布从中下载适合环境的文件：

平台｜文件｜ |----------|------| |macOS（苹果硅）| devrag-macos-apple-silicon.tar.gz | |macOS（英特尔）| 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/

注意：macOS版发布用于酷睿ML GPU高速化libonnxruntime.dylib中所述修改相应参数的值。devrag请放置在与二进制相同的目录中。

窗户：

• 解压缩zip文件
• 放置在任意位置（例如： C:\Program Files\devrag\）

2. Claude Code设定

~/.claude.json 或 .mcp.json 添加到：

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

使用自定义配置文件：

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag",
      "args": ["--config", "/path/to/custom-config.json"]
    }
  }
}

3.放置文档

mkdir documents
cp your-notes.md documents/

到此结束！启动时自动索引。

4.在Claude Code中搜索

在Claude Code中：

「JWTの認証方法について検索して」

设定

config.json创建：

{
  "document_patterns": [
    "./documents",
    "./notes/**/*.md",
    "./projects/backend/**/*.md"
  ],
  "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
  }
}

设定项目

• 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

：指定自定义配置文件的路径（默认值： config.json`）

使用例:

devrag --config /path/to/custom-config.json

这对于以下用途很有用：

• 使用不同的设置运行多个实例
• 测试不同的模型和信息块大小
• 分离开发/测试/生产环境设置

模式示例

{
  "document_patterns": [
    "./documents",                    // documents/内の全.mdファイル
    "./notes/**/*.md",                // notes/内を再帰的に検索
    "./projects/*/docs/*.md",         // 各プロジェクトのdocs/
    "/path/to/external/docs"          // 絶対パス
  ]
}

MCP工具

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

搜索

执行带过滤功能的语义向量搜索

参数：

• query （string，必需）：自然语言搜索查询
• top_k （number，可选）：最大结果数（默认值：5）
• directory （string，可选）：缩小到特定目录（例如，“docs/api”）
• file_pattern （string，可选）：文件名的glob模式（例如“api-*.md“，”*.md”）

返回值： 包含文件名、信息块内容、相似度得分的检索结果的排列

使用例:

// 基本検索
search(query: "JWT認証")

// docs/apiディレクトリ内のみ検索
search(query: "ユーザーエンドポイント", directory: "docs/api")

// パターンに一致するファイルのみ検索
search(query: "デプロイ", file_pattern: "guide-*.md")

// フィルターの組み合わせ
search(query: "認証", directory: "docs/api", file_pattern: "auth*.md")

索引_降价

索引标记文件

参数：

• filepath （string）：要索引的文件路径

list_文档

获取索引文档列表

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

删除文档

从索引中删除文档

参数：

• filepath （string）：要删除的文件路径

reindex_document

重新索引文档

参数：

• filepath （string）：要重新索引的文件路径

CLI使用方法

DevRag也可以作为独立的CLI工具使用。所有的MCP工具都可以作为CLI命令使用。

# MCPサーバーを起動（デフォルト）
devrag
devrag serve

# ドキュメントを検索
devrag search "JWT認証"
devrag search "デプロイ" --top-k 10 --directory docs/api

# ファイルをインデックス化
devrag index ./docs/api-spec.md
devrag index-code --directory ./src

# インデックス済みドキュメント一覧
devrag list
devrag list --fields filename

# 削除 / 再インデックス
devrag delete ./docs/old-spec.md --dry-run
devrag reindex ./docs/updated-spec.md

# コードシンボル関係検索
devrag search-relations handleAuth --type calls

# 辞書ビルド（日本語→英語マッピング）
devrag build-dictionary

# CLIスキーマ表示（機械可読）
devrag schema

出力形式

所有命令默认输出JSON。--output text中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

# JSON（デフォルト、スクリプトやAIエージェント向け）
devrag search "認証"

# テキスト（人間向け）
devrag search "認証" --output text

与MCP工具名称的兼容性

CLI命令也可以使用下划线格式的MCP工具名称：

devrag index_markdown ./docs/api.md    # devrag index と同じ
devrag list_documents                  # devrag list と同じ
devrag delete_document ./docs/old.md   # devrag delete と同じ
devrag reindex_document ./docs/api.md  # devrag reindex と同じ

标记语法

标志是位置参数的前必须放置在：

# 正しい
devrag delete --dry-run file.md

# 誤り（--dry-runが無視される）
devrag delete file.md --dry-run

团队开发

最适合有大量文档的团队：

1. 按Git管理文档：常规Git工作流
2. 每个开发人员启动DevRag：在每台计算机上进行本地设置
3. 在Claude Code中搜索：所有人都可以搜索所有文档
4. 自动同期: git pull自动更新索引

为项目的docs目录设置：

{
  "document_patterns": [
    "./docs",
    "./api-docs/**/*.md",
    "./wiki/**/*.md"
  ],
  "db_path": "./.devrag/vectors.db"
}

性能

环境：MacBook Pro M2100文件（合计1MB）

操作｜时间｜令牌｜ |------|------|----------| |起动| 2.3秒| - | ｜索引｜8.5秒｜-｜ 搜索（1个查询） 以前的读取=25秒｜~120000｜

搜索速度为260倍，令牌为40分之1

开発

测试运行

# すべてのテスト
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自动：

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

项目结构

devrag/
├── cmd/
│   └── main.go              # エントリーポイント
├── internal/
│   ├── cli/                 # CLIコマンド
│   ├── config/              # 設定管理
│   ├── embedder/            # ベクトル埋め込み
│   ├── indexer/             # インデックス処理
│   ├── mcp/                 # MCPサーバー
│   └── vectordb/            # ベクトルDB
├── models/                  # ONNXモデル
├── build.sh                 # ビルドスクリプト
└── integration_test.go      # 統合テスト

故障排除

下载模型失败

原因：互联网连接或主机接口服务器问题

解决方法:

1. 检查互联网连接
2. 对于代理环境：

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

1. 手动下载（models/DOWNLOAD.md参照）
2. 重试（自动删除不完整的文件）

GPU/CoreML无法正常工作

macOS使用Apple CoreML的GPU/Noural Engine高速化。条件：

• libonnxruntime.dylib的devrag与二进制文件位于同一目录中
• GitHub的macOS版本包含此文件

如果CoreML不可用，则自动回退至CPU。性能调整：

# CPUスレッド数の変更（デフォルト: 4）
DEVRAG_THREADS=4 devrag

明确指定CPU模式时：

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

无法启动

• 确定是否安装了Go1.21+（如果从源构建）
• 确定CFO是否有效： go env CGO_ENABLED
• 确认是否安装了依赖关系
• 首次启动时需要互联网连接（模型下载）

搜索结果与预期不同

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

内存使用量大

• 在GPU模式下，模型加载到VRAM
• 切换到CPU模式时内存使用量减少

必要要件

• Go1.21+（从源构建时）
• CFO有效（由于sqlite-vec）
• macOS, Linux,或Windows

许可证

MIT许可证

信用

• 嵌入模型： intfloat/多语言e5-small
• 矢量数据库： sqlite-vc
• MCP协议： 模型上下文协议
• ONNX运行时： onnxruntime go

分发

欢迎Issues和Pull Requests！

分销商

感谢为改善DevRag做出贡献的各位：

大家的贡献使DevRag变得更好！

作者

附近