GrepTool：搜索内容

GrepTool 负责在文件内容里搜索文本或正则模式。
在真实使用里，它常常是 Claude Code 排查问题、理解代码和定位实现的第一步。

如果你把 Claude Code 的常见动作拆开看，会发现很多轮对话其实都是：

1. 先 Grep
2. 再 Read
3. 再判断要不要 Edit

所以 GrepTool 本质上是主循环里的“线索发现器”。

tools/GrepTool/GrepTool.ts：

const inputSchema = z.strictObject({
  pattern: z.string(),
  path: z.string().optional(),
  glob: z.string().optional(),
  output_mode: z.enum(['content', 'files_with_matches', 'count']).optional(),
  '-B': z.number().optional(),
  '-A': z.number().optional(),
  '-C': z.number().optional(),
  '-n': z.boolean().optional(),
  '-i': z.boolean().optional(),
  type: z.string().optional(),
  head_limit: z.number().optional(),
  offset: z.number().optional(),
  multiline: z.boolean().optional(),
})

这说明 GrepTool 不只是“搜某个词”，它还支持：

• 搜文件名过滤
• 搜文件类型过滤
• 只看命中文件
• 看内容上下文
• 看匹配计数
• 分页和截断
• 多行模式

也就是说，它是一个被结构化封装过的 ripgrep 搜索器。

源码里最关键的导入是：

import { ripGrep } from '../../utils/ripgrep.js'

Anthropic 没有让模型直接去 Bash 里跑 rg，而是把 ripgrep 包装成了正式工具。
这样做的好处很直接：

• 权限系统能识别它是“内容搜索”
• 输出模式更可控
• 上下文结果更容易裁剪
• UI 能做更合理展示

源码里有一个非常关键的默认值：

const DEFAULT_HEAD_LIMIT = 250

注释写得很直白：
无上限的 grep 很容易把上下文塞爆。

所以 GrepTool 天生就做了两件事：

• 默认限制结果规模
• 支持 offset 分页继续看

这很重要，因为 Claude Code 本质上是在和有限上下文做博弈。
搜索工具如果不帮它控量，很快就会把对话拖垮。

源码里把输出模式拆成：

• content
• files_with_matches
• count

这三种模式背后对应的是三种完全不同的工作目标：

• files_with_matches：我先知道哪些文件相关
• content：我要看匹配周边上下文
• count：我想知道影响范围或匹配规模

这也是 Claude Code 比“让 AI 跑 rg 然后自己读终端输出”更高级的地方。
因为它不是只有一个工具，而是让工具内部支持不同意图。

这两个工具经常放在一起比较：

• GlobTool：按路径/文件名找
• GrepTool：按内容找

你可以这么理解： 知道文件长什么样 -------------> GlobTool

知道内容里有什么关键词 --------> GrepToo

在真实任务里，GrepTool 的使用频率通常会更高。
因为大多数时候你知道的是：

• 某个函数名
• 某个 API 路径
• 某个报错信息
• 某个文案

而不是准确文件名。

和 GlobTool 一样，GrepTool 也明确声明自己是：

isConcurrencySafe() {
  return true
}

isReadOnly() {
  return true
}

这意味着主线程可以更大胆地把多个搜索请求并行发出去。
这对 Claude Code 的探索效率很有帮助。

比如用户说：

登录成功后，为什么还会跳回登录页？

Claude Code 很典型的路径会是：

1. GrepTool 搜 login、redirect、路由保护逻辑
2. FileReadTool 读取命中的几个关键文件
3. 再用 GrepTool 搜状态来源
4. 最后定位 root cause

你会发现，GrepTool 在这里不是辅助工具，而是调查主链的起点。

功能上也许能凑合，但系统层面不一样。
GrepTool 更可控、更节省上下文、更利于后续推理。

不对。
它实际上支持不同输出模式、上下文范围、分页和文件过滤。

也不完全。
它还经常被用于：

• 确认某次改动影响了哪些地方
• 看一个名字是否还残留在项目里
• 确认重构是否改全

如果把 Claude Code 的搜索能力压缩成一句话：

GrepTool 是主循环里最常用的内容定位工具，它把 ripgrep 封装成了可分页、可裁剪、可结构化回注的正式搜索能力。

很多源码分析任务，真正开始于 GrepTool。