派生 AI 插件的发布链：从生成器到可执行门禁

我最早以为，派生一个 AI 插件应该是一件很机械的事：把源仓库里的能力目录复制到另一个宿主，再改几处配置。

真正进入发布链之后，我先撞上的并不是复制失败，而是另一种更麻烦的情况：目录确实复制过去了，制品看起来也很完整，但它还不能稳定地交给下一个人使用。

源能力依赖的入口在新宿主里不存在，某些命令没有完成适配，文档仍然在描述原来的环境，公开制品里还混进了不应该外发的路径或配置。

这让我后来更认可一种发布顺序：派生能力不能从复制目录开始，而要从生成、适配、完整性检查、公开边界和可执行交接一起设计。

相关公开资源

• Idea-Maglev/maglev：公开说明 Maglev 的 CLI、能力目录和分发入口。
• Maglev 发布构建脚本：公开展示目录过滤、公开清单重建、制品生成、敏感文本扫描和 manifest 校验。

第一次复制以后，问题才真正出现

派生制品至少要回答五个问题：

• 它从哪个源版本生成？
• 哪些能力被保留，哪些能力被排除？
• 新宿主需要哪些适配？
• 谁负责维护生成后的文件？
• 发布前如何证明制品完整且没有越过公开边界？

如果这些问题没有答案，复制出来的只是一个目录快照，不是一件可以继续维护的能力产品。

1. 一个目录复制之后仍然不能发布的匿名现场

把这个过程还原成一个更具体的场景。

一个团队准备把已经验证过的一组 AI 能力派生到另一个宿主。第一次做法很直接：

1. 复制源仓库中的能力目录；
2. 替换几个配置值；
3. 把说明文件放进新仓库；
4. 看到目录结构和文件数量都对上，就认为可以交付。

但第一次检查很快发现了几类问题：

这次之后，我不再把“复制成功”当成“发布完成”。发布链需要能够明确指出：缺的是生成、适配、完整性、公开边界，还是交接说明。

2. 生成器解决的不是复制，而是重复性

如果每次派生都靠人工复制和临时修改，第一次可能还能靠熟悉源仓库的人完成，第二次就会开始出现漂移：

• 某次漏复制一个入口文件；
• 某次忘了更新版本说明；
• 某次把宿主专属配置带进了公开包；
• 某次修了派生目录，却没有记录源版本。

生成器的价值，是把“从源能力到派生制品”的规则写成可重复执行的动作。

它至少要明确：

1. 输入的源版本是什么；
2. 哪些目录和能力允许进入派生制品；
3. 目标宿主需要怎样的适配；
4. 输出制品应该有哪些稳定文件；
5. 生成失败时，应该在哪一步停止。

3. 适配层不能被藏在复制动作里

源能力和目标宿主之间通常不会完全相同。

可能不同的是：

• 入口命令；
• 配置路径；
• 权限模型；
• 依赖服务；
• 目录约定；
• 验证方式。

如果这些差异被人临时改在复制后的文件里，派生过程就无法复现。更稳的做法是把适配层单独拿出来，让每个变化都能被看到、被检查、被再次生成。

这样做的好处不是让文件更多，而是让“哪些是通用能力，哪些是宿主差异”不再依赖某个人的记忆。

4. 完整性门禁应该真的能拦住发布

发布前检查最容易变成一句“请确认一下有没有问题”。但如果门禁不能给出明确的通过或失败信号，它就只是提醒，不是门禁。

我会至少检查四类问题：

来源完整性

• 源版本是否明确；
• 派生制品是否能回到源能力；
• 生成过程是否使用了正确的公开清单。

文件完整性

• 必要入口是否存在；
• 文档、命令和配置是否互相匹配；
• 目标宿主需要的适配文件是否完整。

公开边界

• 私有路径是否被过滤；
• 不该外发的目录或文本是否被扫描出来；
• 公开 catalog 是否只包含允许分发的能力。

制品一致性

• manifest 是否与最终制品一致；
• 版本和来源是否可回查；
• 安装、更新和验证说明是否对应当前制品。

公开的 Maglev 发布脚本之所以值得看，不是因为它提供了一个“发布按钮”，而是因为它把目录筛选、公开清单重建、制品生成、敏感文本扫描和 manifest 校验拆成了可执行步骤。

5. 真相记录和可执行文档不能省

派生能力最容易丢掉的，通常不是文件，而是维护上下文：

• 这个版本从哪里来；
• 为什么保留这些能力；
• 哪些文件由源仓库管理；
• 哪些文件允许目标宿主自行维护；
• 下一次更新应该重新生成，还是手工处理；
• 出现漂移时，先检查生成器、适配层还是制品。

所以，发布包里应该同时有一张简短的“真相卡”和一份可执行的使用说明。真相卡回答“它是什么、从哪里来、边界在哪里”；使用说明回答“怎么安装、怎么更新、怎么验证、失败后看哪里”。

没有这两类文档，下一位维护者只能重新猜一遍发布链。

结尾：发布的是可继续维护的能力

我现在越来越不把“目录已经复制过去”当成能力分发完成。

能复制出来，只能说明文件存在；能生成、适配、校验、安装、更新和回查，才接近真正的能力分发。

发布链的价值不是增加流程，而是把原本藏在维护者脑中的责任变成可执行门禁：源版本有记录，宿主差异有适配，公开边界能检查，最终制品能验证，下一次更新还能重跑。

如果一个派生插件离开原作者就没人敢更新，它还只是一次复制结果；只有当它可以被别人理解、检查和继续维护，它才真正成为一个能力包。

公开发布链参考

• Idea-Maglev/maglev
• Maglev 发布构建脚本