主题
版本策略
1. SDK 版本承诺
| 主版本 | 状态 | 接口签名 |
|---|---|---|
| v1 | 当前 | 一次冻结。window.ZBJ 全部成员只增不改不删；新增能力以可选成员追加，对老挂件不可见、不影响 |
manifest.sdkVersion 与 ZBJ.sdkVersion 均为主版本号。挂件作者应在 manifest 中显式声明 sdkVersion: 1；客户端在安装时校验 manifest.sdkVersion ≤ 客户端支持上限，超出时拒绝并提示升级客户端。
只有出现无法向后兼容的破坏性变更（例如调整既有事件字段的语义、删除已发布的方法），才会升 sdkVersion 至 2。届时：
- 客户端同时支持 v1 / v2 一段时间（计划 ≥ 2 个客户端大版本），给老挂件迁移窗口；
- 升级日志会标注 v1 → v2 的差异，挂件可以在 manifest 中切到新主版本以使用新能力，但旧挂件不会自动失效。
2. 兼容性矩阵
| 客户端版本 | 支持 manifest.sdkVersion |
|---|---|
| 当前 | 1 |
| 未来 v2 升级时 | 1 与 2 同时支持（至少 2 个客户端大版本的并行期） |
3. 规划中能力
下列能力需求已经明确，按价值与依赖排序，会以 v1 可选成员的形式追加（不会因为新增而升 sdkVersion，老挂件不引用即不受影响）。
| 能力 | 说明 |
|---|---|
| 应用内市场分发 | 挂件作为产品类型进入主播酱市场，用户可一键购买/下载/更新 |
| 挂件皮肤系统 | manifest theme 字段可被独立的「挂件皮肤」整体覆盖；同一挂件可发布多套主题 SKU |
| 挂件事件总线 | ZBJ.bus.emit/on 让多个挂件、挂件与内置元素之间通信 |
| 直播间共享变量 | ZBJ.vars.get/set/onChange，跨场景、跨开播持久化的键值表 |
| 控制面挂件 | manifest surfaces.control 入口，渲染在可交互的控制台窗口；与展示面通过事件总线联动 |
| 事件录制与回放 | 录制真实直播事件流到本地文件；调试时按时间轴回放 |
4. 不在路线图内
为避免误期望，明确以下能力不在规划内：
- 挂件接收鼠标 / 键盘输入：iframe 恒
pointer-events: none，交互通过直播事件或宿主面板表达；如需真正可交互的玩法，会通过未来的「控制面」机制单独实现，不会改变展示面挂件的非交互特性。 - 打开外部 / 顶层窗口：受 iframe 安全策略限制。
- 同步访问宿主数据：所有跨进程 / 跨 iframe 数据访问都是异步（RPC 或事件），不存在同步阻塞接口。
- 挂件之间共享 DOM 或运行时：每个挂件实例是独立 iframe，无法直接访问彼此的
window、document或全局变量；如需跨挂件通信，使用未来的事件总线（ZBJ.bus）。