从旧插件迁移到 Bundle 管理器
定位 retired 插件和生命周期协议不匹配，区分作者迁移、插件实现与平台能力问题，完成后继版本发布和安装验证。
收到“已退役的插件标识不能用于新资源版本”时，应迁移插件接入。升级 CLI、补一个协议字段、 恢复旧目录记录或直接换名都不能完成迁移。先确认失败对象与目标环境，再修改资源和插件实现。
先定位失败对象
先从本机帮助确认命令与参数，再读取目标工作区的安装执行账、资源归属和版本：
baijimu --version
baijimu runtime bundle installation get --help
baijimu runtime bundle installation get "$BUNDLE_ID" --workspace-id "$WORKSPACE_ID"
baijimu bundle resource module list "$BUNDLE_ID" --workspace-id "$WORKSPACE_ID"
baijimu bundle resource module version list "$BUNDLE_ID" \
--workspace-id "$WORKSPACE_ID" --module-id "$MODULE_ID"
baijimu workspace lifecycle-plugin list --workspace-id "$WORKSPACE_ID"
baijimu workspace 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 的服务引用。
Bundle 管理器的 pluginId 应表达实际业务能力，必须由插件提供方注册并回读确认；没有通用替代 ID。
不能随意换成目录中的其他插件，也不能只改成任意新名称来通过校验。
判断是否需要 Bundle 管理器
仅调用已有无状态 API 或由用户配置已有业务服务时，可以先确认是否需要 Bundle 管理器。 只有在已经替代旧插件负责的租户创建、安装绑定、配置同步和清理职责后，才能删除旧绑定。 不能为了发布成功直接移除插件，造成安装后的租户、业务属性或授权缺失。
需要外部状态协调时，由提供方实现 Bundle 管理器并完成登记。Bundle 作者独立设置来源 Bundle 的固定管理器关系。平台按当前关系、安装和本包资源归属校验管理器操作，Runtime 安装器负责安装和恢复状态。
对齐四处契约后再修改
每次迁移都应记录以下四项证据：
- 当前 CLI 的目标子命令帮助，证明客户端支持注册和绑定所需字段。
- 插件目录回读，证明稳定身份、执行声明、协议和支持阶段已经登记。
- 插件后端已发布版本与契约测试，证明它实际接收并返回对应结构。
- 目标环境的 Runtime 能力与真实安装验证，证明执行方支持同一契约。
v1 不是精确 Semantic Version。把它改成 3.0.0、4.0.0 或 5.0.0 也不等于升级协议。
新实现统一采用来源 Bundle 的跨版本固定管理器关系，作者清单不再包含插件绑定。通信版本按管理器当前登记选择。独立引用解析接口已退役。
文档、源码或插件目录中出现某个版本，单独都不能证明目标环境已完成配套部署。
Bundle 管理器提供方按首次接入流程与验收申请一次性授权， 部署启动后握手登记执行声明并建立双向凭据；作者按 Bundle 管理器设置来源 Bundle 的固定关系，不在清单中声明资源授权。
完整迁移顺序
- 检查精确发布提交中的模块插件绑定与 Bundle 声明，列出旧插件承担的外部业务职责和现有实例。
- Bundle 管理器提供方实现并发布目标契约，按首次接入流程与验收 完成授权申请、部署握手、接入确认、引导清理和凭据恢复验证，回读管理器身份与执行声明。
- 作者移除旧模块绑定，并用
baijimu bundle manager set设置来源 Bundle 的管理器关系。业务配置使用正常配置合同，执行地址与凭据留在受控登记和存储中。 - 明确旧外部实例如何由新实现识别、接管或清理，并验证重试不会重复创建租户。未确定归属时停止迁移， 不猜测实例身份，不接受任意旧状态。
- 提交 canonical 项目源码，从精确 Git 提交创建后继模块版本，再发布引用该精确版本的后继 Bundle。 已发布不可变版本不能原地修改。需要改变 MAJOR 或 MINOR 时，先确认准确目标版本及兼容影响。
- 在明确的目标 Runtime 升级，回读安装、Operation 和各资源结果，验证外部实例、业务调用、授权和卸载行为。 仅成功创建版本或返回操作已受理，不能报告升级完成。
只迁移引用退役插件或不受支持契约的资源及其创建 Bundle 版本，不因一个资源失败而重发所有 Bundle。
其他资源当前为 ACTIVE 也不能代替它们后续升级的兼容验证。
产品不再使用时执行退役
完全停止产品时，不必先把旧插件迁移成可安装的新产品。先核对依赖和全部安装范围， 由安装方清理活动安装及失败安装，由市场管理员处理市场条目，再由来源所有者禁用并退役定义。 产品独占的后端、Endpoint、凭据和数据由对应所有者按实际归属清理，不能删除其他产品共享资源。 平台保留的不可变版本与操作审计不代表产品仍可分发或使用。
CLI 拒绝卸载没有活动版本的失败安装时，不要为了删除而重新安装产品，也不要直接删数据库记录。 提供安装身份、失败执行账和 CLI 版本，由平台确认受支持的失败安装清理入口与实际外部效果。 只有安装不可再用、市场停止分发、定义已退役且专属运行资源完成清理后，才能报告完整退役。