深入解构Claude Code - 第 4 篇 · 工具：AI 的手

本篇回答六个问题："工具"到底是什么？哪几样工具永远随身？为什么不把所有工具一次全告诉 AI？危险操作谁把关？几件事同时干怎么安排？几个最重要的工具长什么样？

4.1 AI 只会说话，怎么就能改文件、跑命令："工具"是什么

第 1 篇打过一个比方：工具是 AI 的手。这一章把这双手的结构讲清楚。

一个工具就是一份"说明书 + 一个函数"

在程序内部，每个工具是一个固定的结构，包含两样东西：

给 AI 看的说明书 ：我叫什么名字、我是干什么的、用我需要提供哪些参数（参数名、类型、含义）。这份说明书写成一种标准格式（叫 JSON Schema，可以理解成一张"填空表格"：{ 文件路径: 一段文字, 要搜索的内容: 一段文字 }）。
给程序执行的函数：真正干活的代码。读文件的工具，函数里就真的去读磁盘；跑命令的工具，函数里就真的去启动终端命令。

AI 是怎么"用"工具的

关键在于：AI 并不能直接调用函数。它能做的只有一件事------输出文字。所谓"调用工具"，是它在回复里用约定好的格式写一段结构化内容，相当于填了那张表格：

arduino 复制代码

（AI 回复中的一段）
我要调用「读文件」工具，参数：
  文件路径 = "src/auth.ts"

程序收到这段回复，看懂了"这是一个工具调用请求"，于是：查表找到"读文件"对应的函数 → 把参数填进去执行 → 把执行结果（文件内容）作为一条新消息，放回聊天记录 → 下一圈带给模型看。

bash 复制代码

AI：我要用「读文件」，参数是 src/auth.ts     ← AI 只是"说"
        ↓
程序：（找到读文件工具的函数，真的去读）
        ↓
程序：（把读到的内容包成"工具结果"消息）
        ↓
AI：（下一圈看到文件内容）原来是这里写错了......

所以再次强调那个分工：AI 负责决定"做什么"，程序负责"真的去做"。AI 自始至终碰不到你的电脑，它只是在文字里表达意图，所有动作都是本地程序执行的。这个边界是安全模型的基础------正因为动作是程序执行的，程序才有机会在执行前喊停（4.4 讲）。

工具的执行函数为什么也是"一段段往外吐"的

和核心循环一样，工具的执行函数也被设计成"说书人"模式（生成器）：不是憋到全部做完才返回，而是边做边往外吐"进展片段"。

为什么？有些工具很慢或者输出很多：跑一个测试命令要一分钟、读一个大文件内容很长。边做边吐，界面就能实时显示"正在跑测试......已通过 30 个"这种进度，而不是让用户对着转圈发呆。工具吐出来的片段，和模型回复的片段走同一条通道到界面，所以你在屏幕上看到的"工具执行过程"和"AI 说话"能无缝交织在一起。

一个工具还带几个"性格标签"

每个工具除了说明书和函数，还贴着几个小标签，程序靠这些标签决定怎么对待它：

只读还是会改东西：读文件、搜索是只读的；改文件、跑命令可能改东西。会改东西的工具，执行前要给文件拍快照（为了后悔药）。
能不能和别人同时干：两个搜索工具可以同时跑；但两个跑命令的工具不能同时跑（可能互相干扰，比如同时改同一个文件）。
现在能不能用：有些工具在特定条件下才出现（比如后台任务相关的工具，没有后台任务时就不出现）。

4.2 随身工具箱：哪几样工具永远在身上

项目里实际有六十多个工具，但有七八样是永远随身的，构成最核心的工具箱。不管什么场景、什么模式，这几样一定在。

核心工具清单

工具	干什么	为什么不可或缺
跑命令（Bash）	在终端执行任意命令	装依赖、跑测试、git 操作、构建......全靠它，是"万能手"
读文件	读单个文件内容	看代码、看配置、看日志的基础
改文件	精确修改文件里的一段内容	修 bug 的主要手段
写文件	创建或整体覆盖一个文件	新建文件、写文档
搜文件名（Glob）	按文件名模式找文件（`src/*/.ts`）	先得找到文件在哪
搜内容（Grep）	在文件里搜文字/正则	定位"某个函数在哪定义、在哪被调用"
记待办（TodoWrite）	维护一个任务清单	让长任务有条理，也让用户看到进度
计划模式相关	提交计划请用户批准	动手前先给方案（第 10 篇讲）

为什么是这几样

注意一个设计思想：这套工具是正交的------每样负责一个基础能力，组合起来能覆盖几乎所有编程任务，而且没有重叠。

