学会这 5 个 Hermes 插件开发本领，让 Agent 本领扩展 10 倍

Hermes Agent 插件使用教程

项目需求总在变，Agent 功能却”锁死”在框架里，改源码又怕升级时被覆盖？Hermes Agent 的插件体系正是为此而生——它是 模块化扩展核心本领 的关键机制，无需修改框架源码，即可自界说工具、变乱钩子、下令与集本钱事。插件依照 ”低侵入、高兼容、可插拔” 筹划，支持用户自界说、项目专属、官方内置三类插件，覆盖工具扩展、流程自动化、第三方集成等全场景。本文从核心概念、插件管理、开发入门、内置插件、最佳实践五方面，带你全面把握插件使用与开发。
一、插件核心概念

1.1 什么是插件

插件是 Hermes 的扩展模块，以独立目次情势存在，通过标准化设置与代码，向 Agent 注入自界说本领，完全解耦于核心框架，升级 / 更换不影响主步伐运行。
1.2 插件范例

Hermes 插件分为三类，各司其职：

• 通用插件（General）：自界说工具、钩子、斜杠下令，可组合启用。
  
• 内存插件（Memory Provider）：更换 / 增强内置影象体系，仅支持单实例。
  
• 上下文插件（Context Engine）：更换内置上下文压缩本领，仅支持单实例。
  

1.3 插件发现路径

插件按优先级扫描，后加载覆盖同名先加载插件：

• 官方内置：框架自带插件（/plugins），默认禁用。
  
• 用户插件：个人专属（~/.hermes/plugins），全局收效。
  
• 项目插件：项目目次（./.hermes/plugins），需手动开启权限。
  
• Pip 插件：通过 hermes_agent.plugins 入口点分发。
  

1.4 启用机制

插件默认禁用，需手动到场答应列表（plugins.enabled）才会加载。
图1：插件范例与发现路径图
graph LR    subgraph "插件范例"        A[通用插件 General
工具 · 钩子 · 斜杠下令]        B[内存插件 Memory Provider
仅支持单实例]        C[上下文插件 Context Engine
仅支持单实例]    end        subgraph "发现路径（按优先级）"        D[官方内置 /plugins]        E[用户插件 ~/.hermes/plugins]        F[项目插件 ./.hermes/plugins]        G[Pip 插件 hermes_agent.plugins]    end        D -->|后加载覆盖先加载| E    E -->|后加载覆盖先加载| F    F -->|后加载覆盖先加载| G明确了插件范例与发现机制后，接下来看看怎样用 CLI 下令管理这些插件。
二、插件管理（CLI 下令）

Hermes 提供同一 CLI，实现插件全生命周期管理。
2.1 检察插件

1. # 交互式面板（空格勾选启用/禁用）
2. hermes plugins
4. # 列表模式（显示启用/禁用状态）
5. hermes plugins list

复制代码

2.2 启用 / 禁用插件

1. # 启用单个插件
2. hermes plugins enable 插件名
4. # 禁用单个插件（加入拒绝列表）
5. hermes plugins disable 插件名

复制代码

2.3 安装 / 更新 / 卸载

1. # 从 Git 安装（自动提示启用）
2. hermes plugins install 仓库名/插件名
4. # 安装并自动启用
5. hermes plugins install 仓库名/插件名 --enable
7. # 更新插件
8. hermes plugins update 插件名
10. # 卸载插件
11. hermes plugins remove 插件名

复制代码

2.4 设置文件管理

插件状态长期化于 ~/.hermes/config.yaml：

1. plugins:
2.   enabled:    # 允许列表（启用的插件）
3.     - hello-world
4.     - disk-cleanup
5.   disabled:   # 拒绝列表（强制禁用）
6.     - noisy-plugin

复制代码

设置管理是底子，但假如内置插件不满意需求，你可以本身动手开发一个插件。
三、插件开发入门（极简示例）

3.1 目次布局

最小插件仅需 4 个文件：

1. ~/.hermes/plugins/hello-world/
2. ├── plugin.yaml   # 插件元数据
3. ├── __init__.py   # 注册入口
4. ├── schemas.py    # 工具模型（可选）
5. └── tools.py      # 工具逻辑

