構建一個 Hermes 插件

本指南將帶你從零開始構建一個完整的 Hermes 插件。完成之後，你將擁有一個功能齊全的插件，包含多個工具、生命週期鉤子、已打包的數據文件以及一個內置技能文件——涵蓋了插件系統支持的所有功能。

你將構建的內容

一個 計算器 插件，包含兩個工具：

• calculate —— 計算數學表達式（2**16，sqrt(144)，pi * 5**2）
• unit_convert —— 單位轉換（100 F → 37.78 C，5 km → 3.11 mi）

此外還包括一個在每次工具調用時記錄日誌的鉤子，以及一個打包的技能文件。

第一步：創建插件目錄

mkdir -p ~/.hermes/plugins/calculator
cd ~/.hermes/plugins/calculator

第二步：編寫清單文件

創建 plugin.yaml：

name: calculator
version: 1.0.0
description: Math calculator — evaluate expressions and convert units
provides_tools:
  - calculate
  - unit_convert
provides_hooks:
  - post_tool_call

這告訴 Hermes：“我是一個名為 calculator 的插件，我提供工具和鉤子。”provides_tools 和 provides_hooks 字段列出了插件註冊的內容。

可選字段（你可以添加）：

author: Your Name
requires_env:          # 環境變量的門加載；安裝時提示
  - SOME_API_KEY       # 簡單格式 - 如果缺少插件則禁用
  - name: OTHER_KEY    # rich 格式 — 安裝期間顯示說明 /url
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true

第三步：編寫工具 Schema

創建 schemas.py —— 這是 LLM 用來決定何時調用你的工具的依據：

"""Tool schemas — what the LLM sees."""

CALCULATE = {
    "name": "calculate",
    "description": (
        "Evaluate a mathematical expression and return the result. "
        "Supports arithmetic (+, -, *, /, **), functions (sqrt, sin, cos, "
        "log, abs, round, floor, ceil), and constants (pi, e). "
        "Use this for any math the user asks about."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Math expression to evaluate (e.g., '2**10', 'sqrt(144)')",
            },
        },
        "required": ["expression"],
    },
}

UNIT_CONVERT = {
    "name": "unit_convert",
    "description": (
        "Convert a value between units. Supports length (m, km, mi, ft, in), "
        "weight (kg, lb, oz, g), temperature (C, F, K), data (B, KB, MB, GB, TB), "
        "and time (s, min, hr, day)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "value": {
                "type": "number",
                "description": "The numeric value to convert",
            },
            "from_unit": {
                "type": "string",
                "description": "Source unit (e.g., 'km', 'lb', 'F', 'GB')",
            },
            "to_unit": {
                "type": "string",
                "description": "Target unit (e.g., 'mi', 'kg', 'C', 'MB')",
            },
        },
        "required": ["value", "from_unit", "to_unit"],
    },
}

Schema 為何重要：
description 字段是 LLM 決定是否使用你的工具的關鍵。請明確描述其功能以及使用場景。parameters 定義了 LLM 傳遞給工具的參數。

第四步：編寫工具處理器

創建 tools.py —— 這是當 LLM 調用工具時實際執行的代碼：

"""Tool handlers — the code that runs when the LLM calls each tool."""

import json
import math

# 用於表達式求值的安全全局變量 — 無 file/network 訪問權限
_SAFE_MATH = {
    "abs": abs, "round": round, "min": min, "max": max,
    "pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos,
    "tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10,
    "floor": math.floor, "ceil": math.ceil,
    "pi": math.pi, "e": math.e,
    "factorial": math.factorial,
}


def calculate(args: dict, **kwargs) -> str:
    """Evaluate a math expression safely.

    Rules for handlers:
    1. Receive args (dict) — the parameters the LLM passed
    2. Do the work
    3. Return a JSON string — ALWAYS, even on error
    4. Accept **kwargs for forward compatibility
    """
    expression = args.get("expression", "").strip()
    if not expression:
        return json.dumps({"error": "No expression provided"})

    try:
        result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
        return json.dumps({"expression": expression, "result": result})
    except ZeroDivisionError:
        return json.dumps({"expression": expression, "error": "Division by zero"})
    except Exception as e:
        return json.dumps({"expression": expression, "error": f"Invalid: {e}"})


# 換算表 — 值採用基本單位
_LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01}
_WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495}
_DATA = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
_TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400}


def _convert_temp(value, from_u, to_u):
    # 標準化為攝氏度
    c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value)
    # 轉換為目標
    return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c)


