docs: 新增 Hermes Agent 深度研究报告及 Metona 改进方案
This commit is contained in:
thzxx
@@ -0,0 +1,268 @@
|
||||
# Hermes Agent 深度研究 — Metona 可借鉴方案
|
||||
|
||||
> 基于 2026-04-18 对 [NousResearch/hermes-agent](https://github.com/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 轮（可配置） | 15 轮（硬编码） |
|
||||
| 上下文压缩 | 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
|
||||
|
||||
```python
|
||||
# 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 | 34 个内置 |
|
||||
| Toolset | 工具分组，可按组启用/禁用 | 无分组，全部启用 |
|
||||
| Shadowing 防护 | MCP 不能覆盖内置工具 | 无此机制 |
|
||||
| 工具发现 | AST 扫描自动发现 | 手动导入 |
|
||||
| 结果截断 | max_result_size_chars 每工具可配 | web_fetch 统一 15000 字符 |
|
||||
| 安全审批 | tools/approval.py 危险命令检测 + 用户确认 | tool-security.ts 路径/命令检查 |
|
||||
|
||||
### Metona 可借鉴
|
||||
|
||||
1. **Toolset 分组**：将 34 个工具分为文件系统/系统网络/记忆会话/浏览器/MCP 等组，用户可按组启用/禁用
|
||||
2. **结果截断按工具配置**：不同工具设置不同的 max_result_size_chars
|
||||
3. **Shadowing 防护**：MCP 工具注册时检查是否与内置工具重名
|
||||
|
||||
---
|
||||
|
||||
## 四、记忆系统对比
|
||||
|
||||
### Hermes 的记忆
|
||||
|
||||
| 维度 | Hermes | Metona |
|
||||
|------|--------|--------|
|
||||
| 存储方式 | 2 个 Markdown 文件（MEMORY.md + USER.md） | SQLite（memories 表 + FTS5） |
|
||||
| 容量限制 | MEMORY.md 2200 字符，USER.md 1375 字符 | 无限制 |
|
||||
| 注入方式 | 会话开始时冻结快照注入 system prompt | 每次用户消息时检索注入 |
|
||||
| 管理方式 | Agent 通过 memory tool 自主管理 | Agent 通过 memory_search/memory_add 工具 |
|
||||
| 操作 | add / replace / remove（子串匹配） | search / add |
|
||||
| 会话搜索 | session_search（FTS5 + Gemini 摘要） | session_read（原始内容） |
|
||||
| 外部提供者 | 8 个插件（Honcho / Mem0 / OpenViking 等） | 无 |
|
||||
| 安全扫描 | 注入检测 + 凭证外泄检测 | 无 |
|
||||
|
||||
### Metona 可借鉴
|
||||
|
||||
1. **记忆容量限制**：给 memories 表加容量限制（如 2200 字符），超限时 Agent 自动合并旧条目
|
||||
2. **冻结快照模式**：会话开始时一次性注入记忆，不随对话变化（保护 LLM cache）
|
||||
3. **replace/remove 操作**：记忆工具支持修改和删除，不只能添加
|
||||
4. **安全扫描**：记忆条目写入前检查 prompt injection / 凭证外泄模式
|
||||
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
|
||||
|
||||
```python
|
||||
# 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 |
|
||||
| 记忆 replace/remove 操作 | Hermes Memory | 中 | memory-manager.ts + tool-registry.ts |
|
||||
| 记忆安全扫描 | Hermes Memory | 低 | memory-manager.ts |
|
||||
| 工具结果截断按工具配置 | Hermes Tool Registry | 低 | tool-registry.ts |
|
||||
|
||||
### P1 — 近期实施
|
||||
|
||||
| 改进 | 来源 | 复杂度 | 改动文件 |
|
||||
|------|------|--------|----------|
|
||||
| Skill 渐进式加载 | Hermes Skills | 中 | skill-manager.ts + agent-engine.ts |
|
||||
| Skill patch 更新 | Hermes Skills | 中 | skill-manager.ts + tool-registry.ts |
|
||||
| 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 | 低 |
|
||||
| Shadowing 防护 | Hermes Registry | 低 |
|
||||
|
||||
---
|
||||
|
||||
## 九、Hermes vs Metona 定位总结
|
||||
|
||||
```
|
||||
Hermes = 云端 Python Agent（CLI + Gateway + 多平台）
|
||||
✅ 技能生态成熟（agentskills.io 开放标准）
|
||||
✅ 记忆系统精巧（容量限制 + 冻结快照）
|
||||
✅ 工具注册表自动发现
|
||||
❌ 非桌面原生体验
|
||||
❌ 需要 Python 环境
|
||||
|
||||
Metona = 本地 Electron 桌面 Agent
|
||||
✅ 零配置启动，全离线
|
||||
✅ 系统托盘 + 原生文件对话框
|
||||
✅ 工作空间面板（终端 + 文件浏览器）
|
||||
✅ 暖色调 UI
|
||||
❌ 技能系统较原始
|
||||
❌ 记忆无容量管理
|
||||
❌ 上下文管理粗糙
|
||||
|
||||
互补方向：
|
||||
Metona 吸收 Hermes 的学习进化能力
|
||||
Hermes 不具备 Metona 的桌面原生体验
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026-04-18*
|
||||
Reference in New Issue
Block a user