构建 Hermes 插件

本指南从零开始构建一个完整的 Hermes 插件。完成后，你将拥有一个包含多个工具、生命周期钩子（hook）、随附数据文件和捆绑技能的可用插件——涵盖插件系统支持的所有功能。

:::info 不确定需要哪份指南？
Hermes 有多种不同的可插拔接口——有些使用 Python register_* API，另一些是配置驱动或放入指定目录即可生效。请先查阅下表：

如果你想添加…	请阅读
自定义工具、钩子、斜杠命令、技能或 CLI 子命令	本指南（通用插件接口）
LLM / 推理后端（新提供商）	模型提供商插件
网关频道（Discord/Telegram/IRC/Teams 等）	添加平台适配器
记忆后端（Honcho/Mem0/Supermemory 等）	记忆提供商插件
上下文压缩引擎	上下文引擎插件
图像生成后端	图像生成提供商插件
视频生成后端	视频生成提供商插件
TTS 后端（任意 CLI——Piper、VoxCPM、Kokoro、声音克隆等）	TTS 自定义命令提供商——配置驱动，无需 Python
STT 后端（自定义 whisper / ASR CLI）	语音消息转录——将 `HERMES_LOCAL_STT_COMMAND` 设置为 shell 模板
通过 MCP 接入外部工具（文件系统、GitHub、Linear、任意 MCP 服务器）	MCP——在 `config.yaml` 中声明 `mcp_servers.<name>`
网关事件钩子（在启动、会话事件、命令时触发）	事件钩子——将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/`
Shell 钩子（在事件发生时运行 shell 命令）	Shell 钩子——在 `config.yaml` 的 `hooks:` 下声明
额外技能来源（自定义 GitHub 仓库、私有技能索引）	技能——`hermes skills tap add <repo>` · 发布 tap
一流的核心推理提供商（非插件）	添加提供商

查看完整的可插拔接口表，获取每种扩展接口的汇总视图，包括配置驱动（TTS、STT、MCP、shell 钩子）和放入目录（网关钩子）两种方式。
:::

你将构建什么

一个计算器插件，包含两个工具：

calculate——计算数学表达式（2**16、sqrt(144)、pi * 5**2）

unit_convert——在单位之间转换（100 F → 37.78 C、5 km → 3.11 mi）

另外还有一个记录每次工具调用的钩子，以及一个捆绑的技能文件。

第一步：创建插件目录

第二步：编写清单文件

创建 plugin.yaml：

这告诉 Hermes："我是一个名为 calculator 的插件，我提供工具和钩子。" provides_tools 和 provides_hooks 字段是插件注册内容的列表。

可选字段示例：

第三步：编写工具 schema

创建 schemas.py——这是 LLM 读取以决定何时调用你的工具的内容：

schema 为何重要： description 字段决定了 LLM 何时使用你的工具。请明确说明工具的功能和使用时机。parameters 定义了 LLM 传入的参数。

第四步：编写工具处理器

创建 tools.py——这是 LLM 调用工具时实际执行的代码：

处理器的关键规则：

签名： def my_handler(args: dict, **kwargs) -> str

返回值： 始终返回 JSON 字符串。成功和错误均如此。

不要抛出异常： 捕获所有异常，改为返回错误 JSON。

接受 **kwargs： Hermes 未来可能传入额外上下文。

第五步：编写注册代码

创建 __init__.py——将 schema 与处理器连接起来：

register() 的作用：

在启动时恰好调用一次

ctx.register_tool() 将你的工具放入注册表——模型立即可见

ctx.register_hook() 订阅生命周期事件

ctx.register_cli_command() 注册 CLI 子命令（例如 hermes my-plugin <subcommand>）

ctx.register_command() 注册会话内斜杠命令（例如在 CLI / 网关聊天中输入 /myplugin <args>）——详见下方注册斜杠命令

ctx.dispatch_tool(name, arguments) ——以父代理的上下文（审批、凭证、task_id 自动连接）调用任意其他工具（内置或来自其他插件）。适用于需要直接调用 terminal、read_file 或其他工具的斜杠命令处理器，效果等同于模型直接调用。

如果此函数崩溃，插件将被禁用，但 Hermes 继续正常运行

dispatch_tool 示例——执行工具的斜杠命令：

被分发的工具会经过正常的审批、脱敏和预算流程——这是真实的工具调用，而非绕过这些流程的捷径。

第六步：测试

启动 Hermes：

你应该在启动横幅的工具列表中看到 calculator: calculate, unit_convert。

尝试以下提示词（prompt）：

What's 2 to the power of 16?
Convert 100 fahrenheit to celsius
What's the square root of 2 times pi?
How many gigabytes is 1.5 terabytes?

检查插件状态：

/plugins

输出：

Plugins (1):
  ✓ calculator v1.0.0 (2 tools, 1 hooks)

调试插件发现问题

如果你的插件没有出现，或出现了但未加载——设置 HERMES_PLUGINS_DEBUG=1 可在 stderr 获取详细的发现日志：

你将看到每个插件来源（内置、用户、项目、entry-points）的以下信息：

每个清单：解析后的键、名称、类型、来源、磁盘路径

跳过原因：disabled via config、not enabled in config、exclusive plugin、no plugin.yaml, depth cap reached

加载时：正在导入的插件，以及 register(ctx) 注册内容的单行摘要（工具、钩子、斜杠命令、CLI 命令）

解析失败时：异常的完整堆栈跟踪（YAML 扫描器错误等）

register() 失败时：指向 __init__.py 中抛出异常的行的完整堆栈跟踪

同样的日志始终写入 ~/.hermes/logs/agent.log，失败时为 WARNING 级别，设置环境变量时为 DEBUG 级别（全部内容）。如果无法使用环境变量运行（例如从网关内部），可以改为追踪日志文件：

插件未出现的常见原因：

未在配置中启用——插件需要手动启用。运行 hermes plugins enable <name>（名称来自 plugins list 输出，嵌套布局下可能是 <category>/<plugin>）。

目录结构错误——必须是 ~/.hermes/plugins/<plugin-name>/plugin.yaml（扁平）或 ~/.hermes/plugins/<category>/<plugin-name>/plugin.yaml（一级分类嵌套，最多）。更深层的目录会被忽略。

缺少 __init__.py——插件目录需要同时包含 plugin.yaml 和带有 register(ctx) 函数的 __init__.py。

kind 错误——网关适配器需要在清单中设置 kind: platform。记忆提供商会被自动检测为 kind: exclusive，并通过 memory.provider 配置路由，而非 plugins.enabled。

插件的最终结构

~/.hermes/plugins/calculator/
├── plugin.yaml      # "我是 calculator，我提供工具和钩子"
├── __init__.py      # 连接：schema → 处理器，注册钩子
├── schemas.py       # LLM 读取的内容（描述 + 参数规格）
└── tools.py         # 实际运行的代码（calculate、unit_convert 函数）

四个文件，职责清晰：

清单声明插件是什么

Schema 向 LLM 描述工具

处理器实现实际逻辑

注册将一切连接起来

插件还能做什么？

随附数据文件

将任意文件放入插件目录，并在导入时读取：

捆绑技能

插件可以随附技能文件，代理通过 skill_view("plugin:skill") 加载。在 __init__.py 中注册：

~/.hermes/plugins/my-plugin/
├── __init__.py
├── plugin.yaml
└── skills/
    ├── my-workflow/
    │   └── SKILL.md
    └── my-checklist/
        └── SKILL.md

代理现在可以通过命名空间名称加载你的技能：

关键特性：

插件技能是只读的——它们不会进入 ~/.hermes/skills/，也无法通过 skill_manage 编辑。

插件技能不会列在系统提示词的 <available_skills> 索引中——需要显式加载。

裸技能名称不受影响——命名空间防止与内置技能冲突。

代理加载插件技能时，会在前面添加一个捆绑上下文横幅，列出同一插件的兄弟技能。

旧版模式

旧的 shutil.copy2 模式（将技能复制到 ~/.hermes/skills/）仍然有效，但存在与内置技能名称冲突的风险。新插件请优先使用 ctx.register_skill()。

根据环境变量决定是否启用

如果你的插件需要 API 密钥：

如果 WEATHER_API_KEY 未设置，插件将被禁用并显示清晰的提示信息。不会崩溃，代理中也不会报错——只会显示"Plugin weather disabled (missing: WEATHER_API_KEY)"。

用户运行 hermes plugins install 时，会交互式提示输入任何缺失的 requires_env 变量。值会自动保存到 .env。

为了获得更好的安装体验，使用带有描述和注册 URL 的富格式：

字段	必填	描述
`name`	是	环境变量名称
`description`	否	安装提示时显示给用户
`url`	否	获取凭证的地址
`secret`	否	若为 `true`，输入时隐藏（类似密码字段）

两种格式可在同一列表中混用。已设置的变量会被静默跳过。

懒加载可选 Python 依赖

如果你的插件封装了一个并非所有用户都会安装的 SDK（供应商 SDK、重型 ML 库、平台特定包），不要在模块顶部 import 它。在工具处理器内部使用 tools.lazy_deps.ensure(...) 辅助函数——Hermes 会在首次使用时安装该包，并受用户 security.allow_lazy_installs 配置的控制。

来自 tools/lazy_deps.py 安全模型的两条规则：

规则	原因
你的功能键必须出现在内置的 `LAZY_DEPS` 允许列表中	防止恶意配置诱使 Hermes 安装任意包——只有 Hermes 自身随附的规格才符合条件
规格仅限 PyPI 包名	不允许 `--index-url`、`git+https://` 或 `file:` 路径。在允许列表条目中使用 PEP 440 固定版本（`"my-sdk>=1.2,<2"`）

