Skip to main content

代码库索引

代码库索引通过使用 AI 嵌入创建语义搜索索引，彻底改变了 Roo Code 理解项目的方式。它不再依赖精确的文本匹配搜索，而是理解查询的含义，帮助 Roo 找到相关的代码，即使你不知道具体的函数名或文件位置。


功能说明​

启用后，索引系统会：

  1. 解析你的代码，使用 Tree-sitter 识别语义块（函数、类、方法）
  2. 创建嵌入，使用 AI 模型将每个代码块转换为向量
  3. 存储向量到 Qdrant 数据库，实现快速相似性搜索
  4. 提供 codebase_search 工具，供 Roo 进行智能代码发现

这使得你可以使用自然语言查询，如“用户认证逻辑”或“数据库连接处理”，在你的整个项目中找到相关代码。

快速开始指南​

💰 完全免费的设置方案

你可以通过以下方式免费设置代码库索引：

  • Qdrant Cloud（免费套餐）或 Docker Qdrant（完全免费）
  • Google Gemini（目前免费）

这让你无需任何订阅费用即可获得专业级的语义搜索！

步骤 1：选择你的设置方案​

启用代码库索引前，你需要两个组件：

  1. 嵌入提供商 - 将代码转换为可搜索向量
  2. 向量数据库 - 存储和搜索这些向量

步骤 2：设置 Qdrant（向量数据库）​

选项 A：云端设置（推荐用于快速开始）- 免费​

  1. 在 Qdrant Cloud 注册（提供免费套餐）
  2. 创建一个集群
  3. 复制你的 URL 和 API 密钥

选项 B：本地设置 - 免费​

使用 Docker：

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant

使用 Docker Compose：

services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
    volumes:
      - qdrant_storage:/qdrant/storage
volumes:
  qdrant_storage:

步骤 3：设置嵌入提供商​

Google Gemini 设置（推荐）- 免费​

  1. 从 Google AI Studio 获取 API 密钥（目前免费）
  2. 在 Roo Code 设置中：
    • 提供商：Google Gemini
    • API 密钥：你的 Google AI Studio 密钥
其他提供商可用

虽然本指南重点介绍 Google Gemini（因为它目前免费），Roo Code 也支持 OpenAI、Ollama 和兼容 OpenAI 的提供商。你可以在配置下拉菜单中探索这些选项。

步骤 4：保存​

  1. 点击 保存 并 开始索引

状态指示器将显示：

  • 黄色（索引中）：正在处理文件
  • 绿色（已索引）：准备就绪，可进行搜索
  • 红色（错误）：查看故障排除部分

管理和配置索引器​

你可以直接从 Roo Code 聊天界面监控状态并管理代码库索引器的所有配置。

状态图标​

在聊天输入框的右下角，你会找到代码库索引状态图标。这个图标提供了索引器当前状态的快速概览。

代码库索引状态图标

图标颜色表示状态：

  • 🟢 绿色：已索引。索引已更新并准备好搜索。
  • 🟡 黄色：索引中。系统正在主动处理文件。仍可执行搜索，但结果可能不完整。
  • 🔴 红色：错误。发生问题（例如，无法连接到 Qdrant 或嵌入提供商）。查看故障排除部分获取帮助。
  • ⚪ 灰色：待机。索引器正在等待配置或已被禁用。

多文件夹工作区：在多文件夹工作区中，每个文件夹维护自己的索引状态和配置。状态图标反映所有工作区文件夹的组合状态。

配置弹出框​

点击状态图标会打开主配置弹出框。在这里，你可以查看详细状态并管理所有设置。

代码库索引弹出框
  • 状态：显示当前状态的详细消息，例如“已索引 - 文件监视器已启动”或正在进行扫描的进度。
  • 设置：包含连接到嵌入提供商和向量数据库的主要字段。
  • 高级配置：允许你微调搜索参数，如相似度阈值。
  • 清除索引数据：删除 Qdrant 集合中的所有数据并清除本地文件缓存。当你想从头开始重新索引整个项目时使用。此操作无法撤销。
  • 保存：应用你的配置更改。如果更改了关键设置（如 API 密钥或模型），索引器将自动重启。

详细配置字段​

本指南解释了配置弹出框中可用的每个设置。

代码库索引配置详情

设置字段​

  • 嵌入提供商

    • 用途：选择你的 AI 嵌入源。
    • 行为：此下拉菜单决定显示哪些配置字段。你的选项是 OpenAI、Google Gemini、Ollama 和 OpenAI Compatible。

  • API 密钥（用于 OpenAI、Gemini、OpenAI Compatible）

    • 用途：用于验证你选择的提供商的密钥。
    • 行为：此输入对所有基于云的提供商都是必需的，并安全存储在你的 VS Code 密钥存储中。

  • 基础 URL（用于 Ollama、OpenAI Compatible）

    • 用途：连接到提供商 API 的端点。
    • 行为：对于 Ollama，这通常是 http://localhost:11434。对于 OpenAI Compatible 提供商（如 Azure），这是完整的部署 URL。

  • 模型

    • 用途：选择你想要使用的特定嵌入模型。
    • 行为：可用模型列表根据所选提供商而变化。模型的向量维度（例如 1536 dimensions）会显示出来，因为更改维度需要完全重新索引。

  • Qdrant URL

    • 用途：你的 Qdrant 向量数据库的连接端点。
    • 行为：这必须是指向你的本地或基于云的 Qdrant 实例的有效 URL（例如 http://localhost:6333）。

  • Qdrant API 密钥

    • 用途：用于安全 Qdrant 实例的身份验证密钥。
    • 行为：此字段是可选的，仅当你的 Qdrant 部署需要 API 密钥时才应使用。