def unit_convert(args: dict, **kwargs) -> str:
    """Convert between units."""
    value = args.get("value")
    from_unit = args.get("from_unit", "").strip()
    to_unit = args.get("to_unit", "").strip()

    if value is None or not from_unit or not to_unit:
        return json.dumps({"error": "Need value, from_unit, and to_unit"})

    try:
        # 溫度
        if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}:
            result = _convert_temp(float(value), from_unit.upper(), to_unit.upper())
            return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4),
                             "output": f"{round(result, 4)} {to_unit}"})

        # 基於比率的轉換
        for table in (_LENGTH, _WEIGHT, _DATA, _TIME):
            lc = {k.lower(): v for k, v in table.items()}
            if from_unit.lower() in lc and to_unit.lower() in lc:
                result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()]
                return json.dumps({"input": f"{value} {from_unit}",
                                 "result": round(result, 6),
                                 "output": f"{round(result, 6)} {to_unit}"})

        return json.dumps({"error": f"Cannot convert {from_unit} → {to_unit}"})
    except Exception as e:
        return json.dumps({"error": f"Conversion failed: {e}"})

處理器的關鍵規則：

1. 簽名： def my_handler(args: dict, **kwargs) -> str
2. 返回值： 始終返回 JSON 字符串。無論成功或失敗都如此。
3. 絕不拋出異常： 捕獲所有異常，返回錯誤的 JSON 而非拋出。
4. 接受 **kwargs： Hermes 未來可能會傳遞額外上下文。

第五步：編寫註冊邏輯

創建 __init__.py —— 這是將 Schema 與處理器連接起來的文件：

