🤖HermesBlog
Hermes 功能详解 · 第9篇2026/8/9· Easy Understand Hermes Agent

第9篇：插件系统——无限扩展 Hermes

Hermes 功能详解第9篇：插件系统。不满足于内置功能？插件让 Hermes 能力无限扩展。

插件系统：给 Hermes 装 App

第9篇：插件系统——无限扩展 Hermes

嘿，朋友们！今天咱们来聊聊 Hermes 的插件系统——说白了，就是给 Hermes 装 App。不用改核心代码，丢个文件夹进去，它就能多出一堆新本事。

一个插件长啥样

在 ~/.hermes/plugins/ 下建个目录，放一个 plugin.yaml 加几个 Python 文件就行：

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # 清单
├── __init__.py      # register() —— 把 schema 和 handler 接起来
├── schemas.py       # 工具 schema（LLM 看到的东西）
└── tools.py         # 工具 handler（被调用时真正跑的代码）

重启 Hermes，你的工具就和内置工具并排出现了，模型马上就能调用。想跟着完整例子一步步做，看官方那篇 Build a Hermes Plugin。

插件能干啥

在插件的 register(ctx) 函数里，这些 ctx.* API 都能用：

  • 加工具：ctx.register_tool(...)
  • 加钩子：ctx.register_hook("post_tool_call", callback)
  • 加斜杠命令：ctx.register_command(...)，CLI 和网关会话里都能用 /名字
  • 加 CLI 子命令：ctx.register_cli_command(...)，变成 hermes <插件> <子命令>
  • 注入消息：ctx.inject_message(...)
  • 打包技能：ctx.register_skill(...)，命名空间是 plugin:skill
  • 借用宿主 LLM：ctx.llm.complete(...) / ctx.llm.complete_structured(...)，直接借用户当前在用的模型和鉴权跑一次性补全，还能带 JSON schema 校验
  • 调 MCP 工具：ctx.call_mcp(server, tool, arguments, timeout=30)

再往深了玩，插件还能注册一整个后端：

  • 网关平台（Discord、Telegram、IRC 等）：ctx.register_platform(...)
  • 图像生成后端：ctx.register_image_gen_provider(provider)
  • 视频生成后端：ctx.register_video_gen_provider(provider)
  • 上下文压缩引擎：ctx.register_context_engine(engine)
  • 终端执行后端（云沙箱）：ctx.register_terminal_environment_provider(provider)
  • 记忆后端：在 plugins/memory/<名字>/__init__.py 里继承 MemoryProvider（走的是另一套发现机制）
  • 推理后端（LLM 供应商）：在 plugins/model-providers/<名字>/__init__.py 里 register_provider(ProviderProfile(...))（也是独立发现机制）

插件从哪来

Hermes 会在好几个地方找插件：

来源 路径 用途
内置 <repo>/plugins/ 随 Hermes 一起发布
用户 ~/.hermes/plugins/ 你自己的插件
项目 .hermes/plugins/ 项目专用（要设 HERMES_ENABLE_PROJECT_PLUGINS=true）
pip hermes_agent.plugins entry_points 分发的包
Nix services.hermes-agent.extraPlugins / extraPythonPackages NixOS 声明式安装

同名冲突时，后面的来源会覆盖前面的——所以你自己写的同名插件能顶掉内置的。

插件默认是关着的

通用插件和用户装的后端默认不加载——Hermes 能发现它们（hermes plugins 和 /plugins 里看得到），但在你把名字加进 ~/.hermes/config.yaml 的 plugins.enabled 之前，带钩子或工具的东西一个都不会跑。这是为了防止第三方代码未经你同意就执行。

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # 可选的拒绝名单，两边都出现时它赢
    - noisy-plugin

三种切换方式：

hermes plugins                    # 交互式开关（空格勾选/取消）
hermes plugins enable <名字>      # 加进允许名单
hermes plugins disable <名字>     # 从允许名单移除并加进 disabled

hermes plugins install owner/repo 装完后会问你 Enable 'name' now? [y/N]，默认是不启用。脚本化安装可以用 --enable 或 --no-enable 跳过提问。

想装得可复现，可以钉死一个完整的 commit（标签、分支、缩写 SHA 都不收）：

hermes plugins install owner/repo --ref 0123456789abcdef0123456789abcdef01234567

钉住之后 hermes plugins update 不会动它，要换得显式用 --force --ref <新commit> 重新装。桌面端也有对应的 Pin to commit 输入框，列表里会显示 pinned @ <sha8> 徽章。

装私有仓库的插件

hermes plugins install 克隆时不会弹用户名密码，所以私有仓库得让 Hermes 自己找得到凭据。每次克隆、--ref 拉取和 hermes plugins update 都会先匿名试一次——公开仓库永远看不到你的凭据，所以过期的 token 也不会把公开安装搞坏。只有远端拒绝匿名访问时，Hermes 才去找凭据。对 https:// 来源，按顺序试：

  1. .env 里的 GITHUB_TOKEN 或 GH_TOKEN（仅 GitHub）
  2. gh CLI 的登录态（gh auth login，仅 GitHub）
  3. 你的 git credential helper（git credential fill）——GitLab、Bitbucket、自建服务器只要存过凭据都能用

凭据只在那次安装或更新时作为一次性 HTTP header 发出去，绝不会写进插件的 .git/config 或安装元数据。SSH 来源（git@host:owner/repo.git）还是走 ssh-agent。

哪些东西不受允许名单管

有几类插件会绕过 plugins.enabled——它们是 Hermes 内置能力的一部分，默认关掉会坏事儿：

  • 内置平台插件（plugins/platforms/ 下的 IRC、Teams 等）：自动加载，具体频道由 gateway.platforms.<名字>.enabled 控制
  • 内置后端（plugins/image_gen/ 等）：自动加载，用 <类别>.provider 选
  • 记忆后端：全部被发现，同时只有一个生效，由 memory.provider 选
  • 上下文引擎：同上，由 context.engine 选
  • 模型供应商：内置的全部注册，用 --provider 或 config 一次选一个
  • pip 装的 backend 插件：还是要 plugins.enabled 显式开启
  • 用户装的平台插件（~/.hermes/plugins/platforms/）：也要显式开启，第三方网关适配器得你点头

一句话：内置的“开箱即用”基础设施自动加载，第三方的东西一律要你同意。

小细节，大用心

  • 插件可以注册 hermes_cli.plugins.VALID_HOOKS 里那 27 个生命周期事件，具体时机和返回值看 Event Hooks 目录
  • 项目本地插件（./.hermes/plugins/）默认禁用，只在可信仓库里开
  • 模型看到的工具描述写在 schema["description"] 里；ctx.register_tool(description=...) 那个是注册表元数据，两处都写的话记得保持同步，模型只认 schema 里的

插件配好了，你的 Hermes 才算真正长出了自己的样子。下篇咱们聊聊怎么让它更懂你！

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/features/plugins

← 返回全部文章