第二章 Tool Use (工具使用)
s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12
“本专栏基于开源项目
learn-claude-code的官方文档。原文档非常硬核，为了方便像我一样的新手小白理解，我对文档进行了逐行精读，并加入了很多中文注释、大白话解释和踩坑记录。希望这套‘咀嚼版’教程能帮你推开 AI Agent 开发的大门。”
"加一个工具, 只加一个 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.txtCreate a file called greet.py with a greet(name) functionEdit greet.py to add a docstring to the functionRead greet.py to verify the edit worked
六、其他
这里的tool其实就是函数调用，但不止于此
在 Claude 的 Messages API 中，tools 参数确实可以包含你定义的函数（客户端工具），也可以包含来自 MCP（Model Context Protocol）服务器的工具，还可以包含由 Anthropic 提供的服务器端工具。
