65 分钟过审 61 个插件:官方插件目录的批量收录到底在查什么


你写了一个 Hermes 插件,跑得挺好,想让别人也能一条命令装上。你去翻了官方文档,看到“提交一个 PR,加一个 plugin-catalog/<名字>.yaml”,然后你打开仓库的 Pull requests 页面,发现凌晨两点到三点之间,合并记录像瀑布一样滚过去——六十多条,全是插件条目。

第一反应大概是:这也太随机了,我的 PR 会不会淹没在里面?第二反应是:他们真的每一条都看了吗?

这两个问题都有确切答案,而且答案就写在仓库的准入规则里。

一小时 61 条:这是设计好的,不是失控

先把事实摆清楚。11 月 8 日 02:14 到 03:19(UTC),NousResearch/hermes-agent 合并了 61 个插件目录条目。它们标签高度一致:全部带 ci-reviewed,绝大多数带 comp/plugins,一小部分是 type/feature + P3。

这不是有人熬夜点鼠标。准入规则第 5 条明确允许两条路径:

  1. 插件仓库的所有者或主要贡献者自己提交;
  2. 维护者从一批已审阅的社区插件里批量收录——“every pin validated and scanned at the pinned commit”。

也就是说,批量收录是官方承认的工作方式,但“批量”只体现在 PR 的节奏上,不体现在检查的密度上。每一条仍然要过同一套门。

顺带说一句:被批量收录的作者并不是失去控制权。规则写得很清楚,作者本人发 PR 要求调整或撤下自己的条目,会被接受;之后的 SHA 升级(规则 4)也仍然是作者或维护者发起的 PR。

批量收录里,每条到底跑什么

如果你只想知道“我要准备什么”,这一段就是清单。官方的本地命令和 CI 跑的是同一个检查:

hermes plugins validate /path/to/your-plugin --install-deps

它检查的不是“能不能跑”,而是一串很容易被忽略的东西:

  • plugin.yaml 清单与 requires_hermes 是否成立;
  • 插件能不能真的加载(在钉住的那个 commit 上);
  • 你声明的 capabilities(tools / hooks / middleware / env)与实际注册的是否一致——不一致直接失败,因为“悄悄多申请权限”被当成安全问题;
  • config_schema 与 requires_env;
  • Python 依赖是否落在 Hermes 的核心约束里;
  • 安装时的安全扫描(dangerous 直接挡,caution 变成警告留给评审读);
  • desktop surface 检查与 no core override 检查。

后面两条是这套目录最硬的价值观,值得单独说:桌面插件只能用 SDK(不许打补丁改渲染层或者原型),任何插件都不许在运行时覆盖 Hermes 核心(不许 AIAgent.<method> = ...、不许 sys.modules[...]、不许往核心模块的表里写)。理由在文档里写得很直接:两个插件打同一个缝,会静默地互相破坏;而核心每发一版,两边都可能一起坏。

对作者来说,最省事的心态是:不要“绕过去”,要“要一个钩子”。缺能力就开 issue,官方明确说了宁可加一个新钩子,也不愿意收录一个补丁式插件。

这批里两个边角修复,暴露了流程的真实摩擦

批量收录不只是“合并”这个动作,它会把平时见不到的边角磨出来。这次有两个。

