glob - 查找文件

概述

glob 工具用于高效查找匹配特定 glob 模式的文件（例如 src/**/*.ts、**/*.md），返回按修改时间排序的绝对路径（最新的在前）。非常适合基于文件名或路径结构快速定位文件，特别是在大型代码库中。

工具名称

• 内部名称: glob
• 显示名称: FindFiles
• 图标: 文件搜索 (FileSearch)

参数

必需参数

参数名	类型	说明
pattern	string	要匹配的 glob 模式（例如：**/*.py、docs/*.md）。

可选参数

参数名	类型	说明
path	string	要搜索的目录的绝对路径。如果省略，则搜索根目录。
case_sensitive	boolean	搜索是否区分大小写。默认为 false。
respect_git_ignore	boolean	查找文件时是否遵守 .gitignore 模式。仅在 git 仓库中可用。默认为 true。

功能说明

1. Glob 模式匹配：

   • 支持标准 glob 语法
   • 可以匹配文件名和路径
   • 支持多级目录匹配

2. 排序：

   • 按修改时间排序（最新的在前）
   • 最近修改的文件优先显示
   • 旧文件按字母顺序排列

3. 过滤：

   • 可选择是否遵守 .gitignore
   • 支持大小写敏感/不敏感搜索
   • 自动排除常见的忽略目录

4. 性能优化：

   • 高效的文件系统遍历
   • 适合大型代码库
   • 快速定位文件

Glob 模式语法

基本通配符

• *: 匹配任意字符（不包括目录分隔符）
  • 示例：*.js 匹配所有 JavaScript 文件
• **: 匹配任意字符（包括目录分隔符）
  • 示例：src/**/*.ts 匹配 src 下所有 TypeScript 文件
• ?: 匹配单个字符
  • 示例：file?.txt 匹配 file1.txt、fileA.txt 等
• [abc]: 匹配括号中的任意字符
  • 示例：file[123].txt 匹配 file1.txt、file2.txt、file3.txt
• {a,b}: 匹配大括号中的任意模式
  • 示例：*.{js,ts} 匹配所有 .js 和 .ts 文件

常用模式示例

**/*.ts          # 所有 TypeScript 文件
src/**/*.test.js # src 目录下所有测试文件
docs/*.md        # docs 目录下的 Markdown 文件
**/*config*.json # 所有包含 config 的 JSON 文件
lib/**/*.{js,ts} # lib 目录下所有 JS 和 TS 文件

使用示例

查找所有 TypeScript 文件

{
  "pattern": "**/*.ts"
}

在特定目录中查找

{
  "pattern": "*.md",
  "path": "/home/user/project/docs"
}

区分大小写搜索

{
  "pattern": "**/*.Test.ts",
  "case_sensitive": true
}

忽略 .gitignore 规则

{
  "pattern": "**/*.log",
  "respect_git_ignore": false
}

查找多种文件类型

{
  "pattern": "**/*.{js,ts,jsx,tsx}"
}

返回结果

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

• llmContent: 匹配文件的绝对路径列表
• returnDisplay: 用户友好的显示信息
• summary: 操作摘要（例如："Found 25 files matching pattern"）

返回格式

Found 3 file(s) matching "**/*.ts":
/home/user/project/src/main.ts (modified: 2024-01-15)
/home/user/project/src/utils.ts (modified: 2024-01-14)
/home/user/project/src/types.ts (modified: 2024-01-10)

错误处理

可能的错误情况：

1. 路径错误：

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

2. 模式错误：

   • 模式为空或无效
   • 模式语法错误

3. 参数错误：

   • 缺少必需参数
   • 参数类型不正确

排序规则

文件按以下规则排序：

1. 最近文件优先：

   • 在最近阈值内修改的文件（默认 30 天）
   • 按修改时间从新到旧排序

2. 旧文件字母排序：

   • 超过最近阈值的文件
   • 按路径字母顺序排序

性能考虑

1. 大型代码库：

   • 工具针对大型代码库优化
   • 使用高效的文件系统遍历

2. 模式复杂度：

   • 简单模式（如 *.js）比复杂模式更快
   • ** 通配符会递归搜索所有子目录

3. 忽略规则：

   • 遵守 .gitignore 可以提高性能
   • 自动跳过常见的大型目录（node_modules 等）

注意事项

1. 路径格式：返回的路径始终是绝对路径
2. 符号链接：默认不跟随符号链接
3. 隐藏文件：默认包含隐藏文件（以 . 开头）
4. 权限：需要有读取目录的权限

与其他工具的区别

• vs list_directory: glob 支持递归搜索和模式匹配，list_directory 只列出单个目录
• vs search_file_content: glob 基于文件名/路径搜索，search_file_content 基于文件内容搜索

相关工具

• list_directory: 列出目录内容
• search_file_content: 搜索文件内容
• read_file: 读取文件
• read_many_files: 批量读取多个文件