# 第二章 Tool Use (工具使用)


`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`

>“本专栏基于开源项目 `learn-claude-code` 的官方文档。原文档非常硬核，为了方便像我一样的新手小白理解，我对文档进行了**逐行精读**，并加入了很多**中文注释、大白话解释和踩坑记录**。希望这套‘咀嚼版’教程能帮你推开 AI Agent 开发的大门。”


项目地址：[shareAI-lab/learn-claude-code: Bash is all you need - A nano Claude Code–like agent, built from 0 to 1](https://github.com/shareAI-lab/learn-claude-code)

>"加一个工具, 只加一个 handler" -- 循环不用动, 新工具注册进 dispatch map 就行。


## 一、问题-**Robustness (鲁棒性)** 和 **Security (安全性)**


只有 `bash` 时, 所有操作都走 shell。如果你的 Agent 只有一个工具 `bash`，那么无论它想做什么（读取文件、写入文件、修改内容），它**必须**通过执行 shell 命令来完成。


- 想读文件？它得执行 `cat filename`。

- 想写文件？它得执行 `echo "content" > filename`。

- 想改文件？它得执行 `sed` 命令。


`cat` 截断不可预测, `sed` 遇到特殊字符就崩, 每次 bash 调用都是不受约束的安全面。专用工具 (`read_file`, `write_file`) 可以在工具层面做路径沙箱。

关键洞察: 加工具不需要改循环。

## 二、解决方案


```
+--------+      +-------+      +------------------+
|  User  | ---> |  LLM  | ---> | Tool Dispatch    |
| prompt |      |       |      | {                |
+--------+      +---+---+      |   bash: run_bash |
                    ^           |   read: run_read |
                    |           |   write: run_wr  |
                    +-----------+   edit: run_edit |
                    tool_result | }                |
                                +------------------+

The dispatch map is a dict: {tool_name: handler_function}.
One lookup replaces any if/elif chain.
```
### 1.引入专用工具，替代滥用 Bash


s02 不再让模型什么都用 `bash` 解决，而是提供了 `read_file`, `write_file`, `edit_file` 这三个专用函数。

### 2.强制实施路径沙箱 (`safe_path`)


这是 s02 最重要的安全升级。所有涉及文件操作的专用工具（read, write, edit），在执行前都会先通过 `safe_path` 函数进行检查。

## 三、工作原理


1. 每个工具有一个处理函数。路径沙箱防止逃逸工作区。


```
def safe_path(p: str) -> Path:
    #解析为绝对路径，并消除&nbsp;..&nbsp;和&nbsp;.
    path = (WORKDIR / p).resolve() 
    
    #检查路径是否在工作目录内，防止用户访问非法路径。
    if not path.is_relative_to(WORKDIR): 
        raise ValueError(f"Path escapes workspace: {p}")
    return path

def run_read(path: str, limit: int = None) -> str:
    text = safe_path(path).read_text()
    lines = text.splitlines()
    if limit and limit < len(lines):
        lines = lines[:limit]
    return "\n".join(lines)[:50000]
```

1. dispatch map 将工具名映射到处理函数。


```
TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"],
                                        kw["new_text"]),
}
```
**`lambda **kw`**：这是一个匿名函数，作为中间层，负责接收大模型发来的任意参数。


1. 循环中按名称查找处理函数。循环体本身与 s01 完全一致。


```
for block in response.content:
    if block.type == "tool_use":
        handler = TOOL_HANDLERS.get(block.name)
        output = handler(**block.input) if handler \
            else f"Unknown tool: {block.name}"
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": output,
        })
```
加工具 = 加 handler + 加 schema。循环永远不变。

## 四、相对 s01 的变更


|组件|之前(s01)|之后(s02)|
|:-:|:-:|:-:|
|Tools|1 (仅 bash)|4 (bash, read, write, edit)|
|Dispatch|硬编码 bash 调用|`TOOL_HANDLERS` 字典|
|路径安全|无|`safe_path()` 沙箱|
|Agent loop|不变|不变|

## 五、试一试


```
cd learn-claude-code
python agents/s02_tool_use.py
```
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):


1. `Read the file requirements.txt`

2. `Create a file called greet.py with a greet(name) function`

3. `Edit greet.py to add a docstring to the function`

4. `Read greet.py to verify the edit worked`


## 六、其他


### 这里的tool其实就是函数调用，但不止于此


在 Claude 的 Messages API 中，`tools` 参数确实可以包含你定义的函数（客户端工具），也可以包含来自 MCP（Model Context Protocol）服务器的工具，还可以包含由 Anthropic 提供的服务器端工具。

s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（2）Tool Use (工具使用)

本文介绍了如何为AI Agent添加专用工具来提升鲁棒性和安全性。

编程语言

本专栏详解AI Agent开发中工具使用的关键技巧，通过read_file、write_file等专用工具替代Bash操作，提升系统安全性和鲁棒性。重点介绍路径沙箱(safe_path)实现原理和dispatchmap工具调度机制，帮助开发者构建更安全的AI应用。基于开源项目learn-claude-code，适合新手入门AI Agent开发。

服务器

Agent

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本专栏详解AI Agent开发中工具使用的关键技巧，通过read_file、write_file等专用工具替代Bash操作，提升系统安全性和鲁棒性。重点介绍路径沙箱(safe_path)实现原理和dispatchmap工具调度机制，帮助开发者构建更安全的AI应用。基于开源项目learn-claude-code，适合新手...

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（2）Tool Use (工具使用)-腾讯云开发者社区-腾讯云

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（2）Tool Use (工具使用)

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（2）Tool Use (工具使用)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