插件格式说明

插件以 .cbplugin（ZIP 包）分发，也可加密打包（.encplugin，manifest 一并加密）。

包结构

my-plugin/
├── manifest.json          # 插件清单（必填）
├── index.html             # 入口页面（manifest.entryPoint 指向，惯例固定 index.html）
├── app.js                 # 推荐逻辑独立成文件
└── vendor/                # 可选：第三方库，打包时递归包含

manifest.json 字段

{
  "pluginId": "7e2a9c41-8b3d-4f6e-9a5c-2d7b1e4f8a63",
  "name": "信纸",
  "version": "1.8.0",
  "description": "一句话描述",
  "author": "YuzhouHe Team",
  "minAppVersion": "1.3.0",
  "entryPoint": "index.html",
  "icon": "💌",
  "tags": ["信纸", "写信"],
  "category": "lifestyle"
}

字段	必填	说明
pluginId	✅	UUIDv4，生成后永不更改——数据目录、加密密钥、权限授权都挂在它上面
name / version / description / author	✅	显示信息；version 用语义化版本，每次发布必须递增
entryPoint	✅	入口 HTML 文件名（相对包根）
icon	✅	单个 emoji
minAppVersion	✅	当前市场惯例 1.3.0
tags / category	建议	category：tool / efficiency / lifestyle / entertainment / health
permissions	否	声明预申请的权限（运行时仍逐项弹窗授权）
fileHandlers	否	文件类型关联（声明后可从系统文件路由打开）

⚠️ 旧文档写的 "id" 字段已过时——安装器读取的是 pluginId。

尺寸与结构限制（安装器强制）

限制	数值
包体积	≤ 50 MB
文件数	≤ 500
单文件解压后	≤ 200 MB
解压总量	≤ 100 MB

覆盖安装（同 pluginId）不动 plugin_data/<id>/ 数据目录，用户数据安全。

官方市场发布流程

# 1. 递增 plugins/<name>/manifest.json 的 version
# 2. 打包（产出 packages/*.cbplugin + plugins.json + preview/ 预览页）
node tool/build_market.mjs
# 3. 部署变更文件到官网 plugins/ 目录（packages + plugins.json + preview）
# 4. 校验：curl plugins.json，核对 version 与 checksum（= 包文件 SHA-256）

• plugins.json 汇总全部插件元数据，checksum 字段必须与线上包实际 SHA-256 一致
• 用户侧更新：插件市场下拉刷新 → 更新（覆盖安装不动数据目录）
• 入口文件伺服带 Cache-Control: no-store，更新即生效

沙箱环境

• 页面由本地伺服器下发（随机端口 + 会话 Cookie），响应带 CSP（可引用 https 资源、 禁止 http 明文、禁止被 iframe 嵌套）
• 数据目录 plugin_data/<pluginId>/ 与包内容隔离，详见插件数据管理