"""Calculator plugin — registration."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

# 通過鉤子跟蹤 tool 使用情況
_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    """Hook: runs after every tool call (not just ours)."""
    _call_log.append({"tool": tool_name, "session": task_id})
    if len(_call_log) > 100:
        _call_log.pop(0)
    logger.debug("Tool called: %s (session %s)", tool_name, task_id)


def register(ctx):
    """Wire schemas to handlers and register hooks."""
    ctx.register_tool(name="calculate",    toolset="calculator",
                      schema=schemas.CALCULATE,    handler=tools.calculate)
    ctx.register_tool(name="unit_convert", toolset="calculator",
                      schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)

    # 此鉤子會針對 ALL tool 調用觸發，而不僅僅是我們的調用
    ctx.register_hook("post_tool_call", _on_post_tool_call)

register() 的作用：

• 在啟動時僅調用一次
• ctx.register_tool() 將你的工具註冊到系統中——模型會立即看到它
• ctx.register_hook() 訂閱生命週期事件
• ctx.register_cli_command() 註冊一個 CLI 子命令（例如 hermes my-plugin <subcommand>）
• 如果此函數崩潰，插件將被禁用，但 Hermes 仍能正常運行

第六步：測試插件

啟動 Hermes：

hermes

你應該在啟動橫幅的工具列表中看到 calculator: calculate, unit_convert。

嘗試以下提示：

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/calculator/
├── plugin.yaml      # "I'm calculator, I provide tools and hooks"
├── __init__.py      # 連線：模式 → 處理程序、註冊掛鉤
├── schemas.py       # LLM 讀取的內容（描述 + 參數規格）
└── tools.py         # 運行什麼（計算、unit_convert 函數）

四個文件，職責清晰分離：

• 清單文件：聲明插件的身份
• Schema 文件：向 LLM 描述工具
• 處理器文件：實現實際邏輯
• 註冊文件：連接所有組件

插件還能做什麼？

打包數據文件

將任意文件放入插件目錄，並在導入時讀取：

# 在 tools.py 或 __init__.py 中
from pathlib import Path

_PLUGIN_DIR = Path(__file__).parent
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"

with open(_DATA_FILE) as f:
    _DATA = yaml.safe_load(f)

打包一個技能文件

包含一個 skill.md 文件，並在註冊時安裝：

import shutil
from pathlib import Path

def _install_skill():
    """Copy our skill to ~/.hermes/skills/ on first load."""
    try:
        from hermes_cli.config import get_hermes_home
        dest = get_hermes_home() / "skills" / "my-plugin" / "SKILL.md"
    except Exception:
        dest = Path.home() / ".hermes" / "skills" / "my-plugin" / "SKILL.md"

    if dest.exists():
        return  # 不要覆蓋用戶編輯

    source = Path(__file__).parent / "skill.md"
    if source.exists():
        dest.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source, dest)

def register(ctx):
    ctx.register_tool(...)
    _install_skill()

基於環境變量啟用/禁用

如果插件需要 API 密鑰：

# plugin.yaml — 簡單格式（向後兼容）
requires_env:
  - WEATHER_API_KEY

如果未設置 WEATHER_API_KEY，插件將被禁用，並顯示清晰提示。不會崩潰，也不會導致 Agent 出錯——只會顯示“Plugin weather disabled (missing: WEATHER_API_KEY)”。

當用戶運行 hermes plugins install 時，系統會 交互式提示 輸入任何缺失的 requires_env 變量。值會自動保存到 .env 文件中。

為了獲得更好的安裝體驗，可以使用帶描述和註冊鏈接的豐富格式：

# plugin.yaml — rich 格式
requires_env:
  - name: WEATHER_API_KEY
    description: "API key for OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

字段	是否必需	描述
name	是	環境變量名稱
description	否	安裝提示時向用戶顯示
url	否	獲取憑證的地址
secret	否	若為 true，輸入將隱藏（如密碼字段）

兩種格式可在同一列表中混合使用。已設置的變量會靜默跳過。

條件性工具可用性

對於依賴可選庫的工具：

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = Tool 對 模型 隱藏
)

註冊多個鉤子

def register(ctx):
    ctx.register_hook("pre_tool_call", before_any_tool)
    ctx.register_hook("post_tool_call", after_any_tool)
    ctx.register_hook("pre_llm_call", inject_memory)
    ctx.register_hook("on_session_start", on_new_session)
    ctx.register_hook("on_session_end", on_session_end)

鉤子參考

每個鉤子的完整文檔請參見 事件鉤子參考 —— 包括回調簽名、參數表、觸發時機以及示例。以下是摘要：

鉤子	觸發時機	回調簽名	返回值
pre_tool_call	任何工具執行前	tool_name: str, args: dict, task_id: str	忽略
post_tool_call	任何工具返回後	tool_name: str, args: dict, result: str, task_id: str	忽略
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	忽略
pre_api_request	每次向 LLM 提供商發起 HTTP 請求前	method: str, url: str, headers: dict, body: dict	忽略
post_api_request	每次從 LLM 提供商收到 HTTP 響應後	method: str, url: str, status_code: int, response: dict	忽略

大多數鉤子都是“觸發即丟棄”的觀察者——它們的返回值被忽略。例外是 pre_llm_call，它可以向對話中注入上下文。

所有回調都應接受 **kwargs 以保證向前兼容性。如果某個鉤子回調崩潰，它會被記錄並跳過，其他鉤子和 Agent 將繼續正常運行。

pre_llm_call 上下文注入

這是唯一一個返回值有意義的鉤子。當 pre_llm_call 回調返回一個包含 "context" 鍵的字典（或一個非空字符串）時，Hermes 會將該文本注入到當前輪次的用戶消息中。這是實現記憶插件、RAG 集成、安全護欄以及任何需要向模型提供額外上下文的插件的機制。

返回格式

# 帶 context 鍵的字典
return {"context": "Recalled memories:\n- User prefers dark mode\n- Last project: hermes-agent"}

# 純字符串（相當於上面的字典形式）
return "Recalled memories:\n- User prefers dark mode"

# 返回 None 或不返回 → 不注入（僅限觀察者）
return None

任何非 None、非空的返回值，若包含 "context" 鍵（或為非空字符串），都會被收集並附加到當前輪次的用戶消息中。

注入機制說明

注入的上下文是附加到用戶消息，而非系統提示。這是有意為之的設計選擇：

• 提示緩存保留 —— 系統提示在各輪次中保持一致。Anthropic 和 OpenRouter 會緩存系統提示前綴，保持其穩定可節省多輪對話中 75% 以上的輸入 token。如果插件修改了系統提示，每輪都會導致緩存未命中。
• 瞬時性 —— 注入僅在 API 調用時發生。對話歷史中的原始用戶消息永遠不會被修改，也不會持久化到會話數據庫。
• 系統提示屬於 Hermes 的領域 —— 系統提示包含模型特定的指導、工具強制規則、人格指令和緩存的技能內容。插件應與用戶輸入一同提供上下文，而非通過修改 Agent 的核心指令。

示例：記憶召回插件

"""Memory plugin — recalls relevant context from a vector store."""

import httpx

MEMORY_API = "https://your-memory-api.example.com"

def recall_context(session_id, user_message, is_first_turn, **kwargs):
    """Called before each LLM turn. Returns recalled memories."""
    try:
        resp = httpx.post(f"{MEMORY_API}/recall", json={
            "session_id": session_id,
            "query": user_message,
        }, timeout=3)
        memories = resp.json().get("results", [])
        if not memories:
            return None  # 沒有什麼可注射的

        text = "Recalled context from previous sessions:\n"
        text += "\n".join(f"- {m['text']}" for m in memories)
        return {"context": text}
    except Exception:
        return None  # 默默地失敗，不要破壞agent

def register(ctx):
    ctx.register_hook("pre_llm_call", recall_context)

示例：安全護欄插件

"""Guardrails plugin — enforces content policies."""

POLICY = """You MUST follow these content policies for this session:
- Never generate code that accesses the filesystem outside the working directory
- Always warn before executing destructive operations
- Refuse requests involving personal data extraction"""

def inject_guardrails(**kwargs):
    """Injects policy text into every turn."""
    return {"context": POLICY}

def register(ctx):
    ctx.register_hook("pre_llm_call", inject_guardrails)

示例：僅觀察型鉤子（無注入）

"""Analytics plugin — tracks turn metadata without injecting context."""

import logging
logger = logging.getLogger(__name__)

def log_turn(session_id, user_message, model, is_first_turn, **kwargs):
    """Fires before each LLM call. Returns None — no context injected."""
    logger.info("Turn: session=%s model=%s first=%s msg_len=%d",
                session_id, model, is_first_turn, len(user_message or ""))
    # 無返回→無注入

def register(ctx):
    ctx.register_hook("pre_llm_call", log_turn)

多個插件同時返回上下文

當多個插件從 pre_llm_call 返回上下文時，它們的輸出將通過雙換行符連接，並一同附加到用戶消息中。順序遵循插件發現順序（按插件目錄名稱的字母順序）。

註冊 CLI 命令

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

def _my_command(args):
    """Handler for hermes my-plugin <subcommand>."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("All good!")
    elif sub == "config":
        print("Current config: ...")
    else:
        print("Usage: hermes my-plugin <status|config>")

