构建 Hermes 插件

本指南将引导你从零开始构建一个完整的 Hermes 插件。完成后，你将拥有一个包含多个工具、生命周期钩子、内置数据文件和一个打包技能的可运行插件——涵盖插件系统支持的所有功能。

不确定需要哪个指南？

Hermes 有多种不同的可插拔接口——有些使用 Python 的 register_* API，有些是配置驱动或即插即用目录。请先查看此映射表：

如果你想添加…	请阅读
自定义工具、钩子、斜杠命令、技能或 CLI 子命令	本指南（通用插件表面）
一个 LLM / 推理后端（新提供商）	模型提供商插件
一个 网关渠道（Discord/Telegram/IRC/Teams 等）	添加平台适配器
一个 记忆后端（Honcho/Mem0/Supermemory 等）	记忆提供商插件
一个 上下文压缩引擎	上下文引擎插件
一个 图像生成后端	图像生成提供商插件
一个 视频生成后端	视频生成提供商插件
一个 TTS 后端（任何 CLI——Piper、VoxCPM、Kokoro、语音克隆等）	TTS 自定义命令提供商——配置驱动，无需 Python
一个 STT 后端（自定义 whisper / ASR CLI）	语音消息转录——将 HERMES_LOCAL_STT_COMMAND 设置为 shell 模板
通过 MCP 使用外部工具（文件系统、GitHub、Linear 或任何 MCP 服务器）	MCP——在 config.yaml 中声明 mcp_servers.<name>
网关事件钩子（在启动、会话事件、命令时触发）	事件钩子——将 HOOK.yaml + handler.py 放入 ~/.hermes/hooks/<name>/
Shell 钩子（在事件发生时运行 shell 命令）	Shell 钩子——在 config.yaml 的 hooks: 下声明
额外技能来源（自定义 GitHub 仓库、私有技能索引）	技能——hermes skills tap add <repo> · 发布一个 tap
一个首要的 核心 推理提供商（非插件）	添加提供商

查看完整的可插拔接口表，获取包括配置驱动（TTS、STT、MCP、shell 钩子）和即插即用目录（网关钩子）样式在内的所有扩展表面的统一视图。

你将构建什么

一个包含两个工具的 计算器 插件：

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

此外，还有一个记录每次工具调用的钩子，以及一个打包的技能文件。

第 1 步：创建插件目录

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

第 2 步：编写清单文件

创建 plugin.yaml：

name: calculator
version: 1.0.0
description: 数学计算器 —— 求解表达式与单位换算
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    # 详细格式 —— 安装时显示描述/网址
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true

第 3 步：编写工具模式定义

创建 schemas.py —— 这是 LLM 读取以决定何时调用你的工具的内容：

"""工具模式定义 —— LLM读取的内容。"""

CALCULATE = {
    "name": "calculate",
    "description": (
        "求解一个数学表达式并返回结果。"
        "支持算术运算 (+, -, *, /, **)、函数 (sqrt, sin, cos, "
        "log, abs, round, floor, ceil) 和常量 (pi, e)。"
        "用于处理用户提出的任何数学计算。"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "要求解的数学表达式（例如 '2**10', 'sqrt(144)'）",
            },
        },
        "required": ["expression"],
    },
}

UNIT_CONVERT = {
    "name": "unit_convert",
    "description": (
        "在单位之间进行换算。支持长度 (m, km, mi, ft, in)、"
        "重量 (kg, lb, oz, g)、温度 (C, F, K)、数据量 (B, KB, MB, GB, TB) "
        "和时间 (s, min, hr, day)。"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "value": {
                "type": "number",
                "description": "要换算的数值",
            },
            "from_unit": {
                "type": "string",
                "description": "源单位（例如 'km', 'lb', 'F', 'GB'）",
            },
            "to_unit": {
                "type": "string",
                "description": "目标单位（例如 'mi', 'kg', 'C', 'MB'）",
            },
        },
        "required": ["value", "from_unit", "to_unit"],
    },
}

