Featured image of post Hermes Agent 扩展篇:Skills 管理、插件开发与 Cron 脚本任务

Hermes Agent 扩展篇:Skills 管理、插件开发与 Cron 脚本任务

讲解 Hermes Agent 的三种扩展方式:用 SKILL.md 组织技能并禁用用不到的内置技能,用插件挂载网关钩子或替换内部方法来补上游缺失的能力,以及用 Cron 的脚本模式跑不经过模型的定时任务,并整理 PATH 不展开等实际踩坑。

-- 次浏览
-- 条评论

写在前面

这是 Hermes Agent 架构系列的第五篇,讲能力层。整体分层见 Hermes Agent 自托管架构总览。

Hermes 有三种扩展方式,解决的问题完全不同:

方式本质适合做什么
Skills给模型看的说明书教 Agent 怎么完成某类任务
Plugins运行在网关进程里的 Python 代码修改或补充 Hermes 自身的行为
Cron定时触发器定时让 Agent 干活,或定时跑脚本

一个简单的判断:需要模型理解和决策的,写 Skill;需要改变 Hermes 程序行为的,写插件;需要按时间触发的,用 Cron。

Skills:给 Agent 的操作手册

技能的格式

一个技能就是一个目录,核心是 SKILL.md,开头是 YAML 元数据,后面是给模型读的正文。以内置的 sdlc-review 为例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
---
name: sdlc-review
description: Review Kanban handoffs and route verified outcomes.
version: 1.1.0
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [kanban, review, quality, verification]
    category: devops
    requires_toolsets: [kanban]
---

# SDLC Review Skill

## When to Use
...

description 最关键:Agent 根据它判断什么时候该加载这个技能。正文只有在被使用时才会读入,所以写在正文里的细节不占日常上下文,写在 description 里的每个字每轮都会带上。

技能按分类目录存放,比如 skills/devops/、skills/productivity/,分类目录下可以放一个 DESCRIPTION.md 说明这一类技能的用途。

禁用用不到的内置技能

Hermes 自带大量技能:Notion、Obsidian、PPT、Excel、各种 GitHub 工作流、音视频生成等等。全部开着有两个问题:每个技能的描述都会进入系统提示词,消耗上下文;技能越多,Agent 越容易在不该用的时候误用。

我的做法是把用不到的全部禁用:

1
2
3
4
5
6
7
8
9
skills:
  disabled:
    - airtable
    - apple-notes
    - notion
    - obsidian
    - powerpoint
    - xlsx
    # ……共禁用了 89 个

被禁用的技能文件还在,随时可以从列表里删掉重新启用。上一篇提到的 Profile 也各有自己的 skills/ 目录,所以还能做到"同一个技能只给 dev 用,不给 home 用"。

技能的安装和管理使用 hermes skills,例如 hermes skills search、hermes skills install、hermes skills list。Hermes 对技能的每次修改都会记录在 .curator_backups/ 中,改坏了可以找回。

Plugins:修改 Hermes 自己的行为

技能只能影响模型怎么想,影响不了 Hermes 程序本身怎么运行。比如"每天自动切换会话"“某个平台发送失败时换一种方式重试”,这些只能写插件。

插件的结构

插件放在数据目录的 plugins/ 下,一个插件一个目录:

1
2
3
4
5
plugins/hermes-session-reset-policy/
├── plugin.yaml     # 元数据
├── __init__.py     # 入口,提供 register(ctx)
├── README.md
└── tests/

plugin.yaml 声明插件信息和用到的钩子:

1
2
3
4
5
6
name: hermes-session-reset-policy
label: Session Reset Policy
kind: standalone
version: 0.3.0
provides_hooks:
  - pre_gateway_dispatch

__init__.py 中的 register(ctx) 是入口,在这里注册钩子:

1
2
def register(ctx):
    ctx.register_hook("pre_gateway_dispatch", _maybe_reset)

在 config.yaml 中启用,然后重启网关:

1
2
3
4
plugins:
  enabled:
    - hermes-session-reset-policy
    - wecom-media-proactive-fallback

我目前用了两个插件,正好代表两种典型写法。

例一:用钩子补回被移除的能力

上游 v2026.9.11 移除了按时间自动切换会话的定时器,session_reset 配置从此不再生效。在聊天软件里用 Agent,没有自动切换意味着会话越积越长。

社区插件 hermes-session-reset-policy 把这个能力补了回来,安装方式:

1
hermes plugins install https://github.com/fastfinge/hermes-session-reset-policy.git

它的设计很值得学习:

  • 不用定时器:在用户发来新消息、正式分发之前检查要不要重置。没有后台线程,也不会在没人说话时写数据库。
  • 复用官方的重置流程:不自己删会话,而是调用和手动输入 /new 完全相同的代码路径,缓存清理、钩子通知、状态库更新都由 Hermes 自己完成,结果和手动重置一致。
  • 不打断进行中的任务:如果会话正在执行任务,就先不重置。
  • 只看用户消息的时间:Cron 和后台消息不会让会话"保持活跃",也不会触发重置。

