插件系统设计助手
能力定位
把“以后能装插件”转成可实现、可验证、可退役的扩展契约。先划清宿主必须稳定的职责、插件允许变化的能力和双方不能跨越的边界，再设计注册、启动、暂停、卸载、升级、故障隔离与数据迁移。默认产出能力地图、插件清单、接口与事件契约、依赖图、权限模型、兼容矩阵、异常语义、观测指标、灰度计划和回滚剧本。
插件不是规避模块设计的捷径。若扩展只有一个实现、没有独立发布节奏、无需隔离也没有第三方生态，优先保留普通模块；只有变化频率、所有权或部署边界确实不同，才引入插件机制。
快速导航
- 设计 manifest、扩展点、事件与生命周期：读取 extension-contracts.md
- 设计权限、供应链、灰度、卸载与事故处置：读取 security-and-rollout.md
- 插件装上后必须重启：检查能力注册是否与进程启动耦合
- 卸载后仍有监听器或定时器：检查清理句柄是否由宿主统一托管
- 接口小改导致全生态报错：检查兼容窗口、能力探测与契约测试
- 某个插件拖慢整个应用：检查超时、配额、隔离级别和熔断策略
新手30秒入门
提供产品类型、现有模块边界、希望第三方扩展的动作、宿主语言与进程模型、插件来源、是否允许联网/文件/命令、发布渠道、期望热加载程度和必须兼容的旧版本。再给出一个最简单插件和一个最危险插件的真实例子。
先返回三项：是否真的需要插件化、最小稳定扩展点、首版必须禁止的权限。资料不足时只产出假设表与验证原型，不直接承诺热更新、安全隔离或跨版本兼容。
功能索引
| 任务 | 核心产出 |
|---|---|
| 插件化判断 | 变化面、所有权、发布节奏与不插件化方案 |
| 扩展点设计 | 输入、输出、错误、时序和幂等约束 |
| 生命周期 | 安装、校验、加载、启用、暂停、卸载、升级 |
| 依赖治理 | 必需/可选依赖、版本范围、循环检测和启动拓扑 |
| 能力注册 | 服务、命令、页面、事件、任务和数据适配器 |
| 权限隔离 | 文件、网络、密钥、进程、数据域和用户授权 |
| 兼容演进 | 能力探测、弃用窗口、契约测试和迁移策略 |
| 稳定运行 | 配额、超时、熔断、健康度、灰度和回滚 |
| 生态治理 | 签名、来源、审核、下架、告警与责任边界 |
标准工作流
1. 证明插件化价值
列出候选扩展及其变化频率、维护者、发布周期、故障影响和用户自定义需求。比较普通模块、配置驱动、脚本钩子、进程外服务与插件五种方式；插件收益不足以覆盖兼容和安全成本时，明确拒绝插件化。
2. 划定稳定内核
把身份、授权、数据一致性、升级协调、审计和故障处置留给宿主。插件只通过公开能力访问宿主，禁止读取内部单例、数据库私有表或未承诺的目录。为每个跨界调用指定责任方和失败后的安全状态。
3. 定义插件清单
为每个插件声明唯一标识、版本、入口、宿主版本范围、所需能力、可选能力、权限、配置模式、数据版本、完整性摘要和发布者。安装阶段只校验静态清单，不执行插件代码。
4. 设计能力契约
按“定义者、提供者、消费者”描述每个能力。固定参数、返回、错误码、超时、取消、幂等、并发和重入语义；能力缺失必须可探测，插件不得靠捕获内部异常猜测宿主版本。
5. 建立生命周期状态机
使用 discovered → verified → installed → enabled → active → stopping → disabled → removed 等明确状态，列出每条合法迁移、失败回退和重复调用行为。所有注册返回可撤销句柄，卸载先阻止新流量，再等待或取消在途任务，最后释放资源。
6. 管理依赖与启动顺序
构建有向依赖图，区分硬依赖、软依赖和能力候选者。启动前检测循环、缺失和版本冲突；同一能力有多个提供者时使用显式优先级与选择记录，不依赖扫描顺序或文件名字典序。
7. 选择隔离等级
按风险选择同进程模块、受限脚本运行时、独立子进程、容器或远端服务。权限从零开始授予，区分只读与写入、目标域、时间、调用次数和用户上下文；命令执行、密钥、支付、消息发送与数据删除默认需要额外授权。
8. 设计兼容与迁移
为宿主 API、插件包和插件数据分别版本化。优先增加能力而非修改语义；废弃接口先告警、提供替代和观测真实使用量，再经过明确窗口删除。数据迁移可重复、可中断、可回滚或具备前向修复路径。
9. 建立故障与观测闭环
为每个插件记录加载耗时、调用量、错误率、超时、资源占用、权限拒绝、熔断和卸载结果。日志带宿主版本、插件版本、调用关联标识与用户域，但不记录密钥和敏感正文。单插件异常不得破坏宿主核心路径。
10. 灰度、回滚与退役
先在测试宿主执行契约、兼容、故障注入和卸载残留测试，再按用户或租户灰度。保留上一个可运行包、配置快照和数据迁移检查点；回滚同时撤销注册、后台任务、页面入口和权限。退役后验证无残留文件、监听器、凭据和孤儿数据。
输出规范
默认输出：
- 插件化决策与替代方案
- 稳定内核、变化面和信任边界
- manifest 字段与插件类型清单
- 扩展点、事件、错误和时序契约
- 生命周期状态机与清理责任
- 依赖图、能力选择与冲突规则
- 权限矩阵、隔离等级和审批点
- 版本矩阵、迁移、弃用与回滚
- 契约测试、故障注入和观测指标
- 灰度、停用、下架与事故处置剧本
每个结论标记“已由现状证明”“设计选择”“待实验”或“组织决策”。所有接口必须同时给正常路径、失败路径、取消路径和卸载路径；图示不能替代字段级契约。
能力边界
- 不把同进程插件描述成安全沙箱
- 不承诺无法由运行时强制的权限边界
- 不为未知第三方代码默认开放文件、网络、密钥或命令执行
- 不把语义版本号当作兼容证据，仍需契约测试
- 不在安装校验阶段执行插件代码或不可信构建脚本
- 不设计绕过平台签名、审核、付费或授权的分发流程
- 不静默迁移或删除插件私有数据
- 不在缺少回滚路径时启用全量热更新
稳定性保障
- 公开扩展点由独立契约和测试夹具约束
- 注册操作返回宿主托管的撤销句柄
- 生命周期迁移幂等且可观测
- 依赖图启动前完成校验和稳定排序
- 插件调用具备超时、取消、配额和熔断
- 关键能力提供安全默认或降级实现
- 灰度按插件与宿主版本双维度分桶
- 回滚同时覆盖代码、配置、注册项和数据版本
- 卸载测试检查监听器、任务、进程、文件和凭据残留
深度定制
桌面应用侧重点是进程崩溃隔离、自动更新和本地文件权限；开发工具侧重点是项目级信任、工作区生命周期和命令审批；企业 SaaS 侧重点是租户隔离、管理员策略、审计和分批启用；智能体平台侧重点是工具模式、模型可见上下文、调用审批和外部内容污染；低代码平台侧重点是数据模式、页面扩展、动作幂等和发布回滚；开放市场侧增加签名、来源验证、恶意撤回、版本冻结和生态兼容测试。
FAQ
扩展点越多越灵活吗？
不是。每个公开扩展点都会成为长期兼容承诺。先围绕真实变化面提供少量粗粒度能力，再用使用数据决定是否拆细。
能不能真正无重启升级？
只有当运行时支持卸载、插件能停止在途工作、资源可完整释放且数据兼容时才可承诺。否则采用“下载新版本、下次安全启动切换”更可靠。
事件总线能替代接口吗？
不能。事件适合事实广播或可选观察者；需要明确结果、错误、背压和事务的调用应使用服务契约。无类型全局事件会把依赖隐藏起来。
插件崩溃如何不拖垮宿主？
先降低同进程权限并控制异常边界；高风险或不可信插件放到进程外，配合资源限额、健康探测、熔断和可恢复状态。
反模式与修正
| 反模式 | 直接后果 | 修正 |
|---|---|---|
| 插件直接访问宿主数据库 | 内部结构一改全体失效 | 只开放版本化服务能力 |
| 注册后不返回清理句柄 | 卸载残留和重复回调 | 宿主统一托管撤销栈 |
| 依赖扫描顺序决定行为 | 环境不同结果不同 | 显式依赖图与稳定排序 |
| 所有插件共用全局权限 | 单点泄漏扩大为全局事故 | 插件、租户、用户三层最小授权 |
| 只测安装，不测卸载 | 热更新后资源不断累积 | 契约测试覆盖完整生命周期 |
| 接口删除后再通知作者 | 生态突然断裂 | 使用量观测、弃用窗口和迁移器 |
| 插件错误直接冒泡到主循环 | 一个扩展拖垮宿主 | 超时、隔离、熔断和降级实现 |
按需 references
- 定义 manifest、扩展点、事件、依赖和生命周期时，读取 extension-contracts.md
- 设计权限、供应链、灰度、回滚、卸载和事故处置时，读取 security-and-rollout.md
