claude-code/docs/tool-system.md

# 工具系统分析

## 架构概述

工具系统是 Claude Code 的核心能力层，定义了 Agent 可以执行的所有操作。每个工具是一个自包含模块，包含输入 Schema、权限模型和执行逻辑。

```mermaid
classDiagram
    class Tool {
        +string name
        +string description
        +ToolInputJSONSchema inputSchema
        +isEnabled() boolean
        +getDescription() string
        +getPrompt() string
        +execute(input, context) ToolResult
        +validateInput(input) ValidationResult
    }

    class BashTool {
        +name = "Bash"
        +execute() 运行 Shell 命令
        +沙盒支持
        +安全验证
    }

    class FileReadTool {
        +name = "Read"
        +支持图片/PDF/Notebook
        +行号范围读取
    }

    class FileWriteTool {
        +name = "Write"
        +完整文件写入
        +读取前置检查
    }

    class FileEditTool {
        +name = "Edit"
        +字符串替换编辑
        +replace_all 模式
    }

    class GlobTool {
        +name = "Glob"
        +文件模式匹配
        +基于 ripgrep
    }

    class GrepTool {
        +name = "Grep"
        +内容正则搜索
        +ripgrep 集成
    }

    class AgentTool {
        +name = "Agent"
        +子代理生成
        +worktree 隔离
        +代理类型选择
    }

    class MCPTool {
        +MCP 服务器工具调用
    }

    class LSPTool {
        +LSP 操作
        +goToDefinition 等
    }

    class WebFetchTool {
        +URL 内容获取
    }

    class WebSearchTool {
        +Web 搜索
    }

    Tool <|-- BashTool
    Tool <|-- FileReadTool
    Tool <|-- FileWriteTool
    Tool <|-- FileEditTool
    Tool <|-- GlobTool
    Tool <|-- GrepTool
    Tool <|-- AgentTool
    Tool <|-- MCPTool
    Tool <|-- LSPTool
    Tool <|-- WebFetchTool
    Tool <|-- WebSearchTool
```

## 工具注册机制

工具注册在 `src/tools.ts` 中，通过 `getAllBaseTools()` 函数集中管理：

```mermaid
flowchart TD
    A[getAllBaseTools] --> B{环境判断}
    B -->|默认| C[核心工具集]
    B -->|USER_TYPE=ant| D[内部工具集]
    B -->|feature flag| E[特性开关工具]

    C --> F[AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool, NotebookEditTool, WebFetchTool, WebSearchTool, AskUserQuestionTool, SkillTool, BriefTool, TaskStopTool, TodoWriteTool, ExitPlanModeV2Tool, ListMcpResourcesTool, ReadMcpResourceTool]

    D --> G[ConfigTool, TungstenTool, REPLTool, SuggestBackgroundPRTool]

    E --> H[SleepTool PROACTIVE/KAIROS]
    E --> I[CronCreateTool/CronDeleteTool/CronListTool AGENT_TRIGGERS]
    E --> J[RemoteTriggerTool AGENT_TRIGGERS_REMOTE]
    E --> K[EnterWorktreeTool/ExitWorktreeTool]
    E --> L[TeamCreateTool/TeamDeleteTool]
    E --> M[SendMessageTool]
    E --> N[ToolSearchTool]
    E --> O[WorkflowTool WORKFLOW_SCRIPTS]
    E --> P[WebBrowserTool WEB_BROWSER_TOOL]
    E --> Q[MonitorTool MONITOR_TOOL]
    E --> R[PowerShellTool]
```

## 工具分类

### 文件操作类
| 工具 | 名称 | 功能 |
|------|------|------|
| FileReadTool | Read | 读取文件（支持图片、PDF、Jupyter Notebook） |
| FileWriteTool | Write | 创建或覆盖文件 |
| FileEditTool | Edit | 部分文件修改（字符串替换） |
| GlobTool | Glob | 文件模式匹配搜索 |
| GrepTool | Grep | 基于 ripgrep 的内容搜索 |
| NotebookEditTool | NotebookEdit | Jupyter Notebook 编辑 |

### 执行类
| 工具 | 名称 | 功能 |
|------|------|------|
| BashTool | Bash | Shell 命令执行（含沙盒） |
| PowerShellTool | PowerShell | Windows PowerShell 命令 |

### 网络类
| 工具 | 名称 | 功能 |
|------|------|------|
| WebFetchTool | WebFetch | 获取 URL 内容 |
| WebSearchTool | WebSearch | Web 搜索 |

