# Claude Code 工具系统分析

## 1. 工具系统架构

### 1.1 工具基类 (`src/Tool.ts`, 30KB)

所有工具继承自 `Tool` 抽象类：

```
Tool
├── 元数据属性:
│   ├── name: string              # 工具名称 (如 "Bash", "Read", "Edit")
│   ├── description: string       # 功能描述 (Markdown 格式，发送给模型)
│   ├── inputSchema: ZodSchema   # 参数校验 (Zod v4)
│   ├── isEnabled: () => boolean  # 是否可用 (受 feature flag 控制)
│   └── promptCategory?: string  # 归类标签
│
├── 执行方法:
│   ├── toolUseOutput(): Promise<ToolResult>
│   │   主执行逻辑，接收模型解析的参数
│   └── renderToolUse(): ReactElement
│       工具调用消息的 UI 渲染 (Ink React 组件)
│
└── 辅助:
    ├── toolMatchesName(): 按名称/别名匹配工具
    ├── isConcurrencySafe(): 是否支持并发
    └── yieldControl(): 是否释放控制权
```

### 1.2 工具注册 (`src/tools.ts`)

`tools.ts` 将所有工具汇总导出：

```typescript
export function getTools(): Tools {
  const baseTools = [
    AgentTool, SkillTool, BashTool, PowerShellTool,
    FileEditTool, FileReadTool, FileWriteTool,
    GlobTool, GrepTool, NotebookEditTool,
    WebFetchTool, WebSearchTool, TaskStopTool,
    TaskOutputTool, TodoWriteTool, ExitPlanModeV2Tool,
    AskUserQuestionTool, LSPTool, ListMcpResourcesTool,
    ReadMcpResourceTool, ToolSearchTool, EnterPlanModeTool,
    EnterWorktreeTool, ExitWorktreeTool, ...
  ]
  // 条件工具 (feature flag 控制)
  if (feature('PROACTIVE')) baseTools.push(SleepTool)
  if (feature('AGENT_TRIGGERS')) baseTools.push(...cronTools)
  // ...
}
```

### 1.3 工具调用流程

```
模型响应
  │
  ├── content_block.type === 'tool_use'
  │   ├── 解析工具名和参数 (JSON → Zod 校验)
  │   ├── 权限检查: useCanUseTool(toolName, params)
  │   │   ├── bypass → 直接放行
  │   │   ├── auto_accept → 自动批准 (特定模式)
  │   │   └── 需要确认 → 弹出权限请求 UI
  │   │
  │   ├── 执行: tool.toolUseOutput(params)
  │   │   ├── 实时流式输出 (Shell 命令)
  │   │   └── 返回 ToolResult
  │   │
  │   └── 结果回传模型: { type: 'tool_result', content: [...] }
  │
  └── content_block.type === 'text'
      └── 直接渲染 Markdown 到终端
```

## 2. 完整工具清单

### 2.1 文件系统工具

#### BashTool (`tools/BashTool/`)
- **功能**: 执行 Shell 命令 (bash/sh/zsh)
- **参数**: `command`, `description`, `timeout`, `dangerouslyDisableSandbox`
- **安全**: 沙箱模式、危险命令检测、命令白名单/黑名单
- **输出**: stdout + stderr 流式返回

#### PowerShellTool (`tools/PowerShellTool/`)
- **功能**: Windows PowerShell 命令执行
- **参数**: 同 BashTool，适配 PowerShell 语法

#### FileReadTool (`tools/FileReadTool/`)
- **功能**: 读取文件内容（支持分段、PDF、图片）
- **参数**: `file_path`, `offset?`, `limit?`, `pages?`
- **特性**: 图片自动识别显示，PDF 分页，大文件分段

#### FileWriteTool (`tools/FileWriteTool/`)
- **功能**: 创建/覆盖文件
- **参数**: `file_path`, `content`
- **约束**: 不在已有文件未读取时直接覆盖

#### FileEditTool (`tools/FileEditTool/`)
- **功能**: 基于字符串匹配的精准文件编辑
- **参数**: `file_path`, `old_string`, `new_string`, `replace_all?`
- **特性**: 
  - 要求 `old_string` 在文件中唯一（避免歧义编辑）
  - 支持 `replace_all` 全局替换
  - Diff 渲染展示变更

