Hermes Agent 整体了解

码路高手2026-05-19 18:24

Hermes Agent 整体了解

1. 系统定位

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架，对标 Claude Code、Codex、OpenClaw 等自主编码与任务执行型 Agent。核心差异在于：

  • Skills 自进化: 将解决过的问题沉淀为可复用 Skill，跨会话加载
  • 持久化 Memory: 跨会话记忆用户偏好、环境细节与经验教训
  • 多平台 Gateway: 同一 Agent 实例可跑在 Telegram/Discord/Slack/WhatsApp/Signal/Matrix/Email 等 10+ 平台
  • Provider 无关: 支持 20+ 模型提供商，可中途切换模型而不影响工作流
  • Profile 隔离: 多实例独立配置、会话、Skill 与记忆

2. 整体架构

sql 复制代码 
+-------------------------------------------------------------+
|                        User Interfaces                       |
|  CLI (terminal)  |  Telegram  |  Discord  |  Slack  | ...  |
+-------------------------------------------------------------+
                              |
+-------------------------------------------------------------+
|                        Gateway 层                            |
|         平台适配器 (Platform Adapters)                        |
|   telegram / discord / slack / whatsapp / signal / matrix   |
|   email / sms / mattermost / feishu / wecom / webhooks      |
+-------------------------------------------------------------+
                              |
+-------------------------------------------------------------+
|                      Core Engine 核心引擎                     |
|  +----------------+  +----------------+  +----------------+ |
|  |  Conversation  |  |    Tool        |  |   Context      | |
|  |    Loop        |  |   Dispatch     |  |  Compression   | |
|  +----------------+  +----------------+  +----------------+ |
|  +----------------+  +----------------+  +----------------+ |
|  |  Skill Manager |  |  Memory Store  |  |  Model Router  | |
|  +----------------+  +----------------+  +----------------+ |
+-------------------------------------------------------------+
                              |
+-------------------------------------------------------------+
|                     Durable Background                      |
|   Cron Scheduler  |  Curator  |  Kanban  |  Delegation      |
+-------------------------------------------------------------+
                              |
+-------------------------------------------------------------+
|                     Extensions 扩展层                        |
|      MCP Servers  |  Plugins  |  Custom Tools  |  Webhooks  |
+-------------------------------------------------------------+

3. 核心模块详解

3.1 对话引擎 (Conversation Engine)

入口: run_agent.py -> AIAgent

核心循环:

rust 复制代码 
run_conversation():
  1. Build system prompt (环境提示 + Skill 注入 + Memory 注入)
  2. Loop while iterations < max_turns (默认 90):
     a. 调用 LLM (OpenAI-format messages + tool schemas)
     b. 若返回 tool_calls -> 并发调度每个 tool -> 将结果 append 到上下文 -> continue
     c. 若返回文本 -> 输出给用户 -> 等待下一轮输入
  3. 接近 token 上限时自动触发 Context Compression

约束:

  • 严格的消息角色交替: 不允许连续两条 assistant 或连续两条 user 消息
  • Tool 变更不热加载 : 启用/禁用 tool 后需 /reset 开启新会话才生效，以保护 prompt caching

3.2 工具系统 (Tool System)

文件: model_tools.py (发现与分发), tools/registry.py (注册中心), toolsets.py (工具集定义)

注册机制:

python 复制代码 
# 任意 tools/*.py 中顶层调用即自动注册，无需手动导入
registry.register(
    name="example_tool",
    toolset="example",           # 所属工具集
    schema={...},                # JSON Schema
    handler=lambda args, **kw: ...,  # 处理函数
    check_fn=check_requirements,    # 环境检查
    requires_env=["EXAMPLE_API_KEY"],
)

核心工具集 (Toolsets):

工具集 能力
terminal Shell 命令与进程管理
file 文件读写/搜索/补丁
browser 浏览器自动化 (Browserbase/Camofox/本地 Chromium)
web / search 网络搜索与内容提取
code_execution 沙箱 Python 执行
vision 图像分析
image_gen AI 图像生成
video 视频分析与生成
delegation 子代理任务委派
cronjob 定时任务管理
memory 跨会话持久化记忆
session_search 搜索历史会话
todo 会话内任务规划
kanban 多代理协作看板 (仅 worker 进程可见)

默认 bundle: _HERMES_CORE_TOOLS

3.3 模型路由 (Model Router)

  • 支持 20+ 提供商 (OpenRouter, Anthropic, OpenAI, DeepSeek, Google Gemini, xAI, 本地模型等)
  • 配置: ~/.hermes/config.yaml -> model 段
  • 凭证池 (Credential Pools): 多 API Key 自动轮询，避免单 key 限流
  • 辅助模型 (Auxiliary): vision、compression、session_search 等子任务可独立配置 provider/model

3.4 上下文压缩 (Context Compression)

  • 触发阈值: compression.threshold (默认 0.50，即上下文使用 50% 时)
  • 目标压缩率: compression.target_ratio (默认 0.20)
  • 由辅助模型执行摘要，保持关键信息同时缩减 token

