第13章 - 交互式录制器与截图工具实战

手写 YAML、逐个截图固然可行，但对新手不够友好。robotgo-flow 提供了交互式录制器（record）与截图工具（capture），让你能像「录制宏」一样一步步生成工作流，或快速截取模板。本章深入这两个工具的实战使用与内部机制。

13.1 三种获取模板的方式回顾

框架提供三种截取模板的途径：

1. WPF 录制标签页：图形界面中一键启动交互式录制（见第 15 章）；
2. capture 命令：交互式框选屏幕区域，截取单个模板；
3. record 命令 / CaptureInteractive API：录制工作流时顺带截取模板，或通过编程调用。

本章聚焦命令行下的 record 与 capture。

13.2 capture 截图工具

13.2.1 基本用法

robotgo-flow.exe capture btn_login --out-dir templates

执行后进入交互模式：

1. 提示「把鼠标移到 btn_login 区域的左上角，按回车」→ 记录坐标 (x1, y1)；
2. 提示「把鼠标移到右下角，按回车」→ 记录坐标 (x2, y2)；
3. 自动截取矩形区域 (x1, y1)–(x2, y2)，保存为 templates/btn_login.png。

13.2.2 内部机制

capture.go 提供了三个层次的截图函数：

• CaptureRegion(x, y, w, h, outputPath)：底层区域截图。调用 robotgo.CaptureScreen(x, y, w, h) 截取指定矩形，再用 bitmaputil.Save 保存（路径经 encoding.ToGBK 转换以支持中文路径），并自动创建输出目录；
• CaptureInteractive(name, outputDir)：交互式截图。通过 os.Stdin 读取用户的回车确认，先后记录左上角与右下角坐标，再调用 CaptureRegion；
• CaptureInteractivePipe(name, outputDir)：管道模式的交互式截图，用于 GUI 集成——因为 stdin 被 JSON 协议占用，它把提示信息写到 os.Stderr，并用 waitEnterPress() 检测回车。

13.2.3 回车检测的巧思

在管道模式下无法用常规的 ReadString 读回车（stdin 被协议占用），框架转而用 Windows API 直接检测按键：waitEnterPress() 通过 user32.dll 的 GetAsyncKeyState（键码 0x0D 即回车）轮询按键状态。它还做了防抖处理：先等回车被松开，再等按下，再等松开，避免一次按键被识别多次。默认超时 60 秒。

13.2.4 截图实战建议

• 先让目标可见：截图前把目标 UI 调到可见、稳定的状态；
• 框选精准：左上、右下两点尽量贴合元素边界，避免带入过多背景；
• 同分辨率：在实际运行的机器与分辨率下截图（呼应第 10 章）；
• 命名规范：用有意义的名字（如 btn_submit、input_email），便于在 YAML 中辨识。

13.3 record 交互式录制器

record 是一个「向导式」的工作流生成器，引导你一步步构建工作流，并在需要时自动截取模板。

robotgo-flow.exe record --out login.yaml --tpl-dir templates

13.3.1 录制总流程

recorder.go 中 Run() 的流程：

1. askMeta()：提示输入工作流名称与描述；
2. 创建模板目录：os.MkdirAll(templateDir)；
3. 步骤循环：提示输入步骤名（留空 = 结束录制）；
4. 动作循环：为当前步骤反复添加动作（选 0 = 完成本步骤）；
5. 保存：yaml.Marshal 序列化工作流，写入 --out 指定的文件。

13.3.2 动作菜单

askAction() 会呈现一个动作类型菜单，供你选择要添加的动作。菜单大致如下：

13.3.3 模板还是坐标

对于点击类动作，录制器会通过 askTemplateOrCoord 询问你用模板（1）还是坐标（2）：

• 选模板：输入模板名。若对应的 .png 文件还不存在，录制器会当场调用 capture.CaptureInteractive 让你截取——这就是「边录边截图」的体验；
• 选坐标：直接输入 x、y。

13.3.4 录制时设置运行时变量

在录制 type 动作时，输入文本后，录制器（recordType）会询问这个文本是固定值（1）还是运行时变量（2）：

• 选运行时变量：依次询问变量名（varName）、标签（label）、是否必填（默认 y）、是否隐藏（mask，默认 n）；
• 录制器会自动向 wf.Inputs 添加一个 InputSpec，并把文本设为 "$input." + varName。

这意味着你在录制时就能顺手把「密码」这类字段声明为运行时变量，无需事后手改 YAML。

13.3.5 模板路径的可移植性

录制器通过 makeTemplateRel 计算模板相对于 YAML 文件目录的相对路径（filepath.Rel），保证生成的 YAML 具有可移植性——把整个项目目录拷到别处，相对路径依然有效。

13.3.6 中文与保存

录制器读取输入时（readLine）会去掉换行符并调用 encoding.ToUTF8String 做 GBK→UTF-8 转换，因此中文名称、中文文本都能正确录入。保存时 save() 用 yaml.Marshal 生成 YAML 并以 0600 权限写文件。

13.3.7 管道模式

record --pipe 会启用管道模式（recorder.NewPipe），配合 GUI 通过 JSON-Line 协议驱动录制，模板截取则走 CaptureInteractivePipe。这主要供 WPF 录制标签页使用，普通用户直接用交互模式即可。

13.4 录制 vs 手写

实践中常常「录制 + 手改」结合：先用 record 快速生成骨架和模板，再手动打开 YAML 精调 settings、超时、错误策略、人类模拟等细节。

13.5 实战：录制一个搜索工作流

假设我们要录制「在搜索框输入关键词并搜索」：

robotgo-flow.exe record --out search.yaml --tpl-dir templates

交互过程大致：

1. 工作流名称：网页搜索；描述：输入关键词并搜索；
2. 步骤名：执行搜索；
3. 添加动作：选 5（Type）→ 模板名 search_box →（当场框选截图）→ 文本 → 选「运行时变量」→ 变量名 keyword、标签 搜索关键词、必填 y；
4. 继续添加动作：选 6（Press）→ 键名 enter；
5. 添加动作：选 8（Wait）→ 模板名 results（当场截图）；
6. 选 0 完成步骤；步骤名留空结束录制。

生成的 search.yaml 大致等价于手写的：

name: "网页搜索"
description: "输入关键词并搜索"
inputs:
  - name: keyword
    label: "搜索关键词"
    required: true
settings:
  element_timeout: 10
steps:
  - name: "执行搜索"
    actions:
      - type: {into: "templates/search_box.png", text: "$input.keyword"}
      - press: "enter"
      - wait: "templates/results.png"

13.6 常见问题

13.7 小结

本章我们实战讲解了截图工具与录制器：capture 通过框选左上/右下两点截取模板，底层由 CaptureRegion/CaptureInteractive 实现，管道模式用 GetAsyncKeyState 检测回车并防抖；record 以向导方式引导录制工作流，支持边录边截图、录制时声明运行时变量、生成可移植的相对模板路径。我们对比了录制与手写的适用场景，并完整演示了录制一个搜索工作流。下一章，我们讲解错误处理、容错与调试。