旧插件迁移与发布错误处理

定位 retired 插件和生命周期协议不匹配，区分作者迁移、插件实现与平台能力问题，完成后继版本发布和安装验证。

收到“已退役的插件标识不能用于新资源版本”时，应迁移插件接入。升级 CLI、补一个协议字段、恢复旧目录记录或直接换名都不能完成迁移。先确认失败对象与目标环境，再修改资源和插件实现。

先定位失败对象

先从本机帮助确认命令与参数，再读取目标工作区的安装执行账、资源归属和版本：

baijimu --version
baijimu bundle get --help
baijimu bundle get "$BUNDLE_ID" --workspace-id "$WORKSPACE_ID"
baijimu bundle module list "$BUNDLE_ID" --workspace-id "$WORKSPACE_ID"
baijimu bundle module version list "$BUNDLE_ID" \
  --workspace-id "$WORKSPACE_ID" --module-id "$MODULE_ID"
baijimu lifecycle-plugin list --workspace-id "$WORKSPACE_ID"
baijimu lifecycle-plugin get "$PLUGIN_ID" --workspace-id "$WORKSPACE_ID"

变量来自平台记录，不能把案例的工作区、项目、模块、Bundle 或插件身份复制到其他项目。区分 Bundle 的来源工作区与安装工作区；模块版本在来源 Bundle 下查询。保存失败阶段、稳定资源身份、当前版本、目标版本、Operation ID、错误码和脱敏错误信息。安装执行账中的 PENDING 表示该资源尚未完成执行，不能据此判定它自身有错误。

失败位置或信息	含义	处理方与动作
创建模块版本时报插件已退役	当前源码仍绑定禁止用于新版本的旧插件	作者检查精确 Git 提交的模块声明，并与插件提供方完成迁移
必须显式使用当前插件生命周期协议版本	绑定缺少协议或与执行方支持的契约不一致	对齐注册、绑定、插件实现和目标 Runtime，再创建后继版本
CLI 没有需要的参数	当前客户端不支持该命令合同	查本机版本和帮助，使用明确支持该能力的 CLI
CLI 有参数，但目录仍返回另一种协议或平台拒绝对应结构	尚不能证明整条执行链支持目标契约	向平台提供脱敏证据，确认环境能力和配套迁移；不能继续猜字段
插件响应不符合 CModel，或下游返回 502/404	还需定位执行地址、可达性和响应合同	插件提供方与平台分别检查各自边界，不能都归因于退役

退役标识与普通停用不同

external-managed 和 http-proxy 是已退役且禁止复用的旧插件标识。它们不能用于新资源版本，也不能通过重新注册或恢复旧记录重新成为受支持插件。普通插件的所有者停用操作与这种协议级退役不同。

旧模块里的数字 config.serviceId 属于旧接入方式，不是新插件身份，不能改写成 Runtime 的服务引用。新插件的 pluginId 应表达实际业务能力，必须由插件提供方注册并回读确认；没有通用替代 ID。不能随意换成目录中的其他插件，也不能只改成任意新名称来通过校验。

判断是否需要插件

仅调用已有无状态 API 或由用户配置已有业务服务时，先确认是否根本不需要生命周期插件。只有在已经替代旧插件负责的租户创建、安装绑定、配置同步和清理职责后，才能删除旧绑定。不能为了发布成功直接移除插件，造成安装后的租户、业务属性或授权缺失。

需要外部状态协调时，由插件提供方实现原生生命周期服务。Bundle 作者负责声明使用哪个已注册插件、允许访问哪些资源和属性；Runtime 安装器负责安装和恢复状态。插件不能修改平台安装账。

对齐四处契约后再修改

每次迁移都应记录以下四项证据：

当前 CLI 的目标子命令帮助，证明客户端支持注册和绑定所需字段。
插件目录回读，证明稳定身份、执行声明、协议和支持阶段已经登记。
插件后端已发布版本与契约测试，证明它实际接收并返回对应结构。
目标环境的 Runtime 能力与真实安装验证，证明执行方支持同一契约。

v1 不是精确 Semantic Version。把它改成 3.0.0、4.0.0 或 5.0.0 也不等于升级协议。新实现统一采用 Bundle 顶层插件绑定。Bundle 生命周期和引用访问属于不同合同，不能互换版本号或拼接字段。文档、源码或插件目录中出现某个版本，单独都不能证明目标环境已完成配套部署。

当前 CLI 使用 --bundle-execution，不再使用旧的顶层执行地址、协议和 Hook 参数注册插件。应使用对应的插件注册与管理及 Bundle 插件绑定合同；如果目标环境仍只提供旧声明，先由平台完成能力对齐，再执行作者迁移。

完整迁移顺序

检查精确发布提交中的模块插件绑定与 Bundle 声明，列出旧插件承担的外部业务职责和现有实例。
插件提供方实现并发布目标契约，注册稳定插件身份并回读；由插件注册者自助完成双向调用凭据配置和验证。当前目录管理 CLI 不会自动签发或配置这些凭据。
作者更新绑定、配置及显式属性授权。改为 Bundle 级接入时，按 Bundle 合同声明插件，移除旧模块绑定；不把旧 Hook 请求改名后塞进 Bundle 请求，也不把执行地址或凭据写进发布内容。
明确旧外部实例如何由新实现识别、接管或清理，并验证重试不会重复创建租户。未确定归属时停止迁移，不猜测实例身份，不接受任意旧状态。
提交 canonical 项目源码，从精确 Git 提交创建后继模块版本，再发布引用该精确版本的后继 Bundle。已发布不可变版本不能原地修改。需要改变 MAJOR 或 MINOR 时，先确认准确目标版本及兼容影响。
在明确的目标 Runtime 升级，回读安装、Operation 和各资源结果，验证外部实例、业务调用、授权和卸载行为。仅成功创建版本或返回操作已受理，不能报告升级完成。

只迁移引用退役插件或不受支持契约的资源及其创建 Bundle 版本，不因一个资源失败而重发所有 Bundle。其他资源当前为 ACTIVE 也不能代替它们后续升级的兼容验证。

产品不再使用时执行退役

完全停止产品时，不必先把旧插件迁移成可安装的新产品。先核对依赖和全部安装范围，由安装方清理活动安装及失败安装，由市场管理员处理市场条目，再由来源所有者禁用并退役定义。产品独占的后端、Endpoint、凭据和数据由对应所有者按实际归属清理，不能删除其他产品共享资源。平台保留的不可变版本与操作审计不代表产品仍可分发或使用。

CLI 拒绝卸载没有活动版本的失败安装时，不要为了删除而重新安装产品，也不要直接删数据库记录。提供安装身份、失败执行账和 CLI 版本，由平台确认受支持的失败安装清理入口与实际外部效果。只有安装不可再用、市场停止分发、定义已退役且专属运行资源完成清理后，才能报告完整退役。