对于通过 pip 分发的第三方插件，在你自己的 pyproject.toml 中将可选依赖声明为 [project.optional-dependencies] extras，并告知用户执行 pip install your-plugin[backend]——该路径不经过 lazy_deps。懒加载安装最适合内置插件，因为对每次安装都强制依赖会增加 Hermes 基础安装的体积。

当全局设置 security.allow_lazy_installs: false 时，ensure() 会立即抛出 FeatureUnavailable 并附带修复提示——你的插件应捕获该异常并优雅降级（返回错误结果，而非让工具循环崩溃）。

条件工具可用性

对于依赖可选库的工具：

覆盖内置工具

要用你自己的实现替换内置工具（例如将默认浏览器工具替换为有头 Chrome CDP 后端，或将 web_search 替换为自定义企业索引），传入 override=True：

不加 override=True 时，注册表会拒绝任何会遮蔽来自不同 toolset 的已有工具的注册——这防止了意外覆盖。覆盖操作会以 INFO 级别记录日志，可在 ~/.hermes/logs/agent.log 中审计。插件在内置工具之后加载，因此注册顺序是正确的：你的处理器会替换内置处理器。

注册多个钩子

钩子参考

每个钩子的完整文档见**事件钩子参考**——回调签名、参数表、触发时机和示例。以下是摘要：

