交接须知

这份文档只回答一个问题：你怎么加的东西，才能被别人接住。

先说清楚它为什么存在。这个站收的都是「作品」——作者做出来是为了爽，不是为了维护。于是同类项目各自长一套，一个项目裂成上百个变体，八成功能重复，而且因为底层不同，重复的还互相不兼容。

插件是把「重复」变回「复用」的最小单位。主体只做连接和分发，功能全部沉到插件里——因为功能会变，会有人想改，会有人想要不一样的。谁写的插件，署名就是谁的。

一、插件到底是什么

插件不是「扩展包」，也不是「皮肤」。它是一段在主体的某个时刻被叫起来、拿到当前上下文、返回一个动作的代码。

它由主体叫起来，不是自己跑。消息到达、定时触发、有人 @ 它——这些时刻由主体判断，插件只是被告知。

它拿到的是一份已经归一化过的上下文。原始协议报文长什么样，插件不该知道。这是整个架构里最重要的一条：假设只允许存在一个地方。

它返回的是「想做什么」，不是「已经做了什么」。想发一条消息、想存一个值、想调一次模型——由主体去执行。这样权限才管得住。

因为「升级之后装好的东西还能跑」这件事，靠的就是这一条。

上游改一个字段，如果每个插件都直接读那个字段，那这个假设就同时散落在几十个文件里，改一次上游要改几十处，而报错只会出现在离根因最远的那一个。

所以：协议报文怎么变，由主体那一层翻译；插件永远只读归一化之后的上下文。插件越多，这一条越值钱。

三样东西，缺一样就接不上。

一个入口。插件放哪个目录、入口函数叫什么、怎么注册。每个项目的具体写法不一样，看它交接文档里的「插件怎么被加载」。

一组权限。读消息、发消息、存数据、联网、管理权限。写清楚，装的人要看见这几行字才敢按下去。

一份依赖。你基于哪个上游、哪个版本区间写的。写不清楚，升级时第一个坏的就是你。

同样重要的是「不需要」什么：不需要自己实现协议连接，不需要自己实现记忆，不需要自己管配置文件。主体已经有的能力，插件不要重写一遍——重写的那份一定和主体打架。

先看这个项目有没有人做过。项目页下面有插件列表和搜索，按功能搜一遍。有人做到一半，你去接手比另起一个强。

把交接文档整段贴给你的 AI。项目页最上面那一块，点「复制全文」。里面写了技术栈、插件怎么接、什么不能碰。

说清你要加什么。「让它在被骂的时候回一句」比「优化对话体验」有用一百倍。

按上面三样声明。入口、权限、依赖。写不全，别人装不上。

本地跑通再交。装一遍、触发一次、看到效果。没跑过的插件，交上来只会变成别人的坑。

四样：插件本体、权限声明、依赖的上游版本、一个联系方式。项目页最下面有上传入口，拖进去就行。

如果你改的是主体而不是插件，那要多一样：哪里和原版不兼容。这一条最常被跳过，也最常让别人升级失败。

因为不这么做的结果，我们都见过：一个人改完没交代，下一个人接不上，只好另起一个；再下一个人又接不上，再另起一个。三年之后有三十个版本，每个都缺一半功能，谁也不敢动。

规范不是为了管你。是为了让你改的东西，能被下一个人接住。

字段会随几位作者的反馈调整。你有意见直接发 hi@dseasier.cn。