Skip to main content

codebase_search

需要配置

codebase_search 工具是 代码库索引 功能的一部分。需要额外配置，包括嵌入提供者和向量数据库。

codebase_search 工具使用 AI 嵌入技术在您的整个代码库中执行语义搜索。与传统的基于文本的搜索不同，它理解查询的含义，即使没有精确匹配关键词也能找到相关代码。

参数​

该工具接受以下参数：

  • query（必需）：描述您要查找内容的自然语言搜索查询
  • path（可选）：目录路径，将搜索范围限制在代码库的特定部分

功能说明​

此工具使用语义相似性而非精确文本匹配在索引的代码库中搜索。它找到与您的查询在概念上相关的代码块，即使它们不包含您搜索的确切单词。结果包括带有文件路径、行号和相似度分数的相关代码片段。

使用场景​

  • 当 Roo 需要在项目中查找与特定功能相关的代码时
  • 当寻找实现模式或类似代码结构时
  • 当搜索错误处理、身份验证或其他概念性代码模式时
  • 当探索不熟悉的代码库以了解功能如何实现时
  • 当查找可能受更改或重构影响的相关代码时

主要特性​

  • 语义理解：通过含义而非精确关键词匹配查找代码
  • 跨项目搜索：在索引的整个代码库中搜索，而不仅限于打开的文件
  • 上下文结果：返回带有文件路径和行号的代码片段，便于导航
  • 相似度评分：结果按相关性排序，附带相似度分数（0-1 范围）
  • 范围过滤：可选的路径参数，将搜索限制在特定目录
  • 智能排序：结果按与查询的语义相关性排序
  • UI 集成：结果显示语法高亮和导航链接
  • 性能优化：基于向量的快速搜索，支持配置结果限制

要求​

此工具仅在正确配置代码库索引功能时可用：

  • 功能已配置：代码库索引必须在设置中配置
  • 嵌入提供者：需要 OpenAI API 密钥或 Ollama 配置
  • 向量数据库：Qdrant 实例正在运行且可访问
  • 索引状态：代码库必须已索引（状态："已索引" 或 "索引中"）

限制​

  • 需要配置：依赖外部服务（嵌入提供者 + Qdrant）
  • 索引依赖：仅搜索已索引的代码块
  • 结果限制：每次搜索最多 50 个结果以保持性能
  • 相似度阈值：仅返回超过相似度阈值的结果（默认：0.4，可配置）
  • 文件大小限制：限于 1MB 以下且成功索引的文件
  • 语言支持：效果取决于 Tree-sitter 语言支持

工作原理​

调用 codebase_search 工具时，它遵循以下流程：

  1. 可用性验证：

    • 验证 CodeIndexManager 是否可用且已初始化
    • 确认代码库索引在设置中已启用
    • 检查索引是否正确配置（API 密钥、Qdrant URL）
    • 验证当前索引状态允许搜索

  2. 查询处理：

    • 获取您的自然语言查询并生成嵌入向量
    • 使用与索引配置相同的嵌入提供者（OpenAI 或 Ollama）
    • 将查询的语义含义转换为数学表示

  3. 向量搜索执行：

    • 在 Qdrant 向量数据库中搜索相似的代码嵌入
    • 使用余弦相似度找到最相关的代码块
    • 应用最小相似度阈值（默认：0.4，可配置）过滤结果
    • 将结果限制为 50 个匹配项以优化性能

  4. 路径过滤（如指定）：

    • 过滤结果，仅包含指定目录路径内的文件
    • 使用标准化路径比较进行准确过滤
    • 在过滤范围内保持相关性排序

  5. 结果处理和格式化：

    • 将绝对文件路径转换为工作区相对路径
    • 构建结果结构，包括文件路径、行范围、相似度分数和代码内容
    • 格式化输出，同时支持 AI 消费和 UI 显示（带语法高亮）

  6. 双重输出格式：

    • AI 输出：结构化文本格式，包含查询、文件路径、分数和代码块
    • UI 输出：JSON 格式，带语法高亮和导航功能

搜索查询最佳实践​

有效的查询模式​

良好：概念性和具体性

<codebase_search>
<query>用户身份验证和密码验证</query>
</codebase_search>

良好：功能导向

<codebase_search>
<query>数据库连接池设置</query>
</codebase_search>

良好：问题导向

<codebase_search>
<query>API 请求的错误处理</query>
</codebase_search>

效果较差：过于宽泛

<codebase_search>
<query>函数</query>
</codebase_search>

有效查询类型​

  • 功能描述："文件上传处理"、"电子邮件验证逻辑"
  • 技术模式："单例模式实现"、"工厂方法使用"
  • 领域概念："用户资料管理"、"支付处理工作流"
  • 架构组件："中间件配置"、"数据库迁移脚本"

目录范围限定​

使用可选的 path 参数将搜索集中在代码库的特定部分：

在 API 模块中搜索：

<codebase_search>
<query>端点验证中间件</query>
<path>src/api</path>
</codebase_search>

在测试文件中搜索：

<codebase_search>
<query>模拟数据设置模式</query>
<path>tests</path>
</codebase_search>

在特定功能目录中搜索：

<codebase_search>
<query>组件状态管理</query>
<path>src/components/auth</path>
</codebase_search>

结果解读​

相似度分数​

  • 0.8-1.0：高度相关匹配，很可能正是您要找的
  • 0.6-0.8：良好匹配，具有较强的概念相似性
  • 0.4-0.6：可能相关，但可能需要审查
  • 低于 0.4：被过滤为过于不相似

结果结构​

每个搜索结果包括：

  • 文件路径：到包含匹配项的文件的工作区相对路径
  • 分数：表示相关性的相似度分数（0.4-1.0）
  • 行范围：代码块的起始和结束行号
  • 代码块：与您的查询匹配的实际代码内容

使用示例​

在整个项目中搜索身份验证相关代码：

<codebase_search>
<query>用户登录和身份验证逻辑</query>
</codebase_search>

在特定目录中查找数据库相关代码：

<codebase_search>
<query>数据库连接和查询执行</query>
<path>src/data</path>
</codebase_search>

在 API 代码中查找错误处理模式：

<codebase_search>
<query>HTTP 错误响应和异常处理</query>
<path>src/api</path>
</codebase_search>

查找测试工具和模拟设置：

<codebase_search>
<query>测试设置和模拟数据创建</query>
<path>tests</path>
</codebase_search>

查找配置和环境设置代码：

<codebase_search>
<query>环境变量和应用程序配置</query>
</codebase_search>