Astra GateEnglish

编写 v2 插件

v2 插件的清单、权限、扩展点、界面(JS 构建、Web 与桌面端同一套组件)、网关钩子,以及 SDK、测试与发布

v2 插件是 Astra 自己的插件格式,与兼容 magpie 的 v1 插件(插件)并存但互不兼容:v1 插件照常运行,v2 插件由新的宿主加载。和 v1 相比,v2 插件:

  • 在 沙箱 里运行(Jaunt,一个 JS 引擎实例对应一个插件),只能做它 声明并经用户授权 的事;
  • 用 JS 描述 界面:插件返回一棵组件树,控制台(Web)和桌面端(Avalonia)用同一套组件把它画出来;
  • 可以在获得 gateway.* 权限后 读取、改写或拒绝 经过网关的请求与回复,与 v1 中间件在同一条链上;
  • 有存储、密钥、设置、命令、定时任务、事件、通知、受限的网络访问(含流式)和只读的数据查询;
  • 可以添加服务商(请求由 Astra 发出,插件只负责地址和凭据)和客户端(写入仍由 Astra 完成)。

一个插件长什么样

命令text
my-plugin/
  astra.plugin.json   清单(必需)
  main.js             主模块:视图、命令、任务、事件
  gateway.js          网关钩子(可选,在网关的请求路径上运行)

最快的开始方式是 SDK 的脚手架:

命令bash
npx @astragate/plugin-sdk init my-plugin --id me.my-plugin
cd my-plugin && npm install && npm test

清单 astra.plugin.json

代码json
{
  "manifestVersion": 2,
  "id": "acme.word-guard",
  "version": "2.1.0",
  "name": { "zh": "敏感词守卫", "en": "Word Guard" },
  "engines": { "astra": ">=0.15.0", "api": "^2.0" },
  "main": "main.js",
  "gateway": "gateway.js",
  "permissions": ["ui", "storage", "gateway.request:reject"],
  "optionalPermissions": ["net:{config.endpoint}"],
  "contributes": {
    "configuration": { "properties": { "words": { "type": "array", "items": { "type": "string" }, "default": [] } } },
    "gateway.hooks": [{ "id": "guard", "on": ["request"], "view": "ir", "match": { "protocols": ["anthropic"] }, "reads": ["words"] }],
    "ui.pages": [{ "id": "dashboard", "title": "Guard", "icon": "shield", "nav": "tools", "routes": [{ "path": "", "view": "list" }, { "path": ":id", "view": "detail" }] }]
  },
  "replaces": [{ "v1": "@astragate-community/middleware-word-guard" }]
}
  • id 是 <发布者>.<名字>,小写;version 是 semver。name、description 和各处的 title 可以是字符串,也可以是按语言的对象。
  • engines.api 是插件需要的 API 版本(当前 2.0.0),不满足时不会加载;engines.astra 是需要的 Astra 版本。
  • main、gateway 是包内的相对路径。contributes 里出现 Astra 不认识的扩展点只会产生警告,不会让插件失效。
  • replaces 列出它取代的 v1 插件:装着这些 v1 插件的用户会在控制台看到升级提醒(见下文)。

权限

插件只能调用权限覆盖的宿主接口,没有“全部权限”。安装或升级时用户会看到完整列表并逐项确认;optionalPermissions 在运行时用 permissions.request() 申请,用户在弹出的对话框里允许或拒绝。

权限允许什么
storage / secrets插件自己的键值存储 / 加密保存的密钥
ui提供页面、设置页、插槽和菜单
notifications、jobs、events发通知、定时任务、发布与订阅事件
gateway.request:read / :rewrite / :reject读取 / 改写 / 拒绝网关请求(改写和拒绝都包含读取)
gateway.response:read / :rewrite读取 / 改写回复(含流式事件和文本)
gateway.upstream:headers在发往上游的请求上设置请求头(凭据和分帧相关的头除外)
data.requests:read、data.providers:read、data.models:read、data.tokens:read只读查询请求日志、提供商、模型、令牌(从不含密钥)
net:https://host[:port]访问这一个 https 源;net:{config.<设置>} 表示用户在设置里填的地址
providers添加服务商并管理它们的账号;请求经插件的 prepare 发往上游
clients让 Astra 接入新的本地客户端(写入它的配置文件,仍经 Astra 的备份与还原)
legacy.auth:import从 v1 provider 插件升级时,一次性取得那个 v1 插件自己的登录条目

网络访问只走 http.fetch:仅 https、仅已授权的源、不允许私有地址,跟随重定向时每一跳都重新检查,回复不超过 10 MB。

扩展点

