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

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

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

## 先定位失败对象

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

```bash
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 安装器负责安装和恢复状态。插件不能修改平台安装账。

## 对齐四处契约后再修改

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

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

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

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

## 完整迁移顺序

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

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

## 产品不再使用时执行退役

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

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