插件

Hermes 拥有插件系统，可在不修改核心代码的情况下添加自定义工具、钩子和集成。

→ 构建一个 Hermes 插件 — 带有完整可运行示例的逐步指南。

快速概览

将一个目录放入 ~/.hermes/plugins/，包含一个 plugin.yaml 和 Python 代码：

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

启动 Hermes —— 你的工具将与内置工具一同出现。模型可立即调用它们。

最小可行示例

以下是一个完整的插件示例，它添加了一个 hello_world 工具，并通过钩子记录每次工具调用。

~/.hermes/plugins/hello-world/plugin.yaml

name: hello-world
version: "1.0"
description: A minimal example plugin

~/.hermes/plugins/hello-world/__init__.py

"""Minimal Hermes plugin — registers a tool and a hook."""


def register(ctx):
    # --- Tool: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params):
        name = params.get("name", "World")
        return f"Hello, {name}! 👋  (from the hello-world plugin)"

    ctx.register_tool("hello_world", schema, handle_hello)

    # --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

将这两个文件放入 ~/.hermes/plugins/hello-world/，重启 Hermes 后，模型即可立即调用 hello_world。该钩子会在每次工具调用后打印一条日志。

项目本地的插件位于 ./.hermes/plugins/，默认情况下处于禁用状态。仅在信任的仓库中，通过设置 HERMES_ENABLE_PROJECT_PLUGINS=true 再启动 Hermes 时启用。

插件能做什么

能力	实现方式
添加工具	ctx.register_tool(name, schema, handler)
添加钩子	ctx.register_hook("post_tool_call", callback)
添加 CLI 命令	ctx.register_cli_command(name, help, setup_fn, handler_fn) —— 添加 hermes <plugin> <subcommand>
注入消息	ctx.inject_message(content, role="user") —— 参见 注入消息
发布数据文件	Path(__file__).parent / "data" / "file.yaml"
打包技能	在加载时将 skill.md 复制到 ~/.hermes/skills/
根据环境变量控制	requires_env: [API_KEY] 在 plugin.yaml 中 —— 在 hermes plugins install 期间提示输入
通过 pip 分发	[project.entry-points."hermes_agent.plugins"]

插件发现机制

来源	路径	使用场景
用户	~/.hermes/plugins/	个人插件
项目	.hermes/plugins/	项目专用插件（需设置 HERMES_ENABLE_PROJECT_PLUGINS=true）
pip	hermes_agent.plugins entry_points	分发包

可用的钩子

插件可以注册以下生命周期事件的回调函数。详见 事件钩子页面 获取完整细节、回调签名和示例。

钩子	触发时机
pre_tool_call	任何工具执行前
post_tool_call	任何工具返回后
pre_llm_call	每轮对话开始前一次，可返回 {"context": "..."} 以 向用户消息注入上下文
post_llm_call	每轮对话结束时（仅成功回合）
on_session_start	新会话创建时（仅第一轮）
on_session_end	每次 run_conversation 调用结束后 + CLI 退出处理器

插件类型

Hermes 有三种类型的插件：

类型	功能	选择方式	位置
通用插件	添加工具、钩子、CLI 命令	多选（启用/禁用）	~/.hermes/plugins/
内存提供者	替换或增强内置内存	单选（仅一个激活）	plugins/memory/
上下文引擎	替换内置上下文压缩器	单选（仅一个激活）	plugins/context_engine/

内存提供者和上下文引擎是 提供者插件 —— 每种类型在同一时间只能有一个激活。通用插件可以任意组合启用。

管理插件

hermes plugins                  # unified interactive UI
hermes plugins list             # table view with enabled/disabled status
hermes plugins install user/repo  # install from Git
hermes plugins update my-plugin   # pull latest
hermes plugins remove my-plugin   # uninstall
hermes plugins enable my-plugin   # re-enable a disabled plugin
hermes plugins disable my-plugin  # disable without removing

交互式 UI

运行 hermes plugins 且无参数时，将打开一个综合交互界面：

Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

  General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

• 通用插件部分 —— 复选框，按空格键切换
• 提供者插件部分 —— 显示当前选择。按回车键进入单选选择器，从中选择一个活跃的提供者

提供者插件的选择会被保存至 config.yaml：

memory:
  provider: "honcho"      # empty string = built-in only

context:
  engine: "compressor"    # default built-in compressor

禁用通用插件

被禁用的插件仍保留在安装状态，但在加载时会被跳过。禁用列表存储于 config.yaml 的 plugins.disabled 下：

plugins:
  disabled:
    - my-noisy-plugin

在运行会话中，/plugins 可显示当前已加载的插件。

注入消息

插件可通过 ctx.inject_message() 将消息注入到当前对话中：

ctx.inject_message("New data arrived from the webhook", role="user")

签名： ctx.inject_message(content: str, role: str = "user") -> bool

工作原理如下：

• 如果代理处于 空闲状态（等待用户输入），该消息将被排队作为下一条输入，并开启新回合。
• 如果代理处于 中途回合（正在运行），该消息将中断当前操作 —— 相当于用户输入新消息并按下 Enter。
• 对非 "user" 角色的消息，内容前会加上 [role]（例如 [system] ...）。
• 若消息成功排队，返回 True；若无 CLI 引用可用（如网关模式），则返回 False。

这使得远程控制查看器、消息桥接器或 Webhook 接收器等插件能够从外部来源向对话注入消息。

note

inject_message 仅在 CLI 模式下可用。在网关模式下，没有 CLI 引用，该方法返回 False。

参见 完整指南 了解处理器契约、Schema 格式、钩子行为、错误处理及常见错误。