metona-ollama-desktop/docs/HERMES-AGENT-DEEP-STUDY.md

Hermes Agent 深度研究 — Metona 可借鉴方案

基于 2026-04-18 对 NousResearch/hermes-agent 源码和文档的深度研究。 定位：与 OPENCLAW-HERMES-ANALYSIS.md 互补，侧重实现细节和可落地方案。

---

一、Hermes 核心架构一览

语言：Python（~40K 行代码）
核心文件：
  run_agent.py       — AIAgent 类（~10,700 行），Agent Loop 引擎
  cli.py             — TUI 终端界面（~10,000 行）
  model_tools.py     — 工具发现、Schema 收集、调度
  tools/registry.py  — 中央工具注册表（47 个工具，19 个 toolset）
  hermes_state.py    — SQLite 状态数据库（FTS5）
  prompt_builder.py  — System Prompt 组装
  context_compressor.py — 上下文压缩

关键设计原则

原则	实践
Prompt 稳定性	System prompt 在对话中不变化，保护 LLM prefix cache
可观测执行	每个工具调用通过 callback 通知用户
可中断	API 调用和工具执行可被用户输入中断
平台无关核心	一个 AIAgent 类服务 CLI/Gateway/ACP/Batch/API
松耦合	MCP/插件/记忆提供者使用 registry 模式 + check_fn
Profile 隔离	每个 profile 独立 HERMES_HOME、配置、记忆、会话

---

二、Agent Loop 对比

Hermes 的 Agent Loop

用户输入 → build_system_prompt() → resolve provider → API 调用
  → 有 tool_calls？→ 并行执行（ThreadPoolExecutor）→ 循环
  → 无 tool_calls？→ 持久化 → 返回

关键差异：

维度	Hermes	Metona
API 模式	3 种（chat_completions / codex_responses / anthropic_messages）	1 种（Ollama chat）
工具执行	单工具主线程，多工具 ThreadPoolExecutor 并行	同一批次 Promise.all 并行
中断机制	后景线程 + interrupt event	AbortController
迭代预算	90 轮（可配置）	✅ 默认 85 轮，设置面板可配（v5.1.1）
上下文压缩	context_compressor.py 摘要中间轮次	context-manager.ts 滑动窗口
Prompt 缓存	Anthropic prompt caching 支持	无
消息交替	严格 user→assistant 交替	Ollama 自动处理
回调系统	8 种 callback（progress/thinking/reasoning/clarify/step/stream/status）	5 种 callback

Metona 可借鉴

1. 迭代预算可配置化：从硬编码 15 轮改为 state.get('maxTurns', 15)
2. 工具执行分单/并行逻辑优化：单工具直接执行，多工具并行（Hermes 的 ThreadPoolExecutor 思路）
3. 上下文压缩：当 context 超过 50% 时自动摘要中间轮次，而非简单滑动窗口

---

三、工具系统对比

Hermes 的 Tool Registry

# tools/registry.py — 中央注册表
class ToolRegistry:
    def register(self, name, toolset, schema, handler, check_fn, ...):
        # 每个 tool 文件在 import 时自动注册
        # 防止 shadowing（MCP 不能覆盖内置工具）
    
    def discover_builtin_tools(self):
        # AST 扫描 tools/*.py，找到 registry.register() 调用的文件自动 import

关键差异：

维度	Hermes	Metona
注册方式	每个文件 import 时自动 register()	集中式 getToolDefinitions()
工具数量	47 个 + 19 个 toolset	38 个内置 + MCP 动态注册
Toolset	工具分组，可按组启用/禁用	无分组，全部启用
Shadowing 防护	MCP 不能覆盖内置工具	✅ 已实现（v5.1.2）
工具发现	AST 扫描自动发现	手动导入
结果截断	max_result_size_chars 每工具可配	✅ 按工具独立配置（v5.1.0）
安全审批	tools/approval.py 危险命令检测 + 用户确认	tool-security.ts 路径/命令检查

Metona 可借鉴