模式定义为何重要： description 字段是 LLM 决定何时使用你的工具的方式。请具体说明工具的功能和适用场景。parameters 定义了 LLM 需要传递的参数。

第 4 步：编写工具处理程序

创建 tools.py —— 这是 LLM 调用你的工具时实际执行的代码：

"""工具处理程序 —— LLM调用每个工具时运行的代码。"""

import json
import math

# 用于表达式求值的安全全局变量 —— 无文件/网络访问
_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:
    """安全地求解一个数学表达式。

    处理程序规则：
    1. 接收参数 args (dict) —— LLM传递的参数
    2. 执行工作
    3. 返回 JSON 字符串 —— 即使出错也必须如此
    4. 接受 **kwargs 以实现前向兼容性
    """
    expression = args.get("expression", "").strip()
    if not expression:
        return json.dumps({"error": "未提供表达式"})

    try:
        result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
        return json.dumps({"expression": expression, "result": result})
    except ZeroDivisionError:
        return json.dumps({"expression": expression, "error": "除以零"})
    except Exception as e:
        return json.dumps({"expression": expression, "error": f"无效: {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": "需要提供 value, from_unit 和 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"无法转换 {from_unit} → {to_unit}"})
    except Exception as e:
        return json.dumps({"error": f"转换失败: {e}"})

处理程序的关键规则：

1. 签名： def my_handler(args: dict, **kwargs) -> str
2. 返回： 始终返回 JSON 字符串。成功和错误情况均如此。
3. 切勿抛出异常： 捕获所有异常，改为返回错误 JSON。
4. 接受 **kwargs： Hermes 将来可能会传递额外的上下文信息。

第 5 步：编写注册代码

创建 __init__.py —— 这会将模式定义与处理程序连接起来：

"""计算器插件 —— 注册。"""

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("工具已调用: %s (会话 %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 <子命令>）
• ctx.register_command() 注册一个会话内的斜杠命令（例如在 CLI / 网关聊天中输入 /myplugin <参数>）—— 参见下方 注册斜杠命令
• ctx.dispatch_tool(name, arguments) —— 使用父智能体的上下文（审批、凭证、task_id）自动连接，调用任何其他工具（内置的或来自另一个插件的）。这对于需要调用 terminal、read_file 或任何其他工具（就像模型直接调用一样）的斜杠命令处理程序非常有用。
• 如果此函数崩溃，插件将被禁用，但 Hermes 会正常继续运行

dispatch_tool 示例 —— 一个运行工具的斜杠命令：

def handle_scan(ctx, argstr):
    """通过注册表调用终端工具来实现 /scan 命令。"""
    result = ctx.dispatch_tool("terminal", {"command": f"find . -name '{argstr}'"})
    return result  # 返回给调用者的聊天界面

def register(ctx):
    ctx.register_command("scan", handle_scan, help="查找匹配 glob 模式的文件")

分派的工具会经过正常的审批、脱敏和预算处理流程 —— 这是一个真正的工具调用，而不是绕过这些流程的快捷方式。

第 6 步：进行测试

启动 Hermes：

hermes

您应该能在横幅的工具列表中看到 calculator: calculate, unit_convert。

尝试以下提示：

2 的 16 次方是多少？
将 100 华氏度转换为摄氏度
2 乘以 π 的平方根是多少？
1.5 太字节是多少千兆字节？

检查插件状态：

/plugins

输出：

插件 (1):
  ✓ calculator v1.0.0 (2 个工具, 1 个钩子)

调试插件发现

如果您的插件未出现——或出现了但未加载——请设置 HERMES_PLUGINS_DEBUG=1 以在 stderr 上获取详细的发现日志：

HERMES_PLUGINS_DEBUG=1 hermes plugins list

对于每个插件源（捆绑、用户、项目、入口点），您将看到：

• 扫描了哪些目录，以及每个目录产生了多少个清单
• 每个清单：解析的键、名称、类型、来源、磁盘路径
• 跳过原因：通过配置禁用、未在配置中启用、独占插件、无 plugin.yaml、达到深度上限
• 加载时：正在导入的插件，以及 register(ctx) 注册内容的单行摘要（工具、钩子、斜杠命令、CLI 命令）
• 解析失败时：异常的完整回溯（YAML 扫描器错误等）
• register() 失败时：完整的回溯，指向 __init__.py 中引发错误的行

相同的日志总是以 WARNING 级别（仅失败）和 DEBUG 级别（所有内容，当设置环境变量时）写入 ~/.hermes/logs/agent.log。因此，如果您无法使用环境变量运行（例如在网关内部），请改为 tail 日志文件：

hermes logs --level WARNING | grep -i plugin

插件未出现的常见原因：

• 未在配置中启用 — 插件是选择加入的。运行 hermes plugins enable <name>（名称来自 plugins list 输出，对于嵌套布局可能是 <category>/<plugin>）。
• 目录布局错误 — 必须是 ~/.hermes/plugins/<plugin-name>/plugin.yaml（扁平结构）或 ~/.hermes/plugins/<category>/<plugin-name>/plugin.yaml（最多一级类别嵌套）。更深层次的嵌套将被忽略。
• 缺少 __init__.py — 插件目录需要同时包含 plugin.yaml 和包含 register(ctx) 函数的 __init__.py。
• kind 错误 — 网关适配器需要在其清单中设置 kind: platform。内存提供者被自动检测为 kind: exclusive，并通过 memory.provider 配置而不是 plugins.enabled 进行路由。

您插件的最终结构

~/.hermes/plugins/calculator/
├── plugin.yaml      # "我是 calculator，我提供工具和钩子"
├── __init__.py      # 连接：模式 → 处理程序，注册钩子
├── schemas.py       # LLM 读取的内容（描述 + 参数规范）
└── tools.py         # 运行的内容（calculate、unit_convert 函数）

四个文件，结构清晰：

• 清单声明插件是什么
• 模式为 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_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)

智能体现在可以通过带命名空间的名称加载你的技能：

skill_view("my-plugin:my-workflow")   # → 插件的版本
skill_view("my-workflow")              # → 内置版本（未改变）

关键属性：

• 插件技能是只读的 — 它们不会进入 ~/.hermes/skills/，且无法通过 skill_manage 编辑。
• 插件技能不会列在系统提示词的 <available_skills> 索引中 — 它们是显式按需加载的。
• 裸技能名称不受影响 — 命名空间防止了与内置技能的冲突。
• 当智能体加载插件技能时，会前置一个上下文横幅，列出同一插件中的兄弟技能。

旧模式

旧的 shutil.copy2 模式（将技能复制到 ~/.hermes/skills/）仍然有效，但会与内置技能产生名称冲突风险。新插件请优先使用 ctx.register_skill()。

基于环境变量守门

如果你的插件需要 API 密钥：

# plugin.yaml — 简单格式（向后兼容）
requires_env:
  - WEATHER_API_KEY

如果 WEATHER_API_KEY 未设置，插件将被禁用并给出清晰信息。不会导致崩溃或在智能体中产生错误 — 仅显示 "Plugin weather disabled (missing: WEATHER_API_KEY)"。

当用户运行 hermes plugins install 时，系统会交互式提示用户输入任何缺失的 requires_env 变量。值会自动保存到 .env。

为了获得更好的安装体验，可以使用带有描述和注册 URL 的富格式：

# plugin.yaml — 富格式
requires_env:
  - name: WEATHER_API_KEY
    description: "OpenWeather 的 API 密钥"
    url: "https://openweathermap.org/api"
    secret: true

字段	必需	描述
name	是	环境变量名称
description	否	在安装提示期间向用户展示
url	否	在何处获取凭证
secret	否	如果为 true，输入将被隐藏（类似密码字段）

两种格式可以在同一列表中混合使用。已设置的变量会被静默跳过。

懒安装可选的 Python 依赖

如果你的插件封装了一个并非所有用户都已安装的 SDK（供应商 SDK、大型 ML 库、平台特定包），请不要在模块顶部直接 import 它。在工具处理器内部使用 tools.lazy_deps.ensure(...) 辅助函数 — Hermes 会在首次使用时安装该包，受限于用户的 security.allow_lazy_installs 配置。

# tools.py
from tools.lazy_deps import ensure, FeatureUnavailable

def my_tool_handler(args, **kwargs):
    try:
        ensure("my-plugin.my-backend")   # 键必须在 LAZY_DEPS 中
    except FeatureUnavailable as exc:
        return {"error": str(exc)}

    import my_backend_sdk   # 现在安全了
    ...

tools/lazy_deps.py 安全模型中的两条规则：

规则	原因
你的功能键必须出现在树内 LAZY_DEPS 白名单中	防止恶意配置诱导 Hermes 安装任意包 — 只有 Hermes 自己提供的规格才有资格
规格仅为 PyPI 按名称指定	不允许 --index-url、git+https:// 或 file: 路径。在白名单条目中使用 PEP 440 指定版本（"my-sdk>=1.2,<2"）

对于通过 pip 分发的第三方插件，请在你自己的 pyproject.toml 中将可选依赖声明为 [project.optional-dependencies] 额外包，并告知用户 pip install your-plugin[backend] — 该路径不经过 lazy_deps。懒安装机制对于捆绑插件最有用，因为在每次安装时附带硬依赖会膨胀基础 Hermes 占用空间。

当全局设置 security.allow_lazy_installs: false 时，ensure() 会立即引发 FeatureUnavailable 并附带修复提示 — 你的插件应捕获它并优雅降级（返回错误结果，而不是使工具循环崩溃）。

条件工具可用性

对于依赖可选库的工具：

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = 工具对模型隐藏
)

覆盖内置工具

要用你自己的实现替换内置工具（例如，将默认浏览器工具换成带界面的 Chrome CDP 后端，或用自定义企业索引替换 web_search），请传入 override=True：

def register(ctx):
    ctx.register_tool(
        name="browser_navigate",             # 与内置工具同名
        toolset="plugin_my_browser",         # 你自己的工具集命名空间
        schema={...},
        handler=my_custom_navigate,
        override=True,                       # 显式选择加入
    )

如果没有 override=True，注册表会拒绝任何可能覆盖来自不同工具集的现有工具的注册 — 这防止了意外覆盖。覆盖操作会在 INFO 级别记录，因此可在 ~/.hermes/logs/agent.log 中审计。插件在内置工具之后加载，因此注册顺序是正确的：你的处理器替换了内置处理器。

注册多个钩子

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, duration_ms: int	忽略
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	忽略
on_session_finalize	CLI/网关关闭活动会话时	session_id: str | None, platform: str	忽略
on_session_reset	网关换入新会话密钥（/new, /reset）时	session_id: str, platform: str	忽略

大多数钩子是发后即忘的观察者 — 它们的返回值被忽略。pre_llm_call 是个例外，它可以向对话注入上下文。

所有回调都应接受 **kwargs 以保证前向兼容性。如果钩子回调崩溃，它会被记录并跳过。其他钩子和智能体会正常继续。

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 的领域 — 它包含模型特定指导、工具执行规则、个性指令和缓存的技能内容。插件通过伴随用户输入的方式提供上下文，而不是通过改变智能体的核心指令。

示例：记忆召回插件

"""记忆插件 — 从向量存储中召回相关上下文。"""

import httpx

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

def recall_context(session_id, user_message, is_first_turn, **kwargs):
    """在每轮 LLM 调用前被调用。返回召回的记忆。"""
    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  # 静默失败，不中断智能体

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

示例：护栏插件

"""护栏插件 — 执行内容策略。"""

POLICY = """本次会话你必须遵循以下内容策略：
- 永不生成访问工作目录外文件系统的代码
- 执行破坏性操作前总是发出警告
- 拒绝涉及个人数据提取的请求"""

def inject_guardrails(**kwargs):
    """在每轮注入策略文本。"""
    return {"context": POLICY}

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

示例：仅观察钩子（无注入）

"""分析插件 — 跟踪轮次元数据，不注入上下文。"""

import logging
logger = logging.getLogger(__name__)

def log_turn(session_id, user_message, model, is_first_turn, **kwargs):
    """在每次 LLM 调用前触发。返回 None — 不注入上下文。"""
    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):
    """hermes my-plugin <子命令> 的处理器。"""
    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):
    """为 hermes my-plugin 构建 argparse 树。"""
    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 命令不会干扰帮助输出。