高级配置字段​

  • 搜索分数阈值

    • 用途：控制代码片段被视为匹配所需的最小相似度分数。
    • 行为：使用滑块设置 0.0 到 1.0 之间的值。较低的值返回更多（但可能相关性较低）的结果，而较高的值返回更少、更精确的结果。
    • 推荐设置：
      • 低（0.15-0.3）：更广泛的结果，适合探索
      • 中（0.4-0.5）：平衡精度和召回率（默认：0.4）
      • 高（0.6-0.8）：仅精确匹配

  • 最大搜索结果

    • 用途：设置单个 codebase_search 返回的最大代码片段数。
    • 行为：使用滑块调整限制。这有助于控制提供给 AI 的上下文量。

主要优势​

  • 语义搜索：通过含义而非仅关键字查找代码
  • 增强的 AI 理解：Roo 可以更好地理解和处理你的代码库
  • 跨项目发现：在所有文件中搜索，而不仅仅是打开的文件
  • 模式识别：定位相似的实现和代码模式

文件处理方式​

智能代码解析​

系统使用复杂的解析策略：

  1. 优先使用 Tree-sitter：对于支持的语言，使用 AST 解析识别语义代码块（函数、类、方法）
  2. Markdown 支持：通过将标题作为语义入口点来索引 Markdown 文件
  3. 智能回退：对于不支持的文件类型，回退到基于行的分块

块大小：

  • 最小值：100 字符
  • 最大值：1,000 字符
  • 大型函数在逻辑边界处智能分割

文件过滤​

索引器尊重你项目的忽略模式：

  • 匹配 .gitignore 模式的文件
  • 匹配 .rooignore 模式的文件
  • 二进制文件和图像
  • 大于 1MB 的文件

重要：确保你的 .gitignore 包含常见的依赖文件夹，如 node_modules、vendor、target 等，因为系统完全依赖这些模式进行过滤。

增量更新​

  • 文件监视：实时监控工作区中的更改
  • 智能更新：仅重新处理修改的文件
  • 分支感知：自动处理 Git 分支切换
  • 基于哈希的缓存：避免重新处理未更改的内容
  • 多文件夹工作区：多文件夹工作区中的每个文件夹维护自己的索引，具有独立的设置和状态

最佳实践​

编写有效的查询​

而不是搜索确切的语法：

  • ❌ const getUser
  • ✅ function to fetch user from database

使用自然语言描述：

  • "authentication middleware"
  • "error handling for API requests"
  • "database connection setup"

安全考虑​

  • API 密钥：安全存储在 VS Code 的加密存储中
  • 代码隐私：只有小代码片段被发送用于嵌入
  • 本地处理：所有解析都在本地进行
  • 访问控制：尊重文件权限和忽略模式

故障排除​

连接问题​

"连接 Qdrant 失败"

  • 确保 Qdrant 正在运行（docker ps 检查）
  • 验证 URL 匹配（默认：http://localhost:6333）
  • 检查防火墙/网络策略
  • 对于云实例，确认 URL 和 API 密钥

"无效的 API 密钥" 或 "401 未授权"

  • 仔细检查你的 API 密钥是否正确
  • 确保密钥具有必要的权限
  • 对于 Ollama，验证服务正在运行

API 密钥格式错误（"ByteString 转换"）​

  • 症状：在索引或保存设置期间出现 "ByteString 转换" 错误
  • 可能原因：你的嵌入提供商 API 密钥包含无效/特殊字符或隐藏的空白字符
  • 解决方法：
    • 从你的提供商仪表板重新生成新的 API 密钥
    • 再次粘贴密钥，确保没有前导/尾随空格或隐藏字符
    • 如果密钥无效，Roo 会显示清晰的验证消息

模型问题​

"未找到模型"

  • 对于 Google Gemini：确保模型名称正确（例如 text-embedding-004）
  • 对于其他提供商：查阅其文档了解可用模型和正确的命名

索引问题​

"卡在错误状态"

  1. 首先检查连接问题
  2. 在设置中点击 "清除索引并重新索引"
  3. 这可以解决损坏的缓存或集合问题

"索引耗时过长"

  • 对于大型代码库（10k+ 文件）是正常的
  • 检查 .gitignore 是否包含大型目录
  • 考虑在 .rooignore 中添加模式

使用搜索功能​

索引完成后，Roo 可以使用 codebase_search 工具：

示例自然语言查询：

  • "用户认证是如何处理的？"
  • "数据库连接设置"
  • "错误处理模式"
  • "API 端点定义"
  • "组件状态管理"

该工具提供：

  • 相关代码片段
  • 带行号的文件路径
  • 相似度分数
  • 直接导航链接

隐私与数据安全​

你的代码保持私密：

  • 只有小代码块（100-1000 字符）被发送用于嵌入
  • 嵌入是单向数学表示
  • 本地解析意味着完整文件永远不会离开你的机器
  • 使用 Ollama 实现完全离线操作

数据存储：

  • 向量存储在你选择的 Qdrant 实例中
  • 你控制数据的位置（本地/云端）
  • 易于删除：只需清除索引

当前限制​

  • 文件大小：每文件最大 1MB
  • 外部依赖：需要嵌入提供商 + Qdrant
  • 语言支持：在支持 Tree-sitter 的语言上效果最佳

未来增强​

计划的改进：

  • 更多嵌入提供商
  • 多工作区索引
  • 增强的过滤选项
  • 团队协作功能
  • VS Code 原生搜索集成
  • 增量重新索引优化