# Hermes Agent：Harness 完整架构与创新模式

> 资料来源：Hermes Agent 官方文档、Pyshine Orange Book、dev.to 技术深度解析、Nous Research GitHub 及 ArXiv 相关研究
> 整理时间：2026-05-06

---

## 一、总体架构

### 1.1 核心理念：从 Harness 到 Agent

Hermes Agent 源自 Nous Research 的 **Harness 工程框架**，完成了一次从"开发者工具"到"自主智能体平台"的根本性转变。这不是简单的重命名，而是 AI 工程第三范式转移的体现：

| 范式 | 核心 | 特点 |
|------|------|------|
| Prompt Engineering | 优化提示词 | 手工调试，易出错 |
| Context Engineering | 管理上下文 | 复杂，仍是被动的 |
| **Harness Engineering** | **自我进化的控制基础设施** | 主动学习，持续改进 |

**核心洞察**：模型提供智能，但 **Harness 提供控制**。没有 Harness，将 LLM 部署到生产环境就像"把喷气发动机直接连到方向盘上"——有动力但无控制系统。

### 1.2 三层架构概览

```
┌────────────────────────────────────────────────────────────┐
│                     ENTRY POINTS                           │
│  CLI / TUI / Gateway (TG, Discord, Slack) / Cron / Batch  │
└─────────────────────┬──────────────────────────────────────┘
                      │ 每个入口构建一个 AIAgent
                      ▼
┌────────────────────────────────────────────────────────────┐
│              AIAgent (核心循环 ~13,700 行)                   │
│  build_system_prompt → call model → dispatch tools → loop │
└──────┬─────────────┬──────────────┬───────────┬───────────┘
       │             │              │           │
       ▼             ▼              ▼           ▼
┌──────────┐  ┌──────────┐  ┌────────────┐ ┌─────────────┐
│  Tools   │  │  Skills  │  │  Memory    │ │  Providers  │
│ Registry │  │  Loader  │  │  Manager   │ │ (model API) │
└──────────┘  └──────────┘  └────────────┘ └─────────────┘
                                                        │
       ┌────────────────────────────────────────────────┘
       ▼
┌────────────────────────────────────────────────────────────┐
│     Execution Environments: local / Docker / SSH / Modal  │
└────────────────────────────────────────────────────────────┘
```

**三层语义**：
- **第一层（Surfaces）**：人/系统如何与 Agent 对话（CLI、聊天平台、Cron）
- **第二层（Agent Core）**：循环 + 四个可插拔子系统（工具、技能、记忆、模型）
- **第三层（Execution）**：Shell/代码执行的实际运行环境

### 1.3 核心组件

| 组件 | 文件 | 功能 |
|------|------|------|
| AIAgent | `run_agent.py` | 核心对话循环，同步编排引擎 |
| HermesCLI | `cli.py` | 交互式终端 UI |
| Gateway | `gateway/run.py` | 消息平台网关 |
| Tool Registry | `tools/registry.py` | 61 个注册工具，52 个工具集 |
| SessionDB | `hermes_state.py` | SQLite + FTS5 全文本搜索 |
| Prompt Builder | `agent/prompt_builder.py` | 系统提示组装 |
| Skill Manager | `agent/skill_commands.py` | 技能生命周期管理 |

### 1.4 Agent 循环（核心执行流程）

```
1. 接收输入 ── CLI / gateway / cron / ACP / web
2. 构建系统提示 ── persona + memory + skills + tools（会话期间仅一次）
3. 解析 Provider ── 选择哪个 API key + endpoint
4. 调用模型 ── 支持 4 种 API 模式：
   chat_completions | codex_responses | anthropic_messages | bedrock_converse
5. 解析响应：
   ├─ 存在 tool_calls → 分发到 registry → 追加结果 → 回到步骤 4
   └─ 否则 → 最终回复 → 展示 → 持久化 → 完成
6. 持久化 ── SQLite SessionDB（WAL 模式 + FTS5 索引）
```

