别让 Agent 浏览器任务无限重试：失败分类、RetryPolicy 与人工复核

很多 Agent 浏览器任务最开始都能跑通。

真正麻烦的是上线以后：偶发失败、页面状态不一致、登录态失效、重试后结果更乱。

如果失败后只做一件事：retry()，系统很快会进入不可复盘状态。

浏览器任务失败不是单一错误，它更像一个现场问题。你需要先判断现场还能不能继续执行。

1. 先定义 FailureReason

不要把所有异常都归类成 error 或 timeout。

建议至少拆成下面几类：

failure_type	含义	处理方向
session_invalid	会话不可用	检查 Cookie、LocalStorage、IndexedDB
env_mismatch	环境不匹配	检查 Profile、Proxy、时区、语言
page_changed	页面结构变化	检查 DOM、选择器、页面版本
action_timeout	操作超时	检查等待策略和页面加载
security_verification_required	需要安全验证	暂停任务，人工走官方验证
agent_uncertain	Agent 判断不确定	保存证据，进入人工复核

这一步的价值是把"失败了"变成"为什么失败，以及能不能继续"。

2. RetryPolicy 要有边界

一个不推荐的做法：

ts 复制代码

for (let i = 0; i < 3; i++) {
  await runBrowserTask();
}

这段代码没有判断失败类型。

更合理的结构应该是：

ts 复制代码

type FailureType =
  | "session_invalid"
  | "env_mismatch"
  | "page_changed"
  | "action_timeout"
  | "security_verification_required"
  | "agent_uncertain";

const retryAllowed = new Set<FailureType>([
  "action_timeout",
]);

const pauseRequired = new Set<FailureType>([
  "session_invalid",
  "env_mismatch",
  "security_verification_required",
  "agent_uncertain",
]);

原则很简单：

低风险、临时性失败，可以重试。

环境不可信、会话不可用、安全验证、Agent 不确定，直接暂停。

3. 重试前保存证据

没有 StepEvidence 的重试，本质上是在覆盖现场。

建议每个关键步骤保存：

字段	说明
step_id	步骤编号
action	执行动作
target	操作目标
url	当前页面 URL
page_title	页面标题
before_screenshot	操作前截图
after_screenshot	操作后截图
assertion	预期状态
result	实际结果
reason	Agent 或脚本判断理由

这样即使任务暂停，也能知道它为什么停。

4. ReviewQueue 的作用

人工复核队列不是为了降低自动化程度，而是处理自动化不应该继续执行的分支。

比如：

场景	建议
出现安全验证	暂停，交给人工完成官方验证
Profile 快照变化	暂停，对比环境记录
Cookie 失效	暂停，确认登录状态
页面结构变化	保存截图，确认是否改版
Agent 判断不确定	记录 reason，人工确认

这些分支如果继续自动跑，通常只会制造更多不可追溯结果。

5. 一个最小数据结构

ts 复制代码

type RunDecision = {
  runId: string;
  workspaceId: string;
  profileId: string;
  failureType?: FailureType;
  retryAllowed: boolean;
  reviewRequired: boolean;
  evidenceSaved: boolean;
  nextAction: "retry" | "pause" | "manual_review" | "finish";
};

可以把任务结果收敛到一个决策对象里，而不是散落在日志中。

6. 推荐流程

text 复制代码

EnvironmentSnapshot
  -> BrowserTask
  -> StepEvidence
  -> FailureReason
  -> RetryPolicy
  -> ReviewQueue

其中 RetryPolicy 不是兜底工具，而是一个风险控制器。

它要回答：

这次失败能不能重试？
重试前证据是否保存？
是否需要人工复核？
如果暂停，后续该看什么？

7. 小结

Agent 浏览器任务不是无限重试就能稳定。

稳定来自三个能力：

运行前知道环境是否可信。
运行中保留步骤证据。
失败后能区分重试、暂停和人工复核。

尤其是遇到安全验证、环境不一致、登录态异常时，正确做法不是绕过去，而是暂停并走官方验证或人工确认。

这会让系统看起来"慢一点"，但能显著降低不可复盘问题。

Web4Browser 关注 Agent 浏览器任务的环境连续性、证据链和人工复核机制，可以作为这类工作流的基础设施参考。

参考： web4browser.io/cn/