#### GlobTool (`tools/GlobTool/`)
- **功能**: 文件名模式搜索
- **参数**: `pattern`, `path?`
- **底层**: 使用 fast-glob / Bun 文件系统 API

#### GrepTool (`tools/GrepTool/`)
- **功能**: 文件内容正则搜索
- **参数**: `pattern`, `path?`, `glob?`, `output_mode?`, `-i?`, `multiline?`, `head_limit?`
- **底层**: 调用 ripgrep (rg) 可执行文件

#### NotebookEditTool (`tools/NotebookEditTool/`)
- **功能**: 编辑 Jupyter Notebook (.ipynb) 文件
- **参数**: `notebook_path`, `cell_id?`, `new_source`, `cell_type?`, `edit_mode?`
- **操作**: 替换/插入/删除 Cell

### 2.2 AI 编排工具

#### AgentTool (`tools/AgentTool/`)
- **功能**: 启动子 Agent 处理复杂任务
- **参数**: `description` (3-5 词), `prompt` (任务描述), `subagent_type?`, `model?`, `run_in_background?`
- **Agent 类型**:
  - `general-purpose` — 通用 Agent（默认有全部工具）
  - `statusline-setup` — 配置状态栏
  - `claude-code-guide` — 回答 Claude Code 使用问题
- **执行模式**:
  - 前台：等待结果返回后继续
  - 后台 (`run_in_background: true`)：异步执行，完成时通知

#### SkillTool (`tools/SkillTool/`)
- **功能**: 执行可用技能
- **参数**: `skill` (技能名), `args?`
- **技能来源**: 内置技能 + 用户自定义 + MCP 技能

#### BriefTool (`tools/BriefTool/`)
- **功能**: 对指定内容做摘要/压缩
- **参数**: `content`, `instruction?`

#### AskUserQuestionTool (`tools/AskUserQuestionTool/`)
- **功能**: 在工具调用流程中向用户提问
- **参数**: `questions[]` (含选项、多选、预览等)
- **特性**: 渲染交互式选项 UI

### 2.3 任务管理工具

#### TaskCreateTool
- **功能**: 创建结构化任务
- **参数**: `subject`, `description`, `activeForm?`, `metadata?`

#### TaskListTool
- **功能**: 列出所有任务及其状态

#### TaskGetTool
- **功能**: 获取指定任务的完整详情

#### TaskUpdateTool
- **功能**: 更新任务状态/属性/依赖
- **参数**: `taskId`, `status?`, `subject?`, `addBlocks?`, `addBlockedBy?`

#### TaskOutputTool
- **功能**: 获取后台任务的输出

#### TaskStopTool
- **功能**: 停止运行中的任务

#### TodoWriteTool (`tools/TodoWriteTool/`)
- **功能**: 写入待办列表

### 2.4 Web 工具

#### WebFetchTool
- **功能**: 获取网页内容并分析
- **参数**: `url`, `prompt` (从页面提取什么信息)
- **特性**: HTML → Markdown 转换，15分钟缓存

#### WebSearchTool
- **功能**: Web 搜索
- **参数**: `query`, `allowed_domains?`, `blocked_domains?`
- **要求**: 结果需标注来源

#### WebBrowserTool
- **功能**: 浏览器自动化操作

### 2.5 计划/Worktree 工具

#### EnterPlanModeTool
- **功能**: 进入计划模式，用于复杂任务的设计阶段
- **触发条件**:
  1. 新功能实现
  2. 多种可行方案
  3. 涉及架构决策
  4. 多文件变更

#### ExitPlanModeTool
- **功能**: 退出计划模式，提交方案供用户审批

#### EnterWorktreeTool
- **功能**: 创建 Git Worktree 隔离工作区
- **参数**: `name?` (可选名称)

#### ExitWorktreeTool
- **功能**: 退出 Git Worktree
- **参数**: `action` ("keep"|"remove"), `discard_changes?`

### 2.6 MCP 工具

#### MCPTool
- **功能**: 调用 MCP 服务端提供的通用工具

#### McpAuthTool
- **功能**: MCP 服务端 OAuth 认证