注册斜杠命令

插件可以注册会话内斜杠命令 — 用户在对话期间输入的命令（如 /lcm status 或 /ping）。这些命令在 CLI 和网关（Telegram、Discord 等）中都有效。

def _handle_status(raw_args: str) -> str:
    """/mystatus 的处理器 — 接收命令名后的所有内容。"""
    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",
    )

注册后，用户可以在任何会话中输入 /mystatus。该命令会出现在自动补全、/help 输出和 Telegram 机器人菜单中。

签名： ctx.register_command(name: str, handler: Callable, description: str = "")

参数	类型	描述
name	str	命令名称，不带前导斜杠（例如 "lcm", "mystatus"）
handler	Callable[[str], str | None]	以原始参数字符串调用。也可以是 async。
description	str	显示在 /help、自动补全和 Telegram 机器人菜单中

与 register_cli_command() 的主要区别：

	register_command()	register_cli_command()
调用方式	会话中的 /name	终端中的 hermes name
适用场景	CLI 会话、Telegram、Discord 等	仅终端
处理器接收	原始参数字符串	argparse Namespace
使用案例	诊断、状态、快速操作	复杂的子命令树、设置向导

冲突保护： 如果插件尝试注册与内置命令冲突的名称（help、model、new 等），注册将被静默拒绝并记录警告日志。内置命令始终优先。

