从 v1 迁移
把兼容 magpie 的 v1 中间件改写成 v2 插件,并让已安装 v1 的用户收到升级提醒
v1 插件照常运行,不需要迁移;迁移的好处是界面、设置表单、权限和存储。v2 与 v1 不兼容,是重写,但网关部分可以几乎原样搬过去。
对照
步骤
- 用
npx @astragate/plugin-sdk init生成骨架,把原来的钩子函数移到gateway.js的一个钩子集合里; - 清单里声明钩子需要的最小权限,
match写上它关心的协议和模型(不匹配的请求不会进入插件); - 把
options的结构写成configuration,给每项默认值; - 在
replaces里写上 v1 的包名:"replaces": [{ "v1": "@scope/middleware-name" }]; - 需要迁移 v1 的设置时,在
activate里读ctx.upgrade?.from.options(只在升级后的第一次激活出现)并写入存储; - 发布到市场(插件市场与发布),条目进入注册表的
pluginsV2。
provider 与 agent 插件
- provider 插件改写成
providers扩展点:代码只提供prepare/models/refresh/usage,请求由 Astra 发出(不再需要 Bun)。服务商 id 与 v1 的相同时,升级会把原提供商(plugin-<id>)上的客户端绑定和令牌池转到新的提供商;声明legacy.auth:import的,v1 插件自己的登录条目会通过ctx.upgrade.from.auth交给 v2 插件,由它providers.accounts.add写入。 - agent 插件改写成
clients扩展点,描述字段相同,connect的输入输出也相同。客户端 kind 不变(plugin-<id>),已写入用户配置的键原样保留。
用户这边
装着 v1 插件的用户会在插件页看到升级提醒,列出 v2 插件申请的权限;确认后 Astra 安装 v2、停用 v1,v1 的设置交给 v2 迁移。旧版本保留 30 天,期间可以在插件菜单或用 astra plugin rollback <id> 回到 v1。不想升级可以忽略提醒。