Astra GateEnglish

开发工具

SDK(构建、校验、打包、测试与组合件)、开发模式热重载、组件画廊与检查器

SDK

命令bash
npm i -D @astragate/plugin-sdk
命令说明
npx astra-plugin init <目录> --id me.name生成起步插件:一个页面、一个命令、一组钩子、一个测试
npx astra-plugin validate按 Astra 的规则检查清单;还会扫描代码:用了接口却没有声明权限、声明了却没用到、t('key') 缺少翻译、包体积
npx astra-plugin build [--watch]用 esbuild 把 main 和 gateway 各打成一个 ESM 文件(沙箱只能相对导入),输出到 dist/
npx astra-plugin pack [dist]打成 tarball,打印 sha256 和 sha512

类型:在 tsconfig.json 里把 astra 指向 SDK("paths": { "astra": ["./node_modules/@astragate/plugin-sdk"] });JSX 用 jsxImportSource: '@astragate/plugin-sdk'。

组合件(@astragate/plugin-sdk/patterns):SettingsPage、ListDetail(窄宽度下变为导航)、Wizard、Dashboard、CrudTable。它们只是用基础组件拼成的函数,和你自己的代码一起打包。

测试

测试工具(@astragate/plugin-sdk/testing)在 Node 里运行与 Astra 相同的运行时脚本:

  • mount(view, { storage, secrets, config, permissions, fetch, confirm, prompt, … }) 打开视图,返回 find / findAll / press / change / render / effects / storage;

  • 每次渲染都按组件模式检查:未知组件或属性、类型不符、事件指向不存在的动作、缺少 a11yLabel / alt 是错误(默认抛出,strict: false 时收集到 view.warnings),列表缺 key、超过限额 80% 是警告;

  • runCommand(plugin, id, args)、runHook(hooks, setId, 'request', input, { shared, config })。

  • runProvider(plugin, id, 'prepare', req, { key, secret })、runClient(plugin, id, input):服务商和客户端。

在测试运行器里把 astra 指向 @astragate/plugin-sdk/runtime(vitest:resolve.alias)。

在 Astra 的沙箱里跑同一组测试:

命令bash
astra plugin test ./my-plugin

test/**/*.test.js(或 .mjs)里的测试在 Astra 自己的 JavaScript 引擎里运行:真实的 astra 模块、真实的宿主调用和权限检查,但用一份独立的临时存储(不碰已安装插件的数据),没有网络(http.fetch 返回 404)。测试从 vitest 和 @astragate/plugin-sdk/testing 导入,沙箱提供这两个模块,所以同一个文件在 Node 和沙箱里都能跑。只允许本机。

开发模式

命令bash
astra plugin dev ./my-plugin

把目录作为开发插件挂载(只允许本机),确认权限后开始打印插件日志,Ctrl+C 卸载(--keep 保留)。开发插件:

  • 保存即重载:目录里任何文件变化(node_modules、dist、.git 除外)都会重新加载插件;打开着的视图用原来的状态重新渲染,界面不会丢;新代码与旧状态不兼容时视图重新初始化;
  • 可以用 http 访问本机地址(连本地的测试服务):在 net: 里声明它,并以 ASTRA_PLUGIN_DEV_LOOPBACK=1 启动服务端;
  • 视图右上角有 检查器:当前组件树、状态与本地输入、每次动作的耗时(排队、处理、渲染、求差、补丁大小)、宿主调用与日志、模式警告;还可以把视图切换到 compact / regular / wide 宽度、明暗主题、页面 / 侧板 / 托盘位置预览。

组件画廊

插件页在有开发插件时显示 组件画廊(/plugins/dev/gallery,桌面端同样有):每个组件、每种状态(变体、色调、尺寸、加载、错误、禁用)和几个组合场景,可以切换宽度、主题和位置,并查看产生它的组件树。画廊的场景就是 Web 与桌面端视觉比对用的同一组场景(tests/fixtures/plugin-ui/)。