Watchdog 核弹重启后自动恢复¶

1. 背景 / 动机¶

来源：../raw/feedback/2026-05-26-watchdog-auto-resume-after-restart|2026-05-26-watchdog重启后自动继续

用户原话：

这个自动暂停了地图的抓取了，要点继续才行，我希望能自动继续

为什么要做： - watchdog 设计初衷是「让长跑稳定」，但 v0.10.15 核弹重启后强制 task 降级为 paused → 必须手动点开始才能继续 - 用户核心场景是隔夜跑/无人值守：半夜无法操作，停在那等人 = 浪费时间 - 当前行为与 watchdog 初衷自相矛盾

矛盾要解决： - ✅ 用户要自动恢复（不被打断） - ⚠️ 但持续性问题（网络断 / Google 全面拦截）下无限自动恢复会让电脑反复卡死

2. 目标 / 非目标¶

目标¶

默认自动恢复（不需要手动点开始）
加冷却时间（让网络/状况稳定）
加恢复上限（避免无限循环）
用户可关闭 / 调参

非目标¶

不改 watchdog 巡检逻辑本身（孤儿/僵尸检测保持）
不引入复杂状态机（如指数退避），保持简单

3. 用户故事¶

作为隔夜跑任务的用户，
我希望 watchdog 自动恢复抓取，
以便第二天早上看到任务正常完成，而不是停在那等我点开始。

作为遇到持续问题（网络全断）的用户，
我希望系统在多次自动恢复失败后停下来，
以便保护电脑不被反复重启搞卡。

4. 数据模型¶

settings 新增 3 个字段¶

interface SettingParams {
  // ... 已有字段
  // v0.10.23：watchdog 自动恢复
  watchdogAutoResume: boolean;            // 默认 true
  watchdogAutoResumeCooldownSec: number;  // 默认 60，冷却秒数
  watchdogAutoResumeMaxCycles: number;    // 默认 3，连续自动恢复次数上限
}

新增 storage key¶

'local:watchdogAutoResumeCycles': number  // 持久化「连续自动恢复次数」
// 触发自动恢复 → +1
// watchdog 巡检发现干净（无孤儿/僵尸）→ 清 0
// 达上限触发人工模式 → 清 0

默认值变更¶

老用户升级后： - watchdogAutoResume = true（默认开 → 用户立刻享受自动恢复） - 上限 3 次防止意外卡死 - 60s 冷却保守

5. API 接口¶

不涉及外部 API。仅内部函数签名调整：

// batch-controller.ts
export async function nukeAllSchedulerState(opts?: {
  keepTasksRunning?: boolean;  // v0.10.23：自动恢复路径传 true，不降级 task
}): Promise<void>;

6. UI 设计¶

设置 → 高级 · 健康巡检 子区新增 3 个字段（接在「自动重启阈值」后）：

🛡️ 看门狗（Watchdog）
   [Switch] 启用健康巡检
   巡检周期 / 寿命阈值 / 自动重启阈值        ← 已有

   ── 自动恢复（v0.10.23 新增）─────────
   [Switch] 重启后自动继续抓取（推荐开启）   ← watchdogAutoResume
   冷却秒数: 60                              ← watchdogAutoResumeCooldownSec
   自动恢复次数上限: 3                       ← watchdogAutoResumeMaxCycles

   💡 自动恢复会重置「连续重启计数」，巡检干净时也清零。
      达到上限后才停下要求人工点「开始」（保护电脑不被无限重启拖慢）。

7. 任务拆分¶

后端¶

任务 1：storage-data.ts 加 3 个字段 + DefaultSettings
任务 2：batch-controller.ts nukeAllSchedulerState 加 opts.keepTasksRunning
任务 3：scrape-watchdog.ts 改核弹分支
读 settings 决定 autoResume 路径
读/写 local:watchdogAutoResumeCycles 持久化计数
autoResume：调用 nukeAllSchedulerState({keepTasksRunning:true}) + setTimeout cooldown + pumpTasks
上限达到 / autoResume 关闭：走老行为（降级 paused + 通知人工）
每次巡检干净（orphans=0, zombies=0）→ 清 cycles 计数
任务 4：engine-manager.ts handleScrapeFailure 退场时清 cycles
任务 5：导入 pumpTasks 到 watchdog

前端¶

任务 6：settings-view.tsx 健康巡检子区加 3 个 UI 字段 + yup schema

文档¶

任务 7：更新 docs/wiki/tab-lifecycle-and-watchdog.md 加自动恢复设计说明
任务 8：更新 docs/wiki/settings-field-semantics.md 加 3 个新字段
任务 9：本 spec 移到 done/

测试¶

任务 10：用户实测
制造孤儿（手动开几个 google maps tab 在共享窗口）→ 3 次累积应自动恢复
连续 3 次自动恢复（人为重复制造）→ 第 4 次应停下显示「自动恢复达上限」通知
关闭 autoResume → 回到 v0.10.22 老行为

8. 风险 / 注意点¶

⚠️ 无限循环风险：靠 watchdogAutoResumeMaxCycles 上限保护。默认 3 次（≈ 45 分钟）足够区分「短暂波动」vs「持续故障」
⚠️ 冷却期太短导致连环触发：默认 60s 足够让 SW / 浏览器 / 网络平稳。可调
⚠️ pumpTasks 失败兜底：cooldown 后 pumpTasks 抛错 → watchdog 已是 best-effort，写日志即可
⚠️ 与 ISSUE-0015 mutex 的关系：watchdog 本身有 mutex 防并发，自动恢复路径不会与下一次巡检撞车

9. 验证标准¶

pnpm build ✅
settings UI 显示 3 个新字段
默认值 = autoResume=true, cooldown=60s, max=3
storage local:watchdogAutoResumeCycles 持久化正确
wiki 同步更新
用户实测（隔夜跑场景）

10. 决策记录¶

2026-05-26：默认 ON 而不是 OFF — 用户的核心诉求就是自动；OFF 用户得二次手动操作，没意义
2026-05-26：上限 3 次而不是 1 次或 5 次 — 3 次 ≈ 45 分钟（按 5min 周期），既能区分短暂波动又能保护电脑
2026-05-26：冷却 60s 而不是 0 / 5min — 0 太激进，5min 太保守；60s 让网络/SW/CPU 喘口气足够
2026-05-26：成功巡检（无孤儿/僵尸）→ 清 cycles 计数 — 否则计数会持续累积，几小时后误触发人工模式
2026-05-26 (v0.10.24)：用户反馈 60s/3 次太保守 → 改默认 10s 冷却 / 9999 次上限
原话：「10s 后继续无限次除非人工点停止」
推理：用户场景是全无人值守，任何自动停都是打扰；用户已有「点停止」逃生机制
9999 不是 0/-1 因为 yup 校验需要数字 + UI 字段类型 number，9999 实际等价无限（5min 周期跑 9999 次 = 35 天）
同步修：syncWatchdogAlarm 关闭路径加清 local:watchdogAutoResumeCycles，让用户「停-开」循环时计数干净