<!-- Source: https://hermesbible.com/docs/user-guide/features/plugins -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/plugins

Hermes 擁有外掛系統，可以用來新增自訂工具、鉤子和整合功能，而無需修改核心程式碼。

如果你想為自己、團隊或特定專案建立自訂工具， 這通常是最合適的路徑。開發者指南中的 新增工具 頁面是針對位於 tools/ 和 toolsets.py 中的 Hermes 核心內建工具。

→ 建立 Hermes 外掛 — 附有完整可用範例的逐步指南。

快速概覽

將目錄放入 ~/.hermes/plugins/，包含 plugin.yaml 和 Python 程式碼：

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # 設定檔
├── __init__.py      # register() — 將 schema 繫結到處理函式
├── schemas.py       # 工具 schema（LLM 所看到的）
└── tools.py         # 工具處理函式（呼叫時執行程式碼）

啟動 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."""

import json

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, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Return a friendly greeting for the given name.",
    )

    # --- 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 之前設定 HERMES_ENABLE_PROJECT_PLUGINS=true。

外掛可以做什麼

以下每個 ctx.* API 都可以在外掛的 register(ctx) 函式中使用。

外掛發現

後面的來源會在名稱衝突時覆蓋前面的來源，因此與內建外掛同名的使用者外掛會替換它。

外掛子分類

在每個來源中，Hermes 還會識別子分類目錄，將外掛路由到專門的發現系統：

位於 ~/.hermes/plugins/model-providers/<name>/ 和 ~/.hermes/plugins/memory/<name>/ 的使用者外掛會覆蓋同名的內建外掛 — 在 register_provider() / register_memory_provider() 中採用後寫入者勝出原則。放入目錄即可替換內建版本，無需修改儲存庫。

外掛是選擇性加入的（少數例外）

通用外掛和使用者安裝的後端預設是停用的 — 發現系統會找到它們（因此它們會出現在 hermes plugins 和 /plugins 中），但在你將外掛名稱加入 ~/.hermes/config.yaml 的 plugins.enabled 之前，帶有鉤子或工具的外掛不會載入。這可以防止未經你明確同意的第三方程式碼執行。

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # 可選的拒絕清單 — 若名稱同時出現在兩者中，則以此為準
    - noisy-plugin

三種切換狀態的方式：

hermes plugins                    # 互動式切換（空白鍵勾選/取消勾選）
hermes plugins enable <name>      # 加入允許清單
hermes plugins disable <name>     # 從允許清單移除 + 加入停用清單

執行 hermes plugins install owner/repo 後，會提示 Enable 'name' now? [y/N] — 預設為否。若要在腳本安裝時跳過提示，可使用 --enable 或 --no-enable。

允許清單不涵蓋的範圍

有幾個類別的外掛會繞過 plugins.enabled — 它們是 Hermes 內建功能的一部分，若預設被閘限會導致基本功能無法運作：

簡而言之：內建的「始終可用」基礎設施會自動載入；第三方通用外掛則是選擇性加入的。plugins.enabled 允許清單是專門用來管控使用者放入 ~/.hermes/plugins/ 中任意程式碼的閘限機制。

現有使用者的遷移

當你升級到具有選擇性加入外掛功能的 Hermes 版本（設定結構 v21+）時，任何已安裝在 ~/.hermes/plugins/ 下且尚未出現在 plugins.disabled 中的使用者外掛，都會自動被保留至 plugins.enabled。你現有的設定會繼續運作。內建的獨立外掛則不會被保留 — 即使是現有使用者也必須明確選擇加入。（內建的平台/後端外掛從不需要保留處理，因為它們從未被閘限。）

可用的鉤子

外掛可以為這些生命週期事件註冊回呼函式。詳情、回呼函式簽章和範例，請參閱**事件鉤子頁面**。

外掛類型

Hermes 有四種外掛：

記憶體供應商和上下文引擎是供應商外掛 — 每種類型同時只能有一個啟用。模型供應商也是外掛，但可以同時載入多個；使用者一次只能透過 --provider 或 config.yaml 選擇一個。通用外掛可以任意組合啟用。

可插拔介面 — 各功能的對應位置

上表顯示了四種外掛類別，但在「通用外掛」中，PluginContext 暴露了數個不同的擴展點 — Hermes 也接受 Python 外掛系統之外的擴展（設定驅動的後端、shell 鉤子命令、外部伺服器等）。使用此表格找到你想建立功能的正確文件：

注意

並非所有功能都是 Python 外掛。有些擴展表面故意使用設定驅動的 shell 命令（TTS、STT、shell 鉤子），讓你已有的任何 CLI 無需撰寫 Python 就能成為外掛。其他則是外部伺服器（MCP），代理會連線並自動註冊其工具。還有一些是直接放入的目錄（閘道器鉤子），有其專屬的設定檔格式。根據你的整合風格選擇正確的表面；上表中的每個開發指南都涵蓋了佔位符、發現機制和範例。

NixOS 宣告式外掛

在 NixOS 上，外掛可以透過模組選項以宣告式方式安裝 — 無需使用 hermes plugins install。詳情請參閱 Nix 設定指南。

services.hermes-agent = {
  # 目錄外掛（包含 plugin.yaml 的原始碼樹）
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # 入口點外掛（pip 套件）
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
  # 在設定中啟用
  settings.plugins.enabled = [ "my-plugin" ];
};

宣告式外掛會以 nix-managed- 前綴建立符號連結 — 它們與手動安裝的外掛共存，並在從 Nix 設定中移除時自動清理。

管理外掛

hermes plugins                               # 統一互動式介面
hermes plugins list                          # 表格：已啟用 / 已停用 / 未啟用
hermes plugins install user/repo             # 從 Git 安裝，然後提示 Enable? [y/N]
hermes plugins install user/repo --enable    # 安裝並啟用（不提示）
hermes plugins install user/repo --no-enable # 安裝但保持停用（不提示）
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
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

• 通用外掛區塊 — 核取方塊，使用空白鍵切換。已勾選 = 在 plugins.enabled 中，未勾選 = 在 plugins.disabled 中（明確關閉）。
• 供應商外掛區塊 — 顯示目前的選擇。按下 ENTER 進入單選介面，選擇一個啟用的供應商。
• 內建外掛會出現在相同清單中，帶有 [bundled] 標籤。

供應商外掛的選擇會儲存到 config.yaml：

memory:
  provider: "honcho"      # 空字串 = 僅使用內建版本

context:
  engine: "compressor"    # 預設的內建壓縮器

已啟用 vs. 已停用 vs. 未啟用

外掛佔據三種狀態之一：

新安裝或內建外掛的預設狀態是 not enabled。hermes plugins list 會顯示這三種不同的狀態，讓你分辨哪些是被明確關閉的，哪些只是等待被啟用。

在執行中的工作階段中，/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 接收器等外掛，可以從外部來源將訊息餵入對話中。

注意

inject_message 僅在 CLI 模式下可用。在閘道器模式下，沒有 CLI 參考，方法會回傳 False。

詳情請參閱**完整指南**，包含處理函式合約、schema 格式、鉤子行為、錯誤處理和常見錯誤。

---

---

內建外掛