#### ListMcpResourcesTool
- **功能**: 列出 MCP 服务端提供的资源

#### ReadMcpResourceTool
- **功能**: 读取指定 MCP 资源

### 2.7 协作/通信工具

#### SendMessageTool
- **功能**: 向用户发送消息通知

#### SendUserFileTool
- **功能**: 发送文件给用户 (ANT/KAIROS)

#### PushNotificationTool
- **功能**: 推送通知 (KAIROS)

#### TeamCreateTool / TeamDeleteTool
- **功能**: 创建/删除团队

#### ListPeersTool
- **功能**: 列出在线同伴/协作者

### 2.8 调度/监控工具

#### ScheduleCronTool (3个子工具)
- `CronCreateTool` — 创建定时任务
- `CronListTool` — 列出定时任务
- `CronDeleteTool` — 删除定时任务
- **特性**: 支持 Cron 表达式，Jitter 偏移

#### MonitorTool
- **功能**: 主动监控检查

#### RemoteTriggerTool
- **功能**: 远程触发任务执行

#### SleepTool
- **功能**: 休眠/等待指定时间
- **用途**: 定时任务等待 (PROACTIVE 模式)

### 2.9 专用工具

#### LSPTool
- **功能**: 调用 LSP (Language Server Protocol) 获取代码智能

#### ToolSearchTool
- **功能**: 搜索可用工具

#### ConfigTool
- **功能**: 读写配置项

#### CtxInspectTool
- **功能**: 检查当前上下文状态

#### DiscoverSkillsTool
- **功能**: 发现可用技能

#### SnipTool
- **功能**: 从内容中裁剪/截取片段

#### WorkflowTool
- **功能**: 执行预定义工作流

#### SubscribePRTool
- **功能**: 订阅 GitHub PR 状态更新

#### VerifyPlanExecutionTool
- **功能**: 验证计划是否正确执行

#### TerminalCaptureTool
- **功能**: 捕获终端输出截图

#### SyntheticOutputTool
- **功能**: 生成合成输出数据

#### ReviewArtifactTool
- **功能**: 审查产出物（代码审查）

#### TungstenTool
- **功能**: 特殊内部工具（少量使用）

#### OverflowTestTool
- **功能**: 溢出/边界测试（仅测试用）

#### REPLTool
- **功能**: 执行 REPL 代码片段 (ANT Only)

#### SuggestBackgroundPRTool
- **功能**: 后台建议创建 PR (ANT Only)

### 2.10 测试工具

#### TestingPermissionTool
- **功能**: 权限系统测试

---

## 3. 工具安全模型

### 3.1 权限层级

```
permissionMode:
  ├── default          # 每次询问
  ├── acceptEdits      # 自动批准文件编辑
  ├── bypass           # 完全跳过权限
  ├── plan             # 计划模式（只读+计划工具）
  └── custom           # 自定义规则
```

### 3.2 权限检查流程

```typescript
async function useCanUseTool(toolName, params, context) {
  // 1. 检查是否 bypass 模式
  if (permissionMode === 'bypass') return true;

  // 2. 检查工具白名单/黑名单
  if (isInDenyList(toolName)) {
    showDenialMessage();
    return false;
  }

  // 3. 检查 auto-accept 规则
  if (isAutoAcceptable(toolName, params)) return true;

  // 4. 弹出权限请求 UI 等待用户确认
  const approved = await showPermissionDialog(toolName, params);
  return approved;
}
```

### 3.3 沙箱系统

`BashTool` 支持沙箱模式：
- 网络隔离 (阻止出站连接)
- 文件系统只读挂载
- 进程隔离

由 `@anthropic-ai/sandbox-runtime` 提供，通过 `dangerouslyDisableSandbox` 参数控制。

---

## 4. 工具体系统计

| 分类 | 数量 |
|---|---|
| 文件系统 | 8 |
| AI 编排 | 4 |
| 任务管理 | 8 |
| Web | 3 |
| 计划/Worktree | 4 |
| MCP | 4 |
| 协作/通信 | 6 |
| 调度/监控 | 6 |
| 专用工具 | 15+ |
| 测试 | 1 |
| **总计** | **约 60 个工具** |

---

*本文档基于 2026-06-11 源码状态生成*