要"找到某段代码"：搜文件名 + 搜内容。
要"看懂它"：读文件。
要"改它"：改文件/写文件。
要"验证改得对不对"：跑命令（跑测试）。
要"做复杂的事"：跑命令里可以执行 git、npm、任何 CLI 工具。

打个比方：这不像给 AI 配了一百种专用电动工具，而是给了它刀、锯、尺、锤这几样基础工具------手艺好的木匠用基础工具什么都能做。而且基础工具的说明书短，AI 容易用对；专用工具越多，AI 越容易在"该用哪个"上犯选择困难。

"跑命令"工具为什么是万能手但也最危险

跑命令工具能执行任意终端命令，意味着它理论上能做任何事：安装软件、删除文件、联网下载、改系统配置......能力最强，风险也最高。所以它也是权限把关最严的工具（4.4 讲），而且它的输出会被截断（命令可能打印几十万行，全留着会撑爆上下文）。

其他五十多个工具是什么

除了核心几样，剩下的工具大致是：

网络类：抓取网页内容、联网搜索；
任务类：创建/查看/管理后台任务；
子助手类：派一个"分身"去干独立的子任务（第 9 篇讲）；
外部能力类：调用用户自己接的外部工具（第 7 篇讲）；
记忆类：查长期记忆；
计划类：进入/退出计划模式；
询问类：遇到拿不准的选择，正式向用户提问；
还有一些是实验性功能，普通版本里被开关摘掉了（第 11 篇讲）。

这些工具不是"永远在身上"，而是按下面两章讲的机制按需出现。

4.3 为什么不把一百件工具一次全告诉它：工具太多反而变笨

这是工具系统里最反直觉、也最精妙的设计：不是工具越多越好。给 AI 看的工具越多，它反而表现越差。

为什么会"变笨"

每次和模型对话，都要把"当前有哪些工具可用"连同它们的说明书一起发过去。每个工具的说明书（名字 + 描述 + 参数表格）都要占地方，按模型的计量单位算，几十个工具的说明书加起来可能占好几千字的篇幅。这带来三个问题：

费钱：这部分篇幅每次对话都要发，按用量计费，一天聊下来是不小的成本。
挤占容量：模型一次能看的内容有上限，说明书占多了，留给你的代码和对话的空间就少了。
最关键的------选择困难：模型要从一堆工具里挑"这次该用哪个"。工具一多，相似的工具也多，模型更容易挑错、挑花眼，就像给一个人五十页的菜单，他反而点不好菜。心理学上这叫"选择过载"，对模型同样成立。

三层工具供给策略

项目的解法是把工具分三层，像商店的"门口货架 / 店内货架 / 仓库"：

arduino 复制代码

第一层：核心工具（门口货架）
  └─ 4.2 讲的那七八样，永远在说明书里，AI 随时能用
        ↓ 这些不够时
第二层：技能池（店内货架）
  └─ 大量进阶能力不在说明书里展开，只列个"名字 + 一句话简介"
     AI 需要时，通过一个专门的「技能工具」去把完整说明取来
        ↓ 连技能池里都找不到时
第三层：现查（仓库）
  └─ 有个"搜索更多工具"的工具，AI 报上需求，
     程序按相关度把匹配的工具找出来给它

这个设计的精髓是：AI 每次"随身带的说明书"很薄（只有核心工具 + 其他能力的"目录"），但它知道"如果需要更多本事，我可以去查目录、去仓库调货"。

打个比方：一个老练的员工，脑子里牢记最常用的几套流程（核心工具），同时知道公司有一本《能力手册》（技能池目录），遇到不常用的事他会先翻手册找到对应流程，再按流程做；手册里都没有的，他还能去公司的共享资料库搜索（第三层）。你不需要、也不应该让他把整本手册背下来。

外部工具更要按需

用户自己接的外部工具（比如公司内部系统、第三方服务）数量可能成百上千，更不可能全发。它们同样走"目录 + 按需加载"的路子：平时只告诉 AI"你接了这些外部服务"，具体每个服务有哪些工具，AI 需要时再去拉取清单。

这个思想的通用性

"不要一次性把所有选项都摆出来，给一个目录 + 按需展开的机制"------这是和 AI 打交道时非常通用的一条经验，不光适用于工具，也适用于给 AI 看文件、看文档、看代码：先给索引，让 AI 自己决定深入看什么。第 5 篇讲记忆和上下文时你会看到同样的思想反复出现。

4.4 危险操作谁把关：删文件、装软件前为什么要问你一声

AI 想调工具，程序不会立刻执行，中间隔着一道权限关卡。这一章讲这道关卡怎么运作。

