Lzh on GitHub
需要设置
codebase_search 工具是 代码库索引 功能的一部分。它需要额外的设置，包括嵌入提供程序和向量数据库。

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

参数

该工具接受以下参数：

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

功能与使用时机

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

它在以下情况中使用：

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

主要功能

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

要求

本工具仅在代码库索引功能正确配置后才可用：

  • 功能已配置：必须在设置中配置代码库索引。
  • 嵌入提供程序：需要 OpenAI API 密钥或 Ollama 配置。
  • 向量数据库：Qdrant 实例正在运行且可访问。
  • 索引状态：代码库必须已建立索引（状态为“Indexed”或“Indexing”）。

局限性

  • 需要配置：依赖外部服务（嵌入提供程序 + 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>user authentication and password validation</query>
</codebase_search>
  • 好的：功能聚焦
<codebase_search>
<query>database connection pool setup</query>
</codebase_search>
  • 好的：面向问题
<codebase_search>
<query>error handling for API requests</query>
</codebase_search>
  • 效果较差：过于笼统
<codebase_search>
<query>function</query>
</codebase_search>

效果好的查询类型

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

目录范围限定

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

  • 在 API 模块中搜索：
<codebase_search>
<query>endpoint validation middleware</query>
<path>src/api</path>
</codebase_search>
  • 在测试文件中搜索：
<codebase_search>
<query>mock data setup patterns</query>
<path>tests</path>
</codebase_search>
  • 搜索指定功能目录：
<codebase_search>
<query>component state management</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）。
  • 行范围：代码块的起始和结束行号。
  • 代码块：与您的查询匹配的实际代码内容。

使用示例

  • 在实现新功能时，Roo 会搜索“身份验证中间件”，以在编写新代码之前了解现有模式。
  • 在调试问题时，Roo 会搜索“API 调用中的错误处理”，以在整个代码库中查找相关的错误模式。
  • 在重构代码时，Roo 会搜索“数据库事务模式”，以确保所有数据库操作的一致性。
  • 在熟悉新代码库时，Roo 会搜索“配置加载”以了解应用程序如何启动。

用法示例

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

<codebase_search>
  <query>user login and authentication logic</query>
</codebase_search>

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

<codebase_search>
  <query>database connection and query execution</query>
  <path>src/data</path>
</codebase_search>

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

<codebase_search>
  <query>HTTP error responses and exception handling</query>
  <path>src/api</path>
</codebase_search>

搜索测试工具和模拟设置：

<codebase_search>
  <query>test setup and mock data creation</query>
  <path>tests</path>
</codebase_search>

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

<codebase_search>
  <query>environment variables and application configuration</query>
</codebase_search>