扩展系统
NIE-SLA 将主题和插件作为两类独立扩展管理。管理员分别在后台 主题 与 插件 页面上传 ZIP；系统验证整个包后写入各自存储路径，新包默认停用。
选择扩展类型
| 类型 | 适用场景 | JavaScript | 数据能力 | 高度范围 |
|---|---|---|---|---|
| CSS 主题 | 保留原功能，只调整配色、字体、间距和视觉 | 不允许 | 使用宿主已有 DOM | 页面自身 |
| Canvas 主题 | 完全重写公开页面布局、交互和图表 | sandbox iframe | 状态快照 + 受限历史请求 | 400–12000 |
| 插件 | 在原页面增加独立只读面板 | sandbox iframe | 状态快照 | 200–1200 |
希望最大自由度时使用 Canvas 主题；只改视觉时优先 CSS 主题；需要增加一个互不干扰的小面板时使用插件。
安装与启用流程
- 作者从源码构建干净的
dist/； manifest.json位于 ZIP 根目录；- 作者计算并发布 ZIP SHA-256；
- 管理员从对应的主题或插件入口上传；
- 浏览器与 Worker 分别校验 SHA-256；
- Worker 校验路径、文件数、体积、类型和 Manifest；
- 文件写入 R2 的独立版本目录，注册表写入 D1；
- 新包保持停用，管理员核对信息和哈希后手动启用。
主题和插件入口不会互相接受：
| 管理操作 | 路径 |
|---|---|
| 主题列表 | GET /api/themes/manage |
| 上传主题 | POST /api/themes/upload |
| 插件列表 | GET /api/plugins/manage |
| 上传插件 | POST /api/plugins/upload |
这些是 Admin API，需要短期管理 Session，不属于公开开发者 API。第三方扩展不得自行调用。
推荐仓库结构
text
nie-sla-extension-example/
src/ # 可读源码
public/ # 构建时复制的静态资源（可选）
tests/
manifest.json # 源 Manifest
package.json
README.md
CHANGELOG.md
LICENSE
dist/ # 唯一 ZIP 输入
release/ # 发布 ZIP 与 SHA256SUMSdist/ 不得包含 .env、Token、生产数据、node_modules、缓存、测试快照或泄露本机路径的 sourcemap。
标准命令
构建工具可以自由选择，但项目应提供等价命令：
bash
npm run dev
npm run build
npm run typecheck
npm test
npm run packagebuild清空并重建dist/；typecheck至少验证 Manifest、引用路径和代码语法；test覆盖数据为空、异常值、窄屏和消息来源过滤；package只压缩dist/，输出带版本号的 ZIP；- 同一 Git tag 的源码、Manifest、ZIP 和 SHA-256 必须一致。
运行边界
CSS 主题没有脚本生命周期。Canvas 主题和插件使用 sandbox="allow-scripts"，没有 allow-same-origin。扩展 HTML 的 CSP 禁止直接联网、表单、Worker、子 frame、对象和顶层导航；运行资源必须全部在 ZIP 内。
扩展不是后台模块
扩展只能展示公开数据，不能修改目标、读取通知密钥、访问管理 Session、触发 Agent 命令或获得 Cloudflare 绑定。