扩展点说明
configuration设置项(JSON Schema 子集);控制台按它生成设置表单,config.get() 读取
commands命令(commands.register 实现);可以从控制台、CLI(astra plugin run)和菜单执行
ui.pages侧边栏页面:nav 是分组(overview、gateway、resources、tools、plugins),routes 把路径映射到视图
ui.settings插件详情里的自定义设置视图(替代自动生成的表单)
ui.slots填入宿主页面的插槽,见下表
ui.menus把命令加到宿主菜单:token.row(令牌行)、provider.row(提供商详情)、provider.account.row(账号卡片)、request.row(请求详情)、client.row(客户端);命令收到对应的 ID(tokenId、providerId …)。command.palette 已保留,目前还没有显示的位置
gateway.hooks网关钩子集合,见下文
jobs定时任务:every(如 6h)或 cron(五段式)
events插件发布的事件名
providers服务商:协议、模型、登录流程;代码 providers.register(id, { prepare, models, refresh, usage }),见下文
clients客户端:配置文件、格式、模型键、可执行文件名;代码 clients.register(id, { connect })
ui.flows分步流程(登录向导),在侧板里打开;服务商的 signIn.flow 指向它
插槽位置传给视图的参数
overview.cards概览页range
provider.detail.tabs提供商详情providerId
provider.account.sections提供商账号providerId、accountId
request.detail.sections请求详情requestId
client.detail.sections客户端clientKind
token.detail.sections令牌详情tokenId
settings.sections设置页—
tray.panel托盘面板—

界面

视图是 main.js 的 顶层导出,导出名就是清单里 routes、ui.slots 引用的视图名。视图的代码在服务端的沙箱里运行,返回组件树;宿主比较前后两棵树,把差异推送给控制台或桌面端,由它们用各自的原生控件绘制。

代码js
import { storage, ui } from 'astra';

export const list = ui.defineView({
  init: async () => ({ words: (await storage.get('words')) ?? [] }),
  render: (s) =>
    ui.Stack({ gap: '4' }, [
      ui.Heading({ value: '敏感词', level: 2 }),
      ui.TagInput({ name: 'draft' }),
      ui.Button({ label: '保存', variant: 'primary', onPress: 'save' }),
      ui.Table({ columns: [{ key: 'word', title: '词' }], rows: s.words.map((word) => ({ word })) }),
    ]),
  actions: {
    save: async (s, _args, ctx) => {
      s.words = ctx.local.draft ?? [];
      await storage.set('words', s.words);
      ctx.toast({ message: '已保存', tone: 'success' });
    },
  },
});
  • 状态:init 返回的状态由宿主保存(不超过 256 KB),actions 修改它后视图自动重新渲染;引擎被回收或重启后状态不会丢。
  • 输入:输入控件(name)的值保存在界面一侧,动作通过 ctx.local 读取,打字不会往返服务端。visible / disabled 可以写成 ui.when(...) 条件,由界面在本地求值。
  • 交互:ctx 上有 toast、navigate、confirm、prompt、pickFile、openSheet、openDialog、copy、download、fail(表单字段错误)等。
  • 大量数据:ctx.collection(name) 向表格、列表、树、图表和日志视图推送行,不重新渲染整棵树。
  • 组件:布局(Stack、Grid、Card、Tabs、Sheet …)、文本与 Markdown、表单输入(文本、数字、选择、开关、日期 / 时间 / 日期范围、标签、文件 …)、表格、列表、树、折线 / 柱状 / 面积 / 饼图、Sparkline、仪表、指标卡、JSON 树、日志、二维码、画布等。完整的组件和属性见 SDK 的类型定义;ui.supports(name) 可判断当前界面是否支持某个组件。
  • 一致性:Markdown 在服务端解析成同一种结构,只保留 https 和站内链接;格式化(数字、金额、tokens、时长、日期)和图表刻度两端使用同一套规则。

网关钩子

gateway.js 默认导出 gateway.defineHooks({...}),键是清单 gateway.hooks 里的 id。钩子与 v1 中间件在同一条链上运行,按清单的 match(协议、模型通配、客户端、是否流式)筛选请求。

