构建一个 Hermes 插件

本指南会带你从零构建一个完整的 Hermes 插件。完成后，你将拥有一个真正可用的插件，里面包含多个工具、生命周期 hooks、随插件发布的数据文件，以及一个打包好的技能，基本覆盖插件系统支持的主要能力。

你要构建什么

一个 calculator 插件，包含两个工具：

• calculate：计算数学表达式（2**16、sqrt(144)、pi * 5**2）
• unit_convert：单位转换（100 F → 37.78 C、5 km → 3.11 mi）

此外还会加上一个 hook，用来记录每次工具调用，以及一个打包好的技能文件。

第 1 步：创建插件目录

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

第 2 步：编写 manifest

创建 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 的插件，我会提供工具和 hooks。” 其中 provides_tools 和 provides_hooks 列出了该插件将注册的内容。

你还可以加入这些可选字段：

author: Your Name
requires_env:
  - SOME_API_KEY
  - name: OTHER_KEY
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true

第 3 步：编写工具 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 应该传入哪些参数。

第 4 步：编写工具 handler

创建 tools.py。这里才是真正执行工具逻辑的代码：

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

import json
import math

# Safe globals for expression evaluation — no file/network access
_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:
    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:
    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}"})

Handler 的核心规则：

1. 签名：def my_handler(args: dict, **kwargs) -> str
2. 返回值：始终返回 JSON 字符串，成功和失败都一样
3. 不要向外抛异常：捕获全部异常并返回错误 JSON
4. 接受 **kwargs：为未来额外上下文参数保留兼容性

第 5 步：编写注册逻辑

创建 __init__.py，把 schema 和 handler 接起来：

