聊天窗口一打开,插件就该知道:Hermes 新增 on_session_open 钩子

早上九点,你打开 Hermes Desktop,接着昨天那个仓库的活干。你的记忆插件里其实存着昨天最后得出的结论——哪个接口一开始就配错了、哪个测试文件其实不用跑。可它并不知道“你回来了”:它只能等你在输入框里敲下第一句话,那条消息走到模型前面的时候,才第一次看见这个会话。
更别扭的是另一种情况。你只是打开窗口看了一眼昨天的对话,翻了两屏,关掉。插件从头到尾没收到任何通知,因为它等的那条新消息永远不会来。
插件作者对这件事的反应通常很一致:那就轮询吧。定时去读会话目录,看有没有新文件,再看文件的修改时间。能用,但很难看——它既不知道你是不是真的回来了,也不知道你回来的是新会话还是旧会话。
on_session_open 就是来解决这个问题的。
它比 on_session_start 早了整整一轮
Hermes 早就有一个长得很像的钩子:on_session_start。名字几乎一样,触发点差得很远——那个是在第一轮 agent 回合里触发的,也就是真的有一条用户消息要被处理了才触发。
所以你重开一个旧会话时,on_session_start 一次都不会响。哪怕你接着聊,它响的也是“这一轮开始了”,而不是“这个会话被打开了”。
on_session_open 的定位是后者:会话被创建或被打开的那一刻,早于模型看见任何内容。文档里写得很直白——它是给你“为一场对话先做好准备”用的,比如记忆插件先把最近 20 条笔记捞进缓存,或者状态栏立刻把这行会话标成“已打开”。
触发点长什么样
具体什么时候响,值得说细一点,因为它决定了你写出来的代码会不会重复执行。
它由网关里的权威会话层触发:一个客户端连接接上了一个它原本没有接着的本地会话时,响一次。几个边界因此很清楚:
- 一次打开只响一次。客户端已经在读这个会话,只是又轮询了一次快照——不响。断线重连回来——也不响。所以你不需要自己维护一套去重集合。
- 两个客户端打开同一个会话,响两次。这是两个真实的打开,插件该知道有两个人来了。
- 会话创建(新开一个空会话)和会话恢复(打开一个已经有内容的会话)都算,靠
reason区分:会话里还没有消息时是create,一旦有了对话就是resume。 - 它跑在拥有这个会话的 profile 里。一个网关服务多个 profile 时,每个 profile 的插件只会看见自己那几个会话——不会串台。
- 消息类平台不触发。Telegram、Discord 这些聊天窗口没有“打开”这个动作,它们的会话是由第一条消息开始的,那里继续用
on_session_start。
payload 很小,只有三个字段:session_id、platform(cli、tui、desktop、acp 之类)、reason(create 或 resume)。没有消息内容,没有用户输入——这是有意的,你不用为隐私担心。
写一个回调:先把缓存热起来
插件里的写法跟其他钩子一模一样,ctx.register_hook 注册即可:
# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}
def warm(session_id, platform, reason, **kwargs):
# 只在这里做“便宜”的准备工作:读文件、查本地索引、写状态
_cache[session_id] = load_recent_notes(limit=20)
def register(ctx):
ctx.register_hook("on_session_open", warm)
**kwargs 别省。钩子的字段以后可能会加,签名写死的人迟早会被一个新字段打成 TypeError。
同一份代码里最值得注意的一点是:它跑在网关里,不在客户端里。也就是说经典 CLI、TUI、Desktop 打开会话时,插件代码是由网关进程加载并执行的,客户端进程根本不碰插件。这既是安全边界,也解释了为什么你在日志里只会看到网关的 pid。
不想写 Python 也行。shell 钩子同样支持这个事件,配置里加一段就可以:
# ~/.hermes/config.yaml
hooks:
on_session_open:
- command: "~/.hermes/agent-hooks/session-open.sh"
timeout: 10
脚本从 stdin 收到一个 JSON,里面就是那三个字段。写一行审计日志、给某个本地服务发个通知,几行 bash 就够了。
调完之后记得测一下。hermes hooks test 支持这个事件,会用一份合成 payload 打一遍你配置的钩子,把解析出来的响应打给你看:
hermes hooks test on_session_open
五秒钟的时间预算,和一条不能忘的规矩
这里有个设计取舍值得你知道:打开会话这个动作不等插件,但会话的下一轮会等。
具体说,回调被扔到自己的线程上跑,所以你点开窗口的那一下永远是瞬间的。但这一轮真正开始处理之前,会等回调跑完——最多等 5 秒,或者 plugins.hook_callback_timeout(默认 30 秒)如果设得更长就等更久。超过这个时间,这一轮照常往下走,回调继续在后台跑。
plugins.hook_callback_timeout 设成 0 表示永不放弃回调线程。即便如此,这一轮也只会等 5 秒——那个设置的意思是“别杀掉慢回调”,不是“允许它拖住对话”。
规矩因此很直白:回调要快。读本地文件、查一次 SQLite、往内存里塞点东西,这些都在预算内。在回调里发一次 LLM 请求、拉一个远程 API、跑一遍全仓库扫描——那你就是在给用户的开场白加延迟。
还有两个细节:
- 如果一个会话的回调还在跑,而你又打开了同一个会话,新的打开会排在它后面合并成一次,等前一个跑完再带着最新一次打开的细节响一次。所以就算你的回调卡住了,也不会堆出十个线程。
- 这个 profile 加载的插件里没有任何订阅者,那就什么都不会发生——连线程都不起。
失败是开放的:回调抛异常会被记录并跳过,后面的回调继续跑,会话照开。
什么该放进来,什么别放
适合放进来的,基本是“会话还没开始,但我想先准备好”这一类:
- 记忆/知识库预热:把跟这个仓库相关的笔记、上次的结论先捞出来,第一条消息就能用上。
- 状态与提示:状态栏、外部仪表盘、审计日志——“谁在什么时候打开了哪个会话”是运维很想要的一条数据。
- 按会话隔离的凭据或工作目录:某些插件需要知道当前会话属于哪个项目,再决定用哪套配置。
- 清理上一轮的临时状态:新会话
create时把残留的草稿清掉,比重开会话时靠猜更可靠。
不适合的也很明确:
- 消息类平台上的“会话开始”(用
on_session_start)。 - 需要用户输入才能决定的事情——这一刻还没有用户输入。
- 任何超过几百毫秒的网络往返。
顺便提一句范围:--safe-mode 和 --ignore-user-config 启动的会话不会触发它,因为那些模式下插件本来就不加载。
现在能用吗
这个钩子是 2026 年 11 月 8 日合并进 main 的(PR #151120)。我查了一遍 v0.23.0 的发布范围——那个版本是 11 月 6 日发的,所以这个钩子不在 v0.23.0 里,属于 main 上的新代码,要等下一个版本才会随正式版到达。
更新(2026-11-10):这批改动已随 v0.23.1 发布(2026-11-09),
hermes update升级即可用。上文「不在 v0.23.0 里」仍然成立,v0.23.1 把缺口补上了。
如果你在跑 main,现在就能用。如果你在稳定版上,建议先把插件代码写好、用 hermes hooks test 把逻辑跑通,等升级后直接生效。
想在稳定版上做类似的事,目前还有两个更老的钩子可以用:on_session_start(第一轮开始时)和一些会话边界上的钩子,写法可以参考我们之前那篇会话被压缩、被删除时的插件通知。同一套钩子机制还能在模型调用前拦下整轮对话,见pre_llm_call 的拦截用法;所有支持的事件名和配置字段在命令参考里能查到。
一句话总结
on_session_open 补上的是一个很具体的空档:“会话被打开了,但还没有任何消息” 那一刻,插件以前完全是瞎的。现在它有了 session_id、platform 和 reason,还有五秒钟把该准备的东西准备好。写插件的人只要记住一件事——在这五秒里做便宜的事,贵的留给第一轮。