search_file_content - 搜索文件内容

概述

search_file_content 工具用于在指定目录（或当前工作目录）的文件内容中搜索正则表达式模式。可以通过 glob 模式过滤文件。返回包含匹配项的行，以及文件路径和行号。

工具名称

• 内部名称: search_file_content
• 显示名称: SearchFileContent
• 图标: 正则表达式 (Regex)

参数

必需参数

参数名	类型	说明
pattern	string	要在文件内容中搜索的正则表达式模式（例如：function\s+myFunction、import\s+\{.*\}\s+from\s+.*）。

可选参数

参数名	类型	说明
path	string	要搜索的目录的绝对路径。如果省略，则搜索当前工作目录。
include	string[]	用于过滤要搜索的文件的 glob 模式数组（例如：['*.js', '*.ts']、['*.{ts,tsx}', 'src/**']）。每个模式单独搜索，结果合并。如果省略，则搜索所有文件（遵守潜在的全局忽略规则）。
limit	number	每个文件模式返回的最大结果数（默认：20）。帮助防止搜索结果过多。
totalLimit	number	所有模式的最大总结果数（默认：100）。无论模式数量如何，提供总体结果限制。
offset	number	要跳过的结果数，用于分页（默认：0）。与 limit 一起使用实现分页：offset=0,limit=20 表示第 1 页，offset=20,limit=20 表示第 2 页。
file_filtering_options	object	文件过滤选项。
file_filtering_options.respect_git_ignore	boolean	是否遵守 .gitignore / VCS 忽略文件（默认：项目设置，通常为 true）。设置为 false 可搜索被忽略的文件。
file_filtering_options.respect_sii_ignore	boolean	是否跳过 .siiignore 匹配的路径（默认：项目设置）。
file_filtering_options.use_default_excludes	boolean	为 true 时，跳过常见的大型文件夹（如 node_modules）。当需要有意搜索它们时设置为 false。

功能说明

1. 正则表达式搜索：

   • 支持完整的正则表达式语法
   • 区分大小写匹配
   • 可以搜索复杂的模式

2. 文件过滤：

   • 使用 glob 模式指定要搜索的文件
   • 支持多个 include 模式
   • 自动排除常见的大型目录

3. 分页支持：

   • 使用 limit 和 offset 实现分页
   • 防止结果过多
   • 支持逐步浏览结果

4. 性能优化：

   • 优先使用原生 ripgrep (rg) 命令
   • 回退到 JavaScript 实现
   • 智能文件过滤

正则表达式语法

支持标准的正则表达式语法：

• .: 匹配任意字符
• *: 匹配前面的元素零次或多次
• +: 匹配前面的元素一次或多次
• ?: 匹配前面的元素零次或一次
• \s: 匹配空白字符
• \d: 匹配数字
• \w: 匹配单词字符
• [abc]: 匹配括号中的任意字符
• (a|b): 匹配 a 或 b
• ^: 匹配行首
• $: 匹配行尾

使用示例

基本搜索

{
  "pattern": "function\\s+\\w+"
}

在特定文件类型中搜索

{
  "pattern": "import.*from",
  "include": ["*.ts", "*.tsx"]
}

在特定目录中搜索

{
  "pattern": "TODO|FIXME",
  "path": "/home/user/project/src"
}

分页搜索

{
  "pattern": "class\\s+\\w+",
  "limit": 10,
  "offset": 0
}

搜索多种文件类型

{
  "pattern": "console\\.log",
  "include": ["**/*.js", "**/*.ts"]
}

忽略默认排除规则

{
  "pattern": "error",
  "file_filtering_options": {
    "use_default_excludes": false
  }
}

返回结果

工具返回一个包含以下字段的对象：

• llmContent: 匹配结果的详细列表
• returnDisplay: 用户友好的显示信息
• summary: 操作摘要

匹配结果格式

{
  matches: [
    {
      filePath: string;    // 文件路径
      lineNumber: number;  // 行号（从 1 开始）
      line: string;        // 匹配的行内容
    }
  ],
  metadata: {
    totalMatches: number;        // 总匹配数
    returnedMatches: number;     // 返回的匹配数
    hasMore: boolean;            // 是否有更多结果
    currentOffset: number;       // 当前偏移量
    patternsSearched: string[];  // 搜索的模式
    searchSummary: string;       // 搜索摘要
    isEstimate: boolean;         // 是否为估计值
    searchedPath: string;        // 搜索的路径
  }
}

错误处理

可能的错误情况：

1. 模式错误：

   • 正则表达式语法错误
   • 模式为空

2. 路径错误：

   • 搜索路径不存在
   • 搜索路径不在项目根目录内

3. 参数错误：

   • limit 或 offset 为负数
   • 参数类型不正确

性能考虑

1. 使用 ripgrep：

   • 如果系统安装了 rg，工具会自动使用它
   • rg 比 JavaScript 实现快得多

2. 文件过滤：

   • 使用 include 模式限制搜索范围
   • 启用 use_default_excludes 跳过大型目录

3. 结果限制：

   • 使用 limit 限制每次返回的结果数
   • 使用 totalLimit 限制总结果数

默认排除目录

默认情况下，以下目录会被排除：

• .git
• node_modules
• bower_components
• .svn
• .hg
• dist
• build
• coverage

可以通过设置 use_default_excludes: false 来搜索这些目录。

注意事项

1. 正则表达式转义：在 JSON 中需要双重转义（例如：\\s 表示空白字符）
2. 性能：搜索大型代码库可能需要一些时间
3. 二进制文件：自动跳过二进制文件
4. 大文件：非常大的文件可能被跳过或部分搜索

相关工具

• glob: 基于文件名查找文件
• read_file: 读取文件内容
• read_many_files: 批量读取多个文件
• list_directory: 列出目录内容