跳转到主要内容

codebase_search

需要设置

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

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

参数​

该工具接受以下参数：

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

作用​

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

何时使用？​

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

主要功能​

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

使用示例​

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

用法示例​

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

<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>