调试与发布

1) 调试

调试模式的具体操作步骤见快速开始。要点：

在插件设置页开启调试模式，填入 dev server 输出的 bundle 地址
bundle 文件变更时宿主会重建 QuickJS 实例，内存状态不保留
部分功能（init、getInfo 的 function 入口）无法热更新，需重启或重装插件

远程日志

dev server 提供 /log 端点用于远程查看插件日志。在本体设置中填入 log 地址后，插件的 console.log/warn/error 输出会转发到终端。

2) 构建

构建前请先更新 src/get-info.ts 中 buildPluginInfo() 的 version 字段，构建脚本会据此自动同步 package.json 和 manifest.json。

pnpm run build

构建流程：typecheck → 同步版本号（get-info.ts → package.json）→ 生成 manifest.json → rspack 打包 → Brotli 压缩。

产物在 dist/ 目录，包括 <package-name>.bundle.cjs 和 <package-name>.bundle.cjs.br。

3) 发布

3.1 命名规范

插件仓库名必须以 Breeze-plugin- 开头，例如 Breeze-plugin-example。

本体中的插件列表会搜索 GitHub 上所有以 Breeze-plugin- 开头的仓库。使用其他名称开头将不会被收集到插件列表中。

3.2 发布到 GitHub

更新 src/get-info.ts 中 buildPluginInfo() 的 version 字段
执行 pnpm run build
推送代码和 dist/ 产物到 GitHub 仓库
创建 GitHub Release，tag 必须与 manifest.json 中的 version 一致（否则自动更新失效）

updateUrl 推荐填写：

https://api.github.com/repos/<owner>/Breeze-plugin-<name>/releases/latest

3.3 发布到 npm（可选）

不强制发布到 npm，但推荐。发布后可通过 jsDelivr CDN 加速下载。

发布前确保：

package.json 的 name 与 manifest.json 的 npmName 一致
version 格式为 x.y.z

3.4 常见问题

插件一定要开源吗？ 不一定。插件列表的收录条件是 GitHub 上有以 Breeze-plugin- 开头的仓库且包含 manifest.json，与源码是否公开无关。如果连 manifest.json 都不放到 GitHub 上，插件不会出现在列表中，用户只能通过"网络安装"手动输入 bundle URL。

为什么已经发布了，插件列表里还看不到？ 插件收集有延迟，通常在 2~4 小时内入库。如果超时仍未出现，检查：

仓库名是否以 Breeze-plugin- 开头
manifest.json 格式是否正确
是否创建了 GitHub Release 且 tag 与版本号一致

不想发布到 GitHub 可以吗？ 可以。用户可通过「网络安装 / 本地安装」加载 bundle。
只要 getInfo() 提供了可用的 npmName 或 updateUrl，即使不在插件列表中，客户端仍可静默检查更新（见下方第 4 节）。
不在列表中时，用户无法通过商店发现你的插件，但更新通道仍然有效。

4) 插件更新

客户端支持两条互不回退的更新路径：云端列表 与 插件自身通道（npmName / updateUrl）。
插件列表只负责发现与商店分发，不是更新资格的硬门槛。

4.1 更新通道字段

在 getInfo()（以及发布用的 manifest.json）中建议提供：

字段	作用
`version`	本地已安装版本；与远端版本做语义比较（`x.y.z`，可带 `v` 前缀）
`npmName`	优先通道：通过 npm 查询 `latest` 并走 CDN 下载 bundle
`updateUrl`	次要通道：拉取类似 GitHub Release API 的 JSON，再下载资产

推荐同时填写两者：有 npmName 时优先走 npm/CDN；失败或未配置时再走 updateUrl（下载阶段的回退，与「列表 / 自身通道」分路无关）。

updateUrl 推荐：

https://api.github.com/repos/<owner>/<repo>/releases/latest

自定义 updateUrl 也可以，返回 JSON 的最小期望值如下（字段名对齐 GitHub Release API）：

{
  "tag_name": "1.2.3",
  "assets": [
    {
      "name": "my-plugin.bundle.cjs.br",
      "browser_download_url": "https://example.com/my-plugin.bundle.cjs.br"
    }
  ]
}

说明：

tag_name：远端版本（没有时可用 name）
assets[]：至少一项；每项需有 name、browser_download_url
资产优先选 *.bundle.cjs.br，其次 *.cjs / *.bundle.cjs