每个工具调用都要过一道检查

流程是这样的：

bash 复制代码

AI 提出：我要调用「跑命令」，参数是 rm -rf node_modules
        ↓
程序：先别执行，过权限关卡
        ↓
权限关卡综合判断：这个操作该不该放行？
        ↓
   ┌─ 直接允许 → 执行
   ├─ 直接拒绝 → 不执行，告诉 AI"用户拒绝了"
   └─ 拿不准 → 弹窗问用户："它要执行 rm -rf node_modules，允许吗？"
                  ↓
              用户选择：允许这次 / 永远允许这类 / 拒绝这次 / 永远拒绝这类

判断依据从哪来

权限关卡做决定时，会综合好几个来源的规则，按"从宽到严"或"明确优先"的顺序匹配：

你在本次对话里已经表过的态：比如你刚对一个命令选了"以后这类都允许"，那同类操作不再问。
你的配置文件里写死的规则 ：你可以提前写好"允许所有 npm test""禁止任何 rm -rf""所有 git 推送都要问我"。规则支持按工具 + 参数模式匹配（比如"跑命令工具，但命令必须以 npm 开头"）。
当前的工作模式 （下一章和第 10 篇会讲几种模式）：
- 普通模式：危险操作都问；
- 自动同意改文件模式：文件编辑不再问，但跑命令还问；
- 计划模式：只能只读，任何修改都不允许；
- 完全放开模式：全都不问（危险，只建议在沙盒环境用）。

为什么需要"永远允许"这类选择

如果每一次跑测试都问你一遍，一天问几十次，你会疯掉，最后无脑点"允许"，关卡就形同虚设。所以好的权限设计不是"问得越多越安全"，而是把真正需要人判断的问题问得恰到好处：

高频、低风险、意图明确的操作（跑测试、读文件），让你能一次授权、以后放行；
低频、高风险、不可逆的操作（删文件、推代码、装软件、联网外传数据），每次都问，或者默认拒绝。

这里有个产品细节值得学：权限弹窗给出的选项不是简单的"允许/拒绝"，而是"允许这次 / 永远允许这类 / 拒绝这次 / 永远拒绝这类"。这让用户的每次点击都在调教规则 ------点"永远允许 npm test"就等于往配置里加了一条规则，程序越用越懂你的边界，问得越来越少，但该问的危险操作一次不会漏。

拒绝之后会怎样

被拒绝的工具不会执行，程序会把"用户拒绝了这个操作，原因是......"作为工具结果还给 AI。AI 看到拒绝，通常会换个思路（"那我不删了，先问问用户想怎么处理"）。连续被拒绝多次时，程序还会认为"这条路走不通"，干脆结束这一轮，让用户重新指示，避免 AI 对着一堵墙反复撞。

沙盒：另一层物理防护

除了"问不问"这种软件层面的把关，还有一层物理防护叫沙盒：把程序关在一个"隔离房间"里，它在房间里随便折腾，但碰不到房间外的重要东西（比如不能联网、不能写工作目录之外的文件）。就算 AI 或程序出了错，损失也被限制在房间内。第 10 篇讲模式时会再提到。

4.5 几件事同时干：工具怎么排队、怎么打断

模型在一轮回复里可能同时要求调好几个工具（"我要同时读这三个文件"），这些工具怎么安排执行？

能并行的并行，不能并行的排队

还记得 4.1 说每个工具贴着"能不能和别人同时干"的标签吗？编排工具执行时就靠它：

能并行的：几个读文件、几个搜索之间互不干扰，就同时开工，等全部完成再一起把结果还给模型。这能明显省时间（读三个文件串行要 3 秒，并行可能只要 1 秒）。
不能并行的：跑命令这类可能改环境的工具，按模型提出的顺序一个个来，避免两个命令互相踩脚。

打个比方：厨房里，洗菜、切配菜可以同时进行（互不干扰），但炒菜和装盘有先后顺序，而且两个厨师不会同时用同一口锅。

执行中的工具怎么打断

用户按取消时（3.6 讲的总闸）：

还没开始执行的工具：直接不执行了；
正在执行的：给它发终止信号。比如跑命令工具启动的终端进程，会收到温和的终止信号，给它一点时间自己收尾（清理临时文件之类）；超时还不退出才强制杀掉。

这个"先礼后兵"很重要：直接强杀可能留下半截文件、锁死的进程。

工具结果太大怎么办：结果预算

工具产出的结果要塞回聊天记录、发给模型，而模型的容量有限。一个命令输出十万行、一个文件几万字，全塞进去会把容量吃光。所以有"结果预算"机制：

