插件import了核心内部模块?Hermes 现在有一份公开的"可引名单"


你的插件写了三个月,用户用得挺顺。某天 Hermes 发了个新版本,用户升级完打开一看:插件加载失败,报 ImportError。你去翻升级日志,没有一条提到你的插件;再翻代码,问题出在你半年前随手写的一行 from hermes_cli.cli_config_load import _parse_service_tier_config——那个内部函数被挪位置了。

这类事故最难受的地方在于:它在开发的那一刻完全没有报错。 你的插件装得上、跑得通、测试也绿。这种“未来的定时炸弹”,就是这次改动想提前暴露出来的东西。

私有 import 为什么迟早会炸

Hermes 有一道运行时检查,叫“核心覆盖”(core override):插件不能在运行时把核心模块里的函数换掉。但那道检查管的是“替换”,不是“引用”。你去 import 一个内部模块,检查是过的——然后你就把自己挂在了别人的私有实现上,而私有实现没有兼容性承诺:它可以改名、可以挪文件、可以在某个重构里彻底消失。

对插件作者来说,这类耦合的代价是延后兑现的;对审核者来说,它又很难在几百行代码里靠肉眼发现。所以真正需要的是一个静态的、能机械判定的边界:你引用的东西,在不在公开名单里。

名单从代码里搬出来了

之前这份名单是写死在 hermes_cli/plugin_validate_private_imports.py 里的一个 frozenset。它能用,但插件作者看不到——你只能提交、等 CI 告诉你哪一行有问题。

11 月 5 日的那次改动把名单原样搬进了 hermes_cli/data/plugin_api.json(它已经作为包数据随发行版一起发出去),校验器读这个文件;同时新增了一个生成脚本,用同一个文件渲染出文档页 developer-guide/plugins/public-api.md。更关键的一点:如果文档页和 JSON 不同步,测试会失败。 也就是说这份清单不可能悄悄漂移——改名单必须同时改文档。

一天之后,这份名单又多了第一条真正属于“插件该用”的条目:agent.redact.redact_sensitive_text。这个后面单独说。

三种 import,怎么判定

规则本身很短:

  • 名单里的整模块(如 agent.memory_provider):允许该模块,以及它下面所有不以 _ 开头的名字。
  • 名单里的单名(如 hermes_cli.auth_model_picker:prompt_model_selection):只允许那一个名字。
  • 名单外的 Hermes 模块:警告,不阻断。

不阻断是刻意的:这是准入门禁(catalog rule 9,“只用公开接口”)的提示,不是编译器。插件仍然装得上、跑得起来,只是审核者和作者都能看到“这里将来可能碎”。

另外四种情况永远不会被标记:标准库、第三方包、插件自己的模块,以及写在 if TYPE_CHECKING: 里的 import。最后这条很实用——类型注解需要 import 内部类型时,用 TYPE_CHECKING 包起来就是干净做法。用 importlib.import_module("hermes_cli.xxx") 这种字符串写法也一样会被查出来,不要以为换个写法就绕过了。

警告长什么样

校验器输出的形式是 相对路径:行号 模块[.名字],比如:

myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config

一个细节值得知道:报告会先把每个不同模块的第一次出现排在前面,再排其余位置。所以名单被截断的时候,你看到的仍然是“我到底碰了几处内部实现”的全貌,而不是同一个模块的十行重复。

CI 里可以加 --json 拿机器可读的结果;要连依赖一起装好再做能力探测,用 --install-deps(catalog 的 CI 门禁就是这么跑的)。

新进名单的那个函数:redact_sensitive_text

这条值得单独讲,因为它回答了一个插件作者经常遇到的问题:我要把用户文本发给模型,怎么先脱敏?

以前的做法是 from agent.redact import redact_sensitive_text,能跑,但校验器会警告你——它是私有的。现在它是公开 API 了,插件可以放心用:

from agent.redact import redact_sensitive_text

text = redact_sensitive_text(user_text, force=True)

为什么是“先脱敏再发”而不是给 ctx.llm 加一个 redact= 参数?因为插件可能需要对同一段文本做多次处理(切片、拼接、拼进提示词),只在最后一次调用上脱敏不够;手上有函数,任何位置都能先洗干净。

force=True 的语义要记住:它是那个“不给自己留后路”的开关。 默认情况下脱敏跟随操作员的 security.redact_secrets 设置——如果他关掉了脱敏,函数就原样返回。而“要发给模型的文本”属于安全边界,那里不该跟随这个开关,所以传 force=True。官方文档的说法是:在秘密绝不能离开本机的地方用它。

函数还有两个参数值得知道:code_file=True 会跳过针对源码的 ENV/JSON 赋值匹配(避免把 MAX_TOKENS=*** 这种测试夹具也改掉),file_read=True 用于“文件内容回给 agent”的场景,它把前缀型凭据(比如 ghp_…)换成一个不可复用的哨兵值,而不是首尾掩码——因为首尾掩码看起来像一把真的、被截断的密钥,agent 有可能把它写回 config.yaml。

怎么自查

hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json

先看警告里有没有 hermes_cli.、agent.、gateway.、tools. 这些核心包开头的 import。有的话,三条路:一是换成名单里的公开入口;二是如果只是类型标注,用 TYPE_CHECKING 包起来;三是确实需要内部能力,那就准备好跟着核心一起改——至少现在你知道自己踩在了哪里。

关于插件本身的准入、安装和目录结构,站内的 插件与 catalog 指南 更全面;如果你关心的是“敏感信息在链路上怎么被处理”,密钥脱敏的三条出口 那篇从另一个角度讲了同一套机制。

现在能用吗

名单搬迁和新条目都在 main 上(11 月 5–6 日),不在 v0.23.0 的标签里。也就是说你现在的稳定版里,hermes plugins validate 仍然用着写死在代码里的那份名单,redact_sensitive_text 仍然是私有 import。

更新(2026-11-10):这批改动已随 v0.23.1 发布(2026-11-09),hermes update 升级即可用。上文「不在 v0.23.0 里」仍然成立,v0.23.1 把缺口补上了。

但这件事对你的价值不依赖版本:现在就可以照着公开文档页的要求写插件。 名单里的东西才是稳的,名单外的都算借用——这个判断标准不会因为版本而变。

总结

这次改动没有加功能,它加的是可见性:把一条一直存在、但只有审核者心里有数的规则,变成一份能下载、能对照、能被 CI 检查的公开清单,并且用测试保证文档与实现同步。对插件作者来说,这是那种“以后少踩十个坑”的基础设施——它不会让你的插件跑得更快,但会让它在十次升级之后还能装上。