第11章工具系统 —— 从Bash到MCP的工具分发

2026-05-23 约 2000 字预计阅读 10 分钟

上一篇我们深入了 Agent Loop 的核心机制。本章我们看工具系统——Agent 的双手，如何从Bash扩展到MCP。

工具系统是什么

一句话定义：Agent 可以采取的行动集合——文件读写、命令执行、网络请求、浏览器控制等。

Tools = Agent 的双手定位：Harness 的第二层，执行 Model 的 tool_use 决策

图表代码

graph LR
    Model[Model 推理
tool_use 决策] --> ToolRegistry[工具注册表
工具定义]
    ToolRegistry --> Dispatch[工具分发
匹配执行]
    Dispatch --> Executor[工具执行器
调用环境]
    Executor --> Result[工具输出
返回 Loop]graph LR
    Model[Model 推理
tool_use 决策] --> ToolRegistry[工具注册表
工具定义]
    ToolRegistry --> Dispatch[工具分发
匹配执行]
    Dispatch --> Executor[工具执行器
调用环境]
    Executor --> Result[工具输出
返回 Loop]graph LR
    Model[Model 推理
tool_use 决策] --> ToolRegistry[工具注册表
工具定义]
    ToolRegistry --> Dispatch[工具分发
匹配执行]
    Dispatch --> Executor[工具执行器
调用环境]
    Executor --> Result[工具输出
返回 Loop]

graph LR
    Model[Model 推理<br/>tool_use 决策] --> ToolRegistry[工具注册表<br/>工具定义]
    ToolRegistry --> Dispatch[工具分发<br/>匹配执行]
    Dispatch --> Executor[工具执行器<br/>调用环境]
    Executor --> Result[工具输出<br/>返回 Loop]

核心机制：

工具定义：每个工具有名称、参数schema、执行函数
工具注册：所有工具注册到 dispatch map
工具分发：根据 Model 的 tool_name 匹配执行
工具执行：调用具体工具，返回结果

工具设计原则

格言

“加一个工具, 只加一个 handler” —— 循环不用动，新工具注册进 dispatch map 就行

设计要点

设计要点	说明	示例
原子化	每个工具只做一件事	Read 只读文件，不编辑
可组合	工具组合完成复杂任务	Glob + Read + Edit = 搜索读取编辑
描述清晰	工具名称和参数明确	`Read(file_path: "/src/app.ts")`
无状态	工具执行不保存状态	每次调用独立，结果返回给 Loop
可注册	新工具只需注册到 dispatch map	`dispatch_map["NewTool"] = new_tool_handler`

图表代码

graph TB
    subgraph Atomic["原子化工具"]
        A1[Read
只读文件]
        A2[Write
只写文件]
        A3[Edit
只编辑片段]
        A4[Glob
只搜索路径]
    end
    
    subgraph Composable["可组合工作流"]
        C1[Glob 搜索文件] --> C2[Read 读取内容]
        C2 --> C3[Edit 编辑片段]
        C3 --> C4[Bash 运行测试]
    end
    
    Atomic --> Composablegraph TB
    subgraph Atomic["原子化工具"]
        A1[Read
只读文件]
        A2[Write
只写文件]
        A3[Edit
只编辑片段]
        A4[Glob
只搜索路径]
    end
    
    subgraph Composable["可组合工作流"]
        C1[Glob 搜索文件] --> C2[Read 读取内容]
        C2 --> C3[Edit 编辑片段]
        C3 --> C4[Bash 运行测试]
    end
    
    Atomic --> Composablegraph TB
    subgraph Atomic["原子化工具"]
        A1[Read
只读文件]
        A2[Write
只写文件]
        A3[Edit
只编辑片段]
        A4[Glob
只搜索路径]
    end
    
    subgraph Composable["可组合工作流"]
        C1[Glob 搜索文件] --> C2[Read 读取内容]
        C2 --> C3[Edit 编辑片段]
        C3 --> C4[Bash 运行测试]
    end
    
    Atomic --> Composable

