search_files

search_files 工具可在项目多文件中执行正则表达式检索，助力 VJSP 在整个代码库中定位特定代码模式、文本及其他内容，并返回带上下文的检索结果。

参数说明

该工具支持以下入参：

path（必选）：待检索的目录路径，相对当前工作目录
regex（必选）：检索使用的正则表达式匹配模式（遵循Rust正则语法规范）
file_pattern（可选）：文件过滤的通配符模式（如 *.ts 匹配所有TypeScript文件）

功能介绍

本工具通过正则表达式对指定目录下的文件进行全域检索，为每个匹配结果展示其前后关联上下文，等效于一款可作用于整个项目结构的高性能「多文件查找」功能。

适用场景

需定位特定函数、变量的所有调用位置时
协助代码重构，需梳理代码使用模式时
需查找某一代码模式的所有出现实例时
需按规则过滤文件，在多文件中检索指定文本时

核心特性

基于高性能Ripgrep引擎，单次操作即可完成多文件全域检索
为每个匹配结果展示上下文（默认前后各1行）
支持通配符模式按文件类型过滤（如仅检索TypeScript文件）
返回匹配结果行号，便于快速定位
支持功能强大的正则表达式，实现精准检索
自动限制输出结果数量为300条，超出时进行提示
对长度超过500字符的行进行截断，并添加「[已截断...]」标记
智能合并相邻匹配结果为单个展示块，提升可读性

限制说明

对纯文本文件检索效果最佳，对图片等二进制文件无效
面对超大规模代码库时，检索性能可能下降
遵循Rust正则语法，与其他正则实现存在细微差异
不支持在压缩文件、归档文件内进行检索
上下文展示行数为固定默认值（前后各1行）
因结果合并规则，当匹配结果位置相邻时，实际展示的上下文行数可能存在差异

执行流程

调用search_files工具后，将按以下流程执行操作：

参数校验：验证必选参数path和regex的有效性
路径解析：将相对路径解析为绝对路径
检索执行：
- 基于Ripgrep（rg）引擎执行高性能文本检索
- 若指定file_pattern，则按规则过滤文件
- 收集带上下文的所有匹配结果
结果格式化：
- 为结果添加文件路径、行号及上下文并格式化展示
- 为每个匹配结果展示前后各1行上下文
- 优化结果结构，提升可读性
- 结果数量上限为300条，超出时给出提示
- 截断长度超过500字符的行
- 将相邻匹配结果合并为连续展示块

检索结果格式

检索结果包含以下内容：

每个匹配文件的相对路径（以#为前缀）
每个匹配结果的前后上下文行（默认各1行）
行号按3位补零对齐，后接|及行内容
每个匹配结果块后附带分隔线（----）

结果输出示例：

# rel/path/to/app.ts
 11 |   // 数据处理逻辑
 12 |   // 待办：实现异常处理机制
 13 |   return processedData;
----

# 本次共匹配300+条结果，仅展示前300条。如需精准检索，请优化匹配条件。

当匹配结果位置相邻时，将合并为单个展示块，而非单独展示：

# rel/path/to/auth.ts
 13 | // 业务逻辑代码
 14 | // 待办：添加参数合法性校验
 15 | function validateUser(credentials) {
 16 |   // 待办：实现接口限流策略
 17 |   return checkDatabase(credentials);
----

实际应用示例

接收到代码重构请求时，VJSP 会先检索目标函数的所有调用位置，确保重构操作的完整性
排查程序BUG时，VJSP 会检索相似代码模式，定位全代码库中的关联问题
处理技术债务时，VJSP 会检索项目中所有的TODO注释，梳理待优化点
分析项目依赖时，VJSP 会检索某一模块的所有导入语句，明确依赖关系

工具使用示例

检索所有 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>

search_files ​

参数说明 ​

功能介绍 ​

适用场景 ​

核心特性 ​

限制说明 ​

执行流程 ​

检索结果格式 ​

实际应用示例 ​

工具使用示例 ​