异步处理器： 网关调度会自动检测并等待异步处理器，因此你可以使用同步或异步函数：

async def _handle_check(raw_args: str) -> str:
    result = await some_async_operation()
    return f"Check result: {result}"

def register(ctx):
    ctx.register_command("check", handler=_handle_check, description="Run async check")

从斜杠命令调度工具

需要编排工具（通过 delegate_task 生成子智能体、调用 file_edit 等）的斜杠命令处理器应使用 ctx.dispatch_tool()，而不是直接访问框架内部。父智能体上下文（工作区提示、进度指示器、模型继承）会自动连接。

def register(ctx):
    def _handle_deliver(raw_args: str):
        result = ctx.dispatch_tool(
            "delegate_task",
            {
                "goal": raw_args,
                "toolsets": ["terminal", "file", "web"],
            },
        )
        return result

    ctx.register_command(
        "deliver",
        handler=_handle_deliver,
        description="Delegate a goal to a subagent",
    )

签名： ctx.dispatch_tool(name: str, args: dict, *, parent_agent=None) -> str

参数	类型	描述
name	str	在工具注册表中注册的工具名称（例如 "delegate_task", "file_edit"）
args	dict	工具参数，与模型发送的格式相同
parent_agent	Agent | None	可选覆盖。省略时，从当前 CLI 智能体解析（或在网关模式下降级处理）

