Claude Code 源码文档 - 工具系统 (Tools)

版本: 2.1.88 | 文件数: 184 | 源码路径: src/tools/

1. 模块概述

工具系统是 Claude Code 的核心能力层，定义了 AI 可以执行的所有操作。每个工具对应一种具体能力（文件编辑、命令执行、网页搜索等），通过统一的 Tool 类型接口注册和调度。

架构设计

┌─────────────────────────────────────────┐
│           tools.ts (注册中心)             │
│  getAllBaseTools() → Tools[]             │
│  getTools(context) → 过滤后的工具列表      │
└──────────┬──────────────────────────────┘
           │
    ┌──────┴──────┐
    │   Tool.ts    │ ← 类型定义 & 接口
    │   Tool<T>    │ ← 泛型工具类型
    └──────┬──────┘
           │
   ┌───────┼───────────────────┐
   │       │                   │
 BashTool  FileEditTool  AgentTool  ...（45+工具）

2. 核心类型定义

Tool<T> 类型 (Tool.ts)

type Tool<
  T extends AnyObject = AnyObject,
  P extends ToolProgressData = ToolProgressData,
  R = unknown
> = {
  name: string                              // 工具唯一标识
  description(context) => string            // 动态描述（给模型看的）
  inputSchema: T                            // Zod schema 定义输入
  progress?: ToolCallProgress<P>            // 进度回调
  isEnabled?(context): boolean              // 是否启用
  isReadOnly?(context): boolean             // 是否只读
  needsPermissions?(context): boolean       // 是否需要权限
  canUse?(context): PermissionResult        // 权限检查
  execute(params, context): Promise<R>      // 执行逻辑
  renderToolUse?: (...) => ReactNode        // UI 渲染
  renderResult?: (...) => ReactNode         // 结果渲染
}

ToolUseContext (Tool.ts)

工具执行时的上下文对象，包含：

• permissionMode - 权限模式 (bypassPermissions, default, etc.)
• canUseTool - 权限检查函数
• options - CLI 选项
• abortController - 中断控制
• fileStateCache - 文件状态缓存
• messages - 对话历史
• tools - 可用工具列表

3. 所有工具清单

核心工具（默认启用）

工具	目录	功能
BashTool	tools/BashTool/	执行 Shell 命令，支持沙盒模式
FileReadTool	tools/FileReadTool/	读取文件内容，支持图片处理
FileEditTool	tools/FileEditTool/	精确编辑文件（搜索替换）
FileWriteTool	tools/FileWriteTool/	写入/创建文件
GlobTool	tools/GlobTool/	文件名模式匹配搜索
GrepTool	tools/GrepTool/	文件内容搜索（正则）
WebFetchTool	tools/WebFetchTool/	抓取网页内容
WebSearchTool	tools/WebSearchTool/	网页搜索
AgentTool	tools/AgentTool/	子代理系统（多Agent协作）
TaskOutputTool	tools/TaskOutputTool/	获取任务输出
TaskStopTool	tools/TaskStopTool/	停止运行中的任务
TodoWriteTool	tools/TodoWriteTool/	待办事项管理
AskUserQuestionTool	tools/AskUserQuestionTool/	向用户提问
SkillTool	tools/SkillTool/	技能系统调用
BriefTool	tools/BriefTool/	Brief/摘要工具
EnterPlanModeTool	tools/EnterPlanModeTool/	进入计划模式
ExitPlanModeV2Tool	tools/ExitPlanModeTool/	退出计划模式
SendMessageTool	tools/SendMessageTool/	发送消息
ListMcpResourcesTool	tools/ListMcpResourcesTool/	列出 MCP 资源
ReadMcpResourceTool	tools/ReadMcpResourceTool/	读取 MCP 资源
NotebookEditTool	tools/NotebookEditTool/	Jupyter Notebook 编辑
ToolSearchTool	tools/ToolSearchTool/	工具搜索
LSPTool	tools/LSPTool/	语言服务协议（代码诊断）

条件启用工具

