附录 B：工具定义速查表
本附录按功能分类列出全书讨论的所有 Agent 工具，供快速查阅。每个工具包含参数摘要、返回值、典型用途和所属章节。
约定：参数中
*标记为必填，其余为可选。返回值均为字符串（作为tool_result回传模型）。
B.1 文件操作工具
文件操作工具是 Agent 感知和修改代码库的主要手段。与通过 Bash 调用 cat/sed/find 相比，专用工具提供了三个工程优势：可审计性（每个操作独立的 tool_call）、权限粒度控制（读/写分离）、输出格式确定性（行号标注、结构化结果）。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| Read | file_path*, offset, limit, pages | 带行号的文件内容（cat -n 格式）；图片返回 base64 内容块；PDF 按页读取 | 读取源代码、查看配置文件、预览图片/PDF | Ch.5 |
| Write | file_path*, content* | 确认信息（如 "Updated file /path"） | 创建新文件、完整覆写已有文件（需先 Read） | Ch.5 |
| Edit | file_path*, old_string*, new_string*, replace_all | 确认信息或错误提示 | 精确替换文件中的代码片段（search-and-replace 模式） | Ch.5 |
| Glob | pattern*, path | 匹配的文件路径列表（按修改时间排序） | 按模式搜索文件（如 **/*.py），替代 find 命令 | Ch.5 |
| Grep | pattern*, path, glob, output_mode | 匹配结果（文件路径 / 匹配行及上下文 / 匹配计数） | 跨文件内容搜索（纯文本匹配，非正则），替代 grep/rg | Ch.5 |
| apply_patch | patch*（自定义 patch 格式字符串） | 成功/失败信息 | 批量编辑：一次 tool_call 完成多处修改、新增文件、删除文件、重命名 | Ch.5 |
设计要点：
- Read 默认返回带行号输出，便于后续 Edit 定位；支持
offset/limit分页，防止大文件撑爆上下文；单行超 5000 字符时自动拆分为子行。 - Edit 使用文本匹配而非行号定位——LLM 对精确文本的复述准确率远高于行号计算。默认只替换首次出现（
replace_all=False），匹配 0 次或多于 1 次时直接报错。 - apply_patch 采用无行号的自定义 patch 格式（
*** Begin Patch ... *** End Patch），通过上下文文本和@@标记定位。支持四级模糊匹配（精确 → 忽略尾部空白 → 忽略首尾空白 → Unicode 标点归一化）。
B.2 执行工具
执行工具赋予 Agent 运行任意命令和脚本的能力，是功能最强但也最危险的工具类别。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| Bash / Shell | command*, workdir, timeout, run_in_background, description | stdout + stderr 拼接（截断至 50000 字符） | 执行构建、测试、安装依赖、Git 操作等 shell 命令 | Ch.4, Ch.11 |
| Execute (js_repl) | code* | 脚本执行输出 | 在沙箱中执行 JavaScript 脚本，用于数据处理或计算 | Ch.5 |
设计要点：
- Bash 通过
shell=True（Python）或sh -c（Rust）解释命令，支持管道、重定向等完整 shell 语法。默认 120 秒超时，stdin关闭（防止交互式阻塞）。 run_in_background参数将命令交给后台线程执行（Ch.11），主循环立即获得 task_id 继续推理，结果通过通知注入机制自动送达。- 生产级实现通过沙箱（Seatbelt / Bubblewrap+seccomp / Restricted Token）在 OS 内核层面约束命令的文件系统和网络访问（Ch.4）。
- System prompt 明确禁止用 Bash 替代专用文件工具（如
cat替代 Read、grep替代 Grep），确保所有文件操作经过审计路径。
B.3 规划工具
规划工具给 Agent 提供可自我锚定的结构化状态，防止在长任务中因注意力稀释而迷失方向。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| TodoWrite | items*（数组，每项含 id*, text*, status*） | 渲染后的 todo 列表（[ ] / [>] / [x] 标记 + 进度统计） | 管理多步任务的计划与进度；每次传入完整列表（非增量） | Ch.6 |
| TaskCreate | subject*, description | 创建的任务 JSON（含分配的 id） | 在 DAG 任务图中创建新任务节点 | Ch.10 |
| TaskUpdate | task_id*, status, addBlockedBy, addBlocks | 更新后的任务 JSON | 变更任务状态、添加依赖关系；状态变为 completed 时自动解除下游阻塞 | Ch.10 |
| TaskList | （无参数） | 全部任务的文本列表（含状态标记和阻塞信息） | 查看任务全景，识别就绪任务（pending 且 blockedBy 为空） | Ch.10 |
| TaskGet | task_id* | 单个任务的完整 JSON | 查看任务详细描述、owner、依赖关系 | Ch.10 |
设计要点：
- TodoWrite 是内存中的扁平清单，适合 5 步以内的线性任务。上限 20 项，同一时刻只允许 1 个
in_progress（强制串行聚焦）。配合 Nag Reminder 机制（3 轮未调用时注入<reminder>）防止模型忘记更新。 - Task System（TaskCreate/Update/List/Get）是磁盘上的 DAG，每个任务独立存为 JSON 文件（
.tasks/task_N.json）。支持依赖关系（blockedBy+blocks双向记录）、并行识别、上下文压缩后恢复（一次 TaskList 即可重建全貌）。 - 两套规划工具互补而非替代：TodoWrite 启动快、零开销；Task System 支持依赖、持久化、多 Agent 共享。
B.4 协作工具
协作工具实现上下文隔离的分治和多 Agent 通信，从单 Agent 扩展到团队协作。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| Agent (Subagent) | prompt*, description | 子 Agent 的最终文本摘要 | 将子任务委派给独立上下文的子 Agent；中间产物不污染父对话 | Ch.12 |
| SendMessage | to*, content* | 发送确认 | 向指定 teammate 的 JSONL 邮箱发送消息 | Ch.13 |
| TeamCreate (spawn_teammate) | name*, role*, prompt* | 创建确认（含角色信息） | 创建持久化 teammate 实例，在独立线程中运行 Agent 循环 | Ch.13 |
扩展协作工具（生产级系统）：
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| list_teammates | （无参数） | 所有成员的 name/role/status 列表 | 查询团队状态（仅 Lead 可用） | Ch.13 |
| read_inbox | （无参数） | 收件箱中的消息列表（drain 后清空） | 读取发给自己的消息 | Ch.13 |
| broadcast | content* | 广播确认 | 向全体 teammate 发送消息（仅 Lead 可用） | Ch.13 |
| shutdown_request | teammate* | 请求 ID + pending 状态 | 请求 teammate 优雅关机（request-response 协议） | Ch.13 |
| shutdown_response | request_id*, approve*, reason | 批准/拒绝确认 | 响应关机请求（teammate 有权拒绝） | Ch.13 |
| plan_approval | plan* 或 request_id*, approve*, feedback | 提交确认 / 审批结果 | 执行前的计划审批协议（teammate 提交，Lead 审阅） | Ch.13 |
设计要点：
- Agent (Subagent) 的核心价值是上下文隔离。子 Agent 从空白
messages[]开始（模式 A），可能执行 30 次工具调用，但父 Agent 只收到最终摘要。子 Agent 的 tools 通常是父 Agent 的子集（移除 task 工具防止递归）。 - 三种 Subagent 模式：研究型（只读工具）、执行型（全部工具）、验证型（只读 + 测试命令）。
- Team 系统 将 Agent 从无状态函数调用升级为持久化协作实体。通信基于 JSONL 邮箱（append-only 写入，零依赖，可调试）。协议层通过 request_id + FSM 实现结构化协商（关机、计划审批）。
B.5 知识工具
知识工具实现按需加载和外部信息获取，避免将所有知识前置塞入 system prompt。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| SkillList | （无参数） | 所有已安装 skill 的名称和一句话描述 | 发现可用的 skill（Layer 1 摘要） | Ch.7 |
| SkillRead (load_skill) | name* | Skill 完整内容（<skill> 标签包裹） | 按需加载 skill 的详细指令和工作流（Layer 2 注入） | Ch.7 |
| WebSearch | query*, allowed_domains | 搜索结果摘要 | 快速事实验证、版本号查询等轻量搜索 | Ch.8 |
| WebFetch | url*, format | 网页内容（Markdown 格式） | 获取指定 URL 的页面内容 | Ch.8 |
| ToolSearch | query*, max_results | 匹配工具的完整 JSON Schema 定义 | 从延迟加载的工具存根中按需获取完整参数 Schema | Ch.8 |
设计要点：
- Skill 系统 采用两层分离架构。Layer 1（system prompt 中的名称+描述列表，每 skill 约 100 token）始终存在；Layer 2（完整 skill body，约 2000 token）仅在模型调用 SkillRead 时通过 tool_result 注入。10 个 skill 的 Layer 1 总共约 1000 token，对比前置加载的 20000 token，节省 95%。
- ToolSearch 是 Claude Code 的延迟加载机制。Prompt 中只放工具存根（名称+描述，不含完整 Schema），模型需要使用某工具时先调用 ToolSearch 获取完整定义。保持前缀稳定，不破坏 KV-cache。
- WebSearch 适合快速验证（版本号、简单事实），延迟低、无需配置。WebFetch 适合获取特定页面内容（API 文档、技术博客）。
B.6 系统工具
系统工具管理后台任务的生命周期，打破 Agent Loop 的串行瓶颈。
| 工具 | 参数摘要 | 返回值 | 典型用途 | 所属章节 |
|---|---|---|---|---|
| BackgroundRun | command* | task_id + 启动确认 | 将慢操作（构建、测试、安装）交给后台线程，主循环继续推理 | Ch.11 |
| BackgroundStatus | task_id | 任务状态 + 输出（省略 task_id 时列出全部任务） | 主动查询后台任务的执行状态和结果 | Ch.11 |
| BackgroundCancel | task_id* | 取消确认 | 请求取消正在运行的后台任务（cooperative cancellation） | Ch.11 |
设计要点：
- BackgroundRun 是 fire-and-forget 模式：模型立即获得 task_id，不等待执行结果。后台线程完成后将结果推入通知队列。
- 主循环在每次 LLM 调用前执行 drain-and-inject：原子性地取出所有已完成的后台结果，以
<background-results>XML 标签包裹注入 messages[]。模型无需主动轮询，零额外 LLM 调用。 - 通知中的结果截断至 500 字符（节省 context window），完整输出通过 BackgroundStatus 按需获取。
- Python 实现使用 daemon 线程 +
threading.Lock保护通知队列；Rust 生产实现使用 tokio 绿色线程 +CancellationToken实现结构化取消。
B.7 工具数量演进总览
下表展示了从最小 Agent 到完整系统，工具集如何逐步扩展。每一步新增工具都遵循同一模式：写 handler + 注册到 dispatch map，循环代码零改动。
| 阶段 | 工具数 | 新增工具 | 对应章节 |
|---|---|---|---|
| 最小 Agent Loop | 1 | bash | Ch.2 |
| 文件操作 | 4 | + read_file, write_file, edit_file | Ch.3, Ch.5 |
| 规划 (Flat List) | 5 | + todo | Ch.6 |
| 知识加载 | 6 | + load_skill | Ch.7 |
| 任务 DAG | 9 | + task_create, task_update, task_list, task_get | Ch.10 |
| 后台执行 | 12 | + background_run, background_status, background_cancel | Ch.11 |
| 团队协作 | 14 | + spawn_teammate, send_message (+ list_teammates, read_inbox, broadcast) | Ch.13 |
| 团队协议 | 16+ | + shutdown_request, shutdown_response, plan_approval | Ch.13 |
核心不变量：无论工具集从 1 个扩展到 16+ 个，Agent Loop 的骨架始终是同一段代码：while has_tool_calls: execute -> append -> call LLM。工具系统的可扩展性源于 Dispatch Map 的解耦设计——循环结构与具体工具实现完全独立。