Lzh on GitHub

search_files

search_files 工具用于在项目工作区内的多个文件中执行正则表达式搜索。出于安全考虑，它无法搜索当前工作区目录之外的区域。它通过提供上下文结果，帮助 Roo 在您的代码库中定位特定的代码模式、文本或其他内容。

search_files 工具用于在项目工作区内的多个文件中执行正则表达式搜索。出于安全考虑，它无法搜索当前工作区目录之外的区域。它通过提供上下文结果，帮助 Roo 在您的代码库中定位特定的代码模式、文本或其他内容。

参数

该工具接受以下参数：

  • path（必需）：要搜索的目录路径，相对于当前工作区目录。搜索仅限于工作区内。
  • regex（必需）：要搜索的正则表达式模式（使用 Rust 正则表达式语法）。
  • file_pattern（可选）：用于过滤文件的全局模式（例如，'*.ts' 用于 TypeScript 文件）。

功能与使用时机

该工具使用正则表达式在指定目录的文件中进行搜索，并显示每个匹配项及其周围的上下文。这就像一个功能强大的 “在文件中查找” 功能，可用于整个项目结构。

它在以下情况中使用：

  • 当 Roo 需要查找特定函数或变量的使用位置时。
  • 当 Roo 协助重构并需要了解使用模式时。
  • 当 Roo 需要定位特定代码模式的所有实例时。
  • 当 Roo 需要在多个文件中搜索文本并具有过滤功能时。

主要功能

  • 使用高性能的 Ripgrep 在一次操作中搜索多个文件。
  • 显示每个匹配项周围的上下文（前一行和后一行）。
  • 使用 glob 模式按类型过滤文件（例如，仅限 TypeScript 文件）。
  • 提供行号，便于参考。
  • 使用强大的正则表达式模式进行精确搜索。
  • 自动将输出限制为 300 个结果并提供通知。
  • 将超过 500 个字符的行截断，并带有“[truncated...]”标记。
  • 智能地将附近的匹配项合并到单个块中，以提高可读性。

局限性

  • 文件类型：最适合处理基于文本的文件（对图像等二进制文件无效）。
  • 性能：在极其庞大的代码库中，性能可能会下降。
  • 正则表达式语法：使用 Rust 正则表达式语法，可能与其他正则表达式实现略有不同。
  • 文件格式：无法搜索压缩文件或归档文件内的内容。
  • 上下文大小：默认上下文大小是固定的（匹配项的前后各 1 行）。
  • 结果分组：由于结果分组，当匹配项彼此靠近时，可能会显示不同的上下文大小。
  • 安全限制：出于安全考虑，搜索严格限制在当前工作区内，无法访问父目录或文件系统上的其他位置。

工作原理

当调用 search_files 工具时，它会遵循以下流程：

  1. 参数验证：验证所需的 path 和 regex 参数
  2. 路径解析：将相对路径解析为绝对路径
  3. 搜索执行：
    • 使用 Ripgrep（rg）进行高性能文本搜索
    • 如果指定，应用文件模式过滤
    • 收集匹配项及其周围上下文
  4. 结果格式化：
    • 将结果格式化为文件路径、行号和上下文
    • 在每个匹配项前后显示 1 行上下文
    • 结构化输出以便易于阅读
    • 将结果限制为最多 300 个匹配项并提供通知
    • 截断超过 500 个字符的行
    • 将相邻匹配合并为连续块

搜索结果格式

搜索结果包括：

  • 文件路径：每个匹配文件的相对路径（以 # 为前缀）。
  • 上下文行：每个匹配项之前和之后（默认各 1 行）的上下文行。
  • 行号：行号填充至 3 个空格，后跟 | 和行内容。
  • 分隔线：每个匹配组后有分隔线（----）。

示例输出格式：

# rel/path/to/app.ts
 11 |   // Some processing logic here
 12 |   // TODO: Implement error handling
 13 |   return processedData;
----

# Showing first 300 of 300+ results. Use a more specific search if necessary.

当匹配项彼此接近时，它们会合并成一个单独的块，而不是显示为单独的结果：

# rel/path/to/auth.ts
 13 | // Some code here
 14 | // TODO: Add proper validation
 15 | function validateUser(credentials) {
 16 |   // TODO: Implement rate limiting
 17 |   return checkDatabase(credentials);
----

使用示例

  • 重构：Roo 首先搜索函数的所有使用位置，以确保全面的更改。
  • 调查 Bug：Roo 搜索类似的模式，以识别代码库中的相关问题。
  • 处理技术债务：Roo 定位项目中所有 TODO 注释。
  • 分析依赖项：Roo 查找特定模块的所有导入。

用法示例

在所有 JavaScript 文件中搜索 TODO 注释：

<search_files>
  <path>src</path>
  <regex>TODO|FIXME</regex>
  <file_pattern>*.js</file_pattern>
</search_files>

查找特定函数的所有用法：

<search_files>
  <path>.</path>
  <regex>function\s+calculateTotal</regex>
  <file_pattern>*.{js,ts}</file_pattern>
</search_files>

在整个项目中搜索特定导入模式：

<search_files>
  <path>.</path>
  <regex>import\s+.*\s+from\s+['"]@components/</regex>
</search_files>