"""Calculator plugin — registration."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    _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):
    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)

    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 本身仍会继续运行

第 6 步：测试

启动 Hermes：

hermes

你应该会在 banner 的工具列表里看到 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
├── __init__.py
├── schemas.py
└── tools.py

四个文件，各司其职：

• Manifest：声明插件是什么
• Schemas：告诉 LLM 工具长什么样
• Handlers：实现实际逻辑
• Registration：把它们连接起来

插件还能做什么？

携带数据文件

你可以把任意文件放进插件目录，并在导入时读取：

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)

打包技能

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

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

from pathlib import Path

def register(ctx):
    skills_dir = Path(__file__).parent / "skills"
    for child in sorted(skills_dir.iterdir()):
        skill_md = child / "SKILL.md"
        if child.is_dir() and skill_md.exists():
            ctx.register_skill(child.name, skill_md)

这样 agent 就能通过带命名空间的名称加载：

skill_view("my-plugin:my-workflow")
skill_view("my-workflow")

关键特性：

• 插件技能是只读的，不会进入 ~/.hermes/skills/，也不能通过 skill_manage 编辑
• 插件技能不会自动出现在 system prompt 的 <available_skills> 索引中，必须显式加载
• 裸技能名不受影响，命名空间可避免与内置技能冲突
• 当 agent 加载某个插件技能时，会自动附带同一插件内其他技能的 bundle 上下文横幅

旧模式

旧的 shutil.copy2 方式（把技能复制到 ~/.hermes/skills/）仍可工作，但容易与内置技能重名。新插件更推荐 ctx.register_skill()。

依赖环境变量时按条件启用

如果你的插件需要 API key：

requires_env:
  - WEATHER_API_KEY

如果未设置 WEATHER_API_KEY，插件不会崩溃，只会被禁用并给出清晰提示。

执行 hermes plugins install 时，安装器会交互式提示用户填写缺失的 requires_env 变量，并自动写入 .env。

如果想提供更好的安装体验，可以使用 richer 格式：

requires_env:
  - name: WEATHER_API_KEY
    description: "API key for OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

Field	Required	Description
name	Yes	环境变量名
description	No	安装时展示给用户的说明
url	No	获取凭证的网址
secret	No	若为 true，输入内容会被隐藏

条件化工具可用性

如果某个工具依赖可选库：

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),
)

注册多个 hook

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)

Hook 参考

每个 hook 的完整说明都在 Event Hooks reference 中，包括回调签名、参数表、触发时机和示例。这里给出概要：

Hook	Fires when	Callback signature	Returns
pre_tool_call	任意工具执行前	tool_name: str, args: dict, task_id: str	ignored
post_tool_call	任意工具返回后	tool_name: str, args: dict, result: str, task_id: str	ignored
pre_llm_call	每轮开始前、工具调用循环之前	session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str	context injection
post_llm_call	每轮成功结束后	session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str	ignored
on_session_start	新会话创建时	session_id: str, model: str, platform: str	ignored
on_session_end	每次 run_conversation 结束及 CLI 退出时	session_id: str, completed: bool, interrupted: bool, model: str, platform: str	ignored
on_session_finalize	CLI/网关销毁活动会话时	session_id: str | None, platform: str	ignored
on_session_reset	网关切换新 session key 时	session_id: str, platform: str	ignored

大多数 hook 都只是观察者，返回值会被忽略。唯一的例外是 pre_llm_call，它可以向对话注入上下文。

pre_llm_call 上下文注入

这是唯一一个返回值有意义的 hook。当 pre_llm_call 回调返回一个带 "context" 键的 dict（或直接返回字符串）时，Hermes 会把这段文本注入到当前轮的用户消息中。这正是记忆插件、RAG 集成、guardrails 等在不修改 system prompt 的前提下补充上下文的机制。

返回格式

return {"context": "Recalled memories:\n- User prefers dark mode"}
return "Recalled memories:\n- User prefers dark mode"
return None

为什么注入到用户消息而不是 system prompt

• 保护 prompt cache：system prompt 跨轮保持不变，可以命中 Anthropic/OpenRouter 的缓存，显著降低多轮成本
• 临时生效：只在当前 API 调用时注入，不会修改原始对话历史，也不会持久化到 session 数据库
• 职责边界清晰：system prompt 属于 Hermes 核心指令区，插件应把上下文附着在用户输入旁边，而不是篡改代理本体规则

注册 CLI 命令

插件也可以注册自己的 hermes <plugin> 子命令树：

def _my_command(args):
    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):
    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,
    )

注册 Slash Command

插件还可以注册会话内 slash command，这些命令既可在 CLI 中使用，也可在 Telegram、Discord 等网关平台中使用：

def _handle_status(raw_args: str) -> str:
    if raw_args.strip() == "help":
        return "Usage: /mystatus [help|check]"
    return "Plugin status: all systems nominal"

def register(ctx):
    ctx.register_command(
        "mystatus",
        handler=_handle_status,
        description="Show plugin status",
    )

Parameter	Type	Description
name	str	不带前导斜杠的命令名
handler	Callable[[str], str | None]	接收原始参数字符串，也可以是 async
description	str	展示在 /help、自动补全和 Telegram bot 菜单中

与 register_cli_command() 的区别：

	register_command()	register_cli_command()
调用方式	会话中的 /name	终端中的 hermes name
生效范围	CLI 会话、Telegram、Discord 等	仅终端
Handler 接收	原始参数字符串	argparse Namespace
适用场景	诊断、状态、快速操作	复杂子命令树、安装向导

提示

本指南覆盖的是通用插件（工具、hooks、slash commands、CLI commands）。对于更专门的插件类型，请参阅：

• Memory Provider Plugins
• Context Engine Plugins

通过 pip 分发

如果你想把插件作为 Python 包公开发布，可以在 pyproject.toml 中声明 entry point：

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

pip install hermes-plugin-calculator

常见错误

Handler 没返回 JSON 字符串：

# Wrong
def handler(args, **kwargs):
    return {"result": 42}

# Right
def handler(args, **kwargs):
    return json.dumps({"result": 42})

Handler 缺少 **kwargs：

# Wrong
def handler(args):
    ...

# Right
def handler(args, **kwargs):
    ...

Handler 抛异常：

# Wrong
def handler(args, **kwargs):
    result = 1 / int(args["value"])
    return json.dumps({"result": result})

# Right
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)})

Schema 描述过于模糊：

# Bad
"description": "Does stuff"

# Good
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."