第14章 - 错误处理、容错与调试

自动化流程运行在真实、多变的桌面环境中，失败在所难免：元素没及时出现、网络卡顿、弹窗遮挡……一个成熟的 RPA 框架，衡量标准不只是「能跑通」，更是「出错时能优雅应对」。本章讲解 robotgo-flow 的错误处理策略、容错重试机制、恢复执行与调试手段。

14.1 三种错误处理策略

robotgo-flow 通过 settings.on_error 配置全局的错误处理策略，共三种取值：

settings:
  on_error: abort      # abort / skip / retry
  max_retries: 3       # retry 模式下的最大重试次数

值	行为
`abort`	遇错立即终止执行（默认）
`skip`	记录错误日志，跳过当前动作，继续下一个
`retry`	重试当前动作，最多 `max_retries` 次；耗尽后仍失败则 abort

14.1.1 abort（终止）

默认策略。任何一个动作失败，整个工作流立即停止。它的执行逻辑（executor.go）是：

保存现场错误截图（便于事后排查）；
记录错误日志（notify.LogError）并弹出错误提示框（notify.PrintError）；
返回错误，进程以非零退出码结束。

abort 适合要求严格、不容出错的流程——宁可停下让人介入，也不带着错误状态继续。

14.1.2 skip（跳过）

遇错时记录一条警告日志，跳过当前动作，继续执行下一个。它适合容忍部分失败的场景，例如批量操作中「个别项失败不影响整体」。

注意：skip 会在跳过时仍调用 OnActionDone 回调，以保持进度回调协议的对称（对 GUI 的进度显示很重要）。

14.1.3 retry（重试）

遇错时重试当前动作，最多重试 max_retries 次（默认 3），每次重试之间会等待约 1 秒（eng.Wait(1000)）。若重试次数耗尽仍失败，则退回 abort 行为（终止）。

retry 适合偶发性、瞬时性失败——比如页面偶尔加载慢导致元素晚出现，重试几次往往就成功了。

14.2 如何选择策略

场景	推荐策略
关键流程、不容错（如支付、提交）	`abort`
网络/加载不稳定，失败多为瞬时	`retry`
批量处理，允许个别失败	`skip`

也可以「分层」考虑：整体用 retry 增强健壮性，对绝对不能出错的关键步骤，则通过流程设计（如前置 wait、confirm 人工确认）加固。

14.3 从指定步骤恢复：–from

当长流程失败后，--from N 让你从失败的步骤恢复，而不必从头再来：

robotgo-flow.exe run workflow.yaml --from 5

它按步骤定位（1-indexed）。executor.RunFromStep 会校验 1 ≤ startStep ≤ 步骤总数，越界会报错。恢复执行时，前面的步骤被跳过，直接从第 N 步开始。

使用前提：从第 N 步恢复，意味着你要保证「第 N 步开始时的界面状态」与正常执行到那里时一致。例如若前几步是登录，恢复前你需要手动登录到对应页面。这也是把动作合理组织成「自洽」步骤的价值。

14.4 调试模式：–debug

调试模式在每一步成功后自动截取全屏，保存到输出目录：

robotgo-flow.exe run workflow.yaml --debug --out screenshots

截图按步骤命名（如 debug_step_001.png、debug_step_002.png……）。这让你能「回放」整个流程的每一步屏幕状态，快速定位是哪一步、什么界面出了问题。

14.4.1 debug 截图 vs 错误截图

debug 截图：每步成功后主动截图，用于全程回放；
错误截图：abort 失败时自动保存的现场截图，用于定位失败点。

二者互补：平时用 --debug 观察全流程，出错时看错误截图定位问题。

14.5 安全停止机制

执行过程中随时可以安全地取消，这依赖 Go 的 context 取消机制。

Executor 内部持有一个 context.Context（可通过 WithContext 注入）。在遍历步骤与动作时，每一步都会检查 ctx.Done()：一旦收到取消信号，立即停止后续执行并返回哨兵错误 ErrCancelled（「执行已被用户取消」）。

CLI 模式：按 Ctrl+C 触发中断；
serve/GUI 模式：WPF 发送 stop 命令，serve 触发 context 取消。

这种机制保证了取消是「协作式」且干净的——不会在一个动作执行到一半时被硬生生杀掉，而是在动作边界安全退出，避免留下不一致的状态。

14.6 进度回调与日志

执行器通过 ProgressCallback 接口在关键节点发出事件（供 GUI、日志消费）：

OnWorkflowStart / OnWorkflowDone：工作流开始/结束；
OnStepStart / OnStepDone：步骤开始/结束（结束时带错误与截图路径）；
OnActionStart / OnActionDone：动作开始/完成；
OnLog(level, message, stepIdx)：日志消息，级别有 LogInfo、LogWarn、LogError。

CLI 模式下这些事件体现为终端日志；GUI 模式下则驱动进度条与状态显示（详见第 15 章）。理解这套回调，有助于你读懂执行过程中的输出，也是二次开发时对接界面的接口。

14.7 调试实战流程

一个高效的调试流程建议：

首跑用 –debug：run workflow.yaml --debug，观察每步截图，确认流程走向；
定位失败步：若在第 N 步失败，查看错误截图与日志，判断是模板问题还是时机问题；
修复：
- 模板匹配失败 → 重截模板（第 10 章），检查分辨率/DPI；
- 时机问题 → 增大 element_timeout，或在动作前加 wait/wait_gone；
- 偶发失败 → 把 on_error 设为 retry；
局部验证：用 --from N 只跑失败步及其后，快速验证修复；
整体回归：修好后完整跑一遍确认。

14.8 常见错误与应对

错误现象	可能原因	应对
「等待元素超时」	超时太短、模板不准、页面没加载	增大超时、重截模板、加 `wait_gone` 等加载动画消失
「找不到模板文件」（加载阶段）	模板路径错或文件缺失	检查相对路径，先截好所有模板
点击位置偏移	窗口状态、DPI 不一致	保证窗口最大化、缩放一致
频繁瞬时失败	网络/渲染波动	用 `retry` 策略
中途需要取消	发现异常	`Ctrl+C` 或 GUI 停止，安全退出

14.9 小结

本章我们讲解了 robotgo-flow 的错误处理与调试体系：三种错误策略 abort（默认，终止并存现场截图）、skip（跳过继续）、retry（重试 max_retries 次、间隔 1 秒）；--from N 从失败步骤恢复；--debug 每步成功后截图用于全程回放；基于 context 的安全停止机制；以及 ProgressCallback 进度回调与分级日志。最后给出了一套实用的调试流程。掌握这些，你就能让工作流在真实多变的环境中稳健运行。下一章，我们讲解 WPF 托盘应用与集成。