def _setup_argparse(subparser):
    """Build the argparse tree for hermes my-plugin."""
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show plugin status")
    subs.add_parser("config", help="Show plugin config")
    subparser.set_defaults(func=_my_command)

def register(ctx):
    ctx.register_tool(...)
    ctx.register_cli_command(
        name="my-plugin",
        help="Manage my plugin",
        setup_fn=_setup_argparse,
        handler_fn=_my_command,
    )

註冊後，用戶可以運行 hermes my-plugin status、hermes my-plugin config 等命令。

記憶提供者插件採用基於約定的方式：在插件的 cli.py 文件中添加 register_cli(subparser) 函數。記憶插件發現系統會自動找到它——無需調用 ctx.register_cli_command()。詳情請參見 記憶提供者插件指南。

激活提供者控制：記憶插件的 CLI 命令僅在配置中設置為活動 memory.provider 時才會顯示。如果用戶未配置你的提供者，你的 CLI 命令不會出現在幫助輸出中，避免干擾。

提示

本指南涵蓋通用插件（工具、鉤子、CLI 命令）。對於特定類型的插件，請參閱：

• 記憶提供者插件 —— 跨會話知識後端
• 上下文引擎插件 —— 替代上下文管理策略

通過 pip 發佈

對於公開共享插件，請在您的 Python 包中添加入口點：

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

pip install hermes-plugin-calculator
# 下次 hermes 啟動時自動發現插件

常見錯誤

處理器未返回 JSON 字符串：

# 錯誤——返回一個字典
def handler(args, **kwargs):
    return {"result": 42}

# 右 — 返回 JSON 字符串
def handler(args, **kwargs):
    return json.dumps({"result": 42})

處理器簽名中缺少 **kwargs：

# 錯誤 — 如果 Hermes 通過額外的 context 將中斷
def handler(args):
    ...

# 正確的
def handler(args, **kwargs):
    ...

處理器拋出異常：

# 錯誤 — 異常傳播，tool 調用失敗
def handler(args, **kwargs):
    result = 1 / int(args["value"])  # 零除法錯誤！
    return json.dumps({"result": result})

# 右 — 捕獲並返回錯誤 JSON
def handler(args, **kwargs):
    try:
        result = 1 / int(args.get("value", 0))
        return json.dumps({"result": result})
    except Exception as e:
        return json.dumps({"error": str(e)})

模式描述過於模糊：

# 不好——model 不知道什麼時候使用它
"description": "Does stuff"

# 好 — model 確切地知道何時以及如何
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."