Hermes Agent 的 Skills、Plugins、Gateway 深度解析

Hermes Agent 的 Skills、Plugins、Gateway 深度解析

1. 为什么要单独分析这三个系统

如果说：

• run_agent.py是“Agent 大脑主循环”
• tools/是“执行能力层”

那么：

• skills/是“可复用经验层”
• plugins/是“扩展机制层”
• gateway/是“外部接入层”

这三者决定了 Hermes Agent 为什么不是一个封闭单体，而是一个可以持续扩展、接入多生态、多平台、多工作流的系统。

2. Skills 系统：它本质上是什么

Skills 不是 Python 插件，也不是代码模块。

它本质上是一种：

面向 Agent 的、按需加载的知识文档/工作流文档系统。

它解决的问题是：

• 有些能力不需要写成工具代码
• 但又不适合每次都把完整说明塞进 system prompt

于是 Hermes 采用了技能机制：

• 平时只给模型一个技能索引
• 需要时再加载具体 skill 内容
• skill 可以带 references、templates、scripts、assets

这就是文档里所谓的 progressive disclosure。

3. Skills 的核心设计

3.1 数据结构

典型技能目录结构：

<skill-name>/ SKILL.md references/ templates/ scripts/ assets/

SKILL.md是核心。

它一般包含：

• frontmatter
• 使用条件
• 操作步骤
• 常见坑
• 验证方法

3.2 技能发现与索引

相关关键位置：

• agent/skill_commands.py
• agent/skill_utils.py
• tools/skills_tool.py
• tools/skills_hub.py
• hermes_cli/skills_hub.py

工作方式大致是：

1. 扫描本地技能目录
2. 解析SKILL.mdfrontmatter
3. 生成 skill 索引
4. 将 skill 映射为 slash command
5. 在需要时通过skill_view加载完整内容

3.3 技能的“按需加载”

文档中给出了 3 层加载模式：

• skills_list()：只看索引
• skill_view(name)：加载某个技能主内容
• skill_view(name, path)：加载技能附属文件

这种设计的价值非常大：

• 节省 token
• 降低默认 system prompt 膨胀
• 让技能数量可以扩展得很大

4. Skills 的运行方式

4.1 Skill 可以像 slash command 一样使用

例如：

• /plan
• /github-pr-workflow
• /gif-search

说明 skill 在用户感知层像“命令”，但底层其实是文档型能力加载。

4.2 Skill 也可以在自然对话中被调用

这说明 skill 不是强依赖显式 slash command 的，而是 Agent 可主动发现和装载。

4.3 Skill 可以有条件显示

文档明确支持：

• platforms
• fallback_for_toolsets
• requires_toolsets
• fallback_for_tools
• requires_tools

这意味着 skill 系统已经不是简单文件夹扫描，而是具备运行时条件装配能力。

5. Skills Hub：技能生态层

tools/skills_hub.py和hermes_cli/skills_hub.py说明 Hermes 还做了一个更进一步的事情：

把 skills 做成可安装、可搜索、可审计、可隔离来源的生态系统。

它支持的内容包括：

• 官方 optional skills
• GitHub skill source
• lock file
• quarantine
• audit log
• taps
• index cache

这已经非常接近包管理器思路。

5.1 为什么这很重要

因为 skill 一旦规模变大，用户就不可能只靠仓库自带内容：

• 需要外部来源
• 需要 provenance
• 需要审计
• 需要缓存
• 需要信任等级

Hermes 已经显式意识到了这一点。

6. Plugins 系统：它和 Skills 的区别

这是很多人第一次看仓库时最容易混淆的点。

Skill

• 更偏知识/流程
• 通常是 Markdown + 附属文件
• 给 Agent 提示和流程指导
• 不直接修改 Hermes 核心执行逻辑

Plugin

• 是真正的程序级扩展
• 能注册 hook
• 能注册 tool
• 能注册 CLI 子命令
• 能注册 slash command
• 甚至能替换 context engine

所以：

Skill 是“给模型看的能力文档”，Plugin 是“给系统加能力的代码扩展”。

7. Plugins 系统怎么工作

关键文件：

• hermes_cli/plugins.py

它明确写了三种插件来源：

1. 用户插件
   • ~/.hermes/plugins/<name>/
2. 项目插件
   • ./.hermes/plugins/<name>/
3. pip entrypoint 插件
   • hermes_agent.plugins

7.1 一个插件需要什么

目录型插件至少要有：

• plugin.yaml
• __init__.py
• register(ctx)函数

7.2 插件能做什么

从PluginContext看，插件至少可以：

• register_tool(...)
• register_cli_command(...)
• register_command(...)
• dispatch_tool(...)
• inject_message(...)
• register_context_engine(...)

这意味着插件能力很强，几乎能插进系统多个层面。

8. Plugin Hooks：生命周期插点

VALID_HOOKS目前包括：

• pre_tool_call
• post_tool_call
• pre_llm_call
• post_llm_call
• pre_api_request
• post_api_request
• on_session_start
• on_session_end
• on_session_finalize
• on_session_reset

这说明插件机制不是“只支持加载工具”，而是真正支持生命周期扩展。

8.1 这带来的价值

• 可以监控工具调用
• 可以附加上下文
• 可以做审计
• 可以做自定义日志/遥测
• 可以做会话前后处理

8.2 这也带来风险

• Hook 太强，调试复杂度会上升
• 插件之间可能发生行为冲突
• 对时序的依赖会增大

9. Memory Plugins：插件体系中的一个重点方向

plugins/memory/说明 Hermes 已经把“记忆后端”做成插件化能力。

当前可见的 memory plugin 包括：