复制代码

3.2 编写设置（plugin.yaml）

1. name: hello-world
2. version: "1.0.0"
3. description: 极简示例插件（打招呼工具+日志钩子）

复制代码

3.3 注册入口（init.py）

1. import json
3. def register(ctx):
4.     # 1. 注册工具：hello_world
5.     tool_schema = {
6.         "name": "hello_world",
7.         "description": "向指定用户打招呼",
8.         "parameters": {
9.             "type": "object",
10.             "properties": {"name": {"type": "string", "description": "用户名"}},
11.             "required": ["name"]
12.         }
13.     }
15.     def handle_hello(params, **kwargs):
16.         name = params.get("name", "World")
17.         return json.dumps({"success": True, "greeting": f"Hello, {name}!"})
19.     ctx.register_tool(
20.         name="hello_world",
21.         toolset="hello-world",
22.         schema=tool_schema,
23.         handler=handle_hello,
24.         description="向用户打招呼"
25.     )
27.     # 2. 注册钩子：日志所有工具调用
28.     def log_tool_call(tool_name, params, result, **kwargs):
29.         print(f"[插件日志] 工具：{tool_name}，参数：{params}")
31.     ctx.register_hook("post_tool_call", log_tool_call)

复制代码

3.4 启用测试

1. # 启用插件
2. hermes plugins enable hello-world
4. # 重启 Hermes 生效
5. hermes restart
7. # 调用工具
8. hermes chat "调用 hello_world 工具，name=Hermes"

复制代码

本身动手开发了插件，再看看 Hermes 自带的几个实用插件，开箱即用。
四、官方内置插件

Hermes 自带实用内置插件，开箱即用。
4.1 disk-cleanup（磁盘清算）

功能：自动追踪并清剖析话暂时文件（测试脚本、缓存、日记）。

1. # 启用
2. hermes plugins enable disk-cleanup
4. # 手动清理
5. /disk-cleanup quick

复制代码

4.2 observability/langfuse（可观测性）

功能：对接 Langfuse，追踪 LLM 调用、工具实行、会话链路。

1. # 交互式配置（推荐）
2. hermes tools → Langfuse → 输入密钥
4. # 启用
5. hermes plugins enable observability/langfuse

复制代码

4.3 google_meet（集会助手）

功能：自动到场 Google Meet、及时转录、天生纪要。

1. # 启用并授权
2. hermes plugins enable google_meet

复制代码

内置插件覆盖了常见需求，但假如要深度定制，就必要相识插件提供的核心扩展本领。
五、插件核心本领开发

5.1 自界说工具

通过 ctx.register_tool 注册自界说工具，支持参数校验、效果返回。
5.2 变乱钩子

支持全生命周期钩子，拦截 / 增强 Agent 举动：

• pre_tool_call：工具实行前（拦截伤害操纵）
  
• post_tool_call：工具实行后（日记 / 统计）
  
• pre_llm_call：LLM 推理前（注入上下文）
  
• on_session_end：会话竣事（清算资源）
  

5.3 斜杠下令

注册自界说会话下令，CLI / 网关均可调用：

1. ctx.register_command(
2.     name="mycmd",
3.     handler=mycmd_handler,
4.     description="自定义命令"
5. )

复制代码

把握了插件的开发方式，末了总结几项最佳实践，帮你构建结实的插件生态。
六、最佳实践

• 权限控制：项目插件需手动开启 HERMES_ENABLE_PROJECT_PLUGINS=true，仅信托堆栈启用。
  
• 定名规范：插件名小写 + 连字符，克制辩论。
  
• 精简筹划：单一插件聚焦单一本领，克制功能痴肥。
  
• 安全优先：插件钩子拦截高危工具（rm -rf、sudo）。
  
• 版本管理：插件标注版本，更新前测试兼容性。
  

七、总结

Hermes 插件体系以模块化、低侵入、高扩展为核心，覆盖自界说工具、变乱钩子、第三方集成等场景，官方内置插件开箱即用，自界说插件开发极简。通过同一 CLI 管理，连合安全启用机制，可机动扩展 Agent 本领，适配个性化、项目专属、复杂集成等各类需求，是 Hermes 生态扩展的核心基石。