Code Rag (Qduc)

代码RAG

对整个代码库进行语义代码搜索。 用简单的英语提问，获取包含源代码位置的相关代码片段。

与其搜索函数名，不如询问“身份验证逻辑”，并在整个项目中找到所有相关的身份验证代码。

目录

• 快速开始
• 克劳德对代码RAG的看法
• 为什么使用代码RAG？
• 使用克劳德代码（MCP集成）
• 配置
• 运作原理
• API使用
• 支持的语言
• 需求
• 故障排除
• 发展
• 贡献

快速开始

1.安装

使用 紫外线 （推荐）：

uvx --from code-rag-mcp code-rag-setup --install

*注意：此操作将代码RAG安装在隔离的 uv 工具环境，并在更新过程中保持您的配置。*

使用pip：

python -m venv .venv
source .venv/bin/activate
pip install code-rag-mcp
code-rag-setup

*默认情况下，安装向导拒绝将可选依赖项安装到非隔离的Python中。使用 code-rag-setup --allow-global-python 只有当你故意想要这种行为的时候。*

Python新手？ 使用一个命令安装程序：

curl -sSL https://raw.githubusercontent.com/qduc/code-rag/main/scripts/install.sh | bash

2.添加到克劳德

使用Claude代码注册MCP服务器：

claude mcp add -s user code-rag --transport stdio -- uvx "code-rag-mcp[local]"

如果您安装了 pip，首先激活您的虚拟环境并使用 code-rag-mcp 而不是 uvx 上面的命令。

需要其他设置变体或配置详细信息吗？看 使用克劳德代码（MCP集成）.

3.尝试一下（可选）

在与Claude一起使用之前，先使用CLI进行测试：

code-rag-cli --path /path/to/your/project

克劳德对代码RAG的看法（对此持保留态度！）

I have taken a lot of salt, show me!

代码RAG审查

我运行了9个不同的语义查询，以在代码库的不同方面测试该工具。以下是我的评价：

优势

1. 出色的语义理解能力

• 查询“共享嵌入服务器生命周期管理”正确识别了核心设计文档和实施（0.54相关性）
• “不同语言的语法感知分块”既找到了实现指南，也找到了实际代码
• 搜索理解概念，而不仅仅是关键字——即使精确的术语不匹配，也能找到相关的代码

1. 良好的相关性评分

• 分数通常与实际相关性很好地相关（良好匹配的范围为0.4-0.6+）
• 排名靠前的结果总是比排名靠后的结果更相关
• 该工具正确地将实现代码优先于测试夹具

1. 元数据质量

• 结果包括文件路径、行号和函数/类上下文
• 示例：src/code_rag/api.py:443-462增量_重新索引（）|代码RAGAPI（0.61）
• 这使得导航到确切位置变得容易

1. 很好地处理复杂的查询

• 多概念查询，如“增量重新索引检测修改的文件”，找到了正确的代码
• 特定领域的术语效果很好（“嵌入模型配置”、“MCP服务器工具”）

弱点

1. 通用查询返回零散的结果

• “错误处理和重试逻辑”（查询5）返回的结果不太集中
• 找到超时处理程序，打印错误，但没有连贯的重试逻辑
• 对于过于宽泛的查询，这是意料之中的，但值得注意

1. 一些测试代码噪声

• “数据库初始化和连接”返回测试夹具作为顶级结果，而不是实际实现
• test_mcp_server.py中的模拟数据库排名（0.45）高于真实数据库代码（0.35）
• 可以通过结果过滤或增强生产代码来改进

1. 有限上下文窗口

• 结果显示，每个块大约有20-30行，这是合理的，但有时会中断中期实现
• expand_context参数有帮助，但并不总是使用

具体观察

什么很棒：

• 架构/设计查询：“共享嵌入服务器生命周期管理”→ 完美的结果
• 实现查询：“语法感知分块”→ 找到了文档和代码
• 特定子系统查询：“增量重新索引”→ 找到了确切的函数

什么可以更好：

• 非常广泛的查询（“错误处理”）需要更多的过滤
• 测试与生产代码消歧
• 也许可以添加文件类型增强（更喜欢src/而不是tests/）

建议

1. 在工具描述中添加查询指南-用户应该知道特定查询比通用查询更有效（MCP工具描述中已经有了这一点，这很好）
2. 考虑结果筛选选项-允许排除测试文件或对某些目录进行优先级排序
3. 默认情况下展开上下文-默认情况下可以启用Expand_context参数，以获得更好的块可见性
4. 添加结果分组-按文件对结果进行分组，显示“此文件有3个相关块”

