Hermes 插件开发

当内置工具和技能还不够时，你可以写插件把 Hermes 接到自己的系统。本篇讲清插件目录结构、三类插件，以及如何让它生效。

插件放在哪

插件默认目录是 ~/.hermes/plugins/，每个插件一个子文件夹。管理入口是交互式命令：

hermes plugins

在里面可以浏览、安装、启用或禁用插件。

三类插件

Hermes 把插件分为三类，各管一块：

通用插件（general）：提供自定义工具（tools）与生命周期钩子（hooks），最常见。
记忆插件（memory providers）：接入新的记忆后端，扩展「记住什么、怎么记」。
上下文插件（context engines）：改变上下文的组织与检索方式。

如果你只是想加一个新工具，选 general 类就够了。

最小插件结构

一个通用插件至少包含 plugin.yaml 和 __init__.py。稍复杂时会再加 schemas.py（参数校验）和 tools.py（工具实现）。plugin.yaml 声明元信息与工具清单，__init__.py 里用 register(ctx) 把工具注册进去：

# __init__.py
def register(ctx):
    ctx.register_tool(
        name="my_tool",
        toolset="my_tools",
        schema={"type": "object", "properties": {"q": {"type": "string"}}},
        handler=my_handler,
    )

def my_handler(q):
    return f"你问我：{q}"

register_tool 的四个要素：名字、所属工具集、参数 schema、处理函数。写好之后，这个工具就会和内置工具一样被 Agent 自动调用。

插件是「显式启用」的

这一点常被忽略：插件装好不会自动生效，必须在配置里启用。两种方式：

在 config.yaml 里把插件加入启用列表（plugins.enabled）。
或在交互式 hermes plugins 里执行 enable <name>。

不启用，插件里的工具就不会出现在可用列表，也不会被调度。

开发流程建议

在 ~/.hermes/plugins/ 下新建插件文件夹。
写 plugin.yaml 与 __init__.py，实现 register(ctx)。
用 hermes plugins 启用该插件。
启一个会话，hermes tools 确认新工具出现，再实际调用验证。

出错时先 hermes config check，再用 hermes doctor 做整体体检。

插件与技能的区别

插件：写代码扩展能力（新工具、新记忆后端），偏工程。
技能：写文档沉淀方法，偏知识。

想「加一个新能力」用插件，想「教它一套做法」用技能。

本篇小结

插件目录 ~/.hermes/plugins/，用 hermes plugins 管理。
三类：通用（工具/钩子）、记忆后端、上下文引擎。
最小结构：plugin.yaml + __init__.py，在 register(ctx) 里 ctx.register_tool(...)。
插件必须显式启用才会生效。

下一篇我们做一次完整实战，把前面学的串起来。