钩子	触发时机	回调签名	返回值
`pre_tool_call`	任意工具执行前	`tool_name: str, args: dict, task_id: str`	忽略
`post_tool_call`	任意工具返回后	`tool_name: str, args: dict, result: str, task_id: str, duration_ms: int`	忽略
`pre_llm_call`	每轮一次，工具调用循环前	`session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str`	上下文注入
`post_llm_call`	每轮一次，工具调用循环后（仅成功轮次）	`session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str`	忽略
`on_session_start`	新会话创建（仅第一轮）	`session_id: str, model: str, platform: str`	忽略
`on_session_end`	每次 `run_conversation` 调用结束 + CLI 退出	`session_id: str, completed: bool, interrupted: bool, model: str, platform: str`	忽略
`on_session_finalize`	CLI/网关销毁活跃会话	`session_id: str \| None, platform: str`	忽略
`on_session_reset`	网关切换新会话键（`/new`、`/reset`）	`session_id: str, platform: str`	忽略

大多数钩子是即发即忘的观察者——其返回值被忽略。例外是 pre_llm_call，它可以向对话中注入上下文。

所有回调都应接受 **kwargs 以保持向前兼容性。如果钩子回调崩溃，会被记录日志并跳过。其他钩子和代理继续正常运行。

`pre_llm_call` 上下文注入

