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

第二章 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

"加一个工具, 只加一个 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 函数进行检查。

三、工作原理

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

def safe_path(p: str) -> Path: #解析为绝对路径，并消除 .. 和 . 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]
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`**：这是一个匿名函数，作为中间层，负责接收大模型发来的任意参数。

循环中按名称查找处理函数。循环体本身与 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 效果更好, 也可以用中文):

Read the file requirements.txt
Create a file called greet.py with a greet(name) function
Edit greet.py to add a docstring to the function
Read greet.py to verify the edit worked

六、其他

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

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