---

## 二、Harness 的定义与作用

### 2.1 什么是 Harness？

Harness 是围绕模型的基础设施层，它将 LLM 转化为**可控的、可审计的、可投入生产使用的智能体**。具体包括：

| Harness 职责 | Hermes 实现 |
|-------------|------------|
| **工具中介** (Tool Mediation) | 61 个内置工具 + 动态 MCP 集成 |
| **上下文管理** (Context Management) | 三层记忆 + FTS5 检索 + 上下文压缩 |
| **委托分发** (Delegation) | 最多 3 个并发子 Agent |
| **安全控制** (Safety Control) | 四层防护：Tirith 扫描 / Regex 检测 / LLM 风险评级 / 审批范围 |
| **编排调度** (Orchestration) | AIAgent 单一类服务所有入口 |

### 2.2 五大子系统

```
Central Orchestration Core
         │
    ┌────┼────┬────┬────┐
    ▼    ▼    ▼    ▼    ▼
 ┌────┐┌────┐┌────┐┌────┐┌──────┐
 │Skill││Memory│ │Tool│ │Gateway││Learning│
 │System││System│ │Eco-│ │Layer │ │  Loop │
 │   │ │   │ │system│ │   │ │      │
 └────┘└────┘└────┘└────┘└──────┘
```

### 2.3 从 Harness 进化到 Hermes 的五层映射

| Harness 层 | → | Hermes 进化 |
|-----------|---|------------|
| 指令层 | → | **技能系统**：静态提示模板 → 动态可进化技能 |
| 约束层 | → | **工具权限**：刚性执行边界 → 粒度化权限模型 |
| 反馈层 | → | **学习循环**：Harness 将反馈当日志 → Hermes 闭合循环 |
| 记忆层 | → | **三层记忆**：临时上下文 → Session/Persistent/Skill 三层结构 |
| 编排层 | → | **子 Agent 委托**：单线程 → 最多 3 个并发子 Agent |

---

## 三、创新点（核心差异化）

### 3.1 学习循环飞轮（最核心创新）

Hermes 区别于其他 Agent 框架的根本在于**五步学习循环**，形成自我强化飞轮：

```
┌─────────────┐
│ 1. 记忆管理  │ ── 评估对话，筛选值得保留的信息
└──────┬──────┘
       ▼
┌─────────────┐
│ 2. 技能创建  │ ── 重复模式 → 自动蒸馏为新 Skill
└──────┬──────┘
       ▼
┌─────────────┐
│ 3. 技能自改进│ ── 达尔文压力：表现好的技能存活并传播
└──────┬──────┘
       ▼
┌─────────────┐
│ 4. FTS5 召回│ ── 全量历史语义检索，不只依赖当前上下文
└──────┬──────┘
       ▼
┌─────────────┐
│ 5. 用户建模  │ ── 通过 Honcho 构建用户画像（风格/专业/偏好）
└──────┬──────┘
       │
       └────── "更好记忆 → 更好技能 → 更好结果 → 更丰富反馈 → 更精确用户模型 → 更相关记忆"飞轮闭环
```

**关键**：Agent 通过 `skill_manage` 工具自己编写 Skills，自己编辑 MEMORY.md——不是人类在改代码，而是 Agent 在自我进化。

### 3.2 三层记忆架构（类人认知）

| 层级 | 类型 | 内容 | 存储 | 回答问题 |
|------|------|------|------|---------|
| Session Memory | 情景记忆 | 单次对话全内容、工具调用结果、推理步骤 | SQLite | "这次对话发生了什么？" |
| Persistent Memory | 语义记忆 | 身份、关系、长期知识 | MEMORY.md + USER.md（纯文本） | "我是谁？用户是谁？" |
| Skill Memory | 程序记忆 | 如何执行任务的步骤 | `~/.hermes/skills/` 的 Markdown | "我怎么做这件事？" |

这三重结构**直接对应人类认知架构**（情景/语义/程序记忆），是有意为之的设计哲学，而非偶然。