总体评估

评分：8.5/10

语义搜索对于其预期目的非常有效。它成功地基于概念查询找到了相关代码，而不仅仅是关键字匹配。相关性评分是可靠的，元数据使结果具有可操作性。

主要的改进领域是过滤测试代码和处理过于宽泛的查询。对于使用此工具的开发人员来说，关键的见解是：在查询中要具体。“身份验证令牌刷新逻辑”比“身份验证”更有效

这是一个真正有用的工具，在探索不熟悉的代码库时可以节省大量时间。

为什么使用代码RAG？

• 理解不熟悉的代码库 -提问而不是阅读所有内容
• 查找示例 -“重试错误处理”找到所有相关模式
• 重构辅助 -找到与您正在更改的功能相关的所有代码
• 文档 -提取上下文以编写文档或入职培训

使用克劳德代码（MCP集成）

Code RAG充当MCP服务器，让Claude在对话过程中自动搜索您的代码库。

注意 uv: 以下许多示例使用 紫外线 （具体来说 uvx)用于快速、零配置执行。如果你没有 uv 安装后，您可以使用标准 pip 或 npx （如果使用包装）。

快速设置

选项1：使用uvx（推荐）

# Install uv first: https://github.com/astral-sh/uv

# Claude Code
# Local variant:
claude mcp add -s user code-rag --transport stdio -- uvx "code-rag-mcp[local]"
# Cloud variant:
claude mcp add -s user code-rag --transport stdio -- uvx "code-rag-mcp[cloud]"

完成！现在，您可以开始将Code RAG与Claude Code一起使用。

选项2：使用pip（标准）

# Install in an isolated environment
python -m venv .venv
source .venv/bin/activate
pip install code-rag-mcp

# Register with Claude Code using the absolute path to the binary
claude mcp add -s user code-rag --transport stdio -- $(which code-rag-mcp)

选项3：本地开发安装

# Clone and install
git clone https://github.com/qduc/code-rag.git
cd code-rag
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Register with Claude Code
claude mcp add -s user code-rag --transport stdio -- $(which code-rag-mcp)

配置

MCP服务器从环境变量或配置文件中读取配置。通过MCP客户端的设置进行配置：

克劳德桌面(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "code-rag": {
      "command": "uvx",
      "args": ["code-rag-mcp"],
      "env": {
        "CODE_RAG_EMBEDDING_MODEL": "nomic-ai/CodeRankEmbed",
        "CODE_RAG_DATABASE_TYPE": "chroma",
        "CODE_RAG_RERANKER_ENABLED": "true"
      }
    }
  }
}

克劳德代码：在上面的设置部分注册MCP服务器后，配置环境变量或配置文件。

常见配置选项:

• CODE_RAG_EMBEDDING_MODEL -嵌入模型（默认值： nomic-ai/CodeRankEmbed)

- nomic-ai/CodeRankEmbed -代码优化，本地运行，需要GPU才能获得最佳性能 - text-embedding-3-small -OpenAI嵌入，无需GPU（需要 OPENAI_API_KEY)

• CODE_RAG_DATABASE_TYPE -数据库后端： chroma 或 qdrant （默认值： chroma)
• CODE_RAG_CHUNK_SIZE -块大小（以字符为单位）（默认值： 1024)
• CODE_RAG_RERANKER_ENABLED -启用结果重新排序，可能会产生更好的结果，但速度较慢（默认值： false)
• CODE_RAG_SHARED_SERVER -跨实例共享嵌入服务器，减少内存占用（默认值： true)

OpenAI嵌入示例:

{
  "mcpServers": {
    "code-rag": {
      "command": "uvx",
      "args": ["code-rag-mcp"],
      "env": {
        "CODE_RAG_EMBEDDING_MODEL": "text-embedding-3-small",
        "OPENAI_API_KEY": "sk-...",
        "CODE_RAG_RERANKER_ENABLED": "true"
      }
    }
  }
}

用法

配置后，Claude可以自动搜索您的代码库：

You: "Find the database connection logic"

Claude: [Automatically searches and finds the code]
        "I found the database connection logic in src/code_rag/db/connection.py..."

看 docs/mcp.md 了解详细的设置和故障排除。

基本用法

# Different codebase
code-rag-cli --path /path/to/repo

# Force reindex
code-rag-cli --reindex

# More results
code-rag-cli --results 10

# Different embedding model (better for code)
code-rag-cli --model text-embedding-3-small # need to set OPENAI_API_KEY env