运行时行为：

• CLI 模式： parent_agent 从活动的 CLI 智能体解析，因此工作区提示、进度指示器和模型选择会按预期继承。
• 网关模式： 没有 CLI 智能体，因此工具会降级处理 — 工作区从 TERMINAL_CWD 读取，不显示进度指示器。
• 显式覆盖： 如果调用者显式传递了 parent_agent=，它会被尊重且不会被覆盖。

这是从插件命令进行工具调度的公共、稳定接口。插件不应访问 ctx._cli_ref.agent 或类似的私有状态。

提示

本指南涵盖通用插件（工具、钩子、斜杠命令、CLI 命令）。以下各节概述了每种专门插件类型的编写模式；每个都链接到其完整指南以获取字段参考和示例。

专用插件类型

Hermes 除了通用界面外，还有五种专用插件类型。每种都以目录形式存在，位于 plugins/<category>/<name>/（内置）或 ~/.hermes/plugins/<category>/<name>/（用户自定义）。合同因类别而异——选择你需要的，然后阅读其完整指南。

模型提供商插件 — 添加 LLM 后端

将一个配置文件放入 plugins/model-providers/<name>/：

# plugins/model-providers/acme/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="acme",
    aliases=("acme-inference",),
    display_name="Acme Inference",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=("acme-large-v3", "acme-medium-v3"),
))

