插件

Hermes 提供了插件系統，可在不修改核心代碼的情況下添加自定義工具、鉤子和集成。

→ 構建一個 Hermes 插件 — 帶有完整可運行示例的逐步指南。

快速概覽

將一個目錄放入 ~/.hermes/plugins/，幷包含一個 plugin.yaml 文件和 Python 代碼：

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # 顯現
├── __init__.py      # register() — 將模式連接到處理程序
├── schemas.py       # tool 架構（LLM 看到的內容）
└── tools.py         # tool 處理程序（調用時運行的內容）

啟動 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):
    # --- 工具：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)

    # --- 掛鉤：記錄每個 tool 調用 ---
    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 前設置 HERMES_ENABLE_PROJECT_PLUGINS=true 來啟用它們。

插件可實現的功能

功能	實現方式
添加工具	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                  # 統一交互界面
hermes plugins list             # 具有啟用/disabled狀態的表視圖
hermes plugins install user/repo  # 從 Git 安裝
hermes plugins update my-plugin   # 拉最新的
hermes plugins remove my-plugin   # 卸載
hermes plugins enable my-plugin   # 重新啟用已禁用的插件
hermes plugins disable my-plugin  # 禁用而不刪除

交互式界面

運行 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"      # 空字符串 = 僅內置

context:
  engine: "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

工作原理：

• 如果 Agent 處於 空閒 狀態（等待用戶輸入），則消息將被排隊為下一個輸入，並啟動一個新回合。
• 如果 Agent 處於 回合中（正在運行），則消息會中斷當前操作——與用戶輸入新消息並按 Enter 鍵的效果相同。
• 對於非 "user" 角色的消息，內容前會加上 [role] 前綴（例如 [system] ...）。
• 如果消息成功排隊，返回 True；如果無法獲取 CLI 引用（例如在網關模式下），則返回 False。

這使得遠程控制查看器、消息橋接器或 Webhook 接收器等插件能夠從外部源向對話中注入消息。

備註

inject_message 僅在 CLI 模式下可用。在網關模式下，沒有 CLI 引用，該方法將返回 False。

有關處理器合約、模式格式、鉤子行為、錯誤處理和常見錯誤的完整指南，請參閱 完整指南。