夜雨聆风AI应用实录 · Claude Code 源码拆解 · 第三章
拆解 Claude Code 45+ 个工具背后的五要素协议、并发分区策略和零等待流式引擎
Maslow 那句话在工程师圈子里流传甚广：如果你只有一把锤子，所有问题都像钉子。
放进 Claude Code 的语境——如果 Agent 只有一个 BashTool，它会把所有操作都变成 Shell 命令：读文件用 cat，搜代码用 grep，改内容用 sed。能跑，但糙。
Claude Code 选了另一条路：45+ 个专门化工具，每个工具只干一件事，干到位。这篇拆的就是这套工具系统的完整架构——从单个工具的类型契约，到多工具并发调度，再到流式执行引擎的状态机。
每个工具都遵循一个统一的类型契约：Tool<Input, Output, Progress>。三个泛型参数分别对应输入结构、输出结构和流式进度的数据类型。
这个协议要求每个工具必须实现五个要素：
▲ 五要素协议
五要素之间有清晰的递进关系：名称是身份证，Schema 是使用说明书，权限模型是准入边界，执行逻辑是实际能力，UI 渲染是对外表达。
要素一：名称与别名
别名机制揭示了一个工程原则：在公开 API 中，重命名是"只增不减"的操作。
SearchTool 改名为 GrepTool 时，旧名称必须通过别名保持可用——否则依赖旧名称的配置和脚本会静默失效。工具查找函数同时检查主名称和别名，这是对历史包袱的优雅处理。
要素二：Zod Schema 的双重职责
Zod Schema 干两件事：
运行时验证——LLM 生成的参数在执行前必须过 Zod 解析。LLM 的输出是概率性的，工具不能信任外部输入，必须自我保护。
API 通信——Zod Schema 转换为 JSON Schema 发给模型 API，让模型知道每个参数的含义和约束。Schema 里的 describe() 注释，就是工具对模型说的使用说明。
要素三：三层权限防护
三个权限方法构成分层防护：
▲ 三层权限模型
三层各管一件事：数据验证不关心权限策略，权限策略不关心并发调度。串联起来就是完整防护。
要素四：执行逻辑与 contextModifier
call() 方法返回的结果携带一个可选的 contextModifier——工具执行后修改上下文的唯一通道。
FileWriteTool 写完文件后通过 contextModifier 更新文件状态缓存，后续的 FileReadTool 才能看到最新内容。没有这个机制，工具之间就是信息孤岛。
要素五：六个 UI 渲染方法
renderToolUseMessage | |
renderToolUseProgressMessage | |
renderToolResultMessage | |
renderToolUseRejectedMessage | |
renderToolUseErrorMessage | |
renderGroupedToolUse |
六个方法覆盖了工具调用的生老病死——开始、进行中、成功、被拒、出错、并行分组。每个方法返回 React.ReactNode，UI 表现可以像 React 组件一样灵活组合。
buildTool：默认最严格
buildTool 是创建工具的标准工厂函数，遵循 fail-closed 原则：安全相关的属性默认取最严格值。isConcurrencySafe 默认 false，isReadOnly 默认 false——工具必须显式声明自己安全，才能走并发快车道。
跟机场安检一个逻辑：默认所有行李都要过机器，只有特殊认证才能走快速通道。
45+ 工具的并发安全分布
getAllBaseTools() 是所有内建工具的注册中心：
超过一半标记为并发不安全——反映了一个事实：Agent 系统中大多数操作都有副作用，真正能安全并行的（纯读取、纯搜索）是少数。
死代码消除：不只是优化体积
工具注册大量使用条件导入实现编译期死代码消除。功能开关关闭时，对应工具的整个模块不会进入最终构建。
安全层面的意义：如果调试工具、REPL 工具被包含在外部构建中，即使不可调用，也可能通过代码分析泄露内部架构信息。死代码消除从源头堵住了这个口子。
四层过滤管线
从 getAllBaseTools() 到最终发送给 API 的工具列表，经过四层过滤：
▲ 工具过滤管线
最后一步的排序值得注意：工具按名称排序是为了确保 prompt 缓存稳定性。如果每次请求工具顺序不同，缓存不断失效，白白浪费 token。
延迟工具发现：目录索引而非百科全书
工具数量超过阈值时，Claude Code 启用延迟发现机制。
传统做法：把所有工具的完整 Schema 塞进初始 system prompt，工具越多 token 消耗越大。
延迟发现：初始 prompt 只放工具名称列表，模型通过 ToolSearchTool 按需加载完整 Schema。
▲ 延迟工具发现
就像把百科全书换成目录索引——模型知道有哪些工具可用，需要时再翻到具体那页。当 MCP 服务器注册了几十个工具时，这招能省不少 token。
哪些工具不能延迟？显式标记 alwaysLoad 的不延迟（如 AgentTool，子智能体是核心能力）；ToolSearchTool 自己不延迟（否则它自己都找不到）；MCP 工具总是延迟。
BashTool：最强大，也最需要被约束
BashTool 是整个工具系统的特例，有几个其他工具没有的行为：
错误传播：BashTool 执行失败时，取消所有并行的 Bash 调用。Bash 命令之间往往有隐式依赖——mkdir 失败意味着后续执行环境已损坏，继续跑只会制造更多错误。快速失败是唯一正确的做法。
语义分析：BashTool 会对命令做 AST 解析，判断它是搜索/只读操作（isSearchOrReadCommand），决定 UI 是否折叠展示。工具不只是被动执行命令的管道，还能理解命令的语义。
沙盒集成：通过沙盒配置控制命令执行边界。即使在 bypass 权限模式下，沙盒仍然限制文件系统访问范围——最后一道安全网。
文件三件套：故意少了 Delete
FileReadTool、FileEditTool、FileWriteTool 构成文件操作的完整能力集，但刻意没有 Delete——删除不可逆，必须走 BashTool 的 rm 命令，触发更严格的权限检查。
FileReadTool 维护文件状态缓存，追踪哪些文件已被读取，避免同一轮次重复注入内容。
FileEditTool 用的是 old_string → new_string 精确替换，而不是行号范围。原因很实际：行号是脆弱的——如果读取和编辑之间另一个工具改了文件，行号就偏了。字符串匹配是幂等的，目标片段存在就能精确定位。
FileEditTool 还有个 isDestructive 方法，根据编辑内容（比如删除大量代码）判断是否为破坏性操作——比简单的"写入即破坏性"标签精确得多。
FileWriteTool 完全覆写文件，权限最严。三个工具都支持 contextModifier，执行后更新缓存，确保后续工具调用看到最新状态。
搜索双雄：专门化胜过通用化
BashTool 能用 find 和 grep 实现同样功能，但 GlobTool 和 GrepTool 有三个优势：
1.结构化输出：返回结构化结果列表，模型解析更准确，不用处理 Shell 文本输出。
2.更宽松的权限：搜索工具默认只读，不触发写入确认提示。
3.性能更好：GrepTool 底层走 ripgrep，比 Shell 的 grep 快几倍，还能控制最大结果数避免输出爆炸。
AgentTool：子智能体的入口
AgentTool 通过 createSubagentContext 为每个子智能体创建独立的 ToolUseContext：继承父上下文的权限规则，但消息列表完全独立。"继承但不共享"——子智能体不能意外改动父智能体的状态。
AgentTool 被标记为 alwaysLoad，确保延迟发现启用时它仍然在第一轮就可见。
工具编排引擎同时追求三个目标：最大化并行度、保障执行安全、保证结果顺序。三者天然矛盾，引擎的设计就是在矛盾中找精确平衡。
runTools() 与并发分区策略
runTools 基于并发分区调度多个工具调用：
▲ 并发分区策略
为什么 Read(c.ts) 不能和 Bash(ls) 放在同一批次？Bash 命令可能有副作用——创建文件、修改内容、改变目录结构。如果 Bash 执行时同时读文件，Read 可能读到旧数据或中间状态。串行确保 Read(c.ts) 看到的是 Bash 完成后的确定状态。
并发度上限由环境变量控制，默认 10。
StreamingToolExecutor：零等待的四阶段状态机
传统做法：等模型响应完整结束，再批量执行工具。
StreamingToolExecutor 的做法：流式接收到工具调用块时立即启动执行，不等模型响应完成。
性能差距很直观：假设模型生成完整响应要 2 秒，五个工具每个执行 1 秒。传统方式 7 秒（2+5），流式模式约 3 秒——快了一倍多。
每个工具的四阶段状态机：
▲ 四阶段状态机
四个关键决策：
顺序保证：工具可以并行完成，但结果输出保持和请求相同的顺序。收集函数遍历工具列表时，遇到未完成的非安全工具立即停止——允许并行执行提升速度，但结果呈现严格有序。
差异化错误传播：BashTool 失败取消所有并行兄弟工具（环境可能已损坏）；非 Bash 工具的错误不传播（读取和搜索是局部操作，互相独立）。
进度消息绕过顺序约束：执行中的进度消息立即输出，不等前序工具完成。进度是"提示性"的，结果是"事实性"的——前者不需要严格顺序。
流式回退的丢弃机制：模型切换到 fallback 时，所有待执行和执行中的工具标记为废弃。模型改变策略时，旧策略的工具结果全部作废。
状态机在对话主循环中的集成
▲ 状态机与主循环集成
上下文传播是整个集成的关键：工具执行后通过 contextModifier 修改上下文，传播回对话循环，影响后续工具的执行环境。如果工具 A 写了文件但缓存没更新，后续工具 B 会基于旧缓存做出错误决策。
1. 五要素协议是工具系统的 DNA。 名称、Schema、权限、执行、渲染——每个工具围绕这五个维度定义自己。buildTool 的 fail-closed 默认值确保简单工具只需关注核心逻辑，安全性自动兜底。
2. 死代码消除不只是优化，是安全保障。 条件导入 + tree-shaking，确保内部工具不出现在外部构建中。防的不只是代码体积，是信息泄漏。
3. 并发分区是性能杠杆。 正确标记只读工具为 isConcurrencySafe=true，Agent 就能在单轮中并行跑多个搜索和读取操作。标错的代价是数据竞争。
4. StreamingToolExecutor 实现零等待调度。 模型还在生成 tool_use 块时工具就开始执行，四阶段状态机在并行性和顺序一致性之间找到平衡。快了一倍多不是靠算法优化，是靠架构思路转变。
5. 工具系统的扩展性来自类型契约。Tool<Input, Output, Progress> 让每个工具有独立的类型空间，加新工具不需要动编排引擎。系统边界开放，接口稳定。
下一章进入权限管线。工具系统给了 Agent 行动的能力，权限管线决定的是行动的边界——Claude Code 怎么在"自主执行"和"安全保障"之间卡住那条线。
— END —
