[youngslin]

背景与取舍

#1900 已关闭且未合并。放弃 BetterGI 单独弹窗 / WS 选择，改为纯后端自动恢复。#1900 中有价值的「识别安装目录之外启动的 BetterGI 官方安装器」进程检查已迁入本 PR；不迁移弹窗与前端组件。

公共收束入口与持久备份

• 公共 run_managed_script_install 入口收发检查、安装、回退和恢复结果；专项仅提供 inspect / acknowledge / install / ensure_idle / after_rollback 适配器。
• script_install_backup 在同磁盘工作区保存原版完整快照、哈希清单与跨任务持久状态；不能覆盖未结算的备份。新安装在确认成功且停写后删除备份。
• 安装器明确失败：确认停写，再回退到经哈希校验的原版；回退并验证成功后可继续任务，但在结束摘要报告该次失败。
• 首次安装超时/状态不明：保留快照并禁止直接覆盖；下轮先做只读健康检查，若完整成功则确认并删除备份，否则重试安装；重试失败/超时，在再次确认完全停写后才允许回滚旧版并继续。
• 恢复时反复下载失败（下载来源与受控错误原因），即使成功回滚旧版继续运行，也会在整轮任务结束时经 ScriptUpdateSession 统一写入后端日志、current.recovery_summary 和 task.notice，专项不再单独弹窗。
• 备份、安装确认、版本及原生事务记录检查出现异常，统一 fail-closed；保留现场，禁止使用半安装版本。安装锁由调用方持有直到事务收束结束。

范围和后续

本 PR 提供公共备份/恢复决策能力与 BetterGI 安装器外部进程保护，但尚未把新的通用事务入口接到每个脚本的真实安装器。后续需要按脚本的原生 pending、资源布局、数据保护目录、官方安装器停写约束分别接入。不能因为公共测试通过就宣称所有脚本已经自动修复。

历史 UI 尚未消费新 recovery_summary 字段；目前可从任务结束通知和后端日志看到汇总。对外类型生成及历史界面回看需另行完成。

测试

新增持久快照、已确认失败回滚、首次超时后下轮重试与清理、下载反复失败最终汇总、安装器仍在写入时拒绝回滚、跨配置恢复、哈希损坏保护、目录交换中断续做和通用报告等回归测试。CI 以最新提交为准；未运行真实游戏或上游官方安装器。

[sentry]

Bug: Unguarded inspect() and acknowledge() calls in reconcile_installation propagate exceptions without emitting a blocked RecoveryIncident, resulting in missing incidents in recovery summaries.
_{Severity: LOW}

Suggested Fix

Wrap inspect() and acknowledge() invocations in try...except blocks within reconcile_installation, emitting a blocked RecoveryIncident before re-raising the exception or handling it appropriately.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: app/core/script_update_recovery.py#L77

Potential issue: In `reconcile_installation`, calls to initial `inspect()`,
`acknowledge()`, and the final `inspect()` are unguarded by error handling. If an
exception is raised during these calls—such as `acknowledge()` raising due to a race
condition—the error propagates without calling `emit('blocked', ...)`. As a result, no
`RecoveryIncident` is recorded, causing `current.recovery_summary` and the queue summary
to omit reporting this blocked-start case.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[jinghero]

总体结论：修改后合并

AUTO-MAS-Project/AUTO-MAS #1916

宝宝，这次把“是否能继续”交给公共决策层、把安装细节留给适配器，范围说清楚啦。dot酱没有确认半安装被放行或取消变成旧版回退的缺陷；目前挡住合并的是实际 CI 格式失败，另有两处低风险问题值得补齐喵。

公共入口依据适配器提供的健康证据作决定，ScriptUpdateSession 收集结果，ScriptExpander 等预下载收尾后统一发通知。现有安装锁仍由适配器持有，本 PR 尚未接入具体专项，不能把这份公共能力当作各脚本已经自动修复成功。

合并前处理

当前格式检查明确失败于 Ruff：

• app/core/script_update.py:123 的条件换行。
• tests/core/test_script_update_recovery.py:239、264 附近的空行及两处 inspection 参数排版。

请使用仓库锁定版本的 Ruff 格式化这两份文件，并确认重跑通过。不是安装逻辑失败，但这盏红灯现在确实还亮着，先别把构建通过当全绿啦。

规范

[规范 · P3，非阻断] 新增对外字段尚未同步生成客户端

TaskItem.Current:369–371新增 recovery_summary，TaskTreeData 从它派生，字段确实会进入任务查询和完成包。但当前生成文件 TaskItem_current.ts仍没有它。请按项目的 API 契约规则重新生成客户端，不要手改生成文件。这里是类型契约没有同步，不是后端把字段丢了。

当前真正会显示汇总的是既有 task.notice；前端 完成消息处理还没有保存这个字段用于回看。后端最近终态缓存会保留它，所以也不能说“任务结束就丢了”。本 PR 可以保持公共后端范围，但说明中应分清“完成包已携带”与“历史界面已展示”，回看接入还要留给后续啦。

模块归属和遥测未确认新增阻断项。自动检查与重试沿用已有脚本/任务终态观察；摘要里的安装目录和业务身份未被加入匿名统计，不需要为这些内部步骤另发一套完成事件。

规格

[逻辑 · P3，非阻断] 确认或复核抛错时，汇总漏掉这次阻断

位置：reconcile_installation:101–102、141–146。