### 3.3 技能系统（Skills as Runbooks）

Skills 不是代码，也不是配置，而是**Agent 可读取和增长的 Markdown 运行手册**：

```yaml
---
name: article-summarizer
description: 以结构化格式总结文章
triggers:
  - summarize
  - tl;dr
tools:
  - web_search
  - web_scraper
  - file_write
---

# Article Summarizer

你是一个善于提炼文章为清晰结构化摘要的专家。

## Instructions
1. 使用 web_search 或 web_scraper 获取文章内容
2. 识别核心论点、支撑论据和结论
3. 格式化摘要为：
   - **论点**：一句话核心论点
   - **关键点**：3-5 个要点
   - **结论**：影响和收获
4. 如有需要保存摘要
```

**三种来源**：
1. **内置技能（40+）**：开箱即用
2. **Agent 自创技能**：重复模式 → 自动蒸馏 → 存放本地 → 可继续改进
3. **社区 Skills Hub**：遵循 agentskills.io 标准，可分享安装

### 3.4 渐进式加载（Progressive Disclosure）

Hermes 不一次性加载所有技能、记忆和工具文档，而是分层加载：

| 层级 | 内容 | 时机 |
|------|------|------|
| Level 0 | Skills 索引（名称+描述） | 始终在系统提示中 |
| Level 1 | 实际技能内容 | Agent 真正需要时才注入 |
| Level 2 | 引用的外部文件 | 技能自己请求时才加载 |

这就是为什么 Hermes 可以携带 47 个工具和数十个技能，而不会超出上下文限制。

### 3.5 平台无关核心（One Agent, Many Surfaces）

单个 `AIAgent` 类服务所有入口，平台差异只存在于薄薄的适配层：

| 入口 | 说明 |
|------|------|
| CLI / TUI | 交互式终端 |
| Gateway | 20 个消息平台（Telegram/Discord/Slack/WhatsApp/飞书/微信等） |
| ACP | VS Code / Zed / JetBrains IDE 集成 |
| Cron | 定时任务（JSON 配置，支持绑定技能） |
| Batch Runner | 批量轨迹生成（训练数据管道） |
| Web UI | 网页界面 |
| API Server | REST API |

跨平台对话连续性：用户可以在 Telegram 开始对话，切换到 Discord 继续，全程共享同一上下文。

### 3.6 自注册模式（Self-Registration）

工具和插件在**导入时**通过 `registry.register(...)` 自注册，而不是维护中心列表：
- 新增工具 = 新增一个 `.py` 文件，无需修改其他代码
- MCP 服务器即插即用
- 插件通过 `~/.hermes/plugins/` 自动发现

### 3.7 提示缓存友好设计（Prompt Stability）

系统提示在会话启动时组装，**会话期间不改变**。原因：
- Anthropic / OpenAI 的提示缓存要求稳定前缀才能命中
- 会话中改变工具集、重新加载记忆会破坏缓存，成本可能增加 **10 倍**
- 新记忆在磁盘写入，但系统提示不变——下次会话生效

### 3.8 四层安全防护

```
第1层：Tirith（Rust 外部扫描器）
  └─ 同形异义词 URL、终端注入（ANSI 转义隐藏命令）

第2层：Regex 危险命令检测
  └─ 归一化后检测（忽略大小写/空格），防止 RM -RF 绕过

第3层：Smart Approval（LLM 风险评级）
  └─ 低风险自动批准，中/高风险需人工确认

第4层：Approval Scopes（信任累积）
  └─ Once / Session / Permanent 三级，逐步建立信任
```

### 3.9 执行环境抽象

同一工具可在不同执行环境中运行，Agent 本身无感知：

| 环境 | 用途 | 隔离级别 |
|------|------|---------|
| local | 开发笔记本，最快，零隔离 | 无 |
| docker | 共享开发机，每个会话一个容器 | 容器级 |
| ssh | 远程 VM | VM 级 |
| daytona / modal | Serverless 沙箱，按需启动 | 强隔离 |
| singularity | HPC 集群 | 集群级 |