3.5 记忆系统 (Memory System)

  • 两种记忆:
    • user_profile: 用户是谁、偏好、沟通风格
    • memory: 环境事实、工具怪癖、项目约定
  • 后端可插拔: built-in (默认) / Honcho / Mem0 等
  • 注入方式: 自动附加到 system prompt 中

4. 持久化后台系统 (Durable Systems)

四个与主对话循环并行的长期运行系统:

4.1 Delegation (子代理委派)

  • 入口: delegate_task 工具
  • 同步阻塞: 父代理等待子代理返回 summary 后才继续
  • 支持单任务和批量并行 (默认最多 3 个并发子代理)
  • 角色: leaf (默认，不可再委派) / orchestrator (可再 spawn worker)
  • 非持久化: 父进程被中断则子进程取消；长时任务应改用 cronjob 或 background terminal

4.2 Cron (定时调度)

  • 模块: cron/jobs.py + cron/scheduler.py
  • 调度语法: 持续时间 (30m)、cron 表达式 (0 9 * * *)、ISO 时间戳
  • 特性:
    • 每任务可绑定独立 model/provider
    • 可附加 script 作为预运行数据采集
    • no_agent=True 时仅运行脚本，不消耗 LLM token
    • context_from 支持任务链式依赖 (A 的输出注入 B 的 prompt)
    • workdir 支持在指定项目目录运行，自动加载该目录的 AGENTS.md/CLAUDE.md
  • 安全: 3 分钟硬中断、.tick.lock 防止重复执行、默认 skip_memory=True

4.3 Curator (Skill 生命周期管理)

  • 作用: 后台维护 agent 创建的 skills
  • 行为: 追踪使用频率、标记闲置 skill 为 stale、归档 stale skill、保留 tar.gz 备份
  • 保护: 仅处理 created_by: "agent" 的 skill； bundled / hub 安装的 skill 不可触碰；永不删除，最大破坏为归档；pinned skill 免疫所有自动操作
  • 遥测: ~/.hermes/skills/.usage.json 记录 use_count / view_count / patch_count / last_activity_at

4.4 Kanban (多代理协作看板)

  • 存储: SQLite 持久化
  • 作用: 多 profile / 多 worker 间的任务队列与协作
  • 角色分离:
    • Dispatcher: 运行在 gateway 内，回收 stale claim、提升 ready 任务、原子化 claim、spawn 分配的 profile
    • Worker : 仅暴露 kanban_* 工具集，环境变量 HERMES_KANBAN_TASK 控制可见性
  • 隔离: board 是硬边界；tenant 是 board 内的软命名空间

5. Gateway (消息网关)

模块: gateway/platforms/

  • 统一抽象层，将不同消息平台的协议差异封装为统一接口
  • 支持平台: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin (WeChat), API Server, Webhooks
  • Open WebUI 通过 API Server 适配器接入
  • 每条消息进入 Gateway 后，转化为统一内部格式，送入 Core Engine 处理
  • 回复通过对应 Platform Adapter 发回原始平台

6. 配置体系

6.1 文件结构

bash 复制代码 
~/.hermes/
├── config.yaml          # 主配置 (可被 hermes config edit/set 管理)
├── .env                 # API keys 与 secrets
├── skills/              # 已安装 skills
│   └── .usage.json      # Curator 遥测
├── sessions/            # 会话转录
├── logs/                # 日志 (gateway.log 等)
├── auth.json            # OAuth tokens / 凭证池
├── hermes-agent/        # 源码目录 (git 安装时)
└── profiles/
    └── <name>/          # Profile 隔离目录 (与 ~/.hermes 同结构)

6.2 核心配置段

配置段 关键项
model default, provider, base_url, api_key, context_length
agent max_turns (90), tool_use_enforcement
terminal backend (local/docker/ssh/modal), cwd, timeout (180s)
compression enabled, threshold (0.50), target_ratio (0.20)
display skin, tool_progress, show_reasoning, show_cost
memory memory_enabled, user_profile_enabled, provider
security tirith_enabled, website_blocklist, redact_secrets
approvals mode (manual/smart/off)
delegation model, provider, max_iterations (50)
checkpoints enabled, max_snapshots (50)
curator enabled, interval_hours, stale_after_days, archive_after_days
kanban dispatch_in_gateway, boards...

7. 安全与隐私架构

机制 默认状态 说明
Secret Redaction 关闭 工具输出中自动掩码 API key/token；需 security.redact_secrets=true 开启，重启生效 (防止 LLM 自行关闭)
PII Redaction 关闭 Gateway 消息中哈希用户 ID、剥离手机号；privacy.redact_pii 控制
Command Approval manual destructive 命令 (rm -rf, git reset --hard) 前弹窗确认；可选 smart/off
Shell Hooks Allowlist 交互提示 首次运行需用户显式允许
YOLO Mode 关闭 --yolo 或 approvals.mode: off 跳过所有确认；不影响 secret redaction