# plugins/model-providers/acme/plugin.yaml
name: acme-provider
kind: model-provider
version: 1.0.0
description: Acme Inference — 兼容 OpenAI 的直接 API

首次调用 get_provider_profile() 或 list_providers() 时会被懒发现——auth.py、config.py、doctor.py、models.py、runtime_provider.py 以及聊天完成传输会自动连接到它。用户插件按名称覆盖内置插件。

完整指南： 模型提供商插件 — 字段参考、可覆盖的钩子（prepare_messages、build_extra_body、build_api_kwargs_extras、fetch_models）、api_mode 选择、认证类型、测试。

平台插件 — 添加网关通道

将一个适配器放入 plugins/platforms/<name>/：

# plugins/platforms/myplatform/adapter.py
from gateway.platforms.base import BasePlatformAdapter

class MyPlatformAdapter(BasePlatformAdapter):
    async def connect(self): ...
    async def send(self, chat_id, text): ...
    async def disconnect(self): ...

def check_requirements():
    import os
    return bool(os.environ.get("MYPLATFORM_TOKEN"))

def _env_enablement():
    import os
    tok = os.getenv("MYPLATFORM_TOKEN", "").strip()
    if not tok:
        return None
    return {"token": tok}

def register(ctx):
    ctx.register_platform(
        name="myplatform",
        label="MyPlatform",
        adapter_factory=lambda cfg: MyPlatformAdapter(cfg),
        check_fn=check_requirements,
        required_env=["MYPLATFORM_TOKEN"],
        # 从环境变量自动填充 PlatformConfig.extra，这样仅通过环境变量设置的配置
        # 也能在 `hermes gateway status` 中显示，而无需实例化 SDK。
        env_enablement_fn=_env_enablement,
        # 选择启用定时投递：`deliver=myplatform` 路由到此变量。
        cron_deliver_env_var="MYPLATFORM_HOME_CHANNEL",
        emoji="💬",
        platform_hint="您正在通过 MyPlatform 进行对话。请保持回复简洁。",
    )

# plugins/platforms/myplatform/plugin.yaml
name: myplatform-platform
label: MyPlatform
kind: platform
version: 1.0.0
description: MyPlatform 网关适配器
requires_env:
  - name: MYPLATFORM_TOKEN
    description: "来自 MyPlatform 控制台的机器人令牌"
    password: true
optional_env:
  - name: MYPLATFORM_HOME_CHANNEL
    description: "用于定时投递的默认频道"
    password: false

完整指南： 添加平台适配器 — 完整的 BasePlatformAdapter 合同、消息路由、认证拦截、设置向导集成。查看 plugins/platforms/irc/ 作为仅使用标准库的可工作示例。

记忆提供商插件 — 添加跨会话知识后端

将 MemoryProvider 的一个实现放入 plugins/memory/<name>/：

# plugins/memory/my-memory/__init__.py
from agent.memory_provider import MemoryProvider

