Astra GateEnglish

从 v1 迁移

把兼容 magpie 的 v1 中间件改写成 v2 插件,并让已安装 v1 的用户收到升级提醒

v1 插件照常运行,不需要迁移;迁移的好处是界面、设置表单、权限和存储。v2 与 v1 不兼容,是重写,但网关部分可以几乎原样搬过去。

对照

v1(magpie 中间件)v2
package.json 的 magpie.middlewareastra.plugin.json(manifestVersion: 2),gateway 指向钩子模块
模块导出 onRequest / onEvent / onResponse / onUpstream、eventsgateway.defineHooks({ <id>: { onRequest, onEvent, onResponse, onUpstream } }),清单 gateway.hooks 声明 on 和 match
能读写所有请求和回复只能做授权的事:gateway.request:read/rewrite/reject、gateway.response:read/rewrite、gateway.upstream:headers
设置是一段 JSON(options)清单 configuration 生成设置表单;钩子里仍是 ctx.options
没有存储;状态只在内存storage / secrets;钩子通过清单 reads 拿到 ctx.shared
只有原始请求体也可以要 "view": "ir":与协议无关的统一结构,以及流式文本的 onText
没有界面页面、设置页、插槽、菜单、命令、任务、通知

步骤

  1. 用 npx @astragate/plugin-sdk init 生成骨架,把原来的钩子函数移到 gateway.js 的一个钩子集合里;
  2. 清单里声明钩子需要的最小权限,match 写上它关心的协议和模型(不匹配的请求不会进入插件);
  3. 把 options 的结构写成 configuration,给每项默认值;
  4. 在 replaces 里写上 v1 的包名:"replaces": [{ "v1": "@scope/middleware-name" }];
  5. 需要迁移 v1 的设置时,在 activate 里读 ctx.upgrade?.from.options(只在升级后的第一次激活出现)并写入存储;
  6. 发布到市场(插件市场与发布),条目进入注册表的 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。不想升级可以忽略提醒。