03.1 工具家族

关注源码

• src/tools/*
• src/tools/shared/*
• src/tools.ts

这层真正承载什么

工具层定义的是“模型能调用哪些能力”，不是“程序内部有哪些 helper”。因此工具家族的划分，基本就对应了产品能力面。

主要工具家族

1. 工作区与执行环境工具

代表目录：

• BashTool
• PowerShellTool
• FileReadTool
• FileEditTool
• FileWriteTool
• NotebookEditTool
• GlobTool
• GrepTool

这组工具直接作用于：

• 文件系统
• shell
• notebook / structured file edit
• 搜索与读取

它们通常也是权限、安全与 sandbox 规则最重的一组工具。

2. 智能体与协作工具

代表目录：

• AgentTool
• SendMessageTool
• TeamCreateTool
• TeamDeleteTool
• TaskOutputTool
• TaskStopTool

这组工具的特点是：它们不是直接做业务动作，而是创建、控制或观察其他执行单元。

3. 计划与上下文工具

代表目录：

• TodoWriteTool
• TaskCreateTool / TaskGetTool / TaskUpdateTool / TaskListTool
• EnterPlanModeTool
• ExitPlanModeTool
• EnterWorktreeTool
• ExitWorktreeTool
• SkillTool
• AskUserQuestionTool

这些工具直接改写 agent 的工作方式、计划状态、工作区边界或上下文策略。

4. 外部能力接入工具

代表目录：

• MCPTool
• ListMcpResourcesTool
• ReadMcpResourceTool
• LSPTool
• WebFetchTool
• WebSearchTool
• RemoteTriggerTool

它们是外部系统进入工具池的入口。

5. 平台/增强类工具

代表目录：

• BriefTool
• ConfigTool
• ScheduleCronTool
• ToolSearchTool
• SyntheticOutputTool
• REPLTool

这类工具更多承担运行时增强、平台接入或特殊模式适配。

工具家族背后的共同约束

权限不是外挂逻辑

每个工具本身就要声明：

• 是否只读
• 是否 destructive
• 是否需要交互
• 如何检查 permissions

因此安全语义属于工具定义的一部分，而不是工具外面套一层通用中间件就结束。

UI 语义跟着工具走

大多数工具都提供：

• tool use message
• tool result message
• progress message
• rejected / error message

这让 UI 能基于工具语义做专用展示，而不是把所有结果都当成纯文本。

部分工具本身就是运行时桥

例如：

• AgentTool 把子智能体纳入工具系统
• REPLTool 把 primitive tools 包进 VM/REPL
• ToolSearchTool 把 deferred tools 拉回主能力面

它们不是边缘工具，而是运行时结构的一部分。

读代码时建议关注

• 基础文件工具的 isReadOnly / checkPermissions / getActivityDescription。
• ToolSearchTool 如何影响其他工具是否直接暴露给模型。
• AgentTool 和 TaskOutputTool 如何把“后台对象”重新接入 transcript。