# 第一章 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. 每个工具有一个处理函数。路径沙箱防止逃逸工作区。


```
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"]),
}
```

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`

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

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（1）The Agent Loop (智能体循环)

本文介绍了智能体开发中的核心概念——智能体循环(Agent Loop)，基于开源项目learn-claude-code实现。该循环采用ReAct范式，让AI通过&quot;思考-行动-观察&quot;的循环自主完成任务。核心代码仅30行左右，通过while循环持续运行，直到模型不再调用工具为止。文章详细解析了循环的工作原理，包括消息传递、工具调用和退出条件等关键机制，并提供了实际测试案例。

人工智能

开源AI代理开发教程，详解Claude Code项目工具使用原理。通过bash、read、write、edit等工具实现文件操作，采用路径沙箱确保安全性。包含代码解析、中文注释和实战案例，帮助开发者快速掌握AI代理开发技巧。

AI Agent

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

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

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

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

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

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

社区新版编辑器体验调研

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（1）The Agent Loop (智能体循环)-腾讯云开发者社区-腾讯云

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（1）The Agent Loop (智能体循环)

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（1）The Agent Loop (智能体循环)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