调试与排错
- 开发宿主：
npm run tauri dev启动宿主。插件加载 / 激活的报错打在 webview 控制台（带插件 <id> …前缀）。 - 插件自身日志：
console.log / console.error同样出现在 webview 控制台；activate(ctx)里第一行打ctx.apiVersion可确认契约版本。 - 构建报错：
npx termii-plugin-sdk build …的 esbuild 错误会指明 文件与行列；esbuild 缺失时脚手架给出友好提示（先在插件项目npm install）。 - manifest 校验：写插件时用
validateManifest提前校验清单，错误为 中文、逐条收集。
常见加载失败原因
Section titled “常见加载失败原因”| 症状 | 原因 | 处理 |
|---|---|---|
| toast「插件 X 需要更新的 Termii 版本」 | 声明 apiVersion > 3 |
降低声明值，见 apiVersion 契约 |
| 插件加载失败（无具体信息） | manifest.id 与目录名不一致 / bundle 缺 default export / bundle 内 manifest 缺失 |
检查 plugin.json 与 src/manifest.js 一致；确认构建产物是最新的 main.js |
| 设置页显示「缺少前置依赖」 | dependencies 中的插件未安装 / 未启用 / 未信任 |
先启用并信任依赖插件；检查依赖 id 拼写（kebab-case） |
| 提示未获授权（进程 / sidecar） | L1 能力未在信任弹窗确认 | 「设置 → 插件」重新确认能力声明（卸载重装会要求重新信任） |
ctx.sidecar.call 报「当前平台无对应二进制」 |
sidecar.binaries 缺少当前平台键 |
补上 <os>-<arch> 键（如 darwin-aarch64） |
| 注册贡献点后界面没有出现 | 贡献点 id 未加 <pluginId>. 前缀被拒绝 |
显式写全前缀 id，见 贡献点 |
安全约束（生产构建）
Section titled “安全约束（生产构建）”- CSP 允许
script-src blob:——外部插件经 Blob URL 加载，插件内不允许 远程脚本 / 样式。 - 网络请求走页面级
fetch（connect-src只放行https:与宿主 IPC）； 需要访问远程 API 时在插件内直接fetch，或经ctx.hosts.exec在远端 主机执行。
调试官方插件
Section titled “调试官方插件”官方插件与第三方完全等同，也是从磁盘加载的外部插件：改 plugins/official/<id>/src/
后运行 npm run build:plugins（或单独构建某个插件）重新生成 main.js，
再到应用内「设置 → 插件」重新启用即可生效。发布流程见
官方插件开发与发布。