工具调用完整参考

工具调用完整参考

Claude Code 在执行任务时会调用内置工具。了解每个工具的完整参数，能帮你写出更精准的指令，也能理解 Claude 在做什么。

何时明确指定工具

大多数时候让 Claude 自己选择工具即可。以下场景值得明确指定：

场景	明确指定工具	原因
找函数/类定义	ide_find_definition	语义跳转，比 Grep 更准确
分析大文件	Read(offset, limit)	避免读整个大文件浪费 token
查找关键词	Grep	比让 Claude 自由搜索更快
全局重命名	ide_refactor_rename	比文本替换安全，处理作用域
查代码错误	ide_diagnostics	实时 IDE 诊断，比手动运行快

---

工具一览

工具	分类	核心用途
Read	文件操作	读取文件内容
Write	文件操作	创建或完全覆写文件
Edit	文件操作	精确替换文件中的字符串片段
Glob	搜索	按文件名模式查找文件
Grep	搜索	在文件内容中搜索文本
Bash	执行	运行 shell 命令
Agent	子任务	启动子 Agent 处理独立任务
WebFetch	网络	获取网页内容
WebSearch	网络	搜索互联网
TodoWrite	任务	写入 todo 列表（轻量任务追踪）
TaskCreate	任务	创建结构化任务
TaskUpdate	任务	更新任务状态
TaskGet	任务	获取任务详情
TaskList	任务	列出所有任务
ExitPlanMode	规划	完成规划，请求用户批准
AskUserQuestion	交互	向用户提问（多选/单选）

---

文件操作工具

Read — 读取文件

参数：
  file_path   必填  文件绝对路径
  offset      可选  从第几行开始读取（从 1 计）
  limit       可选  最多读取多少行
  pages       可选  PDF 专用，指定页码范围如 "1-5"

使用示例：

# 读取整个文件
> 读一下 src/auth.ts

# 精确读取（节省 token 的关键技巧）
> 读一下 src/auth.ts 的第 80-130 行

# 读取 PDF 的特定页
> 读一下 API文档.pdf 的第 3-5 页

支持的文件类型：

• 所有文本文件（.ts、.java、.md 等）
• 图片文件（.png、.jpg 等）—— 以视觉方式呈现
• PDF 文件（需要指定页码范围）
• Jupyter Notebook（.ipynb）

注意：每行超过 2000 字符会被截断。

---

Write — 创建/覆写文件

参数：
  file_path   必填  文件绝对路径
  content     必填  写入的完整内容

重要规则：

• Write 完全覆盖文件内容
• 修改现有文件时，Claude 会优先用 Edit（更安全）
• 创建新文件时使用 Write

# 触发场景
> 帮我创建一个 src/utils/format.ts 工具文件
（Claude 用 Write 创建新文件）

> 把这个文件完全重写为 TypeScript 版本
（Claude 可能用 Write 覆写）

---

Edit — 精确修改文件片段

参数：
  file_path    必填  文件绝对路径
  old_string   必填  要替换的原始文本（必须在文件中唯一存在）
  new_string   必填  替换后的新文本
  replace_all  可选  是否替换所有匹配项（默认 false）

工作原理：Edit 做的是精确字符串替换，不是按行号替换：

文件原内容：
function validateToken(token: string) {
  return token.length > 0;
}

Edit 操作：
old_string = "return token.length > 0;"
new_string = "return token.length >= 32 && token.startsWith('Bearer ');"

文件新内容：
function validateToken(token: string) {
  return token.length >= 32 && token.startsWith('Bearer ');
}

关键约束：old_string 必须在文件中唯一，否则 Edit 失败（避免歧义）。如果有多处相同代码，需要提供更多上下文使其唯一。

---

搜索工具

Glob — 按文件名模式查找

参数：
  pattern   必填  glob 模式（支持 * 和 **）
  path      可选  搜索的起始目录（默认为工作目录）

常用模式：

"**/*.ts"          所有 TypeScript 文件（递归）
"src/**/*.test.ts" src 下的所有测试文件
"*.json"           当前目录下的 JSON 文件
"src/components/*" components 目录下的所有直接子项

# 触发场景
> 有哪些测试文件？
（Claude 用 Glob("**/*.test.ts")）

> src/pages 下有哪些页面组件？
（Claude 用 Glob("src/pages/**/*")）

---

Grep — 在文件内容中搜索

参数：
  pattern        必填  正则表达式或文本
  path           可选  搜索目录（默认工作目录）
  glob           可选  文件类型过滤，如 "*.ts"
  type           可选  文件类型，如 "js"、"py"
  output_mode    可选  "files_with_matches"（默认）| "content" | "count"
  -i             可选  是否忽略大小写
  -n             可选  是否显示行号（仅 content 模式）
  context        可选  显示匹配行前后各 N 行
  -A             可选  匹配行后 N 行
  -B             可选  匹配行前 N 行
  head_limit     可选  限制返回的结果数量

使用示例：

# 查找函数定义（返回文件列表）
> 找一下 getUserById 函数在哪里定义的

