跳到主要内容

工具系统总览

工具系统是 Claude Code 的核心能力载体。每个工具都是一个自包含的能力单元，拥有独立的输入 Schema（Zod 定义）、权限规则和执行逻辑。Claude 模型通过 Anthropic API 的 Tool Use 机制调用这些工具。

工具架构​

┌──────────────────────────────────────┐
│           Claude LLM 模型            │
│    (决定调用哪个工具，传入参数)          │
├──────────────────────────────────────┤
│           工具注册表 (tools.ts)        │
│    (维护所有可用工具的列表和元数据)      │
├──────────────────────────────────────┤
│          权限系统 (Permission)         │
│    (检查工具调用是否被允许)             │
├──────────────────────────────────────┤
│          Schema 校验 (Zod v4)         │
│    (校验 LLM 传入的参数是否合法)        │
├──────────────────────────────────────┤
│          工具执行器 (Tool Runner)      │
│    (执行具体工具逻辑，返回结果)         │
└──────────────────────────────────────┘

工具定义结构​

每个工具遵循统一的接口定义（Tool.ts，792 行）：

interface Tool {
  name: string;               // 工具名称
  description: string;        // 工具描述（给 LLM 看的）
  inputSchema: ZodSchema;     // 输入参数 Schema
  isReadOnly?: boolean;       // 是否为只读操作
  isBuiltIn?: boolean;        // 是否为内置工具
  requiresPermission?: boolean; // 是否需要用户授权
  execute(input: ToolInput): Promise<ToolResult>;
}

工具分类总览​

类别工具数说明
文件操作5读、写、编辑、Notebook、目录操作
搜索分析4Glob、Grep、WebSearch、WebFetch
Agent 编排6子 Agent、消息传递、团队、计划模式
MCP 工具3MCP 工具调用、资源读取
执行与自动化5Bash、Cron、RemoteTrigger、Sleep
任务管理4创建、更新、查询、停止任务
模式切换4计划模式、Worktree、用户提问
其他12+Skill、Config、PowerShell 等

工具执行流程​

1. LLM 决定调用工具
   ↓
2. 提取工具名称和参数
   ↓
3. 在注册表中查找工具
   ↓
4. Zod Schema 校验输入参数
   ↓
5. 权限系统检查（是否需要用户确认）
   ↓
6. 执行工具逻辑
   ↓
7. 返回结果给 LLM
   ↓
8. LLM 根据结果继续推理或输出

权限模式​

工具调用支持多种权限模式：

模式行为
default危险操作需要用户确认
plan只允许只读操作
bypassPermissions跳过所有权限检查
auto智能判断是否需要确认
acceptEdits自动接受文件编辑
dontAsk不询问，直接执行

工具注册​

工具通过 tools.ts (354 行) 统一注册：

// 工具注册表
const allTools = [
  BashTool,
  FileReadTool,
  FileWriteTool,
  FileEditTool,
  GlobTool,
  GrepTool,
  AgentTool,
  MCPTool,
  // ...更多工具
];

注册时会为每个工具生成：

  • API 格式的工具描述（供 LLM 使用）
  • 权限规则映射
  • 输入/输出类型定义