加速规则：仅当 updateUrl 是 api.github.com 时，客户端才会套用 GitHub 代理加速；其它域名一律直连，不会错误拼接代理前缀。

4.2 静默自动更新（启动后后台）

应用启动后会调度一次静默更新，逻辑概要：

拉取云端插件列表（失败则全部改走自身通道）
对每个已安装且未删除的插件：
- 在列表中：只用列表里的 version / npmName / updateUrl，不回退到本地 getInfo
- 不在列表中：只用本地缓存的 getInfo（npmName 优先，否则 updateUrl），不回退到列表
远端版本 > 本地版本时才下载；下载后执行 getInfo，uuid 必须与当前插件一致，否则拒绝安装
任意成功更新后，都会重新执行 getInfo 并写回本地缓存

不在列表中的插件如何获得更新能力：

在 getInfo() 中填写 npmName 和/或 updateUrl，并正确维护 version / uuid
发布 npm 包，或保证 updateUrl 可返回最新 Release 信息
用户通过本地/网络安装后，静默更新会自动检查自身通道
若本地还没有 getInfo 缓存，客户端会用已安装脚本再跑一次 getInfo 并缓存

4.3 手动更新（用户侧）

在 单个插件的设置页（发现页 → 插件 → 设置）中：

入口	位置	行为
同步	右上角图标	固定走 `npmName` / `updateUrl` 检查并下载；有新版本才安装
更新	底部「插件管理」→ 对话框	手动重装入口（不判断「是否有新版本」）：从网络安装 / 从本地安装 / 取消；安装前 `getInfo`，uuid 与当前插件不一致则拒绝

说明：

插件自身设置 / 用户信息 / 操作在上半部分；底部「插件管理」含版本、更新、调试、删除
同步是「检查更新」：依赖插件 getInfo 里的 npmName / updateUrl（与是否在商店列表无关）
更新是「手动安装/重装」的便捷入口（例如网络差、自己下好了包、或临时换包）：
- 从网络安装：用户输入一个 bundle URL，宿主下载并安装
- 从本地安装：用户自选已下载的 .js / .cjs / .br 文件安装
两种手动安装都会校验 uuid，避免把别的插件装到当前条目上
它不是「从商店列表自动拉包」；自动检查更新请用同步

4.4 开发者检查清单（更新相关）

getInfo().uuid 稳定，永远不要随意更换（更换等于新插件）
每次发版先改 version，再 pnpm run build 并发布
GitHub Release 的 tag 与 version 一致
npmName 与 package.json 的 name 一致（若走 npm）
updateUrl 可访问；非 GitHub API 时勿依赖宿主加速
未进列表时，务必在 getInfo 中提供 npmName 或 updateUrl，否则静默更新与「同步」均无法工作

5) 故障定位

`target is not function: xxx`

原因：export default 中缺少该函数。

处理：检查 export default { ... } 是否包含对应键名，键名大小写是否与 fnPath 一致。

`插件返回格式错误`

原因：返回值结构不符合当前页面所需的类型。

处理：对照 API 契约中的 TypeScript 类型定义，逐项补齐字段。

`plugin_not_found` / `bundle_js_missing_db`

原因：插件未正确注册，或 bundle 地址不可用。

处理：检查插件 UUID、配置元数据、debugUrl 与 bundle 文件是否可访问。

图片能显示但下载失败

原因：fetchImageBytes 没有返回有效的 Uint8Array。

处理：

确认请求头加了 x-rquickjs-host-offload-binary-v1: 1
确认返回 new Uint8Array(await res.arrayBuffer())
检查图片 url 是否有效（不能为空或 404）

图片不显示

原因：ImageItem.url 为空字符串或 404 地址。

处理：url 必须是有效格式的占位符字符串，如 "https://example.com/placeholder.jpg"。宿主会校验格式但不会用这个 URL 下载图片。

1) 调试​

远程日志​

2) 构建​

3) 发布​

3.1 命名规范​

3.2 发布到 GitHub​

3.3 发布到 npm（可选）​

3.4 常见问题​

4) 插件更新​

4.1 更新通道字段​

4.2 静默自动更新（启动后后台）​

4.3 手动更新（用户侧）​

4.4 开发者检查清单（更新相关）​

5) 故障定位​

target is not function: xxx​

插件返回格式错误​

plugin_not_found / bundle_js_missing_db​

图片能显示但下载失败​

图片不显示​