版本与兼容

你要遵守的

• version 用 semver。破坏性变更(设置键改名、存储结构变化)升大版本,并在 onUpdate(from, to, ctx) 钩子里做迁移——它在版本变化时先于 activate 调一次。
• minAppVersion 写实测跑通的版本,不要往高写:它比宿主版本高一位,插件整个装不上。没把握写 0.0.0。
• id 永不改名。卡的 requires、用户设置、插件存储都按它建键;改名 = 新插件 + 老的标弃用。
• 能力 id 的字段只增不改:已发布能力的 inputs 只能新增可选字段;改类型 / 改必填 / 删字段必须新开 id(如 acme.tts → acme.tts.v2),老 id 进弃用期。
• 更新中新增权限会触发用户复确认——把权限变化当成破坏性变更来规划。

宿主向你承诺的

• 扩展点 decl 与桥协议发布后只增不改:追加可选字段不破坏旧插件;删除与改签名走弃用周期。
• apiVersion 只有大版本(当前 '1'):出 '2' 时宿主同时支持 N 与 N−1,旧 API 弃用警告至少一个大版本周期后才移除。
• 官方 npm 包在 0.x 阶段破坏性变更发生在次版本号上(semver 惯例),1.0.0 起逐字执行只增不改;每次破坏性变更在 CHANGELOG 写清迁移。

依赖别的插件

dependencies / optionalDependencies 按 id → 版本区间 声明。缺依赖时你的插件标 unresolved 灰态,用户按提示级联启用——不要在运行时自己探测别的插件存在与否,让声明系统干这件事。多个插件协作的场景优先考虑:对方把能力注册成 capability.*,你经 capability:invoke 权限调用——能力松耦合,比硬依赖插件 id 更能各自演进。