Tool Use - 工具扩展的优雅机制

s01 vs s02：对比理解#

s01 的循环直接调用 bash，s02 的循环通过字典查找。循环代码零改动——这就是开闭原则。

开闭原则：对扩展开放，对修改封闭#

为什么字典查找能实现开闭原则？

1
加工具 = 加 handler + 加 schema
2
循环代码 = 零改动

TOOL_HANDLERS.get(block.name) 这行代码的关键在于：循环不知道具体工具，只知道”按名查找”。工具的增删改，都在字典里发生，循环体代码不受影响。

验证你的理解#

Q1：如果用 if/elif 链而不是字典，加第 100 个工具要改几处？

:::details 答案 循环体要改 100 处——每加一个工具，就要加一个 elif 分支。

字典结构的好处：加第 100 个工具，只需在字典里加一项，循环体代码不变。 :::

Q2：block.name 从哪里来？

:::details 答案 block.name 由 LLM 决定。LLM 看到 Tool Schema，根据 description 判断调用时机，在 tool_use block 中提供 name。Harness 只是执行。

这意味着：LLM 决策，Harness 执行。字典查找是”执行”层，不参与决策。 :::

description 是 LLM 的唯一依据#

LLM 没有上下文之外的”直觉”。它判断何时调用工具，完全依赖 description。

看两个对比：

1
# 差的 description
2
"description": "Read a file."  # 太模糊，LLM 不知道何时该用
3

4
# 好的 description
5
"description": "Read the contents of a file. Use this when you need to see what's in a file, check existing code, or understand file structure before making changes."

好的 description 告诉 LLM 三件事：

1. 工具做什么（Read contents）
2. 何时用（need to see, check, understand）
3. 与其他工具的关系（before making changes）

原则：description 越精准，LLM 调用越准确。但过度详细可能限制 LLM 的创造性用法——这是个权衡。

验证你的理解#

Q3：如果 description 写错了，会发生什么？

:::details 答案 LLM 会在错误的时机调用工具。比如把 read_file 的 description 写成”Delete a file”，LLM 就会在想删除时调用 read——行为完全错误。

这再次证明：LLM 决策依赖 description，description 是”契约”，必须准确。 :::

信任边界原则#

LLM 要求读取 /etc/passwd，不是 LLM 的错——它只是”决策”。Harness 的职责是拦截这个请求——这是”护栏”。

safe_path 实现：路径沙箱#

1
def safe_path(p: str) -> Path:
2
    path = (WORKDIR / p).resolve()  # 解析符号链接、消除 ../
3
    if not path.is_relative_to(WORKDIR):
4
        raise ValueError(f"Path escapes workspace: {p}")
5
    return path

两步检查：

1
# 攻击示例：路径逃逸
2
LLM: "read_file(path='../../../etc/passwd')"
3
Harness: safe_path("../../../etc/passwd")
4
         → resolve() → "/etc/passwd"
5
         → is_relative_to(WORKDIR) → False
6
         → raise ValueError: "Path escapes workspace"

LLM 可能犯错，可能被 prompt injection 攻击，但 Harness 的 safe_path 是硬边界——逃逸请求直接报错。

专用工具优先：减少攻击面#

为什么优先用 read_file/write_file/edit_file，而不是 bash？

原则：专用工具约束操作范围，bash 作为最后手段。

验证你的理解#

Q4：如果 LLM 被 prompt injection 攻击，要求执行 rm -rf /，会发生什么？

:::details 答案 取决于用什么工具：

• 如果用 bash：run_bash("rm -rf /") 执行，灾难性后果。
• 如果用专用工具：没有 delete_file 工具，LLM 无法删除——攻击被工具范围约束。

这就是”减少攻击面”的价值：专用工具把 bash 的”任意命令”降级为”特定操作”。 :::

与后续课程的关系#

理解 L02 后，你会发现后续课程都在 Dispatch Map 上叠加——循环本身始终不变：

核心洞察：无论机制多复杂，骨架始终是 L01 的循环 + L02 的 Dispatch Map。理解 L01 和 L02，就理解了整个 Agent 系统的根基。

L02 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

如果要加一个新工具”search_files”，你会怎么设计？循环需要改动吗？

:::details L2 层级回答 循环不需要改动。只需三步：

1. 加 handler：TOOL_HANDLERS["search_files"] = lambda **kw: run_search(kw["pattern"])
2. 加 schema：TOOLS.append({name, description, input_schema})
3. 加护栏：handler 内部调用 safe_path() 确保只在工作区搜索

这就是开闭原则的实践：扩展点是字典注册，循环代码零改动。安全护栏在 handler 层实现，符合信任边界原则。 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L02，不只是记住代码，而是掌握”如何在循环上安全扩展能力”的设计原则。

Tool Dispatch 流程#

L01 vs L02 对比#

开闭原则示意#

信任边界#