v0.23.1:一个 2 MiB 的上限,让你的插件目录悄悄停在了过去

周三下午,同事在群里甩来一个插件名,说“你装这个试试,特别好用”。你在终端里敲下安装命令,Hermes 回你一句:找不到这个插件。你以为是名字拼错了,又换了个写法,还是没有。打开网页一看,插件明明在目录里,版本号、仓库地址、说明一应俱全。
这不是网络问题,也不是你打错字。从 11 月 9 日起,官方发布的插件目录文件超过了客户端愿意接收的大小,而客户端在遇到“太大”时的处理方式是:不报错,不提示,安安静静地退回到你这个版本里自带的那份目录。你看到的、能搜到的,是发布那天封进安装包的快照。v0.23.1 干的事,就是把那个上限抬高,让线上目录重新被用起来。
这篇讲三件事:那个上限是怎么咬人的、为什么“静默”是这里最贵的部分、以及你现在怎么自己确认一遍。顺带把这次补丁窗口里其它值得知道的东西列出来。
先说结论:更新一下就好
hermes update
hermes update 之后,客户端读取上限从 2 MiB 变成了 16 MiB。线上目录现在可以正常加载,hermes plugins install 能看到新收录的插件、能拿到被重新钉过的当前版本,也能看到后来新增的“已下架”条目。
一个必须说清的前提:这个修复在客户端。停留在 v0.23.0 或更早版本的安装,仍然会退回自带目录,直到你更新为止。所以如果你身边有同事“就是搜不到某个插件”,先问他一句 hermes version。
那个上限是怎么咬人的
插件目录是一个公开的 JSON 文档,客户端启动安装或浏览时会去取它,读完之后在本地缓存 6 小时。文档有两种来源,优先级明确:
- 线上目录(
plugin-catalog.json),由官方站点发布,包含最新收录的插件、最新的版本钉(pin)和最新的下架清单; - 自带目录(随你的安装包一起发的那份),永远不会更新,只在你取不到线上目录时兜底。
取线上目录的代码里有一条大小检查,超过上限就直接判定为异常响应,抛错、记一条 debug 级日志、返回“没有线上目录”。上层的调用方看到“没有”,于是用了自带目录。整条链路上没有任何一处面向用户的提示。
11 月 9 日,这个文档的体积是 2,109,306 字节、1,268 个条目(平均一条约 1.7 KB),刚好越过 2 MiB 那条线。于是从那一天起:
- 新收录的插件,在你的机器上“不存在”;
- 已经收录但被重新钉到新提交的插件,你装到的是发布当天那个旧钉;
- 后来新增的“已下架/不再维护”条目你也看不到——这比前两条更麻烦,因为它意味着一个已经被判为不安全的插件,在你的机器上仍然显得可以装。
我刚刚量了一下现在线上的那份文档:1,380 个条目、2,310,445 字节。也就是说,即使你今天才更新,这个体积也已经越过 2 MiB 有 10% 了;上限不抬,问题只会越来越普遍。
为什么“静默”是这里最贵的设计
回头看,这个 bug 的技术含量并不高:一个常量写小了。真正难缠的是它的失败方式——它把所有错误都藏起来了。
这个设计本身是对的。插件目录取不到不该阻塞你安装插件:网络断了、站点挂了、DNS 抽风了,你仍然应该能用安装包里那份目录装东西。所以“任何失败都退回自带目录”是一条合理的兜底策略。
问题在于,“文档太大”和“我没网”被归成了同一类。前者意味着“你手上的目录已经过时了”,后者意味着“先将就一下,等会儿再试”。用户看到的行为一模一样,但需要的动作完全不同。于是这个 bug 活了整整一天多,直到有人注意到“新插件搜不到”,才顺藤摸到那个常量上。
这也是这类基础设施 bug 的共同点:它们不崩溃、不报警、不污染日志,只是让世界的某个部分悄悄变旧。你做对了所有操作,看到的结果却是错的。
现在发生了什么变化
改动只有一行常量的量级,但代码里那段注释值得抄下来,因为它把边界说清了:
- 上限从
2 * 1024 * 1024改成16 * 1024 * 1024; - 按当前条目平均体积估算,16 MiB 大约能装 9,000 个条目;
- 上限没有被取消。它仍然在那里,用来挡住一个恶意或损坏的响应,只是不再误伤正常增长。
同一个文件里还有几条相关的兜底规则,知道它们能帮你判断“我现在用的是哪份目录”:
| 规则 | 值 | 含义 |
|---|---|---|
| 正常缓存 | 6 小时 | 6 小时内重复调用不会重新下载 |
| 陈旧缓存可用上限 | 24 小时 | 超过 24 小时的旧缓存会丢掉条目,只保留下架清单 |
| 失败记忆 | 60 秒 | 一次取失败后 60 秒内不再重试,避免拖慢每次调用 |
| 请求超时 | 5 秒 | 单次取目录的网络超时 |
怎么自己确认一次
想知道你的机器现在用的是哪份目录,最直接的办法是看行为:装一个最近才收录的插件,看它能不能被找到。命令参考页 hermes plugins 里有完整的子命令列表。
更稳的做法是养成两个习惯:
- 遇到“插件搜不到”时,先跑
hermes version,确认客户端版本够新,再看是不是目录问题; - 看到某个插件的行为和你预期的版本不一致时,别急着怀疑插件本身,先确认客户端拿到的是不是线上钉。
如果你之前看过我们那篇插件目录是怎么工作的,可以把这次的修复当成那条规则的一个直接后果:目录是“数据”,不是“代码”,数据的增长会反过来压到客户端的假设上。同一个道理也适用于插件公开 API 的边界——接口稳定了,数据规模才会稳定增长,而客户端必须为这个增长留出空间。
这个窗口里还有什么
v0.23.1 是一个补丁版本,它把 v0.23.0 之后合并的 618 个 PR 打成一个稳定版本,供 CLI 与安装器、Microsoft Store 应用、Docker 和 Hermes Cloud 使用。官方在这个节点上的测量口径是:自 v0.23.0 以来 2,578 次非合并提交、2,781 个文件变更(+151,690 / −62,595)、409 个 issue 关闭。
官方在发版说明里明确写了一句:这个窗口里还有一批功能是“故意不在这里展开”的,完整的策划型发版说明会随 v0.24.0 一起发布。它点名提到的包括:
- TUI 与经典 CLI 的 Esc 回退(取代原来的回退列表选择器);
- 不依赖桌面端也能跑的群聊,并且可以坐进来自其它电脑的机器人;
- 保存的 gateway 连接在桌面端与 Webapp 之间共享;
- 应用内浏览器用你真实的浏览器配置登录,并从地址栏直接填充已保存的登录信息;
hermes gateway attach,供本机客户端接入;hermes clipboard image --json;- 一批新的插件 API:会话级环境值、插件 JSON-RPC 方法与事件、
llm.oneshot辅助任务、压缩后保持稳定的conversation_id、gateway 的on_session_open钩子、post_curator_run钩子; - 更快的历史记录与 handoff 读取,以及一大批新的插件目录条目。
这些我们大多已经单独写过:Esc 回退那套见回退与改写的用法,插件目录批量清扫的机制见目录条目是怎么被批量更新的,v0.23.0 的整体变化见v0.23.0 发版说明。
升级
# CLI
hermes update
# 或者重跑安装器
# Docker / Hermes Cloud
# 镜像标签:nousresearch/hermes-agent:stable
Microsoft Store 版通过商店更新;用安装器装的桌面端这次没有变化,会跟着下一个打包版本走。
升级之后建议顺手做一件事:装一个你之前“搜不到”的插件,验证目录确实恢复了。如果还是搜不到,再看 hermes plugins list 的输出和客户端版本——这时候问题通常在插件名或仓库状态上,不在目录缓存上。
完整版本说明见v0.23.1 发版页。