42 Built-in Tools — 完整功能与机制详解

用户价值

让 Claude 能「看到」你项目里的任何文件。不只是代码文本——它还能看图片、读 PDF、解析 Jupyter Notebook。

它不只是 cat 命令

很多人以为 FileRead 就是跑了个 cat，但实际上它做了很多事：

• 智能分页：默认读取前 2000 行，支持 offset 和 limit 参数精确定位。对大文件不会一股脑全读进来撑爆上下文。
• PDF 解析：传入 pages: "1-5" 可以只读指定页。超过 10 页的 PDF 必须指定页码范围，防止上下文溢出。
• 图片识别：读取 PNG/JPG 时会压缩并编码为 base64，利用 Claude 的多模态能力直接「看」图片内容。
• Notebook 解析：读取 .ipynb 文件时会解析所有 cell 及其输出，包括代码、文本和可视化。
• 设备文件阻断：如果路径指向 /dev/ 等设备文件，会直接拒绝，防止进程 hang 住。
• macOS 特殊字符处理：会自动检测并转换截图文件名中的特殊空格字符。
• 行号标注：输出格式类似 cat -n，带行号方便后续引用和编辑。

权限模型

需要读权限。在所有权限模式下（包括最保守的 default）通常自动批准，因为读操作不改变任何状态。

参数

用户价值

