第三篇：工具即双手 —— 从 Bash 到 Tool Dispatch Map
s01 说"一个 bash 就够了"，但没人真的只用 bash 写代码。
全栈工程师 vs. 全栈工具
你说"帮我读一下 config.py 的第 10 行到第 20 行"，如果 Agent 只有一个 bash 工具，它得敲：sed -n '10,20p' config.py。这当然可以。但就像你可以用螺丝刀钉钉子，但有锤子的话为什么要用螺丝刀？
这就是 s02 的核心进化：从"一个万能工具"到"一套专用工具"。
Tool Dispatch Map
s02 的核心创新是一张映射表：
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"]),}一个函数名到处理函数的直接映射。没有 if-else 森林。当模型返回工具调用时：
handler=TOOL_HANDLERS.get(block.name)output=handler(**block.input)ifhandlerelsef"Unknown tool:{block.name}"两行代码，路由了一切。想加新工具？加一行字典条目就行。
专有工具的精妙之处
read_file 比 bash cat 好在哪里？
- 安全边界：safe_path() 阻止路径穿越
- 输出控制：limit 参数 + 50000 字符截断
- 友好报错：异常被捕获为字符串
- 语义精准：模型知道"我在读文件"
那个 safe_path 函数：
defsafe_path(p:str)->Path:path=(WORKDIR/p).resolve()ifnotpath.is_relative_to(WORKDIR):raiseValueError(f"Path escapes workspace:{p}")returnpath永远、永远、永远不要相信模型的输入。
Agent Loop 没有变
defagent_loop(messages:list):whileTrue:response=client.messages.create(...)messages.append(response.content)ifresponse.stop_reason!="tool_use":returnforblockinresponse.content:ifblock.type=="tool_use":handler=TOOL_HANDLERS.get(block.name)output=handler(**block.input)messages.append(tool_result)和 s01 相比，唯一的变化就是把 run_bash 换成了 TOOL_HANDLERS.get。
这就是扩缩性的全部秘密。你不改核心循环。你只改工具注册表。
如果说 Agent Loop 是操作系统内核，那 TOOL_HANDLERS 就是系统调用表。
从 4 个工具到 16 个工具
s02 只有 4 个工具。到了 s12，同一个 pattern 被扩展到了 16 个——基础工具、任务工具、worktree 工具、事件工具。但核心循环还是那几行，没变。
下一篇：TodoManager —— 一个让模型自己写 TODO List 的工具，以及一个讨人厌的提醒器。
