官方插件开发与发布

官方插件开发与发布

官方插件（termii-docker / termii-snippets / termii-tunnels / termii-batch）与第三方插件完全等同：同一 API 面、同一条 安装 → 信任 → 启用流程，无内置、无特权。

official 徽标的含义

• official: true 只是市场条目的展示徽标（「官方」标识），没有任何 特权语义。
• 安装时宿主一律剥离包内 plugin.json 的 official 字段 （strip_official_flag）——任何包自带该字段都无效，第三方伪造无效。
• 信任判定统一以安装时验签为准：官方包必须带 minisign 签名且验签 通过。

仓库结构

plugins/official/
├── termii-docker/
│   ├── plugin.json        # 清单（官方插件同样遵守全部外部插件约定）
│   ├── main.js            # 构建产物（npm run build:plugins 生成，不入库）
│   ├── main.css           # 可选：插件样式
│   └── src/               # 源码（index.ts + 模块；TS 模板）
├── termii-snippets/
├── termii-tunnels/
└── termii-batch/

官方插件包内不得 import 宿主内部模块（src/lib、src/stores 等）—— 与第三方一样只从 @termii/plugin-sdk 取类型与运行时，验收时以 grep 证明。

构建

npm run build:plugins          # 构建全部官方插件
# 等价于（单插件）：
npx termii-plugin-sdk build plugins/official/termii-docker/src/index.ts \
  --outfile plugins/official/termii-docker/main.js --minify

发布（publish-plugins.sh）

bash scripts/publish-plugins.sh               # 打包 + 签名 + 生成 catalog + 同步
bash scripts/publish-plugins.sh --push        # 同步后提交并推送 resps/plugins
bash scripts/publish-plugins.sh --no-build    # 跳过 npm run build:plugins
bash scripts/publish-plugins.sh plugins/official/termii-docker  # 只发布指定插件

流程：

npm run build:plugins
  → 逐插件：组装运行时文件（plugin.json / main.js / main.css）→ tar.gz
    （COPYFILE_DISABLE=1，目录根 = 插件目录）
  → minisign 签名 tar.gz 字节（信任根同 updater，产出 <包>.sig）
  → build-catalog.mjs 合并目录：官方条目整体替换、社区条目保留
  → 同步到 resps/plugins/（组织仓库源码归档；--push 时提交推送）
  → 本地复验（resps/plugins/.github/scripts/validate-catalog.mjs）

前置条件

• npm run build:plugins 已构建好 main.js（产物不入库，默认发布流程自动构建；传 --no-build 时自行保证新鲜）
• 签名私钥：~/.tauri/termii.key（带密码），或用环境变量 TAURI_SIGNING_PRIVATE_KEY / TAURI_SIGNING_PRIVATE_KEY_PATH / TAURI_SIGNING_PRIVATE_KEY_PASSWORD（CI 用 GitHub Secrets）
• resps/plugins 已克隆：git clone git@github.com:Termii-App/plugins.git resps/plugins

catalog 合并语义

• 官方条目整体替换旧目录中的官方条目（含下架的：随下次发布从目录移除）；
• 社区条目原样保留——社区条目由作者手工维护，官方发布不得覆盖；
• 与官方 id 冲突的旧条目一并丢弃（catalog id 必须全局唯一）。

部署

• 组织仓库 Termii-App/plugins（即 resps/plugins）main 分支推送后经 GitHub Actions 自动部署到 https://plugins.termii.meowdream.cn/catalog.json（Cloudflare Pages 项目 termii-plugins，与官网同 CDN）——这是应用内 CATALOG_URL 的唯一事实源。发布脚本只写 resps/plugins/，不再同步 website/plugins/。
• 官网插件目录页通过 CATALOG_REMOTE 直接读取 https://plugins.termii.meowdream.cn/catalog.json，本地 dev 用 site/public/plugins/ 兜底（已 gitignore，非发布产物）。

密钥与签名对象

• 公钥：tauri.conf.json 的 plugins.updater.pubkey（与更新包同一信任根）。
• 签名对象：tar.gz 包字节本身；.sig 是 base64 编码的 minisign 文本 （tauri signer sign 输出与 updater signature 字段同格式）。

验收清单

• npm run build:plugins 通过，四个 main.js 已更新
• 包内无对宿主内部模块的 import（grep 证明）
• bash scripts/publish-plugins.sh --push 成功，resps/plugins 已推送
• 目录复验脚本通过（社区条目未被覆盖）
• 主站部署 npm run pages:deploy 完成