;
is_error?: boolean;
}
```
特点：
* 类型安全的接口定义
* 支持流式处理(streaming)
* 灵活的内容块(ContentBlock)设计
### OpenClaw的接口设计
OpenClaw使用WebSocket协议进行通信，消息格式基于帧(Frame)：
**WebSocket帧结构：**
| 帧类型 | 负载 |
| --------- | ---------------------------- |
| HEARTBEAT | {agent\_id, timestamp} |
| TASK | {task\_id, description, ...} |
| ACTION | {action\_type, tool\_call} |
| RESULT | {action\_id, result\_data} |
| CONTROL | {command: pause/resume/stop} |
特点：
* 长连接保证高实时性
* 帧类型的设计明确了各种通信场景
* Heartbeat机制支持长期运行的Agent
## 2.4.5 版本控制和向后兼容性
当Harness系统演进时，接口的向后兼容性变得重要。
```python
class VersionedMessage:
"""带版本的消息,支持向后兼容"""
VERSION = "1.0"
def __init__(
self,
role: MessageRole,
type: MessageType,
content: str,
version: str = None,
**kwargs
):
self.version = version or self.VERSION
# ... 其他初始化 ...
@classmethod
def from_dict(cls, data: dict) -> "VersionedMessage":
"""从字典反序列化,处理版本兼容性"""
version = data.get("version", "1.0")
if version == "1.0":
return cls._from_v1_0(data)
elif version == "2.0":
return cls._from_v2_0(data)
else:
raise ValueError(f"Unsupported message version: {version}")
@classmethod
def _from_v1_0(cls, data: dict) -> "VersionedMessage":
"""从v1.0格式反序列化"""
# 处理v1.0特定的字段和格式
return cls(
role=MessageRole(data.get("role")),
type=MessageType(data.get("type")),
content=data.get("content"),
version="1.0"
)
@classmethod
def _from_v2_0(cls, data: dict) -> "VersionedMessage":
"""从v2.0格式反序列化"""
# 处理v2.0特定的字段和格式
return cls(
role=MessageRole(data.get("role")),
type=MessageType(data.get("type")),
content=data.get("content"),
version="2.0"
)
```
## 2.4.6 总结
良好的接口设计包括：
1. **统一的消息格式**：所有层间通信都使用结构化的消息
2. **工具调用协议**：标准化的请求和响应格式
3. **事件流规范**：异步通信的统一事件定义
4. **版本控制**：为系统演进预留向后兼容的机制
这些接口的清晰定义，使得Harness系统的各个组件可以独立开发和测试，同时保持整体的一致性。
# 2.5 MiniHarness脚手架搭建
本节将前两节的架构设计落地为可运行的代码骨架。完成后，MiniHarness 项目将具备完整的目录结构、依赖配置和核心接口定义，为后续章节的增量开发打下基础。
> 完整代码见 `lab/` 目录，可直接运行。本节聚焦设计决策和关键接口，不重复贴出全部源码。
## 2.5.1 项目结构设计
MiniHarness 的目录结构遵循“按子系统分包”的原则，每个包对应一个 Harness 子系统：
| 目录 | 对应子系统 | 职责 | 首次实现章节 |
| ---------------- | -------- | --------------------- | ------ |
| `core/` | 公共基础 | 消息、工具、智能体、事件的接口定义 | 本章 |
| `runtime/` | 运行时引擎 | Agent 循环、流式处理、事件驱动 | 第4章 |
| `tools/` | 工具层 | 工具注册、执行流水线、内置工具 | 第5章 |
| `memory/` | 记忆子系统 | 存储、上下文组装、记忆整合 | 第6章 |
| `models/` | 模型集成 | Provider 抽象、输出解析、质量门控 | 第7章 |
| `orchestration/` | 编排引擎 | 任务分解、状态机、多智能体协调 | 第8章 |
| `mcp/` | MCP 集成 | MCP 客户端、工具发现、协议适配 | 第9章 |
| `reliability/` | 可靠性与可观测性 | 日志、追踪、监控指标、容错机制 | 第11章 |
| `security/` | 安全防护 | 权限管理、路径校验、护栏、安全执行 | 第12章 |
| `utils/` | 工具类 | 配置管理等辅助模块 | 本章 |
项目还包含 `tests/`（按 unit/integration 分层）和 `examples/`（使用示例）。
## 2.5.2 依赖配置
MiniHarness 使用 `pyproject.toml` 管理项目元数据和依赖（见 `lab/pyproject.toml`）。核心依赖只有四个：
| 依赖 | 用途 |
| --------------- | -------------------- |
| `anthropic` | Claude API 客户端 |
| `pydantic` | 数据校验与序列化 |
| `httpx` | 异步 HTTP 客户端（MCP 传输等） |
| `python-dotenv` | 环境变量管理 |
开发依赖包括 pytest（测试）、black/isort（格式化）、mypy（类型检查）、pylint（代码分析）。
这种最小依赖策略是有意为之的——作为教学项目，MiniHarness 避免引入重型框架（如 LangChain、LlamaIndex），让读者能看清 Harness 的每一层是如何从零构建的。
## 2.5.3 核心接口定义
`core/` 包定义了四组基础接口，它们是整个系统的公共语言。
### 消息系统(`core/message.py`)
消息是 Harness 中所有组件之间通信的载体。设计要点：
* **角色枚举** (`MessageRole`)：user / assistant / tool / system，与 LLM API 的角色模型对齐
* **类型枚举** (`MessageType`)：text / tool\_call / tool\_result / event，区分不同用途的消息
* **通用消息类** (`Message`)：包含 role、type、content 三个核心字段，加上 message\_id（唯一标识）、parent\_id（消息链追踪）、metadata（扩展信息）
* **特化子类**：`ToolCallMessage` 和 `ToolResultMessage` 通过 metadata 字段提供便捷属性访问
```python
# 核心消息结构(完整代码见 lab/mini_harness/core/message.py)
@dataclass
class Message:
role: MessageRole
type: MessageType
content: str
message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
parent_id: Optional[str] = None
metadata: Dict[str, Any] = field(default_factory=dict)
timestamp: datetime = field(default_factory=datetime.now)
```
选择 `dataclass` 而非 Pydantic 的 `BaseModel`，是因为核心消息需要轻量和灵活——在 Agent 循环中每秒可能创建数百个 Message 实例，dataclass 的开销更小。
### 工具接口(`core/tool.py`)
工具层的接口设计遵循“定义与实现分离”的原则：
* **`ToolInputSchema`**：描述工具参数的 JSON Schema，与 LLM 的 function calling 格式对齐
* **`ToolDefinition`**：工具的元数据（名称、描述、参数 schema、权限要求、超时时间）
* **`Tool`(ABC)**：抽象基类，子类只需实现 `execute()` 方法
这种分离使得工具注册表可以只持有 `ToolDefinition`（用于向 LLM 描述工具），而不需要加载工具的实际实现——这正是第5章将实现的延迟加载机制的基础。
### 智能体接口(`core/agent.py`)
智能体接口定义了状态机模型：IDLE → INITIALIZING → EXECUTING → COMPLETED / FAILED，以及 PAUSED 状态用于支持人机协同。`ExecutionResult` 封装了执行结果，包括状态、输出和错误信息。
### 事件系统(`core/event.py`)
事件系统为可观测性提供基础。`EventType` 枚举覆盖三类事件：任务生命周期(started/completed/failed)、步骤生命周期、工具执行生命周期，以及权限检查事件。
## 2.5.4 工具注册表
工具注册表(`tools/registry.py`)是工具层的核心数据结构，负责管理所有可用工具的注册、查找和 Schema 缓存。
```python
# 注册表核心接口(完整代码见 lab/mini_harness/tools/registry.py)
class ToolRegistry:
def register(self, tool: Tool): ... # 注册工具并缓存 Schema
def get(self, name: str) -> Tool: ... # 按名称获取工具
def list_tools(self) -> List[Dict]: ... # 返回所有工具的 Schema(供 LLM 使用)
```
注册表在注册时就缓存好工具的 Schema，避免每次 LLM 调用都重新生成——这个看似微小的优化在高频调用场景下非常重要。
## 2.5.5 配置管理
配置管理模块(`utils/config.py`)使用单例模式，从 `.env` 文件和环境变量加载配置。关键配置项包括 API 密钥、模型选择、最大步数和执行超时时间。
项目根目录的 `.env.example` 提供了配置模板，开发者只需复制并填入实际值即可开始使用。
## 2.5.6 验证脚手架
搭建完成后，运行测试来验证基础设施：
```bash
cd lab
pip install -e ".[dev]"
pytest -v
```
测试用例覆盖消息创建与序列化、工具定义与注册、智能体创建等基础功能（见 `lab/tests/unit/test_core.py` 和 `lab/tests/unit/test_tools.py`）。
## 2.5.7 下一步
至此，MiniHarness 已有了坚实的骨架：
* **公共语言** (core/)：消息、工具、智能体、事件的统一接口
* **注册机制** (tools/)：工具的注册与发现
* **配置基础** (utils/)：环境变量驱动的配置管理
* **测试框架** (tests/)：pytest + pytest-asyncio 就绪
从第4章开始，我们将在这个骨架上逐章添加子系统：运行时引擎 → 工具层 → 记忆子系统 → 输出治理 → 编排引擎 → MCP 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。
# 本章小结
本章系统地阐述了Harness的整体架构设计，包括三层+横切关注点的参考架构、核心组件的深入设计、层间接口规范和参考实现对比。以下是主要内容的总结。
## 核心架构模型
**三层 + 横切关注点参考架构**
Harness系统采用三层结构加横切关注点的方式组织，清晰地分离了不同的关注点：
```mermaid
graph TB
A["接入层
(与用户/系统的接口、协议适配)"]
B["编排层(可选)
(多智能体编排和任务分解)"]
C["智能体核心层
(单智能体执行的核心工作区)"]
D["运行时引擎
(循环中枢)"]
E["模型集成与输出治理"]
F["工具层"]
G["记忆子系统"]
H["横切关注点:安全 / 可观测性 / 存储"]
A --> B
B --> C
C --> D
C --> E
C --> F
C --> G
D -.-> H
E -.-> H
F -.-> H
G -.-> H
style C fill:#e8f4f8
style D fill:#fff4e6
style E fill:#fff4e6
style F fill:#fff4e6
style G fill:#fff4e6
style H fill:#f0f0f0
```
图 2-4：Harness三层+横切关注点架构总览
这个架构与第一章的星型子系统模型一致：模型调用、工具执行、记忆更新在运行时引擎的同一循环中交替发生，因此归属同一层（智能体核心层），而非人为分到不同层级。
## 智能体核心层的深入设计
智能体核心层是Harness系统的核心，包含四个紧密协作的子系统（运行时引擎、模型集成与输出治理、工具层、记忆子系统）：
### 运行时引擎
实现智能体的执行循环：
1. **感知**：从记忆中检索相关信息
2. **推理**：调用LLM进行思考
3. **决策**：提取工具调用意图
4. **执行**：通过工具层执行操作
5. **学习**：更新记忆和状态
关键设计模式：状态机管理、异步协调、超时控制
### 工具层
提供安全、标准化的外部系统访问：
* **工具注册表**：管理所有可用工具
* **参数验证**：确保格式和类型正确
* **权限检查**：验证执行权限
* **隔离执行**：在沙箱中运行，防止副作用
* **结果标准化**：统一的输出格式
### 记忆子系统
按生命周期支持分层记忆结构：
* **工作记忆**：当前对话的上下文窗口（LLM 上下文）
* **短期记忆**：会话级的摘要和临时状态（内存或文件）
* **长期记忆**：跨会话的持久化知识（数据库），借助向量索引支持语义检索
这三层记忆的协作，使得智能体能够跨越时间维度学习和改进。
## 安全与可观测性
两个横切的关注点贯穿整个系统：
### 安全层的关键要素
1. **权限管理**：梯度化的权限模型(Free → Ask-first → Approve-once)
2. **沙箱隔离**：进程级、容器级或VM级隔离
3. **审计日志**：记录所有关键操作
4. **输入验证**：防止注入攻击
### 可观测性层的三个支柱
1. **日志(Logs)**：结构化、可搜索的事件记录
2. **追踪(Traces)**：分布式追踪，追踪请求的完整路径
3. **指标(Metrics)**：性能指标和趋势分析
## 层间接口规范
清晰的接口是模块化系统的基础：
### 统一的消息格式
所有层间通信都使用结构化的Message对象：
* **消息基类**
* ToolCallMessage（工具调用）
* ToolResultMessage（工具结果）
* TextMessage（文本信息）
### 工具调用协议
标准化的请求-响应模式：
```mermaid
flowchart TD
A["ToolCallRequest"] -->|执行| B["ToolCallResponse"]
style A fill:#e3f2fd
style B fill:#e8f5e9
```
图 2-5：工具调用的请求-响应模式
### 事件流规范
事件总线实现发布-订阅模式，支持异步通信和解耦。
## 参考实现的对比
### OpenAI Codex
* **语言**：Rust（核心语言，具体比例以官方代码库统计为准），60+ Cargo crate 模块化
* **安全**：execpolicy 策略引擎 + 平台原生沙箱双层防御
* **上下文**：提示缓存 + 异步压缩，线性成本增长
* **编排**：Subagent 层级委派，支持 3+ 层深度
优势：系统级性能和安全保障，适合对延迟和隔离要求高的场景
### Claude Code
* **语言**：TypeScript（\~50万行），类型安全
* **架构**：模块化设计，40+ 特性门控
* **编排**：Coordinator 动态多智能体
* **集成**：24+ 内置工具 + MCP 扩展
优势：响应快速，类型安全，易于集成
### OpenClaw
* **通信**：WebSocket 长连接 + 心跳机制
* **架构**：五平面设计（数据/控制/管理/隔离/监控）
* **工作流**：Lobster 确定性引擎
* **记忆**：MEMORY.md + SOUL.md 双层
优势：支持长期自主运行，适合持久化应用
## MiniHarness脚手架
本章完成了MiniHarness项目的初始化：
### 文件结构
MiniHarness项目的完整文件结构如下所示：
* **lab/**
* pyproject.toml - 项目配置和依赖
* **mini\_harness/**
* **core/** - 核心接口定义
* message.py
* tool.py
* agent.py
* event.py
* **tools/** - 工具注册表
* registry.py
* **utils/** - 工具函数
* config.py
* **tests/** - 测试套件
* test\_core.py
* test\_registry.py
### 核心接口已定义
* **Message**：统一的消息类型
* **Tool/ToolDefinition**：工具的抽象
* **Agent**：智能体的配置
* **Event**：事件定义
* **ToolRegistry**：工具管理
### 可运行的代码
已实现完整的类型定义、序列化、注册表逻辑，并提供了基本的单元测试。
## 与其他章节的关系
各个章节之间的联系和依赖关系如下所示：
```mermaid
flowchart TD
A["第1章(概论)"] -->|定义基本概念| B["第2章(架构全景)← 你在这里"]
B -->|定义设计原则| C["第3章(设计原则)"]
C -->|实现权限和验证| D["第4-8章(子系统深入)"]
D -->|实现每个层的详细功能| E["第9-14章(高级主题)"]
E -->|生产部署、可靠性、安全加固| F["完成"]
style A fill:#e8f5e9
style B fill:#fff9c4,stroke:#ffb74d,stroke-width:2px
style C fill:#e8f5e9
style D fill:#e3f2fd
style E fill:#f3e5f5
```
图 2-6：Harness工程指南全书的章节结构与学习路径
## 关键学习点总结
| 概念 | 说明 | 实践体现 |
| ---- | -------------------------- | --------------------------------- |
| 分层架构 | 三层 + 横切关注点，明确职责 | 接入层-编排层-智能体核心层 + 安全/可观测性/存储 |
| 执行循环 | 智能体的核心是感知-推理-决策-执行的循环 | RuntimeEngine的步骤实现 |
| 工具抽象 | 统一各种外部系统的接口 | ToolRegistry和Tool基类 |
| 三层记忆 | 短期+长期+向量，支持学习 | MemoryManager的设计 |
| 权限管理 | 梯度化信任，从Free到Approve-always | PermissionManager和AuditLog |
| 可观测性 | 日志+追踪+指标 | Logger, Tracer, MetricsCollector |
| 接口规范 | 清晰的消息格式和协议 | Message, ToolCallRequest/Response |
## 常见设计问题与答案
### Q: 为什么要有编排层？
**A**: 当任务过于复杂，无法由单个Agent完成时，编排层负责分解任务、分配给专门的Agent、汇总结果。即使对于简单系统，编排层也可以很轻薄。
### Q: 为什么需要三层记忆？
**A**: 不同的使用场景对记忆的要求不同。工作记忆快速访问当前上下文，短期记忆保留会话级的摘要和状态，长期记忆持久化跨会话的知识并借助向量索引支持语义检索。三层按生命周期递进，形成完整的记忆体系。
### Q: 工具层的权限检查和安全层的权限检查重复了吗？
**A**: 不重复。工具层检查的是智能体能否调用该工具，安全层检查的是整个系统级别的权限政策。前者更细粒度，后者更宏观。
### Q: 为什么需要事件总线？
**A**: 事件总线实现了不同子系统的解耦。监控系统可以订阅所有事件来进行可观测性，权限系统可以订阅工具执行事件，而不需要运行时引擎直接依赖它们。
## 后续学习路径
1. **第3章**：深入学习设计原则，特别是“约束优先”和“渐进信任”
2. **第4章**：实现完整的运行时引擎，包括错误处理和重试策略
3. **第5章**：实现各种工具的适配器，学习如何集成真实系统
4. **第6章**：实现记忆系统，包括向量数据库集成
## 代码审查清单
完成本章的脚手架搭建后，检查以下内容：
* [ ] 项目目录结构完整
* [ ] pyproject.toml依赖配置正确
* [ ] 核心接口(message, tool, agent, event)已定义
* [ ] 工具注册表实现正确
* [ ] 所有单元测试通过
* [ ] 代码风格一致（Black格式化）
* [ ] 类型提示完整（mypy检查）
* [ ] 文档注释充分
完成这些检查后，MiniHarness项目将为后续的功能开发提供坚实的基础。
# 第三章：设计原则与方法论
本章从哲学和方法论的高度，总结了在构建生产级Harness系统时应该遵循的四大设计原则。
这些原则不是从零开始发明的，而是从Claude Code、OpenClaw以及业界其他成功的智能体系统中提炼出来的最佳实践。它们在看似不同的架构中都能找到体现，这证明了它们的普遍性和重要性。
**约束优先(Constraint-first)** 强调的是，对智能体能力的合理限制，往往比无限制地赋予能力更为关键。通过明确的约束边界，我们既保证了安全性，也提高了系统的可预测性。
**可验证性(Verifiability)** 要求系统的每一个操作都应该是可审计的、可重放的、可验证的。这不仅是安全合规的要求，更是快速定位问题的基础。
**渐进信任(Progressive Trust)** 描述了如何从人工密集的管理模式逐步演进到自主执行模式。这个过程应该是可观测的、可回退的、循序渐进的。
**故障假设(Design for Failure)** 要求我们在设计时，主动假设每一步都可能失败，并提前设计失败的处理机制。这样做的收益是，即使出现意外，系统也能够优雅地降级而非彻底崩溃。
这四大原则相互补充、相互强化，共同构建了一个安全、可靠、可管理的智能体系统。
## 本章结构
* 3.1：约束优先原则
* 3.2：可验证性原则
* 3.3：渐进信任原则
* 3.4：故障假设原则
# 3.1 约束优先原则
本节介绍约束优先原则的核心理念、重要性、约束的分类、设计方法和实施策略，阐明为什么约束是构建安全智能体系统的首要考虑。
## 3.1.1 原则的核心
**约束优先** 意味着：在设计Harness系统时，首先考虑的不是“智能体能做什么”，而是“Agent不能做什么”、“Agent做事时的限制是什么”。
这与直觉相反。通常我们在构建系统时，首先关心的是功能特性——系统应该具备什么能力。但对于智能体系统，这个思路导致了无尽的“功能蔓延”和安全隐患。
约束优先原则翻转了这个优先级：
1. **首先定义约束**：明确智能体可以做的事(Permission Model)
2. **然后在约束内赋能**：通过工具和模型来实现功能
3. **最后验证合规**：确保所有操作都在约束内
## 3.1.2 为什么约束如此重要
本小节通过现象观察、成本分析和失败案例，论证约束机制在智能体系统中的关键作用。
### 现象观察
在Claude Code中，有一个叫“protected files”的机制，以及“dangerous patterns”的检测。这些都是约束。
在OpenClaw中，有一个叫SOUL.md的约束文档。这个文档不是系统的“特性”，而是智能体的“戒律”。它定义了Agent绝对不能做的事。
有趣的是，许多智能体系统失败的原因，往往不是因为模型不够聪明，而是因为缺乏足够的约束。Agent学会了用户没有授权的方式做事，执行了超越权限的操作，或者被用户恶意利用。
### 约束能解决什么
**1. 安全性** 通过约束，我们明确地防止某些危险操作。比如：
* 不允许删除生产数据库的内容
* 不允许修改系统配置文件
* 不允许执行需要人工审批的操作
**2. 可预测性** 有约束的系统比无约束系统更容易被理解和维护：
| 约束方式 | 系统状态 | 可测试性 |
| ------- | ------------------- | ------------------------ |
| **无约束** | 智能体可以调用任何API | 很难预测会发生什么；难以编写测试用例 |
| **有约束** | Agent只能调用预先批准的API列表 | 系统行为在可预期的范围内；易于编写和维护测试用例 |
**3. 可审计性** 有约束的系统更容易被审计：
```
审计问题:智能体为什么执行了X操作？
无约束答案:谁知道呢,模型就是这样决定的
有约束答案:因为这个操作在智能体的权限列表中,
并且满足了Y条件,所以被批准了
```
## 3.1.3 约束的多个维度
约束可以在多个维度进行定义和实现。如图所示，约束可以分为四个关键维度：
```mermaid
graph TB
subgraph "约束维度"
A["权限维度
定义能访问什么资源"]
B["操作维度
定义什么操作被禁止"]
C["时间维度
定义什么时候可以操作"]
D["数据维度
定义什么数据可以处理"]
end
style A fill:#e1f5ff
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8f5e9
```
图 3-1：约束的四个维度
### 1. 权限维度
定义智能体能访问什么资源：
```python
class PermissionConstraint:
"""权限约束"""
# 工具级约束:哪些工具可用
available_tools = [
"weather_api",
"send_email",
"retrieve_documents"
]
# 资源级约束:可以访问哪些资源
resource_access = {
"database": {
"tables": ["users", "orders"], # 只能访问这些表
"operations": ["read"], # 只能读,不能写
"row_limit": 1000 # 最多一次查询1000行
},
"file_system": {
"paths": ["/data/public/"], # 只能访问这个目录
"operations": ["read"]
}
}
# 用户级约束:可以操作哪些用户的数据
user_scope = {
"current_user_only": True, # 只能操作当前用户的数据
"allowed_org_ids": ["org-123", "org-456"]
}
```
### 2. 操作维度
定义什么样的操作是被禁止的：
```python
class OperationConstraint:
"""操作约束"""
# 绝对禁止的操作
forbidden_operations = [
"delete_database_records",
"modify_user_permissions",
"export_user_data",
"disable_audit_logging"
]
# 受限制的操作(需要额外的验证或审批)
restricted_operations = {
"transfer_money": {
"requires_approval": True,
"approval_type": "human",
"max_amount_per_operation": 10000,
"max_amount_per_day": 100000
},
"send_communication": {
"requires_approval": False,
"rate_limit": "100_per_hour",
"allowed_channels": ["email", "sms"]
}
}
# 隐藏的危险操作(Agent应该意识不到它们的存在)
hidden_operations = [
"access_internal_debug_endpoints",
"trigger_system_shutdown"
]
```
### 3. 时间维度
定义什么时候某些操作被允许：
```python
class TimeConstraint:
"""时间约束"""
# 可用时间窗口
availability_window = {
"weekdays": {
"start_hour": 9,
"end_hour": 17,
"timezone": "UTC"
},
"weekends": None # 周末不可用
}
# 速率限制
rate_limits = {
"api_calls_per_minute": 60,
"database_queries_per_minute": 100,
"expensive_operations_per_hour": 10
}
# 过期时间
expiration = {
"credentials_expire_after_days": 90,
"session_timeout_minutes": 60
}
```
### 4. 数据维度
定义什么样的数据可以被处理：
```python
class DataConstraint:
"""数据约束"""
# 数据大小限制
size_limits = {
"max_file_size_mb": 100,
"max_api_response_size_mb": 10,
"max_result_rows": 10000
}
# 数据敏感性处理
sensitive_data_handling = {
"pii_fields": ["email", "phone", "ssn"],
"handling": "redact" # 或 "encrypt", "deny"
}
# 数据流向限制
allowed_data_destinations = [
"internal_database",
"approved_third_party_api"
]
forbidden_data_destinations = [
"public_cloud_storage",
"external_email"
]
```
## 3.1.4 Claude Code的protected files和dangerous patterns
Claude Code的约束体现在多个地方：
### Protected Files
系统通过保护文件列表来防止访问敏感文件：
```python
PROTECTED_FILES = [
"/etc/passwd",
"/etc/shadow",
"~/.ssh/id_rsa",
"~/.aws/credentials"
]
# 系统会在Agent尝试访问这些文件前拦截
if file_path in PROTECTED_FILES:
raise PermissionError(f"Cannot access {file_path}")
```
### Dangerous Patterns
通过检测危险的命令模式来防止恶意操作：
```python
DANGEROUS_PATTERNS = [
r"DROP\s+TABLE", # SQL注入
r"rm\s+-rf", # 破坏性命令
r"format\s+[A-Z]:", # 格式化磁盘
r"curl.*\|.*sh" # 下载并执行
]
for pattern in DANGEROUS_PATTERNS:
if re.search(pattern, agent_output):
raise SecurityError(f"Dangerous pattern detected: {pattern}")
```
## 3.1.5 OpenClaw的SOUL.md约束
OpenClaw使用一个特殊的SOUL.md文件来定义智能体的约束：
```
## 智能体 SOUL.md
### 绝对约束
- 不能访问生产环境中的个人身份信息(PII)
- 不能执行删除操作
- 不能修改其他智能体的配置
- 不能访问加密的密钥存储
### 条件约束
- 只能在工作时间调用昂贵的API
- 财务操作需要人工审批
- 大规模数据导出需要安全主管批准
### 能力约束
- 最多并发10个任务
- 单个任务最多100步
- 内存占用不超过1GB
- 单个API调用超时30秒
```
SOUL.md的特殊之处在于：
1. **可读可维护**：用人类可读的方式定义约束，便于审查
2. **可验证**：系统在运行时可以检查智能体的行为是否违反SOUL.md
3. **可追溯**：当出现问题时，可以追踪到具体哪个约束被违反了
## 3.1.6 约束与效能的平衡
一个常见的疑问是：过度约束会不会限制智能体的能力？
答案是：取决于约束的设计。好的约束不会限制能力，反而会使智能体更加聪明。
**对比：机械臂和外科医生**
**机械臂没有约束** → 可以随意摆动，但容易伤害周围的人 **外科医生有约束** → 规范的操作流程，但能够精确地完成复杂手术
**Agent没有约束** → 可以做任何事，但经常出错或做不该做的事 **Agent有约束** → 在清晰的界限内工作，能够可靠地完成任务
好的约束实际上使智能体更有效。它们：
1. **减少歧义**：Agent不用浪费推理能力在“该不该做”上
2. **加快执行**：许多禁止的路径被剪除，搜索空间变小
3. **提高成功率**：少了“想做但不能做”的冲突
## 3.1.7 约束的实现模式
如图所示，约束的实现模式从最严格的白名单到最灵活的规则引擎，提供了不同的安全性和灵活性权衡：
```mermaid
graph LR
A["白名单模式
最安全
最严格"] --> B["黑名单模式
中等安全
较灵活"]
B --> C["规则引擎模式
可控安全
最灵活"]
style A fill:#ffebee
style B fill:#fff9c4
style C fill:#e8f5e9
```
图 3-2：约束实现模式的安全性和灵活性权衡
### 模式1：白名单模式
白名单模式通过明确指定允许的操作来实现最高的安全性：
```python
class WhitelistConstraint:
"""白名单:只有明确批准的操作才能进行"""
def can_perform(self, operation: str) -> bool:
return operation in self.allowed_operations
allowed_operations = {
"read_data",
"send_notification",
"update_user_profile"
}
```
### 模式2：黑名单模式
黑名单模式通过禁止特定的危险操作，允许其他所有操作：
```python
class BlacklistConstraint:
"""黑名单:明确禁止的操作不能进行"""
def can_perform(self, operation: str) -> bool:
return operation not in self.forbidden_operations
forbidden_operations = {
"delete_data",
"modify_permissions",
"system_shutdown"
}
```
### 模式3：规则引擎模式
规则引擎模式使用条件化的规则集，实现细粒度的访问控制：
```python
class RuleBasedConstraint:
"""基于规则的约束"""
def can_perform(self, operation: str, context: dict) -> bool:
"""根据上下文和规则判断是否允许操作"""
# 规则1:删除操作需要特殊权限
if "delete" in operation:
if "admin_privileges" not in context:
return False
# 规则2:成本超过100元的操作需要审批
if context.get("operation_cost", 0) > 100:
if "approval_granted" not in context:
return False
# 规则3:工作时间外的某些操作不允许
if datetime.now().hour > 18:
if operation in self.after_hours_forbidden:
return False
return True
```
## 3.1.8 约束的监控和违反处理
约束仅仅定义是不够的，还需要在运行时监控和执行。
```python
class ConstraintEnforcer:
"""约束执行器"""
def __init__(self, constraints: List[Constraint]):
self.constraints = constraints
self.violations = []
async def check_and_enforce(
self,
operation: Operation,
context: dict
) -> bool:
"""
检查操作是否违反约束。
返回:是否允许操作
"""
for constraint in self.constraints:
if not constraint.allows(operation, context):
# 记录违反
self.violations.append({
"timestamp": datetime.now(),
"constraint": constraint.name,
"operation": operation,
"context": context
})
# 日志警告
logger.warning(
f"Constraint violation: {constraint.name}",
extra={"operation": operation}
)
return False
return True
def get_violations(self) -> List[dict]:
"""获取所有的约束违反记录"""
return self.violations
```
## 3.1.9 约束的演进
约束不是一成不变的。随着系统的运行和学习，约束也应该演进。
```mermaid
flowchart TD
A["初期
保守的约束,防止任何可能的问题"] -->|观察运行数据
发现大多数约束很少被触发| B["中期
根据实际情况调整约束"]
B -->|放宽某些不必要的约束
加强某些存在问题的约束| C["稳定期
约束和实际需求达成平衡"]
style A fill:#ffebee
style B fill:#fff9c4
style C fill:#e8f5e9
```
这个演进过程应该基于数据和观测，而不是猜测。
## 3.1.10 总结
约束优先原则的核心要点：
1. **安全第一**：约束不是限制，而是保护
2. **清晰定义**：约束应该明确、可读、可验证
3. **多维度约束**：权限、操作、时间、数据等多个维度
4. **平衡与灵活**：约束和能力之间找到平衡，使用规则引擎获得灵活性
5. **监控与演进**：约束需要被监控、被验证、随时间演进
在后续章节，我们将看到这个原则如何在具体的工具层、权限管理等地方落实。
# 3.2 可验证性原则
本节阐述可验证性原则的含义，说明其在生产系统中的重要性，深入讨论可验证性的三个层次及其实现方法。
## 3.2.1 原则的核心
**可验证性** 意味着：系统的每一个行为都应该是可观察的、可审计的、可重放的。当被问“Agent做了什么？”和“为什么这样做？”时，系统应该能够提供清晰、完整的答案。
这一原则在智能体时代变得尤为关键。传统软件的行为由预先编写的代码决定，而 Agent 的行为路径是 LLM 在运行时动态生成的——这些被称为“暗码(Dark Code)”的运行时行为执行完毕后即消散，无法像源代码一样被事先审查或精确复现。可验证性正是 Harness 对抗暗码的核心武器：通过将“即生即灭”的行为转化为“可观察、可追踪、可重放”的记录，让动态行为获得与静态代码同等的可审计性。
可验证性涵盖三个层面：
1. **可观察性**：看得见智能体在做什么
2. **可追踪性**：追踪来自何处，去往何处
3. **可重放性**：给定相同的输入，能够重现相同的结果
## 3.2.2 为什么可验证性至关重要
本小节通过具体问题场景、法规要求和技术挑战，说明可验证性为什么是系统可靠运行的基础。
### 问题场景
想象以下情况：
* 智能体执行了一个转账操作，但钱到了错误的账户
* Agent生成了一个不符合规范的法律文件，造成了合规问题
* Agent多次调用同一个API，导致重复扣款
在这些情况下，最紧迫的问题是：**发生了什么？以及为什么？**
如果系统不可验证，这些问题就无法被回答。开发者只能：
* 陷入无尽的调试
* 无法向用户解释
* 无法修复根本原因
### 可验证性的价值
**1. 快速诊断** 有完整的审计日志和执行追踪，我们可以立即看到问题发生的位置。
**2. 用户信任** 当用户询问“这笔钱去哪了？”，如果我们能够提供详细的操作日志，用户会更有信心。
**3. 法律合规** 许多行业（金融、医疗、法律）都要求对所有关键操作进行审计。
**4. 系统改进** 通过观察和分析执行数据，我们能够识别出系统的瓶颈和改进空间。
## 3.2.3 可验证性的三个层次
本小节从基础到高级，分别介绍操作日志、执行追踪和可重放性三个层次的可验证性，以及它们的实现方法。
### 第一层：操作日志
最基础的可验证性：记录发生了什么。
```python
@dataclass
class OperationLog:
"""操作日志"""
timestamp: datetime
agent_id: str
operation_type: str # "tool_call", "permission_check", "decision"
operation_name: str # 具体的操作名称
input: dict # 输入参数
output: dict # 输出结果
status: str # "success", "error", "permission_denied"
duration_ms: float # 耗时
error_message: Optional[str] = None
class OperationLogger:
"""操作日志记录器"""
async def log(self, operation_log: OperationLog) -> None:
"""记录一个操作"""
# 格式化为可读的形式
log_entry = {
"timestamp": operation_log.timestamp.isoformat(),
"agent": operation_log.agent_id,
"type": operation_log.operation_type,
"operation": operation_log.operation_name,
"status": operation_log.status,
"duration_ms": operation_log.duration_ms
}
# 写入日志存储
await self.storage.append(log_entry)
# 如果是错误,也要输出到错误流
if operation_log.status == "error":
logger.error(f"Operation failed: {operation_log.operation_name}",
extra={"log_entry": log_entry})
```
### 第二层：执行追踪
更高级的可验证性：记录操作之间的因果关系。
```python
@dataclass
class ExecutionTrace:
"""执行追踪"""
trace_id: str # 追踪的全局唯一ID
agent_id: str
task_id: str
steps: List[TraceStep] = field(default_factory=list)
start_time: datetime = field(default_factory=datetime.now)
end_time: Optional[datetime] = None
@dataclass
class TraceStep:
"""追踪中的一步"""
step_id: str # 步骤ID
parent_step_id: Optional[str] # 父步骤(用于嵌套调用)
operation: str
input: dict
output: dict
duration_ms: float
timestamp: datetime
status: str
class ExecutionTracer:
"""执行追踪器"""
def __init__(self):
self.traces: Dict[str, ExecutionTrace] = {}
def start_trace(
self,
agent_id: str,
task_id: str,
trace_id: str = None
) -> str:
"""开始一个新的执行追踪"""
trace_id = trace_id or str(uuid.uuid4())
self.traces[trace_id] = ExecutionTrace(
trace_id=trace_id,
agent_id=agent_id,
task_id=task_id
)
return trace_id
def add_step(
self,
trace_id: str,
operation: str,
input: dict,
output: dict,
duration_ms: float,
parent_step_id: str = None
) -> str:
"""在追踪中添加一步"""
step_id = str(uuid.uuid4())
step = TraceStep(
step_id=step_id,
parent_step_id=parent_step_id,
operation=operation,
input=input,
output=output,
duration_ms=duration_ms,
timestamp=datetime.now(),
status="success"
)
self.traces[trace_id].steps.append(step)
return step_id
def get_trace(self, trace_id: str) -> Optional[ExecutionTrace]:
"""获取完整的执行追踪"""
return self.traces.get(trace_id)
def visualize_trace(self, trace_id: str) -> str:
"""生成可视化的执行追踪"""
trace = self.traces.get(trace_id)
if not trace:
return ""
# 生成缩进的树形结构
lines = [f"Trace: {trace.trace_id}"]
lines.append(f"Agent: {trace.agent_id}, Task: {trace.task_id}")
lines.append(f"Duration: {(trace.end_time - trace.start_time).total_seconds():.2f}s")
lines.append("")
def add_step_lines(step: TraceStep, indent: int = 0):
prefix = " " * indent
lines.append(f"{prefix}├─ {step.operation} ({step.duration_ms:.0f}ms)")
lines.append(f"{prefix}│ Input: {step.input}")
lines.append(f"{prefix}│ Output: {step.output}")
for step in trace.steps:
if step.parent_step_id is None:
add_step_lines(step)
return "\n".join(lines)
```
### 第三层：可重放性
最高级的可验证性：给定相同的输入，能够重现执行过程。
```python
class ReplayableExecution:
"""可重放的执行"""
def __init__(self, trace: ExecutionTrace):
self.trace = trace
self.step_index = 0
async def replay(
self,
runtime: RuntimeEngine,
simulation: bool = False
) -> ReplayResult:
"""
重放执行。
simulation: 如果为True,不实际执行工具,而是返回记录的结果
"""
results = []
for step in self.trace.steps:
if simulation:
# 模拟模式:直接返回记录的结果
results.append({
"operation": step.operation,
"recorded_output": step.output,
"simulation": True
})
else:
# 实际重放:重新执行相同的操作
try:
actual_output = await self._execute_step(
step.operation,
step.input
)
# 验证输出是否一致
if actual_output == step.output:
results.append({
"operation": step.operation,
"status": "consistent",
"output": actual_output
})
else:
results.append({
"operation": step.operation,
"status": "diverged",
"recorded_output": step.output,
"actual_output": actual_output
})
except Exception as e:
results.append({
"operation": step.operation,
"status": "error",
"error": str(e)
})
return ReplayResult(
trace_id=self.trace.trace_id,
results=results,
is_consistent=all(r["status"] == "consistent" for r in results)
)
async def _execute_step(self, operation: str, input: dict):
"""执行一个步骤"""
# 实现取决于具体的操作类型
pass
```
## 3.2.4 生产系统中的可验证性实践
Claude Code 使用 OpenTelemetry 标准进行追踪，这使得可以与许多现成的 APM 工具集成：
```typescript
// Claude Code 追踪示例
const span = tracer.startSpan("tool_execution", {
attributes: {
"tool.name": "weather_api",
"tool.params": JSON.stringify(params),
"agent.id": agentId
}
});
try {
const result = await executeWeatherAPI(params);
span.setStatus({ code: SpanStatusCode.OK });
span.end();
} catch (error) {
span.recordException(error);
span.setStatus({ code: SpanStatusCode.ERROR });
span.end();
}
```
这种标准化的追踪方式的好处是：
* 可以与Jaeger、Zipkin等可视化工具集成
* 支持分布式追踪（跨多个微服务）
* 标准的性能分析
OpenClaw的Lobster引擎特别强调可重放性。每个工作流的执行都被记录在一个确定性的日志中：
```yaml
## Lobster execution log
workflow_id: workflow-123
execution_id: exec-456
steps:
- step_id: 1
operation: query_database
input:
query: "SELECT * FROM users WHERE id = ?"
params: [123]
output:
- id: 123
name: "John Doe"
timestamp: 2024-04-01T10:30:00Z
- step_id: 2
operation: send_notification
input:
user_id: 123
message: "Hello John"
output:
status: "sent"
notification_id: "notif-789"
timestamp: 2024-04-01T10:30:01Z
```
Lobster的特点：
1. **确定性**：给定相同的workflow和输入，执行顺序总是相同
2. **可重放**：可以从任何步骤重新开始执行
3. **可审计**：完整的操作历史，精确到每一步
## 3.2.5 可验证性在实战中的应用
**场景：转账操作**
一个典型的转账操作应该被追踪如下：
**Trace ID:** trace-2024-04-01-001
| 步骤 | 操作 | 输入 | 输出 | 耗时 |
| -- | ------------------------- | -------------------------------------------------- | ---------------------------------------------- | ----- |
| 1 | Parse Request | {"from": "ACC001", "to": "ACC002", "amount": 1000} | {"from\_account": {...}, "to\_account": {...}} | 2ms |
| 2 | Check Balance | {"account\_id": "ACC001"} | {"balance": 5000} | 15ms |
| 3 | Validate Transaction | {"amount": 1000, "available\_balance": 5000} | {"valid": true} | 1ms |
| 4 | Create Transaction Record | {"from": "ACC001", "to": "ACC002", "amount": 1000} | {"transaction\_id": "TXN12345"} | 50ms |
| 5 | Execute Transfer | {"transaction\_id": "TXN12345"} | {"status": "completed"} | 100ms |
| 6 | Send Confirmation | {"transaction\_id": "TXN12345"} | {"notification\_sent": true} | 30ms |
**总耗时：** 198ms **最终状态：** Success
当用户问“我的转账怎么样了？”，我们可以立即从这个追踪中回答：
* **什么时候执行的？** 2024-04-01 at 10:30:00
* **执行了哪些步骤？** 6个步骤，每一步都成功了
* **如果失败了，在哪个步骤失败？**（不适用，这里全部成功）
* **整个过程花了多长时间？** 198毫秒
## 3.2.6 实现可验证性的最佳实践
本小节介绍实现可验证性的具体方法，包括结构化日志、链接日志和追踪、定期验证和用户可读摘要。
### 1. 使用结构化日志
结构化日志使用JSON格式记录关键字段，便于验证和审计：
```python
# 不好:非结构化日志
logger.info("Transfer from ACC001 to ACC002 for amount 1000")
# 好:结构化日志
logger.info("transfer_executed", extra={
"from_account": "ACC001",
"to_account": "ACC002",
"amount": 1000,
"transaction_id": "TXN12345",
"status": "success",
"duration_ms": 198
})
```
### 2. 链接日志和追踪
通过trace ID将分布式日志和追踪关联起来，实现全链路可观测性：
```python
# 在日志中包含trace ID,便于关联
logger.info("Step completed", extra={
"trace_id": trace.trace_id,
"step_id": step.step_id,
"operation": "tool_call"
})
```
### 3. 定期验证一致性
通过重放历史执行来验证系统行为的确定性和一致性：
```python
async def periodic_verification():
"""定期验证执行的一致性"""
# 每小时,随机选择一个旧的执行,尝试重放
old_traces = await trace_storage.list_old_traces(
before_hours=1,
limit=10
)
for trace in old_traces:
replayer = ReplayableExecution(trace)
result = await replayer.replay(runtime, simulation=False)
if not result.is_consistent:
logger.error("Inconsistency detected in replay",
extra={"trace_id": trace.trace_id})
# 触发告警,通知运维
```
### 4. 提供用户可读的摘要
虽然完整的追踪对于调试很有用，但用户通常需要一个简化版本：
```python
def generate_user_summary(trace: ExecutionTrace) -> str:
"""生成用户友好的摘要"""
total_duration = (trace.end_time - trace.start_time).total_seconds()
success_count = sum(1 for step in trace.steps if step.status == "success")
error_count = sum(1 for step in trace.steps if step.status == "error")
return f"""
执行摘要:
- 执行ID:{trace.trace_id[:8]}...
- 执行时间:{trace.start_time.strftime('%Y-%m-%d %H:%M:%S')}
- 耗时:{total_duration:.2f}秒
- 步骤数:{len(trace.steps)}(成功{success_count},失败{error_count})
- 状态:{'成功' if error_count == 0 else '失败'}
详细日志:{generate_trace_url(trace.trace_id)}
"""
```
## 3.2.7 总结
可验证性原则的关键要点：
1. **三个层次**：操作日志 → 执行追踪 → 可重放性
2. **结构化数据**：使用统一的格式，便于机器和人类读取
3. **完整的链路**：从请求到响应，每一步都能被追踪
4. **可视化**：提供人类可读的总结和可视化工具
5. **定期验证**：通过重放，验证系统的一致性
实现可验证性看起来增加了复杂性，但它的回报是巨大的：快速诊断、用户信任、法律合规、系统改进。
# 3.3 渐进信任原则
本节阐述渐进信任原则，介绍权限梯度模型、信任评分机制、动态权限调整和实施策略，说明如何通过观察和学习逐步提升智能体的自主权。
## 3.3.1 原则的核心
**渐进信任** 意味着：不要期望一下子就完全信任智能体的自主执行。而是应该设计一个逐步提升信任等级的过程，从完全人工控制，通过观察和学习，最终达到自主执行。
这个过程可以用一个信任梯度来表示：
| 信任等级 | 权限配置 | 实现方式 |
| ------------------------------- | ------ | ---------- |
| Level 0: Manual Only | 完全人工操作 | 每一步都需要人工批准 |
| Level 1: Approve Always | 每步审批 | 每个操作都需要批准 |
| Level 2: Approve Once | 一次性批准 | 任务开始时批准一次 |
| Level 3: Ask First | 事前询问 | 执行前要求人工确认 |
| Level 4: Auto with Notification | 自动+通知 | 自动执行并发送通知 |
| Level 5: Full Trust | 充分信任 | 完全自主，无需监控 |
这个梯度不是固定的，而是应该根据系统的表现动态调整的。如图所示，信任等级从完全人工操作逐步提升到完全自主执行：
```mermaid
graph LR
A["完全人工"] --> B["每步审批"]
B --> C["一次性批准"]
C --> D["事前询问"]
D --> E["自动+通知"]
E --> F["完全自主"]
style A fill:#ffebee
style B fill:#ffe0b2
style C fill:#fff9c4
style D fill:#f0f4c3
style E fill:#dcedc8
style F fill:#c8e6c9
```
图 3-3：渐进信任的六个等级
## 3.3.2 为什么需要渐进信任
本小节分析信任陡崖问题，说明渐进信任相比传统二元模式的优势。
### 问题背景
许多AI系统的部署都失败于“信任陡崖”：
* 开发阶段：我们对模型进行了充分的测试，认为它已经足够聪明
* 部署阶段：我们突然给予它完全的自主权
* 灾难阶段：系统在真实世界中出现意外的行为
这种模式很像是：“我们在学校考试中得了A，所以直接让这个学生毕业去当医生”。
渐进信任的思想是：**逐步提升权限，同时持续观察系统的行为**。
### 渐进信任的收益
**1. 降低风险** 新权限的错误不会立即导致大规模灾难，而是被限制在较小的范围内。
**2. 积累证据** 通过观察系统在较低权限级别的表现，我们可以获得足够的证据，来判断是否应该提升权限。
**3. 快速恢复** 如果智能体在某个权限级别出错，我们可以降回之前的级别，而不是直接禁用。
**4. 用户信心** 逐步的权限提升给了用户看得见的进展和控制感。
## 3.3.3 权限梯度的详细设计
本小节详细介绍六个权限等级，从完全人工到完全信任，每个级别的实现方式和适用场景。
### Level 0: Manual Only
完全人工模式要求每一步操作都经过人工审批，提供最高的控制和安全性：
```python
class ManualOnlyMode:
"""完全人工操作模式"""
async def execute_operation(self, operation: Operation) -> Result:
"""
每一步都需要人工批准。
"""
# 1. Agent提议操作
proposal = await agent.propose_operation(task)
# 2. 等待人工批准
approval = await request_human_approval(
operation=proposal,
timeout=timedelta(hours=24)
)
if approval.approved:
# 3. 由人工或系统执行
result = await execute_operation(proposal)
else:
result = Result(status="rejected", reason=approval.reason)
return result
```
**适用场景**：系统刚上线，信任度最低
### Level 1: Approve Always
每步审批模式要求每个操作执行前都获得人工批准，适合高风险操作：
```python
class ApproveAlwaysMode:
"""每个操作都需要人工审批"""
async def execute_operation(self, operation: Operation) -> Result:
"""
每个操作都需要事前批准。
"""
# 请求批准
approval = await request_human_approval(
operation=operation,
timeout=timedelta(minutes=5)
)
if not approval.approved:
return Result(status="rejected")
# 执行操作
return await execute_operation(operation)
```
**适用场景**：高风险操作，每一步都需要人工确认
### Level 2: Approve Once
一次性批准模式在任务开始时获得完整批准，减少审批频次同时保持控制：
```python
class ApprovedOnceMode:
"""任务开始时批准一次"""
async def execute_task(self, task: Task) -> Result:
"""
在任务开始时,对整个任务进行一次审批。
一旦批准,任务执行过程中不再询问。
"""
# 1. 任务规划阶段:Agent提议任务计划
plan = await agent.plan_task(task)
# 2. 人工审查:人工查看任务计划
approval = await request_task_approval(
task=task,
plan=plan,
timeout=timedelta(hours=1)
)
if not approval.approved:
return Result(status="rejected")
# 3. 执行阶段:任务自动执行
result = await execute_task_plan(plan)
# 4. 完成:生成执行报告
report = generate_execution_report(result)
return Result(
status="success",
output=result,
report=report
)
```
**适用场景**：生产环境，系统已证明可靠性
### Level 3: Ask First
事前询问模式仅在执行关键操作前进行交互确认，平衡了自动化和安全性：
```python
class AskFirstMode:
"""关键操作事前询问"""
# 定义哪些操作被认为是关键的
CRITICAL_OPERATIONS = {
"delete_data",
"transfer_money",
"modify_permissions"
}
async def execute_operation(self, operation: Operation) -> Result:
"""
关键操作需要事前询问,其他操作自动执行。
"""
if operation.type in self.CRITICAL_OPERATIONS:
# 关键操作:询问
approval = await request_human_approval(
operation=operation,
timeout=timedelta(minutes=5)
)
if not approval.approved:
return Result(status="rejected")
# 执行操作
return await execute_operation(operation)
```
**适用场景**：开发/测试环境，系统表现良好但仍需对关键操作保持警觉
### Level 4: Auto with Notification
自动执行加通知模式允许自动执行，同时实时通知用户进度和异常情况：
```python
class AutoWithNotificationMode:
"""自动执行,并发送通知"""
async def execute_operation(self, operation: Operation) -> Result:
"""
自动执行操作,执行后发送通知。
"""
try:
# 执行操作
result = await execute_operation(operation)
# 发送通知
await notify_user(
message=f"Operation {operation.type} completed",
details=result,
urgency="low"
)
return result
except Exception as e:
# 出错时发送警告通知
await notify_user(
message=f"Operation {operation.type} failed",
error=str(e),
urgency="high"
)
return Result(status="error", error=str(e))
```
**适用场景**：低风险日常操作，需要用户知晓
### Level 5: Full Trust
充分信任模式完全自主执行，适合已充分验证且风险极低的场景：
```python
class FullTrustMode:
"""充分信任,无需额外监控"""
async def execute_operation(self, operation: Operation) -> Result:
"""
完全信任Agent,无需额外的验证或监控。
"""
return await execute_operation(operation)
```
**适用场景**：系统已经运行多年，证明了其可靠性（罕见）
## 3.3.4 从一个等级提升到下一个等级
权限提升不应该是自动的，而应该基于明确的证据。
```python
class TrustEvaluator:
"""信任等级评估器"""
# 各信任等级的提升标准
PROMOTION_CRITERIA = {
"Manual Only → Approve Always": {
"min_operations": 100,
"min_success_rate": 0.99, # 99%成功率
"min_duration_days": 7, # 运行至少7天
"no_critical_errors": True
},
"Approve Always → Approve Once": {
"min_operations": 1000,
"min_success_rate": 0.995, # 99.5%
"min_duration_days": 30,
"no_critical_errors": True,
"recent_error_rate": 0.005 # 最近的错误率<0.5%
},
"Approve Once → Ask First": {
"min_operations": 10000,
"min_success_rate": 0.999, # 99.9%
"min_duration_days": 90,
"no_critical_errors": True
},
"Ask First → Auto with Notification": {
"min_operations": 50000,
"min_success_rate": 0.9999, # 99.99%
"min_duration_days": 180,
"no_critical_errors_in_recent_month": True
},
"Auto with Notification → Full Trust": {
"min_operations": 1000000,
"min_success_rate": 0.99999, # 99.999%
"min_duration_days": 365,
"no_critical_errors_in_recent_quarter": True
}
}
async def evaluate_promotion(
self,
current_level: TrustLevel,
agent_history: AgentHistory
) -> Optional[TrustLevel]:
"""
评估是否应该提升智能体的信任等级。
"""
next_level = self._get_next_level(current_level)
criteria = self.PROMOTION_CRITERIA.get(f"{current_level} → {next_level}")
if criteria is None:
return None # 已经是最高等级
# 检查所有标准
checks = {
"operations": agent_history.total_operations >= criteria["min_operations"],
"success_rate": agent_history.success_rate >= criteria["min_success_rate"],
"duration": agent_history.days_running >= criteria["min_duration_days"],
"critical_errors": not criteria.get("no_critical_errors", False)
or not agent_history.has_critical_errors
}
# 所有标准都满足才能提升
if all(checks.values()):
logger.info(f"Agent {agent_history.agent_id} promoted from {current_level} to {next_level}",
extra={"checks": checks})
return next_level
logger.info(f"Agent promotion blocked",
extra={"agent_id": agent_history.agent_id, "failed_checks": {k: v for k, v in checks.items() if not v}})
return None
def _get_next_level(self, current_level: TrustLevel) -> TrustLevel:
"""获取下一个信任等级"""
levels = [
"Manual Only",
"Approve Always",
"Approve Once",
"Ask First",
"Auto with Notification",
"Full Trust"
]
idx = levels.index(current_level)
return levels[idx + 1] if idx < len(levels) - 1 else None
```
## 3.3.5 降级机制
信任不仅可以提升，也应该在必要时降级。如图所示，智能体的信任等级通过提升和降级机制动态调整，以保持安全性和有效性的平衡：
```mermaid
stateDiagram-v2
[*] --> Manual
Manual -->|min_ops=100
success_rate=99%| Approve: 提升
Approve -->|min_ops=1000
success_rate=99.5%| Once: 提升
Once -->|critical_error| Approve: 降级
Once -->|multiple_errors| Approve: 降级
Once -->|min_ops=10000
success_rate=99.9%| Ask: 提升
Ask -->|security_incident| Ask: 降级到此
Ask -->|min_ops=50000
success_rate=99.99%| Auto: 提升
Auto -->|error_rate_high| Ask: 降级
style Manual fill:#ffebee
style Approve fill:#ffe0b2
style Once fill:#fff9c4
style Ask fill:#f0f4c3
style Auto fill:#dcedc8
```
图 3-4：信任等级的提升和降级机制
```python
class TrustDemotionTrigger:
"""信任降级触发器"""
# 触发降级的条件
DEMOTION_TRIGGERS = {
"critical_error": 1, # 一次严重错误
"multiple_errors_in_short_time": 3, # 短时间内多次错误
"security_incident": 1, # 一次安全事件
"user_complaint": 5 # 5个用户投诉
}
async def check_and_demote(
self,
agent_id: str,
recent_history: List[AgentEvent]
) -> Optional[TrustLevel]:
"""
检查是否应该降级智能体的信任等级。
"""
current_level = await get_agent_trust_level(agent_id)
# 计数各类事件
event_counts = {
"critical_errors": sum(1 for e in recent_history if e.type == "critical_error"),
"errors_24h": sum(1 for e in recent_history if e.type == "error" and
e.timestamp > datetime.now() - timedelta(hours=24)),
"security_incidents": sum(1 for e in recent_history if e.type == "security_incident"),
"complaints": sum(1 for e in recent_history if e.type == "user_complaint")
}
# 检查触发条件
if event_counts["critical_errors"] >= self.DEMOTION_TRIGGERS["critical_error"]:
demoted_level = self._get_previous_level(current_level)
logger.warning(f"Agent {agent_id} demoted due to critical error",
extra={"from": current_level, "to": demoted_level})
return demoted_level
if event_counts["errors_24h"] >= self.DEMOTION_TRIGGERS["multiple_errors_in_short_time"]:
demoted_level = self._get_previous_level(current_level)
logger.warning(f"Agent {agent_id} demoted due to multiple errors",
extra={"event_counts": event_counts})
return demoted_level
if event_counts["security_incidents"] >= self.DEMOTION_TRIGGERS["security_incident"]:
demoted_level = "Ask-First" # 直接降回询问级别
logger.error(f"Agent {agent_id} demoted to Ask-First due to security incident")
return demoted_level
return None
def _get_previous_level(self, current_level: TrustLevel) -> TrustLevel:
"""获取前一个信任等级"""
# 至少降级一个等级,最多保留在Ask-First
levels = ["Manual Only", "Approve Always", "Approve Once", "Ask First", "Auto with Notification", "Full Trust"]
idx = max(0, levels.index(current_level) - 1)
return levels[idx]
```
## 3.3.6 可视化信任演进
我们可以通过代码来可视化每个智能体的信任等级演进历史：
```python
def visualize_trust_evolution(agent_history: AgentHistory) -> str:
"""生成Agent信任等级演进的可视化"""
lines = [f"Agent: {agent_history.agent_id}"]
lines.append(f"Current Trust Level: {agent_history.current_trust_level}\n")
# 时间线
lines.append("Timeline of Trust Changes:")
for event in agent_history.trust_changes:
lines.append(f" {event.timestamp.strftime('%Y-%m-%d')} "
f"{event.from_level} → {event.to_level}")
# 统计数据
lines.append(f"\nStats:")
lines.append(f" Total Operations: {agent_history.total_operations}")
lines.append(f" Success Rate: {agent_history.success_rate:.2%}")
lines.append(f" Critical Errors: {agent_history.critical_errors}")
lines.append(f" Days Running: {agent_history.days_running}")
# 提升建议
next_level = agent_history.promotion_readiness
if next_level:
lines.append(f"\nPromotion Eligible: {agent_history.current_trust_level} → {next_level}")
return "\n".join(lines)
```
## 3.3.7 总结
渐进信任原则的关键要点：
1. **信任是逐步建立的**，不要期望一步到位
2. **有明确的提升标准**，不是主观决定
3. **也要有降级机制**，快速响应问题
4. **持续监控**，收集足够的证据
5. **透明可视**，让所有相关者了解信任的演进过程
这个原则特别适用于长期运行的系统，如OpenClaw的自驱型Agent，它们需要在生产环境中逐步获得更多的权限和自主性。
# 3.4 故障假设原则
故障假设是构建可靠系统的基础原则。本节介绍这一原则的核心概念，以及对不同故障类型的处理策略、检查点机制、监控告警和完整的故障恢复流程。
## 3.4.1 原则的核心
**故障假设** 意味着：在设计系统时， **主动假设每一步都可能失败**，并提前设计如何处理这些失败。这不是悲观主义，而是现实主义的系统工程。
与其相反的方法是对比如下：
| 设计方法 | 处理方式 | 结果 |
| -------- | ---------- | ------------------------------ |
| **乐观设计** | 假设一切都会正常运行 | 当出现意外时，系统直接崩溃；用户蒙受损失，系统陷入不一致状态 |
| **故障假设** | 假设会出现意外 | 当出现意外时，系统有预案；优雅地降级，数据保持一致 |
## 3.4.2 为什么故障假设如此重要
故障假设原则的重要性可以从理论基础和实际数据统计两个角度理解。以下内容探讨了支撑这一原则的核心思想和在生产环境中的数据证据。
### 墨菲定律的启示
墨菲定律说：“任何可能出错的事情，最终都会出错，而且会在最糟糕的时刻出错。”
在智能体系统中，这尤其真实，因为我们处理的是概率系统。LLM不是确定的，网络不是可靠的，外部API也会偶尔宕机。
### 数据统计
在一个真实的生产系统中：
* **API调用失败率**：通常在0.1-1%
* **网络超时率**：通常在0.01-0.1%
* **数据库连接失败**：通常在0.001-0.01%
乍一看这些比率很低，但在高并发系统中，这意味着什么？
假设系统每天处理100万个任务，每个任务平均进行10个API调用：
```
总API调用数:100万 × 10 = 1000万次
在0.5%失败率下:1000万 × 0.005 = 50,000次失败
```
50,000次失败每天都会发生。如果系统没有为这些失败做准备，那就是50,000个用户的糟糕体验。
## 3.4.3 故障的类型和处理策略
如图所示，系统需要针对不同类型的故障采用不同的处理策略，从临时故障的重试到级联故障的断路器防护：
```mermaid
graph TB
A["临时故障
Transient"] -->|重试| B["重试策略
Retry"]
C["永久故障
Permanent"] -->|降级| D["降级策略
Fallback"]
E["部分故障
Partial"] -->|隔离| F["隔离模式
Bulkhead"]
G["级联故障
Cascading"] -->|防护| H["断路器
Circuit Breaker"]
style B fill:#c8e6c9
style D fill:#fff9c4
style F fill:#ffe0b2
style H fill:#ffccbc
```
图 3-5：故障类型和处理策略
### 类型1：临时故障
网络超时、API临时不可用等，通常过一段时间就会恢复。
**处理策略：重试**
```python
import asyncio
import logging
from typing import Any, Callable
logger = logging.getLogger(__name__)
class RetryStrategy:
"""重试策略"""
def __init__(
self,
max_retries: int = 3,
base_delay_seconds: float = 1.0,
exponential_base: float = 2.0,
jitter: bool = True
):
self.max_retries = max_retries
self.base_delay_seconds = base_delay_seconds
self.exponential_base = exponential_base
self.jitter = jitter
async def execute_with_retry(
self,
operation: Callable,
*args,
**kwargs
) -> Any:
"""
执行操作,失败时自动重试。
"""
last_error = None
for attempt in range(self.max_retries + 1):
try:
return await operation(*args, **kwargs)
except Exception as e:
last_error = e
# 判断是否应该重试
if not self._is_retryable(e):
raise
# 计算延迟
if attempt < self.max_retries:
delay = self._calculate_delay(attempt)
logger.info(
f"Retry attempt {attempt + 1}/{self.max_retries} "
f"after {delay:.1f}s",
extra={"error": str(e)}
)
await asyncio.sleep(delay)
# 所有重试都失败了
raise last_error
def _is_retryable(self, error: Exception) -> bool:
"""判断错误是否可重试"""
retryable_errors = (
asyncio.TimeoutError,
ConnectionError,
TimeoutError,
# 某些HTTP错误可以重试
)
return isinstance(error, retryable_errors)
def _calculate_delay(self, attempt: int) -> float:
"""计算重试延迟(指数退避)"""
delay = self.base_delay_seconds * (self.exponential_base ** attempt)
if self.jitter:
# 添加随机抖动,避免"羊群效应"
jitter = random.uniform(0, delay * 0.1)
delay += jitter
# 设置最大延迟
max_delay = 60 # 最多等60秒
return min(delay, max_delay)
# 重试策略使用示例
retry_strategy = RetryStrategy(max_retries=3, base_delay_seconds=0.5)
async def call_weather_api(city: str):
"""调用天气API"""
return await retry_strategy.execute_with_retry(
weather_api.get,
city=city
)
```
### 类型2：永久故障
API被删除、数据库不存在、权限不足等，重试也无法解决。
**处理策略：降级/回退**
```python
class FallbackStrategy:
"""降级/回退策略"""
def __init__(self, fallbacks: List[Callable]):
"""
初始化降级策略。
fallbacks是一个优先级列表,包含多个备选方案。
"""
self.fallbacks = fallbacks
async def execute_with_fallback(
self,
*args,
**kwargs
) -> Any:
"""
尝试执行,如果失败则使用备选方案。
"""
last_error = None
for i, fallback in enumerate(self.fallbacks):
try:
result = await fallback(*args, **kwargs)
logger.info(
f"Fallback {i} succeeded",
extra={"fallback": fallback.__name__}
)
return result
except Exception as e:
last_error = e
logger.warning(
f"Fallback {i} failed, trying next",
extra={"error": str(e)}
)
# 所有回退都失败了
raise last_error
# 降级策略使用示例:如果无法获取实时天气,使用缓存数据,再不行使用默认值
async def get_weather_with_fallback(city: str):
"""获取天气,支持降级"""
# 备选方案优先级:实时数据 > 缓存数据 > 默认值
strategy = FallbackStrategy([
lambda c: real_time_weather_api.get(c),
lambda c: cached_weather.get(c),
lambda c: default_weather_for(c)
])
return await strategy.execute_with_fallback(city)
```
### 类型3：部分故障
在一个分布式系统中，一部分组件失败，但其他部分仍在运行。
**处理策略：分离和隔离**
```python
class BulkheadPattern:
"""隔离模式:防止一个故障影响整个系统"""
def __init__(self, num_compartments: int = 10):
self.compartments = [asyncio.Semaphore(10) for _ in range(num_compartments)]
def get_compartment(self, request_id: str) -> asyncio.Semaphore:
"""根据请求ID,将其分配到某个隔离舱"""
compartment_idx = hash(request_id) % len(self.compartments)
return self.compartments[compartment_idx]
async def execute_isolated(
self,
request_id: str,
operation: Callable,
*args,
**kwargs
) -> Any:
"""
在隔离的舱中执行操作。
如果一个舱出现问题,不会影响其他舱。
"""
compartment = self.get_compartment(request_id)
async with compartment:
return await operation(*args, **kwargs)
# 隔离模式使用示例
bulkhead = BulkheadPattern(num_compartments=20)
async def process_request(request_id: str, request_data: dict):
"""处理请求,使用隔离模式"""
return await bulkhead.execute_isolated(
request_id,
process_request_logic,
request_data
)
```
### 类型4：级联故障
一个组件的故障导致其他组件也失败，最终整个系统崩溃。
**处理策略：断路器**
```python
from enum import Enum
class CircuitState(Enum):
CLOSED = "closed" # 正常状态
OPEN = "open" # 故障状态,拒绝请求
HALF_OPEN = "half_open" # 恢复测试状态
class CircuitBreaker:
"""断路器:防止级联故障"""
def __init__(
self,
failure_threshold: int = 5,
recovery_timeout_seconds: int = 60
):
self.failure_threshold = failure_threshold
self.recovery_timeout_seconds = recovery_timeout_seconds
self.state = CircuitState.CLOSED
self.failure_count = 0
self.last_failure_time = None
self.last_recovery_attempt = None
async def execute(
self,
operation: Callable,
*args,
**kwargs
) -> Any:
"""
通过断路器执行操作。
"""
# 检查是否应该转换到HALF_OPEN状态
self._update_state()
# 根据当前状态决定是否执行
if self.state == CircuitState.OPEN:
raise CircuitBreakerOpenError(
f"Circuit breaker is OPEN, rejecting request"
)
try:
result = await operation(*args, **kwargs)
# 成功,重置计数
self._record_success()
return result
except Exception as e:
# 失败,记录
self._record_failure()
raise
def _update_state(self):
"""更新断路器状态"""
if self.state == CircuitState.OPEN:
# 如果已经打开足够长的时间,尝试恢复
if (datetime.now() - self.last_failure_time).seconds > self.recovery_timeout_seconds:
self.state = CircuitState.HALF_OPEN
self.last_recovery_attempt = datetime.now()
logger.info("Circuit breaker transitioned to HALF_OPEN")
def _record_success(self):
"""记录成功"""
if self.state == CircuitState.HALF_OPEN:
# 从HALF_OPEN成功恢复到CLOSED
self.state = CircuitState.CLOSED
self.failure_count = 0
logger.info("Circuit breaker recovered to CLOSED")
elif self.state == CircuitState.CLOSED:
# 恢复失败计数
if self.failure_count > 0:
self.failure_count = max(0, self.failure_count - 1)
def _record_failure(self):
"""记录失败"""
self.failure_count += 1
self.last_failure_time = datetime.now()
if self.failure_count >= self.failure_threshold and self.state != CircuitState.OPEN:
self.state = CircuitState.OPEN
logger.warning(
f"Circuit breaker opened after {self.failure_count} failures"
)
class CircuitBreakerOpenError(Exception):
"""断路器打开时的异常"""
pass
# 断路器使用示例
breaker = CircuitBreaker(failure_threshold=5, recovery_timeout_seconds=30)
async def call_external_api():
return await breaker.execute(external_api.request)
```
## 3.4.4 检查点和事务
对于长流程的操作，需要设置检查点，以便从中间进行恢复。
```python
class CheckpointedExecution:
"""支持检查点的执行"""
def __init__(self, checkpoint_storage):
self.checkpoint_storage = checkpoint_storage
async def execute_with_checkpoints(
self,
task_id: str,
steps: List[Step]
) -> Result:
"""
执行一系列步骤,每个步骤前后都保存检查点。
"""
# 检查是否有之前的检查点,以便恢复
checkpoint = await self.checkpoint_storage.load(task_id)
start_idx = checkpoint.last_completed_step + 1 if checkpoint else 0
results = []
for i in range(start_idx, len(steps)):
step = steps[i]
try:
# 执行步骤
result = await execute_step(step)
results.append(result)
# 保存检查点
await self.checkpoint_storage.save(
task_id,
CheckPoint(
last_completed_step=i,
results_so_far=results
)
)
except Exception as e:
# 步骤失败,保存失败检查点
await self.checkpoint_storage.save_error(
task_id,
ErrorCheckPoint(
failed_step=i,
error=str(e),
partial_results=results
)
)
raise
# 完成后,清理检查点
await self.checkpoint_storage.delete(task_id)
return Result(status="success", outputs=results)
async def resume_task(self, task_id: str, steps: List[Step]) -> Result:
"""
恢复一个之前失败的任务。
"""
checkpoint = await self.checkpoint_storage.load(task_id)
if checkpoint is None:
raise ValueError(f"No checkpoint found for task {task_id}")
logger.info(
f"Resuming task {task_id} from step {checkpoint.last_completed_step + 1}",
extra={"step_index": checkpoint.last_completed_step + 1}
)
return await self.execute_with_checkpoints(
task_id,
steps
)
```
## 3.4.5 监控和告警
故障假设的最后一部分是：**快速检测故障**。
```python
class HealthMonitor:
"""系统健康监控"""
async def monitor(self):
"""持续监控系统健康"""
while True:
metrics = await self._collect_metrics()
# 检查关键指标
alerts = []
# 1. 错误率过高
if metrics["error_rate"] > 0.01: # >1%
alerts.append(Alert(
severity="critical",
message=f"Error rate {metrics['error_rate']:.2%} exceeds threshold"
))
# 2. 响应时间过长
if metrics["avg_response_time_ms"] > 1000:
alerts.append(Alert(
severity="warning",
message=f"Avg response time {metrics['avg_response_time_ms']:.0f}ms"
))
# 3. 任务积压
if metrics["pending_tasks"] > 10000:
alerts.append(Alert(
severity="warning",
message=f"{metrics['pending_tasks']} tasks pending"
))
# 4. 外部依赖不可用
for dependency, available in metrics["dependencies"].items():
if not available:
alerts.append(Alert(
severity="critical",
message=f"Dependency {dependency} is unavailable"
))
# 发送告警
for alert in alerts:
await self._send_alert(alert)
await asyncio.sleep(60) # 每分钟检查一次
```
## 3.4.6 故障恢复的总结
故障恢复包括以下几个关键阶段。如图所示，完整的故障处理流程包括从故障检测到学习改进的全过程：
```mermaid
flowchart LR
A["故障发生
Failure"] -->|监控和告警| B["故障检测
Detection"]
B -->|断路器
隔离模式| C["故障隔离
Isolation"]
C -->|重试
降级
检查点| D["故障恢复
Recovery"]
D -->|审计日志
分析报告| E["学习改进
Learning"]
E --> F["系统加强
Reinforcement"]
style A fill:#ffebee
style B fill:#ffccbc
style C fill:#ffe0b2
style D fill:#fff9c4
style E fill:#dcedc8
style F fill:#c8e6c9
```
图 3-6：完整的故障恢复流程
## 3.4.7 总结
故障假设原则的关键要点：
1. **接受故障会发生**，而不是希望它们不发生
2. **为每种故障类型设计处理机制**：重试、降级、隔离、断路器
3. **设置检查点和事务**，允许从中间恢复
4. **持续监控和告警**，快速检测故障
5. **从故障中学习**，不断改进系统韧性
这个原则将一个脆弱的系统变成了一个真正“可靠”(reliable)的系统。
# 本章小结
本章阐述了Harness系统的四大设计原则，以下是核心要点的系统回顾。
## 四大设计原则的完整体系
本章介绍了构建生产级Harness系统的四大设计原则。这些原则相互补充、形成了一个完整的设计哲学体系：
```mermaid
graph TD
A["约束优先"] -->|定义系统的边界| B["可验证性"]
B -->|确保系统的可观测性| C["渐进信任"]
C -->|逐步提升系统的权限| D["故障假设"]
D -->|为不可避免的故障做准备| E["生产级 Harness"]
style A fill:#ffebee
style B fill:#fff9c4
style C fill:#e8f5e9
style D fill:#e3f2fd
style E fill:#f3e5f5
```
## 四大原则的各自职责
### 1. 约束优先
**核心思想**：首先定义Agent不能做什么，然后在这个框架内赋予能力。
**关键要素**：
* 权限维度：可以访问哪些资源
* 操作维度：禁止哪些操作
* 时间维度：什么时候允许操作
* 数据维度：什么样的数据可以处理
**实现方法**：
* 白名单（最安全）
* 黑名单（最灵活）
* 规则引擎（最平衡）
在实践中，Claude Code 通过 protected files 和 dangerous patterns 实现约束优先，OpenClaw 则通过 SOUL.md 约束文档来定义边界。
### 2. 可验证性
**核心思想**：系统的每一个操作都应该是可观测的、可追踪的、可重放的。
**三个层次**：
1. **操作日志**：记录发生了什么
2. **执行追踪**：记录操作之间的因果关系
3. **可重放性**：给定相同输入，能够重现执行
**关键实现**：
* 结构化日志，便于搜索和分析
* 分布式追踪，显示完整的执行路径
* 执行重放，验证系统一致性
在实践中，Claude Code 基于 OpenTelemetry 实现分布式追踪，OpenClaw 则通过 Lobster 确定性日志实现执行重放。
### 3. 渐进信任
**核心思想**：不要期望一下子完全信任Agent，而是通过观察和学习逐步提升权限。
**信任梯度** （从低到高）：
1. Manual Only：完全人工操作
2. Approve Always：每步审批
3. Approve Once：任务开始时批准一次
4. Ask First：关键操作事前询问
5. Auto with Notification：自动执行并通知
6. Full Trust：充分信任（罕见）
**提升和降级**：
* 提升需要明确的证据和标准
* 降级可以快速响应问题
* 持续的监控和评估
### 4. 故障假设
**核心思想**：主动假设每一步都可能失败，并提前设计失败处理。
**故障类型和处理**：
* 临时故障 → 重试(Retry)
* 永久故障 → 降级/回退(Fallback)
* 部分故障 → 隔离(Bulkhead)
* 级联故障 → 断路器(Circuit Breaker)
**关键机制**：
* 指数退避重试，避免羊群效应
* 检查点和事务，支持中间恢复
* 持续监控和告警，快速检测故障
## 四大原则的相互关系
四大原则并非孤立，而是相互支撑的完整体系，如下所示：
```mermaid
graph TB
A["约束优先"]
B["定义边界"]
C["约束"]
D["可验证性"]
E["审计"]
F["监控行为"]
G["渐进信任"]
H["权限提升"]
I["有充分证据"]
J["故障假设"]
K["设计失败处理"]
L["快速恢复"]
M["证据来源"]
A --> B
B --> C
C --> D
D --> E
E --> F
C --> G
G --> H
H -.-> I
J --> M
M --> L
D --> J
K --> L
style A fill:#ffebee
style C fill:#fff3e0
style D fill:#fff9c4
style G fill:#f0f4c3
style E fill:#e8f5e9
style H fill:#e0f2f1
```
## 实践中的集成应用
这四大原则在实际系统设计中是高度集成的：
**设计一个转账系统**
**约束优先**：定义智能体的权限
```python
permissions = {
"transfer_money": {
"max_amount_per_operation": 1000,
"max_amount_per_day": 10000,
"requires_approval": "Approve Always"
}
}
```
**可验证性**：记录每个转账操作
```yaml
Trace ID: trace-2024-04-01-001
Step 1: Check balance
Step 2: Validate transfer
Step 3: Execute transfer
Step 4: Send confirmation
→ 完整的操作日志供后续审计
```
**渐进信任**：根据Agent表现逐步提升权限
```
初期:Approve Always(每次转账都需要人工批准)
一周后:Ask First(小额转账自动,大额需要确认)
一月后:Auto with Notification(自动执行并通知用户)
```
**故障假设**：为可能的失败设计处理
```
失败场景1:网络超时 → 重试3次
失败场景2:余额不足 → 报告给用户
失败场景3:外部API宕机 → 使用缓存的汇率
失败场景4:多个转账失败 → 启动断路器,停止新转账
```
## 与前两章的关系
本章与前两章的关系和递进逻辑如下：
```mermaid
graph TD
A["第1章:概论
为什么需要Harness？"] --> B["第2章:架构全景
Harness的系统设计"]
B --> C["第3章:设计原则 ← 你在这里
如何正确地设计Harness"]
style A fill:#e8f5e9
style B fill:#fff9c4
style C fill:#ffebee,stroke:#c62828,stroke-width:2px
```
## MiniHarness中应用这些原则
在MiniHarness项目中，这些原则的应用包括：
### MiniHarness中的约束优先
在工具注册表中实现约束优先原则：
```python
# 第2章已经定义了ToolRegistry
# 第3章应该添加权限检查
from mini_harness.security.permissions import PermissionDecisionEngine
class ToolRegistry:
async def call_tool(self, tool_name, params):
# 首先检查权限
if not await permission_manager.check_permission(tool_name):
raise PermissionError(f"Tool {tool_name} not allowed")
# 然后执行
return await self._execute_tool(tool_name, params)
```
### MiniHarness中的可验证性
通过结构化日志实现可验证性：
```python
# 添加审计日志
from mini_harness.reliability.logging import StructuredLogger
class ToolExecutor:
async def execute(self, tool_name, params):
logger.info("Tool execution started", extra={
"tool_name": tool_name,
"params": params
})
result = await self._execute_tool(tool_name, params)
logger.info("Tool execution completed", extra={
"tool_name": tool_name,
"status": result.status,
"duration_ms": result.duration
})
return result
```
### MiniHarness中的渐进信任
实现权限等级管理以支持渐进信任：
```python
# 添加权限等级管理
from mini_harness.security.permissions import PermissionLevel
class AgentTrustManager:
async def update_trust_level(self, agent_id):
# 评估是否应该提升信任等级
# 根据agent历史记录调整权限等级
history = await self.get_agent_history(agent_id)
# 简化的信任提升逻辑 - 实际实现可更复杂
if history.success_rate > 0.95:
new_level = PermissionLevel.AUTO
else:
new_level = PermissionLevel.ASK
current_level = await self.get_agent_level(agent_id)
if new_level and new_level.value > current_level.value:
await self.promote_agent(agent_id, new_level)
```
### MiniHarness中的故障假设
实现容错机制以处理故障场景：
```python
# 添加重试和降级机制
from mini_harness.reliability.resilience import RetryConfig, CircuitBreaker
class ResilientToolExecutor:
async def execute(self, tool_name, params):
# 重试配置
retry_config = RetryConfig(max_attempts=3, initial_delay=1.0)
try:
# 使用重试机制执行工具调用
attempt = 1
while attempt <= retry_config.max_attempts:
try:
return await self.tool_registry.call_tool(tool_name, params)
except Exception as e:
if not retry_config.should_retry(e):
raise
if attempt >= retry_config.max_attempts:
raise
delay = retry_config.calculate_delay(attempt)
await asyncio.sleep(delay)
attempt += 1
except Exception as e:
# 降级到缓存结果或默认值
cached = self.cached_results.get(tool_name)
if cached:
return cached
return self.default_value_for(tool_name)
```
## 评估清单
在实现一个Harness系统时，检查以下清单来确保所有四大原则都被正确应用：
### 约束优先检查清单
* [ ] 明确定义了智能体可以访问的资源
* [ ] 列出了禁止的操作
* [ ] 实现了权限检查机制
* [ ] 定义了时间和数据的约束
### 可验证性检查清单
* [ ] 所有操作都被记录在审计日志中
* [ ] 支持执行追踪（可以看到完整的执行路径）
* [ ] 关键操作可以被重放
* [ ] 提供了人类可读的摘要和机器可读的详细日志
### 渐进信任检查清单
* [ ] 定义了信任等级和升级标准
* [ ] 实现了权限提升评估机制
* [ ] 实现了权限降级触发器
* [ ] 可以可视化信任的演进过程
### 故障假设检查清单
* [ ] 识别了可能的故障类型
* [ ] 为每种故障设计了处理机制
* [ ] 实现了重试、降级、隔离、断路器等机制
* [ ] 有监控和告警系统，快速检测故障
## 常见的误区
### 误区1：过度约束
**问题**：为了安全起见，给Agent几乎没有权限。 **结果**：Agent无法完成任何有意义的工作。 **解决**：使用渐进信任，逐步扩展权限。
### 误区2：忽视可验证性
**问题**：为了性能，不记录详细日志。 **结果**：出现问题时无法诊断。 **解决**：记录足够的信息用于调试，但使用异步日志避免性能影响。
### 误区3：假设不会出现故障
**问题**：认为系统足够可靠，不需要额外的故障处理。 **结果**：小故障导致大事件。 **解决**：主动设计故障处理机制。
### 误区4：权限一成不变
**问题**：定义权限后，再也不调整。 **结果**：权限要么太宽松（安全问题），要么太严格（效率问题）。 **解决**：根据运行数据定期评估和调整。
## 与业界最佳实践的对齐
这四大原则与业界的系统工程最佳实践高度对齐：
* **约束优先** ↔ “白名单优于黑名单”（安全工程）
* **可验证性** ↔ “日志和追踪”（SRE最佳实践）
* **渐进信任** ↔ “逐步展开”（DevOps实践）
* **故障假设** ↔ “混沌工程”（系统可靠性）
## 总结和后续步骤
本章确立了Harness系统的四大设计原则。这些原则：
1. **相互补充**：组合在一起，形成了一个完整的安全、可靠、可管理的系统
2. **可操作化**：不是抽象的哲学，而是可以具体实现的工程实践
3. **可度量**：每个原则都有具体的指标可以评估
从第4章开始，我们将进入各个子系统的深入实现，而这四大原则将在每个子系统中不断体现。
## 关键概念回顾表
| 原则 | 核心思想 | 关键实现 | 检验标准 |
| ---- | -------- | -------- | ------------ |
| 约束优先 | 限制比赋能更重要 | 权限检查、隔离 | 能清楚回答智能体能做什么 |
| 可验证性 | 每步都可审计 | 日志、追踪、重放 | 能重现任何操作的细节 |
| 渐进信任 | 信任逐步建立 | 权限评估、升降级 | 有明确的升级标准 |
| 故障假设 | 故障总会发生 | 重试、降级、隔离 | 单个故障不会导致系统崩溃 |
下一章将深入运行时引擎的实现，这些设计原则将在实践中得到充分体现。
# 第四章：运行时引擎
## 章引言
运行时引擎是整个 Harness 系统的心脏。如果说架构与原理是智能体系统的“骨架”，那么运行时引擎就是“血液循环系统”——它驱动智能体的每一个思考、决策、行动的周期，协调组件间的协作，管理系统资源的分配，处理边界情况与故障恢复。
在传统的编译原理中，运行时执行程序的代码并管理其生命周期；在 AI 智能体系统中，运行时执行智能体的一轮轮推理与行动循环，并管理整个会话的生命周期。
本章深入 Harness 运行时引擎的设计与实现，涵盖以下核心专题：
1. **智能体循环的工程实现**——从“思考-行动-观察”的概念模型到代码级的流程控制
2. **消息与状态管理**——类型系统设计与不可变状态模式
3. **流式处理与事件驱动**——为什么工具执行必须与流式响应同步，而非后处理
4. **错误处理与恢复**——工具故障、API 超时、输出截断的应对策略
5. **漂移检测与纠正**——长时任务如何保持目标对齐
6. **令牌预算管理**——有限上下文下的动态调度与压缩
7. **MiniHarness 实现**——用 Python 从零实现一个完整的智能体运行时
## 为什么需要深入理解运行时
运行时引擎决定了系统的以下关键属性：
* **可靠性**——错误恢复策略决定任务成功率
* **吞吐量**——流式处理与并发执行设计决定响应延迟
* **可观测性**——事件发射与日志设计决定问题诊断能力
* **资源利用**——令牌预算与内存管理决定成本与规模
* **安全性**——权限检查、工具验证、输出治理都在运行时执行
两个参考系统展现了不同的设计哲学：
**Claude Code 的异步生成器**：基于 QueryEngine.submitMessage() 的异步生成器循环，StreamingToolExecutor 并发工具执行，上下文缓存与动态边界，追求低延迟与高吞吐，适合任务型的交互式场景。
**OpenClaw 的线性流水线**：顺序执行 intake → context assembly → inference → tool execution → streaming → persistence，单线程会话模型，强调确定性与可追踪性，适合长运行的自驱型智能体。
本章将对两种模式进行对比分析，并在 MiniHarness 实现中融合两者的优点。
## 本章结构
* 4.1：智能体循环的工程实现
* 4.2：消息类型系统与状态管理
* 4.3：流式处理与事件驱动架构
* 4.4：错误处理与故障恢复
* 4.5：长时任务的漂移检测与纠正
* 4.6：令牌预算与上下文动态管理
* 4.7：实战——MiniHarness 运行时实现
* 4.8：实时控制平面
# 4.1 智能体循环的工程实现
智能体循环是运行时的核心执行模式，定义了Agent如何在思考、行动和观察三个阶段间反复迭代。本节对比Claude Code和OpenClaw两种实现模式，分析循环的终止条件和消息流演化。
## 4.1.1 概念模型：思考-行动-观察循环
智能体循环（Agent Loop）是智能体系统的核心执行模式。经典的“思考-行动-观察”(Think-Act-Observe)循环定义如下：
1. **思考(Think)**：Agent 基于当前上下文（历史、状态、工具信息）进行推理，生成意图和下一步行动计划
2. **行动(Act)**：Agent 执行工具调用或发起 API 请求，改变外部世界状态
3. **观察(Observe)**：Agent 获得工具执行结果，更新内部认知模型，为下一轮思考做准备
如果工具调用失败或返回意外结果，观察阶段会将其作为“负面证据”反馈给思考模块，触发错误恢复或备选方案。
**思考-行动-观察循环流程：**
```mermaid
graph LR
A["LLM 推理"] --> B["工具执行"]
B --> C["结果分析"]
C --> D{"是否
完成?"}
D -->|否| A
D -->|是| E["返回最终结果"]
style A fill:#e1f5ff
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8f5e9
style E fill:#c8e6c9
```
图 4-1：思考-行动-观察循环
**为什么是循环而不是链**
传统的链式智能体(Chain-of-Thought)将思考和行动分开，形如：提示→思考→规划→工具调用→输出。这种设计的缺点是：
* **缺乏适应性**：一旦执行遇到问题（工具调用失败、输出超限），难以动态调整策略
* **低效率**：规划阶段必须预测所有可能的工具调用，容易过度规划或不足规划
* **不可恢复**：一旦规划失败，需要重新启动整个流程
**循环设计** 允许智能体逐步细化目标，在每个循环迭代中获得反馈，动态调整策略。这更符合人类解决问题的过程。
## 4.1.2 工程实现模式对比
### Claude Code 的异步生成器模式
Claude Code采用异步生成器模式实现智能体循环，具体如下：
```mermaid
flowchart TD
subgraph Generator["QueryEngine.submitMessage() Generator"]
A["submitMessage(userInput)"] --> B["yield agent_start"]
B --> C
subgraph C["Async Turn Loop (while hasWorkToDo)"]
D["yield turn_start"] --> E["Build & Validate Context
(考虑缓存边界)"]
E --> F["Stream Model Response
(yield text_delta / tool_use)"]
F --> G["StreamingToolExecutor.execute()
(并发执行工具)"]
G --> H["yield message_end"]
H -->|"继续下一轮"| D
end
C --> I["yield agent_end, result"]
end
```
**特点**：
* 异步生成器模式，客户端可以逐个处理事件
* 支持流式响应实时推送(text\_delta)
* StreamingToolExecutor 支持工具的并发执行
* 上下文构建时考虑缓存边界(SYSTEM\_PROMPT\_DYNAMIC\_BOUNDARY)
* AppState 管理会话状态（150+ 字段）
**Claude Code 的核心代码骨架** （伪代码）：
```python
class QueryEngine:
async def submitMessage(self, user_input: str):
"""异步生成器循环,每次 yield 一个事件"""
yield AgentStartEvent()
# 初始化会话状态
app_state = self.init_app_state(user_input)
while app_state.has_work_to_do():
yield TurnStartEvent()
# 构建完整的消息和上下文
# 考虑缓存边界,分离系统提示词和动态上下文
system_prompt = self.get_system_prompt()
messages = await self.build_messages(app_state)
# 检查令牌预算
if self.estimate_tokens(system_prompt + messages) > self.token_budget:
messages = self.auto_compact_history(messages)
# 流式调用模型
stream = await self.model_client.create_message_stream(
messages=messages,
system=system_prompt,
tools=self.get_available_tools()
)
# 逐个处理流中的事件
async for event in stream:
if event.type == "content_block_start":
# 新的内容块开始(文本或工具使用)
yield event
elif event.type == "content_block_delta":
if event.delta.type == "text_delta":
yield TextDeltaEvent(event.delta.text)
elif event.delta.type == "input_json_delta":
yield ToolInputDeltaEvent(event.delta.text)
elif event.type == "message_delta":
# 消息完成
message = event.message
# 异步执行工具(StreamingToolExecutor)
tool_results = await self.execute_tools(
message.content,
app_state
)
# 更新应用状态
app_state.add_message(message)
app_state.add_tool_results(tool_results)
yield MessageEndEvent(message)
# 检查是否需要继续
if not tool_results:
app_state.mark_done()
# 否则继续下一轮(while 循环)
# 返回最终结果
yield AgentEndEvent(
result=app_state.final_response,
message_count=len(app_state.messages)
)
```
### OpenClaw 的线性流水线模式
OpenClaw采用线性流水线模式，在单个事件循环中顺序执行，具体如下：
```mermaid
flowchart TD
subgraph SessionLoop["Session Loop(单线程)"]
A["Intake
(user msg)"] --> B["Context Assembly"]
B --> C["Inference
(Claude)"]
C --> D["Response Streaming
+ Tool Detection"]
D --> E["Tool Execution Loop
(顺序/不阻塞UI)"]
E --> F["Persistence
(会话存储)"]
F -->|"继续下一轮(如需要)"| A
end
```
**特点**：
* 每轮循环是独立的阶段：input → assembly → inference → execution → persist
* 单线程执行，一次一个会话，不支持会话间并发
* 工具执行与流式响应紧耦合
* 错误作为“观察”(ToolResultBlock)反馈回消息流
**OpenClaw 的核心代码骨架** （伪代码）：
```python
class SessionRuntime:
def run_session(self, session_id: str):
"""单个会话的运行时主循环"""
while True:
# 1. Intake:获取用户输入或等待事件
user_message = self.intake_queue.get(timeout=30)
if user_message is None:
break # 会话结束
# 2. Context Assembly:组装上下文
context = self.context_engine.assemble(
session_id=session_id,
user_input=user_message,
system_prompt=self.system_prompt,
tools_schema=self.get_tools_schema(),
memory=self.memory_store.load(session_id)
)
# Initialize messages from context
messages = context.messages.copy()
# 3. Inference:调用模型
response = self.model_client.create_message(
messages=messages,
system=context.system_prompt,
tools=context.tools,
max_tokens=context.token_budget
)
# 4. Tool Execution Loop:处理工具调用
tool_results = []
for tool_use in response.content:
if isinstance(tool_use, ToolUseBlock):
result = self.execute_tool(
tool_use.name,
tool_use.input
)
tool_results.append(ToolResultBlock(
tool_use_id=tool_use.id,
content=result
))
# 如果有工具调用,需要继续推理
if tool_results:
# 构造新一轮的输入:原response + tool results
messages.extend(response.content)
messages.extend(tool_results)
# 继续推理
continue
# 5. Persistence:持久化
self.message_store.save(session_id, response)
self.memory_store.maybe_consolidate(session_id)
# 返回最终响应
return response
```
## 4.1.3 循环的终止条件
两个系统都需要明确定义何时停止循环，避免无限循环：
### 终止条件的类型
1. **工具调用耗尽**：Agent 推理出最后一条消息，不包含工具调用，直接回复用户
2. **最大轮数限制**：防止无限循环的安全机制，通常设为 10-30 轮
3. **令牌预算耗尽**：当前轮推理会导致上下文溢出，无法继续
4. **显式停止信号**：用户取消、超时、或智能体发出停止标记
5. **目标达成**：可选的高层目标追踪（自驱型智能体）
### 实现示例
以下是循环终止检查器的实现示例：
```python
class LoopTerminationChecker:
def __init__(self, max_turns: int = 20, token_limit: int = 100000):
self.max_turns = max_turns
self.token_limit = token_limit
def should_continue(self, state: AgentState) -> bool:
"""判断是否应该继续循环"""
# 检查1:轮数上限
if state.turn_count >= self.max_turns:
state.termination_reason = "max_turns_reached"
return False
# 检查2:是否有工具调用
last_message = state.messages[-1]
if not self._has_tool_calls(last_message):
state.termination_reason = "no_tool_calls"
return False
# 检查3:令牌预算
next_turn_tokens = self._estimate_tokens_for_next_turn(state)
if next_turn_tokens > self.token_limit:
state.termination_reason = "token_limit_exceeded"
return False
# 检查4:显式停止信号
if state.stop_signal_received:
state.termination_reason = "user_stop"
return False
return True
def _has_tool_calls(self, message: Message) -> bool:
"""检查消息中是否有工具调用块"""
for block in message.content:
if isinstance(block, ToolUseBlock):
return True
return False
def _estimate_tokens_for_next_turn(self, state: AgentState) -> int:
"""估计下一轮推理的令牌使用"""
# 简化版本,实际需要调用计数器
history_tokens = len(state.messages) * 50 # 粗略估计
new_input_tokens = 100 # 工具结果的平均大小
return history_tokens + new_input_tokens
```
## 4.1.4 消息流的演化过程
一个完整的 智能体循环中，消息流如何演化：
```bash
轮次 1:
Input: [UserMessage("Find files modified in last 7 days")]
Output: [AssistantMessage([
TextBlock("I'll find recent files for you."),
ToolUseBlock(name="bash", input="find /data -mtime -7")
])]
轮次 2(工具执行):
Input: [
UserMessage("Find files modified in last 7 days"),
AssistantMessage([...]),
ToolResultBlock(tool_use_id=xxx, content="file1.txt\nfile2.log\n...")
]
Output: [AssistantMessage([
TextBlock("Found 3 recent files: file1.txt, file2.log, file3.csv")
])] # 不再有工具调用,循环终止
最终消息历史:
[UserMessage, AssistantMessage(Tool 1), ToolResultBlock, AssistantMessage(Final)]
```
这种结构保证了：
* 完整的推理链条可追踪
* 每次工具调用都有对应的结果
* 智能体的决策过程对用户透明
## 4.1.5 Codex 智能体循环协议规范
Codex Harness采用了JSON-RPC作为循环协议的基础，通过严格的通信原语确保循环的可靠性和可观测性。本节介绍Codex循环的协议层设计。
### 三层通信原语
Codex Agent Loop定义了三个核心的JSON-RPC通信原语，从底层到顶层分别为：
1. **Item** （项）：最小的原子通信单元，代表单次输入/输出操作。每个Item都有明确的生命周期：
* `item/started`：Item开始处理
* 可选的 `item/{type}/delta`：内容流式增量到达（适用于文本、工具执行结果等）
* `item/completed`：Item完成并返回最终payload
Item的类型包括用户消息、助手消息、工具执行、审批请求、差异(diff)等，类型化设计使客户端能够进行强类型校验。
2. **Turn** （轮）：由用户输入发起的单位工作。一个Turn包含一个有序的Item序列，表示从用户请求到最终输出的整个执行过程：
* `turn/start`：接收用户输入（例如”运行测试并总结失败原因”）
* 中间步骤：思考、工具调用、获取结果等（各自作为Item）
* `turn/completed`：最终助手消息返回，Turn结束
3. **Thread** （线程）：持久化的会话容器，包含多个Turn。Threads支持创建、恢复、分叉和归档，历史记录持久化确保客户端可以重连并恢复一致的状态。
### 前缀一致性与缓存优化
Codex的JSON-RPC协议强制执行 **前缀一致性** 原则：每一轮推理的输入都是上一轮输出的精确前缀。这一设计直接启用了模型推理的 **提示词缓存** (Prompt Caching)，使多轮对话的成本从二次方复杂度降至线性复杂度。
具体地，如果第一轮推理的完整消息列表为 `[msg1, msg2, ..., msgN]`，第二轮新增工具结果后的列表必须为 `[msg1, msg2, ..., msgN, toolResult, assistantMsg]`，旧消息部分保持不变。这对循环的构建有两个影响：
* **工具枚举顺序的重要性**：MCP工具在初始化时必须以 **确定的顺序** 枚举，否则工具列表顺序变化会破坏前缀，导致缓存未命中(Cache Miss)。Codex发现过一个bug：MCP工具枚举的顺序不确定，在长会话中每一轮都造成缓存未命中，性能严重下降。
* **配置变更的处理**：若在对话中途需要改变权限设置、沙箱配置或工作目录，Codex不会修改历史消息，而是追加一个新的`role=developer`消息声明配置变更，保持前缀的完整性。
### 双向通信模式
App Server的JSON-RPC协议是 **完全双向的**，不同于传统的单向请求-响应模式：
* **客户端请求**：初始化握手(initialize)、线程和轮次创建(thread/start, turn/start)、输入提交
* **服务端通知**：进度更新（thread/started, turn/started, item/started等）、Item的增量内容（delta事件）、Item完成(item/completed)
* **服务端请求**：当需要用户审批（例如”是否允许执行 pnpm test”）时，服务端主动向客户端发起请求，转为 **暂停** 状态，直到客户端响应批准或拒绝
这种双向特性使循环成为一个 **响应式的流程**：客户端UI可以在Item开始时立即开始渲染，流式地接收delta事件进行增量更新，在Item完成时进行最终定稿。服务端也可以在关键决策点（如权限检查）暂停转移控制权给用户。
## 4.1.6 本节小结
智能体循环的工程实现有两种主要模式：
* **Claude Code 的异步生成器** 追求低延迟与高并发，通过事件驱动的方式支持流式响应，适合交互式的任务场景
* **OpenClaw 的线性流水线** 强调确定性与可追踪性，通过单线程阶段化执行保证顺序，适合需要完全控制的自驱型场景
在生产级Codex系统中，通过 **JSON-RPC协议的三层原语** (Item/Turn/Thread)、 **前缀一致性缓存优化** 和 **双向通信模式**，实现了高效可靠的循环编排。这些设计模式的核心是”思考-行动-观察”循环，但将其具体化为可观测、可缓存、可控制的protocol-level操作。
理解这两种实现模式和协议规范，是构建生产级Harness运行时的基础。
# 4.2 消息类型系统与状态管理
清晰的消息类型系统和适当的状态管理方式是运行时的基础。本节介绍消息流转的完整类型体系，对比两种状态管理模式，并讨论消息历史的窗口管理策略。
## 4.2.1 消息类型的完整体系
在 智能体循环中流转的不仅是文本，还包括多种类型的内容块。清晰的消息类型系统是实现可靠智能体系统的基础。
**核心消息类型：** 系统中使用的核心消息类型定义如下：
```mermaid
graph LR
U["用户消息"] --> S["系统处理"]
S --> A["推理响应"]
A --> T{"是否有
工具调用?"}
T -->|是| TE["工具执行"]
T -->|否| END["对话结束"]
TE --> TR["执行结果"]
TR --> A
style U fill:#bbdefb
style S fill:#c8e6c9
style A fill:#ffe0b2
style TE fill:#f8bbd0
style TR fill:#e1bee7
style END fill:#d1c4e9
```
图 4-2：消息流转流程
```python
# 基础消息类型枚举
class MessageRole(Enum):
USER = "user" # 用户输入
ASSISTANT = "assistant" # 智能体响应
class ContentBlockType(Enum):
TEXT = "text" # 纯文本
TOOL_USE = "tool_use" # 工具调用请求
TOOL_RESULT = "tool_result" # 工具执行结果
THINKING = "thinking" # 推理过程(optional)
IMAGE = "image" # 图像内容
```
**消息对象的定义：** 消息对象的数据结构定义如下：
```python
from typing import List, Dict, Any, Optional
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
import json
@dataclass
class TextBlock:
"""纯文本块"""
type: str = "text"
text: str = ""
def to_dict(self) -> Dict[str, Any]:
return {"type": self.type, "text": self.text}
@dataclass
class ToolUseBlock:
"""工具调用块:Agent 发起工具调用请求"""
type: str = "tool_use"
id: str = "" # 工具使用的唯一ID,用于匹配结果
name: str = "" # 工具名称
input: Dict[str, Any] = field(default_factory=dict) # 工具参数,已解析为字典
def __post_init__(self):
if self.input is None:
self.input = {}
if not self.id:
# 自动生成UUID
import uuid
self.id = f"tooluse_{uuid.uuid4().hex[:12]}"
def to_dict(self) -> Dict[str, Any]:
return {
"type": self.type,
"id": self.id,
"name": self.name,
"input": self.input
}
@dataclass
class ToolResultBlock:
"""工具结果块:工具执行完成后的结果"""
type: str = "tool_result"
tool_use_id: str = "" # 关联的 ToolUseBlock.id
content: str = "" # 工具执行结果(文本)
is_error: bool = False # 是否为错误结果
error_type: Optional[str] = None # 错误类型(如果是错误)
def to_dict(self) -> Dict[str, Any]:
return {
"type": self.type,
"tool_use_id": self.tool_use_id,
"content": self.content,
"is_error": self.is_error,
"error_type": self.error_type
}
@dataclass
class ThinkingBlock:
"""推理块:Agent 的内部思考过程(使用 extended thinking 时)"""
type: str = "thinking"
thinking: str = "" # 思考内容
def to_dict(self) -> Dict[str, Any]:
return {"type": self.type, "thinking": self.thinking}
@dataclass
class Message:
"""完整的消息对象"""
role: str # "user" 或 "assistant"
content: List[Any] # 可以包含 TextBlock, ToolUseBlock, ToolResultBlock 等
timestamp: datetime = None
message_id: str = "" # 唯一标识符
def __post_init__(self):
if self.timestamp is None:
self.timestamp = datetime.utcnow()
if not self.message_id:
import uuid
self.message_id = f"msg_{uuid.uuid4().hex[:12]}"
@classmethod
def user(cls, text: str) -> "Message":
"""工厂方法:创建用户消息"""
return cls(
role="user",
content=[TextBlock(text=text)]
)
@classmethod
def assistant(cls, content: List[Any]) -> "Message":
"""工厂方法:创建助手消息"""
return cls(
role="assistant",
content=content
)
def has_tool_calls(self) -> bool:
"""检查是否包含工具调用"""
return any(isinstance(block, ToolUseBlock) for block in self.content)
def get_tool_calls(self) -> List[ToolUseBlock]:
"""提取所有工具调用块"""
return [block for block in self.content if isinstance(block, ToolUseBlock)]
def get_text(self) -> str:
"""提取所有文本块,拼接为单个字符串"""
texts = [block.text for block in self.content if isinstance(block, TextBlock)]
return "".join(texts)
def to_dict(self) -> Dict[str, Any]:
"""序列化为字典"""
return {
"role": self.role,
"content": [block.to_dict() for block in self.content],
"timestamp": self.timestamp.isoformat(),
"message_id": self.message_id
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Message":
"""从字典反序列化"""
content = []
for block_data in data.get("content", []):
block_type = block_data.get("type")
if block_type == "text":
content.append(TextBlock(**block_data))
elif block_type == "tool_use":
content.append(ToolUseBlock(**block_data))
elif block_type == "tool_result":
content.append(ToolResultBlock(**block_data))
elif block_type == "thinking":
content.append(ThinkingBlock(**block_data))
return cls(
role=data["role"],
content=content,
timestamp=datetime.fromisoformat(data.get("timestamp", "")),
message_id=data.get("message_id", "")
)
```
## 4.2.2 状态管理模式
**发布-订阅模式：** Claude Code 采用发布-订阅模式：维护可变的 AppState，但通过事件发射的方式通知订阅者状态变化。
```python
from typing import Callable, List
from enum import Enum
class StateChangeEvent(Enum):
MESSAGE_ADDED = "message_added"
TOOL_EXECUTED = "tool_executed"
STATE_RESET = "state_reset"
@dataclass
class AppState:
"""可变的应用状态"""
session_id: str
messages: List[Message] = field(default_factory=list)
current_turn: int = 0
token_count: int = 0
_subscribers: List[Callable[[StateChangeEvent, Any], None]] = field(
default_factory=list
)
def subscribe(self, callback: Callable[[StateChangeEvent, Any], None]):
"""订阅状态变化"""
self._subscribers.append(callback)
def _notify(self, event: StateChangeEvent, data: Any):
"""通知所有订阅者"""
for callback in self._subscribers:
try:
callback(event, data)
except Exception as e:
print(f"Subscriber error: {e}")
def add_message(self, message: Message):
"""添加消息(修改当前状态)"""
self.messages.append(message)
self.token_count += self._estimate_tokens(message)
self.current_turn += 1
# 通知订阅者
self._notify(StateChangeEvent.MESSAGE_ADDED, message)
def execute_tool(self, tool_name: str, result: str):
"""记录工具执行"""
# ... 工具执行逻辑
self._notify(StateChangeEvent.TOOL_EXECUTED, {
"tool_name": tool_name,
"result": result
})
# 发布-订阅模式使用示例
app_state = AppState(session_id="sess_456")
def on_state_change(event: StateChangeEvent, data: Any):
print(f"State changed: {event} -> {data}")
app_state.subscribe(on_state_change)
app_state.add_message(Message.user("Hello")) # 触发 MESSAGE_ADDED 事件
```
**不可变状态模式：** OpenClaw 采用不可变状态模式：每次状态变化都产生新的状态对象，保留历史状态链。这种方式的优点：
* **可追踪性**：任何时间点的状态都可恢复
* **并发安全**：多个工作线程无需同步即可读取（因为对象不变）
* **调试友好**：可以记录完整的状态转移序列
```python
from dataclasses import dataclass, field
from typing import List, Tuple
@dataclass(frozen=True) # frozen=True 使对象不可变
class ImmutableSessionState:
"""不可变的会话状态"""
session_id: str
messages: Tuple[Message, ...] = field(default_factory=tuple)
current_turn: int = 0
token_count: int = 0
last_updated: datetime = field(default_factory=datetime.utcnow)
def add_message(self, message: Message) -> "ImmutableSessionState":
"""添加消息,返回新的状态对象"""
new_messages = tuple(list(self.messages) + [message])
return ImmutableSessionState(
session_id=self.session_id,
messages=new_messages,
current_turn=self.current_turn + 1,
token_count=self.token_count + self._estimate_tokens(message),
last_updated=datetime.utcnow()
)
def _estimate_tokens(self, message: Message) -> int:
"""粗略估计消息的令牌数"""
return len(message.get_text().split()) * 1.3 # 简化估计
# 不可变状态模式使用示例
state = ImmutableSessionState(session_id="sess_123")
print(f"初始状态 ID: {id(state)}")
state = state.add_message(Message.user("Hello"))
print(f"添加用户消息后的状态 ID: {id(state)}") # 不同对象
state = state.add_message(Message.assistant([TextBlock(text="Hi there!")]))
print(f"添加助手消息后的状态 ID: {id(state)}") # 又是不同对象
```
## 4.2.3 状态设计的对比
| 方面 | 发布-订阅(Claude Code) | 不可变状态(OpenClaw) |
| ----- | ------------------ | --------------- |
| 内存开销 | 低（原地修改） | 高（每次变化都复制整个状态） |
| 时间复杂度 | O(1) 更新成本 | O(n) 复制成本 |
| 调试能力 | 中（需要日志） | 优（完整历史保留） |
| 并发友好 | 中（需要锁或事件队列） | 优（无竞态条件） |
| 实时反应 | 优（即时通知） | 中（需要后处理历史） |
## 4.2.4 消息历史的窗口管理
由于 LLM 上下文有限，不能无限保留所有消息。需要实现消息窗口管理：
```python
class MessageWindow:
"""消息窗口管理器"""
def __init__(self, max_messages: int = 50, max_tokens: int = 100000):
self.max_messages = max_messages
self.max_tokens = max_tokens
def filter_messages(self, messages: List[Message]) -> List[Message]:
"""根据约束条件过滤消息"""
# 策略1:按消息数量限制
if len(messages) > self.max_messages:
# 保留最后 max_messages 条,丢弃早期消息
messages = messages[-self.max_messages:]
# 策略2:按令牌数量限制
total_tokens = sum(self._estimate_tokens(m) for m in messages)
if total_tokens > self.max_tokens:
# 移除早期消息直到满足令牌限制
while messages and total_tokens > self.max_tokens:
removed = messages.pop(0)
total_tokens -= self._estimate_tokens(removed)
return messages
def _estimate_tokens(self, message: Message) -> int:
"""估计消息的令牌数"""
text = message.get_text()
return len(text.split()) * 1.3
def insert_system_context(self, messages: List[Message],
system_blocks: List[TextBlock]) -> List[Message]:
"""在消息历史前插入系统上下文"""
result = []
# 添加系统消息(不计入限制)
for block in system_blocks:
result.append(Message.assistant([block]))
# 添加过滤后的消息历史
result.extend(self.filter_messages(messages))
return result
```
## 4.2.5 本节小结
清晰的消息类型系统和合理的状态管理方式是运行时的基础：
1. **消息类型体系** 定义了 智能体循环中的各种信息（文本、工具调用、工具结果、思考过程），提供类型安全的接口
2. **不可变状态模式** 适合需要完整追踪和并发安全的场景，代价是内存和性能
3. **发布-订阅模式** 适合需要低延迟反应和实时流式处理的场景，代价是需要额外的同步机制
4. **消息窗口管理** 确保在有限的上下文窗口内动态调度消息，是处理长对话的必需能力
# 4.3 流式处理与事件驱动架构
流式处理和事件驱动是现代智能体系统的必要能力，支持低延迟和高吞吐。本节介绍流式处理的优势，对比OpenClaw和Claude Code的实现方式，并讨论事件流架构和背压控制机制。
## 4.3.1 为什么工具必须在流式响应期间执行
传统的批处理模型(Batch Model)将智能体推理与工具执行分离：
```
推理完成 → 提取工具调用 → 执行工具 → 等待全部完成 → 反馈给 Agent
```
这种模式的问题：
1. **高延迟**：必须等待所有工具执行完成才能继续推理，单个慢工具阻塞整个流程
2. **无法流式响应**：用户无法看到实时的智能体思考过程
3. **低效的资源利用**：CPU 和网络资源无法充分并发
4. **错误恢复困难**：工具失败后难以进行灵活的备选处理
**流式处理模型** (Streaming Model)将工具执行集成到流式响应中：
```mermaid
graph TD
A["响应流开始"] --> B["文本块
立即流送给客户端"]
B --> C["工具调用块开始
异步执行工具
不阻塞流"]
C --> D["文本块
继续流送"]
D --> E["工具调用块完成
结果反馈给 Agent"]
E --> F["响应流结束"]
C -.并发.- G["多个工具
可以并发执行"]
E -.后续.- H["智能体 可以
立即进行下一轮思考"]
style A fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style B fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000000
style C fill:#fff8c4,stroke:#ffb74d,stroke-width:2px,color:#000000
style D fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000000
style E fill:#fff8c4,stroke:#ffb74d,stroke-width:2px,color:#000000
style F fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style G fill:#ffe0b2,stroke:#ffb74d,stroke-width:2px,color:#000000
style H fill:#ffe0b2,stroke:#ffb74d,stroke-width:2px,color:#000000
```
图 4-3：流式处理架构
**流式处理的核心优势**
1. **低时间延迟**：用户可以立即看到智能体的首字节响应，而不需要等待所有工具完成
2. **高吞吐量**：工具并发执行，单个工具的网络延迟不影响整体响应
3. **更好的用户体验**：实时反馈让用户感知到系统正在工作
4. **灵活的错误恢复**：工具失败时可以立即重试或选择替代方案
## 4.3.2 Claude Code 的 StreamingToolExecutor 设计
Claude Code 采用 **流式响应 + 异步工具执行** 的模式：
```python
class StreamingToolExecutor:
"""流式工具执行器:在响应流中处理工具调用"""
def __init__(self, tool_registry: ToolRegistry, max_concurrent: int = 5):
self.tool_registry = tool_registry
self.max_concurrent = max_concurrent
self._pending_executions: Dict[str, asyncio.Task] = {}
async def execute_tools(
self,
tool_uses: List[ToolUseBlock],
app_state: AppState
) -> Dict[str, ToolResultBlock]:
"""
并发执行多个工具调用,返回所有结果
使用 asyncio.Semaphore 限制并发数
"""
semaphore = asyncio.Semaphore(self.max_concurrent)
tasks = []
for tool_use in tool_uses:
task = self._execute_single_tool(tool_use, app_state, semaphore)
tasks.append(task)
self._pending_executions[tool_use.id] = task
# 并发等待所有工具完成
results = await asyncio.gather(*tasks, return_exceptions=True)
# 组织结果
tool_results = {}
for tool_use, result in zip(tool_uses, results):
if isinstance(result, Exception):
tool_results[tool_use.id] = ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Tool execution error: {str(result)}",
is_error=True,
error_type=type(result).__name__
)
else:
tool_results[tool_use.id] = result
return tool_results
async def _execute_single_tool(
self,
tool_use: ToolUseBlock,
app_state: AppState,
semaphore: asyncio.Semaphore
) -> ToolResultBlock:
"""执行单个工具"""
async with semaphore:
try:
# 1. 查找工具
tool = self.tool_registry.get(tool_use.name)
if not tool:
raise ToolNotFoundError(f"Tool '{tool_use.name}' not found")
# 2. 权限检查
if not tool.check_permissions(app_state):
raise PermissionDeniedError(
f"Permission denied for tool '{tool_use.name}'"
)
# 3. 执行工具
result = await tool.call(tool_use.input)
# 4. 组织结果
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(result),
is_error=False
)
except Exception as e:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(e),
is_error=True,
error_type=type(e).__name__
)
def get_tool_progress(self, tool_use_id: str) -> Optional[ToolProgress]:
"""获取某个工具的执行进度(如果可用)"""
task = self._pending_executions.get(tool_use_id)
if not task:
return None
# 实现细节:从工具对象的进度属性中提取(如果工具支持)
# 通常通过工具返回的结果对象或单独的进度查询接口获取
# 这是一个简化的实现,实际需要根据具体工具的API调整
if hasattr(task, '_progress'):
return task._progress
return None
```
## 4.3.3 OpenClaw 的响应流处理
OpenClaw 采用“响应流优先”的设计，在流式响应过程中持续检测工具调用：
```python
class StreamingResponseHandler:
"""处理 API 流式响应"""
def handle_stream(self, stream):
"""逐个处理流中的事件"""
accumulated_input_json = "" # 累积工具参数的 JSON
for event in stream:
if event.type == "content_block_start":
if event.content_block.type == "text":
# 开始新的文本块
pass
elif event.content_block.type == "tool_use":
# 工具调用开始
accumulated_input_json = ""
elif event.type == "content_block_delta":
if event.delta.type == "text_delta":
# 文本增量,直接转发给前端
self.send_to_frontend(TextDeltaEvent(event.delta.text))
elif event.delta.type == "input_json_delta":
# 累积 JSON 参数
accumulated_input_json += event.delta.partial_json
elif event.type == "content_block_stop":
if event.content_block.type == "tool_use":
# 工具调用完成,此时有完整的 accumulated_input_json
tool_name = event.content_block.name
tool_input = json.loads(accumulated_input_json)
# 立即执行工具(可能阻塞,但用户已看到实时响应)
result = self.execute_tool(tool_name, tool_input)
self.send_to_frontend(ToolResultEvent(result))
```
## 4.3.4 事件流架构
完整的 智能体循环产生的事件序列：
```mermaid
graph TD
Start["agent_start
(agent_id, timestamp)"] --> TurnStart["turn_start
(turn_number, context_tokens)"]
TurnStart --> ContentStart["content_block_start
(block_id, block_type, timestamp)"]
ContentStart --> TextDelta["text_delta
(block_id, text, timestamp)"]
TextDelta --> ToolUseStart["tool_use_start
(tool_use_id, tool_name, timestamp)"]
ToolUseStart --> ToolInputDelta["tool_input_delta
(tool_use_id, json_delta, timestamp)"]
ToolInputDelta --> ToolUseEnd["tool_use_end
(tool_use_id, timestamp)"]
ToolUseEnd --> ToolResult["tool_result (async)
(tool_use_id, content, is_error, timestamp)"]
ToolResult --> ContentEnd["content_block_end
(block_id, timestamp)"]
ContentEnd --> MessageEnd["message_end
(message_id, stop_reason, timestamp)"]
MessageEnd --> TurnEnd["turn_end
(turn_number, has_tool_calls, timestamp)"]
TurnEnd --> Decision{继续循环?}
Decision -->|是| TurnStart
Decision -->|否| AgentEnd["agent_end
(final_response, message_count, timestamp)"]
style Start fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style AgentEnd fill:#f5e8f4,stroke:#a44a90,stroke-width:2px,color:#000000
style ToolResult fill:#f8e8e8,stroke:#a44a4a,stroke-width:2px,color:#000000
```
**事件流的实现**
```python
from dataclasses import dataclass
from typing import AsyncIterator
from enum import Enum
class EventType(Enum):
AGENT_START = "agent_start"
TURN_START = "turn_start"
CONTENT_BLOCK_START = "content_block_start"
TEXT_DELTA = "text_delta"
TOOL_USE_START = "tool_use_start"
TOOL_INPUT_DELTA = "tool_input_delta"
TOOL_USE_END = "tool_use_end"
TOOL_RESULT = "tool_result"
CONTENT_BLOCK_END = "content_block_end"
MESSAGE_END = "message_end"
TURN_END = "turn_end"
AGENT_END = "agent_end"
ERROR = "error"
@dataclass
class Event:
"""事件基类"""
event_type: EventType
timestamp: datetime = field(default_factory=datetime.utcnow)
metadata: Dict[str, Any] = field(default_factory=dict)
def to_json(self) -> str:
"""序列化为 JSON(用于流式传输)"""
return json.dumps({
"event_type": self.event_type.value,
"timestamp": self.timestamp.isoformat(),
"metadata": self.metadata
})
class QueryEngine:
"""生成事件流的查询引擎"""
async def submit_message(self, user_input: str) -> AsyncIterator[Event]:
"""异步生成器:逐个 yield 事件"""
try:
yield Event(EventType.AGENT_START, metadata={
"user_input_length": len(user_input)
})
app_state = AppState(session_id=str(uuid.uuid4()))
turn_number = 0
while True:
turn_number += 1
yield Event(EventType.TURN_START, metadata={
"turn_number": turn_number,
"context_tokens": app_state.token_count
})
# 构建上下文
messages = await self._build_messages(app_state)
system_prompt = self._get_system_prompt()
# 流式调用模型
tool_uses = []
async for event in self._stream_model_response(
messages=messages,
system=system_prompt
):
# 转发模型流中的文本和工具使用事件
yield event
if event.event_type == EventType.TOOL_USE_END:
tool_uses.append(event.metadata["tool_use"])
# 执行工具(异步,不阻塞事件流)
if tool_uses:
tool_results = await self.executor.execute_tools(
tool_uses, app_state
)
# 发出工具结果事件
for tool_use_id, result in tool_results.items():
yield Event(EventType.TOOL_RESULT, metadata={
"tool_use_id": tool_use_id,
"is_error": result.is_error,
"content_length": len(result.content)
})
# 更新应用状态以继续下一轮推理
app_state.add_tool_results(tool_results)
else:
# 没有工具调用,循环结束
break
yield Event(EventType.TURN_END, metadata={
"turn_number": turn_number,
"has_tool_calls": bool(tool_uses)
})
yield Event(EventType.AGENT_END, metadata={
"final_response": app_state.get_final_response(),
"turn_count": turn_number,
"message_count": len(app_state.messages)
})
except Exception as e:
yield Event(EventType.ERROR, metadata={
"error_type": type(e).__name__,
"error_message": str(e)
})
```
## 4.3.5 背压与流量控制
在流式处理中，如果客户端处理事件的速度慢于服务器生成事件的速度，会导致内存溢出。需要实现背压机制：
```python
class BackpressureQueue:
"""带背压的事件队列"""
def __init__(self, max_queue_size: int = 100):
self.queue: asyncio.Queue = asyncio.Queue(maxsize=max_queue_size)
async def put_event(self, event: Event):
"""发送事件,如果队列满则等待"""
try:
self.queue.put_nowait(event)
except asyncio.QueueFull:
# 队列满,等待消费者处理
await self.queue.put(event)
async def get_event(self) -> Event:
"""接收事件,带超时"""
return await asyncio.wait_for(
self.queue.get(),
timeout=30.0 # 30秒超时
)
def queue_size(self) -> int:
"""获取当前队列大小"""
return self.queue.qsize()
```
## 4.3.6 本节小结
流式处理与事件驱动是现代智能体系统的必要能力：
1. **流式处理的优势** 明显：低延迟、高吞吐、更好的用户体验、灵活的错误恢复
2. **工具必须在流式响应期间执行**，而不是批处理，这样智能体可以立即获得结果反馈进行下一轮推理
3. **事件流架构** 定义了清晰的状态转移和事件序列，使得系统行为可观测、可预测、可调试
4. **Claude Code 的异步生成器模式和 OpenClaw 的流响应处理** 都实现了这一原则，但编程模型不同（其中 Claude Code 采用异步并发，OpenClaw 采用流式顺序处理）
5. **背压管理** 是生产环境中必需的，防止内存溢出和系统过载
# 4.4 错误处理与故障恢复
在智能体运行时，会遇到多种类型的错误，包括工具执行失败、API 调用超时、输出解析错误等。本节介绍如何对这些错误进行分类、设计恢复策略，以及 OpenClaw 的“错误即观察”模式。
## 4.4.1 错误的分类与应对策略
智能体循环中可能遇到的错误分为几类，每类需要不同的处理策略：
**1. 工具执行错误：** 工具调用失败、权限拒绝、参数错误、工具崩溃 **影响范围**：当前工具调用 **恢复策略**：作为“观察”反馈给 Agent
```python
import asyncio
class ToolExecutionError(Exception):
"""工具执行错误"""
def __init__(self, tool_name: str, message: str,
error_type: str = None, retry_count: int = 0):
self.tool_name = tool_name
self.message = message
self.error_type = error_type or type(self).__name__
self.retry_count = retry_count
super().__init__(message)
class ToolTimeoutError(ToolExecutionError):
"""工具执行超时"""
pass
class ToolPermissionError(ToolExecutionError):
"""工具权限不足"""
pass
# 处理示例
async def execute_tool_with_recovery(
tool_use: ToolUseBlock,
executor: ToolExecutor,
max_retries: int = 3
) -> ToolResultBlock:
"""执行工具,带重试机制"""
for attempt in range(max_retries):
try:
result = await executor.execute(tool_use.name, tool_use.input)
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(result),
is_error=False
)
except ToolTimeoutError as e:
# 超时:使用指数退避重试
if attempt < max_retries - 1:
backoff_seconds = 2 ** attempt # 1, 2, 4 秒
await asyncio.sleep(backoff_seconds)
continue
else:
# 最后一次重试失败,返回错误
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Tool timeout after {max_retries} retries: {str(e)}",
is_error=True,
error_type="ToolTimeoutError"
)
except ToolPermissionError as e:
# 权限错误:不重试,立即反馈
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Permission denied: {str(e)}",
is_error=True,
error_type="ToolPermissionError"
)
except ToolExecutionError as e:
# 其他工具错误:重试一次
if attempt < max_retries - 1:
continue
else:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Tool execution failed: {str(e)}",
is_error=True,
error_type=e.error_type
)
except Exception as e:
# 未预期的异常
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Unexpected error: {str(e)}",
is_error=True,
error_type=type(e).__name__
)
```
### 2. API 调用错误
**类型**：模型 API 超时、速率限制、认证失败、API 服务中断 **影响范围**：当前推理轮次 **恢复策略**：重试或回退到备用模型
```python
class ModelAPIError(Exception):
"""模型 API 错误"""
pass
class RateLimitError(ModelAPIError):
"""速率限制"""
def __init__(self, retry_after: int = None):
self.retry_after = retry_after or 60
super().__init__(f"Rate limited, retry after {self.retry_after}s")
class ModelTimeoutError(ModelAPIError):
"""模型调用超时"""
pass
class RetryPolicy:
"""重试策略"""
def __init__(self,
max_retries: int = 3,
initial_backoff: int = 1,
max_backoff: int = 60,
exponential_base: float = 2.0):
self.max_retries = max_retries
self.initial_backoff = initial_backoff
self.max_backoff = max_backoff
self.exponential_base = exponential_base
async def execute_with_retry(self,
coro_fn,
*args, **kwargs) -> Any:
"""执行异步操作,带重试"""
for attempt in range(self.max_retries):
try:
return await coro_fn(*args, **kwargs)
except RateLimitError as e:
# 速率限制:等待指定时间
if attempt < self.max_retries - 1:
await asyncio.sleep(e.retry_after)
continue
else:
raise
except ModelTimeoutError as e:
# 超时:指数退避
if attempt < self.max_retries - 1:
backoff = min(
self.initial_backoff * (self.exponential_base ** attempt),
self.max_backoff
)
await asyncio.sleep(backoff)
continue
else:
raise
except ModelAPIError as e:
# 其他 API 错误:重试
if attempt < self.max_retries - 1:
backoff = min(
self.initial_backoff * (self.exponential_base ** attempt),
self.max_backoff
)
await asyncio.sleep(backoff)
continue
else:
raise
# API重试策略使用示例
retry_policy = RetryPolicy()
async def call_model_with_retry(engine: QueryEngine, message: str):
try:
result = await retry_policy.execute_with_retry(
engine.infer,
messages=[Message.user(message)]
)
return result
except ModelAPIError as e:
# 重试失败,返回降级响应
return Message.assistant([TextBlock(
text=f"Sorry, I encountered an error: {str(e)}"
)])
```
### 3. 输出解析错误
**类型**：模型输出格式不符、工具参数非法、JSON 解析失败 **影响范围**：当前推理结果 **恢复策略**：要求智能体重新生成或修复
```python
class OutputParsingError(Exception):
"""输出解析错误"""
pass
class ToolParameterValidationError(OutputParsingError):
"""工具参数验证失败"""
def __init__(self, tool_name: str, errors: List[str]):
self.tool_name = tool_name
self.errors = errors
super().__init__(
f"Tool '{tool_name}' parameter validation failed: {errors}"
)
def validate_tool_parameters(
tool_name: str,
parameters: Dict[str, Any],
schema: Dict[str, Any]
) -> Tuple[bool, List[str]]:
"""验证工具参数是否符合 Schema"""
errors = []
# 检查必需参数
required = schema.get("required", [])
for param_name in required:
if param_name not in parameters:
errors.append(f"Missing required parameter: {param_name}")
# 检查参数类型
properties = schema.get("properties", {})
for param_name, param_value in parameters.items():
if param_name not in properties:
errors.append(f"Unknown parameter: {param_name}")
continue
param_schema = properties[param_name]
expected_type = param_schema.get("type")
if expected_type == "string" and not isinstance(param_value, str):
errors.append(
f"Parameter '{param_name}' should be string, got {type(param_value).__name__}"
)
elif expected_type == "integer" and not isinstance(param_value, int):
errors.append(
f"Parameter '{param_name}' should be integer, got {type(param_value).__name__}"
)
elif expected_type == "array" and not isinstance(param_value, list):
errors.append(
f"Parameter '{param_name}' should be array, got {type(param_value).__name__}"
)
return len(errors) == 0, errors
# 在工具执行前进行验证
async def execute_tool_validated(tool_use: ToolUseBlock,
tool_registry: ToolRegistry) -> ToolResultBlock:
"""执行工具前进行参数验证"""
tool = tool_registry.get(tool_use.name)
if not tool:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Tool '{tool_use.name}' not found",
is_error=True,
error_type="ToolNotFoundError"
)
# 验证参数
schema = tool.get_input_schema()
is_valid, errors = validate_tool_parameters(
tool_use.name,
tool_use.input,
schema
)
if not is_valid:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Parameter validation failed:\n" + "\n".join(errors),
is_error=True,
error_type="ParameterValidationError"
)
# 参数有效,执行工具
try:
result = await tool.call(tool_use.input)
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(result),
is_error=False
)
except Exception as e:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(e),
is_error=True,
error_type=type(e).__name__
)
```
### 4. 上下文溢出与令牌耗尽
**类型**：消息历史太长、推理输出超过 max\_tokens **影响范围**：整个会话 **恢复策略**：清理历史、压缩上下文、或启动新会话
```python
class ContextOverflowError(Exception):
"""上下文溢出"""
pass
class TokenBudgetExceededError(ContextOverflowError):
"""令牌预算超支"""
def __init__(self, current_tokens: int, budget: int):
self.current_tokens = current_tokens
self.budget = budget
super().__init__(
f"Token budget exceeded: {current_tokens} > {budget}"
)
class ContextCompressor:
"""上下文压缩器"""
def __init__(self, max_summary_length: int = 500):
self.max_summary_length = max_summary_length
def compress_message_history(
self,
messages: List[Message],
target_tokens: int,
summarizer = None # 可选的摘要函数
) -> List[Message]:
"""压缩消息历史以满足令牌预算"""
total_tokens = sum(self._estimate_tokens(m) for m in messages)
if total_tokens <= target_tokens:
return messages # 无需压缩
# 策略1:移除早期消息
while messages and total_tokens > target_tokens:
removed = messages.pop(0)
total_tokens -= self._estimate_tokens(removed)
# 策略2:如果还是太大,对保留的消息进行摘要
if total_tokens > target_tokens and summarizer:
summarized_messages = []
for message in messages:
if message.role == "assistant":
# 摘要 Assistant 的长响应
original_text = message.get_text()
if len(original_text) > self.max_summary_length:
summary = summarizer(original_text,
max_length=self.max_summary_length)
message = Message.assistant([TextBlock(text=summary)])
summarized_messages.append(message)
messages = summarized_messages
total_tokens = sum(self._estimate_tokens(m) for m in messages)
return messages
def _estimate_tokens(self, message: Message) -> int:
"""估计消息的令牌数"""
text = message.get_text()
return len(text.split()) * 1.3 # 粗略估计
# 上下文压缩使用示例
compressor = ContextCompressor()
async def infer_with_context_management(
engine: QueryEngine,
messages: List[Message],
token_budget: int = 100000
) -> Message:
"""推理,带自动的上下文管理"""
estimated_tokens = compressor._estimate_tokens(
Message.assistant([TextBlock(text="".join(m.get_text() for m in messages))])
)
if estimated_tokens > token_budget * 0.8: # 80% 阈值
messages = compressor.compress_message_history(
messages,
target_tokens=int(token_budget * 0.5)
)
try:
return await engine.infer(messages)
except TokenBudgetExceededError as e:
# 令牌预算溢出,再次压缩
messages = compressor.compress_message_history(
messages,
target_tokens=int(token_budget * 0.3)
)
return await engine.infer(messages)
```
## 4.4.2 OpenClaw 的“错误即观察”模式
OpenClaw 的设计哲学是 **将所有错误作为观察反馈回 Agent**：
```python
class ErrorAsObservationHandler:
"""将错误作为观察反馈给 Agent"""
def handle_tool_error(self, tool_use: ToolUseBlock, error: Exception):
"""处理工具错误"""
# 而不是抛出异常,构造一个 ToolResultBlock,表示错误
error_message = f"[Tool Error]\nTool: {tool_use.name}\n"
error_message += f"Error Type: {type(error).__name__}\n"
error_message += f"Error Message: {str(error)}\n"
error_message += "Please analyze the error and try a different approach."
return ToolResultBlock(
tool_use_id=tool_use.id,
content=error_message,
is_error=True,
error_type=type(error).__name__
)
def handle_api_error(self, error: ModelAPIError) -> Message:
"""处理 API 错误"""
# 返回一条特殊的 Assistant 消息,告知智能体发生了错误
return Message.assistant([TextBlock(text=(
f"An error occurred while processing your request:\n"
f"Error: {str(error)}\n"
f"The system will retry the request automatically."
))])
def handle_context_overflow(self,
messages: List[Message],
token_budget: int) -> List[Message]:
"""处理上下文溢出"""
# 通过压缩历史来恢复
return self.compress_history(messages, token_budget)
```
优点：
* 智能体可以看到所有错误信息，学习如何处理
* 系统行为更透明、更可预测
* 智能体可以提出替代方案（例如，文件不存在，试试列出目录）
## 4.4.3 断路器模式
对于可能频繁失败的外部调用（如模型 API、文件系统操作），使用断路器模式防止级联失败。
**错误恢复与断路器状态转移：**
```mermaid
stateDiagram-v2
[*] --> Running
Running --> Error: 异常发生
Error --> Retry: 可重试错误
Error --> Degrade: 不可重试错误
Retry --> Running: 重试成功
Retry --> CircuitOpen: 重试次数超限
CircuitOpen --> HalfOpen: 恢复超时触发
HalfOpen --> Running: 探测成功
HalfOpen --> CircuitOpen: 探测失败
Degrade --> [*]: 降级响应
style Running fill:#c8e6c9
style Error fill:#ffcdd2
style Retry fill:#fff9c4
style CircuitOpen fill:#ffccbc
style HalfOpen fill:#b3e5fc
style Degrade fill:#f0f4c3
```
图 4-4：断路器状态转移图
```python
class CircuitBreakerState(Enum):
CLOSED = "closed" # 正常,允许请求
OPEN = "open" # 失败过多,拒绝请求
HALF_OPEN = "half_open" # 尝试恢复,允许一个请求
class CircuitBreaker:
"""断路器模式"""
def __init__(self, failure_threshold: int = 5,
recovery_timeout: int = 60):
self.failure_threshold = failure_threshold
self.recovery_timeout = recovery_timeout
self.failure_count = 0
self.state = CircuitBreakerState.CLOSED
self.last_failure_time = None
async def call(self, coro_fn, *args, **kwargs):
"""通过断路器调用函数"""
# 检查是否应该打开断路器
if self.state == CircuitBreakerState.OPEN:
if self._should_attempt_recovery():
self.state = CircuitBreakerState.HALF_OPEN
else:
raise Exception("Circuit breaker is OPEN, rejecting request")
try:
result = await coro_fn(*args, **kwargs)
self._on_success()
return result
except Exception as e:
self._on_failure()
raise
def _on_success(self):
"""成功后的处理"""
self.failure_count = 0
self.state = CircuitBreakerState.CLOSED
def _on_failure(self):
"""失败后的处理"""
self.failure_count += 1
self.last_failure_time = time.time()
if self.failure_count >= self.failure_threshold:
self.state = CircuitBreakerState.OPEN
def _should_attempt_recovery(self) -> bool:
"""判断是否应该尝试恢复"""
if not self.last_failure_time:
return False
return time.time() - self.last_failure_time > self.recovery_timeout
```
## 4.4.4 本节小结
错误处理是智能体系统可靠性的关键：
1. **分类处理**：不同类型的错误需要不同的恢复策略（重试、降级、打断路器）
2. **工具执行错误** 最常见，应该被作为“观察”反馈给 Agent，而不是中断循环
3. **API 错误** 需要重试策略（指数退避、速率限制感知）
4. **输出解析错误** 需要参数验证，防止传递无效的工具调用
5. **上下文溢出** 需要动态压缩和历史管理
6. **断路器模式** 可以防止级联失败和资源耗尽
# 4.5 长时任务的漂移检测与纠正
长时运行的智能体任务容易出现目标漂移现象，即 Agent 在执行过程中逐步偏离原始目标。本节介绍漂移的检测方法、纠正策略以及上下文重置机制。
## 4.5.1 什么是目标漂移
在长时运行的智能体任务中，存在一个常见问题：Agent 在中间某个环节偏离了原始目标，逐步走向错误的方向。这种现象称为 **目标漂移(Goal Drift)**。
### 漂移的表现形式
1. **目标遗忘**：Agent 忘记了原始任务，开始追求无关的子目标
2. **目标替代**：Agent 用某个中间目标替代了主目标
3. **范围蠕变**：原始任务范围逐步扩大，导致成本失控
4. **方向漂移**：推理过程偏离最优路径，走向局部最优
### 漂移的危害
* 任务失败率提高（Agent 最终无法完成原始目标）
* 资源浪费（执行了大量无关的工具调用）
* 用户体验差（Agent 变得不可预测）
* 难以调试（漂移原因通常隐含在推理过程中）
## 4.5.2 漂移检测机制
**目标漂移的检测与纠正流程：**
```mermaid
graph TD
A["监控 Agent 行动"] --> B{"计算漂移
评分"}
B --> C{"漂移分数
< 阈值?"}
C -->|是| D["检测到漂移"]
C -->|否| E["继续执行"]
D --> F{"选择纠正
策略"}
F -->|反思| G["强制反思步骤"]
F -->|检查点| H["恢复到之前状态"]
F -->|约束| I["约束验证"]
G --> J["重新规划"]
H --> J
I --> J
J --> E
style A fill:#e3f2fd
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#ffcdd2
style F fill:#fce4ec
style G fill:#bbdefb
style H fill:#c8e6c9
style I fill:#ffe0b2
style J fill:#d1c4e9
```
图 4-5：漂移检测与纠正流程
### 1. 目标与当前行动的相似度检查
通过关键词匹配检查Agent是否偏离原始目标：
```python
from dataclasses import dataclass
from typing import List, Optional
import math
@dataclass
class Goal:
"""任务目标定义"""
original_goal: str
main_keywords: List[str] # 从目标中提取的关键词
metric: Optional[str] = None # 成功指标
deadline: Optional[int] = None # 轮数限制
class DriftDetector:
"""漂移检测器"""
def __init__(self, similarity_threshold: float = 0.3,
window_size: int = 5):
self.similarity_threshold = similarity_threshold
self.window_size = window_size # 检查最近 N 轮的行动
def detect_drift(self, goal: Goal,
current_state: AgentState) -> Tuple[bool, float, str]:
"""
检测是否发生了漂移
返回: (is_drifted, drift_score, reason)
"""
recent_actions = self._get_recent_actions(current_state)
# 计算相似度
drift_score = self._compute_drift_score(goal, recent_actions)
if drift_score < self.similarity_threshold:
# 相似度太低,表示已漂移
reason = f"Low similarity with goal (score={drift_score:.2f})"
return True, drift_score, reason
# 检查其他漂移指标
is_expanding = self._detect_scope_expansion(goal, current_state)
if is_expanding:
return True, drift_score, "Scope expansion detected"
is_local_optimal = self._detect_local_optimum(goal, current_state)
if is_local_optimal:
return True, drift_score, "Stuck in local optimum"
return False, drift_score, "No drift detected"
def _get_recent_actions(self, state: AgentState) -> List[str]:
"""提取最近 window_size 轮的工具调用"""
recent = []
for msg in state.messages[-self.window_size * 2:]:
if msg.role == "assistant":
for tool_use in msg.get_tool_calls():
recent.append(f"{tool_use.name}({', '.join(tool_use.input.keys())})")
return recent
def _compute_drift_score(self, goal: Goal, actions: List[str]) -> float:
"""计算动作与目标的相关性"""
if not actions:
return 0.0
# 简化版本:检查关键词出现在动作中的频率
keyword_matches = 0
for keyword in goal.main_keywords:
for action in actions:
if keyword.lower() in action.lower():
keyword_matches += 1
return keyword_matches / len(actions) if actions else 0.0
def _detect_scope_expansion(self, goal: Goal,
state: AgentState) -> bool:
"""检测范围蠕变"""
# 检查工具调用数量是否超过合理范围
tool_count = sum(
len(msg.get_tool_calls())
for msg in state.messages
if msg.role == "assistant"
)
# 启发式:假设大多数任务不需要 > 50 次工具调用
if tool_count > 50:
return True
return False
def _detect_local_optimum(self, goal: Goal,
state: AgentState) -> bool:
"""检测是否陷入局部最优"""
# 检查是否重复执行相同的工具调用
action_counts = {}
for msg in state.messages[-self.window_size:]:
if msg.role == "assistant":
for tool_use in msg.get_tool_calls():
key = f"{tool_use.name}({tool_use.input.get('path', '')})"
action_counts[key] = action_counts.get(key, 0) + 1
# 如果有工具被调用了 > 2 次(在小窗口内)
return max(action_counts.values()) > 2 if action_counts else False
```
### 2. 语义检测
通过向量相似度检测目标与当前操作的语义偏离：
```python
class SemanticDriftDetector:
"""使用语义相似度的漂移检测"""
def __init__(self, embedding_model):
self.embedding_model = embedding_model # 如 OpenAI embeddings
async def detect_semantic_drift(
self,
original_goal: str,
recent_messages: List[Message]
) -> Tuple[bool, float]:
"""
使用语义相似度检测漂移
"""
# 获取原始目标的嵌入
goal_embedding = await self.embedding_model.embed(original_goal)
# 获取最近消息内容的嵌入
recent_text = " ".join(
msg.get_text() for msg in recent_messages[-10:]
)
recent_embedding = await self.embedding_model.embed(recent_text)
# 计算余弦相似度
similarity = self._cosine_similarity(goal_embedding, recent_embedding)
# 相似度 < 0.6 表示可能漂移
is_drifted = similarity < 0.6
return is_drifted, similarity
def _cosine_similarity(self, vec1, vec2) -> float:
"""计算两个向量的余弦相似度"""
dot_product = sum(a * b for a, b in zip(vec1, vec2))
norm1 = math.sqrt(sum(a ** 2 for a in vec1))
norm2 = math.sqrt(sum(b ** 2 for b in vec2))
if norm1 == 0 or norm2 == 0:
return 0.0
return dot_product / (norm1 * norm2)
```
## 4.5.3 纠正策略
### 1. 强制反思步骤
OpenClaw 定期在智能体循环中插入强制反思步骤，要求智能体重新评估当前进度：
```python
class ReflectionStep:
"""强制反思步骤"""
def __init__(self, reflection_interval: int = 5):
"""每 reflection_interval 轮执行一次"""
self.reflection_interval = reflection_interval
def should_reflect(self, turn_count: int) -> bool:
"""判断是否应该进行反思"""
return turn_count > 0 and turn_count % self.reflection_interval == 0
def build_reflection_prompt(self, goal: Goal,
state: AgentState) -> Message:
"""构造反思提示"""
reflection_prompt = f"""
### Reflection Point
Original goal: {goal.original_goal}
Current progress (last 3 turns):
{self._summarize_recent_progress(state)}
Please answer:
1. Are we still on track to achieve the original goal?
2. Have we deviated from the original objective?
3. Should we adjust our approach?
4. What's the next best action?
Be concise and critical.
"""
return Message.user(reflection_prompt)
def _summarize_recent_progress(self, state: AgentState) -> str:
"""摘要最近的进度"""
summary = []
for i, msg in enumerate(state.messages[-6:]):
if msg.role == "assistant":
text = msg.get_text()[:200] # 限制长度
summary.append(f"Turn {i}: {text}")
return "\n".join(summary)
# 在 智能体循环中使用
reflection = ReflectionStep(reflection_interval=5)
async def agent_loop_with_reflection(
engine: QueryEngine,
goal: Goal,
max_turns: int = 30
) -> AgentState:
"""带反思的 智能体循环"""
state = AgentState(goal=goal)
for turn in range(max_turns):
# 正常推理
response = await engine.infer(state.messages)
state.add_message(response)
# 检查是否需要反思
if reflection.should_reflect(turn):
print(f"[Turn {turn}] Performing reflection...")
reflection_prompt = reflection.build_reflection_prompt(goal, state)
# 让智能体进行反思
reflection_response = await engine.infer(
state.messages + [reflection_prompt]
)
# 分析反思结果,判断是否需要调整策略
is_on_track = self._analyze_reflection(reflection_response)
if not is_on_track:
print(f"[Turn {turn}] Drift detected, correcting course...")
# 发送纠正提示
correction_prompt = Message.user(
"Your reflection indicates a deviation. "
"Please refocus on the original goal and provide a corrected action plan."
)
state.add_message(reflection_response)
state.add_message(correction_prompt)
# 继续循环
if not response.has_tool_calls():
break
return state
def _analyze_reflection(self, reflection_response: Message) -> bool:
"""分析反思结果"""
text = reflection_response.get_text().lower()
off_track_keywords = ["deviated", "off track", "wrong", "mistake"]
return not any(kw in text for kw in off_track_keywords)
```
### 2. 检查点与恢复
使用检查点机制实现恢复功能，快速回到上一个正确状态：
```python
@dataclass
class Checkpoint:
"""检查点:记录某个时刻的完整状态"""
turn_number: int
messages: List[Message]
goal: Goal
timestamp: datetime
drift_score: float = 0.0
class CheckpointManager:
"""检查点管理"""
def __init__(self, checkpoint_dir: str = "./checkpoints"):
self.checkpoint_dir = checkpoint_dir
os.makedirs(checkpoint_dir, exist_ok=True)
def save_checkpoint(self, state: AgentState, goal: Goal) -> str:
"""保存检查点"""
checkpoint = Checkpoint(
turn_number=state.current_turn,
messages=state.messages.copy(),
goal=goal,
timestamp=datetime.utcnow()
)
checkpoint_id = f"ckpt_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}"
filepath = os.path.join(self.checkpoint_dir, f"{checkpoint_id}.json")
with open(filepath, 'w') as f:
json.dump(
{
"turn_number": checkpoint.turn_number,
"messages": [m.to_dict() for m in checkpoint.messages],
"goal": goal.original_goal,
"timestamp": checkpoint.timestamp.isoformat()
},
f,
indent=2
)
return checkpoint_id
def restore_checkpoint(self, checkpoint_id: str) -> Tuple[AgentState, Goal]:
"""恢复检查点"""
filepath = os.path.join(self.checkpoint_dir, f"{checkpoint_id}.json")
with open(filepath, 'r') as f:
data = json.load(f)
messages = [Message.from_dict(m) for m in data["messages"]]
goal = Goal(original_goal=data["goal"])
state = AgentState(goal=goal)
state.messages = messages
state.current_turn = data["turn_number"]
return state, goal
# 使用
checkpoint_mgr = CheckpointManager()
async def agent_loop_with_checkpointing(
engine: QueryEngine,
goal: Goal,
max_turns: int = 30,
drift_detector: DriftDetector = None
) -> AgentState:
"""带检查点的 智能体循环,支持漂移恢复"""
state = AgentState(goal=goal)
drift_detector = drift_detector or DriftDetector()
for turn in range(max_turns):
# 每 5 轮保存一个检查点
if turn % 5 == 0:
ckpt_id = checkpoint_mgr.save_checkpoint(state, goal)
print(f"[Checkpoint {ckpt_id}] Saved at turn {turn}")
# 推理
response = await engine.infer(state.messages)
state.add_message(response)
# 漂移检测
is_drifted, score, reason = drift_detector.detect_drift(goal, state)
if is_drifted:
print(f"[Turn {turn}] Drift detected: {reason}")
# 回滚到最近的检查点,重新开始
if turn >= 5:
prev_ckpt_id = f"ckpt_{(turn - 5):03d}"
try:
state, goal = checkpoint_mgr.restore_checkpoint(prev_ckpt_id)
print(f"[Restored] From checkpoint {prev_ckpt_id}")
continue
except FileNotFoundError:
pass
# 如果没有检查点可恢复,发送纠正提示
correction_msg = Message.user(
f"The current approach has deviated from the goal. "
f"Original goal: {goal.original_goal}. "
f"Please refocus and provide a new action plan."
)
state.add_message(correction_msg)
if not response.has_tool_calls():
break
return state
```
### 3. 约束验证
通过约束验证器确保智能体行为在预定界限内：
```python
class ConstraintValidator:
"""约束验证器,确保智能体行为在预定界限内"""
def __init__(self):
self.constraints = []
def add_constraint(self, name: str, check_fn: Callable[[AgentState], bool],
violation_msg: str):
"""添加约束条件"""
self.constraints.append({
"name": name,
"check_fn": check_fn,
"violation_msg": violation_msg
})
def validate(self, state: AgentState) -> Tuple[bool, List[str]]:
"""验证所有约束"""
violations = []
for constraint in self.constraints:
if not constraint["check_fn"](state):
violations.append(constraint["violation_msg"])
return len(violations) == 0, violations
# 约束验证使用示例
validator = ConstraintValidator()
# 添加约束:工具调用不超过 50 次
validator.add_constraint(
name="max_tool_calls",
check_fn=lambda state: sum(
len(msg.get_tool_calls()) for msg in state.messages
if msg.role == "assistant"
) <= 50,
violation_msg="Exceeded maximum tool call limit (50)"
)
# 添加约束:消息总长度不超过 1M 字符
validator.add_constraint(
name="max_message_length",
check_fn=lambda state: sum(
len(msg.get_text()) for msg in state.messages
) <= 1_000_000,
violation_msg="Message history exceeded 1M characters"
)
# 添加约束:执行时间不超过 1 小时
validator.add_constraint(
name="max_execution_time",
check_fn=lambda state: (datetime.utcnow() - state.start_time).total_seconds() < 3600,
violation_msg="Execution time exceeded 1 hour"
)
async def agent_loop_with_constraints(
engine: QueryEngine,
goal: Goal,
validator: ConstraintValidator
) -> AgentState:
"""带约束的 智能体循环"""
state = AgentState(goal=goal)
while True:
# 在每轮推理前验证约束
is_valid, violations = validator.validate(state)
if not is_valid:
print(f"[Constraint Violation] {', '.join(violations)}")
break
# 继续推理
response = await engine.infer(state.messages)
state.add_message(response)
if not response.has_tool_calls():
break
return state
```
## 4.5.4 上下文重置
当智能体陷入循环或漂移过远时，传统的漂移纠正方法（反思、修补、约束）可能效果有限。在这种情况下，可以采用一种更激进的方法：**上下文重置**，即清空积累的上下文，从干净状态重新开始。Anthropic 在其 Harness 设计实践中也采用了这一模式，尤其是在处理早期模型的上下文焦虑问题时效果显著。
### 核心思想
上下文重置是一种\u201c重启\u201d机制，类似于计算机系统的重新启动。当系统积累太多错误状态或陷入深度循环时，与其尝试逐步修复，不如清空并重新开始——但仅保留关键信息。
**关键原则：**
* **清空累积的噪音**：移除所有失败的尝试、错误的推理步骤和无关的中间状态
* **保留关键状态**：将重要信息（原始目标、已验证的进展、关键发现）持久化到外部存储
* **简化上下文窗口**：用清晰的摘要替代冗长的历史记录
* **对比增量压缩**：与其试图压缩所有历史（增量压缩往往失去细节），不如直接丢弃并恢复关键部分
### 实现流程
以下是上下文重置的完整流程，当检测到陷入循环或深度漂移时执行：
```mermaid
flowchart TD
A["检测陷入循环或深度漂移
(重复行动 > N 次)"]
B["1. 保存关键检查点到外部存储
- 原始目标
- 当前验证通过的进展
- 学到的关键约束/规则
- 失败模式分析"]
C["2. 清空上下文窗口
- 丢弃所有失败的尝试
- 丢弃中间推理过程
- 保留仅最后的有效状态"]
D["3. 从检查点重新加载
- 加载原始目标
- 加载已验证的进展摘要
- 注入学到的规则到系统提示
- 设置更激进的重试策略"]
E["4. 从清晰状态继续执行
(通常成功率显著提升)"]
A --> B
B --> C
C --> D
D --> E
style A fill:#e8f4f8,stroke:#333,color:#000000
style B fill:#f0e8f8,stroke:#333,color:#000000
style C fill:#f8f0e8,stroke:#333,color:#000000
style D fill:#e8f8f0,stroke:#333,color:#000000
style E fill:#f8e8f0,stroke:#333,color:#000000
```
### 伪代码实现
下面是上下文重置管理器的具体实现示例：
```python
class ContextResetManager:
"""上下文重置管理器"""
def __init__(self, checkpoint_store, max_iterations_before_reset=10):
self.checkpoint_store = checkpoint_store
self.max_iterations = max_iterations_before_reset
self.reset_count = 0
def should_reset(self, state: AgentState) -> bool:
"""判断是否需要重置上下文"""
# 检查最近 N 轮是否重复同样的行动(循环)
recent_actions = self._get_recent_actions(state, window=5)
if len(set(recent_actions)) < 2: # 只有 0-1 种不同的行动
return True
# 检查消息长度是否过度增长
total_chars = sum(len(msg.get_text()) for msg in state.messages)
if total_chars > 100_000: # 超过 100K 字符
return True
return False
def extract_and_save_checkpoint(self, state: AgentState, goal: Goal):
"""提取关键信息并保存检查点"""
checkpoint = {
"timestamp": datetime.utcnow().isoformat(),
"original_goal": goal.original_goal,
"verified_progress": self._extract_verified_progress(state),
"learned_constraints": self._extract_learned_rules(state),
"failure_patterns": self._analyze_failure_patterns(state),
}
checkpoint_id = self.checkpoint_store.save(checkpoint)
return checkpoint_id
def reset_context(self, state: AgentState, checkpoint_id: str) -> AgentState:
"""重置上下文并从检查点恢复"""
# 加载检查点
checkpoint = self.checkpoint_store.load(checkpoint_id)
# 创建新的清晰状态
new_state = AgentState(goal=Goal(original_goal=checkpoint["original_goal"]))
# 注入已验证的进展
progress_msg = Message.assistant(
f"Previous verified progress:\n{checkpoint['verified_progress']}"
)
new_state.add_message(progress_msg)
# 构造系统提示,包含学到的规则
system_prompt = self._build_reset_system_prompt(checkpoint)
# 返回重置后的状态
return new_state, system_prompt
def _extract_verified_progress(self, state: AgentState) -> str:
"""从状态中提取已验证完成的部分"""
# 简化的实现:找到最后一个成功的工具调用
for msg in reversed(state.messages):
if msg.has_tool_result() and msg.tool_result_success:
return f"Successfully: {msg.get_text()[:500]}"
return "No verified progress yet"
def _extract_learned_rules(self, state: AgentState) -> List[str]:
"""从失败和纠正过程中提取规则"""
rules = []
# 扫描是否有"应该避免"的模式
for msg in state.messages[-20:]: # 最近 20 条消息
if "should not" in msg.get_text().lower():
rules.append(msg.get_text())
return rules
def _analyze_failure_patterns(self, state: AgentState) -> dict:
"""分析常见的失败模式"""
failure_types = {}
for msg in state.messages:
if msg.has_tool_error():
error_type = self._categorize_error(msg.tool_error)
failure_types[error_type] = failure_types.get(error_type, 0) + 1
return failure_types
def _build_reset_system_prompt(self, checkpoint: dict) -> str:
"""构造重置后的系统提示,包含学到的约束"""
prompt = f"""
You are solving: {checkpoint['original_goal']}
Previous verified progress:
{checkpoint['verified_progress']}
Learned constraints:
{chr(10).join(checkpoint['learned_constraints'])}
Common failure patterns to avoid:
{checkpoint['failure_patterns']}
Continue from the verified progress and avoid previous mistakes.
"""
return prompt.strip()
def _get_recent_actions(self, state: AgentState, window: int) -> List[str]:
"""获取最近的行动序列"""
actions = []
for msg in state.messages[-window * 2:]:
if msg.role == "assistant" and msg.has_tool_calls():
for tool in msg.get_tool_calls():
actions.append(tool.name)
return actions
# 上下文重置使用示例
async def agent_loop_with_context_reset(
engine: QueryEngine,
goal: Goal,
max_turns: int = 50
) -> AgentState:
"""带上下文重置的智能体循环"""
reset_mgr = ContextResetManager(checkpoint_store)
state = AgentState(goal=goal)
for turn in range(max_turns):
# 检查是否需要重置
if reset_mgr.should_reset(state):
print(f"[Turn {turn}] Detecting loop/deep drift, performing context reset...")
# 保存关键信息
ckpt_id = reset_mgr.extract_and_save_checkpoint(state, goal)
# 重置上下文
state, new_prompt = reset_mgr.reset_context(state, ckpt_id)
print(f"[Reset] Context cleared, restarting from checkpoint {ckpt_id}")
# 正常推理
response = await engine.infer(state.messages)
state.add_message(response)
if not response.has_tool_calls():
break
return state
```
### 何时使用上下文重置
* **循环检测**：同样的工具调用重复超过 3-5 次
* **深度漂移**：即使多轮纠正也无法回到轨道
* **上下文膨胀**：消息历史超过可用上下文窗口的 70%
* **学习瓶颈**：智能体无法从之前的错误中学习
## 4.5.5 本节小结
长时任务的漂移检测与纠正是智能体系统高可靠性的必要条件：
1. **漂移检测** 有多种方式：基于关键词的启发式、语义相似度、行动重复检测
2. **强制反思步骤** 让智能体定期评估进度，OpenClaw 通过在推理中插入反思提示实现
3. **检查点机制** 允许任务在漂移时恢复到之前的正确状态
4. **约束验证** 在任务执行前确保遵守硬约束（令牌数、时间限制、工具调用数）
5. **上下文重置** 当其他方法失效时，清空积累的上下文并从关键检查点重新开始
6. 这些机制相互配合，构成了可靠的漂移检测与纠正体系
# 4.6 令牌预算与上下文动态管理
在有限的上下文窗口内运行长时任务，需要对令牌使用进行精细管理。本节介绍令牌预算的组成、动态管理策略，以及三级预算控制体系。
## 4.6.1 令牌预算的关键概念
在 LLM 智能体系统中，每个 API 调用都有令牌成本和延迟成本。在有限的上下文窗口（如 Claude 的 200k 令牌）内，需要精细的令牌预算管理，确保：
1. **不超过上下文限制**：防止 API 调用失败
2. **保持可用余额**：为推理输出预留空间
3. **最大化有效上下文**：在有限令牌内承载最多有用信息
4. **支持长对话**：通过动态压缩和历史管理支持跨越多轮的对话
**令牌预算分配结构：**
```mermaid
graph LR
A["总预算
200,000 tokens"] --> B["系统提示
~500"]
A --> C["消息历史
~50,000"]
A --> D["工具 Schema
~5,000"]
A --> E["用户输入
~2,000"]
A --> F["推理预留
100,000"]
A --> G["可用预留
~42,500"]
style A fill:#c8e6c9
style B fill:#bbdefb
style C fill:#ffe0b2
style D fill:#f8bbd0
style E fill:#e1bee7
style F fill:#fff9c4
style G fill:#ffccbc
```
图 4-6：令牌预算分配图
### 令牌预算的组成
令牌预算的详细构成情况如下所示：
| 预算项目 | 分配 | 说明 |
| --------- | ----------- | ------------- |
| **总令牌预算** | **200,000** | Claude Sonnet |
| 系统提示词 | \~500 | 系统级指令 |
| 消息历史 | \~50,000 | 上下文消息 |
| 工具 Schema | \~5,000 | 工具定义 |
| 用户输入 | \~2,000 | 当前查询 |
| 可用预留 | \~142,500 | **总计** |
| 推理预留 | 100,000 | 思考过程 |
| 实际可用 | \~42,500 | 可用输出空间 |
### 令牌计数的准确性
使用令牌计数器精确追踪令牌使用情况：
```python
class TokenCounter:
"""令牌计数器"""
def __init__(self, model_name: str = "claude-sonnet-4-5"):
self.model_name = model_name
# 可以使用 tiktoken (OpenAI) 或 Claude 官方的计数 API
self._initialize_counter()
def _initialize_counter(self):
"""初始化计数器"""
# 简化版本:使用粗略估计
# 实际应使用官方 API:https://docs.anthropic.com/en/docs/build-a-quick-start-with-the-tokens-api
pass
def count_text_tokens(self, text: str) -> int:
"""计算文本的令牌数"""
from anthropic import Anthropic
client = Anthropic()
response = client.messages.count_tokens(
model=self.model_name,
messages=[{"role": "user", "content": text}]
)
return response.input_tokens
def count_message_tokens(self, message: Message) -> int:
"""计算消息的令牌数"""
return self.count_text_tokens(message.get_text())
def count_messages_tokens(self, messages: List[Message]) -> int:
"""计算多个消息的总令牌数"""
# 可以一次性计数,效率更高
combined_text = "\n".join(msg.get_text() for msg in messages)
return self.count_text_tokens(combined_text)
def count_tool_schema_tokens(self, tools: List[Dict]) -> int:
"""计算工具 Schema 定义的令牌数"""
schema_json = json.dumps(tools, indent=2)
return self.count_text_tokens(schema_json)
```
## 4.6.2 令牌预算管理策略
### 1. 前向估计
在发送请求前估计可能的令牌消耗：
```python
class TokenBudgetManager:
"""令牌预算管理器"""
def __init__(self, total_budget: int = 200000,
safety_margin: int = 10000):
self.total_budget = total_budget
self.safety_margin = safety_margin # 10k 的安全裕度
self.token_counter = TokenCounter()
def get_available_budget(self, current_state: AgentState) -> int:
"""计算当前可用的令牌预算"""
used_tokens = self._estimate_current_usage(current_state)
available = self.total_budget - used_tokens - self.safety_margin
return max(0, available)
def _estimate_current_usage(self, state: AgentState) -> int:
"""估计当前的令牌使用"""
system_tokens = 500 # 系统提示词
history_tokens = self.token_counter.count_messages_tokens(state.messages)
tools_tokens = 5000 # 工具 Schema(缓存)
return system_tokens + history_tokens + tools_tokens
def can_continue_inference(self, state: AgentState,
expected_output_tokens: int = 2000) -> bool:
"""检查是否还有足够的预算继续推理"""
available = self.get_available_budget(state)
return available >= expected_output_tokens
def plan_inference(self, state: AgentState) -> Dict[str, int]:
"""规划推理的令牌分配"""
available = self.get_available_budget(state)
return {
"available_budget": available,
"recommended_max_tokens": min(available, 4000),
"warning_threshold": available * 0.2
}
# 令牌预算管理使用示例
budget_mgr = TokenBudgetManager()
async def infer_with_budget_check(engine: QueryEngine,
state: AgentState) -> Optional[Message]:
"""推理前检查预算"""
if not budget_mgr.can_continue_inference(state):
print(f"Token budget exhausted. Current usage: "
f"{budget_mgr._estimate_current_usage(state)} / {budget_mgr.total_budget}")
return None
plan = budget_mgr.plan_inference(state)
print(f"[Budget] Available: {plan['available_budget']}, "
f"Max tokens: {plan['recommended_max_tokens']}")
response = await engine.infer(
state.messages,
max_tokens=plan['recommended_max_tokens']
)
return response
```
### 2. 自动压缩
当令牌使用接近阈值时，自动压缩历史：
```python
class AutoCompactor:
"""自动压缩器:当令牌使用超过阈值时触发压缩"""
def __init__(self, compression_threshold: float = 0.8):
"""
compression_threshold: 触发压缩的百分比
例如 0.8 表示当使用到总预算的 80% 时触发
"""
self.compression_threshold = compression_threshold
self.token_counter = TokenCounter()
def should_compact(self, budget_mgr: TokenBudgetManager,
state: AgentState) -> bool:
"""判断是否应该进行压缩"""
used_tokens = budget_mgr._estimate_current_usage(state)
threshold_tokens = budget_mgr.total_budget * self.compression_threshold
return used_tokens > threshold_tokens
def compact_messages(self, messages: List[Message],
target_token_count: int,
summarizer = None) -> List[Message]:
"""压缩消息历史以满足令牌目标"""
current_tokens = self.token_counter.count_messages_tokens(messages)
if current_tokens <= target_token_count:
return messages # 无需压缩
print(f"[Compacting] {current_tokens} tokens -> {target_token_count} tokens")
# 策略 1:移除早期消息
compacted = list(messages)
while compacted and self.token_counter.count_messages_tokens(compacted) > target_token_count:
# 移除最早的消息
removed = compacted.pop(0)
print(f" Removed: {removed.get_text()[:80]}...")
return compacted
def compact_with_summarization(
self,
messages: List[Message],
target_token_count: int,
summarizer
) -> List[Message]:
"""使用摘要进行压缩"""
# 首先尝试移除消息
compacted = self.compact_messages(messages, target_token_count)
# 如果还是太大,使用摘要压缩
if self.token_counter.count_messages_tokens(compacted) > target_token_count:
compacted = self._apply_summarization(compacted, summarizer, target_token_count)
return compacted
def _apply_summarization(self, messages: List[Message],
summarizer, target_tokens: int) -> List[Message]:
"""应用摘要压缩"""
result = []
for message in messages:
if message.role == "assistant" and len(message.get_text()) > 500:
# 摘要长响应
summary = summarizer(
message.get_text(),
max_length=int(len(message.get_text()) * 0.5)
)
summary_msg = Message.assistant([TextBlock(text=summary)])
result.append(summary_msg)
else:
result.append(message)
return result
# 自动压缩使用示例
compactor = AutoCompactor(compression_threshold=0.8)
budget_mgr = TokenBudgetManager()
async def agent_loop_with_auto_compaction(engine: QueryEngine,
state: AgentState):
"""智能体循环,带自动压缩"""
while True:
# 检查是否需要压缩
if compactor.should_compact(budget_mgr, state):
print(f"[Turn {state.current_turn}] Triggering auto-compaction...")
# 压缩到预算的 50%
target_tokens = budget_mgr.total_budget * 0.5
state.messages = compactor.compact_messages(
state.messages,
int(target_tokens)
)
print(f" Compacted to {budget_mgr._estimate_current_usage(state)} tokens")
# 继续推理
if not budget_mgr.can_continue_inference(state):
print(f"Cannot continue: insufficient token budget")
break
response = await engine.infer(state.messages)
state.add_message(response)
if not response.has_tool_calls():
break
```
### 3. 历史片段化
选择性地移除消息，保留最重要的部分：
```python
class HistorySnipper:
"""历史片段化:选择性保留消息"""
def snip_history(self, messages: List[Message],
target_count: int = 20) -> List[Message]:
"""
保留最重要的消息,进行片段化:
1. 保留最后 N 条消息(最近的对话)
2. 保留第一条消息(初始上下文)
3. 移除中间的消息
"""
if len(messages) <= target_count:
return messages
# 保留最后 target_count 条消息
recent_messages = messages[-target_count:]
# 保留第一条消息(通常是系统消息或初始用户输入)
if messages and messages[0] not in recent_messages:
result = [messages[0]] + recent_messages
else:
result = recent_messages
return result
def snip_by_importance(self,
messages: List[Message],
target_count: int = 20,
importance_scorer = None) -> List[Message]:
"""
基于重要性评分进行片段化
importance_scorer: 返回消息重要性分数(0-1)的函数
"""
if len(messages) <= target_count:
return messages
# 计算每条消息的重要性
scores = []
for i, msg in enumerate(messages):
if importance_scorer:
score = importance_scorer(msg, i, len(messages))
else:
score = self._default_importance_score(msg, i, len(messages))
scores.append((i, score, msg))
# 选择重要性最高的 target_count 条消息
selected = sorted(scores, key=lambda x: x[1], reverse=True)[:target_count]
# 按原始顺序重新排列
selected.sort(key=lambda x: x[0])
return [msg for _, _, msg in selected]
def _default_importance_score(self, msg: Message, index: int,
total_count: int) -> float:
"""默认的重要性评分"""
# 最后的消息最重要(权重 0.5)
recency_score = index / max(total_count - 1, 1) * 0.5
# 包含工具调用或长文本的消息较重要(权重 0.3)
if msg.role == "assistant" and msg.has_tool_calls():
content_score = 0.3
else:
content_score = (len(msg.get_text()) / 1000) * 0.15
# 第一条消息很重要(权重 0.2)
if index == 0:
initial_score = 0.2
else:
initial_score = 0
return recency_score + content_score + initial_score
```
## 4.6.3 Claude Code 的 200k 阈值警告
Claude Code 在构建消息时采用分层的令牌预算管理：
```python
class AdaptiveContextManager:
"""自适应上下文管理"""
def __init__(self, model_name: str = "claude-sonnet-4-5"):
self.model_name = model_name
self.total_budget = 200000
self.safety_margin = 10000
self.token_counter = TokenCounter()
def build_messages_with_budget(self, original_messages: List[Message],
tools: List[Dict]) -> List[Message]:
"""构建消息,考虑令牌预算"""
system_tokens = 500
tools_tokens = self.token_counter.count_tool_schema_tokens(tools)
reserved_output = 4000 # 为输出预留空间
available_for_messages = (
self.total_budget -
system_tokens -
tools_tokens -
reserved_output -
self.safety_margin
)
# 估计当前消息的令牌数
current_tokens = self.token_counter.count_messages_tokens(original_messages)
if current_tokens > available_for_messages:
# 超出预算,需要压缩
print(f"[Warning] Messages exceed budget: "
f"{current_tokens} > {available_for_messages}")
# 发出警告
self._emit_warning(current_tokens, available_for_messages)
# 进行压缩
return self._compress_messages_smart(
original_messages,
available_for_messages
)
return original_messages
def _emit_warning(self, current: int, available: int):
"""发出令牌预算警告"""
usage_percent = (current / self.total_budget) * 100
print(f"[Token Budget Warning] {usage_percent:.1f}% used "
f"({current}/{self.total_budget} tokens)")
def _compress_messages_smart(self, messages: List[Message],
target_tokens: int) -> List[Message]:
"""智能压缩消息"""
snipper = HistorySnipper()
compactor = AutoCompactor()
# 首先尝试片段化
snipped = snipper.snip_by_importance(messages, target_count=30)
if self.token_counter.count_messages_tokens(snipped) <= target_tokens:
return snipped
# 如果片段化还不够,进行压缩
return compactor.compact_messages(snipped, target_tokens)
```
## 4.6.4 OpenClaw 的 70% 上下文触发
OpenClaw 采用更激进的提前压缩策略：
```python
class OpenClawContextManager:
"""OpenClaw 风格的上下文管理"""
def __init__(self):
self.total_budget = 200000
self.trigger_threshold = 0.7 # 70% 触发压缩
def should_trigger_consolidation(self, current_tokens: int) -> bool:
"""检查是否应该触发记忆整合(压缩)"""
threshold = self.total_budget * self.trigger_threshold
return current_tokens > threshold
def consolidate_memory(self, session_id: str,
state: AgentState,
memory_store) -> AgentState:
"""
触发记忆整合:
1. 摘要当前会话中的重要事实
2. 更新长期记忆
3. 清理当前会话的历史
"""
# 1. 识别关键事实
key_facts = self._extract_key_facts(state.messages)
# 2. 保存到长期记忆
memory_store.add_facts(session_id, key_facts)
# 3. 清理消息历史
# 只保留最后几条消息和初始上下文
cleaned_messages = [
state.messages[0], # 保留初始消息
*state.messages[-5:] # 保留最后 5 条
]
# 4. 创建摘要消息
summary = self._create_summary_message(key_facts)
cleaned_messages.insert(1, summary)
state.messages = cleaned_messages
return state
def _extract_key_facts(self, messages: List[Message]) -> List[str]:
"""从消息中提取关键事实"""
facts = []
for msg in messages:
if msg.role == "assistant":
text = msg.get_text()
# 简化版本:提取包含特定关键词的句子
sentences = text.split('.')
for sentence in sentences:
if any(keyword in sentence for keyword in
['found', 'result', 'error', 'success']):
facts.append(sentence.strip())
return facts[:10] # 最多 10 个事实
def _create_summary_message(self, facts: List[str]) -> Message:
"""创建摘要消息"""
summary_text = "## Session Summary\n\n"
for i, fact in enumerate(facts, 1):
summary_text += f"{i}. {fact}\n"
return Message.assistant([TextBlock(text=summary_text)])
```
## 4.6.5 三级预算控制体系
生产级系统仅靠单次请求的令牌预算管理远远不够。成熟的 Harness 需要建立 **三级预算控制体系**，从单次调用到全局账期逐层约束：
| 控制层级 | 控制粒度 | 典型阈值 | 超限策略 |
| ----------------- | ---------------- | --------------------------- | ---------- |
| **Per-Request** | 单次 API 调用 | 4k-100k output tokens | 截断输出、降级模型 |
| **Per-Task** | 一个完整任务（可能包含多轮循环） | 50-200 次 API 调用 / 1M tokens | 强制总结、终止循环 |
| **Per-Day/Month** | 账期级全局预算 | $50/天、$1000/月 | 排队、降级、拒绝服务 |
```python
class ThreeTierBudgetController:
"""三级预算控制器"""
def __init__(self, config: dict):
# 第一级:单次请求
self.per_request_max_tokens = config.get("per_request_max_tokens", 4096)
# 第二级:任务级
self.per_task_max_calls = config.get("per_task_max_calls", 100)
self.per_task_max_tokens = config.get("per_task_max_tokens", 1_000_000)
# 第三级:账期级
self.daily_budget_usd = config.get("daily_budget_usd", 50.0)
self.monthly_budget_usd = config.get("monthly_budget_usd", 1000.0)
# 运行时计数器
self._task_call_count = 0
self._task_token_count = 0
self._daily_cost_usd = 0.0
def check_budget(self, estimated_tokens: int) -> dict:
"""在每次 API 调用前检查三级预算"""
# 第一级:请求级检查
request_tokens = min(estimated_tokens, self.per_request_max_tokens)
# 第二级:任务级检查
if self._task_call_count >= self.per_task_max_calls:
return {"allowed": False, "reason": "task_call_limit",
"action": "force_summarize_and_stop"}
if self._task_token_count + request_tokens > self.per_task_max_tokens:
return {"allowed": False, "reason": "task_token_limit",
"action": "force_summarize_and_stop"}
# 第三级:账期级检查
estimated_cost = self._estimate_cost(request_tokens)
if self._daily_cost_usd + estimated_cost > self.daily_budget_usd:
return {"allowed": False, "reason": "daily_budget_exceeded",
"action": "queue_or_downgrade"}
return {"allowed": True, "max_tokens": request_tokens}
def record_usage(self, input_tokens: int, output_tokens: int,
cost_usd: float):
"""记录实际使用量"""
self._task_call_count += 1
self._task_token_count += input_tokens + output_tokens
self._daily_cost_usd += cost_usd
def _estimate_cost(self, tokens: int) -> float:
"""估算成本(简化版)"""
return tokens * 3.0 / 1_000_000 # $3/M tokens 近似值
```
三级预算控制与前面介绍的多模型路由（详见 10.3.4 节）协同使用效果更佳：当账期预算紧张时，路由器可以自动将更多请求降级到低成本模型，在不中断服务的前提下控制支出。
## 4.6.6 本节小结
令牌预算管理是长时智能体任务的关键：
1. **前向估计** 在发送请求前预估令牌使用，防止超限
2. **自动压缩** 在令牌使用接近阈值时触发，保留最重要的信息
3. **历史片段化** 选择性保留消息，平衡信息完整性与令牌成本
4. **Claude Code 的 200k 阈值警告** 提前感知预算压力，主动调整策略
5. **OpenClaw 的 70% 触发** 更激进地进行记忆整合，维持较低的上下文使用
6. **三级预算控制** 从单次请求到账期级逐层约束，防止成本失控
这些策略相互配合，使得智能体能够在有限的上下文窗口内处理长时任务，同时将成本控制在可预测的范围内。
# 4.7 实战：MiniHarness 运行时实现
本节使用 Python 实现一个完整、可运行的 MiniHarness 运行时引擎。涵盖智能体循环、消息系统、事件处理、工具执行和状态管理等核心概念。
完整代码参见 lab/mini\_harness/runtime/。
## 4.7.1 设计决策：消息和状态模型
“消息”是MiniHarness的核心抽象。系统使用分块(block)结构组织内容，允许混合文本和工具调用。
关键设计点：
* **TextBlock**：“纯文本内容，支持多块拼接”
* **ToolUseBlock**：“智能体要求执行的工具调用，包含输入参数”
* **ToolResultBlock**：“工具执行结果，包括成功/失败状态”
* **Message**：“消息容器，role 标识发送者，content 是块数组”
* **AgentState**：“会话状态跟踪，维护消息历史和轮次计数”
参考实现片段(models.py)：
```python
@dataclass
class Message:
role: str
content: List[Any]
@classmethod
def user(cls, text: str) -> "Message":
return cls(role="user", content=[TextBlock(text=text)])
def has_tool_calls(self) -> bool:
return any(isinstance(block, ToolUseBlock)
for block in self.content)
def get_tool_calls(self) -> List[ToolUseBlock]:
return [b for b in self.content
if isinstance(b, ToolUseBlock)]
```
## 4.7.2 事件驱动架构
系统通过“异步事件流”向外部通知执行阶段。每个重要事件都包含 metadata，便于监控和日志记录。
事件类型：
* AGENT\_START, AGENT\_END：“会话生命周期”
* TURN\_START, TURN\_END：“每个智能体循环轮次”
* TEXT\_RESPONSE:“智能体生成的文本内容”
* TOOL\_EXECUTE, TOOL\_RESULT:“工具调用和结果”
* ERROR:“执行异常”
参考片段(events.py)：
```python
class EventType(Enum):
AGENT_START = "agent_start"
TURN_START = "turn_start"
TOOL_EXECUTE = "tool_execute"
# ... 更多类型
@dataclass
class Event:
event_type: EventType
timestamp: datetime = field(default_factory=datetime.utcnow)
metadata: Dict[str, Any] = field(default_factory=dict)
def to_json(self) -> str:
return json.dumps({
"event_type": self.event_type.value,
"timestamp": self.timestamp.isoformat(),
"metadata": self.metadata
})
```
## 4.7.3 智能体循环核心逻辑
运行时引擎(RuntimeEngine)实现了推理、工具执行、反馈融合的完整循环。
循环流程：
1. **初始化**：创建会话，输入用户提示
2. **推理轮次**（最多 max\_turns）
* 调用 \_infer() 获取智能体响应
* 如果包含工具调用，执行并收集结果
* 将结果添加到状态，继续下一轮
* 如果无工具调用，循环结束
3. **关闭**：生成 AGENT\_END 事件
关键设计：” **令牌预算管理** “（简化实现中为常量 4000），实际系统需计算累积令牌数并在超出时截断历史。
参考片段(engine.py)：
```python
async def run(self, user_input: str) -> AsyncIterator[Event]:
yield AgentStartEvent(metadata={"user_input": user_input})
session_id = f"sess_{uuid.uuid4().hex[:8]}"
state = AgentState(session_id=session_id)
state.add_message(Message.user(user_input))
for turn in range(self.max_turns):
yield TurnStartEvent(metadata={"turn_number": turn})
response = await self._infer(state)
if response is None:
yield ErrorEvent(metadata={"error": "Inference failed"})
break
state.add_message(response)
tool_calls = response.get_tool_calls()
if tool_calls:
for tool_use in tool_calls:
result = await self._execute_tool(tool_use)
state.add_message(Message.assistant([result]))
else:
break
yield TurnEndEvent(metadata={"turn_number": turn})
yield AgentEndEvent(metadata={"session_id": session_id})
```
## 4.7.4 工具执行和错误处理
\_execute\_tool() 方法从注册表中查找工具并调用。所有异常都被捕获并转换为 ToolResultBlock，确保循环不中断。
设计原则：“ **故障隔离** ”——单个工具失败不应导致整个会话失败。
```python
async def _execute_tool(self, tool_use: ToolUseBlock) -> ToolResultBlock:
tool = self.tool_registry.get(tool_use.name)
if not tool:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=f"Tool not found",
is_error=True,
error_type="ToolNotFoundError"
)
try:
result = await tool.call(tool_use.input)
# Tool.call() 返回 ToolResult 数据类（success/content/execution_time/error_type），
# 需要解包成 ToolResultBlock 期望的字符串 content + is_error 字段。
if hasattr(result, "success") and hasattr(result, "content"):
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(result.content),
is_error=not result.success,
error_type=getattr(result, "error_type", None),
)
# 向后兼容：若工具直接返回字符串，按成功处理
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(result),
is_error=False
)
except Exception as e:
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(e),
is_error=True,
error_type=type(e).__name__
)
```
## 4.7.5 主要特性总结
1. **消息块架构**：“灵活组合文本和工具”，支持混合内容
2. **异步事件流**：“非阻塞监控”，易于集成日志、指标收集
3. **会话状态隔离**：“独立的 AgentState”，支持并发运行多个会话
4. **工具注册表**：“动态工具加载”，可在运行时增删工具
5. **故障恢复**：“优雅降级”，工具失败不影响会话继续
## 4.7.6 扩展方向
生产系统需补充：
* **真实 LLM 集成**：“替换 \_infer() 的模拟实现”
* **上下文窗口管理**：“动态截断旧消息以保持在令牌预算内”
* **持久化存储**：“会话检查点、恢复机制”
* **丰富的工具库**：“文件操作、网络、数据库等”
* **高级特性**：“意图分类、工具选择器优化、多智能体协调”
## 4.7.7 本节小结
MiniHarness 展示了生产级智能体运行时的关键架构模式：
1. **分层设计**：“模型层、事件层、工具层、引擎层”
2. **异步驱动**：“Python asyncio 实现高效并发”
3. **事件中心**：“所有状态变化都生成可观察的事件”
4. **容错设计**：“隔离失败，保证系统稳定”
这些原则直接应用于 Claude Code 和 OpenClaw 等生产系统。参考 lab/mini\_harness/runtime/ 查看完整实现代码。
# 4.8 实时控制平面
在长时运行的Agent系统中，需要一套实时控制机制，使得外部系统（如UI、监控服务、用户干预系统）能够动态地暂停、恢复、修改和终止Agent执行，同时保持系统的正确性和一致性。本节介绍实时控制平面的架构、关键组件和实现模式。
**设计演示说明**：本节涵盖的详细控制平面实现（CheckpointManager、ActionStream、InterventionHandler 等）为设计参考示例。Lab 中的 miniharness 实现目前包含基础状态枚举（`AgentState.PAUSED`），完整的暂停/恢复、检查点、干预点等功能可根据本节设计参考进行扩展。
## 4.8.1 控制平面架构
实时控制平面将 Agent 系统分为 **数据平面** 和 **控制平面** 两部分：
* **数据平面**：Agent的主循环，负责执行任务、调用工具、生成结果
* **控制平面**：暴露的外部接口，接收暂停、恢复、干预等控制命令，管理Agent的执行状态
```mermaid
graph TB
subgraph ControlPlane["控制平面"]
UI["UI/Dashboard"]
Monitor["监控服务"]
API["Control API"]
StateStore["状态存储"]
end
subgraph DataPlane["数据平面"]
AgentLoop["Agent循环
Think-Act-Observe"]
ToolExec["工具执行"]
StateSync["状态同步"]
end
subgraph External["外部系统"]
User["用户"]
System["系统"]
end
UI -->|暂停/恢复| API
Monitor -->|查询| API
API -->|控制信号| AgentLoop
AgentLoop -->|上报状态| StateStore
StateStore -->|展示| UI
User -->|交互| UI
System -->|命令| API
```
控制平面通过以下机制与数据平面通信：
1. **控制队列**：Agent周期性检查控制队列中的指令
2. **状态检查点**：Agent在安全位置（如工具调用前后）暂停和检查控制信号
3. **异步回调**：控制命令通过回调机制通知Agent做出响应
4. **检查点存储**：暂停时保存Agent状态，便于后续恢复
## 4.8.2 暂停与恢复机制
### 状态序列化与检查点创建
Agent在运行过程中需要在特定的安全点创建检查点，以便暂停和恢复执行：
```python
# core/control_plane.py
from dataclasses import dataclass, field
from typing import Any, Dict, Optional, List
from enum import Enum
from datetime import datetime
import asyncio
import pickle
import uuid
class AgentState(Enum):
"""Agent执行状态"""
RUNNING = "running"
PAUSED = "paused"
RESUMING = "resuming"
COMPLETED = "completed"
FAILED = "failed"
TERMINATED = "terminated"
@dataclass
class Checkpoint:
"""检查点:包含Agent的完整可恢复状态"""
checkpoint_id: str
agent_state: Dict[str, Any] # Agent的内部状态快照
message_history: List[Dict[str, Any]] # 完整消息历史
tool_context: Dict[str, Any] # 当前工具调用上下文
execution_context: Dict[str, Any] # 任务执行上下文
timestamp: datetime
iteration: int
safe_point: str # 检查点所在的安全位置标识
metadata: Dict[str, Any] = field(default_factory=dict)
def serialize(self) -> bytes:
"""序列化检查点为二进制"""
return pickle.dumps(self)
@classmethod
def deserialize(cls, data: bytes) -> 'Checkpoint':
"""反序列化检查点"""
return pickle.loads(data)
class CheckpointManager:
"""检查点管理器"""
def __init__(self, storage_backend=None):
self.checkpoints: Dict[str, Checkpoint] = {}
self.storage_backend = storage_backend # 可选的持久化存储
self.latest_checkpoint_id: Optional[str] = None
async def create_checkpoint(
self,
agent: 'ControlledAgent',
safe_point: str
) -> Checkpoint:
"""在指定的安全点创建检查点"""
checkpoint = Checkpoint(
checkpoint_id=str(uuid.uuid4()),
agent_state=agent._serialize_state(),
message_history=agent.message_history.copy(),
tool_context=agent.tool_context.copy(),
execution_context=agent.execution_context.copy(),
timestamp=datetime.now(),
iteration=agent.iteration,
safe_point=safe_point,
metadata={
"task_id": agent.task_id,
"user_id": agent.user_id,
}
)
self.checkpoints[checkpoint.checkpoint_id] = checkpoint
self.latest_checkpoint_id = checkpoint.checkpoint_id
# 如果有持久化存储,异步保存
if self.storage_backend:
await self.storage_backend.save(checkpoint)
return checkpoint
async def restore_from_checkpoint(
self,
agent: 'ControlledAgent',
checkpoint_id: str
) -> bool:
"""从检查点恢复Agent状态"""
checkpoint = self.checkpoints.get(checkpoint_id)
if not checkpoint:
if self.storage_backend:
checkpoint = await self.storage_backend.load(checkpoint_id)
else:
return False
# 恢复Agent状态
agent._restore_state(checkpoint.agent_state)
agent.message_history = checkpoint.message_history.copy()
agent.tool_context = checkpoint.tool_context.copy()
agent.execution_context = checkpoint.execution_context.copy()
agent.iteration = checkpoint.iteration
return True
async def list_checkpoints(self) -> List[Dict[str, Any]]:
"""列出所有检查点摘要"""
return [
{
"id": cp.checkpoint_id,
"timestamp": cp.timestamp.isoformat(),
"iteration": cp.iteration,
"safe_point": cp.safe_point,
"task_id": cp.metadata.get("task_id")
}
for cp in self.checkpoints.values()
]
async def delete_checkpoint(self, checkpoint_id: str) -> bool:
"""删除检查点"""
if checkpoint_id in self.checkpoints:
del self.checkpoints[checkpoint_id]
if self.storage_backend:
await self.storage_backend.delete(checkpoint_id)
return True
return False
```
### 优雅暂停的实现
Agent在到达安全点时检查暂停信号，并创建检查点：
```python
# core/graceful_pause.py
class ControlledAgent:
"""带控制平面的Agent"""
def __init__(self, model_client, checkpoint_manager: CheckpointManager):
self.model_client = model_client
self.checkpoint_manager = checkpoint_manager
self.state = AgentState.RUNNING
self.pause_requested = False
self.iteration = 0
self.message_history = []
self.tool_context = {}
self.execution_context = {}
self.task_id = str(uuid.uuid4())
self.user_id = None
self.current_checkpoint = None
def _serialize_state(self) -> Dict[str, Any]:
"""序列化内部状态"""
return {
"state": self.state.value,
"iteration": self.iteration,
"task_id": self.task_id,
# 其他需要保存的状态
}
def _restore_state(self, state_dict: Dict[str, Any]):
"""恢复内部状态"""
self.state = AgentState(state_dict.get("state", "running"))
self.iteration = state_dict.get("iteration", 0)
self.task_id = state_dict.get("task_id", self.task_id)
async def _check_pause_at_safe_point(self):
"""在安全点检查暂停请求"""
if self.pause_requested and self.state == AgentState.RUNNING:
# 创建检查点
checkpoint = await self.checkpoint_manager.create_checkpoint(
self,
safe_point="tool_execution_boundary"
)
self.current_checkpoint = checkpoint
# 转换状态为已暂停
self.state = AgentState.PAUSED
print(f"Agent paused at iteration {self.iteration}, checkpoint: {checkpoint.checkpoint_id}")
return True
return False
async def request_pause(self) -> Dict[str, Any]:
"""请求暂停(从外部调用)"""
self.pause_requested = True
# 等待Agent到达安全点并暂停
while self.state != AgentState.PAUSED:
await asyncio.sleep(0.1)
return {
"status": "paused",
"checkpoint_id": self.current_checkpoint.checkpoint_id if self.current_checkpoint else None,
"iteration": self.iteration
}
async def resume(self, checkpoint_id: Optional[str] = None) -> Dict[str, Any]:
"""恢复执行"""
if self.state == AgentState.PAUSED:
if checkpoint_id:
# 从指定检查点恢复
success = await self.checkpoint_manager.restore_from_checkpoint(self, checkpoint_id)
if not success:
return {"status": "error", "message": "Checkpoint not found"}
# 清除暂停标记
self.pause_requested = False
self.state = AgentState.RESUMING
await asyncio.sleep(0.1) # 让主循环处理状态变化
return {"status": "resuming", "iteration": self.iteration}
else:
return {"status": "error", "message": f"Cannot resume from state {self.state.value}"}
```
## 4.8.3 实时行动流
Agent的每个动作（工具调用、决策、结果生成）都应该以流的形式实时传送到UI或日志系统，支持SSE（Server-Sent Events）和WebSocket模式：
```python
# core/action_streaming.py
from typing import AsyncGenerator, Callable
import json
class ActionStream:
"""Agent行动流"""
def __init__(self):
self.listeners: List[Callable] = []
self.history: List[Dict[str, Any]] = []
async def emit_action(
self,
action_type: str,
content: Dict[str, Any],
metadata: Dict[str, Any] = None
):
"""发出一个行动事件"""
event = {
"type": action_type,
"timestamp": datetime.now().isoformat(),
"content": content,
"metadata": metadata or {}
}
self.history.append(event)
# 通知所有监听者
for listener in self.listeners:
try:
if asyncio.iscoroutinefunction(listener):
await listener(event)
else:
listener(event)
except Exception as e:
print(f"Error notifying listener: {e}")
def subscribe(self, listener: Callable):
"""订阅行动事件"""
self.listeners.append(listener)
def unsubscribe(self, listener: Callable):
"""取消订阅"""
if listener in self.listeners:
self.listeners.remove(listener)
async def stream_sse(self) -> AsyncGenerator[str, None]:
"""以SSE格式流式发出事件"""
last_sent = 0
while True:
if len(self.history) > last_sent:
for event in self.history[last_sent:]:
yield f"data: {json.dumps(event)}\n\n"
last_sent = len(self.history)
await asyncio.sleep(0.1)
class AgentWithStreaming(ControlledAgent):
"""支持行动流的Agent"""
def __init__(self, model_client, checkpoint_manager: CheckpointManager):
super().__init__(model_client, checkpoint_manager)
self.action_stream = ActionStream()
async def _emit_thinking(self, reasoning: str):
"""发出思考事件"""
await self.action_stream.emit_action(
action_type="thinking",
content={"reasoning": reasoning},
metadata={"iteration": self.iteration}
)
async def _emit_tool_call(self, tool_name: str, tool_args: Dict[str, Any]):
"""发出工具调用事件"""
await self.action_stream.emit_action(
action_type="tool_call",
content={"tool": tool_name, "arguments": tool_args},
metadata={"iteration": self.iteration}
)
async def _emit_tool_result(self, tool_name: str, result: Any, duration_ms: float):
"""发出工具结果事件"""
await self.action_stream.emit_action(
action_type="tool_result",
content={"tool": tool_name, "result": str(result)},
metadata={"iteration": self.iteration, "duration_ms": duration_ms}
)
async def run(self) -> Any:
"""Agent主循环,支持行动流"""
while self.state == AgentState.RUNNING:
self.iteration += 1
# 安全点:检查暂停请求
if await self._check_pause_at_safe_point():
break
# LLM推理
reasoning = "Analyzing current task..."
await self._emit_thinking(reasoning)
# 工具调用
tool_name = "process_data"
tool_args = {"step": self.iteration}
await self._emit_tool_call(tool_name, tool_args)
# 工具执行(模拟)
import time
start = time.time()
result = f"Iteration {self.iteration} completed"
duration_ms = (time.time() - start) * 1000
await self._emit_tool_result(tool_name, result, duration_ms)
# 安全点:检查暂停
if await self._check_pause_at_safe_point():
break
# 模拟工作
await asyncio.sleep(0.2)
# 循环终止
if self.iteration >= 5:
self.state = AgentState.COMPLETED
await self.action_stream.emit_action(
action_type="completion",
content={"result": "Task completed"},
metadata={"total_iterations": self.iteration}
)
return {"status": self.state.value, "iterations": self.iteration}
```
## 4.8.4 干预点设计
干预点是Agent循环中允许外部系统注入控制的位置。设计良好的干预点确保不会破坏Agent的内部不变量：
```python
# core/intervention_points.py
from enum import Enum
class InterventionPoint(Enum):
"""干预点标识"""
BEFORE_LLM_CALL = "before_llm"
AFTER_LLM_CALL = "after_llm"
BEFORE_TOOL_CALL = "before_tool"
AFTER_TOOL_CALL = "after_tool"
AT_TASK_BOUNDARY = "task_boundary"
BEFORE_STATE_COMMIT = "before_commit"
class InterventionHandler:
"""干预点处理器"""
def __init__(self):
self.handlers: Dict[InterventionPoint, List[Callable]] = {
point: [] for point in InterventionPoint
}
def register_intervention(self, point: InterventionPoint, handler: Callable):
"""在干预点注册处理器"""
self.handlers[point].append(handler)
async def call_intervention(
self,
point: InterventionPoint,
context: Dict[str, Any]
) -> Dict[str, Any]:
"""调用干预点处理器"""
result = {"proceeded": True, "modifications": {}}
for handler in self.handlers[point]:
try:
handler_result = await handler(context) if asyncio.iscoroutinefunction(handler) else handler(context)
if handler_result and not handler_result.get("proceeded", True):
result["proceeded"] = False
break
if handler_result and "modifications" in handler_result:
result["modifications"].update(handler_result["modifications"])
except Exception as e:
print(f"Error in intervention handler: {e}")
return result
class AgentWithInterventions(AgentWithStreaming):
"""支持干预点的Agent"""
def __init__(self, model_client, checkpoint_manager: CheckpointManager):
super().__init__(model_client, checkpoint_manager)
self.intervention_handler = InterventionHandler()
async def run(self) -> Any:
"""Agent循环,支持干预点"""
while self.state == AgentState.RUNNING:
self.iteration += 1
# 干预点:工具调用前
context = {"iteration": self.iteration, "message_count": len(self.message_history)}
intervention = await self.intervention_handler.call_intervention(
InterventionPoint.BEFORE_TOOL_CALL,
context
)
if not intervention["proceeded"]:
print(f"Intervention blocked tool call at iteration {self.iteration}")
self.state = AgentState.FAILED
break
# 应用修改
if intervention["modifications"]:
self._apply_modifications(intervention["modifications"])
# 暂停检查
if await self._check_pause_at_safe_point():
break
# 工具调用
await self._emit_tool_call("process", {})
await self._emit_tool_result("process", "ok", 100.0)
# 干预点:工具调用后
intervention = await self.intervention_handler.call_intervention(
InterventionPoint.AFTER_TOOL_CALL,
{"iteration": self.iteration}
)
await asyncio.sleep(0.1)
if self.iteration >= 5:
self.state = AgentState.COMPLETED
return {"status": self.state.value, "iterations": self.iteration}
def _apply_modifications(self, modifications: Dict[str, Any]):
"""应用干预点的修改"""
if "system_override" in modifications:
print(f"System override applied: {modifications['system_override']}")
```
## 4.8.5 成本与安全控制
控制平面应管理资源消耗（令牌预算、API调用次数）和安全限制（超时、kill switch）：
```python
# core/cost_safety_control.py
from dataclasses import dataclass
@dataclass
class CostBudget:
"""成本预算"""
max_tokens: int
max_api_calls: int
max_duration_seconds: int
current_tokens: int = 0
current_api_calls: int = 0
class CostSafetyController:
"""成本与安全控制器"""
def __init__(self, budget: CostBudget):
self.budget = budget
self.start_time = datetime.now()
self.kill_switch_activated = False
def check_token_budget(self, tokens_used: int) -> bool:
"""检查令牌预算"""
self.budget.current_tokens += tokens_used
exceeded = self.budget.current_tokens > self.budget.max_tokens
if exceeded:
print(f"Token budget exceeded: {self.budget.current_tokens} > {self.budget.max_tokens}")
return not exceeded
def check_api_calls(self) -> bool:
"""检查API调用限制"""
self.budget.current_api_calls += 1
exceeded = self.budget.current_api_calls > self.budget.max_api_calls
if exceeded:
print(f"API call limit exceeded: {self.budget.current_api_calls}")
return not exceeded
def check_timeout(self) -> bool:
"""检查执行超时"""
elapsed = (datetime.now() - self.start_time).total_seconds()
exceeded = elapsed > self.budget.max_duration_seconds
if exceeded:
print(f"Timeout exceeded: {elapsed}s > {self.budget.max_duration_seconds}s")
return not exceeded
def activate_kill_switch(self, reason: str):
"""激活kill switch强制终止"""
self.kill_switch_activated = True
print(f"Kill switch activated: {reason}")
async def check_all_constraints(self) -> Dict[str, bool]:
"""检查所有约束"""
return {
"tokens_ok": self.budget.current_tokens <= self.budget.max_tokens,
"api_calls_ok": self.budget.current_api_calls <= self.budget.max_api_calls,
"timeout_ok": self.check_timeout(),
"kill_switch": not self.kill_switch_activated
}
def get_status(self) -> Dict[str, Any]:
"""获取当前状态"""
return {
"tokens": {
"used": self.budget.current_tokens,
"max": self.budget.max_tokens,
"remaining": max(0, self.budget.max_tokens - self.budget.current_tokens)
},
"api_calls": {
"used": self.budget.current_api_calls,
"max": self.budget.max_api_calls,
"remaining": max(0, self.budget.max_api_calls - self.budget.current_api_calls)
},
"duration": {
"elapsed": (datetime.now() - self.start_time).total_seconds(),
"max": self.budget.max_duration_seconds
},
"kill_switch": self.kill_switch_activated
}
class ControlledAgentWithSafety(AgentWithInterventions):
"""带成本与安全控制的Agent"""
def __init__(self, model_client, checkpoint_manager: CheckpointManager, budget: CostBudget):
super().__init__(model_client, checkpoint_manager)
self.cost_safety = CostSafetyController(budget)
async def run(self) -> Any:
"""Agent循环,集成成本与安全控制"""
while self.state == AgentState.RUNNING:
# 检查所有约束
constraints = await self.cost_safety.check_all_constraints()
if not all(constraints.values()):
print(f"Constraint violation: {constraints}")
self.state = AgentState.TERMINATED
break
self.iteration += 1
# 检查超时
if not self.cost_safety.check_timeout():
self.state = AgentState.TERMINATED
break
# 工具调用和资源计费
await self._emit_tool_call("expensive_operation", {})
tokens_used = 100
if not self.cost_safety.check_token_budget(tokens_used):
self.state = AgentState.TERMINATED
break
api_ok = self.cost_safety.check_api_calls()
if not api_ok:
self.state = AgentState.TERMINATED
break
await self._emit_tool_result("expensive_operation", "ok", 50.0)
if self.iteration >= 5:
self.state = AgentState.COMPLETED
await asyncio.sleep(0.1)
return {
"status": self.state.value,
"iterations": self.iteration,
"cost_report": self.cost_safety.get_status()
}
```
## 4.8.6 实战：完整的实时控制平面
以下是一个完整的示例，展示如何在实际Agent中使用控制平面：
```python
# examples/realtime_control_example.py
import asyncio
async def demo_realtime_control_plane():
"""演示实时控制平面"""
# 初始化管理器
checkpoint_manager = CheckpointManager()
budget = CostBudget(
max_tokens=5000,
max_api_calls=10,
max_duration_seconds=30
)
agent = ControlledAgentWithSafety(
model_client=None,
checkpoint_manager=checkpoint_manager,
budget=budget
)
# 订阅行动流
async def log_action(event):
print(f"[STREAM] {event['type']}: {event['content']}")
agent.action_stream.subscribe(log_action)
# 创建后台任务:动态控制
async def control_agent():
await asyncio.sleep(0.5) # 让Agent运行一会儿
# 请求暂停
print("\n=== Requesting pause ===")
result = await agent.request_pause()
print(f"Pause result: {result}")
# 查询检查点
checkpoints = await checkpoint_manager.list_checkpoints()
print(f"Available checkpoints: {checkpoints}")
await asyncio.sleep(0.5)
# 恢复执行
if checkpoints:
print("\n=== Resuming from checkpoint ===")
result = await agent.resume(checkpoints[0]["id"])
print(f"Resume result: {result}")
await asyncio.sleep(1)
# 注册干预点处理器
async def prevent_tool_calls_at_iteration_3(context):
if context["iteration"] >= 3:
return {"proceeded": False, "reason": "Too many iterations"}
return {"proceeded": True}
# 注意:这在Agent已启动后添加,在这个示例中不会立即生效
agent.intervention_handler.register_intervention(
InterventionPoint.BEFORE_TOOL_CALL,
prevent_tool_calls_at_iteration_3
)
# 并发运行Agent和控制任务
agent_task = asyncio.create_task(agent.run())
control_task = asyncio.create_task(control_agent())
results = await asyncio.gather(agent_task, control_task)
print("\n=== Final Report ===")
print(f"Agent result: {results[0]}")
print(f"Cost report:\n{json.dumps(results[0].get('cost_report', {}), indent=2)}")
print(f"Action history length: {len(agent.action_stream.history)}")
if __name__ == "__main__":
import json
asyncio.run(demo_realtime_control_plane())
```
## 4.8.7 总结
实时控制平面的关键组件：
| 组件 | 功能 | 实现机制 |
| ----- | -------------- | ------------------- |
| 检查点管理 | 保存/恢复Agent状态 | 序列化、存储后端 |
| 暂停/恢复 | 优雅暂停和状态恢复 | 安全检查点、状态锁 |
| 行动流 | 实时发送Agent行动 | 发布-订阅、SSE/WebSocket |
| 干预点 | 外部系统控制Agent | 回调注册、点间插入 |
| 成本控制 | 令牌与API调用预算 | 计数器、约束检查 |
| 安全控制 | 超时和kill switch | 计时器、强制终止 |
实时控制平面使得Agent系统能够响应动态的用户需求和外部约束，是生产级Harness的必要组件。
# 本章小结
本章深入讲解了Harness运行时引擎的设计与实现，从智能体循环的基本模式、消息状态管理、流式处理、错误恢复到漂移检测和令牌管理等关键主题。以下是核心要点的总结。
## 核心要点
### 运行时的本质
运行时引擎是智能体系统的执行核心，定义了系统如何在每一轮循环中协调推理、行动和观察。两个参考系统展现了不同的设计哲学：
* **Claude Code 的异步生成器**：基于 submitMessage() 异步生成器的事件驱动循环，支持实时流式响应和并发工具执行，适合交互式任务
* **OpenClaw 的线性流水线**：顺序执行 intake → context assembly → inference → tool execution → persistence，提供完整的可追踪性，适合自驱型长时任务
### 设计权衡
选择哪种模式取决于应用场景的需求：
| 考虑因素 | Claude Code 异步模式 | OpenClaw 线性模式 |
| ---- | ---------------- | ------------- |
| 可追踪性 | 中（需要日志） | 优（完整阶段化） |
| 响应延迟 | 低（流式响应） | 较高（同步执行） |
| 并发能力 | 高（并发工具执行） | 低（单会话单线程） |
| 调试难度 | 中等（异步调试复杂） | 容易（确定的执行序列） |
| 长时任务 | 中（需要主动管理） | 优（状态管理完善） |
### 智能体循环的终止条件
明确的终止条件防止无限循环或过度执行：
1. **工具调用耗尽**：最后一条消息不包含工具调用
2. **轮数限制**：通常 10-30 轮
3. **令牌预算耗尽**：无法继续推理
4. **显式停止信号**：用户取消或智能体发出停止标记
5. **目标达成**：自驱型智能体的目标检查
## 消息与状态管理的核心抉择
### 消息类型系统
完整的消息类型系统提供类型安全和可追踪性：
| 字段 | 类型 | 说明 |
| ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| role | `"user"` 或 `"assistant"` | 消息发送者角色 |
| content | array | 消息内容块数组，包含：
- TextBlock: 纯文本
- ToolUseBlock: 工具调用请求
- ToolResultBlock: 工具执行结果
- ThinkingBlock: 推理过程（可选）
|
### 状态管理模式
两种模式的权衡：
* **发布-订阅**：原地修改状态，通过事件通知订阅者，低开销但需要额外同步
* **不可变状态**：每次变化产生新对象，完整的历史链可追踪，但内存和性能开销大
## 流式处理的必要性
工具必须在流式响应期间执行，而非批处理，这决定了系统的关键性能特性：
**为什么**：
1. 用户可以立即看到首字节响应
2. 工具可以并发执行
3. 智能体可以基于工具结果立即进行下一轮推理
**事件流架构**：
```mermaid
sequenceDiagram
participant Agent as 智能体
participant Runtime as 运行时
participant Tool as 工具执行
Agent->>Runtime: agent_start
Runtime->>Runtime: turn_start
Runtime->>Agent: text_delta (*)
Runtime->>Runtime: tool_use_start
Runtime->>Runtime: tool_input_delta (*)
Runtime->>Runtime: tool_use_end
Note over Tool: async execute
Tool->>Runtime: tool_result
Runtime->>Runtime: turn_end
alt 继续
Runtime->>Agent: continue
else 结束
Runtime->>Agent: finish
end
```
## 错误处理的分层策略
| 错误类型 | 影响范围 | 处理策略 | 示例 |
| -------- | ---- | --------- | --------- |
| 工具执行错误 | 单个工具 | 重试或作为观察反馈 | 文件不存在 |
| API 调用错误 | 当前轮次 | 指数退避重试 | 速率限制、超时 |
| 输出解析错误 | 当前结果 | 参数验证、重新生成 | JSON 格式错误 |
| 上下文溢出 | 整个会话 | 自动压缩、历史管理 | 超过令牌限制 |
**OpenClaw 的“错误即观察”**：所有错误都被转换为 ToolResultBlock 反馈给 Agent，使其能够学习和调适。
## 长时任务的漂移检测与纠正
### 漂移的表现
* 目标遗忘：Agent 忘记了原始任务
* 目标替代：用中间目标替代主目标
* 范围蠕变：任务范围逐步扩大
* 方向漂移：推理偏离最优路径
### 检测方法
1. **启发式**：关键词匹配、重复行动检测
2. **语义**：向量相似度检测（与原始目标的语义距离）
3. **约束检查**：令牌数、工具调用数、执行时间约束
### 纠正策略
1. **强制反思**：定期插入反思步骤，要求智能体重新评估进度(OpenClaw)
2. **检查点恢复**：保存中间状态，漂移时回滚
3. **约束验证**：硬约束防止出界
## 令牌预算管理的实践
### 预算组成
令牌预算的详细分配方案如下所示：
| 预算项目 | 分配 | 说明 |
| --------- | ------------------ | ------ |
| **总预算** | **200,000 tokens** | - |
| 系统提示词 | \~500 | 系统级指令 |
| 消息历史 | \~50,000 | 上下文消息 |
| 工具 Schema | \~5,000 | 工具定义 |
| 用户输入 | \~2,000 | 当前查询 |
| 预留余额 | \~142,500 | **总计** |
| 推理预留 | 100,000 | 思考过程 |
| 实际可用 | \~42,500 | 可用输出空间 |
### 管理策略
1. **前向估计**：发送请求前预估令牌数，避免超限
2. **自动压缩**：80% 阈值触发压缩(Claude Code)或 70% 触发记忆整合(OpenClaw)
3. **历史片段化**：保留最重要的消息，丢弃中间的
4. **动态边界**：系统提示词与动态上下文的分离缓存(Claude Code)
## MiniHarness 实现的启示
通过从零实现一个完整的运行时，我们理解了：
1. **架构分层** 的重要性：模型层、事件层、工具层、运行时层的清晰划分
2. **异步编程** 的必要性：用 asyncio 实现高效的事件驱动循环
3. **可测试性**：每个组件都可以独立测试和扩展
4. **扩展性**：通过注册表、工具抽象、事件系统实现易于扩展
## 与其他部分的联系
运行时引擎是整个 Harness 系统的枢纽，与其他子系统的关系：
```mermaid
graph TB
subgraph "运行时引擎(智能体循环)"
ToolLayer["工具层
执行工具
管理工具"]
MemorySystem["记忆系统
上下文
组装"]
ModelIntegration["模型集成
推理调用
输出治理"]
ToolLayer -->|消息流转| CoreEngine["核心:消息流转
状态管理
事件驱动"]
MemorySystem -->|消息流转| CoreEngine
ModelIntegration -->|消息流转| CoreEngine
end
style ToolLayer fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style MemorySystem fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style ModelIntegration fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style CoreEngine fill:#f5e8f4,stroke:#a44a90,stroke-width:2px,color:#000000
```
## 学习路径建议
1. **入门**：理解 智能体循环的基本概念(Think-Act-Observe)
2. **进阶**：对比两种实现模式的权衡，选择适合的架构
3. **实践**：实现 MiniHarness 或扩展其功能（添加真实模型、记忆系统等）
4. **深化**：研究特定场景的优化（流式处理、漂移检测、令牌管理）
5. **生产**：在实际项目中应用这些原则和模式
## 关键术语速查
| 术语 | 定义 |
| ----- | ------------------ |
| 智能体循环 | 思考-行动-观察的重复过程 |
| 消息窗口 | 保留在上下文中的消息历史大小 |
| 令牌预算 | 单次推理允许的最大令牌数 |
| 漂移检测 | 识别智能体偏离目标 |
| 流式处理 | 响应和工具执行的实时交互 |
| 事件驱动 | 基于事件的异步编程模型 |
| 工具执行 | 运行智能体调用的外部工具或函数 |
| 上下文组装 | 将系统、历史、工具信息组合成推理输入 |
| 不可变状态 | 每次变化都产生新状态对象 |
| 发布-订阅 | 通过事件通知状态变化 |
## 延伸阅读建议
* 第五章（工具层）：工具的注册、发现、权限管理
* 第六章（记忆系统）：长期记忆对 智能体循环的支持
* 第七章（模型集成）：推理调用、输出治理、质量控制
* 第十章（生产部署）：运行时的可观测性、监控、扩展
## 实践练习
1. **扩展 MiniHarness**：添加文件读写工具、网络请求工具
2. **实现漂移检测**：在 MiniHarness 中添加简单的漂移检测机制
3. **令牌管理**：实现消息自动压缩（基于消息数或字符长度）
4. **对比实验**：实现线性流水线版本和异步生成器版本，对比性能
5. **真实集成**：将 MiniHarness 与真实的 LLM API（如 Claude）集成
## 实时控制平面
在长时运行的智能体系统中，控制平面提供了关键的运行时干预能力：
* **检查点管理**：在安全点序列化智能体完整状态，支持暂停后恢复执行
* **暂停与恢复**：优雅暂停机制，确保状态一致性
* **行动流**：以 SSE/WebSocket 实时传送智能体的每个动作
* **干预点**：允许外部系统在指定位置注入控制逻辑
* **成本与安全控制**：令牌预算、API 调用限制、超时和 kill switch
## 第四章完成
本章深入讲解了 Harness 运行时引擎的设计与实现，涵盖了智能体循环的核心模式、消息状态管理、流式处理、错误恢复、漂移检测、令牌管理和实时控制平面等关键主题。通过 MiniHarness 的实现，我们展示了这些概念如何落地成可运行的代码。
下一章将深入 **工具层** 的设计，研究工具的抽象、注册、执行、权限管理和动态加载。
# 第五章：工具层设计
## 章引言
工具(Tools)是智能体与外部世界交互的手段。每一个工具调用都是一次对外部系统的改造、查询或决策。设计良好的工具层决定了智能体系统的能力边界、安全性、可维护性和可扩展性。
如果说智能体循环是“如何思考和行动”，那么工具层就是“用什么工具去行动”。
## 工具层的三个核心问题
1. **工具抽象**：如何定义一个统一的工具接口，使得各种异构的外部能力（Bash、文件系统、网络请求、数据库、API）都能被智能体调用？
2. **工具执行**：如何安全地执行工具调用，处理超时、权限、错误，并向智能体反馈结果？
3. **工具发现**：如何让智能体知道存在哪些工具、如何使用？在静态工具列表和动态工具发现之间如何平衡？
## 两个参考系统的工具哲学
### Claude Code 的设计
* **24+内置工具**：深度集成，每个工具为特定场景优化
* **工具类型多样**：8个执行工具、3个网络工具、8个Agent工具、5+内置专用工具
* **Tool\ 泛型接口**：类型安全，支持进度报告
* **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["Skills(高级指令)
Markdown 格式定义
.skill 文件
可由智能体组合执行"]
B --> C["Tools(底层能力)
抽象接口
单一职责
由系统管理"]
C --> D["底层系统
bash/fs/network
实际能力实现"]
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\ | Tool Protocol | Async Protocol |
| 执行模式 | 并发 | 顺序 | 顺序（可扩展） |
| 错误处理 | 异常捕获 | 错误即观察 | 两者结合 |
| 权限管理 | check\_permissions() | 工具策略 | 基础实现 |
| 缓存 | FileStateCache | 会话记忆 | 简单缓存 |
| 发现机制 | 预定义 | 6级优先级 | 注册表 |
本章将深入这些设计细节，为你建立完整的工具系统设计能力。
# 5.1 工具抽象接口设计
工具抽象接口是工具系统的核心基础，需要在通用性、类型安全、可观测性和性能间取得平衡。本节介绍Claude Code的泛型设计、工具实现示例、注册中心机制，以及权限管理策略。
## 5.1.1 统一工具接口的设计目标
工具抽象接口的设计需要平衡以下目标：
1. **通用性**：支持各种异构工具（文件、网络、计算、数据库等）
2. **类型安全**：在编译时（或运行时）检查参数和返回值类型
3. **可观测性**：支持进度报告、事件发射、日志记录
4. **可扩展性**：易于添加新工具类型
5. **性能**：最小化开销，支持并发执行
6. **安全性**：权限检查、资源限制、错误隔离
## 5.1.2 Claude Code 的 Tool\ 泛型设计
Claude Code 采用泛型 Tool 接口，明确定义输入、输出和进度类型：
```python
"""
Claude Code 风格的工具接口
"""
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Generic, TypeVar, Optional, Dict, Any, List
import asyncio
# 类型变量
InputType = TypeVar('InputType')
OutputType = TypeVar('OutputType')
ProgressType = TypeVar('ProgressType')
@dataclass
class ToolProgress:
"""工具执行进度"""
step: int # 当前步骤号
total_steps: int # 总步骤数
current_status: str # 当前状态描述
estimated_time_remaining: Optional[float] = None # 剩余时间(秒)
def percentage(self) -> float:
"""进度百分比"""
return (self.step / self.total_steps * 100) if self.total_steps > 0 else 0
class Tool(ABC, Generic[InputType, OutputType]):
"""通用工具抽象"""
@abstractmethod
async def call(self, input_data: InputType) -> OutputType:
"""
执行工具
Args:
input_data: 工具输入,已验证和类型检查过
Returns:
工具执行结果
Raises:
ToolExecutionError: 工具执行失败
"""
pass
@abstractmethod
def name(self) -> str:
"""工具名称"""
pass
@abstractmethod
def description(self) -> str:
"""工具描述"""
pass
@abstractmethod
def input_schema(self) -> Dict[str, Any]:
"""输入的 JSON Schema"""
pass
def check_permissions(self, context: Any) -> bool:
"""
检查当前上下文是否有权限调用此工具
Args:
context: 执行上下文(包含用户、会话信息等)
Returns:
是否有权限
"""
return True # 默认允许
async def get_progress(self) -> Optional[ToolProgress]:
"""
获取工具执行进度
Returns:
进度对象,如果工具不支持进度报告则返回 None
"""
return None
def supports_streaming(self) -> bool:
"""工具是否支持流式输出"""
return False
async def stream_output(self, input_data: InputType):
"""
流式输出(可选)
Yields:
OutputType: 逐个产生的输出
"""
if not self.supports_streaming():
output = await self.call(input_data)
yield output
```
> ⚠️ **类型系统说明**：上述 `Tool[InputType, OutputType]` 的泛型注解为设计理想。在 Python 运行时，由于动态类型特性，实际实现常使用 `Dict[str,Any]` 承载参数和返回值。这是 Python 动态类型系统与静态类型检查间的权衡——静态分析可以验证泛型约束，但运行时仍需灵活处理异构数据。关于完整的类型安全实现，请参考第 5.3 节和附录 D (MiniHarness 类型体系)。
本节展示了工具的核心设计模式与流程。为了更好地理解如何将这些模式应用于实践，下面我们通过具体的实现示例来演示工具的常见用法。
## 5.1.3 工具实现示例
### 1. 简单工具：Bash 执行
一个简单的Bash命令执行工具的实现如下：
```python
@dataclass
class BashInput:
command: str
timeout: int = 30
cwd: Optional[str] = None
@dataclass
class BashOutput:
stdout: str
stderr: str
returncode: int
execution_time: float
class BashTool(Tool[BashInput, BashOutput]):
"""Bash 命令执行工具"""
async def call(self, input_data: BashInput) -> BashOutput:
"""执行 bash 命令"""
import subprocess
import time
start_time = time.time()
try:
result = subprocess.run(
input_data.command,
shell=True,
capture_output=True,
timeout=input_data.timeout,
text=True,
cwd=input_data.cwd
)
return BashOutput(
stdout=result.stdout,
stderr=result.stderr,
returncode=result.returncode,
execution_time=time.time() - start_time
)
except subprocess.TimeoutExpired:
raise ToolExecutionError(
f"Bash command timeout after {input_data.timeout}s"
)
except Exception as e:
raise ToolExecutionError(f"Bash execution failed: {str(e)}")
def name(self) -> str:
return "bash_exec"
def description(self) -> str:
return "Execute bash commands on the system"
def input_schema(self) -> Dict[str, Any]:
return {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "The bash command to execute"
},
"timeout": {
"type": "integer",
"description": "Command timeout in seconds",
"default": 30
},
"cwd": {
"type": "string",
"description": "Current working directory"
}
},
"required": ["command"]
}
def check_permissions(self, context: Any) -> bool:
"""Bash 工具需要特殊权限"""
if hasattr(context, 'is_admin'):
return context.is_admin
return False
```
### 2. 支持进度报告的工具：文件复制
一个支持进度报告的文件复制工具，展示如何在长时间运行的操作中提供实时反馈：
```python
@dataclass
class FileCopyInput:
source: str
destination: str
overwrite: bool = False
@dataclass
class FileCopyOutput:
success: bool
bytes_copied: int
destination: str
class FileCopyTool(Tool[FileCopyInput, FileCopyOutput]):
"""文件复制工具,支持进度报告"""
def __init__(self):
self._current_progress = None
async def call(self, input_data: FileCopyInput) -> FileCopyOutput:
"""复制文件"""
import shutil
import os
# 检查源文件是否存在
if not os.path.exists(input_data.source):
raise ToolExecutionError(f"Source file not found: {input_data.source}")
# 检查目标是否已存在
if os.path.exists(input_data.destination) and not input_data.overwrite:
raise ToolExecutionError(
f"Destination already exists: {input_data.destination}"
)
# 获取文件大小用于进度报告
file_size = os.path.getsize(input_data.source)
chunk_size = 1024 * 1024 # 1MB chunks
bytes_copied = 0
# 自定义复制逻辑以支持进度报告
with open(input_data.source, 'rb') as src, \
open(input_data.destination, 'wb') as dst:
while True:
chunk = src.read(chunk_size)
if not chunk:
break
dst.write(chunk)
bytes_copied += len(chunk)
# 更新进度
self._current_progress = ToolProgress(
step=bytes_copied,
total_steps=file_size,
current_status=f"Copying {bytes_copied}/{file_size} bytes"
)
return FileCopyOutput(
success=True,
bytes_copied=bytes_copied,
destination=input_data.destination
)
async def get_progress(self) -> Optional[ToolProgress]:
"""获取进度"""
return self._current_progress
def name(self) -> str:
return "file_copy"
def description(self) -> str:
return "Copy files with progress reporting"
def input_schema(self) -> Dict[str, Any]:
return {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "Source file path"
},
"destination": {
"type": "string",
"description": "Destination file path"
},
"overwrite": {
"type": "boolean",
"description": "Whether to overwrite existing file",
"default": False
}
},
"required": ["source", "destination"]
}
```
### 3. 流式输出工具：数据库查询
一个支持流式输出的数据库查询工具，展示如何处理大结果集：
> 💡 **类型参数说明**：以下示例中 `Tool` 的类型参数为概念占位符。运行时实现使用 `Dict[str,Any]` 承载动态数据。如需真正的静态类型约束，可改用 `Pydantic BaseModel` 或 `TypedDict`（见附录 D MiniHarness 实现）。
```python
from dataclasses import dataclass
from typing import Dict, Any
import asyncio
@dataclass
class DatabaseQueryInput:
query: str
limit: int = 1000
@dataclass
class DatabaseQueryRow:
columns: Dict[str, Any]
class DatabaseQueryTool(Tool[DatabaseQueryInput, DatabaseQueryRow]):
"""数据库查询工具,支持流式输出"""
def __init__(self, connection_string: str):
self.connection_string = connection_string
async def call(self, input_data: DatabaseQueryInput) -> str:
"""执行查询并返回结果"""
# 这个实现中,我们只返回所有结果的摘要
# 实际使用应该使用流式输出
all_rows = []
async for row in self.stream_output(input_data):
all_rows.append(row)
return f"Query returned {len(all_rows)} rows"
async def stream_output(self, input_data: DatabaseQueryInput):
"""流式输出查询结果"""
# 在实际实现中,这里会连接到真实的数据库
# 示例:连接到 PostgreSQL、MySQL 等
# 模拟流式输出
for i in range(min(input_data.limit, 10)):
yield DatabaseQueryRow(
columns={
"id": i,
"name": f"Row {i}",
"value": i * 100
}
)
await asyncio.sleep(0.1) # 模拟网络延迟
def supports_streaming(self) -> bool:
return True
def name(self) -> str:
return "database_query"
def description(self) -> str:
return "Query database with streaming results"
def input_schema(self) -> Dict[str, Any]:
return {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "SQL query to execute"
},
"limit": {
"type": "integer",
"description": "Maximum number of rows to return",
"default": 1000
}
},
"required": ["query"]
}
```
## 5.1.4 buildTool() 工厂函数
Claude Code 使用工厂函数动态构造工具，支持参数化和延迟初始化：
```python
def build_tool(tool_spec: Dict[str, Any]) -> Tool:
"""
工厂函数:根据规范构造工具
Args:
tool_spec: 工具规范
{
"type": "bash" | "file" | "network" | ...,
"name": "tool_name",
"config": {...} # 工具特定的配置
}
Returns:
构造的工具实例
"""
tool_type = tool_spec.get("type")
config = tool_spec.get("config", {})
if tool_type == "bash":
return BashTool()
elif tool_type == "file_copy":
return FileCopyTool()
elif tool_type == "database_query":
return DatabaseQueryTool(
connection_string=config.get("connection_string")
)
elif tool_type == "custom":
# 动态导入和加载自定义工具
module_path = config.get("module")
class_name = config.get("class")
# 使用 importlib 动态加载
import importlib
module = importlib.import_module(module_path)
tool_class = getattr(module, class_name)
return tool_class(**config.get("args", {}))
else:
raise ValueError(f"Unknown tool type: {tool_type}")
```
## 5.1.5 工具注册中心
工具注册中心是所有工具的中枢，负责工具的注册、发现和管理。下面的流程图展示了工具的注册、发现和查询的完整流程：
```mermaid
graph TD
A["新工具"] -->|buildTool| B["工具实例"]
B -->|register| C["工具注册中心"]
C -->|缓存Schema| D["Schema 缓存"]
E["Agent查询"] -->|find_tool_by_name| C
C -->|查询缓存| D
D -->|返回Schema| F["工具Schema"]
C -->|返回工具| G["工具实例"]
F -->|提供给Agent| H["决策使用"]
G -->|供Agent调用| H
style A fill:#e1f5ff
style C fill:#fff3e0
style D fill:#f3e5f5
style H fill:#e8f5e9
```
图 5-1：工具注册与发现流程
```python
class ToolRegistry:
"""工具注册中心,管理所有可用工具"""
def __init__(self):
self.tools: Dict[str, Tool] = {}
self.tool_cache: Dict[str, Dict[str, Any]] = {} # Schema 缓存
def register(self, tool: Tool):
"""注册工具"""
name = tool.name()
self.tools[name] = tool
# 缓存工具的 Schema
self.tool_cache[name] = {
"name": name,
"description": tool.description(),
"input_schema": tool.input_schema()
}
print(f"Tool registered: {name}")
def get(self, name: str) -> Optional[Tool]:
"""获取工具"""
return self.tools.get(name)
def list_tools(self) -> List[Dict[str, Any]]:
"""列出所有工具的 Schema"""
return list(self.tool_cache.values())
def get_tool_schema(self, name: str) -> Optional[Dict[str, Any]]:
"""获取单个工具的 Schema"""
return self.tool_cache.get(name)
def tool_exists(self, name: str) -> bool:
"""检查工具是否存在"""
return name in self.tools
def unregister(self, name: str):
"""注销工具"""
if name in self.tools:
del self.tools[name]
del self.tool_cache[name]
print(f"Tool unregistered: {name}")
# 使用示例
registry = ToolRegistry()
# 注册内置工具
registry.register(BashTool())
registry.register(FileCopyTool())
registry.register(DatabaseQueryTool("postgresql://localhost/mydb"))
# 列出所有工具
for tool_schema in registry.list_tools():
print(f"- {tool_schema['name']}: {tool_schema['description']}")
# 获取特定工具
bash_tool = registry.get("bash_exec")
if bash_tool:
print(f"Found tool: {bash_tool.name()}")
```
## 5.1.6 OpenClaw 的工具策略模型
OpenClaw 支持更细粒度的权限管理：
```python
class ToolStrategy(Enum):
"""工具使用策略"""
ALLOW = "allow" # 允许使用
DENY = "deny" # 禁止使用
REQUIRE_APPROVAL = "require_approval" # 需要用户批准
class ToolPolicy:
"""工具策略:定义哪些智能体可以使用哪些工具"""
def __init__(self):
self.policies: Dict[str, Dict[str, ToolStrategy]] = {}
# policies[agent_id][tool_name] = strategy
def set_policy(self, agent_id: str, tool_name: str,
strategy: ToolStrategy):
"""设置工具策略"""
if agent_id not in self.policies:
self.policies[agent_id] = {}
self.policies[agent_id][tool_name] = strategy
def can_use_tool(self, agent_id: str, tool_name: str) -> bool:
"""检查智能体是否可以使用工具"""
if agent_id not in self.policies:
return True # 默认允许
strategy = self.policies[agent_id].get(
tool_name,
ToolStrategy.ALLOW
)
return strategy != ToolStrategy.DENY
def requires_approval(self, agent_id: str, tool_name: str) -> bool:
"""检查是否需要审批"""
if agent_id not in self.policies:
return False
strategy = self.policies[agent_id].get(tool_name)
return strategy == ToolStrategy.REQUIRE_APPROVAL
```
## 5.1.7 本节小结
工具抽象接口的设计决定了整个工具系统的质量和可维护性：
1. **Claude Code 的 Tool\ 泛型设计** 提供了强类型检查，但需要 Python 的高级类型系统支持
2. **工具工厂函数** 支持动态工具构造和参数化配置
3. **工具注册中心** 管理工具的生命周期和 Schema 缓存
4. **权限检查** 在工具调用前进行，可以是简单的 boolean 也可以是复杂的策略模型
5. **OpenClaw 的工具策略模型** 提供更细粒度的权限管理，支持不同智能体的不同权限
好的工具抽象应该既通用又灵活，既简单又强大。在实践中，需要根据具体场景选择合适的抽象级别。
# 5.2 工具执行流水线
本节介绍工具从被调用到返回结果的完整执行过程，包括6个关键阶段、流水线的实现细节、进度报告机制和并发执行策略，并通过实例代码展示如何构建一个可靠的工具执行系统。
## 5.2.1 执行流水线的完整过程
工具从被调用到返回结果的完整流程可以分为以下6个阶段：
```mermaid
graph LR
A["工具调用请求"] -->|解析| B["1. 查找工具"]
B -->|成功| C["2. 检查权限"]
C -->|允许| D["3. 验证输入"]
D -->|有效| E["4. 执行工具"]
E -->|完成| F["5. 处理结果"]
F -->|转换| G["6. 持久化结果"]
G -->|保存| H["工具结果"]
B -->|错误| I["错误处理器"]
C -->|拒绝| I
D -->|无效| I
E -->|超时| I
F -->|错误| I
I -->|创建错误结果| H
style B fill:#bbdefb
style C fill:#c8e6c9
style D fill:#fff9c4
style E fill:#ffccbc
style F fill:#d1c4e9
style G fill:#b2dfdb
style H fill:#f8bbd0
```
图 5-2：工具执行流水线的6个阶段
## 5.2.2 完整的执行流水线实现
工具执行流水线的实现可以分为四个主要部分：初始化和主流程、验证阶段、执行和结果处理、以及缓存管理。
### 第一部分：流水线初始化与主流程
首先定义执行流水线的主体和6个阶段的总体流程：
```python
"""工具执行流水线"""
from dataclasses import dataclass
from typing import Optional, Dict, Any, Callable, Tuple
from anthropic.types import ToolUseBlock, ToolResultBlock
import asyncio
import time
import json
class ExecutionPipeline:
"""工具执行流水线"""
def __init__(self,
tool_registry: ToolRegistry,
max_result_size: int = 1024 * 1024,
default_timeout: int = 30):
self.tool_registry = tool_registry
self.max_result_size = max_result_size
self.default_timeout = default_timeout
self.execution_history = []
self.result_cache = {}
async def execute(self,
tool_use: ToolUseBlock,
context: Any,
progress_callback: Optional[Callable] = None) -> ToolResultBlock:
"""执行工具的完整流水线"""
execution_record = {
"tool_use_id": tool_use.id,
"tool_name": tool_use.name,
"start_time": time.time(),
"stages": {}
}
try:
# 阶段1:工具发现
tool, error = await self._find_tool(tool_use.name, execution_record)
if error:
return self._create_error_result(tool_use, error)
# 阶段2:权限检查
is_allowed, error = await self._check_permissions(
tool, context, execution_record
)
if not is_allowed:
return self._create_error_result(tool_use, error)
# 阶段3:输入验证
is_valid, error = await self._validate_input(
tool, tool_use.input, execution_record
)
if not is_valid:
return self._create_error_result(tool_use, error)
# 阶段4:工具执行
result, error = await self._execute_tool(
tool, tool_use.input, execution_record, progress_callback
)
if error:
return self._create_error_result(tool_use, error)
# 阶段5:结果处理
processed_result, error = await self._process_result(
result, execution_record
)
if error:
return self._create_error_result(tool_use, error)
# 阶段6:持久化
await self._persist_result(
tool_use.id, processed_result, execution_record
)
self.execution_history.append(execution_record)
return ToolResultBlock(
tool_use_id=tool_use.id,
content=str(processed_result),
is_error=False
)
except Exception as e:
execution_record["error"] = str(e)
self.execution_history.append(execution_record)
return self._create_error_result(tool_use, str(e))
```
**设计说明**：主流程采用“早期返回”(Early Return)模式。任何阶段失败都立即返回错误，避免继续执行。这提高了效率并简化了错误处理。
### 第二部分：验证阶段（工具发现、权限检查、输入验证）
这部分处理执行前的三个验证阶段：
```python
async def _find_tool(self, tool_name: str,
execution_record: Dict) -> Tuple[Optional[Tool], Optional[str]]:
"""阶段1:工具发现"""
start = time.time()
tool = self.tool_registry.get(tool_name)
execution_record["stages"]["find_tool"] = {
"duration": time.time() - start,
"found": tool is not None
}
if not tool:
return None, f"Tool '{tool_name}' not found"
return tool, None
async def _check_permissions(self, tool: Tool, context: Any,
execution_record: Dict) -> Tuple[bool, Optional[str]]:
"""阶段2:权限检查"""
start = time.time()
try:
has_permission = tool.check_permissions(context)
execution_record["stages"]["check_permissions"] = {
"duration": time.time() - start,
"result": has_permission
}
if not has_permission:
return False, f"Permission denied for tool '{tool.name()}'"
return True, None
except Exception as e:
return False, f"Permission check error: {str(e)}"
async def _validate_input(self, tool: Tool, input_data: Dict[str, Any],
execution_record: Dict) -> Tuple[bool, Optional[str]]:
"""阶段3:输入验证"""
start = time.time()
schema = tool.input_schema()
errors = []
required = schema.get("required", [])
for field in required:
if field not in input_data:
errors.append(f"Missing required field: {field}")
properties = schema.get("properties", {})
for field_name, field_value in input_data.items():
if field_name not in properties:
errors.append(f"Unknown field: {field_name}")
continue
field_schema = properties[field_name]
if not self._check_type(field_value, field_schema):
expected_type = field_schema.get("type", "unknown")
errors.append(
f"Field '{field_name}' validation failed: "
f"expected {expected_type}"
)
execution_record["stages"]["validate_input"] = {
"duration": time.time() - start,
"valid": len(errors) == 0,
"errors": errors
}
if errors:
return False, "; ".join(errors)
return True, None
def _check_type(self, value: Any, schema: Dict[str, Any]) -> bool:
"""基于JSON Schema的类型验证"""
import jsonschema
try:
jsonschema.validate(value, schema)
return True
except jsonschema.ValidationError:
return False
```
**设计说明**：验证阶段按顺序执行，逐步变严格。工具发现最快，然后是权限检查，最后是复杂的输入验证。这样可以快速拒绝无效请求。
### 第三部分：执行和结果处理（工具执行、结果处理、持久化）
这部分处理核心的执行逻辑和结果的后处理：
```python
async def _execute_tool(self,
tool: Tool,
input_data: Dict[str, Any],
execution_record: Dict,
progress_callback: Optional[Callable] = None
) -> Tuple[Any, Optional[str]]:
"""阶段4:工具执行(带超时控制)"""
start = time.time()
try:
result = await asyncio.wait_for(
tool.call(input_data),
timeout=self.default_timeout
)
execution_record["stages"]["execute_tool"] = {
"duration": time.time() - start,
"success": True
}
return result, None
except asyncio.TimeoutError:
error = f"Tool execution timeout ({self.default_timeout}s)"
execution_record["stages"]["execute_tool"] = {
"duration": time.time() - start,
"success": False,
"error": "timeout"
}
return None, error
except Exception as e:
execution_record["stages"]["execute_tool"] = {
"duration": time.time() - start,
"success": False,
"error": type(e).__name__
}
return None, f"Tool execution error: {str(e)}"
async def _process_result(self, result: Any,
execution_record: Dict) -> Tuple[str, Optional[str]]:
"""阶段5:结果处理(序列化和截断)"""
start = time.time()
try:
if isinstance(result, str):
result_str = result
elif isinstance(result, (dict, list)):
result_str = json.dumps(result, indent=2)
else:
result_str = str(result)
if len(result_str) > self.max_result_size:
original_size = len(result_str)
result_str = result_str[:self.max_result_size]
result_str += f"\n... [Output truncated from {original_size} bytes]"
execution_record["stages"]["process_result"] = {
"duration": time.time() - start,
"truncated": True,
"original_size": original_size,
}
else:
execution_record["stages"]["process_result"] = {
"duration": time.time() - start,
"truncated": False,
"size": len(result_str)
}
return result_str, None
except Exception as e:
return None, f"Result processing error: {str(e)}"
async def _persist_result(self, tool_use_id: str, result: str,
execution_record: Dict):
"""阶段6:持久化(缓存)"""
start = time.time()
self.result_cache[tool_use_id] = {
"content": result,
"timestamp": time.time()
}
execution_record["stages"]["persist_result"] = {
"duration": time.time() - start,
"cached": True
}
def _create_error_result(self, tool_use: ToolUseBlock,
error: str) -> ToolResultBlock:
"""创建错误结果"""
return ToolResultBlock(
tool_use_id=tool_use.id,
content=error,
is_error=True,
error_type="ExecutionError"
)
```
**设计说明**：`_execute_tool` 使用 `asyncio.wait_for` 实现超时控制，防止卡顿。`_process_result` 对大结果进行截断，确保不超过最大大小限制。这两个措施都是保护系统稳定性的关键。
### 第四部分：执行历史和缓存管理
最后是查询执行历史和清理缓存的工具方法：
```python
def get_execution_history(self, tool_use_id: Optional[str] = None):
"""获取执行历史"""
if tool_use_id:
return [r for r in self.execution_history
if r["tool_use_id"] == tool_use_id]
return self.execution_history
def clear_cache(self, max_age: int = 3600):
"""清理缓存(删除超过max_age秒的项)"""
now = time.time()
to_delete = [
key for key, value in self.result_cache.items()
if now - value["timestamp"] > max_age
]
for key in to_delete:
del self.result_cache[key]
return len(to_delete)
```
## 5.2.3 进度事件流
支持长时间运行的工具的进度报告：
```python
from typing import Optional, Dict
import asyncio
import time
class ProgressMonitor:
"""进度监控器"""
def __init__(self, tool_use_id: str):
self.tool_use_id = tool_use_id
self.progress_events = []
def report_progress(self, step: int, total_steps: int,
status: str, estimated_time_remaining: Optional[float] = None):
"""报告进度"""
event = {
"tool_use_id": self.tool_use_id,
"timestamp": time.time(),
"step": step,
"total_steps": total_steps,
"percentage": (step / total_steps * 100) if total_steps > 0 else 0,
"status": status,
"estimated_time_remaining": estimated_time_remaining
}
self.progress_events.append(event)
return event
def get_current_progress(self) -> Optional[Dict]:
"""获取当前进度"""
return self.progress_events[-1] if self.progress_events else None
# 在工具执行中使用
async def long_running_tool_call(progress_monitor: ProgressMonitor):
"""长时间运行的工具调用示例"""
total_items = 1000
for i in range(total_items):
# 执行工作
await asyncio.sleep(0.01) # 模拟工作
# 报告进度
if i % 100 == 0:
progress_monitor.report_progress(
step=i,
total_steps=total_items,
status=f"Processing item {i}/{total_items}",
estimated_time_remaining=(total_items - i) * 0.01
)
return f"Processed {total_items} items"
```
## 5.2.4 并发工具执行
具体实现如下：
```python
from typing import List, Dict, Any
import asyncio
class StreamingToolExecutor:
"""并发工具执行器"""
def __init__(self, pipeline: ExecutionPipeline,
max_concurrent: int = 5):
self.pipeline = pipeline
self.max_concurrent = max_concurrent
async def execute_tools(self,
tool_uses: List[ToolUseBlock],
context: Any) -> Dict[str, ToolResultBlock]:
"""
并发执行多个工具
Args:
tool_uses: 工具调用列表
context: 执行上下文
Returns:
{tool_use_id: tool_result_block}
"""
semaphore = asyncio.Semaphore(self.max_concurrent)
async def execute_with_semaphore(tool_use):
async with semaphore:
return tool_use.id, await self.pipeline.execute(
tool_use, context
)
results = await asyncio.gather(
*[execute_with_semaphore(tu) for tu in tool_uses],
return_exceptions=True
)
# 组织结果
result_dict = {}
for tool_use_id, result in results:
if isinstance(result, Exception):
result_dict[tool_use_id] = ToolResultBlock(
tool_use_id=tool_use_id,
content=str(result),
is_error=True,
error_type=type(result).__name__
)
else:
result_dict[tool_use_id] = result
return result_dict
```
## 5.2.5 本节小结
工具执行流水线的设计决定了系统的可靠性和性能：
1. **6 个执行阶段** 清晰分离，每个阶段有明确的职责和错误处理
2. **权限检查** 在执行前进行，防止未授权的操作
3. **输入验证** 基于 JSON Schema，确保工具收到有效参数
4. **超时控制** 防止工具阻塞整个系统
5. **结果处理** 包括序列化、截断、缓存，处理大结果的问题
6. **执行历史记录** 支持审计和调试
7. **并发执行** 和 **进度报告** 支持长时间运行的工具
# 5.3 工具类型体系
本节阐述工具的分类标准、能力等级划分、访问控制策略、扩展模式和能力描述，说明如何设计一个既清晰易用又灵活可扩展的工具体系。
## 5.3.1 工具分类
按功能和特点，Agent 系统的工具可分为以下几类：
### 1. 执行工具
在本地系统执行代码或命令的工具。
```python
class BashTool(Tool):
"""执行 bash 命令"""
def name(self) -> str: return "bash_exec"
class PythonTool(Tool):
"""执行 Python 代码"""
def name(self) -> str: return "python_exec"
class FileReadTool(Tool):
"""读取文件内容"""
def name(self) -> str: return "file_read"
class FileWriteTool(Tool):
"""写入文件"""
def name(self) -> str: return "file_write"
class FileListTool(Tool):
"""列出目录内容"""
def name(self) -> str: return "file_list"
```
**特点**：
* 直接影响本地系统状态
* 需要严格的权限控制
* 可能长时间运行
* 需要超时保护
### 2. 网络工具
通过网络访问远程资源的工具。
```python
class HTTPTool(Tool):
"""发送 HTTP 请求"""
def name(self) -> str: return "http_request"
class WebSearchTool(Tool):
"""网络搜索"""
def name(self) -> str: return "web_search"
class APIDelegationTool(Tool):
"""调用第三方 API"""
def name(self) -> str: return "api_call"
```
**特点**：
* 依赖网络连接
* 可能有速率限制
* 需要处理超时和重试
* 可能涉及认证令牌管理
### 3. 智能体工具
让智能体调用其他智能体的工具。
```python
class SubAgentTool(Tool):
"""创建和委托子任务给另一个 Agent"""
def name(self) -> str: return "delegate_to_agent"
class ParallelAgentsTool(Tool):
"""并行执行多个 Agent"""
def name(self) -> str: return "parallel_agents"
```
**特点**：
* 支持分解复杂任务
* 智能体间通信和协调
* 结果聚合
* 可能导致深层递归，需要深度限制
### 4. 专用工具
针对特定领域的工具。
```python
class DatabaseQueryTool(Tool):
"""数据库查询"""
def name(self) -> str: return "database_query"
class ImageProcessingTool(Tool):
"""图像处理"""
def name(self) -> str: return "image_process"
class CodeAnalysisTool(Tool):
"""代码分析(静态或动态)"""
def name(self) -> str: return "code_analyze"
class DataVisualizationTool(Tool):
"""数据可视化"""
def name(self) -> str: return "plot_data"
```
**特点**：
* 特定领域的深度功能
* 高度优化
* 可能有复杂的依赖
## 5.3.2 工具能力的等级
Claude Code 的 24+内置工具可分为以下等级：
```mermaid
graph TD
A["工具能力等级体系"] --> L4["等级 4(专家级)"]
A --> L3["等级 3(高级)"]
A --> L2["等级 2(中级)"]
A --> L1["等级 1(基础)"]
L4 --> L4A["代码生成和优化"]
L4 --> L4B["架构分析和建议"]
L4 --> L4C["复杂的跨域任务协调"]
L3 --> L3A["深度分析工具"]
L3 --> L3B["专业工具集"]
L3 --> L3C["需要上下文的工具"]
L2 --> L2A["文件操作"]
L2 --> L2B["网络请求"]
L2 --> L2C["基本数据处理"]
L2 --> L2D["搜索功能"]
L1 --> L1A["简单的执行"]
L1 --> L1B["基本的查询"]
L1 --> L1C["初级操作"]
style L4 fill:#fff8e1,stroke:#ffb74d,stroke-width:2px,color:#000000
style L3 fill:#ffe0b2,stroke:#ffb74d,stroke-width:2px,color:#000000
style L2 fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000000
style L1 fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000000
```
## 5.3.3 OpenClaw 的工具策略模型
核心逻辑如下：
```python
class ToolAccessLevel(Enum):
"""工具访问级别"""
SYSTEM = "system" # 仅系统可用
ADMIN = "admin" # 管理员可用
TRUSTED = "trusted" # 信任的用户可用
PUBLIC = "public" # 所有人可用
class ToolPolicy:
"""工具策略定义"""
def __init__(self):
self.access_levels: Dict[str, ToolAccessLevel] = {}
self.resource_limits: Dict[str, Dict[str, Any]] = {}
def set_access_level(self, tool_name: str,
level: ToolAccessLevel):
"""设置工具访问级别"""
self.access_levels[tool_name] = level
def set_resource_limit(self, tool_name: str,
max_execution_time: int = None,
max_memory: int = None,
max_disk_usage: int = None):
"""设置工具的资源限制"""
self.resource_limits[tool_name] = {
"max_execution_time": max_execution_time,
"max_memory": max_memory,
"max_disk_usage": max_disk_usage
}
def can_execute(self, tool_name: str,
user_role: str) -> bool:
"""检查用户是否可以执行工具"""
level = self.access_levels.get(
tool_name,
ToolAccessLevel.PUBLIC
)
if level == ToolAccessLevel.SYSTEM:
return user_role == "system"
elif level == ToolAccessLevel.ADMIN:
return user_role in ["system", "admin"]
elif level == ToolAccessLevel.TRUSTED:
return user_role in ["system", "admin", "trusted"]
else:
return True
```
为了支持不同的使用场景和性能需求，工具系统提供了多种扩展模式，使开发者能够灵活地定制工具行为。
## 5.3.4 工具的扩展模式
### 1. 装饰器模式
该模式的实现示例：
```python
import asyncio
def timeout_wrapper(tool: Tool, timeout: int = 30) -> Tool:
"""为工具添加超时装饰器"""
class TimeoutTool(Tool):
async def call(self, input_data):
try:
return await asyncio.wait_for(
tool.call(input_data),
timeout=timeout
)
except asyncio.TimeoutError:
raise ToolExecutionError(f"Tool timeout after {timeout}s")
def name(self) -> str:
return tool.name()
def description(self) -> str:
return tool.description()
# 其他方法委托...
return TimeoutTool()
def retry_wrapper(tool: Tool, max_retries: int = 3) -> Tool:
"""为工具添加重试装饰器"""
class RetryTool(Tool):
async def call(self, input_data):
for attempt in range(max_retries):
try:
return await tool.call(input_data)
except Exception as e:
if attempt == max_retries - 1:
raise
await asyncio.sleep(2 ** attempt) # 指数退避
# 其他方法...
return RetryTool()
```
### 2. 复合工具
具体代码如下：
```python
from typing import List, Dict
class CompositeToolChain(Tool):
"""工具链:顺序执行多个工具"""
def __init__(self, tools: List[Tool],
input_mapping: Dict[str, List[str]]):
"""
input_mapping: 定义每个工具的输入如何来自前一个工具的输出
例如:{
"tool_2": ["output_from_tool_1.field_a"],
"tool_3": ["output_from_tool_2.field_b", "user_input.param"]
}
"""
self.tools = tools
self.input_mapping = input_mapping
async def call(self, input_data):
"""依次执行工具"""
context = {"user_input": input_data}
for tool in self.tools:
tool_name = tool.name()
# 解析这个工具的输入
tool_input = self._resolve_input(
self.input_mapping.get(tool_name, []),
context
)
# 执行工具
result = await tool.call(tool_input)
context[f"{tool_name}_output"] = result
return context[f"{self.tools[-1].name()}_output"]
def _resolve_input(self, mapping: List[str],
context: Dict) -> Dict:
"""从上下文中解析输入"""
result = {}
for ref in mapping:
parts = ref.split(".")
value = context
for part in parts:
value = value.get(part, {})
# 提取字段名
result[parts[-1]] = value
return result
```
### 3. 条件工具
以下是具体实现：
```python
class ConditionalTool(Tool):
"""条件执行:根据条件选择执行哪个工具"""
def __init__(self, condition_fn, tool_if_true: Tool,
tool_if_false: Tool):
self.condition_fn = condition_fn
self.tool_if_true = tool_if_true
self.tool_if_false = tool_if_false
async def call(self, input_data):
"""根据条件选择执行"""
if self.condition_fn(input_data):
return await self.tool_if_true.call(input_data)
else:
return await self.tool_if_false.call(input_data)
def name(self) -> str:
return "conditional_tool"
```
## 5.3.5 工具的能力描述
完整的工具描述应包含：
```python
@dataclass
class ToolCapability:
"""工具的能力描述"""
name: str
description: str
input_schema: Dict[str, Any]
output_schema: Dict[str, Any]
access_level: ToolAccessLevel
required_permissions: List[str]
estimated_execution_time: float # 秒
estimated_resource_usage: Dict[str, int] # 内存、CPU 等
examples: List[Dict[str, Any]] # 使用示例
limitations: List[str] # 工具的限制
dependencies: List[str] # 外部依赖
```
## 5.3.6 本节小结
工具类型体系和扩展模式决定了工具系统的灵活性：
1. **工具分类**：执行、网络、Agent、专用四大类
2. **访问级别**：系统、管理、信任、公开四个等级
3. **扩展模式**：装饰器、复合、条件等组合方式
4. **能力描述**：完整的元数据帮助智能体理解工具能力
好的工具类型体系应该既清晰易用，又能支持灵活的扩展和组合。
# 5.4 动态发现与加载
本节介绍工具的动态发现和加载机制，包括延迟加载的决策、多级优先级加载策略、Schema缓存、MCP动态注册和上下文缓存等技术，阐明如何构建灵活高效的工具加载系统。
## 5.4.1 动态加载的必要性
静态工具列表的问题：
* 无法适应运行时变化
* 新工具需要重新部署
* 无法根据上下文选择性加载
## 5.4.2 Claude Code 的 shouldDefer 机制
shouldDefer机制决定了工具是否需要延迟加载。下面的流程图展示了动态工具加载的完整流程：
```mermaid
graph TD
A["工具请求"] -->|检查上下文| B["shouldDefer?"]
B -->|否| C["立即加载"]
B -->|是| D["延迟加载"]
C -->|导入模块| E["创建实例"]
E -->|缓存| F["已加载工具"]
F -->|返回| G["就绪可用"]
D -->|稍后检查| H["上下文就绪?"]
H -->|是| C
H -->|否| I["返回不可用"]
style B fill:#fff3e0
style C fill:#c8e6c9
style D fill:#ffccbc
style G fill:#e8f5e9
```
图 5-3：shouldDefer延迟加载机制
核心实现如下：
```python
class ToolLoader:
"""延迟加载机制"""
def __init__(self):
self.loaded_tools = {}
self.tool_metadata = {}
def should_defer_loading(self, tool_name: str,
context: Dict) -> bool:
"""判断是否延迟加载工具"""
# 示例:某些工具只在特定上下文才加载
if tool_name == "database_query":
return context.get("user_role") != "admin"
return False
async def load_tool_on_demand(self, tool_name: str,
context: Dict) -> Optional[Tool]:
"""按需加载工具"""
if tool_name in self.loaded_tools:
return self.loaded_tools[tool_name]
if self.should_defer_loading(tool_name, context):
return None
# 动态导入和加载
try:
spec = self.tool_metadata.get(tool_name)
if not spec:
return None
module = await self._async_import(spec["module"])
tool_class = getattr(module, spec["class"])
tool = tool_class(**spec.get("args", {}))
self.loaded_tools[tool_name] = tool
return tool
except Exception as e:
print(f"Failed to load tool '{tool_name}': {e}")
return None
async def _async_import(self, module_path: str):
"""异步导入模块"""
import importlib
return importlib.import_module(module_path)
```
## 5.4.3 OpenClaw 的 6 级技能加载优先级
实现的代码结构：
```python
class SkillPriority(Enum):
"""技能加载优先级"""
SYSTEM = 1 # 固定系统技能
SESSION = 2 # 会话上下文技能
USER = 3 # 用户自定义
DOMAIN = 4 # 领域专业技能
BUILTIN = 5 # 通用工具
DISCOVERY = 6 # 动态发现
class SkillLoader:
"""6 级优先级技能加载器"""
def __init__(self, storage):
self.storage = storage
self.loaded_skills = {}
async def load_skills_for_session(self, session_id: str):
"""为会话加载所有技能"""
skills = []
# 1. 系统技能
skills.extend(await self._load_system_skills())
# 2. 会话上下文技能
skills.extend(await self._load_session_skills(session_id))
# 3. 用户自定义技能
skills.extend(await self._load_user_skills(session_id))
# 4. 领域技能
domain = await self._detect_domain(session_id)
skills.extend(await self._load_domain_skills(domain))
# 5. 内置工具
skills.extend(await self._load_builtin_tools())
# 6. 动态发现技能
skills.extend(await self._discover_skills_dynamically(session_id))
return skills
async def _load_system_skills(self):
"""加载系统技能(始终可用)"""
return await self.storage.get_system_skills()
async def _load_session_skills(self, session_id: str):
"""加载会话特定的技能"""
return await self.storage.get_session_skills(session_id)
async def _load_user_skills(self, session_id: str):
"""加载用户定义的技能"""
user_id = await self.storage.get_user_for_session(session_id)
return await self.storage.get_user_skills(user_id)
async def _load_domain_skills(self, domain: str):
"""加载特定领域的技能"""
if not domain:
return []
return await self.storage.get_domain_skills(domain)
async def _load_builtin_tools(self):
"""加载内置工具"""
return [
BashTool(),
FileReadTool(),
FileWriteTool(),
# ... 其他内置工具
]
async def _discover_skills_dynamically(self, session_id: str):
"""动态发现技能"""
# 扫描技能目录或 MCP
discovered = await self.storage.discover_available_skills()
return discovered
async def _detect_domain(self, session_id: str) -> str:
"""根据会话内容检测领域"""
recent_messages = await self.storage.get_recent_messages(session_id, limit=5)
# 使用 NLP 检测领域
text = " ".join(m.get_text() for m in recent_messages)
return self._classify_domain(text)
def _classify_domain(self, text: str) -> str:
"""简单的领域分类"""
keywords = {
"data": ["sql", "database", "query", "table"],
"web": ["html", "css", "javascript", "react"],
"system": ["bash", "shell", "linux", "windows"],
"code": ["python", "java", "javascript"]
}
text_lower = text.lower()
for domain, kws in keywords.items():
if any(kw in text_lower for kw in kws):
return domain
return "general"
```
## 5.4.4 JSON Schema 缓存
具体的缓存实现：
```python
class SchemaCache:
"""工具 Schema 缓存"""
def __init__(self, max_age: int = 3600):
self.cache = {}
self.max_age = max_age
self.timestamps = {}
def get_schema(self, tool_name: str) -> Optional[Dict]:
"""获取缓存的 Schema"""
if tool_name in self.cache:
age = time.time() - self.timestamps[tool_name]
if age < self.max_age:
return self.cache[tool_name]
else:
del self.cache[tool_name]
del self.timestamps[tool_name]
return None
def set_schema(self, tool_name: str, schema: Dict):
"""缓存 Schema"""
self.cache[tool_name] = schema
self.timestamps[tool_name] = time.time()
def build_all_schemas(self, tools: List[Tool]) -> Dict[str, Dict]:
"""批量构建 Schema 缓存"""
schemas = {}
for tool in tools:
schema = {
"name": tool.name(),
"description": tool.description(),
"input_schema": tool.input_schema()
}
self.set_schema(tool.name(), schema)
schemas[tool.name()] = schema
return schemas
```
## 5.4.5 MCP 动态注册
MCP(Model Context Protocol)支持动态工具注册：
> ⚠️ **注意**：以下代码为概念示意，非真实 MCP 调用方式。真实 MCP 客户端使用 JSON-RPC 2.0 over stdio 或 Streamable HTTP，不使用 REST 风格的 `/tools/list` 和 `/tools/call` 端点。详见第 9.3 节与 9.4 节 MCP 协议详解。
```python
class MCPToolRegistry:
"""MCP 协议的工具注册"""
def __init__(self):
self.mcp_servers = {}
self.available_tools = {}
async def discover_mcp_tools(self, server_url: str):
"""发现 MCP 服务器的工具"""
try:
# 连接到 MCP 服务器
async with aiohttp.ClientSession() as session:
async with session.get(f"{server_url}/tools") as resp:
tools = await resp.json()
return tools
except Exception as e:
print(f"Failed to discover MCP tools: {e}")
return []
def register_mcp_tool(self, server_url: str,
tool_name: str,
tool_spec: Dict):
"""注册来自 MCP 的工具"""
if server_url not in self.mcp_servers:
self.mcp_servers[server_url] = {}
self.mcp_servers[server_url][tool_name] = tool_spec
self.available_tools[tool_name] = {
"source": "mcp",
"server": server_url,
"spec": tool_spec
}
async def execute_mcp_tool(self, tool_name: str,
input_data: Dict) -> Any:
"""执行 MCP 工具"""
tool_info = self.available_tools.get(tool_name)
if not tool_info:
raise ValueError(f"Tool not found: {tool_name}")
server_url = tool_info["server"]
async with aiohttp.ClientSession() as session:
async with session.post(
f"{server_url}/tools/call",
json={"name": tool_name, "arguments": input_data}
) as resp:
return await resp.json()
```
## 5.4.6 FileStateCache 上下文缓存
实现如下：
```python
class FileStateCache:
"""文件状态缓存:减少重复工具调用"""
def __init__(self, ttl: int = 60): # 缓存时间(秒)
self.cache = {}
self.timestamps = {}
self.ttl = ttl
def get(self, key: str) -> Optional[Dict]:
"""获取缓存"""
if key in self.cache:
age = time.time() - self.timestamps[key]
if age < self.ttl:
return self.cache[key]
else:
del self.cache[key]
del self.timestamps[key]
return None
def set(self, key: str, value: Dict):
"""设置缓存"""
self.cache[key] = value
self.timestamps[key] = time.time()
def invalidate(self, pattern: str):
"""失效匹配模式的缓存"""
import re
regex = re.compile(pattern)
to_delete = [k for k in self.cache.keys() if regex.match(k)]
for key in to_delete:
del self.cache[key]
del self.timestamps[key]
# 使用:缓存文件列表结果
cache = FileStateCache()
async def file_list_with_cache(directory: str) -> List[str]:
"""带缓存的文件列表"""
cache_key = f"file_list:{directory}"
# 检查缓存
cached = cache.get(cache_key)
if cached:
return cached["files"]
# 执行工具
files = await bash_exec(f"ls -la {directory}")
# 缓存结果
cache.set(cache_key, {"files": files})
return files
```
## 5.4.7 本节小结
动态工具加载是现代智能体系统的必需能力：
1. **shouldDefer 延迟加载**：基于上下文决定是否加载工具
2. **6 级优先级加载**：系统 → 会话 → 用户 → 领域 → 内置 → 发现
3. **Schema 缓存**：减少重复构建 Schema 的开销
4. **MCP 动态注册**：支持第三方工具的即插即用
5. **FileStateCache**：减少重复工具调用，提高性能
这些机制共同构成了一个灵活、高效、可扩展的工具加载系统。
# 5.5 实战：MiniHarness 工具层实现
本节实现一个完整的 MiniHarness 工具层，包括工具协议、注册表、执行流水线和几个内置工具。核心设计原则是“发现、权限、执行、结果”四阶段流水线。
## 5.5.1 工具抽象与基类
工具层的核心是统一的 Tool 基类，定义了所有工具必须实现的接口。工具的设计遵循“契约优先”原则：
```python
from abc import ABC, abstractmethod
class Tool(ABC):
"""工具基类 - 定义工具的通用契约"""
@abstractmethod
async def call(self, params: Dict[str, Any]) -> ToolResult:
"""执行工具的核心逻辑"""
pass
@abstractmethod
def name(self) -> str:
"""工具的唯一标识符"""
pass
@abstractmethod
def description(self) -> str:
"""工具描述"""
pass
@abstractmethod
def input_schema(self) -> Dict[str, Any]:
"""JSON Schema 定义输入约束"""
pass
def check_permissions(self, context: Any) -> bool:
"""权限检查钩子 - 可被子类覆盖"""
return True
```
关键设计决策：
1. **异步执行**：所有工具使用 `async/await`，支持 IO 密集型操作
2. **Schema 驱动**：通过 JSON Schema 定义输入，实现自文档化和验证
3. **权限钩子**：`check_permissions()` 允许子类实现细粒度权限控制
4. **统一结果类型**：`ToolResult` 封装成功/失败/执行时间等元数据
完整实现参见 `lab/mini_harness/tools/builtin.py`。
## 5.5.2 工具执行流水线
执行流水线是系统的核心，实现了 4 阶段的工具调用流程：
```python
class ExecutionPipeline:
"""执行流水线 - 控制工具的调用生命周期"""
async def execute(self, tool_name: str,
input_params: Dict[str, Any]) -> ToolResultBlock:
# 阶段 1:工具发现(lookup)
tool = self.tool_registry.get(tool_name)
if not tool:
return ToolResultBlock(success=False,
content=f"Tool not found")
# 阶段 2:权限检查(authorization)
if not tool.check_permissions({}):
return ToolResultBlock(success=False,
content=f"Permission denied")
# 阶段 3:执行工具(execution)
# 阶段 4:结果处理(result handling)
result = await tool.call(input_params)
return ToolResultBlock(
success=result.success,
# ... 其他结果字段
)
```
四阶段设计的优点：
* **可观测性**：每个阶段可独立记录日志和监控
* **可扩展性**：插入速率限制、超时控制、重试逻辑等中间件
* **安全性**：权限检查在执行前进行，防止越权操作
* **容错性**：捕获任意异常并转换为统一的失败结果
完整实现参见 `lab/mini_harness/tools/builtin.py` 中的 `ExecutionPipeline` 类。
## 5.5.3 工具注册表
工具注册表充当服务发现中心和 Schema 缓存：
```python
class ToolRegistry:
"""工具注册中心 - 管理工具的生命周期"""
def register(self, tool: Tool):
"""注册工具并缓存其 Schema"""
name = tool.name()
self.tools[name] = tool
# 缓存 Schema 避免重复调用
self.schema_cache[name] = {
"name": name,
"description": tool.description(),
"input_schema": tool.input_schema()
}
def list_tools(self) -> List[Dict[str, Any]]:
"""返回所有工具的 Schema(用于 LLM 提示词)"""
return list(self.schema_cache.values())
```
设计特点：
* **Schema 缓存**：减少重复的 Schema 构建，加速工具列表生成
* **统一发现**：LLM 通过 `list_tools()` 获取全部可用工具及其约束
* **松耦合**：执行流水线仅依赖注册表接口，不需关心工具实现细节
完整实现参见 `lab/mini_harness/tools/registry.py`。
## 5.5.4 内置工具示例
三个内置工具展示了不同的设计模式：
**BashTool**：命令执行工具，演示了长时间运行任务的超时处理
```python
class BashTool(Tool):
async def call(self, params: Dict[str, Any]) -> ToolResult:
command = params.get("command", "")
timeout = params.get("timeout", 30)
try:
result = subprocess.run(command, shell=True,
timeout=timeout, text=True,
capture_output=True)
return ToolResult(
success=result.returncode == 0,
# ... 其他结果字段
)
except subprocess.TimeoutExpired:
return ToolResult(
success=False,
error_type="TimeoutError",
# ... 其他结果字段
)
```
**FileReadTool 和 FileWriteTool**：文件操作工具，演示了错误分类和限制（如 max\_bytes）
这些工具的完整实现包括详细的错误处理、参数验证和边界情况处理，参见 `lab/mini_harness/tools/builtin.py`。
## 5.5.5 扩展路径
1. **中间件架构**：在执行流水线中插入速率限制、重试、缓存层
2. **权限模型**：为不同用户和工具组合配置细粒度权限
3. **超时和资源限制**：为每个工具实例设置 CPU/内存配额
4. **并发执行**：使用 `asyncio.gather()` 实现多工具并发调用
5. **工具依赖图**：支持工具间的数据流依赖（DAG 执行）
6. **结果缓存**：基于输入哈希缓存工具结果，支持失效策略
## 5.5.6 本节小结
MiniHarness 工具层的核心贡献：
1. **清晰的抽象边界**：Tool 基类定义统一契约，工具之间互不依赖
2. **四阶段执行流水线**：发现→权限→执行→处理，可观测且可扩展
3. **Schema 驱动设计**：工具通过 JSON Schema 自描述，LLM 可直接理解
4. **错误优先处理**：所有失败路径返回统一的 `ToolResult` 类型
这些原则适用于任何规模的 AI Agent 系统工具层设计。
# 本章小结
本章深入探讨了工具层的设计原则和实现模式，以下是主要内容的总结。
## 工具层设计的核心原则
### 1. 统一抽象
无论工具类型如何（文件、网络、计算、数据库），都应该通过统一的接口暴露能力。Claude Code 的 Tool\ 泛型设计实现了强类型检查，OpenClaw 的 Tool Protocol 提供了灵活的抽象。
### 2. 权限隔离
工具调用前必须进行权限检查，防止未授权的操作。不同的工具有不同的权限要求：
* 系统工具(Bash)：只有管理员可用
* 数据库工具：需要认证
* 文件工具：需要文件访问权限
### 3. 错误恢复
工具执行失败是常态，系统必须：
* 捕获所有异常（执行错误、超时、权限拒绝）
* 将错误转化为 ToolResultBlock 反馈给 Agent
* 支持重试策略（指数退避）
### 4. 性能优化
* **并发执行**：多个工具可以并行执行
* **结果缓存**：避免重复调用相同工具
* **Schema 缓存**：减少构建工具信息的开销
## 工具类型体系速览
| 类型 | 特点 | 示例 |
| ----- | ----------- | ---------------- |
| 执行工具 | 直接改变系统状态 | Bash、Python、文件操作 |
| 网络工具 | 远程调用，有延迟和限制 | HTTP、API、搜索 |
| 智能体工具 | 委托给其他智能体 | SubAgent、并行执行 |
| 专用工具 | 特定领域的深度功能 | 数据库、图像处理 |
## 执行流水线的 6 个阶段
流程如下：
```mermaid
flowchart LR
A["发现"] --> B["权限检查"]
B --> C["输入验证"]
C --> D["执行"]
D --> E["结果处理"]
E --> F["持久化"]
style A fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style B fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style C fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style D fill:#e8f4e8,stroke:#4a9044,stroke-width:2px,color:#000000
style E fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style F fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000000
```
每个阶段都有明确的职责和错误处理机制，确保整个流程的可靠性。
## 工具扩展的三种模式
1. **装饰器模式**：为工具添加超时、重试等通用能力
2. **复合工具**：组合多个工具形成工具链
3. **条件工具**：根据条件选择执行的工具
## 动态加载的必要性
* **shouldDefer 延迟加载**：根据上下文决定是否加载工具，节省内存
* **6 级优先级加载**：OpenClaw 的分层加载策略，支持灵活的工具组织
* **MCP 动态注册**：支持第三方工具的即插即用
* **Schema 缓存**：减少重复构建的开销
## Claude Code vs OpenClaw 的工具设计对比
| 方面 | Claude Code | OpenClaw |
| ---- | -------------------- | ------------- |
| 工具数量 | 24+内置工具 | 通用工具 + 技能 |
| 执行模式 | 并发 | 顺序 |
| 接口设计 | Tool\ 泛型 | Tool Protocol |
| 权限模型 | check\_permissions() | 工具策略和访问级别 |
| 加载策略 | shouldDefer | 6 级优先级 |
| 缓存 | FileStateCache | 会话记忆 |
## MiniHarness 的实现启示
通过从零实现工具层，我们学到：
1. **工具抽象** 需要平衡通用性和类型安全
2. **执行流水线** 需要完整的生命周期管理
3. **工具注册表** 是工具系统的中枢
4. **错误处理** 必须穷尽所有可能的失败模式
5. **可扩展性** 通过接口和工厂模式实现
## 与其他章节的联系
关系图如下：
```mermaid
graph TD
A["运行时引擎(第4章)
调用工具的生命周期管理"] -->|调用| B["工具层(第5章)
工具的抽象和执行
← 你在这里"]
B -->|结果| C["记忆系统(第6章)
工具结果的持久化"]
style A fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style B fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style C fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
```
运行时引擎调用工具层执行具体操作，工具执行的结果保存到记忆系统。
## 设计决策速查
1. **工具接口**：选择类型安全(Tool\)还是灵活的协议(Tool Protocol)
2. **执行模式**：并发执行还是顺序执行，取决于工具依赖关系
3. **权限模型**：简单的 boolean 检查还是复杂的策略模型
4. **加载策略**：预加载所有工具还是按需加载
5. **缓存策略**：缓存结果、Schema 还是执行历史
## 学习建议
1. **理解工具抽象**：为什么需要统一接口，不同的设计如何影响系统
2. **掌握执行流水线**：6 个阶段的职责分工和错误处理
3. **学习扩展模式**：如何优雅地扩展工具系统，支持新的工具类型
4. **实践动态加载**：实现工具的延迟加载和按需发现
5. **优化性能**：通过缓存、并发、Schema 预加载提高性能
## 常见陷阱
1. **权限检查遗漏**：在执行前必须检查权限，防止安全漏洞
2. **错误处理不完整**：必须捕获所有可能的异常（超时、权限、格式错误等）
3. **缺乏超时保护**：没有超时的工具调用可能导致系统挂起
4. **Schema 过时**：工具更新后忘记更新 Schema，导致参数错误
5. **缓存不失效**：缓存的数据如果不及时失效，可能导致数据不一致
## 进阶话题
1. **工具的分布式执行**：在多个节点执行工具
2. **工具的版本管理**：支持多个版本的同一工具
3. **工具的性能优化**：对慢工具的优化策略
4. **工具的自动化测试**：确保工具的正确性
5. **工具的文档生成**：从 Schema 自动生成文档
## 第五章完成
本章深入讲解了工具层的设计与实现，涵盖了工具抽象、执行流水线、工具类型体系、动态加载等关键主题。通过 MiniHarness 的实现，我们展示了这些概念如何落地成可运行的代码。
下一章将深入 **记忆与上下文子系统**，研究如何有效地存储、检索和利用过去的交互信息来提高智能体的能力。
# 第六章：记忆与上下文子系统
## 章引言
记忆是智能体系统的第二大脑。没有记忆，Agent 无法学习，每次对话都是从零开始。记忆系统决定了智能体是否能够：
* 记住用户的偏好和背景
* 在多个会话间保持一致性
* 学习和改进其行为
* 高效地处理长时对话（通过压缩而非简单截断）
本章将深入 Harness 的记忆设计，对比 Claude Code 和 OpenClaw 的不同方法。
## 核心设计问题
1. **多层架构**：工作记忆（当前会话）、短期记忆（会话间）、长期记忆（持久化）如何划分？
2. **可写入性**：Agent 不仅读取记忆，还要能更新和创建记忆
3. **组装能力**：如何从多个来源的记忆组装出完整的上下文？
4. **整合机制**：长对话中，何时触发记忆整合（压缩/清理）？
## 两个参考系统
**Claude Code 的三层模型**：
* 对话历史：当前会话的完整消息
* CLAUDE.md：用户反馈、项目信息、参考资料
* autoDream 系统：三门触发、四阶段整合(Orient→Gather→Consolidate→Prune)
**OpenClaw 的双层模型**：
* MEMORY.md：永久性记忆（关键事实、学习、历史）
* 每日日志：当前会话的详细记录
* memory\_search 语义检索：找到相关的历史信息
* 自动刷写：70% 上下文触发记忆整合
## 本章结构
* 6.1：多层记忆架构
* 6.2：可写入式记忆
* 6.3：上下文组装引擎
* 6.4：记忆整合与压缩
* 6.5：MiniHarness 记忆实现
* 本章小结
记忆系统是智能体系统中最复杂但也最关键的子系统之一。
# 6.1 Harness中的记忆系统工程设计
记忆系统是智能体长期学习和适应的基础。关于记忆的认知模型、三层架构理论（工作、短期和长期记忆），以及非参数记忆与参数记忆的根本区别，请参阅《智能体 AI 权威指南》第三章。同时，更多关于记忆系统在上下文工程中的应用，请参阅《上下文工程权威指南》第四章。
> 💡 **理论参考**：
>
> * 《智能体 AI 权威指南》第三章(3.1-3.3)介绍了多层记忆的认知模型和工程映射
> * 《上下文工程权威指南》第四章讨论了上下文管理与记忆的关系
本节重点讨论 **Harness 框架中的记忆实现**，特别是 **autoDream 系统** 和 **记忆整合管道** 的工程细节。
## 6.1.1 Harness记忆架构概览
Harness采用了一个经过验证的三层架构，但针对多任务、多工作流的场景做了特殊优化：
```mermaid
graph TD
A["当前对话消息"] -->|窗口溢出| B["工作记忆
LLM 上下文窗口"]
B -->|自动整合| D["短期记忆
SESSION.md"]
D -->|触发条件 × 3
定期整合| F["长期记忆"]
F -->|结构化部分| G1["MEMORY.md
用户档案、学习、决策"]
F -->|向量部分| G2["embedding_index
语义检索"]
F -->|日志部分| G3["session_logs/
按日期分片"]
B -.->|需要时检索| D
D -.->|需要时检索| G1
D -.->|语义搜索| G2
style A fill:#bbdefb
style B fill:#c8e6c9
style D fill:#fff9c4
style G1 fill:#ffe0b2
style G2 fill:#f8bbd0
style G3 fill:#d4f1d4
```
图 6-1：Harness 三层记忆架构
**各层特性**：
1. **工作记忆**：完全委托给LLM上下文管理，Harness无需干预
2. **短期记忆**：轻量化的会话缓存（JSON格式），存储过去10个会话的摘要
3. **长期记忆**：组合式存储，分为三个子系统
## 6.1.2 autoDream系统：记忆整合管道
autoDream是Harness的自动记忆整合系统，负责将会话数据定期整合到长期记忆。它的设计借鉴了Claude Code的思想，但针对多工作流、多用户的场景进行了扩展。
### 整合触发的三门机制
autoDream不是持续运行，而是在满足 **至少一个** 触发条件时才激活：
```python
import time
class MemoryConsolidationTrigger:
"""记忆整合触发器"""
def __init__(self, config):
self.time_threshold = config.get("time_threshold", 86400) # 24小时
self.session_threshold = config.get("session_threshold", 5) # 5个会话
self.last_consolidation_time = time.time()
self.session_count_since_consolidation = 0
def should_consolidate(self) -> bool:
"""检查是否应该触发整合"""
# 触发条件1:时间门槛
if time.time() - self.last_consolidation_time > self.time_threshold:
return True
# 触发条件2:会话计数门槛
if self.session_count_since_consolidation >= self.session_threshold:
return True
# 触发条件3:显式锁定(用户或系统主动触发)
# 这通过外部API调用实现:POST /consolidate
return False
def on_session_end(self):
"""会话结束时调用"""
self.session_count_since_consolidation += 1
```
### 四阶段整合管道
一旦触发，autoDream执行标准化的四阶段流程：
```python
import time
from typing import List, Dict, Any
class MemoryConsolidationPipeline:
"""记忆整合管道"""
async def consolidate(self, workflow_id: str, session_history: List[Dict[str, Any]]):
"""执行完整的整合流程"""
# 阶段1:Orient - 分析会话目标和上下文
orientation = await self.orient_phase(workflow_id, session_history)
# 结果:{goals, context, decisions, new_patterns}
# 阶段2:Gather - 从对话历史提取关键信息
gathered = await self.gather_phase(session_history, orientation)
# 结果:{facts, preferences, outcomes, patterns}
# 阶段3:Consolidate - 合并到长期记忆,避免冗余
consolidated = await self.consolidate_phase(workflow_id, gathered)
# 结果:更新了MEMORY.md, embedding_index, session_logs
# 阶段4:Prune - 删除过期或低价值的信息
pruned = await self.prune_phase(workflow_id, consolidated)
# 结果:清理过时的会话摘要
return {
"orientation": orientation,
"gathered": gathered,
"consolidated": consolidated,
"pruned": pruned
}
async def orient_phase(self, workflow_id: str, session_history: List[Message]):
"""阶段1:Orient - 理解会话的核心目标和决策点"""
prompt = f"""
分析这个工作流的会话记录,提供:
1. 会话的核心目标(1-3个)
2. 关键的决策点和选择(2-3个)
3. 发现的系统级模式或约束(2-3个)
4. 用户展现的新的偏好或工作风格(如有)
会话记录:
{self._format_session_history(session_history)}
"""
# 调用LLM进行分析
return await self.llm.analyze(prompt)
async def gather_phase(self, session_history: List[Message], orientation: dict):
"""阶段2:Gather - 提取结构化事实"""
facts = {
"user_preferences": [],
"task_outcomes": [],
"technical_discoveries": [],
"system_constraints": []
}
for message in session_history:
if message.role == "user":
# 从用户消息提取偏好
pref = self._extract_preference(message.content)
if pref:
facts["user_preferences"].append(pref)
elif message.role == "assistant":
# 从助手消息提取成果
outcome = self._extract_outcome(message.content)
if outcome:
facts["task_outcomes"].append(outcome)
return facts
async def consolidate_phase(self, workflow_id: str, gathered: dict):
"""阶段3:Consolidate - 合并到长期记忆,避免冗余"""
# 读取现有MEMORY.md
memory = await self._load_memory_file(workflow_id)
# 去重:与现有内容比较,只添加新信息
new_facts = await self._deduplicate(gathered["user_preferences"], memory.get("user_preferences", []))
# 更新MEMORY.md
memory["user_preferences"].extend(new_facts)
memory["last_updated"] = time.time()
# 更新向量索引(用于语义搜索)
embeddings = await self._embed_facts(gathered)
await self._upsert_to_vector_index(workflow_id, embeddings)
# 追加到日志
await self._append_to_session_log(workflow_id, gathered)
return {"updated_memory": memory, "updated_embeddings": embeddings}
async def prune_phase(self, workflow_id: str, consolidated: dict):
"""阶段4:Prune - 删除过期或低价值的信息"""
memory = consolidated["updated_memory"]
# 策略1:删除超过6个月的会话摘要
cutoff_time = time.time() - 180 * 24 * 3600
memory["session_summaries"] = [
s for s in memory.get("session_summaries", [])
if s.get("timestamp", 0) > cutoff_time
]
# 策略2:删除重复或相似的用户偏好
memory["user_preferences"] = await self._deduplicate_with_similarity(
memory["user_preferences"],
similarity_threshold=0.95
)
# 策略3:删除与当前工作无关的信息
relevant_prefs = await self._filter_by_relevance(
memory["user_preferences"],
workflow_id,
relevance_threshold=0.6
)
memory["user_preferences"] = relevant_prefs
# 保存回磁盘
await self._save_memory_file(workflow_id, memory)
return {"pruned_memory": memory}
```
## 6.1.3 短期记忆与缓存策略
短期记忆的目的是快速恢复最近会话的上下文，无需每次都从长期记忆检索。
```python
class SessionMemoryCache:
"""会话记忆缓存(JSON格式)"""
def __init__(self, max_sessions: int = 10):
self.max_sessions = max_sessions
self.cache_file = "~/.harness/session_cache.jsonl"
async def record_session_summary(self, workflow_id: str, session_data: dict):
"""记录一个会话的摘要"""
summary = {
"workflow_id": workflow_id,
"timestamp": time.time(),
"user_input": session_data.get("user_input", ""),
"key_outputs": session_data.get("key_outputs", []),
"decisions_made": session_data.get("decisions", []),
"errors_encountered": session_data.get("errors", []),
}
# 追加到缓存
with open(self.cache_file, "a") as f:
f.write(json.dumps(summary) + "\n")
# 如果超过max_sessions,删除最旧的
await self._prune_old_sessions()
async def get_recent_sessions(self, workflow_id: str, count: int = 5) -> List[dict]:
"""快速获取最近的几个会话"""
sessions = []
with open(self.cache_file, "r") as f:
for line in f:
session = json.loads(line)
if session["workflow_id"] == workflow_id:
sessions.append(session)
return sessions[-count:] # 返回最近的count个
```
## 6.1.4 向量索引与语义检索
对于大规模的长期记忆，必须使用向量索引来支持高效的语义搜索。
### 向量库选型对比
| 向量库 | 许可证 | 适用规模 | 2026 现状 |
| ------------ | ------------- | --------- | ----------------------- |
| **Hnswlib** | Apache 2.0 | <1M 向量 | 稳定内存索引、C++ 优化、无运维成本 |
| **Qdrant** | AGPL v3/商业 | 1M-10M 向量 | v1.7+、高性能 Rust、K8s 部署成熟 |
| **pgvector** | PostgreSQL 许可 | <5M 向量 | v0.5+、HNSW 算法、深度 SQL 集成 |
| **Weaviate** | BSL 1.1/商业 | 10M+ 向量 | v1.6+、多模态支持、GraphQL API |
**选型建议**：简单应用使用 Hnswlib，中等规模选 Qdrant，已有 PostgreSQL 基础设施选 pgvector，大规模企业级选 Weaviate。
```python
# EMBEDDING_DIM 需与所用 embedding 模型一致：
# text-embedding-3-small=1536, text-embedding-3-large=3072, voyage-3-large=1024
class MemoryVectorIndex:
"""向量索引用于语义搜索"""
# 关键：维度必须与 embedding 模型匹配
# 默认 1536 对应 text-embedding-3-small；如使用其他模型需修改
EMBEDDING_DIM = 1536 # 默认使用 text-embedding-3-small 维度
def __init__(self, index_path: str, embedding_dim: int = None):
# 使用轻量级的向量库(如Hnswlib或Faiss)
# dim 参数必须与所用 embedding 模型的输出维度一致
dim = embedding_dim or self.EMBEDDING_DIM
self.index = hnswlib.Index(space='cosine', dim=dim)
self.index.load_index(index_path)
self.metadata = {} # 存储向量到原始数据的映射
async def search_memory(self, query: str, top_k: int = 5) -> List[dict]:
"""语义搜索记忆"""
# 将查询嵌入
query_embedding = await self._embed(query)
# 搜索最相似的向量
labels, distances = self.index.knn_query(query_embedding, k=top_k)
# 返回元数据
results = [
{
"similarity_score": 1 - distances[0][i], # 归一化
"memory_content": self.metadata[label],
}
for i, label in enumerate(labels[0])
]
return results
```
## 6.1.5 本小节小结
Harness的记忆系统通过以下机制支持长期学习：
1. **三门触发机制**：通过时间、会话计数或显式触发来激活整合
2. **四阶段管道**：Orient→Gather→Consolidate→Prune的标准化流程
3. **去重与去噪**：自动清理冗余和过期信息
4. **多模态存储**：结构化(MEMORY.md)、向量(embedding\_index)、日志(session\_logs)
5. **快速检索**：向量索引支持语义搜索，JSON缓存支持秒级访问
关于记忆的认知基础和理论模型，请参阅《智能体 AI 权威指南》和《上下文工程权威指南》。
# 6.2 可写入式智能体记忆构建
为了赋予智能体真正的学习和适应能力，需要构建完整的可写入式记忆系统。本节涵盖记忆的读写对称性设计、Frontmatter 元数据结构、写入时机策略以及 OpenClaw 的混合检索机制，最后讨论并发环境下的冲突解决方案。
## 6.2.1 记忆系统的读写对称性
传统的智能体记忆系统往往是 **单向的**：Agent 读取预设的记忆文件，但无法主动更新。这限制了智能体的自适应能力。真正强大的智能体系统应该支持 **可写入式记忆**——Agent 作为主动的参与者，既读取也创建和更新记忆。
可写入式记忆的关键特性：
1. **主动性**：Agent 在对话过程中识别值得记忆的信息，自主决定何时写入
2. **原子性**：记忆写入操作应该是原子的，避免部分更新导致的不一致
3. **可审计性**：每次写入都应该留下痕迹，支持版本回滚
4. **并发安全**：在多会话并发场景下，防止记忆冲突
## 6.2.2 记忆文件的 Frontmatter 结构
为了支持可写入式记忆，我们采用 **Markdown Frontmatter** 结构，将元数据与内容分离：
```yaml
---
type: episodic # 记忆类型:user/feedback/project/reference/episodic
version: 3 # 版本号,每次更新递增
last_modified: 2024-01-15T14:30:00Z
modified_by: session_id # 修改者的会话标识
confidence: 0.85 # 信息可信度(0-1),自动学习可降低
expiry: 2024-06-15 # 过期时间,可选
tags: [user_preference, performance]
---
# 记忆内容
实际的内容从这里开始...
```
各字段的含义：
* **type**：记忆的语义类别
* `user`：用户档案信息（不改变的属性）
* `feedback`：用户反馈和评估
* `project`：项目或任务上下文
* `reference`：可复用的代码、命令、模式
* `episodic`：具体事件的记录
* **version**：支持版本追踪，允许回滚
* **last\_modified**：ISO 8601 时间戳
* **modified\_by**：记录是哪个会话或智能体实例修改的
* **confidence**：由智能体自评的信息可信度，用于后续搜索排序
* **expiry**：自动清理过期记忆
* **tags**：用于分类和检索的标签集
## 6.2.3 记忆写入时机策略
Agent 应该在以下时刻考虑写入记忆：
**显式写入信号** （高优先级）：
* 用户明确要求“记住这个”或“保存这个信息”
* 系统检测到错误或失败，需要记录教训
* 完成一个重要的里程碑或任务
**隐式写入信号** （中优先级）：
* 首次遇到新的用户偏好（如代码风格、工作习惯）
* 发现系统性的性能问题或优化机会
* 完成一个新的项目或学习领域
**实时写入信号** （低优先级）：
* 每个会话结束后的自动总结
* 长对话中的中间检查点
写入决策的伪代码：
```python
async def decide_write_memory(session_context, content):
"""判断是否应该写入记忆"""
signals = []
# 检查显式信号
if "remember" in content.lower() or "记住" in content:
signals.append(("explicit_user", 0.95))
# 检查隐式信号
if is_new_user_preference(content, session_context):
signals.append(("new_preference", 0.7))
if is_error_or_lesson_learned(content):
signals.append(("learning", 0.8))
if is_milestone_completion(content):
signals.append(("milestone", 0.85))
# 综合评分
max_score = max([score for _, score in signals]) if signals else 0
if max_score > 0.6: # 阈值
return True, dict(signals)
return False, {}
```
## 6.2.4 Claude Code 的记忆类型分类
Claude Code 将记忆划分为四个类型，各有不同的更新策略：
**User Profiles**：
* 存储用户的基本属性、技能、工作风格
* 更新频率：低（通常用户主动告知）
* 示例：
```yaml
User: Alex
- Programming level: Intermediate Python, Advanced JS
- Preferred style: Concise, comments only for complex logic
- Work context: Startup, rapid iteration preferred
```
**Feedback Records**：
* 用户对智能体建议的反馈
* 更新频率：每次用户评价时更新
* 示例：
```yaml
Feedback [2024-01-14]:
- Rejected: Suggested async/await pattern
Reason: Prefers synchronous code in this codebase
- Approved: Refactoring suggestion for API layer
```
**Project Context**：
* 当前项目的架构、进度、关键文件
* 更新频率：每个功能完成后更新
* 示例：
```yaml
Project: WebApp v2.0
Last activity: 2024-01-15
- Modules: auth (done), api (in progress), ui (planned)
- Key files: src/main.py, tests/
- Architecture decision: Monolithic with plugins
```
**Reference Materials**：
* 可复用的代码片段、命令、文档链接
* 更新频率：中等（发现新的有用模式时添加）
* 示例：
```yaml
## Useful Commands
- Test: pytest -v --cov
- Deploy: make deploy-prod
## Code Patterns
- Factory pattern for data access
- Decorator for logging
```
## 6.2.5 OpenClaw 的 memory\_search 混合检索
OpenClaw 的可写入记忆通过 memory\_search 实现高效的读取，支持 **混合检索**：
**关键词检索阶段**：
```python
def keyword_search(query: str, memory_base: str) -> List[str]:
"""在 MEMORY.md 和日志中执行关键词匹配"""
results = []
keywords = query.lower().split()
for memory_file in get_memory_files():
content = read_file(memory_file)
matches = [line for line in content.split('\n')
if any(kw in line.lower() for kw in keywords)]
results.extend(matches)
return results
```
**向量检索阶段**：
```python
def semantic_search(query: str, embedding_index) -> List[str]:
"""使用向量相似度查找相关内容"""
query_embedding = embed(query)
scores = []
for memory_id, stored_embedding in embedding_index.items():
similarity = cosine_similarity(query_embedding, stored_embedding)
scores.append((memory_id, similarity))
# 返回相似度最高的 Top-K
return [mid for mid, _ in sorted(scores, reverse=True)[:5]]
```
**混合排序**：
```python
def hybrid_search(query: str, memory_base: str, embedding_index) -> List[str]:
"""组合关键词和向量搜索结果"""
kw_results = keyword_search(query, memory_base)
sem_results = semantic_search(query, embedding_index)
# 融合:先返回同时匹配两者的结果,再返回单一匹配
combined = set(kw_results) & set(sem_results)
rest = (set(kw_results) | set(sem_results)) - combined
return list(combined) + list(rest)
```
这种混合检索的优势在于：
* **精确性**：关键词搜索捕获精确的事实
* **泛化性**：向量搜索发现语义相似但词汇不同的信息
* **效率**：分阶段执行避免全向量扫描
## 6.2.6 写入冲突解决
在多会话并发环境下，多个智能体实例可能同时修改同一个记忆文件。冲突解决策略：
**版本号机制**：
```python
def write_memory_atomic(memory_id: str, new_content: str,
expected_version: int) -> bool:
"""原子式写入,基于版本号"""
current = read_memory(memory_id)
if current['version'] != expected_version:
# 版本冲突,进行 3-way merge
return merge_versions(current, new_content)
new_version = {
'version': expected_version + 1,
'last_modified': now(),
'modified_by': current_session_id(),
'content': new_content
}
return atomic_write(memory_id, new_version)
```
**3-way Merge 策略**： 当版本冲突时，比较三个版本的差异（基础版本、当前版本、新版本），智能合并：
```python
def merge_versions(base, current, new):
"""3-way merge 用于记忆文件"""
# 简化示例:按行级别的 diff
base_lines = base.split('\n')
curr_lines = current.split('\n')
new_lines = new.split('\n')
merged = []
for i, (b, c, n) in enumerate(zip(base_lines, curr_lines, new_lines)):
if c == n: # 无冲突
merged.append(c)
elif b == c: # 只有新版本改动
merged.append(n)
elif b == n: # 只有当前版本改动
merged.append(c)
else: # 双向改动,标记为冲突
merged.append(f"<<< CONFLICT >>>\n{c}\n---\n{n}\n>>>")
return '\n'.join(merged)
```
## 6.2.7 记忆写入工具的接口
对智能体暴露的记忆写入接口应该简洁明确：
```python
class MemoryWriter:
"""Agent 可调用的记忆写入工具"""
async def save_user_profile(self, key: str, value: any) -> bool:
"""保存用户属性"""
pass
async def record_feedback(self, action: str, approved: bool,
reason: str) -> bool:
"""记录用户反馈"""
pass
async def update_project_context(self, updates: dict) -> bool:
"""更新项目信息"""
pass
async def add_reference(self, category: str, content: str,
tags: List[str]) -> bool:
"""添加参考资料"""
pass
async def record_lesson(self, lesson: str, confidence: float) -> bool:
"""记录学到的教训"""
pass
```
每次写入都应该触发异步验证和索引更新，确保后续的检索不会出现不一致的状态。
下一节将探讨如何从多个记忆源组装出完整的上下文，为智能体的决策提供支持。
# 6.3 上下文组装引擎与缓存策略
上下文的质量直接决定智能体的推理能力，但来自多个源的信息如何高效组装成最优上下文是一个复杂问题。本节介绍静态与动态上下文的分离、三阶段组装流程、Claude Code 的动态边界机制、OpenClaw 的插件化架构，以及通过缓存策略提升性能的方法。
## 6.3.1 上下文组装的挑战
智能体的推理质量高度依赖于上下文的质量和完整性。但是，一个实时的智能体系统通常要从多个不同的来源拼凑上下文：
* **对话历史**：当前和过去会话的消息
* **用户档案**：用户的偏好、背景、技能
* **项目信息**：当前任务的背景、进度、关键决策
* **参考资料**：可用的代码、文档、最佳实践
* **系统状态**：Agent 本身的能力、当前限制、已知问题
这些来源有不同的更新频率、大小、重要性。简单地将所有内容连接会导致：
1. **上下文膨胀**：超出 LLM 的有效处理能力
2. **噪音淹没信号**：重要信息被海量细节隐埋
3. **冷启动问题**：新会话如何快速获得关键背景
上下文组装引擎的目标是 **动态选择和排序** 这些来源的内容，在容量约束下最大化信息密度。
一个经常被低估的事实是：**表观的模型质量，本质上是上下文质量**。Sebastian Raschka 在分析 Coding Agent 架构时指出，同一个模型在精心设计的 Harness 中表现出的能力，远超在普通聊天界面中的表现。这种差异并非来自模型本身，而是来自 Harness 为模型提供的上下文质量——包括相关的项目信息、精确的工具描述、恰当的历史记录。从这个视角看，上下文组装引擎不仅是一个技术组件，而是决定整个智能体”智商”的关键因素。
## 6.3.2 静态上下文 vs 动态上下文
上下文可分为两类：
**静态上下文** (Static Context)：
* 在会话期间基本不变的信息
* 示例：用户档案、系统能力说明、工具定义
* 特点：高复用性，可缓存
**动态上下文** (Dynamic Context)：
* 因用户当前目标而变化的信息
* 示例：相关的历史记录、当前项目进度、最近的执行结果
* 特点：低复用性，需要实时生成
高效的上下文管理应该：
1. **缓存静态部分**，避免每次重复计算
2. **按需选择动态部分**，避免无关内容
3. **优先级排序**，确保关键信息不被截断
## 6.3.3 上下文组装的三阶段流程
上下文组装过程分为三个关键阶段，下面的流程图展示了完整的上下文组装管道：
```mermaid
graph TD
A["用户查询"] -->|分析意图| B["第一阶段
需求分析"]
B -->|识别所需记忆源| C["需要用户档案?
需要项目信息?
需要历史记录?"]
C -->|并行检索| D["第二阶段
搜索与过滤"]
D -->|用户档案| E["用户档案"]
D -->|项目信息| F["项目信息"]
D -->|历史记录| G["历史记录"]
D -->|参考资料| H["参考资料"]
E --> I["第三阶段
合并与排序"]
F --> I
G --> I
H --> I
I -->|按优先级排序| J["优先级排序
系统 > 用户 > 项目
> 历史 > 参考"]
J -->|填充上下文窗口| K["最终上下文"]
K -->|超出容量?| L["截断处理"]
L -->|生成| M["最终上下文"]
style B fill:#c8e6c9
style D fill:#fff9c4
style I fill:#ffe0b2
style M fill:#f8bbd0
```
图 6-2：上下文组装的三阶段流程
**需求分析阶段**：
使用轻量级分类器识别查询的类型，决定需要哪些记忆源：
```python
class ContextRequirement:
"""上下文需求规范"""
needs_user_profile: bool = False # 需要用户档案
needs_project_context: bool = False # 需要项目信息
needs_recent_history: bool = False # 需要最近历史
needs_references: bool = False # 需要参考资料
needs_feedback: bool = False # 需要反馈记录
def analyze_query(user_message: str) -> ContextRequirement:
"""分析查询内容,确定上下文需求"""
query_lower = user_message.lower()
req = ContextRequirement()
# 启发式规则
if any(word in query_lower for word in
["prefer", "style", "like", "habit"]):
req.needs_user_profile = True
if any(word in query_lower for word in
["project", "task", "status", "progress"]):
req.needs_project_context = True
if any(word in query_lower for word in
["previous", "before", "last time", "remember"]):
req.needs_recent_history = True
if any(word in query_lower for word in
["example", "sample", "pattern", "how to"]):
req.needs_references = True
return req
```
**搜索与过滤阶段**：
根据需求，从各记忆源并行检索：
```python
async def search_memory_sources(requirement: ContextRequirement,
query: str,
memory_manager) -> MemorySearchResult:
"""并行搜索多个记忆源"""
tasks = []
if requirement.needs_user_profile:
tasks.append(memory_manager.search_user_profile(query))
if requirement.needs_project_context:
tasks.append(memory_manager.search_project_context(query))
if requirement.needs_recent_history:
tasks.append(memory_manager.search_recent_history(query))
if requirement.needs_references:
tasks.append(memory_manager.search_references(query))
results = await asyncio.gather(*tasks, return_exceptions=True)
return MemorySearchResult(results)
```
**合并与排序阶段**：
将检索结果合并，按相关性和优先级排序，然后填充上下文直到达到容量限制：
```python
def assemble_context(user_message: str,
search_result: MemorySearchResult,
system_prompt: str,
token_budget: int = 50000) -> str:
"""组装最终的上下文"""
# 优先级:系统提示 > 用户档案 > 项目信息 > 历史 > 参考
prioritized_items = [
("system", system_prompt, 100),
("user_profile", search_result.user_profile, 90),
("project", search_result.project_context, 80),
("history", search_result.recent_history, 70),
("references", search_result.references, 60),
]
# 按优先级排序
prioritized_items.sort(key=lambda x: x[2], reverse=True)
assembled = []
current_tokens = 0
for section_name, content, _ in prioritized_items:
if not content:
continue
content_tokens = estimate_tokens(content)
if current_tokens + content_tokens <= token_budget:
assembled.append(f"## {section_name}\n{content}")
current_tokens += content_tokens
else:
# 容量不足,尝试截断
remaining = token_budget - current_tokens
if remaining > 100: # 最少保留 100 tokens
truncated = truncate_to_tokens(content, remaining)
assembled.append(f"## {section_name} (truncated)\n{truncated}")
break
return '\n\n'.join(assembled)
```
## 6.3.4 Claude Code 的 SYSTEM\_PROMPT\_DYNAMIC\_BOUNDARY
Claude Code 采用了一个聪明的策略来管理上下文大小的不确定性—— **动态边界机制**：
定义一个 **保护区** (Protected Boundary)，其内包含：
* 系统提示
* 当前会话的关键信息
* 用户最新的 1-2 条消息
这个保护区的大小是固定的（约 10-15% 的上下文窗口），不会被其他内容侵占。剩余的空间（约 85-90%）用于动态上下文：
| 区域 | 内容 | 占比 |
| ------------------------------ | --------------------- | ----------- |
| **保护区(Protected)** | System Prompt | \~2% |
| | Current User Messages | \~5% |
| **动态区(Dynamic Context Space)** | User Profile | 按需 |
| | Project Context | 按需 |
| | Recent History | 按需 |
| | References | 按需 |
| | Free Space (buffer) | 剩余 |
| **合计** | Total Context Window | 200K tokens |
这样做的好处是：
1. **可预测性**：系统提示和关键信息永不被截断
2. **灵活性**：动态内容可以从几 KB 扩展到几百 KB
3. **简单性**：不需要复杂的优先级算法，只要在约束内填充
## 6.3.5 OpenClaw 的 ContextEngine 插件架构
OpenClaw 采用了 **插件化的上下文生成**，每个记忆源对应一个插件：
```python
class ContextPlugin:
"""上下文插件的基类"""
async def generate(self, query: str, token_budget: int) -> str:
"""生成该插件贡献的上下文部分"""
raise NotImplementedError
@property
def priority(self) -> int:
"""该插件的优先级(0-100)"""
raise NotImplementedError
@property
def name(self) -> str:
"""插件名称"""
raise NotImplementedError
```
具体实现示例：
```python
class UserProfilePlugin(ContextPlugin):
"""用户档案插件"""
@property
def name(self) -> str:
return "user_profile"
@property
def priority(self) -> int:
return 90
async def generate(self, query: str, token_budget: int) -> str:
profile = await self.memory_manager.get_user_profile()
return self._format_profile(profile, token_budget)
class ProjectContextPlugin(ContextPlugin):
"""项目上下文插件"""
@property
def name(self) -> str:
return "project"
@property
def priority(self) -> int:
return 80
async def generate(self, query: str, token_budget: int) -> str:
# 搜索相关项目信息
relevant_info = await self.search_project_db(query)
return self._format_project_info(relevant_info, token_budget)
```
ContextEngine 协调这些插件的执行：
```python
class ContextEngine:
"""上下文生成引擎"""
def __init__(self):
self.plugins: Dict[str, ContextPlugin] = {}
def register_plugin(self, plugin: ContextPlugin):
"""注册上下文插件"""
self.plugins[plugin.name] = plugin
async def assemble(self, query: str,
token_budget: int = 100000) -> str:
"""根据查询组装上下文"""
# 按优先级排序插件
sorted_plugins = sorted(
self.plugins.values(),
key=lambda p: p.priority,
reverse=True
)
assembled = []
remaining_tokens = token_budget
for plugin in sorted_plugins:
if remaining_tokens < 500: # 最小阈值
break
try:
content = await plugin.generate(query, remaining_tokens)
if content:
assembled.append(content)
remaining_tokens -= estimate_tokens(content)
except Exception as e:
logger.warning(f"Plugin {plugin.name} failed: {e}")
return '\n\n'.join(assembled)
```
这种插件化架构的优势：
* **模块化**：新的上下文源无需修改核心引擎
* **容错性**：单个插件失败不影响整体
* **可观测性**：易于追踪每个插件的贡献
* **可测试性**：可以独立测试每个插件
## 6.3.6 缓存策略
上下文组装的性能瓶颈往往在于重复的搜索和格式化。有效的缓存可以加速 10-100 倍：
```python
class ContextCache:
"""上下文缓存,支持失效管理"""
def __init__(self, ttl_seconds: int = 300):
self.cache: Dict[str, CacheEntry] = {}
self.ttl = ttl_seconds
def get(self, key: str) -> Optional[str]:
"""获取缓存"""
if key in self.cache:
entry = self.cache[key]
if time.time() - entry.timestamp < self.ttl:
return entry.value
else:
del self.cache[key]
return None
def set(self, key: str, value: str, tags: List[str] = None):
"""设置缓存,关联标签用于批量失效"""
self.cache[key] = CacheEntry(value, time.time(), tags or [])
def invalidate_by_tag(self, tag: str):
"""按标签批量失效缓存"""
to_delete = [k for k, v in self.cache.items()
if tag in (v.tags or [])]
for k in to_delete:
del self.cache[k]
```
缓存失效时机：
* **用户档案变更**：失效所有包含 user\_profile 标签的缓存
* **项目信息更新**：失效 project 标签的缓存
* **时间过期**：使用 TTL 自动清理
下一节将深入探讨如何在长对话中自动触发记忆整合，防止上下文溢出。
# 6.4 记忆整合与自动化维护
长对话中的记忆不断膨胀会导致检索低效和成本飙升，需要定期的整合与清理。本节探讨记忆整合的必要性、Claude Code 的 autoDream 三门触发和四阶段流程、OpenClaw 的被动式刷写机制、索引维护策略以及监控和调优方法。
## 6.4.1 记忆整合的必要性
在长对话或多轮会话中，Agent 系统会积累大量的上下文。纯粹地保留所有历史会导致：
1. **上下文膨胀**：LLM 上下文窗口被填满，新的对话空间受限
2. **检索低效**：搜索需要扫描巨量信息，延迟增加
3. **成本上升**：对于按 token 计费的 API，成本线性增长
**记忆整合** (Memory Consolidation)是解决方案：定期将分散的、细粒度的信息压缩、融合成更高层次的摘要，同时保留关键细节，形成稳定的长期记忆。
记忆整合的目标：
* **无损压缩**：重要信息不丢失
* **语义保留**：摘要捕捉原始内容的核心含义
* **可追溯**：保留原始记录供验证
* **增量更新**：仅处理新增内容，避免重复计算
## 6.4.2 Claude Code 的 autoDream 系统详解
Claude Code 实现了一个成熟的自动记忆整合系统，称为 **autoDream**。其核心是三门触发 + 四阶段流程。
### 三门触发机制
autoDream 通过三个独立的触发条件来决定是否启动整合：
**1. 时间门(Time Gate)**：
```python
from datetime import datetime
def check_time_gate(last_consolidation: datetime) -> bool:
"""检查距离上次整合是否超过 24 小时"""
elapsed = datetime.now() - last_consolidation
return elapsed.total_seconds() > 86400 # 24 hours
```
**2. 会话门(Session Gate)**：
```python
def check_session_gate(session_count_since_consolidation: int) -> bool:
"""检查是否已完成 5 个新会话"""
return session_count_since_consolidation >= 5
```
**3. 显式锁(Explicit Lock)**：
```python
def check_explicit_lock(user_signal: str) -> bool:
"""用户明确触发整合(如"保存进度")"""
return "consolidate" in user_signal.lower() or \
"save progress" in user_signal.lower()
```
三个条件采用 **或逻辑**：只要任意一个满足，就启动整合：
```python
def should_consolidate(state: ConsolidationState) -> bool:
"""判断是否应该触发 autoDream"""
time_gate = check_time_gate(state.last_consolidation)
session_gate = check_session_gate(state.sessions_since_consolidation)
explicit_lock = check_explicit_lock(state.latest_user_message)
return time_gate or session_gate or explicit_lock
```
这种设计的好处在于 **灵活性**——用户可以显式触发，系统也会自动触发，确保记忆不会无限膨胀。
### 四阶段整合流程
一旦触发整合，autoDream 执行四个阶段：
**阶段 1：Orient（方向确定）**
分析最近对话的主题和目标，确定整合的范围和重点：
```python
async def orient_phase(recent_conversations: List[Message],
current_project: str) -> OrientResult:
"""确定整合的方向和范围"""
# 提取最近对话的摘要
summary = await extract_summary(recent_conversations)
# 识别关键主题
topics = await identify_topics(summary)
# 确定与项目的相关性
project_relevance = await assess_relevance(summary, current_project)
return OrientResult(
summary=summary,
topics=topics,
project_relevance=project_relevance,
scope="deep" if project_relevance > 0.7 else "shallow"
)
```
**阶段 2：Gather（信息收集）**
从对话历史中提取关键信息，按类型分类：
```python
async def gather_phase(conversations: List[Message],
orient_result: OrientResult) -> GatherResult:
"""收集需要记忆的关键信息"""
gathered = {
'user_preferences': [], # 用户偏好
'project_updates': [], # 项目进度
'learned_lessons': [], # 学到的教训
'decisions': [], # 做出的决策
'errors': [] # 发现的错误
}
for msg in conversations:
if orient_result.scope == "deep":
# 深度收集:细粒度提取
gathered['user_preferences'].extend(
extract_user_preferences(msg)
)
gathered['project_updates'].extend(
extract_project_updates(msg)
)
else:
# 浅层收集:仅提取顶级要点
gathered['decisions'].extend(
extract_top_level_decisions(msg)
)
return GatherResult(gathered=gathered)
```
**阶段 3：Consolidate（整合融合）**
将收集的信息融合到 CLAUDE.md，检测并解决冲突：
```python
async def consolidate_phase(gather_result: GatherResult,
claude_md: dict) -> ConsolidateResult:
"""融合新信息到长期记忆"""
updated_claude_md = copy.deepcopy(claude_md)
# 更新用户档案
for pref in gather_result.gathered['user_preferences']:
existing = find_existing(pref, updated_claude_md['user_profile'])
if existing:
# 冲突解决:新信息覆盖(可配置)
updated_claude_md['user_profile'][existing['key']] = pref
else:
updated_claude_md['user_profile'].append(pref)
# 更新项目进度
for update in gather_result.gathered['project_updates']:
category = update['category']
updated_claude_md['project_context'][category].extend(
update['items']
)
# 添加教训和决策到参考资料
for lesson in gather_result.gathered['learned_lessons']:
updated_claude_md['learning'].append({
'date': datetime.now(),
'content': lesson,
'confidence': 0.8
})
return ConsolidateResult(updated=updated_claude_md)
```
**阶段 4：Prune（清理修剪）**
删除冗余、过期或低价值的信息，保持记忆库的精炼：
```python
async def prune_phase(consolidated: dict,
config: PruneConfig) -> dict:
"""清理过期或冗余信息"""
pruned = copy.deepcopy(consolidated)
# 删除过期的项目信息
cutoff_date = datetime.now() - timedelta(days=config.expiry_days)
pruned['project_context'] = [
item for item in pruned['project_context']
if item.get('date', datetime.now()) > cutoff_date
]
# 删除置信度过低的学习项
pruned['learning'] = [
item for item in pruned['learning']
if item.get('confidence', 1.0) > config.confidence_threshold
]
# 合并相似的信息
pruned['user_profile'] = deduplicate_profiles(
pruned['user_profile']
)
# 压缩冗长的文本
pruned['references'] = compress_references(
pruned['references'],
max_lines=config.max_reference_lines
)
return pruned
```
### autoDream 的完整工作流
autoDream采用四阶段整合流程，将分散的对话信息浓缩为高质量的长期记忆。下面的流程图展示了完整的工作流：
```mermaid
graph TD
A["对话历史"] -->|三门触发| B["是否整合?"]
B -->|时间门
24小时| C["检查时间"]
B -->|会话门
5个会话| D["检查会话数"]
B -->|显式触发
用户触发| E["检查用户信号"]
C --> F{任意条件
满足?}
D --> F
E --> F
F -->|是| G["阶段1:方向确定"]
F -->|否| H["继续积累"]
G -->|分析主题和目标| I["识别关键主题
确定整合范围"]
I -->|深度还是浅层?| J["阶段2:信息收集"]
J -->|提取关键信息| K["用户偏好
项目进度
学到教训
做出决策"]
K -->|进行下一阶段| L["阶段3:整合融合"]
L -->|合并到CLAUDE.md| M["更新用户档案
更新项目进度
添加学习项"]
M -->|清理冗余| N["阶段4:清理修剪"]
N -->|删除过期信息| O["删除旧项目
合并相似内容
压缩冗长文本"]
O -->|原子化保存| P["保存到长期记忆"]
P -->|更新状态| Q["重置计数器
记录时间戳"]
style G fill:#c8e6c9
style J fill:#fff9c4
style L fill:#ffe0b2
style N fill:#ffccbc
style P fill:#f8bbd0
```
图 6-3：autoDream四阶段整合流程
以下是autoDream四阶段整合流程的完整实现：
```python
async def autoDream_consolidation(state: ConsolidationState) -> bool:
"""autoDream 整合的完整流程(WAL-风格回滚)"""
if not should_consolidate(state):
return False
# [WAL] 保存原始状态用于故障回滚
original_claude_md = copy.deepcopy(state.claude_md)
original_state = {
"last_consolidation": state.last_consolidation,
"sessions_since_consolidation": state.sessions_since_consolidation
}
try:
# Phase 1: Orient
orient_result = await orient_phase(
state.recent_conversations,
state.current_project
)
# Phase 2: Gather
gather_result = await gather_phase(
state.conversations,
orient_result
)
# Phase 3: Consolidate
consolidate_result = await consolidate_phase(
gather_result,
state.claude_md
)
# Phase 4: Prune
pruned_result = await prune_phase(
consolidate_result.updated,
config=state.prune_config
)
# [WAL] 原子化保存：先写临时文件，再原子重命名
await save_claude_md_atomic(pruned_result)
# 状态更新(仅在持久化成功后)
state.last_consolidation = datetime.now()
state.sessions_since_consolidation = 0
state.claude_md = pruned_result
state.consolidation_failed_count = 0 # 重置失败计数
logger.info("autoDream consolidation completed successfully")
return True
except Exception as e:
logger.error(f"autoDream consolidation failed: {e}")
# [WAL] 失败回滚：恢复到上次已知的好状态
try:
# 1. 放弃本次持久化,不修改磁盘上的 CLAUDE.md
# 2. 恢复内存中的状态
state.claude_md = original_claude_md
state.last_consolidation = original_state["last_consolidation"]
state.sessions_since_consolidation = original_state["sessions_since_consolidation"]
# 3. 记录故障，允许下次重试
state.consolidation_failed_count += 1
if state.consolidation_failed_count > 3:
logger.warning(
f"Multiple consolidation failures ({state.consolidation_failed_count}) detected. "
"Consider manual review of CLAUDE.md integrity."
)
except Exception as rollback_error:
logger.critical(f"Rollback failed: {rollback_error}. Manual intervention required.")
return False
```
## 6.4.3 OpenClaw 的自动刷写机制
OpenClaw 采用了更简单但高效的 **被动式刷写** 模式：
**触发条件**：
```python
def check_memory_flush_trigger(context_utilization: float) -> bool:
"""当上下文占用达到 70% 时触发刷写"""
return context_utilization >= 0.7
```
**刷写流程**：
1. **生成日志摘要**：总结当前会话的关键事项
2. **提取可学习部分**：从日志中找出值得记忆的信息
3. **合并到 MEMORY.md**：追加新学习到长期记忆
4. **清空日志**：释放对话历史空间
```python
async def flush_memory_to_permanent(daily_log: str,
memory_md: str) -> str:
"""自动刷写:将日志转换为长期记忆"""
# 步骤 1:提取日志摘要
summary = await summarize_log(daily_log, max_lines=10)
# 步骤 2:从摘要中提取学习
learnings = await extract_learnings(summary)
# 步骤 3:合并到 MEMORY.md
updated_memory = memory_md + "\n\n## Recent Learnings\n"
for learning in learnings:
updated_memory += f"- {learning}\n"
# 步骤 4:版本控制
updated_memory = add_metadata(
updated_memory,
last_updated=datetime.now(),
version=increment_version(memory_md)
)
return updated_memory
```
这种方式的优势：
* **简洁高效**：单一触发条件，实现简单
* **确定性**：70% 阈值提供清晰的触发点
* **成本低**：不需要复杂的阶段处理
但劣势是缺乏灵活性——无法按不同的优先级处理信息。
## 6.4.4 记忆索引维护
无论采用哪种整合策略，维护记忆的 **可搜索性** 至关重要。
**向量索引维护**：
```python
class EmbeddingIndex:
"""记忆的向量索引"""
async def add_entry(self, memory_id: str, content: str):
"""添加新的记忆条目到索引"""
embedding = await embed_text(content)
self.index[memory_id] = {
'embedding': embedding,
'content': content,
'timestamp': datetime.now()
}
async def search(self, query: str, top_k: int = 5) -> List[str]:
"""向量相似度搜索"""
query_embedding = await embed_text(query)
scores = []
for mid, entry in self.index.items():
similarity = cosine_similarity(
query_embedding,
entry['embedding']
)
scores.append((mid, similarity, entry['content']))
# 按相似度排序,返回 Top-K
return [content for _, _, content in
sorted(scores, key=lambda x: x[1], reverse=True)[:top_k]]
async def rebuild_incremental(self, new_entries: List[dict]):
"""增量更新索引"""
for entry in new_entries:
await self.add_entry(entry['id'], entry['content'])
```
**关键词索引维护**：
```python
class KeywordIndex:
"""基于关键词的反向索引"""
def __init__(self):
self.index: Dict[str, List[str]] = {} # keyword -> memory_ids
def add_entry(self, memory_id: str, content: str):
"""提取关键词并建立索引"""
keywords = extract_keywords(content) # 使用 TF-IDF 或更简单的方法
for keyword in keywords:
if keyword not in self.index:
self.index[keyword] = []
self.index[keyword].append(memory_id)
def search(self, query: str) -> Set[str]:
"""关键词搜索返回所有匹配的记忆ID"""
query_keywords = extract_keywords(query)
matching_ids = set()
for keyword in query_keywords:
matching_ids.update(self.index.get(keyword, []))
return matching_ids
```
**垃圾清理**：
```python
async def cleanup_old_memories(memory_store,
retention_days: int = 90):
"""定期清理过期记忆"""
cutoff = datetime.now() - timedelta(days=retention_days)
for memory_id in memory_store.list_all():
metadata = memory_store.get_metadata(memory_id)
if metadata['last_accessed'] < cutoff:
logger.info(f"Removing unused memory: {memory_id}")
memory_store.delete(memory_id)
# 同步更新索引
await embedding_index.remove(memory_id)
keyword_index.remove(memory_id)
```
## 6.4.5 记忆整合的监控和调优
为了持续改进整合策略，应该监控关键指标：
```python
class ConsolidationMetrics:
"""记忆整合的性能指标"""
def __init__(self):
self.consolidation_latency = [] # 整合耗时
self.context_compression_ratio = [] # 压缩率
self.memory_size_growth = [] # 记忆库增长
self.search_latency = [] # 搜索响应时间
self.false_negatives = [] # 搜索未命中率
async def record_consolidation(self,
before_size: int,
after_size: int,
duration_ms: float):
"""记录整合操作"""
ratio = after_size / before_size if before_size > 0 else 1.0
self.consolidation_latency.append(duration_ms)
self.context_compression_ratio.append(ratio)
async def analyze(self) -> ConsolidationReport:
"""生成整合性能报告"""
return ConsolidationReport(
avg_latency=statistics.mean(self.consolidation_latency),
avg_compression=statistics.mean(self.context_compression_ratio),
p95_latency=statistics.quantiles(
self.consolidation_latency,
n=20
)[18], # 95th percentile
)
```
通过监控这些指标，可以动态调整触发条件和清理策略，保持整个系统的最优性能。
下一节将通过实战代码，演示如何实现完整的 MiniHarness 记忆子系统。
# 6.5 MiniHarness 记忆系统架构
本节从“设计决策”角度讲解记忆系统的核心架构。完整实现代码已分离至 `lab/mini_harness/memory/` 目录，本文聚焦核心概念、关键权衡和实现要点。
## 6.5.1 存储层：MemoryEntry 与 MemoryStore
记忆条目是系统的基本单元。关键设计决策：
**为什么使用 Markdown + YAML frontmatter？**
选择文本格式而非二进制 DB，有三个考量：
1. “便于人工审查”：用户可直接读写存储文件，便于调试
2. “版本控制友好”：支持 Git diff，可追踪记忆演变
3. “轻量化”：无需外部数据库依赖
```python
from datetime import datetime
from typing import List, Optional
class MemoryEntry:
"""包含 5 个维度的记忆条目"""
def __init__(self, memory_id: str, content: str,
memory_type: str = "episodic", # 类型划分
tags: List[str] = None,
confidence: float = 1.0, # 置信度
expiry: Optional[datetime] = None): # 过期时间
self.id = memory_id
self.content = content
self.type = memory_type
self.tags = tags or []
self.confidence = confidence
self.expiry = expiry
# 自动跟踪时间戳和版本
self.created_at = datetime.now()
self.last_modified = datetime.now()
self.version = 1
```
**存储组织策略**：`by_type/` 分类结构。文件组织如下：
```
memory_dir/
by_type/
user/ （用户偏好、档案）
project/ （项目进度、决策）
episodic/ （每日交互记录）
reference/ （模式、示例）
feedback/ （用户反馈、评价）
```
这样设计的好处：
* “热路径优化”：查询特定类型无需全表扫描
* “权限隔离”：便于未来细粒度访问控制
* “过期清理”：批量删除某类型过期项时高效
关键实现位置：`lab/mini_harness/memory/storage.py`
## 6.5.2 上下文组装：需求驱动的选择性加载
ContextAssembler 解决核心问题：“给定用户输入，应该加载哪些记忆？”
**三层决策链路**：
```python
async def analyze_query(self, user_message: str) -> MemoryRequirement:
"""启发式规则:输入 -> 需求"""
req = MemoryRequirement()
msg_lower = user_message.lower()
# 关键词触发
if any(w in msg_lower for w in ['prefer', 'style', 'like']):
req.needs_user_profile = True
if any(w in msg_lower for w in ['project', 'task', 'status']):
req.needs_project_context = True
# ... 其他规则
# 默认回退:当无法识别时加载用户档案
if not any([...]):
req.needs_user_profile = True
return req
```
**为什么选择启发式而非 LLM？**
* “延迟考量”：LLM 调用需另外 1-2 秒，用户感受延迟
* “成本考量”：每次查询都调 LLM 会显著增加开销
* “可调试性”：规则清晰，易于审计和修改
**并行收集 + Token 预算**：
```python
async def assemble(self, user_message: str) -> str:
requirement = await self.analyze_query(user_message)
# 根据需求并行加载多个记忆源
tasks = []
if requirement.needs_user_profile:
tasks.append(('user_profile', self._gather_user_profile()))
if requirement.needs_project_context:
tasks.append(('project', self._gather_project_context()))
# ... 其他需求
# 并行执行,节省 I/O 等待
results = await asyncio.gather(*[task[1] for task in tasks])
# 按优先级排序,限制总大小
# 保证组装结果不超过 token_budget (如 50k)
```
关键权衡：“所有相关记忆”vs“上下文窗口限制”，通过 Token 预算解决。
关键实现位置：`lab/mini_harness/memory/context.py`
## 6.5.3 整合层：四阶段记忆巩固
ConsolidationEngine 实现“睡眠学习”机制——后台自动处理信息。
**三门触发条件** （防止过度整合）：
```python
def should_consolidate(self) -> bool:
# 时间门:距上次整合已超 24 小时
time_gate = (datetime.now() - self.state.last_consolidation
> timedelta(hours=24))
# 会话门:至少完成 5 次对话
session_gate = self.state.sessions_since_consolidation >= 5
# 显式门:由外部调用者手动触发(如用户主动要求)
return time_gate or session_gate
```
**四阶段流程**（基于 autoDream）：
1. “确定阶段”(Orient)：分析最近消息的主题
2. “收集阶段”(Gather)：提取偏好、项目更新、教训、决策
3. “融合阶段”(Consolidate)：写入长期记忆
4. “清理阶段”(Prune)：删除过期项和低置信度项
```python
async def orient_phase(self, recent_messages: List[str]) -> Dict:
"""识别关键主题"""
topics = set()
for msg in recent_messages[-5:]:
if any(w in msg.lower() for w in ['bug', 'error']):
topics.add('issues')
if any(w in msg.lower() for w in ['feature', 'new']):
topics.add('features')
return {'summary': summary, 'topics': list(topics)}
async def gather_phase(self, messages: List[str], orient_result: Dict) -> Dict[str, List[str]]:
"""从消息中抽取不同维度的信息"""
gathered = {
'user_preferences': [], # 用户习惯
'project_updates': [], # 进度变化
'learned_lessons': [], # 知识积累
'decisions': [] # 重要决策
}
# 按关键词提取相关句子
return gathered
async def consolidate_phase(self, gathered: Dict) -> bool:
"""写入对应类型的存储"""
if gathered['user_preferences']:
entry = MemoryEntry(..., memory_type='user')
await self.memory_store.save(entry)
# ...
return True
async def prune_phase(self) -> int:
"""清理两类项:过期项 + 低置信度项"""
removed = await self.memory_store.cleanup_expired()
# 清理 confidence < 0.3 且超过 30 天未更新的项
return removed + low_confidence_count
```
**设计权衡**：
* “自动整合 vs 隐私”：整合过程完全本地化，不上传服务器
* “频率 vs 成本”：三门限制防止频繁整合浪费资源
* “保留 vs 清理”：置信度和过期时间的组合清理策略
关键实现位置：`lab/mini_harness/memory/consolidation.py`
## 6.5.4 系统集成要点
一个完整的使用流程包括：
```python
# 初始化三个核心组件
memory_store = MemoryStore("/path/to/memory")
assembler = ContextAssembler(memory_store, token_budget=50000)
consolidation = ConsolidationEngine(memory_store)
# 在每次对话前:组装上下文
context = await assembler.assemble(user_message)
# 在后台:定期整合
if consolidation.should_consolidate():
success = await consolidation.consolidate(recent_messages)
```
**核心设计特点**：
1. “模块化”：存储、组装、整合相互独立，便于扩展
2. “异步友好”：全 async/await，支持并发操作
3. “可观测”：YAML frontmatter 和文本格式便于审查
4. “防御式编程”：大量 try-catch 和类型检查，处理不完整数据
完整代码参考 `lab/mini_harness/memory/` 目录的三个模块。
# 本章小结
本章探讨了记忆与上下文管理这一关键子系统，以下是核心认识的汇总。
## 核心概念回顾
第六章深入探讨了智能体系统最复杂也最关键的子系统——记忆与上下文管理。核心认识包括：
### 多层记忆架构的必要性
任何实用的智能体系统都需要三个独立的记忆层：
1. **工作记忆**：当前会话的实时上下文，驻留在 LLM 的上下文窗口中
2. **短期记忆**：跨会话但有时限的信息，存储在内存或快速存储中
3. **长期记忆**：持久化的知识库，支持高效的检索和版本控制
这三层形成递进的关系：工作记忆溢出时流入短期，短期积累到阈值时压缩进长期。Claude Code 实现完整的三层模型，而 OpenClaw 采用简化的双层模型（直接从工作跳到长期）。Harness 建议采用 **自适应三层**，在灵活性和复杂度之间取得平衡。
### 可写入式记忆的重要性
传统的智能体记忆往往是单向的——Agent 只读取预设的记忆。强大的系统应该支持 Agent **主动创建和更新记忆**。这要求：
* **原子性保证**：避免并发修改导致的数据不一致
* **版本控制**：每次更新都可回溯
* **Frontmatter 结构**：分离元数据和内容，支持快速索引
Claude Code 提出的 **记忆类型分类** (user/feedback/project/reference)简化了这个问题——不同类型的记忆有不同的更新策略和检索方式。
### 上下文组装是智能体性能的关键
不是所有的记忆都应该在每次请求时加载。高效的上下文组装需要：
* **需求分析**：识别查询需要哪些记忆源
* **并行检索**：从多个源并发获取内容
* **智能排序**：按优先级和相关性排列，优先加载关键信息
* **容量管理**：在 token 预算内最大化信息密度
Claude Code 的 **动态边界机制** （保护系统提示和关键信息，其余空间动态分配）是一个优雅的解决方案。
### 记忆整合是长期对话的保证
在长对话中，如果不进行整合，上下文会无限膨胀。Claude Code 的 **autoDream** 系统提供了成熟的范式：
* **三门触发**：时间门（24h）、会话门（5 次）、显式锁，降低整合的频率同时保证灵活性
* **四阶段流程**：Orient → Gather → Consolidate → Prune，分离关注点
* **增量更新**：仅处理新信息，避免重复计算
相比 OpenClaw 的被动式刷写（70% 上下文触发），autoDream 更加主动和可控。
## 两个参考系统的对比与权衡
| 特征 | Claude Code | OpenClaw | Harness 建议 |
| ----- | ----------- | ------------ | ---------- |
| 架构复杂度 | 中（三层） | 低（双层） | 中（自适应三层） |
| 整合策略 | 主动（定时+计数） | 被动（阈值触发） | 主动+被动混合 |
| 记忆类型 | 分类（4 类） | 统一 | 分类（5+ 类） |
| 检索方式 | 格式化提取 | 混合搜索（关键词+向量） | 混合+向量 |
| 实现难度 | 中等 | 易 | 中等 |
| 适用场景 | 项目驱动应用 | 对话型应用 | 通用应用 |
**选型建议**：
* 代码助手、研究工具 → 参考 Claude Code 的细粒度记忆
* 对话机器人、客服系统 → 参考 OpenClaw 的简洁性
* 通用智能体系统 → 采用 Harness 的自适应方案
## 实现要点
### 1. 存储抽象必须支持
* **Markdown Frontmatter**：元数据 + 内容分离，便于索引和版本控制
* **文件系统组织**：按类型分目录，支持快速列表和搜索
* **版本备份**：每次写入前备份，支持回滚
### 2. 上下文组装的三阶段模型
模型流程如下：
```
需求分析 → 并行搜索 → 优先级排序 + 容量管理
```
轻量级分类器识别查询需要哪些记忆，并行从各源检索，最后按优先级填充。
### 3. 整合的四阶段流程
流程如下：
```mermaid
flowchart LR
A["Orient
分析主题"] --> B["Gather
提取信息"]
B --> C["Consolidate
融合"]
C --> D["Prune
清理"]
style A fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style B fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style C fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style D fill:#ffcccc,stroke:#c62828,stroke-width:2px,color:#000000
```
每个阶段都有明确的责任，支持监控和调试。
### 4. 索引维护的必要性
* **向量索引**：语义搜索，捕捉语义相似的记忆
* **关键词索引**：精确搜索，捕捉精确的事实
* **过期清理**：定期删除低价值的旧项
## 常见陷阱与解决方案
### 陷阱 1：记忆无限增长
**症状**：随着对话轮数增加，系统响应变慢，记忆库无限膨胀
**解决**：
* 设置明确的整合触发条件（时间或会话计数）
* 定期运行清理任务，删除过期项
* 监控记忆库大小，当超过阈值时强制整合
### 陷阱 2：整合丢失关键信息
**症状**：某些重要上下文被压缩或删除，导致智能体犯重复错误
**解决**：
* 使用多级重要性评分，标记关键项
* 保留原始记录供审计，不直接删除
* 使用置信度字段，低置信度项保留更久
### 陷阱 3：上下文装配不当导致无关信息泛滥
**症状**：组装的上下文包含大量不相关信息，noise 淹没 signal
**解决**：
* 实现需求分析模块，精准选择记忆源
* 为每个记忆源设置相关性阈值
* 支持显式查询语言，用户可以指定需要的记忆类型
### 陷阱 4：并发修改导致数据不一致
**症状**：多个智能体实例同时修改同一记忆，导致不可预测的结果
**解决**：
* 使用版本号或时间戳，实现乐观锁
* 提供 3-way merge 算法处理冲突
* 对关键记忆使用悲观锁（数据库事务）
## 性能优化要点
### 1. 缓存策略
* 静态上下文（系统提示、用户档案）可缓存 5-10 分钟
* 动态上下文（最近历史、项目进度）缓存 30 秒
* 使用 tag-based 失效，支持精细控制
### 2. 索引优化
* 使用倒排索引加速关键词搜索(O(1) lookup)
* 使用向量量化或产品量化加速向量搜索
* 定期重建索引，删除已删除项的索引条目
### 3. 异步处理
* 整合操作在后台执行，不阻塞主线程
* 索引更新异步进行
* 批量删除和清理操作优化为批量操作
## 监控和可观测性
为了保持系统健康，应该监控以下指标：
```python
class MemoryMetrics:
memory_size_bytes: int # 记忆库总大小
consolidation_latency_ms: float # 整合耗时
context_assembly_latency_ms: float # 上下文组装耗时
search_hit_rate: float # 搜索命中率
cache_hit_rate: float # 缓存命中率
average_confidence: float # 记忆平均置信度
expired_entries_per_day: int # 每日过期项数
```
通过这些指标，可以及时发现问题（如：缓存命中率下降 → 可能需要调整 TTL；搜索命中率下降 → 可能索引过时）。
## 下一步方向
### 1. 分布式记忆系统
本章的实现都是单机的。对于多智能体并发场景，需要考虑：
* 中央记忆服务器（如 Redis 或 PostgreSQL）
* 分布式一致性协议(Raft、Paxos)
* 记忆同步和冲突解决
### 2. 高级检索技术
* 混合检索：结合关键词和向量，提高召回率
* 知识图谱：将记忆组织成图结构，支持关联查询
* 多模态记忆：支持图像、音频等非文本形式
### 3. 个性化和学习
* 智能体从用户反馈中主动调整记忆策略
* 动态调整整合触发条件，平衡成本和准确性
* 学习用户的查询模式，优化上下文组装
## 关键收获
1. **记忆是智能体的“第二大脑”**，良好的记忆系统是智能体能力的倍增器
2. **三层架构是标准范式**，工作 → 短期 → 长期的递进关系
3. **可写入性很关键**，Agent 应主动创建和更新记忆
4. **上下文装配不是简单连接**，需要需求分析、并行搜索、智能排序
5. **自动化整合不可避免**，但需要谨慎设计触发条件和流程
记忆系统的设计直接影响智能体的长期能力。投入时间建立坚实的记忆基础，会在后续的复杂应用中获得巨大收益。
# 第七章：模型集成与输出治理
## 章引言
模型集成是智能体系统与 LLM 的边界。设计不当的集成会导致：
* 幻觉（输出不真实信息）
* 性能问题（过度推理、令牌浪费）
* 安全隐患（输出不可控）
* 兼容性问题（难以支持多个模型）
本章研究如何设计一个健壮、灵活、高效的模型集成层，包括多模型切换、输出解析、质量门控、幻觉检测等机制。
## 核心设计问题
1. **模型抽象**：如何设计统一接口支持多个模型（Claude、GPT、DeepSeek 等）？
2. **输出解析**：如何从原始 API 响应中安全地提取和验证结构化输出？
3. **质量保证**：在工具调用执行前如何验证输出的合法性？
4. **幻觉检测**：如何识别和防止智能体调用不存在的工具或生成错误的参数？
## 参考系统的方法
**OpenClaw**：支持 Claude/GPT/DeepSeek/Gemini/Ollama，带模型回退链路
**Claude Code**：绑定 Claude，专注于输出质量和推理预算管理
## 本章结构
* 7.1：模型抽象层
* 7.2：结构化输出解析
* 7.3：输出质量门控
* 7.4：幻觉检测与修复
* 7.5：推理预算管理
* 7.6：MiniHarness 输出治理
* 本章小结
模型集成层是智能体可靠性的最后防线。
# 7.1 模型抽象层设计
模型抽象层连接智能体应用与具体LLM API，支持灵活的多模型或单模型策略。本节介绍配置管理系统、故障转移链路、Provider接口设计和模型选择引擎。
## 7.1.1 核心概念
模型抽象层是连接智能体应用与具体 LLM API 的中间层。其目标是：
1. **统一接口**：提供一致的 API，支持 Claude、GPT、DeepSeek、Gemini 等多种模型
2. **灵活切换**：动态选择或回退模型，无需修改业务逻辑
3. **配置驱动**：通过配置文件管理模型选择、默认值、故障转移策略
4. **错误隔离**：单个模型的故障不影响整个系统
## 7.1.2 设计权衡：多模型 vs 单模型绑定
**Claude Code 方案（单模型绑定）**
* 绑定 Claude 模型家族(Opus/Sonnet/Haiku)
* 专注于版本管理与推理预算调优
* 深度集成 Adaptive Thinking 等 Claude 特性
* 场景：需要最佳性能、深度功能集成、模型特性充分利用
**OpenClaw 方案（多模型支持）**
* 支持多供应商切换(Claude/GPT/DeepSeek/Gemini/Ollama)
* 供应商认证与接入配置(openclaw\.json)
* 模型故障转移链路(fallback mechanism)
* 场景：需要成本优化、供应商多元化、灰度迁移
选择建议：
* 小团队初期选择单模型绑定降低复杂度
* 成熟产品需要多模型以应对供应商依赖和成本波动
## 7.1.3 配置管理系统
**模型选择策略**
模型选择的实现方式如下：
```python
from enum import Enum
from dataclasses import dataclass
from typing import Optional, List
class ModelProviderType(Enum):
CLAUDE = "claude"
OPENAI = "openai"
DEEPSEEK = "deepseek"
GEMINI = "gemini"
OLLAMA = "ollama"
@dataclass
class ModelConfig:
"""模型配置对象"""
provider: ModelProviderType
model_id: str
api_key: Optional[str] = None
api_endpoint: Optional[str] = None
timeout: int = 30
max_tokens: int = 4096
temperature: float = 0.7
@dataclass
class ModelSelectionPolicy:
"""模型选择策略"""
primary: ModelConfig
fallback_chain: List[ModelConfig] = None
cost_threshold: float = None # 成本上限,超过则切换
latency_threshold: int = None # 延迟上限,超过则切换
```
### 故障转移链路
故障转移链路定义了模型失败时的替代方案：
```mermaid
flowchart TD
A["应用请求"] --> B["Primary Model"]
B --> C{成功?}
C -->|是| D["成功 ✓"]
C -->|失败/超时/配额| E["Fallback-1 Model"]
E --> F{成功?}
F -->|是| D
F -->|失败| G["Fallback-2 Model"]
G --> H{成功?}
H -->|是| D
H -->|失败| I["Circuit Breaker
返回错误 ✗"]
style A fill:#e8f4f8,stroke:#4a90a4,stroke-width:2px,color:#000000
style B fill:#e8f4e8,stroke:#4a9044,stroke-width:2px,color:#000000
style E fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style G fill:#fff4e8,stroke:#a49044,stroke-width:2px,color:#000000
style D fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000000
style I fill:#ffcccc,stroke:#c62828,stroke-width:2px,color:#000000
```
实现示例：
```python
import time
class CircuitBreaker:
"""熔断器,跟踪模型健康状态"""
def __init__(self, failure_threshold: int = 5, reset_timeout: int = 60):
self.failure_count = 0
self.failure_threshold = failure_threshold
self.reset_timeout = reset_timeout
self.state = "closed" # closed, open, half-open
self.last_failure_time = None
def record_success(self):
self.failure_count = 0
self.state = "closed"
def record_failure(self):
self.failure_count += 1
if self.failure_count >= self.failure_threshold:
self.state = "open"
self.last_failure_time = time.time()
def is_available(self) -> bool:
if self.state == "closed":
return True
if self.state == "open":
if time.time() - self.last_failure_time > self.reset_timeout:
self.state = "half-open"
return True
return False
return True # half-open 允许尝试
```
### Provider 接口设计
Provider 接口定义了模型的核心操作。使用 Python Protocol 提供灵活的鸭子类型：
```python
from typing import Protocol, List, Any, Optional
class Message:
def __init__(self, role: str, content: str):
self.role = role # "user", "assistant"
self.content = content
class ProviderResponse:
def __init__(self, content: str, tokens_used: int, model: str):
self.content = content
self.tokens_used = tokens_used
self.model = model
class ModelProvider(Protocol):
"""LLM 供应商的统一接口"""
def complete(
self,
messages: List[Message],
temperature: float = 0.7,
max_tokens: int = 4096,
) -> ProviderResponse:
"""完整的模型调用(无流式)"""
...
def stream(
self,
messages: List[Message],
temperature: float = 0.7,
max_tokens: int = 4096,
):
"""流式模型调用,逐块返回"""
...
def estimate_tokens(self, text: str) -> int:
"""估算文本的 token 数"""
...
def validate_config(self) -> bool:
"""验证配置有效性(API 密钥等)"""
...
```
### 具体实现：Claude Provider
Claude Provider的具体实现如下：
```python
import anthropic
from typing import Generator
class ClaudeProvider:
def __init__(self, config: ModelConfig):
self.config = config
self.client = anthropic.Anthropic(api_key=config.api_key)
def complete(
self,
messages: List[Message],
temperature: float = 0.7,
max_tokens: int = 4096,
) -> ProviderResponse:
"""Claude 完整调用"""
api_messages = [
{"role": msg.role, "content": msg.content}
for msg in messages
]
response = self.client.messages.create(
model=self.config.model_id,
max_tokens=max_tokens,
temperature=temperature,
messages=api_messages,
)
return ProviderResponse(
content=response.content[0].text,
tokens_used=response.usage.output_tokens
+ response.usage.input_tokens,
model=self.config.model_id,
)
def stream(
self,
messages: List[Message],
temperature: float = 0.7,
max_tokens: int = 4096,
) -> Generator[str, None, None]:
"""Claude 流式调用"""
api_messages = [
{"role": msg.role, "content": msg.content}
for msg in messages
]
with self.client.messages.stream(
model=self.config.model_id,
max_tokens=max_tokens,
temperature=temperature,
messages=api_messages,
) as stream:
for text in stream.text_stream:
yield text
def estimate_tokens(self, text: str) -> int:
"""Claude token 计数"""
response = self.client.messages.count_tokens(messages=[
{"role": "user", "content": text}
])
return response.input_tokens
def validate_config(self) -> bool:
try:
self.estimate_tokens("test")
return True
except:
return False
```
### 模型选择引擎
模型选择引擎的实现方式如下：
```python
class ModelSelectionEngine:
def __init__(self, policy: ModelSelectionPolicy):
self.policy = policy
self.breakers = {}
self._init_breakers()
def _init_breakers(self):
for config in [self.policy.primary] + (
self.policy.fallback_chain or []
):
self.breakers[config.model_id] = CircuitBreaker()
def select_model(self) -> ModelProvider:
"""根据健康状态选择可用模型"""
candidates = [self.policy.primary] + (
self.policy.fallback_chain or []
)
for config in candidates:
breaker = self.breakers[config.model_id]
if breaker.is_available():
return self._create_provider(config)
raise Exception("所有模型不可用")
def mark_failure(self, model_id: str):
"""记录模型故障"""
if model_id in self.breakers:
self.breakers[model_id].record_failure()
def mark_success(self, model_id: str):
"""记录模型成功"""
if model_id in self.breakers:
self.breakers[model_id].record_success()
def _create_provider(self, config: ModelConfig):
if config.provider == ModelProviderType.CLAUDE:
return ClaudeProvider(config)
# ... 其他 provider 实现
```
### 配置文件管理
配置文件的结构示例如下：
```json
{
"model_selection": {
"primary": {
"provider": "claude",
"model_id": "claude-sonnet-4-6",
"timeout": 30,
"max_tokens": 4096
},
"fallback_chain": [
{
"provider": "openai",
"model_id": "gpt-5.4",
"timeout": 30,
"max_tokens": 4096
},
{
"provider": "deepseek",
"model_id": "deepseek-chat",
"timeout": 30,
"max_tokens": 4096
}
],
"cost_threshold": 0.05,
"latency_threshold": 5000
}
}
```
### 模型抽象层架构图
模型抽象层的整体架构如下所示：
```mermaid
graph LR
A["应用程序"] -->|请求调用| B["模型路由器"]
B -->|选择提供商| C["Provider 适配器"]
C -->|调用 API| D["Claude"]
C -->|调用 API| E["OpenAI GPT"]
C -->|调用 API| F["Google Gemini"]
style A fill:#e1f5ff
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#c8e6c9
style E fill:#c8e6c9
style F fill:#c8e6c9
```
图 7-1：模型抽象层架构 —— 应用通过统一的路由器访问多个模型提供商
### 总结
模型抽象层通过 Provider 接口、配置驱动的选择策略和故障转移机制，实现了：
* 灵活的多模型支持或单模型绑定
* 透明的故障切换，对上层应用无感
* 可观测的模型健康度和选择决策
* 成本与性能的可控权衡
这为后续的输出解析、质量门控奠定了基础。
# 7.2 结构化输出解析与校验
模型输出需要被转换为类型安全的结构化形式才能可靠地驱动后续操作。本节介绍 Claude 的消息类型系统、非流式与流式响应的解析方法、Pydantic 参数验证以及完整的解析管道设计。
## 7.2.1 核心问题
原始 API 响应是无类型的字符串或弱类型的 JSON。要将其安全地转换为类型安全的结构化表示，需要解决：
1. **类型识别**：区分文本、工具调用、思考块等不同内容类型
2. **增量解析**：处理流式响应的片段化更新
3. **结构校验**：验证解析结果的完整性与合法性
4. **向后兼容**：支持不同 API 版本和模型的差异
## 7.2.2 Claude 的消息类型系统
Claude API 返回的消息(Message)由多个内容块(ContentBlock)组成，每个块有不同的类型：
```python
from dataclasses import dataclass
from enum import Enum
from typing import Optional, List, Any
class ContentBlockType(Enum):
TEXT = "text"
TOOL_USE = "tool_use"
THINKING = "thinking"
@dataclass
class TextBlock:
"""文本内容块"""
type: str = "text"
text: str = ""
@dataclass
class ToolUseBlock:
"""工具调用块"""
type: str = "tool_use"
id: str = ""
name: str = ""
input: dict = None # JSON 输入参数
@dataclass
class ThinkingBlock:
"""思考过程块(Adaptive Thinking)"""
type: str = "thinking"
thinking: str = ""
ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock
@dataclass
class ParsedMessage:
"""解析后的完整消息"""
content_blocks: List[ContentBlock]
stop_reason: str # "end_turn", "tool_use", "max_tokens"
tokens_used: int
def text_content(self) -> str:
"""提取所有文本内容"""
texts = [
block.text for block in self.content_blocks
if isinstance(block, TextBlock)
]
return "".join(texts)
def tool_calls(self) -> List[ToolUseBlock]:
"""提取所有工具调用"""
return [
block for block in self.content_blocks
if isinstance(block, ToolUseBlock)
]
def thinking_content(self) -> Optional[str]:
"""提取思考过程"""
for block in self.content_blocks:
if isinstance(block, ThinkingBlock):
return block.thinking
return None
```
### 非流式解析
完整响应的解析实现方式如下：
```python
import json
from typing import Dict, Any
class ResponseParser:
"""API 响应解析器"""
@staticmethod
def parse_response(raw_response: Dict[str, Any]) -> ParsedMessage:
"""解析完整的 API 响应"""
content_blocks = []
# 遍历响应的 content 数组
for block in raw_response.get("content", []):
block_type = block.get("type")
if block_type == "text":
content_blocks.append(TextBlock(
type="text",
text=block.get("text", "")
))
elif block_type == "tool_use":
# 工具调用:需要解析 JSON 输入
input_data = block.get("input", {})
if isinstance(input_data, str):
try:
input_data = json.loads(input_data)
except json.JSONDecodeError as e:
# 捕获 JSON 解析失败,记录错误并使用空对象
print(f"警告: JSON 解析失败: {e}, 使用空参数")
input_data = {}
content_blocks.append(ToolUseBlock(
type="tool_use",
id=block.get("id", ""),
name=block.get("name", ""),
input=input_data
))
elif block_type == "thinking":
content_blocks.append(ThinkingBlock(
type="thinking",
thinking=block.get("thinking", "")
))
return ParsedMessage(
content_blocks=content_blocks,
stop_reason=raw_response.get("stop_reason", "end_turn"),
tokens_used=(
raw_response.get("usage", {}).get("input_tokens", 0) +
raw_response.get("usage", {}).get("output_tokens", 0)
)
)
```
### 流式解析
流式响应分块到达，需要增量构建完整消息。关键是跟踪当前正在构建的块状态：
```python
import json
from enum import Enum
from typing import Dict, Any, Optional
class StreamEventType(Enum):
MESSAGE_START = "message_start"
CONTENT_BLOCK_START = "content_block_start"
CONTENT_BLOCK_DELTA = "content_block_delta"
CONTENT_BLOCK_STOP = "content_block_stop"
MESSAGE_DELTA = "message_delta"
MESSAGE_STOP = "message_stop"
class StreamingParser:
"""流式响应解析器"""
def __init__(self):
self.content_blocks = []
self.current_block = None
self.block_index = 0
self.stop_reason = "end_turn"
self.tokens_used = 0
def process_event(self, event: Dict[str, Any]) -> Optional[ParsedMessage]:
"""处理单个流式事件"""
event_type = event.get("type")
if event_type == "message_start":
# 消息开始,重置状态
self.content_blocks = []
self.current_block = None
self.block_index = 0
usage = event.get("message", {}).get("usage", {})
self.tokens_used = usage.get("input_tokens", 0)
elif event_type == "content_block_start":
# 新块开始
self.block_index = event.get("index", 0)
block_info = event.get("content_block", {})
block_type = block_info.get("type")
if block_type == "text":
self.current_block = TextBlock(type="text", text="")
elif block_type == "tool_use":
self.current_block = ToolUseBlock(
type="tool_use",
id=block_info.get("id", ""),
name=block_info.get("name", ""),
input={}
)
elif block_type == "thinking":
self.current_block = ThinkingBlock(type="thinking", thinking="")
# 确保数组足够长
while len(self.content_blocks) <= self.block_index:
self.content_blocks.append(None)
elif event_type == "content_block_delta":
# 块内容增量更新
delta = event.get("delta", {})
delta_type = delta.get("type")
if delta_type == "text_delta":
if isinstance(self.current_block, TextBlock):
self.current_block.text += delta.get("text", "")
elif delta_type == "input_json_delta":
# 工具调用的 JSON 增量
if isinstance(self.current_block, ToolUseBlock):
json_str = delta.get("partial_json", "")
try:
self.current_block.input = json.loads(json_str)
except json.JSONDecodeError:
pass
elif delta_type == "thinking_delta":
if isinstance(self.current_block, ThinkingBlock):
self.current_block.thinking += delta.get("thinking", "")
elif event_type == "content_block_stop":
# 块完成,保存到数组
if self.current_block is not None:
self.content_blocks[self.block_index] = self.current_block
self.current_block = None
elif event_type == "message_stop":
# 消息完成
self.stop_reason = event.get("message", {}).get("stop_reason",
"end_turn")
usage = event.get("message", {}).get("usage", {})
self.tokens_used += usage.get("output_tokens", 0)
# 返回完整的解析结果
return ParsedMessage(
content_blocks=[b for b in self.content_blocks if b],
stop_reason=self.stop_reason,
tokens_used=self.tokens_used
)
return None # 消息未完成
```
### 使用流式解析器
流式解析器的具体使用方式如下：
```python
import json
class StreamIterator:
"""流式迭代器,隐藏解析复杂性"""
def __init__(self, api_stream):
self.api_stream = api_stream
self.parser = StreamingParser()
def __iter__(self):
for event_data in self.api_stream:
try:
event = json.loads(event_data)
except json.JSONDecodeError as e:
# JSON 解析失败,记录错误并跳过该事件
print(f"警告: 流式事件 JSON 解析失败: {e}, 跳过该事件")
continue
result = self.parser.process_event(event)
if result is not None:
yield result
# 使用示例
with client.messages.stream(...) as stream:
for parsed_message in StreamIterator(stream):
print(f"接收到消息: {parsed_message.text_content()}")
for tool_call in parsed_message.tool_calls():
print(f" 工具调用: {tool_call.name}({tool_call.input})")
```
### Pydantic 校验
使用 Pydantic 定义预期的工具参数结构，并在解析后进行验证：
```python
from pydantic import BaseModel, ValidationError, field_validator
from typing import Optional
class SearchToolInput(BaseModel):
"""搜索工具的输入参数"""
query: str
max_results: int = 10
language: str = "en"
@field_validator("max_results")
@classmethod
def validate_max_results(cls, v):
if v < 1 or v > 100:
raise ValueError("max_results 必须在 1-100 之间")
return v
class ToolCallValidator:
"""工具调用参数验证"""
TOOL_SCHEMAS = {
"search": SearchToolInput,
"database_query": "DatabaseQueryInput",
# ... 其他工具
}
@staticmethod
def validate_tool_call(tool_call: ToolUseBlock) -> bool:
"""验证工具调用的合法性"""
tool_name = tool_call.name
if tool_name not in ToolCallValidator.TOOL_SCHEMAS:
raise ValueError(f"未知的工具: {tool_name}")
schema = ToolCallValidator.TOOL_SCHEMAS[tool_name]
try:
schema(**tool_call.input)
return True
except ValidationError as e:
# 捕获 Pydantic 验证错误,提供详细错误信息
error_msg = "; ".join([f"{err['loc']}: {err['msg']}" for err in e.errors()])
raise ValueError(f"工具参数验证失败: {error_msg}")
except (TypeError, AttributeError) as e:
# 捕获参数类型错误
raise ValueError(f"工具调用格式错误: {e}")
# 使用
tool_call = ToolUseBlock(
id="call_123",
name="search",
input={"query": "Python async", "max_results": 10}
)
try:
if ToolCallValidator.validate_tool_call(tool_call):
print("工具调用有效")
except ValueError as e:
print(f"验证失败: {e}")
```
### 解析管道
完整的解析管道实现如下：
```python
class ParsingPipeline:
"""完整的解析管道"""
def __init__(self):
self.parser = ResponseParser()
self.validator = ToolCallValidator()
def parse_and_validate(
self, raw_response: Dict[str, Any]
) -> ParsedMessage:
"""解析并验证响应"""
# 步骤 1:解析
parsed = self.parser.parse_response(raw_response)
# 步骤 2:验证工具调用
for tool_call in parsed.tool_calls():
self.validator.validate_tool_call(tool_call)
# 步骤 3:检查完整性
if parsed.stop_reason == "max_tokens":
raise ValueError("响应因 token 限制被截断")
return parsed
```
### 输出解析管道架构
结构化输出的解析流程如下所示：
```mermaid
graph LR
A["原始响应"] -->|解析内容块| B["流式解析器"]
B -->|验证类型| C["类型验证器"]
C -->|构建消息| D["结构化输出"]
E["完整响应"] -.->|也支持| B
style A fill:#ffebee
style B fill:#fff9c4
style C fill:#e0f2f1
style D fill:#c8e6c9
```
图 7-2：输出解析管道 —— 从原始响应逐步转换为类型安全的结构化数据
### 总结
结构化输出解析通过：
* **类型系统** (TextBlock/ToolUseBlock/ThinkingBlock)提供类型安全
* **非流式与流式双路径** 支持不同使用场景
* **增量解析** 实现高效的流式处理
* **Pydantic 校验** 确保参数合法性
这是构建可靠智能体的基础，为下一步的质量门控做准备。
# 7.3 输出质量门控与过滤
工具执行前需要多层验证防线来确保安全和有效性。本节介绍六层质量门控机制、规划-生成-评估三角色分离模式，以及如何通过独立评估者消除自我确认偏差。
## 7.3.1 问题定义
工具调用前的最后防线是质量门控(Quality Gate)。未经验证的输出可能导致：
* **参数错误**：工具接收非法数据导致执行失败
* **资源泄露**：过度调用导致费用飙升或系统宕机
* **格式异常**：API 调用失败导致 智能体循环重试
* **安全漏洞**：注入攻击、不合理的权限操作
质量门控在 **执行之前** 进行多层验证，确保只有安全、合法的调用才能通过。
## 7.3.2 门控层次结构
质量门控按以下六个层次依次进行验证：
```mermaid
graph TD
A["原始响应"] -->|检查格式| B["格式检查"]
B -->|验证存在| C["工具存在性"]
C -->|检查类型| D["参数验证"]
D -->|检查逻辑| E["业务逻辑"]
E -->|检查权限| F["安全检查"]
F -->|通过所有检查| G["执行工具"]
B -.->|失败| H["拒绝执行"]
C -.->|失败| H
D -.->|失败| H
E -.->|失败| H
F -.->|失败| H
style A fill:#ffebee
style B fill:#fff9c4
style C fill:#fff9c4
style D fill:#fff9c4
style E fill:#fff9c4
style F fill:#fff9c4
style G fill:#c8e6c9
style H fill:#ffcdd2
```
图 7-3：质量门控多层验证流程 —— 工具执行前的六层递进式防护
### 1. 基础格式检查
验证解析结果的完整性和一致性：
```python
from dataclasses import dataclass
from enum import Enum
from typing import Optional, List
class ValidationResult(Enum):
PASS = "pass"
FAIL = "fail"
WARN = "warn"
@dataclass
class ValidationReport:
result: ValidationResult
errors: List[str]
warnings: List[str]
suggestion: Optional[str] = None
class FormatValidator:
"""基础格式验证"""
@staticmethod
def validate_tool_use_block(tool_use) -> ValidationReport:
"""验证工具调用块的结构完整性"""
errors = []
warnings = []
# 检查必填字段
if not tool_use.id:
errors.append("tool_use.id 不能为空")
if not tool_use.name:
errors.append("tool_use.name 不能为空")
if tool_use.input is None:
errors.append("tool_use.input 不能为空")
# 检查 ID 格式(Claude 的 tool_use.id 以 "toolu_" 开头)
if tool_use.id and not tool_use.id.startswith("toolu_"):
warnings.append(
f"非标准 tool_use.id: {tool_use.id}"
)
# 检查名称格式(应为 snake_case)
if tool_use.name and not FormatValidator._is_valid_name(tool_use.name):
warnings.append(
f"工具名格式非标准: {tool_use.name}"
)
if errors:
return ValidationReport(
result=ValidationResult.FAIL,
errors=errors,
warnings=warnings,
suggestion="检查 API 响应是否正确解析"
)
if warnings:
return ValidationReport(
result=ValidationResult.WARN,
errors=[],
warnings=warnings
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
@staticmethod
def _is_valid_name(name: str) -> bool:
"""检查工具名是否符合 snake_case"""
return name.islower() and name.replace("_", "").isalnum()
```
### 2. 工具存在性检查
验证工具是否已注册：
```python
class ToolRegistry:
"""工具注册表与存在性检查"""
def __init__(self):
self.tools = {}
def register(self, name: str, handler, schema):
"""注册工具"""
self.tools[name] = {
"handler": handler,
"schema": schema,
"enabled": True
}
def is_tool_available(self, name: str) -> bool:
"""检查工具是否可用"""
if name not in self.tools:
return False
return self.tools[name]["enabled"]
def get_tool_schema(self, name: str):
"""获取工具的参数 schema"""
if name not in self.tools:
return None
return self.tools[name]["schema"]
class ExistenceValidator:
"""工具存在性验证"""
def __init__(self, registry: ToolRegistry):
self.registry = registry
def validate(self, tool_name: str) -> ValidationReport:
"""检查工具是否存在且可用"""
errors = []
suggestions = []
if tool_name not in self.registry.tools:
errors.append(f"工具 '{tool_name}' 未注册")
# 生成相似工具建议
similar = self._find_similar_tools(tool_name)
if similar:
suggestions.append(
f"您是想用 '{similar[0]}' 吗?"
)
elif not self.registry.is_tool_available(tool_name):
errors.append(f"工具 '{tool_name}' 已禁用")
if errors:
return ValidationReport(
result=ValidationResult.FAIL,
errors=errors,
warnings=[],
suggestion=suggestions[0] if suggestions else None
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
def _find_similar_tools(self, name: str) -> List[str]:
"""使用编辑距离找相似工具名"""
from difflib import get_close_matches
available = [n for n in self.registry.tools.keys()
if self.registry.is_tool_available(n)]
return get_close_matches(name, available, n=1, cutoff=0.6)
```
### 3. 参数类型和范围检查
使用Pydantic进行参数类型和范围验证的实现如下：
```python
from pydantic import BaseModel, ValidationError, field_validator
from typing import Optional, Any
class FileReadInput(BaseModel):
"""文件读取工具的输入"""
file_path: str
encoding: str = "utf-8"
max_lines: Optional[int] = None
@field_validator("file_path")
@classmethod
def validate_file_path(cls, v):
if not isinstance(v, str) or len(v) == 0:
raise ValueError("file_path 必须是非空字符串")
return v
@field_validator("max_lines")
@classmethod
def validate_max_lines(cls, v):
if v is not None and (v < 1 or v > 100000):
raise ValueError("max_lines 必须在 1-100000 之间")
return v
class ParameterValidator:
"""参数验证器"""
def __init__(self, registry: ToolRegistry):
self.registry = registry
def validate(self, tool_name: str, parameters: dict) -> ValidationReport:
"""验证工具参数"""
schema = self.registry.get_tool_schema(tool_name)
if schema is None:
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"无法找到工具 {tool_name} 的 schema"],
warnings=[]
)
errors = []
warnings = []
try:
# 使用 Pydantic 验证参数
validated = schema(**parameters)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
except ValidationError as e:
for error in e.errors():
field = ".".join(str(x) for x in error["loc"])
msg = error["msg"]
errors.append(f"参数 {field}: {msg}")
if errors:
return ValidationReport(
result=ValidationResult.FAIL,
errors=errors,
warnings=warnings,
suggestion="请检查工具的参数定义"
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=warnings
)
```
### 4. 业务逻辑检查
某些检查超越类型系统，涉及业务规则：
```python
class BusinessLogicValidator:
"""业务逻辑验证"""
def __init__(self):
self.config = {
"max_api_calls_per_minute": 100,
"max_file_size_mb": 10,
"allowed_domains": ["example.com", "api.service.com"],
}
def validate_api_call_frequency(self, tool_name: str,
call_history: List[float]) -> ValidationReport:
"""检查 API 调用频率是否超过限制"""
import time
now = time.time()
# 计算最近 1 分钟的调用数
recent_calls = [t for t in call_history if now - t < 60]
limit = self.config["max_api_calls_per_minute"]
if len(recent_calls) >= limit:
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"工具 {tool_name} 在 1 分钟内调用已达 {limit} 次限制"],
warnings=[],
suggestion="请稍后再试"
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
def validate_file_access(self, file_path: str) -> ValidationReport:
"""检查文件访问权限和大小"""
import os
errors = []
# 检查文件存在性
if not os.path.exists(file_path):
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"文件不存在: {file_path}"],
warnings=[]
)
# 检查文件大小
file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
max_size = self.config["max_file_size_mb"]
if file_size_mb > max_size:
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"文件大小 {file_size_mb:.2f}MB 超过限制 {max_size}MB"],
warnings=[]
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
def validate_http_request(self, url: str) -> ValidationReport:
"""检查 HTTP 请求的目标合法性"""
from urllib.parse import urlparse
parsed = urlparse(url)
domain = parsed.netloc
if domain not in self.config["allowed_domains"]:
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"不允许访问域名: {domain}"],
warnings=[],
suggestion=f"允许的域名: {self.config['allowed_domains']}"
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
```
### 5. 安全与权限检查
安全与权限检查的实现方式如下：
```python
from enum import Enum
class Permission(Enum):
READ = "read"
WRITE = "write"
DELETE = "delete"
EXECUTE = "execute"
class SecurityValidator:
"""安全与权限检查"""
def __init__(self, user_permissions: set):
self.user_permissions = user_permissions
def validate_tool_permission(self, tool_name: str) -> ValidationReport:
"""检查用户是否有权调用该工具"""
# 定义工具所需权限
tool_permissions = {
"read_file": {Permission.READ},
"write_file": {Permission.WRITE},
"delete_file": {Permission.DELETE},
"execute_command": {Permission.EXECUTE},
}
if tool_name not in tool_permissions:
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"未知工具: {tool_name}"],
warnings=[]
)
required = tool_permissions[tool_name]
if not required.issubset(self.user_permissions):
missing = required - self.user_permissions
return ValidationReport(
result=ValidationResult.FAIL,
errors=[f"缺少权限: {', '.join(p.value for p in missing)}"],
warnings=[]
)
return ValidationReport(
result=ValidationResult.PASS,
errors=[],
warnings=[]
)
def validate_parameter_injection(self, parameters: dict) -> ValidationReport:
"""检查参数是否包含注入攻击"""
dangerous_patterns = [
"rm -rf",
"DROP TABLE",
"