docs: plan enterprise backup and recovery

2026-06-06 16:42:24 +08:00
parent 9e81d8a960
commit a7e4b96ce3
1 changed files with 878 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-06-enterprise-safety-backup-recovery-design.md
+++ b/docs/superpowers/specs/2026-06-06-enterprise-safety-backup-recovery-design.md
@@ -0,0 +1,878 @@
+# Boss 企业级稳定性、备份、回退与容灾开发文档
+
+状态：已确认，待拆分实施计划  
+日期：2026-06-06  
+适用版本：Boss vNext 企业交付版  
+关联文档：
+
+- `README.md`
+- `docs/architecture/ai_handoff_index_cn.md`
+- `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- `docs/architecture/api_and_service_inventory_cn.md`
+- `docs/architecture/enterprise_ai_ops_architecture_cn.md`
+- `docs/superpowers/specs/2026-06-06-boss-edge-reliability-design.md`
+
+## 1. 文档目标
+
+本版本目标不是继续堆功能，而是把 Boss 从“能控制电脑和 Codex 的工具”升级成“企业客户敢长期使用的生产系统”。
+
+本版本要解决的问题：
+
+1. APP 发起任务后不能长时间卡在第一步，必须有可恢复状态、超时状态和明确下一步。
+2. 主 Agent、Codex 线程、Computer Use、本地 agent 和云端之间不能丢消息、重复执行或假成功。
+3. 关键数据、配置、权限、项目目标、版本记录、Skill、任务和审计必须能备份、校验、恢复和追溯。
+4. 用户误操作、AI 错误接管、线程错误执行、权限误授权、Skill 升级失败后，必须能按业务维度回退。
+5. 企业管理员和平台管理员要能从后台清楚看到风险、备份状态、可恢复点、执行异常和处理记录。
+6. 后续 Codex App Server、Codex Remote Control、Computer Use、Skill Runtime 和第三方 provider 更新时，Boss 不需要推倒重做。
+
+一句话目标：让企业客户相信 Boss 即使遇到断网、设备离线、执行器崩溃、AI 误操作、数据误改，也能知道发生了什么、找回关键数据、恢复业务链路、追责并继续推进。
+
+## 1.1 企业客户能感知到的安全承诺
+
+这套能力对外不能只讲“我们有备份”，要让客户看到可验证的承诺：
+
+1. 数据不会因为单点故障直接丢失。
+2. 关键操作前会自动生成恢复点。
+3. 误操作后能先预览影响范围，再执行回退。
+4. AI 接管、Computer Use、Skill 升级和权限变更都有审计。
+5. 断网、设备离线、本地 agent 重启后，任务回写不会静默丢失。
+6. 管理员能看到最近备份时间、最近恢复演练、失败恢复记录和风险项。
+7. 平台方能在不默认读取企业业务正文的前提下协助客户排障。
+
+客户可见话术应保持克制：当前文件 MVP 阶段只承诺“可见快照、可预览恢复、可审计恢复”；数据库量产阶段再承诺更强 RPO/RTO。
+
+## 2. 当前已有能力
+
+当前仓库已经有一批可靠性和备份基础，不能重复造轮子。
+
+### 2.1 状态文件与快照
+
+当前事实源仍是 `data/boss-state.json`。
+
+已有能力：
+
+- `src/lib/boss-state-store.ts` 支持文件状态原子写入。
+- `src/lib/boss-state-store.ts` 已支持自动快照。
+- `BOSS_STATE_AUTO_BACKUP_ENABLED` 控制是否启用自动快照。
+- `BOSS_STATE_AUTO_BACKUP_INTERVAL_MS` 控制自动快照间隔。
+- `BOSS_STATE_AUTO_BACKUP_KEEP` 控制自动快照保留数量。
+- `src/lib/boss-state-backups.ts` 支持手动创建快照、列出快照、恢复快照。
+- `POST /api/v1/admin/backups` 已支持 `create_snapshot` 和 `restore_snapshot`。
+- 恢复快照前会自动创建 `pre-restore` 快照，避免恢复动作本身不可逆。
+- `scripts/boss-state-store-maintenance.mjs` 已支持文件备份、PostgreSQL 迁移 dry-run、PostgreSQL 导出、恢复和回退到文件。
+
+当前不足：
+
+- 当前快照是全局状态级，缺少企业租户级、项目级、会话级和配置级恢复体验。
+- 当前快照校验主要在创建/读取层，缺少后台可视化校验状态和定期恢复演练记录。
+- 当前恢复动作还偏底层状态恢复，缺少业务级恢复预览、影响范围说明和审批。
+- 当前没有明确区分“文件 MVP 备份”和“量产数据库备份”的产品状态。
+
+### 2.2 任务可靠执行
+
+已有能力：
+
+- `MasterAgentTask` 已有任务状态、设备认领、完成回写和取消入口。
+- 近期可靠性壳已经引入 `phase / lastProgressAt / lastErrorCode / recoverable / nextRetryAt` 等字段。
+- `local-agent/reliable-outbox.mjs` 已作为本地 outbox 草案存在，用于持久化 `task.progress / task.complete / app.log`。
+- `POST /api/v1/master-agent/tasks/[taskId]/progress` 已可接收执行中进度。
+- `local-agent/server.mjs` 已能回写进度和最终结果。
+- `Codex App Server runner` 已经把 Codex plan、diff、approval、warning、file change、thread status、tool activity、stream delta 等归一成 Boss `execution_progress`。
+
+当前不足：
+
+- 任务恢复策略还没有产品化展示成“等待、恢复中、可重试、已中止、需人工处理”。
+- 本地 outbox 与云端任务 watchdog 还需要补充更完整的压力测试和异常注入测试。
+- APP 侧需要把进度卡从“展示状态”升级为“可操作恢复面板”。
+- 后台需要能看见任务卡住原因、所在 phase、最后一次 progress、设备健康和重试建议。
+
+### 2.3 业务级回退
+
+已有能力：
+
+- Codex App Server 线程回滚：`POST /api/v1/projects/[projectId]/thread-rollback`。
+- Codex App Server 线程压缩：`POST /api/v1/projects/[projectId]/thread-compact`。
+- Codex App Server 线程归档/恢复：`POST /api/v1/projects/[projectId]/thread-archive`。
+- Codex App Server 线程改名、目标同步、Git 元数据同步、线程分叉。
+- Skill 生命周期已有安装前备份、失败恢复、回滚和版本锁。
+- 权限变更已有审计日志。
+- 消息删除已有服务端账本删除能力。
+
+当前不足：
+
+- 这些能力分散在不同页面和接口，用户还不能按“我刚才做错了，帮我恢复”这种业务语言触发统一恢复。
+- 项目目标、版本记录、会话消息、权限、Skill、设备接管、主 Agent 托管还没有统一恢复点模型。
+- Codex 线程回滚只回滚线程历史，不自动回滚代码文件，必须在 UI 里明确边界。
+- Computer Use 错误点击的恢复主要靠确认和审计，还缺少动作前 checkpoint、动作后证据留档和恢复建议。
+
+## 3. 本版本推荐方案
+
+推荐采用 B+ 方案：`Boss Cloud 控制面 + Boss Edge 可靠执行面 + 多层恢复点 + 业务级回退`。
+
+### 3.1 不采用的方案
+
+方案 A：只增强当前文件快照。
+
+- 优点：开发快。
+- 缺点：只能解决最粗粒度的数据恢复，不能解决任务卡住、消息丢失、业务误操作、租户级恢复和企业后台可观测。
+- 结论：只能作为本版本的基础，不足以支撑企业交付。
+
+方案 C：立即全面切 PostgreSQL + 完整灾备平台。
+
+- 优点：最接近量产终态。
+- 缺点：改动面过大，会把当前 Codex/App/Android/后台主链全部拖进迁移风险。
+- 结论：作为后续阶段，不作为本版本第一批开发入口。
+
+### 3.2 推荐方案 B+
+
+本版本先不改变整体部署形态，先把现有系统升级出企业可靠性外壳：
+
+```text
+Boss APP / 企业后台 / 平台后台
+  -> Boss Cloud 控制面
+  -> 任务账本、审计账本、备份账本、恢复点账本
+  -> Boss Edge / local-agent
+  -> durable outbox、task journal、executor health、Codex App Server、Computer Use
+  -> Codex Desktop / Codex CLI / CUA Driver / Browser Runtime / Skill Runtime
+```
+
+关键原则：
+
+- Boss Cloud 是企业控制面和最终业务账本。
+- Boss Edge 是本地可靠执行面，不再只是“轮询脚本”。
+- Codex App Server、Codex CLI、Computer Use 和 Skill 都是 provider，不是最终业务事实源。
+- 每个高风险动作前创建恢复点。
+- 每个执行任务都有阶段、租约、幂等 key、outbox、超时处理和安全错误摘要。
+- 每个恢复动作都有审批、影响范围、pre-restore 快照和审计。
+
+## 4. 本版本开发范围
+
+### 4.1 可靠执行层
+
+目标：任何任务都不能无限卡住，任何回写都不能因为短暂网络问题直接丢失。
+
+要开发的功能：
+
+1. 任务阶段正式产品化。
+   - `queued`：云端已创建，等待设备认领。
+   - `claimed`：设备已认领，尚未启动执行器。
+   - `executor_starting`：正在准备 Codex App Server / CLI / Computer Use。
+   - `turn_started`：目标 Codex turn 或桌面动作已启动。
+   - `awaiting_reply`：执行器已接管，等待最终结果。
+   - `completing`：本地已拿到结果，正在回写云端。
+   - `completed`：云端已持久化最终结果。
+   - `recoverable_failed`：可恢复失败，可重试但不能静默重试危险动作。
+   - `terminal_failed`：不可自动恢复，需要用户或管理员处理。
+   - `timed_out`：超过租约或执行超时。
+   - `canceled`：用户或系统取消。
+   - `needs_user_action`：需要用户确认、授权或处理弹窗。
+
+2. APP 进度卡升级。
+   - 显示当前 phase 的中文解释。
+   - 显示最后更新时间。
+   - 显示执行器健康：可用、降级、不可用。
+   - 显示“继续等待 / 重试 / 中断 / 查看详情”。
+   - `turn_started` 后不允许自动重复下发同一任务。
+   - 失败时显示人话原因，不显示系统提示词、内部 prompt、路径、密钥、命令原文。
+
+3. 本地 Edge outbox。
+   - `task.progress` 先写本地 outbox，再发云端。
+   - `task.complete` 先写本地 outbox，再发云端。
+   - `app.log` 先写本地 outbox，再发云端。
+   - 网络失败、云端 5xx、local-agent 重启后自动重放。
+   - complete 必须带幂等 key。
+   - 云端终态任务不被迟到 complete 覆盖。
+
+4. 云端 watchdog。
+   - 清理过期 queued 任务，防止历史任务在修复后突然执行。
+   - 识别 running 但长时间无 progress 的任务。
+   - 对 `turn_started` 前失败可进入 `recoverable_failed`。
+   - 对 `turn_started` 后失败进入人工处理，不自动换 provider 重跑。
+   - 后台展示 watchdog 处理记录。
+
+5. provider 健康分级。
+   - `available`：设备在线，Codex App Server 初始化成功，线程操作可用。
+   - `degraded`：设备在线但 discovery 有失败或最近有可恢复错误。
+   - `unavailable`：设备离线、未登录、App Server 断连、连续失败或权限缺失。
+   - 调度顺序：健康 Codex App Server -> CLI fallback -> 用户 API fallback -> 明确提示无可用模型渠道。
+
+### 4.2 数据备份层
+
+目标：全局状态、企业数据、附件、配置和执行证据都有可恢复点。
+
+要开发的功能：
+
+1. 备份账本。
+   - 新增统一 `backupSnapshots` 视图或投影。
+   - 记录 `snapshotId / scope / companyId / projectId / actor / reason / createdAt / sha256 / bytes / schemaVersion / status`。
+   - `scope` 支持 `global / company / project / conversation / config / skill / task`。
+   - 当前文件快照继续作为底层实现，前台展示成统一恢复点。
+
+2. 自动备份策略。
+   - 定时自动快照。
+   - 关键变更前快照。
+   - 手动快照。
+   - 恢复前快照。
+   - 备份保留策略。
+   - 备份失败告警。
+
+3. 租户级导出。
+   - 平台最高管理员可按企业导出企业数据包。
+   - 企业超级管理员可导出本企业授权范围内的数据包。
+   - 导出包包含项目、会话、版本记录、项目目标、权限、Skill 授权、任务摘要、审计摘要。
+   - 导出包不包含系统提示词、API key、restore token、session token、设备 token、未脱敏命令输出。
+
+4. 附件和产物备份。
+   - 备份只保存附件 manifest、对象存储 key、sha256、大小、上传者、所属租户和访问策略。
+   - 不把大文件直接塞进状态 JSON。
+   - 后续对象存储做跨区域复制或定期导出。
+
+5. 备份校验。
+   - 每个快照保存 sha256。
+   - 后台显示最近一次校验结果。
+   - 支持 dry-run restore，验证快照能被解析和迁移。
+   - 支持恢复演练记录。
+
+### 4.3 业务级回退层
+
+目标：用户不需要理解底层 JSON 快照，也能按业务动作恢复。
+
+要开发的功能：
+
+1. 会话消息恢复。
+   - 消息删除改成软删除优先。
+   - 支持恢复最近删除消息。
+   - 支持按会话恢复到某个消息时间点。
+   - 多选删除或转发相关操作写入审计。
+
+2. 项目目标恢复。
+   - 每次编辑项目目标生成目标版本。
+   - 支持恢复上一版。
+   - 支持对比当前版和历史版。
+   - 主 Agent 同步项目目标时也要写目标版本。
+
+3. 版本记录恢复。
+   - 版本记录只追加，不直接覆盖。
+   - 错误版本记录可标记作废。
+   - 支持恢复到某条版本记录之前的展示状态。
+   - 保留“谁生成、谁确认、关联任务”的审计字段。
+
+4. 权限恢复。
+   - 权限授权和撤销记录变成可回放事件。
+   - 支持撤销最近一次授权变更。
+   - 支持按账号、设备、项目、Skill 查看权限变更时间线。
+   - 高危授权恢复必须要求最高管理员确认。
+
+5. Skill 恢复。
+   - 复用已有 Skill 安装前备份。
+   - 后台展示每台设备的 Skill 版本、锁定状态、最近升级结果、可回滚版本。
+   - 升级失败自动恢复上一版。
+   - 企业管理员可按授权范围触发回滚，平台管理员可跨企业处理。
+
+6. 主 Agent 接管恢复。
+   - 开启接管前创建接管 checkpoint。
+   - 关闭接管时清理 queued 主动任务。
+   - 如果接管导致线程异常，支持一键退出接管并恢复用户直连线程。
+   - 接管期间的所有主 Agent 转述、下发、取消、失败都进入审计。
+
+7. Codex 线程恢复。
+   - 支持 Codex App Server `thread/rollback`，但 UI 必须明确只回滚线程历史。
+   - 支持线程分叉，在不破坏原线程的前提下继续试验。
+   - 支持线程压缩前创建 Boss 业务 checkpoint。
+   - 支持 Git 元数据同步，后续接入代码级 checkpoint。
+
+8. 代码和文件恢复。
+   - 开发任务默认建议独立分支。
+   - 高风险代码修改前记录 Git HEAD、branch、diff summary。
+   - 如果 provider 支持，执行前创建 checkpoint。
+   - 代码回退优先用 Git revert/checkout，不用状态 JSON 恢复代替代码恢复。
+   - APP 和后台只展示摘要，不展示完整 diff 和命令输出。
+
+9. Computer Use 恢复。
+   - 高风险动作前必须确认。
+   - 每个桌面动作保存安全截图摘要或动作证据索引。
+   - 未知弹窗进入 `needs_user_action`，不自动点击。
+   - 错误点击后提供“停止任务 / 查看证据 / 重新下发更安全指令”。
+   - 支付、删除、发送、提交、授权等动作默认不静默执行。
+
+### 4.4 灾备与企业交付层
+
+目标：企业客户能看到明确的安全承诺和恢复能力。
+
+要开发的功能：
+
+1. RPO/RTO 展示。
+   - 文件 MVP 阶段：展示实际最近备份时间和快照数量，不虚标。
+   - 数据库量产阶段：目标 RPO 15 分钟，关键客户可配置 5 分钟。
+   - 数据库量产阶段：目标 RTO 普通故障 1 小时，关键链路 15 分钟内恢复。
+
+2. 灾备策略分层。
+   - L1：本地文件 `.bak` 和自动快照。
+   - L2：Boss Cloud 快照与恢复点。
+   - L3：对象存储附件/产物备份。
+   - L4：PostgreSQL WAL + 全量备份 + 增量备份。
+   - L5：跨区域备份与恢复演练。
+
+3. 恢复演练。
+   - 管理后台显示最近一次恢复演练。
+   - 支持 dry-run restore。
+   - 演练结果记录耗时、结果、失败原因。
+   - 失败进入风险台。
+
+4. 客户成功视图。
+   - 平台后台按企业展示备份健康度。
+   - 展示设备在线、任务失败、备份过期、恢复失败、权限异常、Skill 失败。
+   - 客户成功人员能看到风险摘要，但默认不展开企业业务正文。
+
+5. 企业后台视图。
+   - 企业超级管理员看到本企业备份状态。
+   - 能创建手动快照。
+   - 能恢复企业范围内业务对象。
+   - 能看到恢复影响范围。
+   - 高风险恢复需要二次确认。
+
+### 4.5 安全与审计层
+
+目标：备份和恢复不能成为新的安全漏洞。
+
+要开发的功能：
+
+1. 权限控制。
+   - 全局快照只允许平台最高管理员。
+   - 企业级快照允许企业超级管理员。
+   - 项目级恢复要求项目管理权限。
+   - 线程级恢复要求项目可见和主 Agent 使用权限。
+   - Skill 回滚要求 Skill 管理权限。
+
+2. 敏感字段脱敏。
+   - 不备份明文 API key。
+   - 不导出 session token。
+   - 不导出 restore token。
+   - 不导出设备 token。
+   - 不导出系统提示词和内部调度 prompt。
+   - 不导出 raw Codex App Server item、命令原文、命令输出、MCP tool arguments。
+
+3. 审计字段。
+   - `actorAccount`
+   - `actorRole`
+   - `companyId`
+   - `targetType`
+   - `targetId`
+   - `action`
+   - `reason`
+   - `beforeHash`
+   - `afterHash`
+   - `snapshotId`
+   - `requestId`
+   - `ipAddress`
+   - `userAgent`
+   - `createdAt`
+
+4. 审计不可抵赖。
+   - 恢复动作不能只改状态，必须写审计。
+   - 恢复前自动创建 pre-restore 快照。
+   - 恢复后记录恢复结果。
+   - 失败也要记录失败原因和下一步建议。
+
+### 4.6 客户安心交付包
+
+目标：把底层备份和恢复能力包装成企业用户能理解、能验收、能长期信任的交付能力。
+
+#### 4.6.1 数据安全总览
+
+企业后台需要提供一个总览页，展示：
+
+- 最近一次成功备份时间。
+- 当前可恢复点数量。
+- 最近一次恢复演练时间和结果。
+- 当前未处理恢复风险。
+- 当前离线设备数量。
+- 当前失败任务数量。
+- 当前 Skill 升级失败数量。
+
+平台后台需要按企业聚合展示：
+
+- 备份健康：正常、过期、失败、从未备份。
+- 恢复健康：最近演练成功、最近演练失败、未演练。
+- 任务健康：卡住任务、重复失败任务、需人工处理任务。
+- 设备健康：在线、离线、降级、未授权。
+
+#### 4.6.2 RPO/RTO 分级承诺
+
+当前阶段必须如实展示能力，不虚标。
+
+| 阶段 | 适用对象 | RPO | RTO | 说明 |
+| --- | --- | --- | --- | --- |
+| 文件 MVP | 当前 Boss 文件状态模式 | 以最近成功快照为准 | 人工恢复，目标 30-60 分钟 | 适合内测和早期客户，重点是可见、可恢复、可审计 |
+| 企业标准 | PostgreSQL + 对象存储 | 15 分钟 | 15-30 分钟 | 适合正式企业交付 |
+| 企业增强 | PostgreSQL WAL + 异地备份 + Edge 缓存 | 5 分钟 | 10-15 分钟 | 适合高频生产协作客户 |
+| 企业高级 | 多区域备份 + 定期恢复演练 | 1 分钟级 | 5-10 分钟 | 适合强 SLA 客户，后续单独销售 |
+
+#### 4.6.3 恢复演练报告
+
+恢复演练不是可选项，企业版必须内置。
+
+报告应包含：
+
+- 演练时间。
+- 演练范围。
+- 使用的快照。
+- dry-run 校验结果。
+- 实际恢复耗时。
+- 恢复后校验结果。
+- 失败原因。
+- 下一步处理建议。
+- 操作人和审批人。
+
+#### 4.6.4 误操作保护
+
+所有高风险操作默认 fail closed。
+
+高风险操作包括：
+
+- 删除企业、账号、设备、项目、线程。
+- 批量撤销权限。
+- 主 Agent 全局接管。
+- Skill 批量升级或卸载。
+- Computer Use 执行发送、提交、支付、删除、授权等动作。
+- Codex 线程回滚、归档、压缩。
+- 恢复全局或企业快照。
+
+统一策略：
+
+- 执行前自动创建恢复点。
+- 执行前展示影响范围。
+- 执行时写任务 journal。
+- 执行后写审计和结果摘要。
+- 失败时进入风险台，不静默吞掉。
+
+#### 4.6.5 企业交付验收项
+
+交付给企业前必须能现场验证：
+
+1. 创建企业快照。
+2. 修改项目目标后恢复上一版。
+3. 修改版本记录后作废或恢复。
+4. 删除一条会话消息后恢复。
+5. Skill 升级失败后回滚。
+6. 权限误授权后撤销。
+7. APP 发起任务时断网，恢复后结果能回写。
+8. local-agent 重启后 outbox 能继续重放。
+9. 主 Agent 接管失败后能退出接管并清理主动任务。
+10. 后台能看到恢复报告和审计。
+
+## 5. 需要新增或强化的数据模型
+
+本版本仍可落在 `BossState` 文件模式上，但字段要按未来数据库化设计。
+
+### 5.1 BackupSnapshot
+
+```ts
+type BackupSnapshot = {
+  snapshotId: string;
+  scope: "global" | "company" | "project" | "conversation" | "config" | "skill" | "task";
+  companyId?: string;
+  projectId?: string;
+  conversationId?: string;
+  taskId?: string;
+  actorAccount: string;
+  reason: string;
+  createdAt: string;
+  sha256: string;
+  bytes: number;
+  schemaVersion?: number;
+  storageKind: "file" | "object_storage" | "postgres_export";
+  status: "ready" | "verifying" | "invalid" | "restored" | "deleted";
+  verification?: {
+    checkedAt: string;
+    ok: boolean;
+    message?: string;
+  };
+};
+```
+
+### 5.2 RestoreJob
+
+```ts
+type RestoreJob = {
+  restoreJobId: string;
+  snapshotId: string;
+  scope: BackupSnapshot["scope"];
+  actorAccount: string;
+  reason: string;
+  status: "previewing" | "pending_confirmation" | "running" | "completed" | "failed" | "canceled";
+  impactSummary: string;
+  preRestoreSnapshotId?: string;
+  startedAt?: string;
+  completedAt?: string;
+  errorCode?: string;
+  auditId?: string;
+};
+```
+
+### 5.3 BusinessCheckpoint
+
+```ts
+type BusinessCheckpoint = {
+  checkpointId: string;
+  scope: "task" | "project" | "conversation" | "codex_thread" | "skill" | "permission" | "computer_use";
+  targetId: string;
+  taskId?: string;
+  createdAt: string;
+  createdBy: "system" | "user" | "master_agent";
+  reason: string;
+  refs: {
+    stateSnapshotId?: string;
+    codexThreadRef?: string;
+    gitSha?: string;
+    skillBackupId?: string;
+    evidenceId?: string;
+  };
+};
+```
+
+### 5.4 TaskJournalEntry
+
+```ts
+type TaskJournalEntry = {
+  journalId: string;
+  taskId: string;
+  phase: string;
+  eventType: "claimed" | "progress" | "complete" | "retry" | "timeout" | "cancel" | "recover";
+  deviceId?: string;
+  providerId?: string;
+  idempotencyKey: string;
+  createdAt: string;
+  safeSummary: string;
+  errorCode?: string;
+};
+```
+
+## 6. API 开发规划
+
+### 6.1 备份 API
+
+保留现有：
+
+- `GET /api/v1/admin/backups`
+- `POST /api/v1/admin/backups` with `create_snapshot`
+- `POST /api/v1/admin/backups` with `restore_snapshot`
+
+新增或强化：
+
+- `POST /api/v1/admin/backups` with `verify_snapshot`
+- `POST /api/v1/admin/backups` with `preview_restore`
+- `POST /api/v1/admin/backups` with `dry_run_restore`
+- `GET /api/v1/admin/backups/[snapshotId]`
+- `GET /api/v1/admin/backups/status`
+
+### 6.2 业务恢复 API
+
+新增：
+
+- `GET /api/v1/projects/[projectId]/recovery-points`
+- `POST /api/v1/projects/[projectId]/recovery-points`
+- `POST /api/v1/projects/[projectId]/restore`
+- `POST /api/v1/projects/[projectId]/messages/restore`
+- `POST /api/v1/projects/[projectId]/goals/restore`
+- `POST /api/v1/projects/[projectId]/versions/restore`
+- `POST /api/v1/admin/access/restore`
+- `POST /api/v1/admin/skills/requests` 复用 `rollback`，但补恢复点关联字段
+
+### 6.3 任务恢复 API
+
+新增或强化：
+
+- `GET /api/v1/master-agent/tasks/[taskId]/recovery`
+- `POST /api/v1/master-agent/tasks/[taskId]/retry`
+- `POST /api/v1/master-agent/tasks/[taskId]/interrupt`
+- `POST /api/v1/master-agent/tasks/[taskId]/mark-resolved`
+- `GET /api/v1/devices/[deviceId]/task-health`
+
+### 6.4 后台 BFF
+
+强化：
+
+- `GET /api/v1/admin/backoffice`
+
+新增字段：
+
+- `backupStatus`
+- `restorePointSummary`
+- `staleTaskSummary`
+- `edgeHealthSummary`
+- `recoveryDrillSummary`
+- `businessRollbackSummary`
+- `tenantBackupHealth`
+
+## 7. UI 开发规划
+
+### 7.1 平台总后台
+
+页面：`数据安全与容灾`
+
+模块：
+
+- 全平台备份健康总览。
+- 企业备份健康排行。
+- 过期备份风险。
+- 恢复失败风险。
+- 最近恢复演练。
+- 全局快照列表。
+- 企业数据导出任务。
+- 高危恢复审计。
+
+平台管理员可做：
+
+- 创建全局快照。
+- 查看企业备份状态。
+- 发起恢复演练。
+- 对异常企业创建客户成功工单。
+- 查看不含业务正文的风险摘要。
+
+### 7.2 企业管理后台
+
+页面：`备份与回退`
+
+模块：
+
+- 本企业备份状态。
+- 最近恢复点。
+- 项目级恢复点。
+- 会话级恢复点。
+- 版本记录恢复。
+- 项目目标恢复。
+- Skill 回滚。
+- 权限变更撤销。
+- 恢复影响预览。
+
+企业管理员可做：
+
+- 创建企业快照。
+- 预览恢复影响。
+- 恢复项目目标或版本记录。
+- 恢复最近误删消息。
+- 回滚 Skill。
+- 撤销权限误授权。
+
+### 7.3 Boss APP
+
+页面和组件：
+
+- 聊天进度卡：显示 phase、最后更新时间、可操作恢复按钮。
+- 会话信息页：增加“恢复与回退”入口。
+- 项目目标页：增加历史版本和恢复。
+- 版本记录页：增加作废和恢复。
+- 主 Agent 对话：支持“帮我恢复刚才误操作”自然语言入口。
+- 设备详情页：显示 Edge 健康、outbox 待发送数、最近一次任务恢复。
+
+APP 交互原则：
+
+- 不展示数据库、JSON、raw event 等底层概念。
+- 用户看到的是“这件事卡在哪、能不能恢复、下一步点什么”。
+- 高风险恢复必须二次确认。
+
+## 8. 开发分阶段
+
+### 8.0 第一批优先级
+
+第一批不要贪多，先做最能提升企业信任的闭环：
+
+1. `数据安全总览`：平台后台和企业后台都能看到备份健康、任务风险、恢复风险。
+2. `BackupSnapshot 投影`：把现有文件快照产品化成统一恢复点。
+3. `手动快照 + 自动快照展示`：让管理员能看到快照从哪里来、什么时候生成、是否可用。
+4. `preview_restore / dry_run_restore`：恢复前先展示影响范围，不直接写状态。
+5. `pre-restore 快照`：任何恢复动作前自动创建安全备份。
+6. `恢复审计和恢复报告`：恢复成功和失败都能追责。
+7. `任务卡住风险台`：把 long-running、stale、recoverable、needs_user_action 任务聚合到后台。
+8. `APP 进度卡状态解释`：用户在手机上能看懂“卡在哪、是否还能等、能点什么”。
+
+这批完成后，Boss 就能对企业客户说明：当前版本已经具备基础数据安全、误操作可恢复、任务异常可追踪和恢复动作可审计能力。
+
+### 第一阶段：可靠执行闭环产品化
+
+目标：解决 APP 卡第一步、回写丢失、任务状态不清晰。
+
+开发内容：
+
+- 完善 task phase 到 APP/后台展示。
+- 完善 outbox 重放和云端幂等。
+- 完善 watchdog 和超时任务处理。
+- 增加任务恢复 API。
+- 增加 local-agent 异常注入测试。
+- 增加 APP 进度卡恢复操作。
+
+验收标准：
+
+- 断网后 progress/complete 不丢。
+- local-agent 重启后 pending outbox 自动重放。
+- 旧 queued 任务不会突然执行。
+- turn 启动后不会重复下发。
+- APP 不再无限停在第一步。
+
+### 第二阶段：备份与恢复点产品化
+
+目标：把已有快照能力从底层 API 变成用户能理解的备份中心。
+
+开发内容：
+
+- 统一 BackupSnapshot 投影。
+- 增加 verify、preview、dry-run restore。
+- 后台展示备份状态。
+- 恢复前强制 pre-restore 快照。
+- 恢复动作写审计。
+- 增加备份健康告警。
+
+验收标准：
+
+- 平台后台能看到快照列表和健康状态。
+- 企业后台能看到本企业恢复点。
+- 恢复前能看到影响范围。
+- 恢复失败不会破坏当前状态。
+- 所有恢复动作可审计。
+
+### 第三阶段：业务级回退
+
+目标：让用户按业务对象恢复，而不是按全局 JSON 恢复。
+
+开发内容：
+
+- 消息软删除和恢复。
+- 项目目标历史版本。
+- 版本记录追加、作废和恢复。
+- 权限变更撤销。
+- 主 Agent 接管 checkpoint 和恢复。
+- Codex 线程回滚/分叉/压缩统一到恢复面板。
+- Skill 回滚展示和操作收口。
+
+验收标准：
+
+- 用户能恢复误删消息。
+- 用户能恢复旧项目目标。
+- 用户能作废错误版本记录。
+- 管理员能撤销误授权。
+- 接管关闭后不再留下主动任务。
+- Codex 线程回滚边界在 UI 中明确。
+
+### 第四阶段：企业灾备底座
+
+目标：为正式量产迁移数据库和对象存储做好入口。
+
+开发内容：
+
+- PostgreSQL 迁移工具进入后台可视状态。
+- 增加数据库模式状态展示。
+- 增加对象存储附件 manifest 备份。
+- 增加企业数据导出包。
+- 增加恢复演练记录。
+- 增加 RPO/RTO 展示。
+
+验收标准：
+
+- 文件模式和数据库模式状态在后台可区分。
+- dry-run 迁移和 dry-run restore 可从后台触发或查看结果。
+- 企业数据包不泄露密钥和 token。
+- 后台能看到恢复演练记录。
+
+## 9. 测试与验证
+
+### 9.1 必跑测试
+
+- `npm run build`
+- `npm run lint`
+- `node --test local-agent/reliable-outbox.test.mjs local-agent/master-task-timeout.test.mjs`
+- `npx tsx --test tests/master-agent-task-reliability.test.ts`
+- `npx tsx --test tests/admin-backups-route.test.ts`
+- `npx tsx --test tests/state-store-maintenance-script.test.ts`
+- `npx tsx --test tests/admin-backoffice-bff-route.test.ts`
+- `npm run stress:remote-control:ci`
+
+### 9.2 新增测试
+
+需要新增：
+
+- outbox 网络失败重放测试。
+- complete 幂等和迟到 complete 测试。
+- watchdog 清理旧 queued 测试。
+- watchdog 处理 turn_started 后超时测试。
+- backup verify 失败测试。
+- dry-run restore 不写状态测试。
+- restore 自动 pre-restore 测试。
+- project goal restore 测试。
+- version record restore 测试。
+- permission undo 测试。
+- APP 进度卡 phase 映射单元测试。
+- 后台 BFF backup/recovery 字段测试。
+
+### 9.3 人工回归
+
+需要覆盖：
+
+1. APP 发起普通线程任务。
+2. APP 发起主 Agent 托管任务。
+3. 执行中断网再恢复。
+4. local-agent 重启后继续回写。
+5. Codex App Server 故障后进入可恢复失败。
+6. 任务进入 `needs_user_action` 后 APP 能处理。
+7. 创建手动快照。
+8. 恢复手动快照。
+9. 恢复前自动生成 pre-restore 快照。
+10. 后台显示备份健康。
+11. 后台显示任务卡住风险。
+12. APP 不显示内部 prompt 和敏感路径。
+
+## 10. 安全边界
+
+本版本明确不做：
+
+- 不把备份下载权限开放给普通成员。
+- 不允许没有审批的全局恢复。
+- 不把 Codex 原始 item、reasoning、命令输出和系统 prompt 保存到备份展示层。
+- 不把 Codex 线程回滚描述成代码回滚。
+- 不自动点击支付、删除、提交、发送、授权等高风险桌面动作。
+- 不把 PostgreSQL 量产能力伪装成已经默认启用。
+
+## 11. 成功标准
+
+用户侧成功标准：
+
+- APP 里任务不会再一直卡在第一步。
+- 任务失败时用户知道卡在哪里、能做什么。
+- 用户误删或误改后能找回关键内容。
+- 主 Agent 接管出错后能退出并恢复控制权。
+- Codex 线程误操作后能做线程级回滚或分叉。
+
+企业管理员成功标准：
+
+- 能看到本企业备份是否健康。
+- 能看到可恢复点。
+- 能看到恢复影响范围。
+- 能看到恢复审计。
+- 能恢复项目目标、版本记录、误删消息、Skill 和权限变更。
+
+平台管理员成功标准：
+
+- 能看到所有企业的备份健康和风险。
+- 能发现备份过期、恢复失败、任务卡住、设备离线。
+- 能在不默认读取企业业务正文的情况下协助客户排障。
+- 能用恢复演练证明系统可交付。
+
+工程成功标准：
+
+- 可靠执行、备份、恢复、审计和 UI 都有自动化测试。
+- 每个 provider 故障都有安全失败路径。
+- 所有恢复动作都有 pre-restore 和审计。
+- 文档明确当前已落地能力、待开发能力和长期量产目标。
+
+## 12. 给开发线程的执行原则
+
+1. 先补测试，再改实现。
+2. 先收敛数据模型，再补 UI。
+3. 先做文件模式产品化，再做 PostgreSQL 量产迁移。
+4. 所有恢复动作必须有权限检查、影响预览、pre-restore 和审计。
+5. 所有 APP 展示必须使用人话，不展示内部字段。
+6. 所有后台风险都要能追溯到任务、设备、账号、时间和安全摘要。
+7. 所有 Codex 协议相关能力都必须经过 provider 适配层，不把协议字段写死到业务 UI。
+8. 所有 Computer Use 高风险动作默认 fail closed。
+9. 所有测试必须覆盖“失败怎么恢复”，不能只测成功路径。
+10. 每批开发后必须更新 `docs/architecture/current_runtime_and_deploy_status_cn.md`，避免运行真相和规划文档混淆。