谁在什么时候做什么
| 操作 | 发起者 | 什么时候用 | 之后要验证 |
|---|---|---|---|
| 上传新版本 | 开发者 | 代码、内容、配置模型或权限变化 | 新版本号、重新签名、审核 |
| 隐藏版本 | 开发者主账号 | 不再推荐或提供该版本 | 现有客户的安装与支持安排 |
| 升级安装 | 客户安装管理者 | 应用已授权且兼容的新版本 | 确认新增权限，检查配置与真实调用 |
| 停用安装 | 客户安装管理者（需填写原因） | 暂停该安装提供的能力 | 页面移除、调用拒绝、新事件停止 |
| 卸载安装 | 客户安装管理者（需填写原因） | 撤销该安装 | 授权失效，回调与数据按约定处理 |
发布一个升级版本
- 递增 metadata.version，并且高于所有已审核版本。
- 确认 spec.compatibility.control_api 覆盖目标主控版本；不满足的主控不能安装或升级到这个版本，已安装的保留最近的兼容版本。
- 权限有变化时版本一律进入人工审核，客户升级时也要重新确认新增权限。
- 更新说明写清：改了什么、最低主控版本、是否新增权限、原配置如何迁移、失败怎么恢复。
升级失败时安装进入 upgrade_failed_lkg_preserved，保留最近一次有效版本。这个机制不能代替你自己的数据迁移和回退方案；回退方式取决于插件类型与平台支持的版本，请在插件说明里写清恢复步骤，不要让客户直接改数据库。
停用与卸载后的处理
停用或撤销权限后，新的业务事件和回放也会经过授权检查。外部服务要能识别授权已被撤销，停止使用已撤销的 API Key 和安装身份，不要无限重试被拒的请求，并按与客户的约定处理已持有的数据。
一次完整交付至少验证：新客户首次安装、老客户升级、普通用户与管理员分别使用、依赖不可用、权限收回、重复请求、升级失败后保留最近有效版本、卸载后页面、调用与事件全部停止。
常见问题先这样排查
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 进不了“我的插件” | 入驻状态、当前主体、团队权限 | 由主账号核对申请和成员权限 |
| 公钥验证失败 | 挑战是否过期、是否复制完整、私钥是否对应 | 重新获取挑战再签名 |
| 命名空间冲突 | 是否已被其他发布者认领、是否用了保留前缀 | 使用自己的命名空间 |
| 签名或摘要不符 | 文件是否来自同一次打包、签名后是否改过 | 从源文件重新打包签名 |
| 工具退出 0 却没有产物 | 终端是否打印了预检与产物行 | 用 pwd -P 得到的真实路径重新执行并核对文件 |
| 提示版本已存在 | 版本列表与详情 | 已创建就继续处理；要改文件就递增版本 |
| 审核通过但客户看不到 | 是否公开、渠道、兼容范围、价格计划 | 逐项核对，不要重复改文件 |
| 已获取但没有功能 | 是否确认安装、启用、完成配置，当前角色 | 用目标角色在实际挂载位置验证 |
| 免费插件只有资料不能获取 | 是否有金额为零的生效价格计划 | 主账号在“定价”里添加 |
| 调用被拒绝 | 安装是否有效、批准的权限、凭据类型与作用域 | 按接口的认证方式处理，不要换更高权限账号 |
联系支持时提供：插件 ID、版本、操作时间、request_id、错误码和脱敏截图。不要提交密码、私钥、API secret、Webhook secret 或原始客户数据。