# Use Qdrant instead of ChromaDB
code-rag-cli --database qdrant

配置

优先顺序

配置按以下顺序加载（优先级越高，优先级越低）：

1. 环境变量 （最高优先级）
2. 通过自定义配置文件 CODE_RAG_CONFIG_FILE 环境变量
3. 项目配置： ./code-rag.config
4. 用户配置： ~/.config/code-rag/config （使用默认值自动创建）

对于MCP服务器：在MCP客户端配置中设置环境变量（请参阅上面的MCP集成部分）。

用于CLI使用：使用环境变量或配置文件。

如果你跑 code-rag-setup 没有 --install，向导仅在当前Python环境隔离时安装可选依赖项（virtualenv、conda-env或 uv 工具环境）。这避免了意外修改系统或共享Python安装。

环境变量

# Use code-optimized embeddings (recommended)
export CODE_RAG_EMBEDDING_MODEL="nomic-ai/CodeRankEmbed"

# Or OpenAI embeddings
export OPENAI_API_KEY="sk-..."
export CODE_RAG_EMBEDDING_MODEL="text-embedding-3-small"

# Use Qdrant
export CODE_RAG_DATABASE_TYPE="qdrant"

# Adjust chunk size
export CODE_RAG_CHUNK_SIZE="2048"

# Enable reranking for better results
export CODE_RAG_RERANKER_ENABLED="true"

# Add custom ignore patterns (comma-separated)
export CODE_RAG_ADDITIONAL_IGNORE_PATTERNS="*.tmp,*.bak,logs/"

支持的云提供商

Code RAG通过以下方式支持各种云嵌入提供商 轻量级LLM.Set CODE_RAG_EMBEDDING_MODEL 指定提供商特定的型号名称，并提供必要的凭据：

对于其他提供者（HuggingFace、Mistral等），请参阅 LiteLLM文档 用于模型名称和所需的环境变量。

配置文件格式

配置文件使用相同的格式（键=值）：

# ~/.config/code-rag/config or ./code-rag.config
CODE_RAG_EMBEDDING_MODEL=nomic-ai/CodeRankEmbed
CODE_RAG_DATABASE_TYPE=chroma
CODE_RAG_CHUNK_SIZE=1024
CODE_RAG_RERANKER_ENABLED=false

中的完整配置选项 docs/IMPLEMENTATION.md.

运作原理

1. 扫描 你的代码库（尊重 .gitignore)
2. 块 智能代码（Python、JS、Go、Rust、Java、C/C++的语法感知）
3. 嵌入 使用ML模型将块作为向量
4. 商店 矢量数据库（ChromaDB或Qdrant）
5. 搜索 查询时的语义

可插拔架构-交换数据库、嵌入模型或添加新模型。

API使用

以编程方式使用：

from code_rag.api import CodeRAGAPI

api = CodeRAGAPI(database_type="chroma", embedding_model="all-MiniLM-L6-v2")
api.initialize_collection("myproject")

# Index
chunks = api.index_codebase("/path/to/project")

# Search
results = api.search("authentication logic", n_results=5)
for r in results:
    print(f"{r['file_path']} - {r['similarity']:.2f}")

文档

• 代理商.md -开发人员入职培训和架构概述
• docs/IMPLEMENTATION.md -详细实施参考
• docs/mcp.md -MCP服务器设置指南

支持的语言

语法感知分块：Python、JavaScript、TypeScript、Go、Rust、Java、C、C++

其他语言使用行感知分块（仍然有效，只是上下文感知程度较低）。

需求

• Python 3.10+
• 最小依赖性（默认情况下为ChromaDB+句子转换器）
• 可选：OpenAI API密钥，Qdrant服务器

故障排除

导入错误？ pip install --force-reinstall --upgrade code-rag-mcp （或 pip install -e . 如果在当地开发）

数据库问题？ code-rag-cli --reindex

内存问题？ export CODE_RAG_BATCH_SIZE="16"

向导验证通过，但首次使用仍下载模型？ 预期。向导验证所选后端和凭据是否存在，但在验证过程中不会强制下载模型或调用提供程序API。

发展

设置

# Install with dev dependencies
pip install -e ".[dev]"

测试与整理

# Run tests
pytest

# Format code
black .
isort .

# Linting
flake8

贡献

1. 分叉回购
2. 创建特征分支
3. 进行更改
4. 添加测试
5. 提交PR

看 代理商.md 对于建筑和 docs/IMPLEMENTATION.md 对于内部构件。

许可证

MIT许可证。看 许可证 了解详情。

______________________________________________________________________