# 查找并显示上下文（content 模式）
> 找一下所有 TODO 注释，显示每条注释的前后各 2 行

# 查找并计数
> 项目里一共用了多少次 console.log？

output_mode 对比：

files_with_matches  → 返回包含匹配的文件路径列表（默认，最省 token）
content             → 返回匹配的具体行内容（需要看上下文时用）
count               → 返回每个文件的匹配次数

---

执行工具

Bash — 执行 shell 命令

参数：
  command      必填  要执行的 shell 命令
  description  必填  命令用途说明（给用户看）
  timeout      可选  超时时间（毫秒，最大 600000）
  run_in_background  可选  是否后台运行

执行前会显示命令（根据权限设置，可能需要你确认）。

常见用途：

git status
git diff HEAD~1
npm test
pnpm lint
curl http://localhost:3000/health
ls -la src/

注意：Bash 命令不跨调用保持状态（每次都是新 shell），但工作目录会保持。

---

搜索/网络工具

WebFetch — 获取网页内容

参数：
  url     必填  完整 URL
  prompt  必填  告诉 Claude 从页面中提取什么信息

注意：公司内网环境可能无法访问外部 URL。如需访问内部系统，使用 Chrome DevTools MCP。

---

WebSearch — 互联网搜索

参数：
  query            必填  搜索关键词
  allowed_domains  可选  仅返回这些域名的结果
  blocked_domains  可选  排除这些域名的结果

注意：公司网络通常屏蔽外部访问，此工具在内网环境下可能无法使用。

---

任务管理工具

任务管理工具用于在复杂的多步骤任务中追踪进度，Claude 会在需要时主动使用。

TaskCreate — 创建任务

参数：
  subject      必填  任务标题（简洁的行动描述）
  description  必填  详细说明（包含接收标准）
  activeForm   可选  进行中时显示的动词形式（如"正在分析代码"）

TaskUpdate — 更新任务状态

参数：
  taskId        必填  任务 ID
  status        可选  "pending" | "in_progress" | "completed" | "deleted"
  subject       可选  修改标题
  description   可选  修改描述
  addBlocks     可选  添加被此任务阻塞的任务 ID 列表
  addBlockedBy  可选  添加阻塞此任务的前置任务 ID 列表

任务状态流转：

pending → in_progress → completed
    ↘ deleted（任何时候都可以删除）

TaskGet / TaskList

• TaskGet(taskId) — 获取单个任务详情
• TaskList() — 列出所有任务及其状态

---

规划与交互工具

ExitPlanMode — 完成规划请求批准

在规划模式（Plan Mode）完成后，Claude 调用此工具请求你审阅并批准计划。

AskUserQuestion — 向用户提问

Claude 用此工具在需要你做选择时弹出交互式问题，支持单选和多选。

---

工具调用的 Token 消耗估算

工具              平均 Token 消耗（每次调用）

Glob              低（仅返回文件路径列表）
Grep(files)       低（仅返回匹配文件名）
Grep(content)     中（返回匹配内容，依结果数量）
Read(精确)        中（依读取行数，约 4 token/行）
Read(整文件)      高（大文件可达数千 token）
Bash              中（依输出内容长度）
Write             中（依文件大小）
Edit              低（仅替换片段）
WebFetch          高（整个网页转 Markdown）
Agent             高（子 Agent 完整上下文）

实用原则：优先用 Glob/Grep 定位，再用 Read(offset+limit) 精确读取，避免直接 Read 大文件。

---

Agent 工具（委派子任务）

参数：
  subagent_type     可选  子 Agent 类型（"general-purpose"/"Explore" 等）
  prompt            必填  子任务描述
  description       必填  简短描述（3-5个词）
  run_in_background 可选  是否后台运行
  isolation         可选  "worktree" 表示在独立 worktree 中运行
  resume            可选  恢复之前的子 Agent（传入 agentId）

常用 subagent_type：

general-purpose   通用，适合复杂研究和多步骤任务
Explore           快速代码库探索（only read tools）
Plan              架构规划和方案设计

何时用 Agent：

• 需要大量读取文件（3+ 个）做探索性分析
• 多个独立子任务可以并行执行
• 任务明确独立，不需要主 Agent 参与中间步骤

何时不用 Agent：

• 任务简单（1-2 个文件），子 Agent 启动开销反而更慢
• 步骤之间有强依赖，必须顺序执行
• 需要精确控制每一步的输出

---

工具组合使用的最佳实践

组合一：安全的代码探索（低 token 消耗）

Glob → 找到相关文件列表
Grep → 在文件中定位关键行号
Read(offset+limit) → 精确读取目标代码段

组合二：安全的代码修改

Grep → 确认函数存在且唯一
Read → 阅读完整上下文（避免改错地方）
Edit → 精确替换（不是 Write 整个文件）
Bash("验证命令") → 确认修改没有引入错误

组合三：影响范围分析（修改公共函数前）

ide_find_references → 找所有调用方
ide_call_hierarchy → 追踪调用链
Grep → 验证搜索结果完整性