class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-memory"

    def is_available(self) -> bool:
        import os
        return bool(os.environ.get("MY_MEMORY_API_KEY"))

    def initialize(self, session_id: str, **kwargs) -> None:
        self._session_id = session_id

    def sync_turn(self, user_message, assistant_response, **kwargs) -> None:
        ...

    def prefetch(self, query: str, **kwargs) -> str | None:
        ...

def register(ctx):
    ctx.register_memory_provider(MyMemoryProvider())

记忆提供商是单选的——一次只有一个处于活动状态，通过 config.yaml 中的 memory.provider 选择。

完整指南： 记忆提供商插件 — 完整的 MemoryProvider 抽象基类、线程合同、配置文件隔离、通过 cli.py 注册 CLI 命令。

上下文引擎插件 — 替换上下文压缩器

# plugins/context_engine/my-engine/__init__.py
from agent.context_engine import ContextEngine

class MyContextEngine(ContextEngine):
    @property
    def name(self) -> str:
        return "my-engine"

    def should_compress(self, messages, model) -> bool: ...
    def compress(self, messages, model) -> list[dict]: ...

def register(ctx):
    ctx.register_context_engine(MyContextEngine())

上下文引擎是单选的——通过 config.yaml 中的 context.engine 选择。

完整指南： 上下文引擎插件。

图像生成后端

将一个提供商放入 plugins/image_gen/<name>/：

# plugins/image_gen/my-imggen/__init__.py
from agent.image_gen_provider import ImageGenProvider

class MyImageGenProvider(ImageGenProvider):
    @property
    def name(self) -> str:
        return "my-imggen"

    def is_available(self) -> bool: ...
    def generate(self, prompt: str, **kwargs) -> str: ...   # 返回图片路径

def register(ctx):
    ctx.register_image_gen_provider(MyImageGenProvider())

# plugins/image_gen/my-imggen/plugin.yaml
name: my-imggen
kind: backend
version: 1.0.0
description: 自定义图像生成后端

完整指南： 图像生成提供商插件 — 完整的 ImageGenProvider 抽象基类、list_models() / get_setup_schema() 元数据、success_response()/error_response() 辅助函数、base64 与 URL 输出、用户覆盖、pip 分发。

参考示例： plugins/image_gen/openai/（通过 OpenAI SDK 使用 DALL-E / GPT-Image）、plugins/image_gen/openai-codex/、plugins/image_gen/xai/（Grok 图像生成）。

非 Python 扩展界面

Hermes 也接受完全不是 Python 插件的扩展。这些扩展显示在可插拔接口表中；下面的小节简要概述了每种编写风格。

MCP 服务器 —— 注册外部工具

模型上下文协议（MCP）服务器无需任何 Python 插件即可将它们自己的工具注册到 Hermes 中。在 ~/.hermes/config.yaml 中声明它们：

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 120

  linear:
    url: "https://mcp.linear.app/sse"
    auth:
      type: "oauth"

Hermes 在启动时连接到每个服务器，列出其工具，并将它们与内置工具一起注册。大语言模型会像看待任何其他工具一样看待它们。完整指南： MCP。

网关事件钩子 —— 在生命周期事件时触发

将一个清单文件和处理器放入 ~/.hermes/hooks/<name>/：

# ~/.hermes/hooks/long-task-alert/HOOK.yaml
name: long-task-alert
description: 长任务完成时发送推送通知
events:
  - agent:end

# ~/.hermes/hooks/long-task-alert/handler.py
async def handle(event_type: str, context: dict) -> None:
    if context.get("duration_seconds", 0) > 120:
        # 发送通知...
        pass

事件包括 gateway:startup、session:start、session:end、session:reset、agent:start、agent:step、agent:end，以及通配符 command:*。钩子中的错误会被捕获并记录——它们永远不会阻塞主流程。

完整指南： 网关事件钩子。

Shell 钩子 —— 在工具调用时运行 shell 命令

