search_files

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

参数

工具接受以下参数：

path (必填): 要搜索的目录路径，相对于当前工作区目录。搜索范围仅限于工作区内。
regex (必填): 要搜索的正则表达式模式（使用Rust正则表达式语法）
file_pattern (可选): 用于过滤文件的glob模式（例如'*.ts'表示仅搜索TypeScript文件）

功能说明

该工具使用正则表达式在指定目录中跨文件搜索，显示每个匹配项及其上下文内容。相当于一个强大的"在文件中查找"功能，可在整个项目结构中工作。

使用场景

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

主要特性

使用高性能Ripgrep在单次操作中跨多个文件搜索
显示每个匹配项的上下文（默认前后各1行）
使用glob模式按文件类型过滤（例如仅TypeScript文件）
提供行号便于参考
使用强大的正则表达式模式进行精确搜索
自动限制输出为300个结果并给出通知
对超过500字符的行进行截断并标记为"[truncated...]"
智能地将相邻匹配合并为单个块以提高可读性

限制

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

工作原理

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

参数验证：验证必需的path和regex参数
路径解析：将相对路径解析为绝对路径
搜索执行：
- 使用Ripgrep(rg)进行高性能文本搜索
- 应用文件模式过滤（如指定）
- 收集匹配项及其上下文
结果格式化：
- 使用文件路径、行号和上下文格式化结果
- 默认显示匹配项前后各1行上下文
- 结构化输出以提高可读性
- 限制最多显示300个匹配结果并给出通知
- 截断超过500字符的行
- 将相邻匹配合并为连续块

搜索结果格式

搜索结果包括：

每个匹配文件的相对路径（以#开头）
每个匹配项前后的上下文行（默认1行）
3位行号填充后跟|和行内容
每个匹配组后的分隔线（----）

示例输出格式：

# rel/path/to/app.ts
 11 |   // 一些处理逻辑
 12 |   // TODO: 实现错误处理
 13 |   return processedData;
----

# 显示300+结果中的前300个。如需更精确结果请使用更具体的搜索条件。

当匹配项彼此接近时，它们会被合并为单个块而非单独显示：

# rel/path/to/auth.ts
| // 一些代码
| // TODO: 添加适当的验证
| function validateUser(credentials) {
|   // TODO: 实现速率限制
|   return checkDatabase(credentials);
----

使用示例

当要求重构函数时，Roo首先搜索该函数的所有使用位置以确保全面更改
当调查错误时，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>

参数​

功能说明​

使用场景​

主要特性​

限制​

工作原理​

搜索结果格式​

使用示例​

用法示例​

参数