这就是插件的理想形态:只在边界上插一个判断,具体的事交给 Hermes 已有的机制去做。

例二:替换内部方法修复平台问题

第二个插件 wecom-media-proactive-fallback 是我让 Hermes 自己写的,解决企业微信的一个问题:

  • 企业微信机器人回复消息时,优先使用"被动回复"(带着收到消息时的 req_id 回复)。req_id 过期后会报错 846604。
  • Hermes 发送文字时,遇到这个错误会自动改用"主动发送"接口重试;但发送图片和文件时没有这层回退,直接失败。
  • 结果是 Cron 任务要发送文件时,会被标记为发送失败。

Hermes 没有提供对应的钩子,平台代码在镜像里也不该直接修改(升级会被覆盖)。插件的做法是在 register 时替换掉内部方法:

1
2
3
4
5
6
7
def register(ctx):
    from plugins.platforms.wecom.media import WeComMediaMixin

    current = WeComMediaMixin._send_media_source
    if getattr(current, "_wecom_proactive_media_fallback", False):
        return  # 已经替换过,避免重复安装
    WeComMediaMixin._send_media_source = _send_media_source_with_fallback

新方法的逻辑和文字发送保持一致:被动回复失败时,回退到主动发送接口。

这种写法(monkey patch)很直接,但要清楚代价:它依赖 Hermes 的内部方法名和参数,上游一改就可能失效甚至出错。插件目录里带了测试 tests/test_fallback.py,升级 Hermes 后应该先跑一遍;等上游修复了,就应该删掉这个插件。

截至 v0.23.0,上游做了部分缓解:已知某个会话的流式回复正在进行或已经过期时,发送媒体会直接改走主动接口。但缓存的 req_id 本身过期、被动回复返回 846604 时,媒体发送仍然只报错不回退,所以这个插件暂时还需要保留。

Cron:定时任务

Hermes 内置的 Cron 有两种用法:

  • Agent 模式:定时给 Agent 发一段提示词,可以附带技能,让它去完成任务并把结果发到指定渠道。
  • 脚本模式:定时运行 scripts/ 下的脚本,加上 --no-agent 就完全不经过模型。

我现在的定时任务基本都是脚本模式。以每日磁盘检查为例:

1
2
3
4
5
hermes cron create '30 9 * * *' \
  --name 'host disk usage daily alert' \
  --script disk_usage_alert.py \
  --no-agent \
  --deliver local

保存在 cron/jobs.json 里的关键字段:

1
2
3
4
5
6
7
8
9
{
  "name": "host disk usage daily alert",
  "script": "disk_usage_alert.py",
  "no_agent": true,
  "schedule": { "kind": "cron", "expr": "30 9 * * *" },
  "deliver": "local",
  "last_status": "ok",
  "failure_streak": 0
}

为什么用脚本模式

磁盘检查这种事,规则完全确定:超过 90% 就告警,没超过就安静。让模型来做反而更慢、更贵,还可能不稳定。脚本模式的约定也很简单:

  • 脚本输出为空,就什么都不发。
  • 脚本自己负责告警(我的脚本直接调用企业微信群机器人的 Webhook),所以 deliver 设为 local,结果只留在本地记录中。
  • 脚本退出码非 0,Cron 会记录失败,failure_streak 计数加一,可以用 hermes cron runs 和 hermes cron incidents 查看。

踩坑:脚本里的 PATH 不会展开

这个任务上线后第一次就失败了,hermes cron runs 里记录的错误是找不到 df 命令:

1
2
3
4
5
6
Script exited with code 1
...
  File "/opt/data/scripts/disk_usage_alert.py", line 58, in parse_df
    out = subprocess.check_output(["df", "-PTk"], text=True)
...
FileNotFoundError: [Errno 2] No such file or directory: 'df'

原因是 Cron 运行脚本时会把 Profile 的 .env 叠加到环境变量上。我在 .env 里写了类似 PATH=/some/bin:${PATH} 的配置,而 .env 中的 ${PATH} 是按字面量处理的,不会展开。结果 PATH 变成了一个无效值,系统命令全部找不到。

解决方法是在脚本中调用系统命令时写绝对路径:

1
2
# Cron 会把 Profile .env 中的 PATH 原样叠加,${PATH} 不会展开
out = subprocess.check_output(["/usr/bin/df", "-PTk"], text=True)

更彻底的做法是在 .env 里写完整的 PATH,不要依赖变量展开。

总结

  • Skills 教模型做事:description 写清楚何时使用,正文写怎么做;用不到的内置技能全部禁用。
  • Plugins 改程序行为:优先用钩子并复用 Hermes 已有流程;替换内部方法要配测试,并在上游修复后删除。
  • Cron 按时间触发:规则确定的任务用 --no-agent 脚本模式,注意 .env 中 PATH 不展开的问题。

到这里,Hermes 的部署、模型、接入、角色和扩展都讲完了。回到总览,可以再对照一遍各层之间的关系。