---

## 四、设计原则汇总

| 原则 | 实践 |
|------|------|
| **提示稳定性** | 系统提示会话期间不变，不破坏缓存 |
| **可观察执行** | 每个工具调用通过 callbacks 对用户可见 |
| **可中断** | API 调用和工具执行可在中途取消 |
| **平台无关核心** | 一个 AIAgent 服务所有入口，平台差异在适配层 |
| **松耦合** | MCP、插件、记忆提供者使用注册模式，不硬依赖 |
| **Profile 隔离** | 每个 profile（`-p <name>`）拥有独立 HERMES_HOME、配置、记忆、会话和 Gateway PID |

---

## 五、技术规格速览

| 指标 | 数值 |
|------|------|
| GitHub Stars | 47K+（42天内） |
| AIAgent 代码行数 | ~13,700 行 |
| HermesCLI 代码行数 | ~11,500 行 |
| GatewayRunner 代码行数 | ~12,200 行 |
| 内置工具数 | 61 个 |
| 工具集数 | 52 个 |
| 消息平台适配器 | 20 个 |
| 支持 Provider | 18+（OpenRouter/OpenAI/Anthropic/Ollama 等） |
| 记忆存储 | SQLite（WAL+FTS5）|
| 技能存储 | `~/.hermes/skills/`（Markdown + YAML frontmatter）|
| MCP 集成 | 支持，可连接 6,000+ 外部应用 |
| 并发子 Agent | 最多 3 个 |
| 测试覆盖 | 3,000+ 测试用例 |

---

## 六、与其他框架的对比

| 维度 | **Hermes Agent** | OpenClaw | Claude Code |
|------|-----------------|----------|-------------|
| 架构哲学 | 自我进化 + 记忆连续性 | 模块化 + 可组合性 | Anthropic 生态深度集成 |
| 记忆模型 | 三层（Session/Persistent/Skill）+ Honcho 用户建模 | 可配置记忆后端，无结构化分层 | Session 级上下文 + CLAUDE.md |
| 技能系统 | 最成熟（内置+自创+社区），支持自动蒸馏 | 插件系统，无自动技能蒸馏 | 紧耦合生态，无社区分享 |
| 工具生态 | 40+ 内置 + 6,000+ MCP | 可比内置规模，MCP 较小 | 主要终端+文件系统，MCP 较新 |
| 多平台 | **14 平台 + 跨平台连续性** | 支持但连续性较弱 | 主要 CLI，网页访问通过 API |
| 自我改进 | **飞轮学习循环**，真正的自动进化 | 实验性功能，未生产就绪 | 依赖 CLAUDE.md 手工更新 |
| 最适合场景 | 需要随时间变强的 Agent，跨平台使用 | 追求模块化定制的用户 | Anthropic 生态深度用户 |

---

## 七、关键洞察总结

> **Hermes 的核心创新不是某一个功能，而是一个范式**：将 Agent 视为一个认知系统，而非一个 API 包装器。

1. **Harness 是控制层**：模型是引擎，Harness 是控制系统。没有 Harness 的 LLM 生产部署是危险的。
2. **记忆即知识**：三层记忆架构（情景/语义/程序）使 Agent 拥有真实的跨会话连续性。
3. **技能即进化**：Agent 自己编写 Skills，不是人类工程师在维护——这是真正的自我改进。
4. **平台无关是工程纪律**：一个核心，多个表面，所有平台差异在适配层消失。
5. **提示缓存是经济问题**：Mid-session 的"聪明"改动可能让你的 API 成本增加 10 倍。

---

*整理自：Hermes Agent 官方架构文档（hermes-agent.nousresearch.com）、PyShine Orange Book、dev.to 技术深度解析、ArXiv 研究论文 "Architectural Design Decisions in AI Agent Harnesses"（2604.18071v1）等多个来源。*