工具	条件	功能
PowerShellTool	Windows 平台	PowerShell 命令执行
ConfigTool	USER_TYPE=ant	配置管理
TungstenTool	USER_TYPE=ant	内部工具
REPLTool	USER_TYPE=ant	REPL 交互
CronCreateTool	AGENT_TRIGGERS feature	创建定时任务
CronDeleteTool	AGENT_TRIGGERS feature	删除定时任务
CronListTool	AGENT_TRIGGERS feature	列出定时任务
RemoteTriggerTool	AGENT_TRIGGERS_REMOTE	远程触发器
SleepTool	PROACTIVE or KAIROS	延迟执行
MonitorTool	MONITOR_TOOL	监控工具
EnterWorktreeTool	worktree 模式	进入 git worktree
ExitWorktreeTool	worktree 模式	退出 git worktree
TeamCreateTool	Agent Swarms	创建团队
TeamDeleteTool	Agent Swarms	删除团队
TaskCreateTool	TodoV2	创建任务
TaskGetTool	TodoV2	获取任务
TaskUpdateTool	TodoV2	更新任务
TaskListTool	TodoV2	列出任务
MCPTool	MCP 服务配置	调用外部 MCP 工具
SendUserFileTool	KAIROS	发送文件给用户
PushNotificationTool	KAIROS	推送通知
SubscribePRTool	KAIROS_GITHUB_WEBHOOKS	订阅 PR 事件

4. 工具注册机制

工具池组装 (tools.ts)

// 获取所有基础工具
getAllBaseTools(): Tools → Tool[]

// 根据权限上下文获取可用工具
getTools(permissionContext): Tools → 过滤后的 Tool[]

// 合并工具（含 MCP 工具）
getMergedTools(context): Tools

// 组装工具池（含 MCP + 动态工具）
assembleToolPool(context): Tools

工具过滤 (filterToolsByDenyRules)

权限系统会根据以下规则过滤工具：

• Deny 规则：匹配的工具直接移除
• Blanket deny：无内容的规则匹配整个工具
• MCP 前缀：mcp__server 形式的规则过滤整个 MCP 服务

5. BashTool 详解（最复杂的工具）

BashTool 有 15+ 个支持文件：

文件	职责
prompt.ts	给模型的工具描述 prompt
bashCommandHelpers.ts	命令辅助函数
bashPermissions.ts	权限检查逻辑
bashSecurity.ts	安全沙盒
commandSemantics.ts	命令语义分析
destructiveCommandWarning.ts	危险命令警告
modeValidation.ts	模式验证
pathValidation.ts	路径验证
readOnlyValidation.ts	只读验证
sedEditParser.ts	sed 编辑解析
sedValidation.ts	sed 命令验证
shouldUseSandbox.ts	沙盒使用判断
toolName.ts	工具名定义
utils.ts	工具函数
commentLabel.ts	注释标签

6. AgentTool 子代理系统

AgentTool 是多 Agent 协作的核心：

文件	职责
runAgent.ts	运行子代理
forkSubagent.ts	Fork 子代理进程
resumeAgent.ts	恢复暂停的代理
loadAgentsDir.ts	加载代理定义目录
builtInAgents.ts	内置代理列表
agentMemory.ts	代理记忆系统
agentColorManager.ts	代理颜色管理
agentDisplay.ts	代理显示渲染

内置代理 (built-in/)

代理	功能
claudeCodeGuideAgent.ts	Claude Code 使用指南
exploreAgent.ts	代码库探索
generalPurposeAgent.ts	通用目的代理
planAgent.ts	计划代理
verificationAgent.ts	验证代理
statuslineSetup.ts	状态栏设置

7. 工具生命周期

1. 注册阶段
   getAllBaseTools() → 收集所有工具实例

2. 过滤阶段
   getTools(context) → 根据权限、feature flag 过滤
   assembleToolPool() → 加入 MCP 工具

3. 提交阶段
   QueryEngine → 将工具列表发送给 API

4. 调用阶段
   模型返回 tool_use → 匹配工具 → 检查权限 → execute()

5. 渲染阶段
   renderToolUse() → 显示工具调用 UI
   renderResult() → 显示结果 UI

6. 进度阶段
   progress() → 实时进度更新

8. 扩展：如何添加新工具

1. 在 src/tools/ 下创建新目录，如 MyTool/
2. 创建主文件 MyTool.ts，导出 Tool 对象
3. 创建 prompt.ts（工具描述）、constants.ts（常量）
4. 在 src/tools.ts 的 getAllBaseTools() 中注册
5. 如需条件启用，添加 feature flag 检查

// MyTool/MyTool.ts
export const MyTool: Tool = buildTool({
  name: 'my_tool',
  description: () => 'A custom tool',
  inputSchema: z.object({ input: z.string() }),
  async *execute({ input }, context) {
    // 实现逻辑
    yield { type: 'progress', text: 'Working...' }
    return { type: 'text', text: 'Done' }
  }
})

9. MCP 工具集成

MCP (Model Context Protocol) 工具通过 MCPTool 动态注册：

• MCPTool.ts - MCP 工具包装器
• classifyForCollapse.ts - 工具折叠分类
• MCP 服务配置在 services/mcp/ 中管理
• 支持多种传输：stdio、SSE、WebSocket