工具

L01 > [ L02 ] L03 > L04 > L05 > L06 | L07 > L08 > L09 > L10 > L11 > L12

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

Harness 层: 工具分发 -- 扩展模型能触达的边界。

问题

只有 bash 时, 所有操作都走 shell。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:
    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. 循环中按名称查找处理函数。循环体本身与 L01 完全一致。

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，循环不变

加工具 = 加 handler + 加 schema。循环永远不变。 含义如下。

「循环不变」指哪一段？
指 L01 那种主流程骨架，始终是：把消息（含当前工具定义）发给模型 → 若返回里是 tool_use 则取出工具名与参数 → dispatch 到对应 handler 执行 → 将结果以 tool_result 写回对话 → 再请求模型，直到不再出现 tool_use。
这段 while / for 的逻辑不依赖「有三个工具还是三十个工具」，因此不必每加一种能力就重写主流程。

部分	名称	作用
schema（工具定义）	与 API 的 tools 列表里的一项	告诉模型：工具叫什么、干什么、参数长什么样（常为 JSON Schema）。没有它，模型不知道可以调用这项能力。
handler	如 run_read、run_write	模型真的选了该工具时，由哪段代码执行（读文件、写文件、沙箱检查等），并把字符串结果返回给 tool_result。

合在一起： 模型侧多一个可选动作（在定义里注册 schema），执行侧多一个实现（在 dispatch 里注册 handler）。主循环仍是「通用管道」，只扩展工具表与分发表，不要为每个新工具去改「拼 message、判断 stop_reason」那一套核心结构。

形象说法：循环是固定的传送带；工具是不同工位——新工位 = 说明牌（schema）+ 干活的实现（handler）。

相对 L01 的变更

组件	之前 (L01)	之后 (L02)
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