graph TB
    subgraph Atomic["原子化工具"]
        A1[Read<br/>只读文件]
        A2[Write<br/>只写文件]
        A3[Edit<br/>只编辑片段]
        A4[Glob<br/>只搜索路径]
    end
    
    subgraph Composable["可组合工作流"]
        C1[Glob 搜索文件] --> C2[Read 读取内容]
        C2 --> C3[Edit 编辑片段]
        C3 --> C4[Bash 运行测试]
    end
    
    Atomic --> Composable

Claude Code 的工具全景

工具分类

工具类别	工具名称	功能	参数示例
命令执行	Bash	执行 Shell 命令	`command: "npm install"`
文件操作	Read	读取文件内容	`file_path: "/src/app.ts"`
文件操作	Write	写入新文件	`file_path, content`
文件操作	Edit	编辑文件片段	`file_path, old_string, new_string`
搜索导航	Glob	搜索文件路径	`pattern: "*/.ts"`
搜索导航	Grep	搜索文件内容	`pattern: "function_name"`
网络交互	WebFetch	网络请求	`url: "https://..."`
网络交互	WebSearch	网络搜索	`query: "React hooks"`
浏览器	Browser_navigate	打开网页	`url: "https://..."`
浏览器	Browser_click	点击元素	`ref: "element_ref"`
浏览器	Browser_snapshot	页面快照	-
浏览器	Browser_type	输入文本	`ref, text`
子 Agent	Agent	派发子任务	`prompt, subagent_type`
任务管理	TodoWrite	任务系统	`todos: [...]`
任务管理	TaskCreate	创建任务	`subject, description`
任务管理	TaskUpdate	更新任务	`taskId, status`
MCP 扩展	MCP_*	MCP 工具	根据 MCP 服务器定义

工具注册机制

# 工具注册 dispatch map
dispatch_map = {
    "Bash": bash_handler,
    "Read": read_handler,
    "Write": write_handler,
    "Edit": edit_handler,
    "Glob": glob_handler,
    "Grep": grep_handler,
    "WebFetch": webfetch_handler,
    "WebSearch": websearch_handler,
    "Browser_navigate": browser_navigate_handler,
    "Browser_click": browser_click_handler,
    "Agent": agent_handler,
    "TodoWrite": todo_write_handler,
    # MCP 工具动态注册
    # "MCP_xxx": mcp_xxx_handler,
}

# 工具分发
def dispatch_tool(tool_name, tool_args):
    if tool_name in dispatch_map:
        return dispatch_map[tool_name](tool_args)
    else:
        return f"Error: Unknown tool {tool_name}"

核心工具详解

1. Bash —— 命令执行

一句话定义：执行 Shell 命令——连接 Agent 和终端环境。

参数结构：

{
  "command": "npm install",  // Shell 命令
  "timeout": 120000,         // 超时时间（可选）
  "run_in_background": false // 后台执行（可选）
}

执行流程：

图表代码

graph LR
    A[Bash 工具调用] --> B[权限检查
ask/allow/deny]
    B -->|allow| C[执行 Shell 命令]
    C --> D[收集输出
stdout/stderr]
    D --> E[返回结果]graph LR
    A[Bash 工具调用] --> B[权限检查
ask/allow/deny]
    B -->|allow| C[执行 Shell 命令]
    C --> D[收集输出
stdout/stderr]
    D --> E[返回结果]graph LR
    A[Bash 工具调用] --> B[权限检查
ask/allow/deny]
    B -->|allow| C[执行 Shell 命令]
    C --> D[收集输出
stdout/stderr]
    D --> E[返回结果]

graph LR
    A[Bash 工具调用] --> B[权限检查<br/>ask/allow/deny]
    B -->|allow| C[执行 Shell 命令]
    C --> D[收集输出<br/>stdout/stderr]
    D --> E[返回结果]

适用场景：

✅ 安装依赖：npm install、pip install
✅ 运行测试：npm test、pytest
✅ Git 操作：git status、git diff
✅ 系统命令：ls -la、mkdir

2. Read / Write / Edit —— 文件操作

Read：读取文件内容

{
  "file_path": "/src/app.ts",
  "limit": 100,   // 读取行数限制（可选）
  "offset": 0     // 起始行（可选）
}

