写在前面
这是 Hermes Agent 架构系列的第五篇,讲能力层。整体分层见 Hermes Agent 自托管架构总览。
Hermes 有三种扩展方式,解决的问题完全不同:
| 方式 | 本质 | 适合做什么 |
|---|---|---|
| Skills | 给模型看的说明书 | 教 Agent 怎么完成某类任务 |
| Plugins | 运行在网关进程里的 Python 代码 | 修改或补充 Hermes 自身的行为 |
| Cron | 定时触发器 | 定时让 Agent 干活,或定时跑脚本 |
一个简单的判断:需要模型理解和决策的,写 Skill;需要改变 Hermes 程序行为的,写插件;需要按时间触发的,用 Cron。
Skills:给 Agent 的操作手册
技能的格式
一个技能就是一个目录,核心是 SKILL.md,开头是 YAML 元数据,后面是给模型读的正文。以内置的 sdlc-review 为例:
| |
description 最关键:Agent 根据它判断什么时候该加载这个技能。正文只有在被使用时才会读入,所以写在正文里的细节不占日常上下文,写在 description 里的每个字每轮都会带上。
技能按分类目录存放,比如 skills/devops/、skills/productivity/,分类目录下可以放一个 DESCRIPTION.md 说明这一类技能的用途。
禁用用不到的内置技能
Hermes 自带大量技能:Notion、Obsidian、PPT、Excel、各种 GitHub 工作流、音视频生成等等。全部开着有两个问题:每个技能的描述都会进入系统提示词,消耗上下文;技能越多,Agent 越容易在不该用的时候误用。
我的做法是把用不到的全部禁用:
| |
被禁用的技能文件还在,随时可以从列表里删掉重新启用。上一篇提到的 Profile 也各有自己的 skills/ 目录,所以还能做到"同一个技能只给 dev 用,不给 home 用"。
技能的安装和管理使用 hermes skills,例如 hermes skills search、hermes skills install、hermes skills list。Hermes 对技能的每次修改都会记录在 .curator_backups/ 中,改坏了可以找回。
Plugins:修改 Hermes 自己的行为
技能只能影响模型怎么想,影响不了 Hermes 程序本身怎么运行。比如"每天自动切换会话"“某个平台发送失败时换一种方式重试”,这些只能写插件。
插件的结构
插件放在数据目录的 plugins/ 下,一个插件一个目录:
| |
plugin.yaml 声明插件信息和用到的钩子:
| |
__init__.py 中的 register(ctx) 是入口,在这里注册钩子:
| |
在 config.yaml 中启用,然后重启网关:
| |
我目前用了两个插件,正好代表两种典型写法。
例一:用钩子补回被移除的能力
上游 v2026.9.11 移除了按时间自动切换会话的定时器,session_reset 配置从此不再生效。在聊天软件里用 Agent,没有自动切换意味着会话越积越长。
社区插件 hermes-session-reset-policy 把这个能力补了回来,安装方式:
| |
它的设计很值得学习:
- 不用定时器:在用户发来新消息、正式分发之前检查要不要重置。没有后台线程,也不会在没人说话时写数据库。
- 复用官方的重置流程:不自己删会话,而是调用和手动输入
/new完全相同的代码路径,缓存清理、钩子通知、状态库更新都由 Hermes 自己完成,结果和手动重置一致。 - 不打断进行中的任务:如果会话正在执行任务,就先不重置。
- 只看用户消息的时间:Cron 和后台消息不会让会话"保持活跃",也不会触发重置。
这就是插件的理想形态:只在边界上插一个判断,具体的事交给 Hermes 已有的机制去做。
例二:替换内部方法修复平台问题
第二个插件 wecom-media-proactive-fallback 是我让 Hermes 自己写的,解决企业微信的一个问题:
- 企业微信机器人回复消息时,优先使用"被动回复"(带着收到消息时的
req_id回复)。req_id过期后会报错846604。 - Hermes 发送文字时,遇到这个错误会自动改用"主动发送"接口重试;但发送图片和文件时没有这层回退,直接失败。
- 结果是 Cron 任务要发送文件时,会被标记为发送失败。
Hermes 没有提供对应的钩子,平台代码在镜像里也不该直接修改(升级会被覆盖)。插件的做法是在 register 时替换掉内部方法:
| |
新方法的逻辑和文字发送保持一致:被动回复失败时,回退到主动发送接口。
这种写法(monkey patch)很直接,但要清楚代价:它依赖 Hermes 的内部方法名和参数,上游一改就可能失效甚至出错。插件目录里带了测试 tests/test_fallback.py,升级 Hermes 后应该先跑一遍;等上游修复了,就应该删掉这个插件。
截至 v0.23.0,上游做了部分缓解:已知某个会话的流式回复正在进行或已经过期时,发送媒体会直接改走主动接口。但缓存的 req_id 本身过期、被动回复返回 846604 时,媒体发送仍然只报错不回退,所以这个插件暂时还需要保留。
Cron:定时任务
Hermes 内置的 Cron 有两种用法:
- Agent 模式:定时给 Agent 发一段提示词,可以附带技能,让它去完成任务并把结果发到指定渠道。
- 脚本模式:定时运行
scripts/下的脚本,加上--no-agent就完全不经过模型。
我现在的定时任务基本都是脚本模式。以每日磁盘检查为例:
| |
保存在 cron/jobs.json 里的关键字段:
| |
为什么用脚本模式
磁盘检查这种事,规则完全确定:超过 90% 就告警,没超过就安静。让模型来做反而更慢、更贵,还可能不稳定。脚本模式的约定也很简单:
- 脚本输出为空,就什么都不发。
- 脚本自己负责告警(我的脚本直接调用企业微信群机器人的 Webhook),所以
deliver设为local,结果只留在本地记录中。 - 脚本退出码非 0,Cron 会记录失败,
failure_streak计数加一,可以用hermes cron runs和hermes cron incidents查看。
踩坑:脚本里的 PATH 不会展开
这个任务上线后第一次就失败了,hermes cron runs 里记录的错误是找不到 df 命令:
| |
原因是 Cron 运行脚本时会把 Profile 的 .env 叠加到环境变量上。我在 .env 里写了类似 PATH=/some/bin:${PATH} 的配置,而 .env 中的 ${PATH} 是按字面量处理的,不会展开。结果 PATH 变成了一个无效值,系统命令全部找不到。
解决方法是在脚本中调用系统命令时写绝对路径:
| |
更彻底的做法是在 .env 里写完整的 PATH,不要依赖变量展开。
总结
- Skills 教模型做事:
description写清楚何时使用,正文写怎么做;用不到的内置技能全部禁用。 - Plugins 改程序行为:优先用钩子并复用 Hermes 已有流程;替换内部方法要配测试,并在上游修复后删除。
- Cron 按时间触发:规则确定的任务用
--no-agent脚本模式,注意.env中PATH不展开的问题。
到这里,Hermes 的部署、模型、接入、角色和扩展都讲完了。回到总览,可以再对照一遍各层之间的关系。