这是唯一一个返回值有意义的钩子。当 pre_llm_call 回调返回包含 "context" 键的字典（或纯字符串）时，Hermes 会将该文本注入当前轮次的用户消息中。这是记忆插件、RAG 集成、护栏以及任何需要向模型提供额外上下文的插件所使用的机制。

返回格式

任何非 None、非空的返回值，只要包含 "context" 键（或为非空纯字符串），都会被收集并追加到当前轮次的用户消息中。

注入的工作原理

注入的上下文追加到用户消息，而非系统提示词（system prompt）。这是有意为之的设计：

保留提示词缓存——系统提示词在各轮次之间保持不变。Anthropic 和 OpenRouter 会缓存系统提示词前缀，保持其稳定可在多轮对话中节省 75% 以上的输入 token。如果插件修改系统提示词，每轮都会缓存未命中。

临时性——注入仅在 API 调用时发生。会话历史中的原始用户消息不会被修改，也不会持久化到会话数据库。

系统提示词是 Hermes 的领地——它包含模型特定的指导、工具执行规则、个性指令和缓存的技能内容。插件在用户输入旁边贡献上下文，而非修改代理的核心指令。

示例：记忆召回插件

示例：护栏插件

示例：仅观察钩子（不注入）

多个插件返回上下文

当多个插件从 pre_llm_call 返回上下文时，它们的输出以双换行符连接，一起追加到用户消息中。顺序遵循插件发现顺序（按插件目录名称字母排序）。

注册 CLI 命令

插件可以添加自己的 hermes <plugin> 子命令树：

注册后，用户可以运行 hermes my-plugin status、hermes my-plugin config 等命令。

记忆提供商插件使用基于约定的方式：在插件的 cli.py 文件中添加 register_cli(subparser) 函数。记忆插件发现系统会自动找到它——无需调用 ctx.register_cli_command()。详见记忆提供商插件指南。

活跃提供商限制： 记忆插件 CLI 命令仅在其提供商是配置中活跃的 memory.provider 时才会出现。如果用户尚未设置你的提供商，你的 CLI 命令不会出现在帮助输出中。

注册斜杠命令

插件可以注册会话内斜杠命令——用户在对话中输入的命令（如 /lcm status 或 /ping）。这些命令在 CLI 和网关（Telegram、Discord 等）中均可使用。

注册后，用户可以在任意会话中输入 /mystatus。该命令会出现在自动补全、/help 输出和 Telegram 机器人菜单中。

签名： ctx.register_command(name: str, handler: Callable, description: str = "")

参数	类型	描述
`name`	`str`	不含前导斜杠的命令名称（例如 `"lcm"`、`"mystatus"`）
`handler`	`Callable[[str], str \| None]`	以原始参数字符串调用。也可以是 `async`。
`description`	`str`	显示在 `/help`、自动补全和 Telegram 机器人菜单中

与 register_cli_command() 的主要区别：

	`register_command()`	`register_cli_command()`
调用方式	会话中的 `/name`	终端中的 `hermes name`
适用范围	CLI 会话、Telegram、Discord 等	仅终端
处理器接收	原始参数字符串	argparse `Namespace`
使用场景	诊断、状态查询、快速操作	复杂子命令树、设置向导

冲突保护： 如果插件尝试注册与内置命令（help、model、new 等）冲突的名称，注册会被静默拒绝并记录警告日志。内置命令始终优先。

异步处理器： 网关分发会自动检测并 await 异步处理器，因此可以使用同步或异步函数：

从斜杠命令分发工具

需要编排工具的斜杠命令处理器（生成子代理 delegate_task、调用 file_edit 等）应使用 ctx.dispatch_tool()，而非深入框架内部。父代理上下文（工作区提示、spinner、模型继承）会自动连接。

签名： ctx.dispatch_tool(name: str, args: dict, *, parent_agent=None) -> str

参数	类型	描述
`name`	`str`	工具注册表中的工具名称（例如 `"delegate_task"`、`"file_edit"`）
`args`	`dict`	工具参数，与模型发送的格式相同
`parent_agent`	`Agent \| None`	可选覆盖。省略时从当前 CLI 代理解析（网关模式下优雅降级）

运行时行为：

CLI 模式： parent_agent 从活跃的 CLI 代理解析，工作区提示、spinner 和模型选择按预期继承。