Write：写入新文件

{
  "file_path": "/src/new.ts",
  "content": "// 新文件内容"
}

Edit：编辑文件片段（精准修改）

{
  "file_path": "/src/app.ts",
  "old_string": "function old() {",
  "new_string": "function new() {"
}

Edit 的优势：

✅ 精准修改：只改需要改的部分，不覆盖全文件
✅ 保持格式：不破坏文件其他部分的格式
✅ 多处修改：可以一次修改多处相同内容

图表代码

graph LR
    A[Edit 工具] --> B[查找 old_string]
    B --> C[替换为 new_string]
    C --> D[保存文件]
    
    E[old_string 必须唯一] --> Bgraph LR
    A[Edit 工具] --> B[查找 old_string]
    B --> C[替换为 new_string]
    C --> D[保存文件]
    
    E[old_string 必须唯一] --> Bgraph LR
    A[Edit 工具] --> B[查找 old_string]
    B --> C[替换为 new_string]
    C --> D[保存文件]
    
    E[old_string 必须唯一] --> B

graph LR
    A[Edit 工具] --> B[查找 old_string]
    B --> C[替换为 new_string]
    C --> D[保存文件]
    
    E[old_string 必须唯一] --> B

3. Glob / Grep —— 搜索导航

Glob：搜索文件路径

{
  "pattern": "**/*.ts",  // glob 模式
  "path": "/src"         // 搜索路径（可选）
}

Grep：搜索文件内容

{
  "pattern": "function_name",  // 正则模式
  "path": "/src",              // 搜索路径
  "output_mode": "files_with_matches"  // 输出模式
}

输出模式：

output_mode	输出内容	用途
files_with_matches	只返回文件路径	快速定位文件
content	返回匹配行内容	查看具体代码
count	返回匹配次数	统计使用频率

图表代码