如果你只想在工具触发时运行一个脚本（用于通知、审计日志、桌面提醒、自动格式化），可以在 config.yaml 中使用 shell 钩子——无需 Python：

hooks:
  - event: post_tool_call
    command: "notify-send '工具已运行: {tool_name}'"
    when:
      tools: [terminal, patch, write_file]

支持所有与 Python 插件钩子相同的事件（pre_tool_call、post_tool_call、pre_llm_call、post_llm_call、on_session_start、on_session_end、pre_gateway_dispatch），并支持 pre_tool_call 的结构化 JSON 输出以做出阻止决定。

完整指南： Shell 钩子。

技能来源 —— 添加自定义技能注册表

如果你维护着一个 GitHub 技能仓库（或者想从内置源之外的社区索引获取），可以将其添加为一个 tap：

hermes skills tap add myorg/skills-repo
hermes skills search my-workflow --source myorg/skills-repo
hermes skills install myorg/skills-repo/my-workflow

发布你自己的 tap 只需要一个包含 skills/<skill-name>/SKILL.md 目录的 GitHub 仓库——无需服务器或注册表注册。

完整指南： 技能中心 · 发布自定义 tap（仓库布局、最小示例、非默认路径、信任级别）。

通过命令模板实现 TTS / STT

任何读取/写入音频或文本的命令行界面都可以通过 config.yaml 插入——无需 Python 代码：

tts:
  provider: voxcpm
  providers:
    voxcpm:
      type: command
      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
      output_format: mp3
      voice_compatible: true

对于 STT，将 HERMES_LOCAL_STT_COMMAND 指向一个 shell 模板。支持的占位符：{input_path}、{output_path}、{format}、{voice}、{model}、{speed}（用于 TTS）；{input_path}、{output_dir}、{language}、{model}（用于 STT）。任何与路径交互的命令行界面都自动成为一个插件。

完整指南： TTS 自定义命令提供商 · STT。

通过 pip 分发

为了公开分享插件，请向你的 Python 包添加一个入口点：

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

pip install hermes-plugin-calculator
# 插件在下次 hermes 启动时自动发现

为 NixOS 分发

NixOS 用户可以声明式地安装你的插件，前提是你提供一个带有入口点的 pyproject.toml：

入口点插件（推荐用于分发）：

# 用户的 configuration.nix
services.hermes-agent.extraPythonPackages = [
  (pkgs.python312Packages.buildPythonPackage {
    pname = "my-plugin";
    version = "1.0.0";
    src = pkgs.fetchFromGitHub {
      owner = "you";
      repo = "hermes-my-plugin";
      rev = "v1.0.0";
      hash = "sha256-...";  # nix-prefetch-url --unpack
    };
    format = "pyproject";
    build-system = [ pkgs.python312Packages.setuptools ];
  })
];

目录插件（不需要 pyproject.toml）：

services.hermes-agent.extraPlugins = [
  (pkgs.fetchFromGitHub {
    owner = "you";
    repo = "hermes-my-plugin";
    rev = "v1.0.0";
    hash = "sha256-...";
  })
];

参阅 Nix 设置指南 获取完整文档，包括覆盖层使用和冲突检查。

常见错误

处理器不返回 JSON 字符串：

# 错误 —— 返回一个字典
def handler(args, **kwargs):
    return {"result": 42}

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

处理器签名中缺少 **kwargs：

# 错误 —— 如果 Hermes 传递额外上下文将会中断
def handler(args):
    ...

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

处理器抛出异常：

# 错误 —— 异常传播，工具调用失败
def handler(args, **kwargs):
    result = 1 / int(args["value"])  # ZeroDivisionError!
    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)})

模式描述过于模糊：

# 糟糕 —— 模型不知道何时使用它
"description": "做些事情"

# 良好 —— 模型确切知道何时以及如何使用
"description": "计算数学表达式。用于算术、三角函数、对数运算。支持：+、-、*、/、**、sqrt、sin、cos、log、pi、e。"