一、8 个条目的作者仓库拒绝了维护者推送。 插件目录的 CI 要克隆作者仓库、在钉住的 commit 上跑校验。但有些作者的仓库配置了保护分支或权限策略,维护者推不进去(哪怕只是需要打一个标记)。于是这批里有一个专门的 PR(#150957)把这 8 个条目单独列出来处理。这不是技术问题,是协作问题——如果你想让自己的插件顺利被收录,别把维护者的自动化挡在门外。

二、规则 17 的归档扫描把数据文件当成了载荷。 规则 17 禁止“无法扫描的可执行载荷”,实现方式是扫插件的归档包。这批里有个插件(dike)钉的是一份数据语料 tarball:里面 34k 个 .json、两个 .ttl、还有 .jsonld 上下文文件。扫描器不认识 .jsonld 和 .ttl,于是把它判成了不可扫描载荷,条目校验失败。

修复(commit 11b2b4414f)的理由很朴实:JSON-LD 和 Turtle 都是纯文本的 RDF 序列化,跟已经在白名单里的 .json、.xml 一样可审阅——它们不是载荷。这个修复的措辞值得一读,因为它体现了这套规则的态度:规则是为了“能被审阅”,不是为了“看起来整齐”。

如果你想被收录,这七件事比写代码更重要

按文档的顺序,实际评审最常打回的都是准备工作的疏漏,而不是功能不够酷。

一、钉死 40 位 commit SHA。 分支、tag、短 SHA 都会被 loader 直接拒绝。安装时会 clone 你的仓库并 checkout 到那个确切的 commit——这就是整个信任模型。

二、不要自带更新器。 规则 3 禁止插件自己下载替换文件(in-app “check for updates”、签名下载器、远端加载 plugin.js)。一个自更新器意味着已安装的副本会跑到“没人审过的 commit”上。想更新?发一个 SHA bump 的 PR,用户跑 hermes plugins update <name>。

三、声明的能力必须和现实一致。 多声明是浪费,少声明是安全问题。这条没有商量空间。

四、用公共表面,别打补丁。 hooks、middleware、ctx.register_*、provider profile、Desktop SDK——就这些。缺失的能力去要,不要绕。

五、凭据只从 Hermes 拿。 规则 11 说得很细:requires_env 与 config_schema 里的 secret 用 agent.secret_scope.get_secret(NAME) 读(这样才尊重当前 profile,裸读 os.environ 在多 profile 下会拿到别人的 key);第三方 OAuth 客户端在 plugin.yaml 的 oauth: 下声明,用 hermes auth add <plugin>:<id> 登录;不许自己读 .env、auth.json、别的工具的登录态或者钥匙串。

六、把风险写出来。 规则 13 要求在网络调用、读取插件自身数据以外的内容、shell 命令、长驻后台进程、存储凭据这些行为上做披露,写在 PR 描述和 README 里。遥测必须 opt-in。评审会把这些整理成条目上的披露行——藏起来被发现的代价,比一开始写清楚大得多。

七、requires_hermes 要诚实。 它是 SemVer 下限(">=0.21.5"),不是日期,也不能高于当前版本。而且它是被强制执行的:用目录名安装时,版本不满足会直接拒绝;hermes plugins update 会把你按在当前 pin 上,直到 Hermes 升级。

收录之后你能得到什么

对使用者来说,价值在“按名字装、装到维护者读过的那个 commit”。这些命令是入口:

hermes plugins search <关键词>
hermes plugins browse
hermes plugins show <name>
hermes plugins install <name>
hermes plugins capabilities <name>

show 会给出条目详情(包括它 emits 和 listens 的事件),capabilities 对比“声明的”和“实际授予的”权限——装之前扫一眼,比事后惊讶好。

目录本身的信任模型(人审 + SHA 钉死 + removed.yaml 黑名单)我在 插件目录上手那篇 里讲过;CI 门禁那些更刁钻的拒绝理由(重命名条目、逃出钉住目录的 subdir、指向 tag 对象的 sha)在 这篇讲 CI 门槛的文章 里有具体案例。这篇补的是第三块:批量收录这种工作方式,以及它对作者意味着什么。

状态

这批合并发生在 11 月 8 日的 main 上,不在 v0.23.0 里——但插件目录条目是数据文件,跟 release 的节奏没关系:只要你的 Hermes 能访问目录,新条目就能被搜到、被安装(能不能装成功取决于条目里的 requires_hermes 和你的版本)。

如果你正在准备自己的条目,站内的 hermes plugins 命令参考 有完整的子命令清单,别只记住 install 一个。