Astra GateEnglish

astra 模块参考

v2 插件从 'astra' 导入的全部接口:生命周期、存储、密钥、设置、网络、命令、事件、任务、通知、权限、数据查询、界面与网关钩子

插件只能通过 import … from 'astra' 使用宿主能力。每个接口都需要对应的权限;没有权限时调用抛出 AstraError,code 为 permission_denied。SDK 里有这些接口的完整类型(@astragate/plugin-sdk)。

错误

所有失败都是 AstraError:code 是 permission_denied、not_supported、invalid_argument、not_found、rate_limited、timeout、quota_exceeded、unavailable 之一,message 是说明。

环境

接口说明
version、apiAstra 版本、API 版本(2.0.0)
env{ astraVersion, api, ui, platform, plugin: { id, version }, dev };dev 为真表示从目录加载的开发插件
has(what)某个扩展点、接口或权限是否可用,如 has('net:https://api.example.com')
t(key, params)、i18n.locale按 locales/<语言>.json 翻译;视图里用 ctx.t 得到当前界面的语言
log.debug/info/warn/error(message, fields)写入插件日志(插件详情和 astra plugin dev 里可见),有频率上限

生命周期

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

export default definePlugin({
  async activate(ctx) {
    // ctx.reason: startup | view | command | job | event | upgrade | update | restart
    // ctx.upgrade?.from: 从 v1 升级时,v1 插件的包名、spec 和设置
    // ctx.subscriptions: 放进去的 Disposable 在插件停止时自动释放
  },
  async deactivate() {},
});

清单的 activation 决定何时激活:onStartup,或第一次打开视图、执行命令、收到事件、运行任务时(onView:<id> 等)。

存储与密钥

接口权限说明
storage.get(key) / set(key, value) / delete(key)storage插件自己的键值存储,值是 JSON
storage.list({ prefix, limit, cursor })storage按前缀分页列出
storage.update(key, fn)storage读-改-写,同一个键串行执行
secrets.get(name) / set / deletesecrets加密保存的字符串(API key 等),从不出现在日志或接口返回里

网关钩子不能直接读存储;清单的 reads 列出的键会作为 ctx.shared 的快照交给钩子。

设置

config.get() 返回用户在设置表单里填的值(按清单 configuration 的默认值补全);config.onChange(fn) 在设置改变时调用。secret: true 的设置项不在这里,用 secrets.get 读取。

网络

http.fetch(url, { method, headers, body, timeoutMs }) 返回 { status, ok, url, headers, text(), json(), bytes() }。

  • 只能访问 net: 权限列出的 https 源(或 net:{config.<设置>} 指向的地址);
  • 不允许私有地址和本机地址;重定向每一跳都重新检查;
  • 回复不超过 10 MB,默认 15 秒超时(timeoutMs 可设 0.1 – 120 秒)。

stream: true 时在收到响应头后就返回,响应体留在宿主按需读取:res.lines()(整行文本,适合 SSE 和 NDJSON)、res.stream()(字节块)、res.cancel();text() / json() / bytes() 读完整个流。每个插件同时最多 8 个流,每个流至多 100 MiB,60 秒无人读取即关闭。

开发插件例外:可以用 http 访问本机地址,但仍要在 net: 里声明它,并且服务端启动时设置了 ASTRA_PLUGIN_DEV_LOOPBACK=1。

命令、事件、任务、通知

接口权限说明
commands.register(id, fn)—实现清单 commands 里的命令;返回值交给调用者(控制台、CLI、菜单)
commands.execute(id, args)—执行自己的命令
events.on(name, fn)events订阅宿主事件(如 request.completed、plugin.configChanged)或自己的事件
events.emit(name, payload)events发布清单 events 里声明的事件
jobs.handle(id, fn) / jobs.runNow(id)jobs实现、立即运行清单 jobs 里的定时任务
notifications.send({ title, body, tone })notifications控制台通知;桌面端显示为系统通知
permissions.has(p) / permissions.request(p)—查询权限;申请清单 optionalPermissions 里的权限(用户在弹窗里决定)

加密与计时

crypto.sha256(data)、crypto.hmac(key, data, algorithm)、crypto.randomUUID()、crypto.randomBytes(n);timers.sleep(ms)、timers.setTimeout/clearTimeout/setInterval/clearInterval。沙箱里没有 Node 或浏览器的全局对象(fetch、process、window 等)。

数据查询

只读,需要对应权限,结果里从不含密钥:

接口权限
data.requests.query({ from, to, model, status, limit })、data.requests.stats(...)data.requests:read
data.providers.list()data.providers:read
data.models.list()data.models:read
data.tokens.list()data.tokens:read

界面

接口说明
ui.defineView({ init, render, actions, subscribe, refresh })定义视图;导出名即视图名
ui.<组件>(props, children)构造节点,见组件参考
ui.node(type, props, children)按名字构造任意组件
ui.collection(name)数据通道的引用,作为 Table / List / Tree / Chart / LogView 的 source
ui.when(expr)、ui.local(name)本地条件:visible: ui.when(['eq', ui.local('mode'), 'advanced'])
ui.supports(name)当前界面是否支持某组件
ui.files.read(ref)读取用户选取或拖入的文件
ui.dates.toUtcRange(range, offset)把用户时区的日期范围换成 UTC

视图的 ctx:params、query、client(界面、语言、主题、宽度、位置、时区)、local(输入的值)、t、toast、navigate、back、openExternal、copy、download、focus、scrollTo、close、fail(表单字段错误)、setQuery、flush、refresh、confirm、prompt、pickFile、openSheet、openDialog、collection(name)(replace / append / prepend / update / remove / clear / setChildren)。

服务商(providers)

接口说明
providers.register(id, { prepare, models?, refresh?, usage? })实现清单 providers 里的服务商
prepare(req, account)每次发往上游之前:req 是 { protocol, model, path, method, headers, body, stream }(凭据和传输类请求头已去掉);返回 { url, headers?, body?, method? }。时限 5 秒
models(account)可选:补充或替换清单里的模型
refresh(account)可选:上游 401 / 403 之后调用;返回 'expired' 时账号标为过期并切换到下一个
usage(account)可选:账号卡片上显示的额度
providers.accounts.list / add / update / remove管理账号;add(provider, { key, displayName, email?, plan?, secret? })
account.secret()读这个账号的凭据(由 Astra 加密保存)

客户端(clients)

clients.register(id, { connect(input) }):input 是 { gateway: { url, v1, key }, model, models, agent },返回要写在模型旁边的键值(按键路径)。时限 5 秒。

网关钩子

gateway.defineHooks({ <id>: { onRequest, onUpstream, onEvent, onText, onResponse, onComplete } }),见网关钩子。钩子的 ctx:protocol、model、stream、path、client、token、requestId、options、shared、state、status、upstream、reject(status, message)、setHeader / removeHeader、emit、count、holdBack(n)、sha256。