给工具结果设一个容量上限；
超了就截断，通常保留开头和结尾（开头说明做了什么，结尾是最终结果/报错，中间的过程最不重要），中间用"......（已省略 N 行）"代替；
截断处明确告诉 AI"结果被截断了，如果你需要中间部分，可以用更精确的参数重新取"。

这就像助手给你汇报工作：不会把会议录音逐字给你，而是给摘要；你要听某段细节，他再单独调那段录音。

边执行边汇报：流式执行器

还有个精巧的安排：工具在后台慢慢跑的时候，用户不必干等------可以继续输入下一句话。工具的结果出来后，会自动插到下一轮对话里，而不是把用户的话堵在半路。

这靠一个"流式执行器"协调：它同时照看"正在跑的工具"和"用户新发的内容"，让两边都不丢。体验上就是：AI 在后台跑测试，你照常补充需求，等测试结果出来了，AI 自然会结合你的新需求一起处理。

4.6 重点工具细看

最后逐个看几个最重要的工具长什么样。

跑命令（Bash）

启动一个终端进程执行命令，设置超时时间、工作目录、环境变量；
输出超长时自动只留头尾；
被标记为"不能和别人并行"（独占环境）；
是权限把关最严的工具：命令内容要过规则匹配，危险模式（删库、强推、curl 陌生脚本）格外警惕。

改文件（FileEdit）

有一条铁规：改之前必须先读过这个文件。AI 不能凭想象改一个它没看过的文件------这防止了"凭空乱改"。
修改方式是"找到原文的一段 → 换成新的一段"，而不是整体重写，这样改动精确、出问题好定位；
每次改动的红绿对比（diff）会实时显示在界面上；
改之前自动拍文件快照（后悔药的原料）。

读文件

带行号读，方便 AI 引用"第 42 行"；
文件太大时不会一次全读，提示 AI"文件很长，你可以分段读或先读关键部分"------又一次体现"别一次塞满"的思想；
纯只读，不触发快照，权限基本放行。

记待办（TodoWrite）

维护一个任务清单，每条任务有：内容、状态（待办/进行中/完成）、进行时的描述；
这个清单不只是给 AI 自己看的，界面上会显示成一个进度面板，用户随时知道"它打算干几步、现在干到哪"；
它的深层作用是强迫 AI 做事有条理：复杂任务先列计划再动手，做完一步勾一步，不容易干着干着跑偏。这是用工具设计来引导 AI 行为的典型例子。

派子助手（Agent）

这是最特别的工具：调用它等于**复制出一个"分身"**去干一件独立的子任务；
分身内部跑的是同一套核心循环（第 3 篇那台发动机），有自己的聊天记录、自己的工具；
分身干完活，只把最终结论汇报回来，中间的探索过程不污染主对话；
典型用途：主 AI 说"我要派个分身去把整个代码库里的登录相关代码摸清楚"，分身去翻几十上百个文件，最后回来一句"登录逻辑在 A、B、C 三个文件里，入口是 X"------主对话的记录里只多了这一句，干净；
分身还分不同"工种"：有专门只做调查、不改东西的"探索分身"，有专门做方案规划的"计划分身"；
第 9 篇会细讲分身机制。

搜索类（搜文件名 / 搜内容）

搜内容工具底层调用的是成熟的高速文本搜索（ripgrep 之类），能在大型代码库里秒级搜完；
这两个工具都是只读、可并行，是 AI"探索陌生代码库"时用得最多的工具；
它们也是"先索引后深入"思想的体现：先搜出"在哪些文件"，再读具体文件。

本篇小结

工具 = 给 AI 的说明书 + 给程序执行的函数。AI 只用文字表达"我要做什么"，动作全由本地程序执行------这是安全的根基。
工具的执行函数也是"边做边吐进展"的，所以界面能实时显示工具进度。
七八样核心工具永远随身（跑命令、读/改/写文件、搜文件名/内容、记待办），它们正交组合覆盖所有编程任务。
工具不是越多越好：说明书占容量、费钱、还造成选择困难。解法是三层供给------核心工具随身、进阶能力给目录按需取、外部工具现查。
权限关卡在每个工具调用前把关：综合你历史授权、配置规则、工作模式做决定，拿不准才弹窗；弹窗选项会反过来沉淀成规则，越用越少问。
工具编排讲究：能并行的并行、不能并行的排队；取消时先礼后兵；结果太大就留头去尾；用户不用干等后台工具。
重点工具里，派子助手最特别：它复制出一个跑着同款发动机的分身，独立探索后只汇报结论。

下一篇讲每次提问时，程序到底在你的一句话之外，还给 AI 塞了哪些"背景资料"。