网关模式： 没有 CLI 代理，工具优雅降级——工作区从 TERMINAL_CWD 读取，不显示 spinner。

显式覆盖： 如果调用者显式传入 parent_agent=，则尊重该值，不会被覆盖。

这是从插件命令分发工具的公开稳定接口。插件不应访问 ctx._cli_ref.agent 或类似的私有状态。

提示

本指南涵盖通用插件（工具、钩子、斜杠命令、CLI 命令）。以下各节简要介绍每种专用插件类型的编写模式；每节均链接到其完整指南以获取字段参考和示例。

专用插件类型

Hermes 在通用接口之外还有五种专用插件类型。每种都以目录形式存放在 plugins/<category>/<name>/（内置）或 ~/.hermes/plugins/<category>/<name>/（用户）下。各类别的约定不同——选择你需要的类型，然后阅读其完整指南。

模型提供商插件——添加 LLM 后端

在 plugins/model-providers/<name>/ 下放置一个配置文件：

在任何调用 get_provider_profile() 或 list_providers() 的地方首次使用时懒加载发现——auth.py、config.py、doctor.py、models.py、runtime_provider.py 和 chat_completions 传输层会自动连接。用户插件按名称覆盖内置插件。

完整指南： 模型提供商插件——字段参考、可覆盖钩子（prepare_messages、build_extra_body、build_api_kwargs_extras、fetch_models）、api_mode 选择、认证类型、测试。

平台插件——添加网关频道

在 plugins/platforms/<name>/ 下放置适配器：

完整指南： 添加平台适配器——完整的 BasePlatformAdapter 约定、消息路由、认证限制、设置向导集成。参考 plugins/platforms/irc/ 获取仅使用标准库的可用示例。

记忆提供商插件——添加跨会话知识后端

在 plugins/memory/<name>/ 下实现 MemoryProvider：

记忆提供商是单选的——同一时间只有一个处于活跃状态，通过 config.yaml 中的 memory.provider 选择。

完整指南： 记忆提供商插件——完整的 MemoryProvider ABC、线程约定、配置文件隔离、通过 cli.py 注册 CLI 命令。

上下文引擎插件——替换上下文压缩器

上下文引擎是单选的——通过 config.yaml 中的 context.engine 选择。

完整指南： 上下文引擎插件。

图像生成后端

在 plugins/image_gen/<name>/ 下放置提供商：

完整指南： 图像生成提供商插件——完整的 ImageGenProvider ABC、list_models() / get_setup_schema() 元数据、success_response()/error_response() 辅助函数、base64 与 URL 输出、用户覆盖、pip 分发。

参考示例： plugins/image_gen/openai/（DALL-E / GPT-Image via OpenAI SDK）、plugins/image_gen/openai-codex/、plugins/image_gen/xai/（Grok 图像生成）。

非 Python 扩展接口

Hermes 也接受完全不是 Python 插件的扩展。这些在可插拔接口表中有所展示；以下各节简要介绍每种编写方式。

MCP 服务器——注册外部工具

Model Context Protocol（MCP）服务器无需任何 Python 插件即可将自己的工具注册到 Hermes。在 ~/.hermes/config.yaml 中声明：

Hermes 在启动时连接到每个服务器，列出其工具，并与内置工具一起注册。LLM 看到它们的方式与其他工具完全相同。完整指南： MCP。

网关事件钩子——在生命周期事件时触发

将清单和处理器放入 ~/.hermes/hooks/<name>/：

事件包括 gateway:startup、session:start、session:end、session:reset、agent:start、agent:step、agent:end 以及通配符 command:*。钩子中的错误会被捕获并记录日志——它们不会阻塞主流程。

完整指南： 网关事件钩子。

Shell 钩子——在工具调用时运行 shell 命令

如果你只想在工具触发时运行脚本（通知、审计日志、桌面提醒、自动格式化），在 config.yaml 中使用 shell 钩子——无需 Python：

支持与 Python 插件钩子相同的所有事件（pre_tool_call、post_tool_call、pre_llm_call、post_llm_call、on_session_start、on_session_end、pre_gateway_dispatch），以及用于 pre_tool_call 阻断决策的结构化 JSON 输出。

