夜雨聆风上一篇我们介绍了工具（Tools）的概念。本篇介绍 Hermes 的插件（Plugin）系统，并动手开发第一个插件。
一、 认识 Hermes 插件
插件（Plugin）本质上是一组 Python 文件，无需修改 Hermes 的核心代码，就可以扩展 Hermes 的功能。
在安装和开发插件之前，我们先了解一下 Docker 环境下的插件存储结构。
1. 插件来源
Hermes 插件支持四种来源。在 Docker 环境下，存放位置如下：
内置插件
内置插件是Hermes官方预置，不可修改。
存储根目录：/opt/hermes/plugins/
用户插件
用户自行创建或安装的插件，也是最常用的方式。
存储根目录：/opt/data/plugins/
项目插件
仅在当前项目下生效。
需设置环境变量 HERMES_ENABLE_PROJECT_PLUGINS=true 才会加载。
存储根目录：<项目目录>/.hermes/plugins/
pip 插件
通过 pip install 安装。
存储根目录：作为标准 Python 包自动注册，无需手动管理目录。
2. 插件目录
无论采用哪种安装方式，插件的内部目录结构均保持一致。按目录结构来看，插件分为通用插件和特殊插件（如 memory、context_engine 等）。
/opt/data/plugins/ #根目录├── 插件A/ # 通用插件│ ├── plugin.yaml # 清单文件，声明插件元数据│ ├── __init__.py # 注册函数，将 Schema 与处理器绑定│ ├── schemas.py # 工具描述，定义 LLM 可见的接口│ └── tools.py # 处理器，工具被调用时实际执行的代码│├── memory/ # 特殊插件：memory│ └── 插件B/│ ├── plugin.yaml│ └── __init__.py│└── ......
一个通用插件通常包含以下几个核心文件：
● __init__.py (必需): 插件入口，必须包含 register(ctx) 函数。
● plugin.yaml (推荐): 声明插件的名称、版本、描述等元数据。
● schemas.py (可选): 定义工具的描述和参数结构（LLM 看到的内容）。
● tools.py (可选): 工具被调用时实际执行的代码。
3. 插件安装
方式一：从GitHub仓库安装
hermes plugins install owner/repo安装完成后，系统会询问是否立即启用，默认选否。
方式二：手动安装
直接把插件文件夹放入 /opt/data/plugins/ 目录即可。
4. 插件使用
⚠️ 插件放入目录后默认是禁用状态，需要手动启用，有以下几种方式
●命令行启用：hermes plugins enable <插件名>
●交互式界面：运行 hermes plugins，然后用空格键选择要启用的插件。
●配置文件启用：在 /opt/data/config.yaml 的 plugins.enabled 列表中添加插件名。
当插件启用后，其中注册的工具（Tool）会自动加入 Hermes 的工具列表，Hermes 会根据任务需要自主决定是否调用这些工具。
5. 常用插件命令
命令 | 说明 |
hermes plugins | 进入管理插件页面 |
hermes plugins list | 列出所有插件 |
hermes plugins install user/repo | 从 GitHub 安装插件 |
hermes plugins update <插件名> | 拉取插件最新版本 |
hermes plugins remove <插件名> | 卸载插件 |
hermes plugins enable <插件名> | 启用插件 |
hermes plugins disable <插件名> | 禁用插件 |
二、 插件的开发：一个简单的示例
我们以最简单的 Hello World 插件为例。
第一步：创建插件目录
mkdir -p /opt/data/plugins/hello-world第二步：创建plugin.yaml —— 插件的身份证
Hermes Agent 会读取该文件，用于获取插件的名称、版本、描述以及所需环境变量等元数据。
name: hello-worldversion: "1.0"description: A minimal example plugin with modular structureauthor: Your Name
第三步：创建schemas.py —— 插件的说明书
Schema 是工具暴露给 LLM 的描述信息，它告诉模型这个工具叫什么、做什么，以及需要哪些参数。
"""Tool schemas for the hello-world plugin."""def get_hello_world_schema():"""Return the schema for the hello_world tool."""return {"name": "hello_world","description": "Returns a friendly greeting for the given name.","parameters": {"type": "object","properties": {"name": {"type": "string","description": "Name to greet",}},# 必填参数列表（这里 name 是必填的）"required": ["name"],},}
💡字段说明：
●name：工具的唯一名称，模型通过这个名字调用该工具
●description：该字段是 LLM 判断是否调用工具的重要依据，因此要尽量准确说明功能和使用时机
●parameters：遵循 JSON Schema 规范，用于定义工具接收的参数。
第四步：创建 tools.py ——功能实现
tools.py 定义了工具真正执行的业务逻辑。当 LLM 决定调用工具时，Hermes 最终执行的就是这里的函数。
"""Tool handlers for the hello-world plugin."""import jsondef handle_hello_world(params, **kwargs):# 避免未使用变量警告del kwargs# 从 params 中获取 name，如果未提供则默认为 "World"name = params.get("name", "World")# 返回 JSON 格式的结果，包含成功标志和问候语return json.dumps({"success": True, "greeting": f"Hello, {name}!"})
第五步：创建 __init__.py —— 注册插件
__init__.py 是插件的入口文件。Hermes 加载插件时，会调用其中的 register(ctx) 函数，将 Schema、处理器以及 Hook 注册到系统中。
"""Hello World plugin entry point."""from .schemas import get_hello_world_schemafrom .tools import handle_hello_worlddef register(ctx):"""Register the hello-world tool."""ctx.register_tool(name="hello_world", # 工具名称，需与 Schema 中保持一致toolset="hello_world", # 工具所属的工具集schema=get_hello_world_schema(), # 获取工具 Schemahandler=handle_hello_world, # 获取工具处理函数description="Return a friendly greeting for the given name.",)
第六步：测试插件
# 查看插件状态hermes plugins list# 启用插件hermes plugins enable hello-world
进入 Hermes 对话后，可以尝试输入：请用 hello_world 工具向 'Hermes' 打个招呼。如果返回 Hello, Hermes!，说明插件开发成功。
三、 高阶功能
插件除了注册工具之外，还支持很多高级能力，例如：
●斜杠命令
●命令行扩展
●调度其他工具
●注入消息
●调用大模型
●图像/视频生成后端
更多内容可以参考 Hermes 官方文档《构建 Hermes 插件》和《插件》章节。
写在最后
插件让 Hermes 从一个固定功能的 AI 工具，变成了一个可以持续扩展的平台。不过，开发插件需要一定的 Python 编程基础，更适合有开发经验的用户。
下一篇，我们将介绍 MCP（模型上下文协议）。相比插件开发，MCP 更适合通过标准协议接入 GitHub、数据库、浏览器等外部服务，大多数场景下，无需开发插件即可完成接入。