### 代理和协调类
| 工具 | 名称 | 功能 |
|------|------|------|
| AgentTool | Agent | 生成子代理（支持 worktree 隔离） |
| SendMessageTool | SendMessage | 代理间消息传递 |
| TeamCreateTool | TeamCreate | 创建代理团队 |
| TeamDeleteTool | TeamDelete | 删除代理团队 |
| TaskCreateTool | TaskCreate | 创建任务 |
| TaskGetTool | TaskGet | 获取任务详情 |
| TaskUpdateTool | TaskUpdate | 更新任务状态 |
| TaskListTool | TaskList | 列出所有任务 |
| TaskOutputTool | TaskOutput | 获取后台任务输出 |
| TaskStopTool | TaskStop | 停止后台任务 |

### 交互类
| 工具 | 名称 | 功能 |
|------|------|------|
| AskUserQuestionTool | AskUserQuestion | 向用户提问获取输入 |
| EnterPlanModeTool | EnterPlanMode | 进入计划模式 |
| ExitPlanModeV2Tool | ExitPlanMode | 退出计划模式 |
| EnterWorktreeTool | EnterWorktree | 进入 Git Worktree |
| ExitWorktreeTool | ExitWorktree | 退出 Git Worktree |

### 集成类
| 工具 | 名称 | 功能 |
|------|------|------|
| MCPTool | (动态) | MCP 服务器工具调用 |
| ListMcpResourcesTool | ListMcpResources | 列出 MCP 资源 |
| ReadMcpResourceTool | ReadMcpResource | 读取 MCP 资源 |
| LSPTool | LSP | Language Server Protocol 集成 |
| SkillTool | Skill | 技能执行 |

### 特殊类
| 工具 | 名称 | 功能 |
|------|------|------|
| BriefTool | Brief | 附件处理和上传 |
| ConfigTool | Config | 设置管理（仅内部） |
| ToolSearchTool | ToolSearch | 延迟工具发现 |
| TodoWriteTool | TodoWrite | 待办事项管理 |
| SleepTool | Sleep | 主动模式等待 |
| SyntheticOutputTool | SyntheticOutput | 结构化输出生成 |
| ScheduleCronTool | CronCreate/CronDelete/CronList | 定时任务 |
| RemoteTriggerTool | RemoteTrigger | 远程触发 |
| REPLTool | REPL | REPL 模式（仅内部） |
| WorkflowTool | Workflow | 工作流脚本执行 |
| WebBrowserTool | WebBrowser | Web 浏览器自动化 |

## 权限模型

```mermaid
flowchart TD
    A[工具调用请求] --> B{权限检查}
    B -->|auto 模式| C[自动允许]
    B -->|default 模式| D{规则匹配}
    B -->|plan 模式| E[只读操作允许]
    B -->|bypassPermissions| C

    D -->|允许规则| F[执行工具]
    D -->|拒绝规则| G[拒绝执行]
    D -->|无规则| H[提示用户]

    H -->|用户允许| F
    H -->|用户拒绝| G
    H -->|用户允许本次| I[临时允许并执行]

    G --> J[getDenyRuleForTool 过滤]
    J --> K[从工具列表中移除]
```

## AgentTool 子代理架构

```mermaid
flowchart TD
    A[AgentTool] --> B[子代理类型选择]
    B --> C[general-purpose<br/>通用代理]
    B --> D[Explore<br/>代码探索]
    B --> E[Plan<br/>架构规划]
    B --> F[claude-code-guide<br/>使用指南]

    C --> G[可用工具: 全部]
    D --> H[可用工具: 只读<br/>Glob, Grep, Read, Agent]
    E --> I[可用工具: 只读<br/>同 Explore]

    A --> J{隔离模式}
    J -->|worktree| K[Git Worktree 隔离]
    J -->|默认| L[同目录执行]

    A --> M[代理能力]
    M --> N[并行代理启动]
    M --> O[后台运行]
    M --> P[消息传递]
    M --> Q[内存管理]
```

## BashTool 安全机制

```mermaid
flowchart TD
    A[BashTool 命令执行] --> B{安全检查}
    B --> C[路径验证<br/>pathValidation.ts]
    B --> D[只读验证<br/>readOnlyValidation.ts]
    B --> E[破坏性命令警告<br/>destructiveCommandWarning.ts]
    B --> F[沙盒检查<br/>shouldUseSandbox.ts]
    B --> G[sed 命令验证<br/>sedValidation.ts]

    C --> H{在工作目录内?}
    H -->|是| I[允许执行]
    H -->|否| J[路径限制警告]

    E --> K{破坏性命令?}
    K -->|rm, git reset --hard| L[额外确认]
    K -->|其他| I

    F --> M{沙盒可用?}
    M -->|是| N[沙盒执行]
    M -->|否| I
```