Hermes Agent 的插件系统:用最少的核心代码,装下最多的可能性

一、为什么要用插件？

打开 Hermes 的 plugins/ 目录，你会看到十几个子目录：

plugins/
├── memory/          # 记忆后端：honcho、mem0、holographic...
├── model-providers/ # 推理后端：anthropic、alibaba、bedrock...
├── platforms/       # 消息平台：discord、telegram、feishu...
├── image_gen/       # 图像生成：openai、fal、xai...
├── spotify/         # Spotify 播放控制
├── disk-cleanup/    # 自动清理临时文件
├── google_meet/     # Google Meet 音频桥接
├── kanban/          # 看板式任务编排
└── ...

这不是"什么都塞进核心"的做法。Hermes 的设计原则很明确：

核心是窄腰，能力在边缘。

每增加一个核心工具，每次 API 调用都要多付一次 token 费用。所以新能力优先以插件形式交付——按需加载，不用不花钱。

二、插件的四种类型

Hermes 的插件系统支持四种 kind，对应不同的扩展方式：

1. backend（后端插件）

最通用的类型。可以注册新工具、挂载钩子、添加 slash 命令。

以 Spotify 插件为例，它的 plugin.yaml：

name:spotify
version:1.0.0
kind:backend
description:"Native Spotify integration — 7 tools using Spotify Web API + PKCE OAuth."
provides_tools:
-spotify_playback
-spotify_devices
-spotify_queue
-spotify_search
-spotify_playlists
-spotify_albums
-spotify_library

七个工具，覆盖播放控制、设备管理、队列操作、搜索、播放列表、专辑、音乐库。只有当用户配置了 Spotify 认证后，这些工具才会出现在 Agent 的工具列表中。

2. model_provider（模型提供商）

接入新的推理后端。目前 plugins/model-providers/ 下有超过 20 个提供商：anthropic、alibaba、azure-foundry、bedrock、openrouter、gemini……每个提供商只需实现模型列表和 API 调用逻辑，其余路由、重试、降级由核心处理。

3. platform（消息平台）

让 Agent 能在不同聊天平台上运行。Discord、Telegram、Slack、飞书、钉钉、企业微信、Google Chat、Home Assistant……每个平台是一个独立适配器，实现消息收发和会话管理。

4. hook（钩子插件）

最轻量的扩展方式。不增加工具，只在特定事件发生时执行逻辑。

以 disk-cleanup 插件为例：

name:disk-cleanup
version:2.0.0
description:"Auto-track and clean up ephemeral files created during sessions."
hooks:
-post_tool_call# 每次工具调用后检查
-on_session_end# 会话结束时清理

它在 post_tool_call 钩子中静默追踪新创建的临时文件，在 on_session_end 时自动清理。Agent 完全不需要知道这个插件的存在——零侵入。

三、plugin.yaml：插件的身份证

每个插件目录必须有一个 plugin.yaml，声明元数据和加载规则：

name:my-plugin# 唯一标识
version:1.0.0# 版本号
kind:backend# 插件类型
description:"..."# 描述
author:"@yourname"# 作者

# 可选字段
provides_tools: [...]    # 提供的工具列表
hooks: [...]             # 挂载的钩子
kind:model_provider# 或 platform、hook

加载器（plugins.py 中的 discover_plugins()）扫描所有插件目录，读取 plugin.yaml，根据 kind 决定如何注册。

四、加载流程：自动发现，按需启用

启动
  ↓
discover_plugins()
扫描 ~/.hermes/plugins/ 和内置 plugins/
  ↓
读取每个插件的 plugin.yaml
  ↓
根据 kind 分类注册：
  backend  → 注册工具 + 钩子
  provider → 注册模型路由
  platform → 注册消息适配器
  hook     → 注册事件监听
  ↓
检查启用状态（config.yaml 或 hermes tools 命令）
  ↓
已启用的插件 → 工具进入 Agent schema
未启用的插件 → 跳过，不占 token

关键设计：未启用的插件不会出现在模型的工具列表中。这意味着你可以安装 50 个插件，但只有实际使用的 5 个会影响 API 调用成本。

五、插件能力系统（Plugin Capabilities）

插件不只是"加几个工具"。plugin_capabilities.py 定义了一套标准化的能力接口，让插件可以深入参与 Agent 的行为：

• 记忆后端
  替换默认的内存存储，接入 honcho、mem0 等外部记忆系统
• 上下文引擎
  自定义上下文文件的加载和处理逻辑
• 认证提供者
  集成 OAuth、API Key 等多种认证方式
• 看板调度
  将 Agent 接入 Kanban 工作流

这套接口通过 ABC（抽象基类）定义，插件只需实现对应方法即可接入。核心代码不依赖任何具体插件——依赖倒置，插件可插拔。

六、社区插件索引

除了内置插件，Hermes 还有一个社区插件索引（plugin_index.py），类似 Skills Hub 的模式：

远程索引 → 本地缓存（24h TTL）→ 内置种子（离线兜底）

搜索社区插件：

hermes plugins search spotify

安装社区插件：

hermes plugins install owner/repo

索引条目会固定一个不可变的 ref（tag 或 commit SHA），确保安装的可重复性。

值得注意的是，索引明确声明：Indexed ≠ audited。收录只意味着元数据经过审核，不代表代码经过审计。安装前务必自行检查。

七、写一个最简单的插件

假设你想让 Agent 在每次会话结束时打印一句总结。只需三步：

1. 创建目录和 plugin.yaml：

~/.hermes/plugins/session-summary/
├── plugin.yaml
└── __init__.py

name:session-summary
version:1.0.0
kind:hook
description:"Print a summary when a session ends."
hooks:
-on_session_end

2. 实现钩子逻辑（init.py）：

defon_session_end(session_id, context):
print(f"Session {session_id} finished.")

3. 启用插件：

hermes tools enable session-summary

完成。下次会话结束时，你会看到打印输出。

八、设计哲学总结

Hermes 的插件系统不是"越多越好"的堆砌，而是"核心保持窄腰，能力在边缘生长"的有机扩展。每个插件都有明确的边界、清晰的接口、独立的启用开关。

这才是插件系统该有的样子。