钩子时机需要的权限
onRequest(req, ctx)进入网关、隐私护栏之前gateway.request:read(改写需 :rewrite,ctx.reject 需 :reject)
onUpstream(req, ctx)每次发往上游之前,已转换协议;ctx.upstream 给出上游协议、提供商和模型gateway.request:read(设置请求头需 gateway.upstream:headers)
onEvent(event, ctx) / onText(text, ctx)流式回复的每个事件 / 每段文本(onText 需要 "view": "ir";ctx.holdBack(n) 暂扣末尾 n 个字符,用于跨片段匹配)gateway.response:read(改写需 :rewrite)
onResponse(res, ctx)非流式回复同上
onComplete(info, ctx)请求结束后(状态、用量、耗时),只读gateway.response:read
  • "view": "ir" 时钩子拿到与协议无关的统一结构(消息、工具、文本),raw 时是原始请求体。
  • 钩子返回改写后的对象,返回 undefined 表示不修改;没有改写权限时返回值会被忽略。
  • ctx.shared 是清单 reads 列出的存储键的快照(在 main.js 里写,钩子里读),ctx.count / ctx.emit 记录计数和事件,ctx.options 是插件设置。
  • 钩子在请求路径上运行,时间限制与 v1 中间件相同(请求、整段回复和 onUpstream 250 ms,单个事件 50 ms)。出错或超时时原样放行,只计入失败次数,不会让请求失败。

服务商与客户端

插件可以添加一个服务商:Astra 为它建一个提供商(plugin2-<插件>-<服务商>),客户端绑定、令牌池、故障转移、计费都和其他提供商一样。每次发往上游之前,Astra 调用插件的 prepare(req, account),按它返回的地址和请求头发送(地址必须在 net: 权限内);回复由 Astra 直接流回,插件不经手。

代码js
import { definePlugin, providers } from 'astra';

export default definePlugin({
  activate() {
    providers.register('acme', {
      async prepare(req, account) {
        return { url: 'https://api.acme.example/v1/chat/completions', headers: { authorization: `Bearer ${await account.secret()}` } };
      },
      async refresh(account) { return 'expired'; },   // 上游 401 / 403 之后
    });
  },
});

账号由插件管理:providers.accounts.add('acme', { key, displayName, secret }),secret 由 Astra 加密保存,account.secret() 读取。清单 ui.flows 的视图负责登录(输入 API key、显示设备码、粘贴授权码):提供商页面的“登录账号”在侧板里打开它,完成后 ctx.close()。

客户端与 v1 agent 插件用同一套描述(配置文件、格式、模型键):connect(input) 返回要写入的键值,写入由 Astra 完成,备份、漂移检测和 astra-server restore-all 照常适用。

http.fetch(url, { stream: true }) 返回流式响应:res.lines() 逐行(SSE、NDJSON)、res.stream() 逐块、res.cancel() 关闭。

SDK 与测试

@astragate/plugin-sdk 提供 astra 模块的类型、测试工具和命令行 astra-plugin:

代码js
// vitest.config.js
export default { resolve: { alias: { astra: '@astragate/plugin-sdk/runtime' } } };
代码js
import { mount, runCommand, runHook } from '@astragate/plugin-sdk/testing';
import hooks from '../gateway.js';
import { list } from '../main.js';

const view = await mount(list, { storage: { words: ['a'] } });
await view.change('draft', ['a', 'b']);
await view.press('save');
expect(await view.storage.get('words')).toEqual(['a', 'b']);

const r = await runHook(hooks, 'guard', 'request', { messages: [] }, { shared: { words: ['x'] } });
expect(r.rejected).toBeNull();

测试使用与 Astra 相同的运行时脚本(boot.js、astra.js),只是宿主换成了内存实现。astra plugin test 把同一组测试放进 Astra 自己的沙箱里运行(真实的 astra 模块和宿主调用,独立的临时存储)。构建、校验、组合件、开发模式、组件画廊和检查器见开发工具;全部接口见 astra 模块参考,全部组件见组件参考。

安装、授权与升级

  • 安装:控制台 插件 页,或 astra plugin add <包或路径>。v2 插件安装后处于“等待授权”状态,用户确认权限(控制台或 astra plugin grant <id>)后才会运行。
  • 新版本申请了新的权限时,插件会暂停并等待再次授权;撤销授权(/revoke)会立即停用它。
  • 用户装着 v1 插件、而市场里有声明 replaces 它的 v2 插件时,控制台会显示升级提醒。升级需要用户确认 v2 插件的权限;升级时 v1 的设置会通过 activate 的 ctx.upgrade 交给 v2 插件迁移,v1 插件保留 30 天,期间可以在插件菜单里或用 astra plugin rollback <id> 回滚。升级也可以用 astra plugin upgrade <v1 包名>。迁移步骤见从 v1 迁移。

发布

命令bash
npx astra-plugin validate     # 按 Astra 的规则检查清单
npx astra-plugin pack         # 生成 <id>-<version>.tgz,并打印 sha256 / sha512

把 tarball 发布到市场的方式与 v1 插件相同(插件市场与发布):包里有 astra.plugin.json 时,市场以清单的 id 和 version 登记它,列在注册表的 pluginsV2 里。