第18章 - 综合实战项目

前面的章节我们把 robotgo-flow 的方方面面都拆开讲透了。本章通过一个贴近真实的综合项目，把 YAML 编写、模板截取、运行时变量、交互式动作、等待策略、错误处理、人类模拟等知识点串联起来，完整实践一次「从零到交付」的自动化工作流开发。

18.1 项目背景

需求：某内部管理系统每天需要人工登录、进入「日报」页面、填写当天的工作内容并提交。这个操作重复、机械，非常适合自动化。

目标：做一个工作流，实现「登录 → 进入日报页 → 填写日报内容 → 人工确认 → 提交 → 通知完成」，其中：

• 账号密码在运行前输入（参数化，密码隐藏）；
• 登录可能需要验证码（执行中人工输入）；
• 日报内容作为运行时变量；
• 提交前需人工确认；
• 全程启用人类行为模拟，降低被风控识别的风险；
• 具备一定容错能力。

18.2 需求分析与流程拆解

先把业务流程拆成有语义的步骤（Step）：

1. 打开登录页：导航到登录 URL，等待登录表单出现；
2. 填写登录信息：输入账号、密码；
3. 处理验证码：触发验证码，人工输入；
4. 进入日报页：登录后导航到日报页面；
5. 填写日报：在内容框输入日报文本；
6. 确认并提交：人工确认后点击提交，等待成功；
7. 通知完成：弹出完成通知。

这种「按业务语义分步」的方式，既让 YAML 易读，也方便用 --from N 从任意步骤恢复。

18.3 准备模板

根据流程，梳理出需要截取的模板，统一放到 templates/：

用 capture 逐个截取（在实际运行的机器、相同分辨率与 DPI 下）：

robotgo-flow.exe capture login_form --out-dir templates
robotgo-flow.exe capture input_user --out-dir templates
# ... 其余同理 ...

或用 record 边录边截，再手动精调 YAML。

18.4 编写工作流

新建 daily_report.yaml：

name: "每日日报自动填写"
description: "登录系统、填写并提交当天日报"

inputs:
  - name: account
    label: "账号"
    required: true
    placeholder: "工号或邮箱"
  - name: password
    label: "密码"
    required: true
    mask: true
  - name: report
    label: "日报内容"
    required: true
    placeholder: "今天完成的工作"

settings:
  element_timeout: 15
  on_error: retry          # 偶发失败自动重试
  max_retries: 3
  browser_page_load_delay: 3
  human:
    enabled: true          # 启用人类行为模拟
    speed: 0.8             # 略慢，更像真人
    mistake_rate: 0.02     # 2% 打字错误

steps:
  - name: "打开登录页"
    actions:
      - notify: {title: "日报自动化", message: "开始执行", duration: 2}
      - open_url: "https://intranet.example.com/login"
      - wait_gone: "templates/loading.png"
      - wait: "templates/login_form.png"

  - name: "填写登录信息"
    actions:
      - type: {into: "templates/input_user.png", text: "$input.account"}
      - type: {into: "templates/input_pass.png", text: "$input.password"}

  - name: "处理验证码"
    actions:
      - click: "templates/btn_send_code.png"
      - prompt:
          title: "输入验证码"
          message: "请查看短信/邮箱并输入验证码"
          into: "templates/input_code.png"
      - click: "templates/btn_login.png"
      - wait: "templates/home_ready.png"

  - name: "进入日报页"
    actions:
      - click: "templates/nav_report.png"
      - wait_gone: "templates/loading.png"
      - wait: "templates/report_editor.png"

  - name: "填写日报"
    actions:
      - type: {into: "templates/report_editor.png", text: "$input.report"}

  - name: "确认并提交"
    actions:
      - confirm:
          title: "提交确认"
          message: "日报内容已填写，确认提交？"
      - click: "templates/btn_submit.png"
      - wait: "templates/submit_success.png"

  - name: "通知完成"
    actions:
      - notify: {title: "日报自动化", message: "日报已提交成功！", duration: 0}

18.4.1 逐段解读

• inputs：account、password（隐藏）、report 三个运行前输入的变量；
• settings：15 秒超时、retry 容错、启用人类模拟（偏慢、少量打字错误）；
• 步骤 1：先 notify 告知开始，打开登录页，用 wait_gone 等加载动画消失、wait 等表单就绪——双重等待确保页面真正可用；
• 步骤 2：type 自动点击并填入账号密码；
• 步骤 3：点「发送验证码」后用 prompt 让用户人工输入验证码并自动填入，再点登录、等首页；
• 步骤 4：进入日报页，同样用 wait_gone + wait 双重等待；
• 步骤 5：填写日报内容；
• 步骤 6：confirm 人工确认后提交，等成功提示；
• 步骤 7：notify（duration: 0 需手动关闭）告知完成。

18.5 调试与运行

18.5.1 首次调试运行

robotgo-flow.exe run daily_report.yaml --debug

--debug 会为每步截图，便于观察流程。CLI 先提示输入 account、password、report，然后开始执行。执行到验证码步骤时会弹出输入框等你输入；到提交前会弹确认框。

18.5.2 定位并修复问题

假设执行到「步骤 4 进入日报页」失败（nav_report.png 找不到）：

1. 查看 debug 截图与错误截图，确认失败界面；
2. 发现是「首页布局与截模板时不同」——重新截取 nav_report.png；
3. 用 --from 4 只跑失败步及之后验证：

robotgo-flow.exe run daily_report.yaml --from 4

（注意：--from 4 时前 3 步不执行，你需要手动登录到首页状态。）

18.5.3 正式运行

调试通过后，正式运行即可：

robotgo-flow.exe run daily_report.yaml

18.6 用 WPF 界面运行（可选）

如果要让不熟悉命令行的同事使用，可用 WPF 托盘应用：加载 daily_report.yaml → 界面弹出输入表单填 account/password/report → 点击运行 → 实时进度浮窗展示每一步 → 验证码/确认时弹对话框 → 完成后 Toast 通知。底层通过 serve 的 JSON-Line 协议驱动（见第 15 章）。

18.7 本项目用到的知识点回顾

18.8 进一步优化方向

• 日报内容模板化：结合脚本，把 report 变量按日期/项目动态生成后传入；
• 定时执行：用 Windows 计划任务定时调用 CLI（但含 prompt/confirm 的流程需人值守；若要全自动，需去掉人工节点）；
• 多环境：为测试/生产准备不同的 YAML 与模板目录；
• 失败告警：abort 失败时，结合退出码在外层脚本发送告警。

18.9 小结

本章我们完成了一个贴近真实的综合实战项目——每日日报自动填写。从需求分析、流程拆解、模板准备，到编写含运行时变量、交互式动作、双重等待、人类模拟、容错策略的完整 YAML，再到调试（--debug/--from）、正式运行与 WPF 界面运行。这个项目把前面十七章的知识点融会贯通，展示了 robotgo-flow 在实际业务中的完整落地方式。下一章作为收尾，我们总结最佳实践、常见问题与跨平台展望。