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（苹果硅）	`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版本包括 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

团队开发

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

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

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

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

演出

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

操作	时间	令牌
启动	2.3秒	-
索引	8.5秒	-
搜索（1个查询）	95ms	~300
传统阅读	25秒	~12000

搜索速度提高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自动操作：

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

项目结构

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服务器问题

解决方案:

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

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

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

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

团队开发

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

按Git管理文档：常规Git工作流
每个开发人员启动DevRag：在每台计算机上进行本地设置
在Claude Code中搜索：所有人都可以搜索所有文档
自动同期: 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自动：

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

项目结构

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

故障排除

下载模型失败

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

解决方法:

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

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

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

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变得更好！

作者

附近

devrag (Tomohiro Owada)

快速接入

详细介绍

DevRag

为什么是DevRag？

特性

快速开始

1.下载二进制文件

2.配置克劳德代码

3.添加您的文档

4.使用克劳德代码搜索

配置

配置选项

命令行选项

模式示例

MCP工具

搜索

索引_降价

list_文档

删除文档

reindex_document

CLI使用情况

输出格式

MCP工具名称兼容性

标志语法

团队开发

演出

发展

运行测试

构建

创建发布

项目结构

故障排除

模型下载失败

GPU/CoreML不工作

无法启动

意外搜索结果

内存使用率高

需求

许可证

积分

贡献

贡献者

作者

日本语版

为什么需要DevRag？

特徴

快速启动

1.二进制下载

2. Claude Code设定

3.放置文档

4.在Claude Code中搜索

设定

设定项目

命令行选项

模式示例

MCP工具

搜索

索引_降价

list_文档

删除文档

reindex_document

CLI使用方法

出力形式

与MCP工具名称的兼容性

标记语法

团队开发

性能

开発

测试运行

构建

发布

项目结构

故障排除

下载模型失败

GPU/CoreML无法正常工作

无法启动

搜索结果与预期不同

内存使用量大

必要要件