1. ✅ 结果截断按工具配置：不同工具设置不同的 max_result_size_chars（v5.1.0 已实现）
2. ✅ Shadowing 防护：MCP 工具注册时检查是否与内置工具重名（v5.1.2 已实现）
3. ❌ Toolset 分组：将 38 个工具分为文件系统/系统网络/记忆会话/浏览器/MCP 等组，用户可按组启用/禁用

---

四、记忆系统对比

Hermes 的记忆

维度	Hermes	Metona
存储方式	2 个 Markdown 文件（MEMORY.md + USER.md）	SQLite（memories 表 + FTS5）
容量限制	MEMORY.md 2200 字符，USER.md 1375 字符	✅ 上限 500 条，超限自动清理（v5.1.2）
注入方式	会话开始时冻结快照注入 system prompt	每次用户消息时检索注入
管理方式	Agent 通过 memory tool 自主管理	Agent 通过 memory_search/memory_add 工具
操作	add / replace / remove（子串匹配）	✅ search / add / replace / remove（v5.1.0）
会话搜索	session_search（FTS5 + Gemini 摘要）	session_read（原始内容）
外部提供者	8 个插件（Honcho / Mem0 / OpenViking 等）	无
安全扫描	注入检测 + 凭证外泄检测	✅ prompt injection / 敏感信息 / 不可见字符检测（v5.1.0）

Metona 可借鉴

1. ✅ 记忆容量限制：上限 500 条，超限自动清理低价值条目（v5.1.2 已实现）
2. ✅ replace/remove 操作：记忆工具支持修改和删除（v5.1.0 已实现）
3. ✅ 安全扫描：记忆条目写入前检查 prompt injection / 凭证外泄模式（v5.1.0 已实现）
4. ❌ 冻结快照模式：会话开始时一次性注入记忆，不随对话变化（保护 LLM cache）
5. ❌ 记忆区分层：MEMORY.md（环境/工作流）vs USER.md（用户画像）清晰分离

---

五、Skill 系统对比

Hermes 的 Skill

维度	Hermes	Metona
格式	SKILL.md（Markdown 文件，YAML frontmatter）	SQLite skills 表
加载方式	渐进式披露（Level 0→1→2）	匹配后全文注入
触发条件	/<skill-name> 斜杠命令 + 自然对话	自动匹配关键词
创建时机	5+ 工具调用的复杂任务完成后	2+ 工具调用后
更新方式	create / patch / edit / delete	仅 create
条件激活	fallback_for_toolsets / requires_toolsets	无
Skill Hub	在线注册表浏览/安装	无
agentskills.io 兼容	✅ 开放标准	❌

Metona 可借鉴

1. 渐进式加载：先返回技能名称+描述（~3K tokens），Agent 需要时再加载全文
2. patch 更新：Agent 可以用 old_string/new_string 局部修改技能，而非全文替换
3. 条件激活：某些技能只在特定工具不可用时才显示（fallback 机制）
4. SKILL.md 格式标准化：采用 YAML frontmatter + 结构化正文（When to Use / Procedure / Pitfalls / Verification）

---

六、Prompt 组装对比

Hermes 的 Prompt Builder

prompt_builder.py 组装顺序：
1. Personality（SOUL.md）
2. Memory（MEMORY.md + USER.md 冻结快照）
3. Skills（渐进式索引）
4. Context Files（AGENTS.md, .hermes.md）
5. Tool-use guidance
6. Model-specific instructions
7. Ephemeral layers（budget warnings, context pressure）

关键差异：

维度	Hermes	Metona
组装来源	6 层 + 2 个临时层	4 层（记忆+工作空间+Agent提示+人格）
缓存保护	Prompt 稳定性原则，不随对话变化	每次消息重新组装
预算警告	迭代接近上限时注入警告层	无
上下文压力	context 超 50% 时注入压缩提示	无

Metona 可借鉴

