插件发布指南

插件市场采用 GitHub 分发:插件字节全部托管在你自己的 GitHub 仓库,市场目录只登记一个指向你仓库的条目。发新版只需要打一个 tag —— 不需要每次提 PR。

1. 从模板创建仓库

用 plugin-template 生成你的插件仓库(一个插件一个仓库)。写好插件后,确认根目录有 manifest.json 与入口 main.js:

{
  "id": "example.my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "author": "你的名字",
  "description": "一句话说明插件做什么",
  "main": "main.js",
  "trust": "safe",
  "permissions": ["canvas.registerNodeDef"],
  "categories": ["node"]
}

• id:小写字母/数字/点/连字符;上架后不可更改,也是安装包文件名的一部分
• version:semver(如 0.1.0),每次发版递增
• trust:safe(仅画布)/ trusted(含 nodeEntry,主进程权限,人工审核更严)

2. 打 tag,release 自动打包

推送 v* tag 触发模板自带的 release 工作流,把已经构建好的 manifest.json 与 main.js 打成一个 zip,再算 manifest 内的 integrity 字段,然后上传三个资产:

git tag v0.1.0 && git push origin v0.1.0

• <id>-<version>.zip — 版本化安装包(钉版本用)
• <id>.zip — 无版本别名,永远指向最新正式版
• manifest.json — 无版本别名,供桌面端探测新版本

打包时会重算入口文件的 SHA-256 并注入 integrity 字段,桌面端安装时强制校验。注意 release 必须是正式版(不能是 draft 或 prerelease),否则不会被 releases/latest 命中。

3. 提 PR 登记到插件目录

向 poly-creator/plugins 提交 PR,在 plugins.json 增加一条:

{
  "id": "example.my-plugin",
  "name": "My Plugin",
  "author": "你的名字",
  "repo": "你的用户名/你的插件仓库",
  "description": "一句话说明插件做什么"
}

CI 会自动校验:仓库存在、latest release 三个资产齐全、包内 manifest 与条目一致。合并后插件出现在市场与桌面端「市场」标签页。之后每次发版只需打 tag,目录条目不用再动。

需要钉死某个版本(字节级防替换)时,可在条目里同时加 tag 与 sha256(二者必须成对),安装时会校验哈希。

规则

• 一个插件一个仓库 —— 多插件仓库会破坏 <id>.zip 别名约定,CI 会拒绝
• zip ≤ 30 MiB;路径穿越条目(../、绝对路径)拒绝
• 含 nodeEntry 的 trusted 插件人工审核更严
• 下架 = 从 plugins.json 移除条目(已安装用户不受影响)