• honcho
• supermemory
• holographic
• mem0
• openviking
• retaindb
• hindsight
• byterover

9.1 Honcho

从plugins/memory/honcho/README.md看，Honcho 是高度 AI-native 的记忆后端：

• 双层上下文注入
• dialectic reasoning
• session summary
• user / AI peer model
• cadence 控制

它已经不是简单 KV memory，而是偏用户建模系统。

9.2 Supermemory

偏语义记忆服务：

• semantic search
• profile recall
• explicit memory tools
• session-end ingest

9.3 Holographic

偏本地知识库型设计：

• SQLite
• FTS5
• trust scoring
• entity resolution
• HRR retrieval

9.4 说明了什么

这说明 Hermes 的 memory 层不是“写死一个实现”，而是把记忆视为可插拔基础设施。

这是非常平台化的设计思路。

10. Gateway 系统：为什么它是 Hermes 的第二核心

如果不算run_agent.py，我认为仓库里第二重要的系统就是gateway/。

因为它决定了：

• Hermes 能否脱离本地终端使用
• Hermes 能否成为常驻机器人
• Hermes 能否跨平台连续对话
• Hermes 能否把 cron、memory、tool、session 这些能力带到外部世界

11. Gateway 的基本结构

关键文件：

• gateway/run.py
• gateway/config.py
• gateway/session.py
• gateway/delivery.py
• gateway/platforms/base.py
• gateway/platforms/*.py

工作流大致是：

平台消息入站 -> 平台适配器解析 event -> gateway session 解析/构建 session_key -> 构造 AIAgent 或复用会话上下文 -> AIAgent 运行 -> 流式状态/工具进度/审批/提问回调 -> 平台适配器格式化出站消息

12. Gateway 为什么复杂

因为它不是一个单纯 webhook 层，而是同时要处理：

• 多平台差异
• 会话边界
• 多用户/群组/线程
• 中断和排队
• 背景进程通知
• 语音/图片/附件
• 审批流
• session routing
• restart/drain
• platform reconnect

所以tests/gateway/数量非常多是合理的。

13. 平台适配器设计

gateway/platforms/base.py是所有平台适配器的基类。

它提供的典型基础能力包括：

• 消息截断/编码长度处理
• 代理/网络处理
• 平台共通发送接口抽象
• 背景消息与媒体处理辅助

然后每个平台单独实现自己的协议细节。

当前可见平台包括：

• Telegram
• Discord
• Slack
• WhatsApp
• Signal
• Matrix
• Mattermost
• Email
• Dingtalk
• Feishu
• WeCom
• Weixin
• webhook
• Home Assistant
• API server

这说明 Gateway 其实已经是一个“多协议消息操作系统”了。

14. Gateway 的核心价值

14.1 脱离本地终端

你不需要开着终端守着 Hermes。

可以：

• 在 Telegram 上问它
• 在 Discord 上继续同一个 Agent
• 让它在远程机器上工作

14.2 将 Agent 变成“常驻服务”

CLI 更像前台工具。

Gateway 更像服务形态。

14.3 让 cron、send_message、memory 真正有价值

因为只有 Gateway 在，下面这些能力才真正形成闭环：

• 定时任务完成后发消息
• 后台进程完成后通知
• 多渠道 home channel
• session continuity

15. API Server 也是 Gateway 体系的一部分

gateway/platforms/api_server.py特别值得注意。

它让 Hermes 可以对外表现成：

• OpenAI Chat Completions API
• OpenAI Responses API

作用非常大：

• Open WebUI、LobeChat、LibreChat 等前端可以直接接入
• 第三方工具可以把 Hermes 当成“兼容 OpenAI 的 Agent Server”

这相当于把 Hermes 从“应用”变成“服务接口”。

16. Skills、Plugins、Gateway 三者的关系

可以这样理解：

Skills

回答：

“Agent 应该知道怎么做这件事吗？”

Plugins

回答：

“系统本身应该增加什么能力和扩展点？”

Gateway

回答：

“用户和外部平台怎样连接到这个 Agent？”

它们分别处在三个不同层：

• Skills：知识层
• Plugins：系统扩展层
• Gateway：交互接入层

17. 这三个系统的优点

Skills 的优点

• 低成本扩展能力
• 适合沉淀经验
• token 更经济
• 易于社区共享

Plugins 的优点

• 可编程扩展强
• 能注册工具和 hooks
• 适合深度定制

Gateway 的优点

• 让 Hermes 真正成为多平台 Agent
• 支持长期运行和远程交互
• 把消息、自动化、通知、会话串联起来

18. 这三个系统的风险点

Skills 的风险

• skill 质量不均
• 文档可能过时
• prompt injection 风险
• skill 数量膨胀后治理困难

Plugins 的风险

• hook 冲突
• 调试复杂
• 权限边界更难控
• 插件加载顺序与兼容性问题

Gateway 的风险

• 平台差异巨大
• 行为开关多
• 并发和状态同步复杂
• 测试矩阵膨胀

19. 我的结论

Hermes Agent 的强大，不只是因为它有很多工具，而是因为它同时做对了三件更难的事情：

1. 用 Skills 沉淀“经验和流程”
2. 用 Plugins 暴露“系统扩展点”
3. 用 Gateway 把 Agent 送到“真实交互环境”

这三个系统叠加，才让 Hermes 从一个“能调工具的 LLM 应用”，变成一个“可长期演化的 Agent 平台”。

如果你后续要二开，这三个方向分别适合：

• 想快速增强业务知识：优先看 Skills
• 想深度改系统能力：优先看 Plugins
• 想做机器人/平台接入：优先看 Gateway