第五章 工具系统：40+ 工具的设计与实现

导读｜读完这章能做什么

• 参考 buildTool() 工厂模式设计自己的工具框架
• 用 maxResultSize + 磁盘持久化解决上下文溢出
• 了解 40+ 工具的分类和能力边界

工具框架核心: Tool.ts

泛型工具类型

Tool<Input, Output, Progress>

每个工具定义:

• 输入 Schema — Zod 校验
• 权限模型 — checkPermissions()
• 执行逻辑 — call()
• UI 渲染 — renderToolResultMessage() / renderToolUseMessage()
• 进度回调 — onProgress

buildTool() 工厂模式

提供合理默认值的工具构建工厂，避免每个工具重复定义通用方法。

ToolUseContext — 上下文对象模式

单一参数对象替代多参数:

{
  options,           // 配置选项
  abortController,   // 取消控制器
  stateManager,      // 状态管理
  permissionContext,  // 权限上下文
  uiCallbacks,       // UI 回调
  readFileTimestamps, // 文件读取时间戳追踪
}

好处: 子 Agent 上下文克隆时只需浅拷贝一个对象。

核心工具详解

BashTool — 最复杂的工具 (161KB)

文件组成:

• BashTool.tsx — 主实现
• bashPermissions.ts (101KB) — 权限规则匹配
• bashSecurity.ts (105KB) — 危险命令检测

关键特性:

危险模式检测:

rm -rf, dd if=/dev/zero, 凭证窃取, 数据外泄
→ 通过 Bash AST 解析进行模式匹配 (utils/bash/ast.ts)
→ 不是简单字符串匹配

AgentTool — 第二复杂 (235KB)

子 Agent 生成系统:

• 子 Agent 类型通过 loadAgentsDir.ts 动态加载
• 支持模型覆盖 (sonnet / opus / haiku)
• 隔离模式: worktree (git checkout) 或 remote (CCR 云端)
• 后台执行 + 完成通知

Agent 记忆系统:

• 每个 Agent 类型有独立记忆快照
• 父子上下文隔离
• 记忆附件支持嵌套 Agent

Fork 子 Agent (Feature: FORK_SUBAGENT):

• 子 Agent 继承父的完整上下文和 system prompt
• 利用字节级相同的 fork children 实现 prompt cache 共享
• 防递归 fork 保护 (FORK_BOILERPLATE_TAG)

设计要点: Fork Agent 的 prompt 与父完全一致，因此 Anthropic API prompt cache 能直接命中，不需要重新编译 system prompt，显著节省 Token 和延迟。

FileReadTool (40KB)

多格式支持:

FileEditTool (21KB)

安全特性:

• 文件大小限制: 1 GiB
• 编辑期间文件修改检测 (防冲突)
• 行尾格式保留 (CRLF vs LF)
• Git diff 追踪支持撤销
• 文件编辑历史: fileHistoryTrackEdit()

完整工具清单

文件操作

执行

网络

协议

任务管理

交互

工作流

团队

工具结果大小管理

核心问题与解法: LLM 上下文窗口有限，但工具可能返回很大的结果。解决方式是将大型结果存盘，只给模型发送摘要。