5 分钟上手！Hermes Agent 插件开发保姆级教程，扩展能力从此开挂

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插件类型与发现路径图发现路径按优先级后加载覆盖先加载后加载覆盖先加载后加载覆盖先加载官方内置 /plugins用户插件 ~/.hermes/plugins项目插件 ./.hermes/pluginsPip 插件 hermes_agent.plugins插件类型通用插件 General工具 · 钩子 · 斜杠命令内存插件 Memory Provider仅支持单实例上下文插件 Context Engine仅支持单实例理解了插件类型与发现机制后接下来看看如何用 CLI 命令管理这些插件。二、插件管理CLI 命令Hermes 提供统一 CLI实现插件全生命周期管理。2.1 查看插件# 交互式面板空格勾选启用/禁用hermes plugins# 列表模式显示启用/禁用状态hermes plugins list2.2 启用 / 禁用插件# 启用单个插件hermes pluginsenable插件名# 禁用单个插件加入拒绝列表hermes plugins disable 插件名2.3 安装 / 更新 / 卸载# 从 Git 安装自动提示启用hermes pluginsinstall仓库名/插件名# 安装并自动启用hermes pluginsinstall仓库名/插件名--enable# 更新插件hermes plugins update 插件名# 卸载插件hermes plugins remove 插件名2.4 配置文件管理插件状态持久化于~/.hermes/config.yamlplugins:enabled:# 允许列表启用的插件-hello-world-disk-cleanupdisabled:# 拒绝列表强制禁用-noisy-plugin配置管理是基础但如果内置插件不满足需求你可以自己动手开发一个插件。三、插件开发入门极简示例3.1 目录结构最小插件仅需 4 个文件~/.hermes/plugins/hello-world/ ├── plugin.yaml # 插件元数据 ├── __init__.py # 注册入口 ├── schemas.py # 工具模型可选 └── tools.py # 工具逻辑3.2 编写配置plugin.yamlname:hello-worldversion:1.0.0description:极简示例插件打招呼工具日志钩子3.3 注册入口init.pyimportjsondefregister(ctx):# 1. 注册工具hello_worldtool_schema{name:hello_world,description:向指定用户打招呼,parameters:{type:object,properties:{name:{type:string,description:用户名}},required:[name]}}defhandle_hello(params,**kwargs):nameparams.get(name,World)returnjson.dumps({success:True,greeting:fHello,{name}!})ctx.register_tool(namehello_world,toolsethello-world,schematool_schema,handlerhandle_hello,description向用户打招呼)# 2. 注册钩子日志所有工具调用deflog_tool_call(tool_name,params,result,**kwargs):print(f[插件日志] 工具{tool_name}参数{params})ctx.register_hook(post_tool_call,log_tool_call)3.4 启用测试# 启用插件hermes pluginsenablehello-world# 重启 Hermes 生效hermes restart# 调用工具hermes chat调用 hello_world 工具nameHermes自己动手开发了插件再看看 Hermes 自带的几个实用插件开箱即用。四、官方内置插件Hermes 自带实用内置插件开箱即用。4.1 disk-cleanup磁盘清理功能自动追踪并清理会话临时文件测试脚本、缓存、日志。# 启用hermes pluginsenabledisk-cleanup# 手动清理/disk-cleanup quick4.2 observability/langfuse可观测性功能对接 Langfuse追踪 LLM 调用、工具执行、会话链路。# 交互式配置推荐hermes tools → Langfuse → 输入密钥# 启用hermes pluginsenableobservability/langfuse4.3 google_meet会议助手功能自动加入 Google Meet、实时转录、生成纪要。# 启用并授权hermes pluginsenablegoogle_meet内置插件覆盖了常见需求但如果要深度定制就需要了解插件提供的核心扩展能力。五、插件核心能力开发5.1 自定义工具通过ctx.register_tool注册自定义工具支持参数校验、结果返回。5.2 事件钩子支持全生命周期钩子拦截 / 增强 Agent 行为pre_tool_call工具执行前拦截危险操作post_tool_call工具执行后日志 / 统计pre_llm_callLLM 推理前注入上下文on_session_end会话结束清理资源5.3 斜杠命令注册自定义会话命令CLI / 网关均可调用ctx.register_command(namemycmd,handlermycmd_handler,description自定义命令)掌握了插件的开发方式最后总结几项最佳实践帮你构建健壮的插件生态。六、最佳实践权限控制项目插件需手动开启HERMES_ENABLE_PROJECT_PLUGINStrue仅信任仓库启用。命名规范插件名小写 连字符避免冲突。精简设计单一插件聚焦单一能力避免功能臃肿。安全优先插件钩子拦截高危工具rm -rf、sudo。版本管理插件标注版本更新前测试兼容性。七、总结Hermes 插件系统以模块化、低侵入、高扩展为核心覆盖自定义工具、事件钩子、第三方集成等场景官方内置插件开箱即用自定义插件开发极简。通过统一 CLI 管理结合安全启用机制可灵活扩展 Agent 能力适配个性化、项目专属、复杂集成等各类需求是 Hermes 生态扩展的核心基石。