8. 扩展机制

8.1 Skill 体系

  • 存储: ~/.hermes/skills/ (或 profile 隔离目录)
  • 来源: 内置 / Hub 安装 (hermes skills install) / Agent 自创建
  • 加载: 自动扫描 + /skill <name> 手动加载 + -s name 启动时预加载
  • 格式: YAML frontmatter + Markdown body

8.2 MCP (Model Context Protocol)

  • 命令: hermes mcp add/remove/list/test/configure
  • 支持 stdio 与 HTTP 两种传输方式
  • 外部 MCP Server 的工具自动注册到 Hermes 工具集中

8.3 Plugin 体系

  • 命令: hermes plugins list/install/remove
  • 扩展核心功能、新增 gateway 适配器、替换 memory 后端等

8.4 添加自定义 Tool (3 步)

  1. 创建 tools/your_tool.py，调用 registry.register()
  2. 添加环境检查 check_fn 与 requires_env
  3. 如需归类，在 toolsets.py 的 _HERMES_CORE_TOOLS 中声明工具集 (自动发现机制下此步可选)

所有 handler 必须返回 JSON 字符串；路径使用 get_hermes_home() 而非硬编码 ~/.hermes。

8.5 添加 Slash Command

  1. 在 hermes_cli/commands.py 的 COMMAND_REGISTRY 中添加 CommandDef
  2. 在 cli.py 的 process_command() 中实现 handler
  3. (可选) 在 gateway/run.py 中添加 gateway 端 handler

所有消费端 (help 文本、自动补全、Telegram 菜单、Slack 映射) 自动从中央注册表派生。

9. 关键源码目录

bash 复制代码 
hermes-agent/
├── run_agent.py           # AIAgent --- 核心对话循环入口
├── model_tools.py         # 工具发现与分发
├── toolsets.py            # 工具集定义与枚举
├── cli.py                 # 交互式 CLI (HermesCLI)
├── hermes_state.py        # SQLite 会话存储
├── agent/                 # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
├── hermes_cli/            # CLI 子命令、配置、setup、slash commands
│   ├── commands.py        # Slash command 注册中心 (CommandDef)
│   ├── config.py          # DEFAULT_CONFIG, 环境变量定义
│   └── main.py            # CLI 入口与 argparse
├── tools/                 # 每个工具一个文件
│   └── registry.py        # 中央工具注册表
├── gateway/               # 消息网关
│   └── platforms/         # 各平台适配器
├── cron/                  # 定时任务调度器
├── tests/                 # ~3000 pytest 测试
└── website/               # Docusaurus 文档站点

10. 环境适配要点

macOS / Linux (主要平台)

  • 本地终端后端: 直接探测宿主 OS、$HOME、cwd、shell
  • 默认 shell 为 bash

Windows

  • 支持 PowerShell, cmd, Windows Terminal, git-bash mintty, VS Code terminal
  • Alt+Enter 被 Windows Terminal 拦截为全屏切换，使用 Ctrl+Enter 插入换行
  • execute_code 沙箱需保留 SYSTEMROOT/WINDIR/COMSPEC 环境变量，否则 socket 初始化失败 (WinError 10106)
  • 配置文件需 UTF-8 无 BOM，否则首运行报 HTTP 400 "No models provided"
  • terminal.backend != local 时，所有 file 工具在远端容器内执行
  • 系统 prompt 不描述宿主环境，仅描述 backend 本身
  • 通过 tools.environments.get_environment(...).execute(...) 做实时环境探测

11. 相关链接

相关推荐
日月云棠3 小时前
JAVA数据结构与算法 - 基础：链表
java·后端
日月云棠3 小时前
JAVA数据结构与算法 - 基础：栈 (Stack) 深度解析
java·后端
xiguolangzi3 小时前
java使用Map映射遍历方法
java·后端
日月云棠3 小时前
JAVA数据结构与算法 - 基础：队列 (Queue) 全方位解析
java·后端
IT策士4 小时前
Django 从 0 到 1 打造完整电商平台：为什么用 Django 做电商？
后端·python·django
Cosolar4 小时前
吃透 Spring Cloud Gateway：基于 Spring Boot 3 的核心原理、企业级实战与避坑指南
java·spring cloud·架构
一枝小雨4 小时前
RISC-V架构sp寄存器 & RISC-V架构下FreeRTOS任务上下文保存与恢复
单片机·架构·嵌入式·risc-v·rtos·内核原理
进击的松鼠4 小时前
OpenClaw 的五层架构设计与解析
前端·架构·agent
JavaGuide4 小时前
Claude Code 新功能Agent View 发布：终于不用在一堆终端窗口里找 Agent 了！
前端·后端·agent
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓04CC-Switch & Claude 基于 Linux 服务器安装使用指南05【AI】2026 年具身智能模型和世界模型总结06Codex 手机端连接教程：三分钟搞定，附完整步骤07【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09几个好用的ip纯净度检测网站10codex app每次打开重连5次Reconnecting问题解决