让 Claude 快速找到项目中符合模式的文件。比如「找所有 TypeScript 测试文件」→ **/*.test.ts。

工作机制

• 使用快速 glob 匹配算法，即使项目有上万文件也能瞬间返回。
• 结果按修改时间排序，最近修改的在前——这在理解「最近在动哪些文件」时很有用。
• 结果最多返回 100 个文件路径，防止列表过长。
• 标记为 isReadOnly 和 isConcurrencySafe，可以与其他只读工具并行执行。

参数

用户价值

在整个代码库中搜索内容。Claude 用它来定位函数定义、找 API 调用、追踪错误信息。这是 Claude 理解陌生代码库最重要的工具之一。

底层是 ripgrep，不是 grep

ripgrep (rg) 比传统 grep 快几个数量级，自动忽略 .gitignore 中的文件，自动跳过二进制文件。

三种输出模式

• files_with_matches（默认）：只返回匹配的文件路径列表。用于「这个函数在哪些文件里出现过」。
• content：返回匹配行及上下文。用于「帮我看看这个函数怎么用的」。支持 -B/-A/-C 控制前后文行数。
• count：只返回每个文件的匹配数量。用于「这个 API 被调用了多少次」。

分页与性能

默认 head_limit=250，防止搜索热词（如 "import"）返回上万条结果撑爆上下文。支持 offset 翻页。

参数

用户价值

让 Claude 使用跟 IDE 一样的代码导航能力：跳转到定义、查找引用、查看类型信息、列出文件符号。当 Grep 找到一个函数名但不确定是定义还是调用时，LSP 能精确定位。

支持的操作

• goToDefinition — 跳转到函数/变量的定义位置
• findReferences — 查找所有引用
• hover — 获取类型信息和文档
• documentSymbol — 列出文件内所有符号（函数、类、变量）
• workspaceSymbol — 在整个工作区搜索符号
• implementation — 查找接口的具体实现
• callHierarchy — 查看调用层级

为什么是 feature-gated

LSP 需要连接到一个运行中的语言服务器。在 IDE 环境（VS Code、JetBrains）中通常可用，纯 CLI 环境可能不可用。所以它受 feature flag 控制。

用户价值

让 Claude 直接编辑 .ipynb 文件的 cell，支持插入新 cell、替换 cell 内容、删除 cell。对数据科学工作流特别有用。

操作模式

• insert — 在指定 cell 之后插入新 cell
• replace（默认） — 替换指定 cell 的内容
• delete — 删除指定 cell

每个 cell 通过 cell_id 定位，支持 code 和 markdown 两种类型。

用户价值

让 Claude 执行任何 shell 命令：跑测试、安装依赖、启动服务、查看 git 状态、运行构建脚本。这是 Claude 与操作系统交互的核心通道。

它远不只是 subprocess.run()

BashTool 是所有工具中机制最复杂的一个：

• 语义安全解析：在执行前，系统会解析命令的语义——是搜索类（grep、find）、只读类（cat、ls）还是可能破坏性的（rm、git push --force）。不同类别的权限要求不同。
• 沙箱模式：可以配置沙箱，限制命令只能在指定目录内操作。dangerouslyDisableSandbox 参数名本身就是一个警告。
• 只读验证：在只读权限模式下，系统会验证命令确实不会修改文件系统。
• 输出截断：命令输出超过限制时自动截断，避免一个 cat 大文件把上下文窗口填满。
• 后台运行：run_in_background: true 时，命令在守护线程中执行，模型可以继续做其他事。完成后通过通知队列注入结果。
• 超时控制：默认 2 分钟超时，最长可设 10 分钟。
• 描述字段：模型需要提供 description（简短说明命令目的），这不只是给用户看的，也帮助权限系统和 hooks 做更好的判断。

权限模型

这是 Claude Code 中权限检查最严格的工具：

• 在 default 模式下，几乎每条命令都需要用户确认
• 在 auto 模式下，由 classifier 评估风险
• 用户可以通过 allow/deny 规则预先放行或禁止特定命令模式
• PreToolUse hooks 可以在执行前拦截、修改或拒绝

参数

用户价值

精确修改文件的一部分，而不是重写整个文件。比如「把这个函数名从 foo 改成 bar」。比 FileWrite 更安全，因为只改你指定的部分。

工作机制

• 精确匹配：使用 old_string + new_string 的搜索/替换模式。old_string 必须在文件中唯一匹配，否则报错（防止误改）。
• 缩进保持：自动检测并保持原始文件的缩进风格（tab vs spaces）。
• 编码保持：保持文件原有的编码和换行符格式（LF vs CRLF）。
• Diff 生成：每次编辑都生成可视化 diff，在 UI 中展示具体改了什么。
• 历史追踪：编辑会被记录到文件历史中，支持后续 /rewind 回滚。
• replace_all：设为 true 时替换所有匹配项，适合批量重命名。

为什么推荐用 Edit 而不是 Write

Edit 只发送变更的部分（diff），Write 发送整个文件内容。对于修改现有文件，Edit 消耗的 token 更少，也更不容易出错（不会意外丢失文件其他部分的内容）。

用户价值

创建新文件或完全重写现有文件。适合「帮我创建一个新的配置文件」或「帮我重写这个测试文件」。

安全机制

• 如果目标文件已存在，系统要求 Claude 先读过这个文件（防止盲目覆盖）。
• 对已存在文件生成完整的 diff patch，在 UI 中清楚展示改了什么。
• 自动创建父目录（如果不存在的话）。
• 不会创建 README.md 或文档文件，除非用户明确要求。

用户价值

Windows 上的 BashTool 等价物。执行 PowerShell cmdlet，支持 Windows 特有的系统操作。

架构上与 BashTool 完全一致：同样的安全解析、沙箱、后台执行和权限模型，只是底层执行引擎换成了 PowerShell。

用户价值

当一个复杂任务需要读很多文件做深入研究时，主 Agent 可以派一个 Sub-agent 去做，Sub-agent 在独立的上下文中工作，完成后只把结论返回。这样主对话不会被大量中间过程细节撑爆。

这不是「开个子线程」

AgentTool 创建的是一段完整的、带独立上下文的子运行时：

• 独立的 messages[]：Sub-agent 从空白消息列表开始，有自己的对话历史。
• 独立的工具集：Sub-agent 可以使用除 AgentTool 之外的所有工具（防止无限递归生成）。
• 可选模型选择：可以指定 haiku（快而便宜）、sonnet（均衡）或 opus（最强）。适合用便宜模型做简单的搜索收集工作。
• 可选 worktree 隔离：isolation: "worktree" 让 sub-agent 在独立的 git worktree 中工作，文件修改不会影响主工作目录。
• 后台运行：run_in_background: true 时，主 Agent 可以继续做其他事，后台 agent 完成后会收到通知。

Agent Type

subagent_type 参数支持多种专门化 agent：

• general-purpose（默认）— 通用 agent，可以使用所有工具
• Explore — 专门用于代码探索，只有读取工具，执行更快
• Plan — 专门用于制定实施方案，不会写代码
• 其他专门化类型根据 feature flag 和配置动态出现

结果返回

Sub-agent 可能执行了 30+ 次工具调用，但所有中间过程直接丢弃。父 Agent 只收到最终的文本摘要。这就是「上下文隔离」的核心价值。

用户价值

在 Agent Team 模式下，不同 Agent 之间需要通信。SendMessage 让它们可以互相发消息、广播状态更新、协调关机流程。

消息类型

• 普通消息：文本消息，附带 5-10 字摘要
• 广播：to: "*" 发给所有团队成员
• 关机请求/响应：结构化协议消息（shutdown_request / shutdown_response）
• 计划审批响应：leader 对 teammate 提交的方案做出批准/拒绝

用户价值

创建多 Agent 协作团队。适合大型重构、同时处理前后端、并行测试等场景。

工作机制

• 初始化团队文件和配置
• 生成 Team Lead agent
• 为每个 teammate 分配颜色标识（UI 中区分）
• 每个 teammate 有独立的任务隔离

需要 Agent Swarms feature flag 启用。

解散团队、清理关联目录和状态。是 TeamCreate 的逆操作。

用户价值

给当前工作创建一个独立的 git 工作目录。就像开了一个平行宇宙——在这里面修改代码不影响主分支，适合实验性修改或并行任务。

工作机制

• 调用 git worktree add 创建新的工作树
• 自动创建对应的新分支
• 切换当前会话的工作目录到 worktree
• 保存原始状态，方便退出时恢复

退出时的选择

通过 ExitWorktreeTool 退出时有两个选择：

• keep — 保留 worktree，以后可以继续使用
• remove — 删除 worktree 和分支。如果有未提交的修改，必须显式确认 discard_changes: true

退出 worktree 回到主工作目录。支持保留或删除 worktree。删除时如果有未提交修改会要求显式确认。

用户价值

Claude 在做多步任务时用来记录自己的计划。你能在 UI 中看到它列出的步骤和完成进度。

与 TaskCreate 的区别

• TodoWrite 是简单的内存清单，适合单次会话内的快速规划。全部完成后自动清空。
• TaskCreate/Update 是更完整的任务系统，支持依赖关系、持久化到磁盘、跨 Agent 协调。

TodoWrite 是早期版本的遗留工具，新的任务管理推荐使用 Task 系列。

用户价值

为复杂工作创建可追踪的任务项。你能在 UI 中看到任务列表和各自的状态。

任务结构

• subject — 简短任务标题
• description — 详细说明
• activeForm — 动态文案（如 "Running tests"），在 spinner 中显示
• metadata — 任意附加数据

状态流转

pending → in_progress → completed（或 deleted）

依赖管理

通过 addBlocks 和 addBlockedBy 管理任务间的依赖关系。当一个任务完成时，被它阻塞的任务会自动解锁。这就是 learn-claude-code S07 中介绍的任务图（DAG）机制。

TaskListTool 列出所有任务及其状态；TaskGetTool 获取单个任务的详细信息。两者都是只读的。

用户价值

当 Bash 命令或 Sub-agent 在后台运行时，用这个工具获取它们的输出结果。

• 默认会等待任务完成（block: true）
• 可设超时时间（默认 30 秒）
• 返回 stdout、stderr 和任务元数据

终止正在运行的后台 Bash 命令或 Agent。返回终止确认。

用户价值

切换到「先研究、后实施」的工作方式。在计划模式下，Claude 可以读文件和搜索，但不会修改任何代码。适合复杂需求的方案设计阶段。

不只是权限开关

进入 Plan Mode 会改变整个会话的行为模式：Claude 会更倾向于产出结构化方案、列出步骤，而不是直接动手。等方案得到你的批准后，再通过 ExitPlanMode 切换到实施阶段。

提交计划并进入实施阶段。可以附带 allowedPrompts——一组语义化的权限描述（如「运行测试」「安装依赖」），而不是具体的命令字符串。

用户价值

让 Claude 在互联网上搜索信息。查 API 文档、找错误解决方案、了解库的最新版本。

限制

• 使用 Anthropic 的搜索 API，目前仅在部分地区可用
• 每次调用最多 8 个搜索请求
• 支持域名白名单/黑名单过滤
• 查询最少 2 个字符

用户价值

抓取指定 URL 的网页内容。Claude 可以读在线文档、API 参考、GitHub issue 等。

工作机制

• 抓取 URL 内容并转换为 Markdown
• 用 LLM 处理内容（根据你提供的 prompt 提取关键信息）
• 自动处理重定向
• 部分域名预批准（如官方文档站），其他域名需要权限确认
• 不支持需要登录的页面

用户价值

MCP (Model Context Protocol) 是 Anthropic 定义的标准协议，让 Claude 能连接外部系统——数据库、Slack、JIRA、Figma、你自己的内部工具，任何实现了 MCP 协议的服务。

四个 MCP 相关工具各做什么

• MCPTool — 不是一个工具，而是一个工具模板。每个 MCP 服务器暴露的工具都会动态生成一个 MCPTool 实例。如果你连了 3 个 MCP 服务器，每个暴露 5 个工具，那就有 15 个动态生成的 MCPTool。
• ListMcpResourcesTool — 列出 MCP 服务器提供的资源（文件、知识库条目等）
• ReadMcpResourceTool — 读取特定资源的内容
• McpAuthTool — 当 MCP 服务器需要 OAuth 认证时出现。点击后启动浏览器认证流程，认证成功后自动替换为真正的工具。

连接类型

• StdIO — 最常见。启动一个本地子进程，通过 stdin/stdout 通信
• SSE — HTTP 流式连接，适合远程服务器
• WebSocket — 双向持久连接
• HTTP — 简单请求-响应

延迟加载机制

启动时只加载工具名称（轻量），完整的 schema 在真正被使用时才加载。这就是为什么连接了很多 MCP 服务器时，空闲状态的上下文成本仍然可控。

用户价值

你可能注意到 Claude 有时会说「让我搜索一下是否有可用的工具」。这就是 ToolSearchTool 在工作——它从延迟加载的工具池中按关键词查找并激活工具。

为什么需要延迟加载

如果把所有 40+ 工具的完整 schema 都塞进系统提示，会消耗大量 token。解决方案：

• 启动时只暴露高频工具的完整 schema
• 低频工具只注册名字
• 需要时通过 ToolSearch 动态获取完整 schema 并激活

查询方式

• "select:Read,Edit,Grep" — 直接按名字获取
• "notebook jupyter" — 关键词搜索，返回最匹配的
• "+slack send" — 要求名字包含 "slack"，按其他词排序

用户价值

执行用户定义的 Skill（可复用工作流）。当你输入 /commit、/review-pr 等技能命令时，SkillTool 负责加载和执行对应的 .prompt 文件。

Skill 来源

• 本地 .claude/skills/ 目录中的 .prompt 文件
• MCP 服务器提供的 prompts
• Bundled skills（内置技能）
• 插件提供的技能

用户价值

当 Claude 需要你做选择时使用。比如「你希望用方案 A 还是方案 B？」，会在终端中渲染一个交互式选择界面。

支持单选、多选、附带预览内容（代码片段、mockup 对比）的结构化提问。最多 4 个选项。

用户价值

在 Proactive 模式下使用。当 Agent 需要等待一段时间（比如等部署完成）时，Sleep 让它暂停而不退出。定期唤醒检查是否有新工作。

注意：Sleep 不会阻塞 shell 进程，但每次唤醒都消耗 API 调用（约 5 分钟一次，对齐 prompt cache 过期时间）。

用于 SDK/非交互模式下返回结构化 JSON 数据。必须在执行结束时恰好调用一次。普通用户在终端中不会用到。

在 Proactive 模式下向用户发送带附件的富消息（图片、截图、日志）。支持主动通知（标记为 "proactive"），比如「你离开时发现了一个问题」。

读取或修改 Claude Code 配置（主题、模型、权限默认值等）。读取自动批准，写入需要权限确认。

用户价值

设置定时触发的 Agent 任务。比如「每天早上 9 点检查依赖更新」「每小时运行一次测试」。

• ScheduleCronTool — 创建 cron 定时任务
• CronDeleteTool — 删除定时任务
• CronListTool — 列出所有定时任务
• RemoteTriggerTool — 管理远程 Agent 触发器（通过 Anthropic API），支持创建、更新、运行和查看

需要 OAuth 认证和对应 feature flag。