# 第五章：工具层设计

## 章引言

工具(Tools)是智能体与外部世界交互的手段。每一个工具调用都是一次对外部系统的改造、查询或决策。设计良好的工具层决定了智能体系统的能力边界、安全性、可维护性和可扩展性。

如果说智能体循环是“如何思考和行动”，那么工具层就是“用什么工具去行动”。

## 工具层的三个核心问题

1. **工具抽象**：如何定义一个统一的工具接口，使得各种异构的外部能力（Bash、文件系统、网络请求、数据库、API）都能被智能体调用？
2. **工具执行**：如何安全地执行工具调用，处理超时、权限、错误，并向智能体反馈结果？
3. **工具发现**：如何让智能体知道存在哪些工具、如何使用？在静态工具列表和动态工具发现之间如何平衡？

## 两个参考系统的工具哲学

### Claude Code 的设计

* **内置工具与扩展工具**：深度集成，每个工具为特定场景优化
* **工具类型多样**：8个执行工具、3个网络工具、8个Agent工具、5+内置专用工具
* **Tool\<Input,Output,Progress> 泛型接口**：类型安全，支持进度报告
* **buildTool() 工厂函数**：动态构造工具
* **shouldDefer 延迟加载**：条件决定是否加载工具
* **FileStateCache 上下文缓存**：工具执行结果的智能缓存
* **异步执行**：StreamingToolExecutor 并发调用多个工具

### OpenClaw 的设计

* **Tools + Skills 双层架构**：
  * **Tools**：底层能力（Bash、文件、搜索）
  * **Skills**：Markdown 指令格式的高级操作
* **6级技能加载优先级**：
  1. 固定系统技能
  2. 会话上下文技能
  3. 用户自定义技能
  4. 领域专业技能
  5. 通用工具
  6. 动态发现技能
* **工具策略**：允许/拒绝/分层权限模型
* **单线程顺序执行**：每个工具一个一个执行，但可序列化结果

## 本章结构

* 5.1：工具抽象接口设计
* 5.2：工具执行流水线
* 5.3：工具类型体系
* 5.4：动态发现与加载
* 5.5：实战——MiniHarness 工具层
* 本章小结

## 学习要点

通过本章的学习，你将理解：

1. 如何定义工具的统一接口，支持异步、进度报告、权限检查
2. 工具执行流水线的完整过程：发现 → 验证 → 执行 → 缓存
3. 不同工具类型的实现特点和权衡
4. 动态工具发现的必要性和实现方式
5. 如何在 Python 中实现一个可扩展的工具系统

## 工具与技能的关系

工具和技能的关系可以用以下层级模型表示：

```mermaid
graph TD
    A["使用者指令"] --> B["<b>Skills(高级指令)</b><br/>Markdown 格式定义<br/>.skill 文件<br/>可由智能体组合执行"]
    B --> C["<b>Tools(底层能力)</b><br/>抽象接口<br/>单一职责<br/>由系统管理"]
    C --> D["<b>底层系统</b><br/>bash/fs/network<br/>实际能力实现"]

    style A fill:#f5e8f4,stroke:#a44a90,stroke-width:2px,color:#000000
    style B fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
    style C fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
    style D fill:#f5e8f4,stroke:#a44a90,stroke-width:2px,color:#000000
```

## 设计决策速查

| 决策点  | Claude Code          | OpenClaw      | MiniHarness    |
| ---- | -------------------- | ------------- | -------------- |
| 工具接口 | Tool\<I,O,P>         | Tool Protocol | Async Protocol |
| 执行模式 | 并发                   | 顺序            | 顺序（可扩展）        |
| 错误处理 | 异常捕获                 | 错误即观察         | 两者结合           |
| 权限管理 | check\_permissions() | 工具策略          | 基础实现           |
| 缓存   | FileStateCache       | 会话记忆          | 简单缓存           |
| 发现机制 | 预定义                  | 6级优先级         | 注册表            |

本章将深入这些设计细节，为你建立完整的工具系统设计能力。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/harness_engineering_guide/di-er-bu-fen-harness-he-xin-zi-xi-tong/05_tool_layer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.