编写 v2 插件
v2 插件的清单、权限、扩展点、界面(JS 构建、Web 与桌面端同一套组件)、网关钩子,以及 SDK、测试与发布
v2 插件是 Astra 自己的插件格式,与兼容 magpie 的 v1 插件(插件)并存但互不兼容:v1 插件照常运行,v2 插件由新的宿主加载。和 v1 相比,v2 插件:
- 在 沙箱 里运行(Jaunt,一个 JS 引擎实例对应一个插件),只能做它 声明并经用户授权 的事;
- 用 JS 描述 界面:插件返回一棵组件树,控制台(Web)和桌面端(Avalonia)用同一套组件把它画出来;
- 可以在获得
gateway.*权限后 读取、改写或拒绝 经过网关的请求与回复,与 v1 中间件在同一条链上; - 有存储、密钥、设置、命令、定时任务、事件、通知、受限的网络访问(含流式)和只读的数据查询;
- 可以添加服务商(请求由 Astra 发出,插件只负责地址和凭据)和客户端(写入仍由 Astra 完成)。
一个插件长什么样
最快的开始方式是 SDK 的脚手架:
清单 astra.plugin.json
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() 申请,用户在弹出的对话框里允许或拒绝。
网络访问只走 http.fetch:仅 https、仅已授权的源、不允许私有地址,跟随重定向时每一跳都重新检查,回复不超过 10 MB。
扩展点
界面
视图是 main.js 的 顶层导出,导出名就是清单里 routes、ui.slots 引用的视图名。视图的代码在服务端的沙箱里运行,返回组件树;宿主比较前后两棵树,把差异推送给控制台或桌面端,由它们用各自的原生控件绘制。
- 状态:
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(协议、模型通配、客户端、是否流式)筛选请求。
"view": "ir"时钩子拿到与协议无关的统一结构(消息、工具、文本),raw时是原始请求体。- 钩子返回改写后的对象,返回
undefined表示不修改;没有改写权限时返回值会被忽略。 ctx.shared是清单reads列出的存储键的快照(在main.js里写,钩子里读),ctx.count/ctx.emit记录计数和事件,ctx.options是插件设置。- 钩子在请求路径上运行,时间限制与 v1 中间件相同(请求、整段回复和
onUpstream250 ms,单个事件 50 ms)。出错或超时时原样放行,只计入失败次数,不会让请求失败。
服务商与客户端
插件可以添加一个服务商:Astra 为它建一个提供商(plugin2-<插件>-<服务商>),客户端绑定、令牌池、故障转移、计费都和其他提供商一样。每次发往上游之前,Astra 调用插件的 prepare(req, account),按它返回的地址和请求头发送(地址必须在 net: 权限内);回复由 Astra 直接流回,插件不经手。
账号由插件管理: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:
测试使用与 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 迁移。
发布
把 tarball 发布到市场的方式与 v1 插件相同(插件市场与发布):包里有 astra.plugin.json 时,市场以清单的 id 和 version 登记它,列在注册表的 pluginsV2 里。