# 本章小结

本章系统地阐述了Harness的整体架构设计，包括三层+横切关注点的参考架构、核心组件的深入设计、层间接口规范和参考实现对比。以下是主要内容的总结。

## 核心架构模型

**三层 + 横切关注点参考架构**

Harness系统采用三层结构加横切关注点的方式组织，清晰地分离了不同的关注点：

```mermaid
graph TB
    A["<b>接入层</b><br/>(与用户/系统的接口、协议适配)"]
    B["<b>编排层(可选)</b><br/>(多智能体编排和任务分解)"]
    C["<b>智能体核心层</b><br/>(单智能体执行的核心工作区)"]
    D["<b>运行时引擎</b><br/>(循环中枢)"]
    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项目将为后续的功能开发提供坚实的基础。


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://yeasy.gitbook.io/harness_engineering_guide/di-yi-bu-fen-harness-gong-cheng-ji-chu/02_architecture/summary.md?ask=<question>
```

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

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