给“爱马仕”hermes plugins装个外挂缺啥能力就装啥
TUTORIAL · AI 插件通关2026.07
AI 出厂能力就够用了？
给“爱马仕”装个外挂
缺啥能力就装啥
Plugins 插件系统 · Hermes 教程系列第 9 篇 · 能力扩展一关通
Hermes Agent 通关指南
Plugins插件
📦 9 Parts + Conclusion
👉 滑动
PART 01
Plugins 是啥
一段真能跑的 Python
PART 02
vs Skills
别搞混
PART 03
安装管理
CLI 全在这
PART 04
内置插件
70+ 挑常用
PART ///
写在最后
速查 + 收尾
用 Hermes 用到第 N 个天，我开始嫌它不够用了。
不是它笨，是它“会的事”就那么多。想让它接个飞书机器人发消息——不会。想让它用 Brave 搜点东西——不会。想让它把每次 LLM 调用都记到 Langfuse 里看观测——还是不会。
一开始我以为是 Prompt 没写好，调了半天没调出来。后来翻文档才反应过来：这些活儿不是 AI 该“想”的，是得给它装上对应的能力。说白了，Hermes 出厂不会的，靠插件加。
这就引出本篇的主角——Plugins 插件系统。Hermes 内置 70 多个插件，想接什么平台、什么搜索、什么模型 Provider，基本都是一条命令的事。不够还能自己写。
前面安装、斜杠命令、模型配置、技能系统、Memory、Cron 都讲过了，这篇收一下“能力扩展”这块。如果你在团队里推 Hermes，这篇转给同事一起看，省得每个人都得踩一遍“我以为是 AI 不行，其实是没装插件”这个坑。
01
PART
Plugins 是什么：一段真能跑的 Python
WHAT IS A PLUGIN
一句话，Plugins 是 Hermes 的 Python 扩展机制。
它能往 AI 身上加五种东西：
工具（Tools）
新能力，比如搜索、绘图、发消息
钩子（Hooks）
拦截事件，比如消息过滤、安全检查
命令（Commands）
自定义斜杠命令
提供者（Providers）
接入新的模型 API
平台适配器
接入新的聊天平台
关键在这：插件是真代码，不是文本。它能调 API、能写文件、能发请求，Python 能干的事它都能干。跟那种纯靠 Markdown 提示词扩展的方式不是一个量级。
几个关键特性你心里有数就行：
特性 说明 Python 扩展 真代码，能做任何 Python 能做的事 即装即用 一条命令安装，自动加载 内置丰富 70+ 内置插件，覆盖主流场景 可开发 按规范写 Python，打包发布
02
PART
Plugins vs Skills：这事我一开始没分清
PLUGINS VS SKILLS
说实话，我刚接触 Plugins 的时候跟 Skills 搞混了，以为是一个东西的两个名字。后来踩了几次坑才分清楚——这俩干的不是一码事。
直接看表：
对比项 Plugins Skills 本质 Python 代码 Markdown 文档 作用 扩展功能 注入知识 能力 能调 API、写文件、发请求 只能提供文本指导 开发 需要 Python 开发能力 写 Markdown 就行 典型场景 接入新平台、新工具 项目规范、工作流
Plugins 管“能做什么”，Skills 管“怎么做”
举个实在的例子。我想让 AI 把每次的对话总结发到飞书：
Skills 写一份规范——按什么格式总结、收件人是谁、几点发，告诉 AI 怎么做。
Plugins 装一个能调飞书机器人 API 的工具，给 AI 做的能力。
光有 Skills 没 Plugins，AI 知道怎么做但做不了（没接口）；光有 Plugins 没 Skills，AI 有能力但不知道按什么规矩用。俩搭着用最顺。
我自己的玩法是：先装 Plugins 给能力，再用 Skills 把“这个能力该怎么用”写进去。前面技能系统那篇里讲的规范，配着这块看最清楚。
03
PART
安装和管理：CLI 命令全在这
INSTALL & MANAGE
插件装完会自动加载，不用重启。日常操作都在终端 CLI 里，我整理了一份能直接抄的：
...bash
查看所有插件
hermes plugins list
只看已启用的
hermes plugins list --enabled
只看用户安装的（不含内置）
hermes plugins list --user
安装插件
hermes plugins install
安装并启用
hermes plugins install --enable
安装但不启用
hermes plugins install --no-enable
强制重装
hermes plugins install --force
更新插件
hermes plugins update
启用 / 禁用
hermes plugins enable
hermes plugins disable
卸载
hermes plugins remove
这个位置能填的东西挺多，不止 PyPI 包名：
来源 示例 PyPI 包名 hermes-plugin-example Git 仓库 https://github.com/user/plugin.git 本地路径 ./my-plugin 内置插件名 disk-cleanup （直接 enable 就行，不用 install）
最后那行划重点：内置插件不用 install，直接 enable 就启用了。我第一次用的时候还傻乎乎去 install disk-cleanup，结果报错说找不到包，翻了半天文档才反应过来。
如果你跟我一样不爱记命令，直接改 config.yaml 也行，团队里推的时候尤其方便，一份配置所有人统一：
...yaml
plugins:
enabled:
-
disk-cleanup
-
security-guidance
-
langfuse
disabled:
- some-plugin
04
PART
内置插件：70 多个，先看你大概率会用的
BUILT-IN PLUGINS
Hermes 内置 70+ 插件，全列出来得半页纸。我挑几类常用的讲，让你心里有个“哦，原来连这个都有”的谱。具体清单用 hermes plugins list 自己翻。
通用功能类
插件 干嘛的 disk-cleanup 定期清缓存，防止磁盘爆满 security-guidance 安全提醒，防敏感信息泄露 langfuse LLM 调用追踪和观测 google_meet Google Meet 会议集成
disk-cleanup 我几乎人人推荐——Hermes 跑久了缓存真能把磁盘塞满，开着它省心。security-guidance 跟 Memory 那篇讲的“防 AI 把密钥记进去”一脉相承，多一层提醒没坏处。
模型 Provider（20+ 个）
这块是 Hermes 最香的地方之一，基本主流模型全有：
插件 Provider anthropic Claude 系列 openai GPT 系列 openrouter 多模型聚合 gemini Google Gemini deepseek DeepSeek xai xAI Grok moonshot 月之暗面 Kimi zhipu 智谱 GLM minimax MiniMax ollama 本地模型
想用哪家模型，装对应 Provider 就行。前面模型配置那篇讲过怎么切，配上 Provider 插件才完整。
平台适配器
接聊天平台用的：
插件 平台 discord Discord telegram Telegram teams Microsoft Teams mattermost Mattermost slack Slack
Web 搜索工具
AI 想联网查东西就靠这些：
插件 特点 brave Brave 搜索 API ddgs DuckDuckGo 搜索 exa AI 原生搜索 firecrawl 网页抓取 tavily Tavily AI 搜索 xai xAI 搜索
搜索这块我自己装的是 brave，免费额度够日常用。ddgs 不要 key 也能跑，图省事的话先上这个试水。
05
PART
插件目录与 plugin.yaml
STRUCTURE & METADATA
装好的插件长这样：
...tree
~/.hermes/plugins// # 用户插件
├── plugin.yaml # 元信息（必需）
└── plugin.py # 入口代码（必需）
/plugins// # 内置插件
plugin.yaml 是元信息，格式很简洁：
...yaml
name: my-plugin
version: 1.0.0
description: 我的自定义插件
author: Your Name
requires:
- requests>=2.28.0
requires 这块要留意，写的依赖装插件时会一并处理。漏写了运行时报“模块找不到”，看着像 bug 其实是没声明依赖。
插件有三种状态，别混：
状态 说明 enabled 已安装且启用，加载到 Agent disabled 已安装但禁用，不加载 not enabled 已安装但没配启用状态
！踩坑提示 🕳
not enabled 这个状态新手容易懵——它不是 disabled，是“装了但配置里没说要不要用”。hermes plugins list --enabled 看不到，但插件确实在那躺着。要让它干活，要么 hermes plugins enable ，要么写进 config.yaml 的 enabled 里。
06
PART
自己写一个插件：最小示例
BUILD YOUR OWN
内置的不够用，就自己写。门槛比你想的低，核心就是一个 register 函数。
最小可跑的插件长这样：
...python
plugin.py
from hermes import PluginContext
def register(ctx: PluginContext):
"""插件入口函数"""
注册一个工具
@ctx.register_tool(
name="hello",
description="打个招呼"
)
async def hello(name: str, **kwargs) -> str:
return f"Hello, {name}!"
...yaml
plugin.yaml
name: hello-plugin
version: 1.0.0
description: 简单的打招呼插件
扔到 ~/.hermes/plugins/hello-plugin/ 下，hermes plugins enable hello-plugin，齐活。
register 里能注册五种东西，对应前面讲的五类扩展：
...python
def register(ctx: PluginContext):
1. 工具
ctx.register_tool(name="...", handler=...)
2. 钩子
ctx.register_hook(event="pre_llm_call", handler=...)
3. 命令
ctx.register_command(name="mycommand", handler=...)
4. 提供者
ctx.register_provider(name="...", cls=...)
5. 平台适配器
ctx.register_platform_adapter(name="...", cls=...)
钩子能挂的时机
就这几个，开发拦截逻辑的时候照着对：
钩子 触发时机 session_start 会话开始时 pre_llm_call 调用 LLM 前 post_llm_call LLM 响应后 pre_tool_call 执行工具前 post_tool_call 工具执行后 message_send 发送消息时
我最早写的一个钩子挂在 pre_tool_call，专门拦 AI 准备调外部 API 前先打日志——后来直接换成 langfuse 插件了，省事。
工具开发的三条硬规范
这是踩坑最多的地方，单独拎出来讲。写工具函数有 三条硬规矩，少一条都跑不起来：
...python
@ctx.register_tool(
name="my_tool",
description="工具描述"
)
async def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
"""
重要规范：
-
必须有 **kwargs 参数
-
必须返回 JSON 字符串
-
使用 type hints 标注参数类型
"""
import json
result = {"status": "ok", "data": f"{param1}: {param2}"}
return json.dumps(result)
一条条说为什么：
1
**必须有 kwargs——Hermes 调你的工具时会塞一些上下文参数进来（比如 session 信息），你不接就报参数不匹配。我第一次写漏了这个，AI 一调就崩，报错信息还看不出原因，蹲了半小时才反应过来。
2
必须返回 JSON 字符串——不是 dict、不是字符串，是 json.dumps() 出来的字符串。返回别的格式 AI 读不懂，直接报 handler must return JSON。
3
必须有 type hints——param1: str 这种标注不能省。Hermes 靠这个给 AI 描述工具参数的类型，没标注 AI 不知道该传啥。
这三条记住，工具函数基本不会跑飞。
打包发布
写完想分享给同事或发到 PyPI，标准 Python 打包流程：
...bash
目录结构
my-plugin/
├── plugin.yaml
├── plugin.py
├── pyproject.toml # 打包配置
└── README.md
打包
pip install build
python -m build
发布到 PyPI
pip install twine
twine upload dist/*
团队内部用的话，扔个 Git 仓库，让别人 hermes plugins install https://...git 就行，不一定非得发 PyPI。
07
PART
出问题了：先上安全模式
DEBUG & SAFE MODE
装第三方插件难免会撞车。我有一次装了个搜索插件，结果它注册的工具名跟另一个插件重了，AI 调工具时一阵抽风，两个工具随机响一个，排查半天没头绪。
这种时候直接上安全模式：
...bash
hermes --safe-mode
安全模式下只加载核心工具，不加载任何用户插件。能跑说明是插件的事，再一个一个 enable 回来定位是哪个家伙惹的祸。
常见问题我整理成表了，对着查省事：
问题 原因 解决方法 工具未出现 插件没启用 hermes plugins enable 报错 handler must return JSON 返回格式错 确保返回 JSON 字符串 参数报错 缺 **kwargs 加上 **kwargs 参数 插件冲突 多插件注册同名工具 --safe-mode 排查 依赖缺失 Python 包没装 在 plugin.yaml 加 requires
想看更细的日志，开 DEBUG：
...bash
hermes --log-level DEBUG
日志位置
~/.hermes/logs/
我遇到诡异问题就开 DEBUG 跑一遍，日志里基本能定位到哪个插件在哪个钩子上炸了。
08
PART
怎么用最稳：几条朴素建议
BEST PRACTICES
插件这东西，够用就行，别贪多。我见过有人一上来装二三十个，结果一半用不上，还互相冲突。几条原则：
原则 说明 够用就行 内置 70+ 够用，别装太多 来源可信 只装 PyPI 或官方仓库的 定期审查 用 list --enabled 检查，禁用不用的 权限最小 插件能做的事限制在必要范围内
来源这条我得多说一句：插件是 Python 代码，能干任何 Python 能干的事——意味着你装一个不靠谱的插件，它能在你机器上读文件、发请求、甚至执行系统命令。只装你信得过的来源，别图省事随便 install 一个 Git 仓库。GitHub 上看着 star 多的不一定是安全的，看一眼代码再装。
我自己的工作流是这样的：
...workflow
-
先用内置插件 → 能力不够再加第三方
-
技能定义规范 → 插件提供能力
-
定期清理 → 用 disk-cleanup 自动清缓存
-
安全优先 → 启用 security-guidance
团队里推的话，统一一份 config.yaml 大家都照着配，最省心：
...yaml
团队统一 config.yaml
plugins:
enabled:
-
disk-cleanup
-
security-guidance
-
langfuse # 统一观测
-
brave # 统一搜索
这样每个人的 Hermes 行为一致，不用一个个去教。
09
PART
速查表
CHEATSHEET
把这篇里最常用的东西收一下，存着翻。
CLI 命令
命令 说明 hermes plugins list 查看所有插件 hermes plugins list --enabled 只看已启用 hermes plugins list --user 只看用户装的 hermes plugins install 安装插件 hermes plugins install --enable 装完直接启用 hermes plugins enable 启用 hermes plugins disable 禁用 hermes plugins remove 卸载 hermes --safe-mode 安全模式排查冲突
config.yaml
...yaml
plugins:
enabled: [disk-cleanup, security-guidance, langfuse]
disabled: []
开发规范
规范 说明 入口函数 register(ctx: PluginContext) 工具返回 必须是 JSON 字符串（ json.dumps() ） 参数 必须有 **kwargs 参数标注 必须用 type hints 元信息 plugin.yaml 必需
钩子时机
钩子 触发时机 session_start 会话开始 pre_llm_call 调 LLM 前 post_llm_call LLM 响应后 pre_tool_call 执行工具前 post_tool_call 工具执行后 message_send 发送消息时
///
LAST
写在最后
WRAP UP
Plugins 用起来就这几件事：分清它跟 Skills 的差别，装的时候只装信得过的来源，写工具的时候三条硬规范别漏，出问题先 --safe-mode 缩到最小集排查。
把内置那几个通用的（disk-cleanup、security-guidance、langfuse）先开上，再按需加 Provider 和搜索，基本就够绝大多数场景了。想接新平台、做点定制逻辑的，照着最小示例自己写，门槛没你想的那么高。
插件选对了，AI 才真的“无所不能”
我是 空闲周期，热衷于分享 AI 工具实战干货。这是 Hermes 教程系列第 9 篇，前面几篇把安装、斜杠命令、模型配置、技能系统、Memory、Cron 都打通了，想从装到用一路通关的，去主页翻翻，凑齐一整套。
下一篇讲点更进阶的——多 Agent 编排，让几个爱马仕分工协作干大活。踩到新坑了留言说一声，我更新进来。觉得有用点个在看，转给同样在折腾 Hermes 的朋友——插件选对了，AI 才真的“无所不能”。
既然看到这里了，如果觉得有用，随手点个赞、在看、转发三连吧。
点赞在看转发
THANKS FOR READING