跳到主要内容

codebase_search

实验性功能

codebase_search 工具是实验性功能 代码库索引 的一部分。该功能正在积极开发中，可能在未来的版本中有重大变化。它需要额外的设置，包括嵌入提供程序和向量数据库。

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

参数​

该工具接受以下参数：

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

功能​

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

使用场景​

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

主要特性​

  • 语义理解：通过含义而非精确关键字匹配查找代码
  • 跨项目搜索：搜索整个索引代码库，而不仅仅是打开的文件
  • 上下文结果：返回包含文件路径和行号的代码片段，便于导航
  • 相似度评分：结果按相关性排序，带有相似度分数（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）
  • 行范围：代码块的起始和结束行号
  • 代码块：与查询匹配的实际代码内容

使用示例​

当 Kilo Code 实现新功能时，搜索 "身份验证中间件" 以在编写新代码之前了解现有模式。 当调试问题时，Kilo Code 搜索 "API 调用中的错误处理" 以查找代码库中相关的错误模式。 当重构代码时，Kilo Code 搜索 "数据库事务模式" 以确保所有数据库操作的一致性。 当加入新代码库时，Kilo Code 搜索 "配置加载" 以了解应用程序如何引导。

使用示例​

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

<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>
Is this documentation incorrect or incomplete? Report an issue on GitHub