# Bundle 失败恢复与回滚

读取失败原因，预览完整恢复计划，恢复到精确版本或回滚到成功基线，并验证最终状态。

Bundle 安装或升级失败后，部分资源可能已经生效。平台保留失败操作与资源执行账，普通升级可能返回
“Runtime 已有未完成的 Bundle 操作”。发布修复版本不会自动替换原操作的不可变目标，也不会自动释放占用。

## 选择处理方式

| 方式   | 用途                                 |
| ---- | ---------------------------------- |
| 普通重试 | 原目标没有改变，临时故障已经消除，按原操作允许的重试路径继续     |
| 向前恢复 | 原操作停止后，依据成功基线、执行回执和实际资源，恢复到明确的修复版本 |
| 回滚   | 撤销原失败计划，恢复变更前的成功基线；不是任意选择一个旧版本     |

接口或类型合同不兼容属于确定性错误，重复提交相同内容通常仍会失败。先修正责任方并创建所需不可变版本。
不要删除操作记录、直接清空活动操作 ID，或把部分资源成功当成整个 Bundle 成功。

## Manager

工作区管理员进入 **Bundle 管理**，在失败安装上选择 **恢复** 或 **回滚**。

1. 页面读取当前失败操作与原始错误，自动携带安装身份及失败 operationId。
2. 恢复页面列出原失败计划的全部参与 Bundle。默认保留原目标；使用修复版本时填写发布方提供的精确版本 ID。
3. 点击预览，核对各 Bundle 目标版本、资源变化、跨 Bundle 方法授权与阻塞原因。
4. 确认执行，观察资源进度及最终状态。重试本次恢复时使用已经冻结的同一请求。

回滚尚未启用、成功基线缺失、插件需要补偿、资源结果未知或配置已经改变时，页面会展示后端阻塞原因。
启用回滚是平台运维动作；工作区管理员不能通过界面绕过协议检查。

## CLI 与开发 Agent

先运行 `baijimu --version` 和 `baijimu bundle --help`。只有本机帮助包含以下命令时才使用；
缺少命令时升级到已发布且支持该能力的 CLI，不根据本文猜测旧版本参数。

```bash
baijimu bundle get <bundle> --workspace-id <workspaceId> --json
baijimu bundle recovery-preview --help
baijimu bundle recover --help
```

预览并保存完整请求：

```bash
baijimu bundle recovery-preview <bundle> --workspace-id <workspaceId> \
  --version-id <exactBundleVersionId> --json > recovery-preview.json
```

CLI 从当前安装自动读取失败 operationId，并从后端发现完整计划。省略 `--version-id` 时保留原失败目标；
多个参与 Bundle 都需要修复时，可用 `--targets @targets.json` 提供完整数组，每项包含 `installId` 与
`bundleVersionId`。这些身份必须来自本次安装及后端记录。后端拒绝遗漏成员、任意新增成员和未经证明的资源漂移。

目标版本需要未经市场验证的直接分发确认时，核对发布方与分发授权后，在预览命令中增加
`--confirm-unverified`。这不会绕过分发、付费权益或工作区权限检查。

核对预览输出中的全部目标、资源变化和授权后执行：

```bash
baijimu bundle recover --workspace-id <workspaceId> \
  --request @recovery-preview.json --confirm --wait --timeout-seconds 300
```

预览包含跨 Bundle 方法访问时，执行还需要 `--confirm-runtime-method-access`。
AI 必须遵守用户授权范围，不能为了通过校验自动添加确认参数。若执行失败，先检查原因；
需要重试同一次恢复时重新提交同一个预览文件，不重新选择最新版本，不把新恢复 operationId 替换进原请求。

回滚使用独立的预览与执行命令：

```bash
baijimu bundle rollback-preview <bundle> --workspace-id <workspaceId> --json > rollback-preview.json
baijimu bundle rollback --workspace-id <workspaceId> \
  --request @rollback-preview.json --confirm --wait
```

`canRollback=false` 表示存在阻塞，不能执行。首次安装回滚可能移除已创建资源，必须明确核对影响。
CLI 超时不会取消后台操作，使用 `bundle get` 查询，不要盲目重复发起新操作。

## 接口与权限

Manager 和 CLI 使用相同的恢复流程，均要求目标工作区管理权限和 Runtime 访问权限。
命令行工具自动处理工作区认证上下文，不应手工复制令牌或拼接内部服务地址。

恢复请求的 `targets` 是包含 `installId`、`bundleVersionId` 的数组；回滚目标来自原成功基线，调用方不能改写。
`expectedOperationId` 是并发保护和审计关联，预览不预约状态，执行时仍重新校验。
恢复计划有独立且可复用的操作身份，原失败记录保留。平台内智能体只有被授予对应控制面工具时才能执行；
普通 Runtime 业务方法调用权限不等于 Bundle 管理权限。

## 成功判定

必须同时检查本次操作成功、活动操作已清空、目标版本已提交。正常恢复最终为 `ACTIVE`；
撤销首次安装最终为 `UNINSTALLED`。请求被接受、部分资源 `VERIFIED` 或预览成功都不能代替最终验证。
恢复后再验证原业务能力及后续正常升级，保留原失败操作与恢复操作的审计身份。