# `Glob` 工具

一个快速的**文件名/路径匹配**工具。它回答这个问题：*"哪些文件存在，其路径匹配此模式？"*

Glob 搜索文件**名称和路径**——它**不**查看文件内部。（它的兄弟工具 `Grep` 搜索文件**内容**。见 `grep-tool.md`。）

---

## 何时使用

- 按名称或扩展名定位文件（例如所有 `*.test.ts` 文件）。
- 在深入之前发现代码库的结构/布局。
- 查找匹配某个模式的最近修改的文件。
- 任何时候你想在终端中使用 `find . -name ...` 或 shell 通配符。

> **重要提示：** 对于文件发现，优先使用此工具，而非通过 Bash 工具运行 `find` 或 `ls`。
> 它更快，适用于任何规模的代码库，并以有用的方式排序返回结果。

---

## 参数

| 参数 | 类型   | 必需 | 描述                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `pattern` | string | **是**  | 用于匹配文件的 glob 模式（例如 `**/*.js`、`src/**/*.{ts,tsx}`）。               |
| `path`    | string | 否       | 搜索的目录。默认为当前工作目录。**不要**传递 `undefined` 或 `null` 来表示"当前目录"——直接省略该参数即可。 |

---

## Glob 模式语法

Glob 模式比正则表达式更简单。最有用的标记：

| 标记       | 含义                                                                 |
| ----------- | ----------------------------------------------------------------------- |
| `*`         | 匹配任意字符序列，**除了**路径分隔符 (`/`)。        |
| `**`        | 递归匹配任意数量的目录（包括零个）。        |
| `?`         | 恰好匹配一个字符。                                          |
| `{a,b,c}`   | 匹配任何逗号分隔的选项（花括号展开）。      |
| `[abc]`     | 匹配集合中的一个字符。                                     |

### 常见模式

- `*.md` — 搜索目录中的每个 Markdown 文件（仅顶级）。
- `**/*.md` — 任意深度下的每个 Markdown 文件。
- `src/**/*.js` — `src/` 下任意位置的所有 `.js` 文件。
- `**/*.{ts,tsx}` — 所有 TypeScript 和 TSX 文件，递归。
- `**/test_*.py` — 所有以 `test_` 开头的 Python 文件，任意深度。
- `?[0-9]*.log` — 第二个字符是数字的日志文件。

---

## 输出

- 返回**匹配文件路径的列表**。
- 结果按**修改时间排序**，最近修改的排在最前。这很方便：你刚刚接触的文件（或与最近工作最相关的文件）往往出现在顶部。
- 如果没有任何匹配，返回空结果（不是错误）。

---

## 示例

**项目中所有的 TypeScript 文件：**
```json
{ "pattern": "**/*.ts" }
```

**特定目录下的测试文件：**
```json
{
  "pattern": "**/*.test.{ts,tsx}",
  "path": "packages/web/src"
}
```

**仓库根目录的配置文件：**
```json
{ "pattern": "*.{json,yml,yaml,toml}" }
```

**每个 README，无论深度：**
```json
{ "pattern": "**/README.md" }
```

---

## Glob vs. Grep — 用哪一个？

| 你想要…                                      | 使用      |
| ------------------------------------------------- | -------- |
| 查找**命名**是某种模式的文件                  | `Glob`   |
| 查找**包含**某些文本的文件            | `Grep`   |
| 列出所有 `*.py` 文件                             | `Glob`   |
| 查找哪些 `*.py` 文件调用了 `requests.get`       | `Grep` (with `glob: "*.py"`) |
| 了解目录布局                       | `Glob`   |
| 阅读匹配行的代码                   | `Grep` (`output_mode: "content"`) |

一个常见的工作流程是**链式使用它们**：使用 `Glob` 缩小到一组候选文件，然后使用 `Grep` 搜索它们的内容。请注意，`Grep` 也接受自己的 `glob` 参数，因此对于简单的"搜索这些文件类型"的情况，你可能根本不需要单独的 `Glob` 调用。

---

## 技巧和注意事项

- **`*` 不跨目录边界；`**` 会跨。** `src/*.js` 匹配 `src/` 中直接的文件，而 `src/**/*.js` 匹配 `src/` 及其所有子目录中的 `.js` 文件。
- **省略 `path` 以搜索整个项目。** 不要传递空字符串或占位符——直接省略它以从工作目录搜索。
- **按时间排序。** 因为结果按修改时间排序，`Glob` 是回答"我最近更改了什么匹配 X 的内容？"的快速方式。
- **对于广泛、开放式的搜索**，跨多个目录和命名约定，考虑委托给一个探索代理，而不是发出许多单独的 `Glob` 调用。