完整指南： Shell 钩子。

技能来源——添加自定义技能注册表

如果你维护了一个技能 GitHub 仓库（或想从内置来源之外的社区索引拉取），将其添加为 tap：

发布你自己的 tap 只需一个包含 skills/<skill-name>/SKILL.md 目录的 GitHub 仓库——无需服务器或注册表注册。

完整指南： 技能中心 · 发布自定义 tap（仓库结构、最小示例、非默认路径、信任级别）。

通过命令模板接入 TTS / STT

任何读写音频或文本的 CLI 都可以通过 config.yaml 接入——无需 Python 代码：

对于 STT，将 HERMES_LOCAL_STT_COMMAND 指向一个 shell 模板。支持的占位符：{input_path}、{output_path}、{format}、{voice}、{model}、{speed}（TTS）；{input_path}、{output_dir}、{language}、{model}（STT）。任何与路径交互的 CLI 都自动成为插件。

完整指南： TTS 自定义命令提供商 · STT。

通过 pip 分发

如需公开分享插件，在你的 Python 包中添加 entry point：

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-plugin = "my_plugin_package"

为 NixOS 分发

如果你提供了带有 entry points 的 pyproject.toml，NixOS 用户可以声明式安装你的插件：

Entry-point 插件（推荐用于分发）：

目录插件（无需 pyproject.toml）：

完整文档（包括 overlay 用法和冲突检查）见 Nix 设置指南。

常见错误

处理器未返回 JSON 字符串：

处理器签名缺少 **kwargs：

处理器抛出异常：

Schema 描述过于模糊：

"构建 Hermes 插件"

构建 Hermes 插件#

你将构建什么#

第一步：创建插件目录#

第二步：编写清单文件#

第三步：编写工具 schema#

第四步：编写工具处理器#

第五步：编写注册代码#

第六步：测试#

调试插件发现问题#

插件的最终结构#

插件还能做什么？#

随附数据文件#

捆绑技能#

根据环境变量决定是否启用#

懒加载可选 Python 依赖#

条件工具可用性#

覆盖内置工具#

注册多个钩子#

钩子参考#

pre_llm_call 上下文注入#

返回格式#

注入的工作原理#

示例：记忆召回插件#

示例：护栏插件#

示例：仅观察钩子（不注入）#

多个插件返回上下文#

注册 CLI 命令#

注册斜杠命令#

从斜杠命令分发工具#

专用插件类型#

模型提供商插件——添加 LLM 后端#

平台插件——添加网关频道#

记忆提供商插件——添加跨会话知识后端#

上下文引擎插件——替换上下文压缩器#

图像生成后端#

非 Python 扩展接口#

MCP 服务器——注册外部工具#

网关事件钩子——在生命周期事件时触发#

Shell 钩子——在工具调用时运行 shell 命令#

技能来源——添加自定义技能注册表#

通过命令模板接入 TTS / STT#

通过 pip 分发#

为 NixOS 分发#

常见错误#

构建 Hermes 插件

你将构建什么

第一步：创建插件目录

第二步：编写清单文件

第三步：编写工具 schema

第四步：编写工具处理器

第五步：编写注册代码

第六步：测试

调试插件发现问题

插件的最终结构

插件还能做什么？

随附数据文件

捆绑技能

根据环境变量决定是否启用

懒加载可选 Python 依赖

条件工具可用性

覆盖内置工具

注册多个钩子

钩子参考

`pre_llm_call` 上下文注入

返回格式

注入的工作原理

示例：记忆召回插件

示例：护栏插件

示例：仅观察钩子（不注入）

多个插件返回上下文

注册 CLI 命令

注册斜杠命令

从斜杠命令分发工具

专用插件类型

模型提供商插件——添加 LLM 后端

平台插件——添加网关频道

记忆提供商插件——添加跨会话知识后端

上下文引擎插件——替换上下文压缩器

图像生成后端

非 Python 扩展接口

MCP 服务器——注册外部工具

网关事件钩子——在生命周期事件时触发

Shell 钩子——在工具调用时运行 shell 命令

技能来源——添加自定义技能注册表

通过命令模板接入 TTS / STT

通过 pip 分发

为 NixOS 分发

常见错误