Hermes 不让你改源码,这才是它最好二开的地方

上周有人问我：Hermes 能不能改成我们自己公司用的？

我说能，但你别动它源码。

他以为我在开玩笑。26 万 star，MIT 协议，fork 一下想怎么改怎么改，凭什么不能动源码。

我把官方开发者文档翻给他看。里面有一句写得很硬：替换或包装核心函数、方法、模块属性、私有字典，不属于受支持的扩展点。

不是"不建议"，是"不支持"。插件想进官方目录，有一项专门检查叫 no core override，命中直接拒。

那想加功能怎么办？

我把开发者文档从头翻到尾，发现它把"改"拆成了 14 个有名字的口子。不用 fork，写一个目录就能上线。

一、14 个口子，各管一件事

官方文档开头有张对照表，左边写"你想加什么"，右边写"去看哪一页"。

我数了一遍，能挂东西的地方有 14 个。挑几个最常用的：

剩下的还有图像生成、视频生成、联网搜索、云浏览器、子代理派活、终端环境、密钥管理、Web 控制台。每一格都有独立文档页，不是一句"自行扩展"打发你。

这里有个反直觉的点：口子多，不等于都该用。

文档自己也在提醒：如果对方已经有 MCP server，config.yaml 里声明一下就行，根本不用写插件。写代码之前先问一句——这事能不能用 MCP 或者一个 skill 解决？

能，就别写。

二、一个插件，就是四个文件

这是我觉得它设计得最克制的地方。

ounter(lineounter(lineounter(lineounter(lineounter(line~/.hermes/plugins/你的插件/├── plugin.yaml    # 我是谁，提供什么├── __init__.py    # register(ctx)，唯一入口├── schemas.py     # 给模型看的工具说明└── tools.py       # 真正执行的代码

plugin.yaml 里写清楚提供哪些工具、挂哪些钩子。__init__.py 里只做三件事：注册工具、注册钩子、按需注册技能。

有个细节值得说：钩子回调必须收 **kwargs。

这不是代码风格，是契约。官方承诺新数据只以关键字字段追加，绝不改已有字段的位置和含义。你收 **kwargs，上游加字段时你就不用改签名；你写死参数列表，上游一加东西你就得跟着改。

写完自检三条命令：

ounter(lineounter(lineounter(linehermes plugins doctor . --cihermes plugins validate . --install-depshermes plugins list

doctor 会用临时目录把插件真加载一遍，报钩子名写错、回调不收 **kwargs、声明的工具和实际注册的对不上。validate 跟官方目录的 CI 是同一套检查。

一个人写插件，最怕的不是写不出来，是写完不知道对不对。这三条命令把"对不对"变成了秒级反馈。

三、个人最该盯的三格

14 个口子里，我认为只有三格值得个人投入。

第一格：记忆后端。

Hermes 自带 MEMORY.md 和会话检索，够用但很浅。Memory Provider 允许你把记忆换成任何后端——向量库、图数据库、你自己的服务。

为什么值钱？工具谁都能抄，记忆是数据。用户在你这里存了半年对话，迁移成本高得离谱。

代价是坑多。官方文档明确写了四条：sync_turn 必须非阻塞、必须用 spawn_context_thread 而不是裸线程、路径只能用传入的 hermes_home、每次注册要 new 一个实例。裸线程那条最阴——profile 隔离靠 contextvars，裸线程上下文是空的，会静默写进默认 profile 的库，还不报错。

第二格：国内消息平台。

官方列了 21 个以上平台，微信、企业微信、QQ、钉钉、飞书、元宝都有。

但仔细看通道就明白了：个人微信走 iLink Bot API，QQ 走官方机器人开放平台，企业微信走 AI Bot WebSocket。全都有资质门槛。

个人开发者拿不到资质，就只能做桥接。这是需求，也是合规风险，做之前先想清楚边界。

第三格：整套发行。

这个技术含量最低，变现最快。

distribution.yaml 加一份 SOUL.md、几个 skill、几条 cron，push 到 git，别人一条命令装完：

ounter(linehermes profile install github.com/你/你的agent --alias

你的价值不在代码，在"这套提示词和技能我打磨了三个月"。发行包里永远不会带 memories/、sessions/、.env、auth.json，安装器会硬剔除；cron 任务装进去默认是暂停的，要用户手动恢复。这是安全设计，别想着绕。

四、三个会返工的坑

没有 pip 包。 官方不发布 wheel，也不发布 sdist。想把它当库用，必须 clone 仓库、激活它自己的环境、在里面跑你的程序。你的部署单元不是"一个包"，是"一份 checkout 加一个 venv"。

外部记忆后端全局只能一个。 想同时接两个，只能自己在上层聚合。

依赖没有冷静期。 Hermes 给自己的依赖设了 3 天"发布冷静期"，昨天的包今天进不来。你的插件没有这层保护，上游昨天发的包你今天就能装。所以每个依赖自己加上界，别写裸 >=。

还有一条不算坑，但要有心理准备：这个项目现在挂着 52,471 个 open issue，周更节奏。插件契约承诺加字段不删字段，但内部模块路径不是契约——2026 年 9 月那次模块拆分，把旧 import 路径全删了，还在用旧路径的插件直接报 ImportError。

结论就一句：只用 ctx 和文档里的抽象基类，别 import 内部模块。

落地清单

1. 先别写代码，去翻那张"你想加什么"对照表，确认你要的东西是不是已经能用 MCP 或 skill 解决。
2. 真要写，抄官方那个 calculator 例子，四个文件跑通 hermes plugins doctor . --ci，再换成你自己的业务逻辑。
3. 写完在干净机器上装一遍，确认 requires_env 声明的变量是对的——你自己机器上早就配好了，感觉不到缺。

照这三条走，你能省掉最贵的那段：花两周写了个插件，最后发现官方本来就有，或者装到别人机器上跑不起来。

参考资料

备注：本文所有接口名、目录结构、规则条款均来自官方开发者文档逐页检索，代码未在本机运行——本机没有 Hermes 环境。文中"工作量""值不值"是判断，不是实测。Star 与 issue 数取自 GitHub API 2026-11-03 快照，会变。

转给那个一上来就想 fork 开源项目的朋友。