公共契约明确允许 acknowledge 在记录变化时抛错；健康检查读取安装文件，也可能因文件损坏或 I/O 失败抛错。但这几个 await 位于只包住 reinstall 的异常记录范围之外。比如首次检查返回“有残留、完整且新安装已确认”，随后 acknowledge 拒绝清除变化的记录，异常会正确阻止启动，却没有生成 blocked 事件。队列结束的恢复汇总因此遗漏这一项；若只有这一次恢复事件，汇总甚至为空。

请在确认和复核失败的边界记录固定、脱敏的 blocked 原因，再原样抛出；取消继续向上传播，不能改成恢复失败或旧版继续。沿现有公共入口补一组“acknowledge/复核抛错 → 异常仍传播、汇总含 blocked”的检查就够啦。与现有机器人提示是同一个问题，dot酱核对后只记一次，且不把报告缺项夸大为安全放行。

验证情况

已核对 ContextVar 随任务及预下载继承、结束时重置、预下载收敛后汇总、同轮去重，以及旧版放行同时要求“无 pending、healthy、previous_confirmed”。未确认新增 P1/P2，规范和规格各 1 项非阻断 P3。

读取了当前提交的实际 CI 日志：Windows pytest 1817 通过、2 跳过；Ubuntu 1778 通过、40 跳过，Windows 验证包构建通过。格式工作流在 Python 步骤失败，后续前端 lint/typecheck/format、单测和词条检查均被跳过，不能算通过。

新增测试能证明公共决策和延后通知，但使用了检查/安装回调及任务替身，不能证明真实安装完整性、真实任务树提交或断线后的界面回看。dot酱未执行项目代码、测试、安装器或游戏任务；专项适配和真实恢复效果仍需后续各自验证。

—— dot酱核过公共恢复边界敬上 🐾

[jinghero]

总体结论：修改后合并

AUTO-MAS-Project/AUTO-MAS #1916

宝宝，上轮提到的检查、确认异常漏汇总已经补上啦。不过这次新增了整目录备份和自动回滚，不能沿用上轮“未确认 P1/P2”的判断：dot酱发现一条回滚中断后会再次覆盖旧版的路径，得先修好喵。当前格式检查也仍未通过。

这版由公共入口决定安装、重试和回滚，备份服务负责保存和移动目录，专项提供健康证据与停写确认。职责可以保持这个分工；问题出在上层没有接上底层已有的回滚续做能力，不需要再加一套框架。

规格：必须处理

[逻辑 · P2，阻断] 回滚中断后被当成安装重试，可能改坏唯一完整旧版

位置：retry_previous:272–283、ManagedInstallBackup._restore:155–173。

沿新公共入口静态推演，以下是实现自身能留下的状态，不需要外部篡改记录：

1. 安装明确失败后开始回滚，先写入 restoring，把失败安装移到 failed-install，再把 snapshot 移回安装目录。
2. 在移动完成、写入 restored 之前崩溃，或取消使接下来的哈希检查中断。此时记录仍为 restoring，snapshot 已不存在，安装目录是唯一完整旧版。
3. 下次进入 retry_previous，只将 restored 分流到继续回滚。对于正常的旧版检查结果 healthy=True、updated_confirmed=False，代码会改写为 retrying，再调用 install。
4. 如果第二次安装改写文件后失败，再次恢复会因“snapshot 不存在，且阶段已不是 restoring”而拒绝继续。原本能恢复的旧版可能已被这次安装改坏，failed-install 保存的则是第一次失败现场，不能替代原备份。

安装锁、停写确认和 worker 收尾都不能补回已经被第二次安装覆盖的旧版；它们解决的是并发与退出，不是这个阶段分流问题。好在底层 _restore 已能处理“restoring 且 snapshot 已移走”的情况，别让上层绕开它啦。

最小修改： 在公共编排层将 restoring 和 restored 都先交给 restore_previous，完成原来的回滚、校验和清理，不能再次调用 install。用真实临时目录补一条公共入口回归：在 snapshot 移回后中断，下次调用应保留原文件、完成回滚，且不启动安装。这里不需要运行游戏或真实专项。

规范与 CI

当前格式任务的实际日志显示 Ruff 要求格式化 4 个文件：app/core/script_update.py、app/core/script_update_recovery.py、app/services/script_install_backup.py、tests/core/test_script_update_recovery.py。请用仓库锁定版本处理并重跑，红灯还不能跳过喵。

上轮 P3、非阻断 的客户端生成问题仍在：recovery_summary 已进入后端任务契约，生成的 TaskItem_current.ts 尚未同步。按既有生成器更新即可，具体证据不再重复铺开。

验证情况

已重新检查完整 PR 与新增提交的安装、快照、超时、取消、回滚及清理路径。旧 reconcile 的异常记录修复成立；新安装超时当次会保留备份并阻止继续，没有把取消当成普通下载失败。

本次新增的 run_managed_installation 和 ManagedInstallBackup 尚无直接测试覆盖；当前 281 行恢复测试与上次完全相同，验证的是旧公共决策、下载降级和延后通知，不能证明新增目录事务。上述中断回归应随修复补上，别让已有绿灯替它作保啦。

发布前读取的 CI 中，Windows 验证包构建与 Ubuntu pytest 已通过，Windows pytest 仍在运行；格式任务失败后，前端 lint、类型、格式、单测、词条及 E2E 契约检查均被跳过。dot酱未执行项目代码、测试或安装器。具体专项尚未接入，本次结论只针对公共能力，不声称已经验证真实安装恢复。

—— dot酱守着旧版备份敬上 🐾