1. 临时层机制：在 system prompt 末尾追加临时提示（预算警告、上下文压力），不影响基础 prompt 稳定性
2. 模型特定指令：根据模型能力（tools/thinking/vision）动态调整 prompt 内容

---

七、上下文管理对比

Hermes 的 Context Compression

# context_compressor.py
# 当对话超过 context window 的 50% 时：
# 1. 保留首尾各 2-3 条消息
# 2. 中间消息用 LLM 摘要为 1-2 条 system 消息
# 3. 摘要后的消息标记为 compressed
# 4. 新消息基于压缩后的历史继续

维度	Hermes	Metona
压缩触发	context > 50%	无自动压缩
压缩方式	LLM 摘要中间轮次	滑动窗口截断
Session 谱系	压缩后创建子 session，保留 parent_id	无谱系跟踪
Token 估算	model_metadata.py 按模型配置	粗略估算（中 1.5字/token，英 4字符/token）

Metona 可借鉴

1. LLM 摘要压缩：context 超过阈值时，用 LLM 摘要中间轮次而非简单截断
2. Session 谱系：压缩后创建新 session 并保留 parent_id，支持回溯
3. Token 估算精确化：按模型配置 token 估算参数

---

八、可落地的改进清单

按优先级排序，基于 Metona 现状和投入产出比：

P0 — 已实施

改进	来源	复杂度	改动文件	状态
迭代预算可配置	Hermes Agent Loop	低	agent-engine.ts	✅ v5.1.1（默认 85 轮，设置面板可配）
记忆 replace/remove 操作	Hermes Memory	中	memory-manager.ts + tool-registry.ts	✅ v5.1.0
记忆安全扫描	Hermes Memory	低	memory-manager.ts	✅ v5.1.0
工具结果截断按工具配置	Hermes Tool Registry	低	tool-registry.ts	✅ v5.1.0

P1 — 近期实施

改进	来源	复杂度	改动文件	状态
Skill 渐进式加载	Hermes Skills	中	skill-manager.ts + agent-engine.ts	❌ 当前 Level 0，全文注入
Skill patch 更新	Hermes Skills	中	skill-manager.ts + tool-registry.ts	❌ 仅 create
Toolset 分组管理	Hermes Toolset	中	tool-registry.ts + settings-modal.ts	❌ 未实现
LLM 摘要压缩	Hermes Context	高	context-manager.ts + agent-engine.ts	❌ 未实现（仍用滑动窗口）

P2 — 中期规划

改进	来源	复杂度	状态
Skill 条件激活	Hermes Skills	中	❌ 未实现
Session 谱系跟踪	Hermes Session	中	❌ 未实现
预算警告临时层	Hermes Prompt	低	✅ v5.1.2（≤5 轮 warning，≤2 轮 critical）
Shadowing 防护	Hermes Registry	低	✅ v5.1.2（MCP 工具注册时自动检测重名）

---

九、Hermes vs Metona 定位总结

Hermes = 云端 Python Agent（CLI + Gateway + 多平台）
  ✅ 技能生态成熟（agentskills.io 开放标准）
  ✅ 记忆系统精巧（容量限制 + 冻结快照）
  ✅ 工具注册表自动发现
  ❌ 非桌面原生体验
  ❌ 需要 Python 环境

Metona = 本地 Electron 桌面 Agent
  ✅ 零配置启动，全离线
  ✅ 系统托盘 + 原生文件对话框
  ✅ 工作空间面板（终端 + 文件浏览器）
  ✅ 暖色调 UI
  ✅ MCP 协议支持（v5.0.0）
  ✅ 技能自动生成（v5.1.0）
  ✅ 记忆容量管理 + 安全扫描（v5.1.0 / v5.1.2）
  ❌ 技能渐进式加载（Level 0，全文注入）
  ❌ 上下文管理粗糙（滑动窗口，无 LLM 压缩）

互补方向：
  Metona 吸收 Hermes 的学习进化能力
  Hermes 不具备 Metona 的桌面原生体验

---

最后更新：2026-04-19（根据 v5.1.3 实际代码更新实施状态）