FlowPilot/docs/错误重试分层策略.md

错误重试分层策略（步骤 4/8/9/自动运行）

本文档说明当前实现中的三层重试语义，避免把“当步重试 / 小循环重试 / 大循环重试”混在一起理解。

1. 第一层：当步重试（Step 内部）

定义：不离开当前步骤，在当前页面链路内恢复或替换资源。

典型位置：

• flows/openai/background/steps/fetch-signup-code.js（步骤 4 页面恢复）
• flows/openai/background/steps/fetch-login-code.js + background/verification-flow.js（步骤 8 邮箱轮询与重发）
• background/phone-verification-flow.js（步骤 9 号码轮换、重发、回到 add-phone）

常见动作：

• 点击 Try again 恢复 405/重试页；
• 同一步内重新拉验证码；
• 步骤 9 内直接换号（不立刻回步骤 7）；
• 同提供商/同国家内换价格档位或换号码。

2. 第二层：小循环重试（授权链路重开）

定义：当前轮次内回到授权链路起点（通常步骤 7），再走 7→8→9。

触发来源：

• background.js 的 getPostStep6AutoRestartDecision(...)；
• 步骤 8 检测到邮箱通信异常且当前链路连续重试超限；
• 步骤 9 触发 PHONE_RESTART_STEP7 类错误（例如回调窗口过期/链路不可恢复）。

特点：

• 还是同一“轮次”；
• 不进入线程间隔（20 分钟）；
• 优先用于“流程状态错位/页面链路失效”类问题。

3. 第三层：大循环重试（自动运行 attempt/round）

定义：由自动运行控制器决定是否进入下一次 attempt，或等待线程间隔后继续。

位置：

• background/auto-run-controller.js

关键点：

• autoRunSkipFailures=true 时，允许同轮多次 attempt；
• 某些错误会被视为“本轮直接失败并跳过剩余重试”；
• 若配置了线程间隔，会出现“等待 N 分钟后第 x 次尝试”日志。

4. 错误分类优先级（当前实现）

1. 先做当步恢复（能在步骤内闭环就不升级）
2. 当步失败后，再判断是否走小循环（回步骤 7）
3. 小循环仍失败，才交给大循环（attempt / round / 线程间隔）

5. 已落实的关键规则（与近期问题对应）

• Failed to fetch / network error / fetch failed： 步骤 4/8/9 进入有上限的网络重试（当前默认 3 次，冷却 12 秒）。

• Step 9: 5sim check activation failed: order not found： 归类为“号码失效”，在步骤 9 内立即换号（当步重试），不应直接触发线程间隔。

• Route Error 405（手机号验证码页）： 优先当步恢复；若落入 route-405 循环，步骤 9 内换号。

• add-phone / phone-verification 页面状态： 表示流程已进入手机链路，自动运行层默认不再盲目回步骤 7，避免破坏当前链路。

6. 关于“第几轮尝试 + 暂停”含义

• “第 x/y 轮第 n 次尝试”是自动运行控制器的外层 attempt 计数；
• “线程间隔：等待 20 分钟...”表示已经升级到第三层（大循环）；
• 用户手动停止会中断当前计划；恢复时是否回到步骤 7，取决于当前页面状态与回调是否过期：
  • 回调未过期且仍在可恢复链路：优先当前链路继续；
  • 回调已过期或链路断裂：回步骤 7 重拉授权。