graph TB
    subgraph SearchWorkflow["搜索工作流"]
        S1[Glob 搜索
找到 test/*.ts] --> S2[Grep 搜索
找到 function_name]
        S2 --> S3[Read 读取
查看具体代码]
    endgraph TB
    subgraph SearchWorkflow["搜索工作流"]
        S1[Glob 搜索
找到 test/*.ts] --> S2[Grep 搜索
找到 function_name]
        S2 --> S3[Read 读取
查看具体代码]
    endgraph TB
    subgraph SearchWorkflow["搜索工作流"]
        S1[Glob 搜索
找到 test/*.ts] --> S2[Grep 搜索
找到 function_name]
        S2 --> S3[Read 读取
查看具体代码]
    end

graph TB
    subgraph SearchWorkflow["搜索工作流"]
        S1[Glob 搜索<br/>找到 test/*.ts] --> S2[Grep 搜索<br/>找到 function_name]
        S2 --> S3[Read 读取<br/>查看具体代码]
    end

4. Browser —— 浏览器控制

工具组：

工具	功能	参数
Browser_navigate	打开网页	`url`
Browser_snapshot	页面快照（优于截图）	-
Browser_click	点击元素	`ref`（元素引用）
Browser_type	输入文本	`ref, text`
Browser_scroll	滚动页面	`direction`

Browser_snapshot vs 截图：

维度	Browser_snapshot	截图
内容	✅ 文本 + 结构	❌ 只有图片
可操作	✅ 包含元素引用	❌ 无法操作
性能	✅ 更轻量	❌ 图片大

图表代码

sequenceDiagram
    participant Loop as Agent Loop
    participant Browser as Browser 工具
    
    Loop->>Browser: Browser_navigate(url)
    Browser-->>Loop: 页面加载完成
    
    Loop->>Browser: Browser_snapshot()
    Browser-->>Loop: 返回快照（含元素引用）
    
    Loop->>Browser: Browser_click(ref)
    Browser-->>Loop: 点击完成
    
    Loop->>Browser: Browser_type(ref, text)
    Browser-->>Loop: 输入完成sequenceDiagram
    participant Loop as Agent Loop
    participant Browser as Browser 工具
    
    Loop->>Browser: Browser_navigate(url)
    Browser-->>Loop: 页面加载完成
    
    Loop->>Browser: Browser_snapshot()
    Browser-->>Loop: 返回快照（含元素引用）
    
    Loop->>Browser: Browser_click(ref)
    Browser-->>Loop: 点击完成
    
    Loop->>Browser: Browser_type(ref, text)
    Browser-->>Loop: 输入完成sequenceDiagram
    participant Loop as Agent Loop
    participant Browser as Browser 工具
    
    Loop->>Browser: Browser_navigate(url)
    Browser-->>Loop: 页面加载完成
    
    Loop->>Browser: Browser_snapshot()
    Browser-->>Loop: 返回快照（含元素引用）
    
    Loop->>Browser: Browser_click(ref)
    Browser-->>Loop: 点击完成
    
    Loop->>Browser: Browser_type(ref, text)
    Browser-->>Loop: 输入完成

sequenceDiagram
    participant Loop as Agent Loop
    participant Browser as Browser 工具
    
    Loop->>Browser: Browser_navigate(url)
    Browser-->>Loop: 页面加载完成
    
    Loop->>Browser: Browser_snapshot()
    Browser-->>Loop: 返回快照（含元素引用）
    
    Loop->>Browser: Browser_click(ref)
    Browser-->>Loop: 点击完成
    
    Loop->>Browser: Browser_type(ref, text)
    Browser-->>Loop: 输入完成

5. Agent —— 子 Agent 派发

一句话定义：派发子任务给隔离的子 Agent——大任务拆小，上下文隔离。

{
  "prompt": "分析 test/*.ts 文件覆盖率",
  "subagent_type": "Explore",  // 子 Agent 类型
  "model": "haiku"             // 模型选择（可选）
}

子 Agent 类型：

subagent_type	用途	特点
Explore	快速探索代码库	搜索文件、查找代码
Plan	规划实施方案	设计架构、制定步骤
Review	代码审查	检查质量、安全漏洞
General-purpose	通用任务	多步骤复杂任务

隔离机制：

图表代码

graph TB
    Main[主 Agent
messages 数组A] -->|派发| Sub[子 Agent
messages 数组B
隔离上下文]
    Sub -->|执行| Task[完成任务]
    Task -->|返回结果| Result[只返回结果
不泄露历史]
    Result -->|追加| Main
    
    Sub[上下文隔离
不污染主 Agent]graph TB
    Main[主 Agent
messages 数组A] -->|派发| Sub[子 Agent
messages 数组B
隔离上下文]
    Sub -->|执行| Task[完成任务]
    Task -->|返回结果| Result[只返回结果
不泄露历史]
    Result -->|追加| Main
    
    Sub[上下文隔离
不污染主 Agent]graph TB
    Main[主 Agent
messages 数组A] -->|派发| Sub[子 Agent
messages 数组B
隔离上下文]
    Sub -->|执行| Task[完成任务]
    Task -->|返回结果| Result[只返回结果
不泄露历史]
    Result -->|追加| Main
    
    Sub[上下文隔离
不污染主 Agent]

graph TB
    Main[主 Agent<br/>messages 数组A] -->|派发| Sub[子 Agent<br/>messages 数组B<br/>隔离上下文]
    Sub -->|执行| Task[完成任务]
    Task -->|返回结果| Result[只返回结果<br/>不泄露历史]
    Result -->|追加| Main
    
    Sub[上下文隔离<br/>不污染主 Agent]

MCP 扩展工具

MCP 定义

一句话定义：Model Context Protocol——连接 AI 和外部工具的开放协议。

MCP = 连接外部系统的标准化协议定位：扩展 Harness 能力边界，连接任意外部系统

图表代码

graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务]
    External -->|返回| MCP -->|结果| Agentgraph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务]
    External -->|返回| MCP -->|结果| Agentgraph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务]
    External -->|返回| MCP -->|结果| Agent

graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统<br/>数据库/API/云服务]
    External -->|返回| MCP -->|结果| Agent

MCP 服务器类型

MCP 服务器	功能	提供的工具
filesystem	文件系统操作	read_file、write_file、list_directory
database	数据库连接	query、insert、update
web	网络访问	fetch、search
git	Git 操作	status、diff、commit
custom	自定义系统	企业 API、云服务

MCP 工具注册

# MCP 工具动态注册到 dispatch_map
def register_mcp_tools(mcp_server):
    for tool in mcp_server.tools:
        dispatch_map[f"MCP_{tool.name}"] = mcp_tool_handler
        
        # 注册工具 schema
        tools_schema.append({
            "name": f"MCP_{tool.name}",
            "parameters": tool.parameters
        })

# 示例：注册 filesystem MCP
mcp_filesystem = MCPClient("filesystem")
register_mcp_tools(mcp_filesystem)

# dispatch_map 新增：
# "MCP_read_file": mcp_read_file_handler
# "MCP_write_file": mcp_write_file_handler
# "MCP_list_directory": mcp_list_directory_handler

工具分发流程

完整分发流程

图表代码

sequenceDiagram
    participant Loop as Agent Loop
    participant Model as Model 推理
    participant Perm as 权限系统
    participant Registry as 工具注册表
    participant Executor as 工具执行器
    participant Hooks as Hooks 系统
    participant MCP as MCP 服务器
    participant Env as 环境
    
    Model->>Loop: 返回 tool_use
    Loop->>Perm: 权限检查
    
    Perm-->>Loop: 返回 permission
    
    Loop->>Registry: 查询工具定义
    Registry-->>Loop: 返回工具 schema
    
    Loop->>Hooks: PreToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Executor: 调用工具执行
    
    alt MCP 工具
        Executor->>MCP: 调用 MCP 服务器
        MCP->>Env: 连接外部系统
        Env-->>MCP: 返回结果
        MCP-->>Executor: 返回 MCP 输出
    else 内置工具
        Executor->>Env: 调用环境（文件/终端）
        Env-->>Executor: 返回结果
    end
    
    Executor-->>Loop: 返回工具输出
    
    Loop->>Hooks: PostToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Loop: 追加结果到 messagessequenceDiagram
    participant Loop as Agent Loop
    participant Model as Model 推理
    participant Perm as 权限系统
    participant Registry as 工具注册表
    participant Executor as 工具执行器
    participant Hooks as Hooks 系统
    participant MCP as MCP 服务器
    participant Env as 环境
    
    Model->>Loop: 返回 tool_use
    Loop->>Perm: 权限检查
    
    Perm-->>Loop: 返回 permission
    
    Loop->>Registry: 查询工具定义
    Registry-->>Loop: 返回工具 schema
    
    Loop->>Hooks: PreToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Executor: 调用工具执行
    
    alt MCP 工具
        Executor->>MCP: 调用 MCP 服务器
        MCP->>Env: 连接外部系统
        Env-->>MCP: 返回结果
        MCP-->>Executor: 返回 MCP 输出
    else 内置工具
        Executor->>Env: 调用环境（文件/终端）
        Env-->>Executor: 返回结果
    end
    
    Executor-->>Loop: 返回工具输出
    
    Loop->>Hooks: PostToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Loop: 追加结果到 messagessequenceDiagram
    participant Loop as Agent Loop
    participant Model as Model 推理
    participant Perm as 权限系统
    participant Registry as 工具注册表
    participant Executor as 工具执行器
    participant Hooks as Hooks 系统
    participant MCP as MCP 服务器
    participant Env as 环境
    
    Model->>Loop: 返回 tool_use
    Loop->>Perm: 权限检查
    
    Perm-->>Loop: 返回 permission
    
    Loop->>Registry: 查询工具定义
    Registry-->>Loop: 返回工具 schema
    
    Loop->>Hooks: PreToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Executor: 调用工具执行
    
    alt MCP 工具
        Executor->>MCP: 调用 MCP 服务器
        MCP->>Env: 连接外部系统
        Env-->>MCP: 返回结果
        MCP-->>Executor: 返回 MCP 输出
    else 内置工具
        Executor->>Env: 调用环境（文件/终端）
        Env-->>Executor: 返回结果
    end
    
    Executor-->>Loop: 返回工具输出
    
    Loop->>Hooks: PostToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Loop: 追加结果到 messages

sequenceDiagram
    participant Loop as Agent Loop
    participant Model as Model 推理
    participant Perm as 权限系统
    participant Registry as 工具注册表
    participant Executor as 工具执行器
    participant Hooks as Hooks 系统
    participant MCP as MCP 服务器
    participant Env as 环境
    
    Model->>Loop: 返回 tool_use
    Loop->>Perm: 权限检查
    
    Perm-->>Loop: 返回 permission
    
    Loop->>Registry: 查询工具定义
    Registry-->>Loop: 返回工具 schema
    
    Loop->>Hooks: PreToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Executor: 调用工具执行
    
    alt MCP 工具
        Executor->>MCP: 调用 MCP 服务器
        MCP->>Env: 连接外部系统
        Env-->>MCP: 返回结果
        MCP-->>Executor: 返回 MCP 输出
    else 内置工具
        Executor->>Env: 调用环境（文件/终端）
        Env-->>Executor: 返回结果
    end
    
    Executor-->>Loop: 返回工具输出
    
    Loop->>Hooks: PostToolUse Hook
    Hooks-->>Loop: Hook 处理完成
    
    Loop->>Loop: 追加结果到 messages

并发工具执行

场景：Model 返回多个 tool_use，可并发执行。

# Model 返回多个 tool_use
response = {
    "stop_reason": "tool_use",
    "tool_uses": [
        {"name": "Read", "args": {"file_path": "/src/a.ts"}},
        {"name": "Read", "args": {"file_path": "/src/b.ts"}},
        {"name": "Grep", "args": {"pattern": "function"}}
    ]
}

# 并发执行
results = parallel_execute(response.tool_uses)

# 并发执行实现
def parallel_execute(tool_uses):
    import concurrent.futures
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
        futures = []
        for tool_use in tool_uses:
            handler = dispatch_map[tool_use["name"]]
            future = executor.submit(handler, tool_use["args"])
            futures.append(future)
        
        results = [future.result() for future in futures]
    return results

工具 Schema 定义

Schema 结构

{
  "name": "Read",
  "description": "Reads a file from the local filesystem",
  "parameters": {
    "type": "object",
    "properties": {
      "file_path": {
        "type": "string",
        "description": "The absolute path to the file to read"
      },
      "limit": {
        "type": "integer",
        "description": "Number of lines to read"
      },
      "offset": {
        "type": "integer",
        "description": "Line number to start reading from"
      }
    },
    "required": ["file_path"]
  }
}

Schema 注入 Model

图表代码

graph LR
    Schema[工具 Schema
定义] -->|注入| Prompt[System Prompt
工具定义]
    Prompt -->|发送| Model[Model 推理]
    Model -->|推理| ToolUse[tool_use
决策]graph LR
    Schema[工具 Schema
定义] -->|注入| Prompt[System Prompt
工具定义]
    Prompt -->|发送| Model[Model 推理]
    Model -->|推理| ToolUse[tool_use
决策]graph LR
    Schema[工具 Schema
定义] -->|注入| Prompt[System Prompt
工具定义]
    Prompt -->|发送| Model[Model 推理]
    Model -->|推理| ToolUse[tool_use
决策]

graph LR
    Schema[工具 Schema<br/>定义] -->|注入| Prompt[System Prompt<br/>工具定义]
    Prompt -->|发送| Model[Model 推理]
    Model -->|推理| ToolUse[tool_use<br/>决策]

注入方式：

System Prompt 中注入所有工具 Schema
Model 根据 Schema 知道有哪些工具可用
Model 根据参数定义构造 tool_args

工具系统的扩展设计

新工具添加流程

图表代码

graph TB
    A[定义新工具] --> B[编写 handler 函数]
    B --> C[注册到 dispatch_map]
    C --> D[定义 Schema]
    D --> E[注入 System Prompt]
    
    subgraph Step["添加新工具步骤"]
        Step1[1. 定义工具功能]
        Step2[2. 编写执行函数]
        Step3[3. 注册到 dispatch_map]
        Step4[4. 定义参数 Schema]
        Step5[5. 注入到 Model Prompt]
    endgraph TB
    A[定义新工具] --> B[编写 handler 函数]
    B --> C[注册到 dispatch_map]
    C --> D[定义 Schema]
    D --> E[注入 System Prompt]
    
    subgraph Step["添加新工具步骤"]
        Step1[1. 定义工具功能]
        Step2[2. 编写执行函数]
        Step3[3. 注册到 dispatch_map]
        Step4[4. 定义参数 Schema]
        Step5[5. 注入到 Model Prompt]
    endgraph TB
    A[定义新工具] --> B[编写 handler 函数]
    B --> C[注册到 dispatch_map]
    C --> D[定义 Schema]
    D --> E[注入 System Prompt]
    
    subgraph Step["添加新工具步骤"]
        Step1[1. 定义工具功能]
        Step2[2. 编写执行函数]
        Step3[3. 注册到 dispatch_map]
        Step4[4. 定义参数 Schema]
        Step5[5. 注入到 Model Prompt]
    end

graph TB
    A[定义新工具] --> B[编写 handler 函数]
    B --> C[注册到 dispatch_map]
    C --> D[定义 Schema]
    D --> E[注入 System Prompt]
    
    subgraph Step["添加新工具步骤"]
        Step1[1. 定义工具功能]
        Step2[2. 编写执行函数]
        Step3[3. 注册到 dispatch_map]
        Step4[4. 定义参数 Schema]
        Step5[5. 注入到 Model Prompt]
    end

设计格言：

“加一个工具, 只加一个 handler” —— 循环不用动，新工具注册进 dispatch map 就行

MCP 扩展优势

维度	内置工具	MCP 扩展工具
数量	固定（20+）	无限（任意 MCP 服务器）
定义	硬编码	动态注册
外部系统	❌ 无法连接	✅ 连接任意系统
维护	需改源码	只需配置 MCP

本章小结

工具系统定义：Agent 可以采取的行动集合
设计原则：原子化、可组合、描述清晰、无状态、可注册
核心工具：Bash、Read/Write/Edit、Glob/Grep、Browser、Agent
工具注册：dispatch_map + Schema 定义 + System Prompt 注入
工具分发：权限检查→查询 Schema→PreToolUse Hook→执行工具→PostToolUse Hook
并发执行：Model 可返回多个 tool_use，并发执行提升效率
MCP 扩展：连接外部系统的标准化协议，动态注册新工具
新工具添加：定义→编写→注册→Schema→注入

预告：下一篇我们深入权限系统——deny→ask→allow的安全边界。

☕ 如果这篇文章对你有帮助

欢迎请我喝杯咖啡，你的支持是我持续创作的动力 ❤️

捐赠支持 GitHub Sponsors

第11章工具系统 —— 从Bash到MCP的工具分发

工具系统是什么

工具设计原则

格言

设计要点

Claude Code 的工具全景

工具分类

工具注册机制

核心工具详解

1. Bash —— 命令执行

2. Read / Write / Edit —— 文件操作

3. Glob / Grep —— 搜索导航

4. Browser —— 浏览器控制

5. Agent —— 子 Agent 派发

MCP 扩展工具

MCP 定义

MCP 服务器类型

MCP 工具注册

工具分发流程

完整分发流程

并发工具执行

工具 Schema 定义

Schema 结构

Schema 注入 Model

工具系统的扩展设计

新工具添加流程

MCP 扩展优势

本章小结

相关内容

目录

第11章 工具系统 —— 从Bash到MCP的工具分发

工具系统是什么

工具设计原则

格言

设计要点

Claude Code 的工具全景

工具分类

工具注册机制

核心工具详解

1. Bash —— 命令执行

2. Read / Write / Edit —— 文件操作

3. Glob / Grep —— 搜索导航

4. Browser —— 浏览器控制

5. Agent —— 子 Agent 派发

MCP 扩展工具

MCP 定义

MCP 服务器类型

MCP 工具注册

工具分发流程

完整分发流程

并发工具执行

工具 Schema 定义

Schema 结构

Schema 注入 Model

工具系统的扩展设计

新工具添加流程

MCP 扩展优势

本章小结

相关内容

第11章工具系统 —— 从Bash到MCP的工具分发