第01章 - robotgo-flow 概述与核心特性

1.1 什么是 robotgo-flow

robotgo-flow 是一个基于 robotgo 实现的 Windows 桌面 RPA（Robotic Process Automation，机器人流程自动化）框架，其官方仓库托管在 https://github.com/znlgis/robotgo-flow。

它的核心思想非常直接：用声明式的 YAML 文件来描述一段桌面自动化流程，框架读取这个文件后，通过图像模板匹配定位屏幕上的 UI 元素，并自动执行鼠标、键盘、浏览器等操作。整个过程不需要编写任何 Go 代码，只要会写 YAML、会截图，就能搭建出一套可复用的自动化流程。

如果说 robotgo 提供的是「控制鼠标键盘、读取屏幕」这样的底层原子能力，那么 robotgo-flow 就是在这些原子能力之上，构建了一整套「流程编排 + 元素定位 + 人类行为模拟 + 容错重试 + 图形界面」的上层框架。它把 RPA 场景中常见的重复劳动（登录系统、填表、批量点击、抓取数据）抽象成了可配置的「步骤（Step）」与「动作（Action）」。

一句话概括 robotgo-flow 的定位：

基于 robotgo 实现的、YAML 驱动的、面向 Windows 桌面的 RPA 自动化框架。

1.2 robotgo-flow 与 robotgo 的关系

理解 robotgo-flow，首先要理解它与底层 robotgo 的分层关系。可以用一个简单的比喻：

• robotgo 是「手和眼」——它能移动鼠标、敲键盘、截图、在屏幕里查找一张图片。它提供的是一个个孤立的函数调用。
• robotgo-flow 是「大脑与流程」——它决定「先做什么、后做什么、失败了怎么办、找不到元素怎么办、要不要模拟人类操作」。它把一连串 robotgo 调用组织成有意义的业务流程。

在源码层面，robotgo-flow 的 internal/engine 包对 robotgo 进行了封装（engine.go），把 robotgo.Click、robotgo.Type、robotgo.FindBitmap、robotgo.CaptureScreen 等底层 API 包装成更高层的 Click(x, y)、TypeText(text)、FindElement(template) 等方法，并在其中加入了模板缓存、浏览器窗口定位、人类行为模拟等增强逻辑。

因此，学习 robotgo-flow 时，如果你已经了解 robotgo 的基础能力（鼠标、键盘、屏幕、位图查找），会更容易理解框架内部的工作原理；反之，即使完全不了解 robotgo，也可以只通过 YAML 使用 robotgo-flow，因为框架已经把底层细节完全封装了。

1.3 两大组件：Go CLI 与 WPF 托盘应用

robotgo-flow 由两个可以独立使用、也可以协同工作的组件构成：

1.3.1 Go CLI（命令行工具）

这是框架的核心与必需组件，是一个纯命令行程序，编译后得到单个 robotgo-flow.exe。它提供四个子命令：

CLI 不依赖 .NET 或 WPF，可以完全独立运行，非常适合脚本化、定时任务、服务器无人值守等场景。

1.3.2 WPF 托盘应用（可选图形界面）

这是一个基于 .NET 10 WPF 的 Windows 系统托盘应用（项目名 RobotgoFlow.Tray）。它通过两种方式与 Go 引擎通信：

1. 子进程模式：启动 robotgo-flow.exe serve 作为子进程，通过标准输入输出（stdin/stdout）以 JSON-Line 协议双向通信；
2. DLL 模式：把 Go 引擎编译为 c-shared 动态链接库（robotgo-flow.dll），通过 P/Invoke 直接调用。

托盘应用提供了任务栏快捷操作、实时进度浮窗、桌面通知、输入变量采集等图形化能力，让不熟悉命令行的用户也能方便地运行工作流。

重要提示：WPF 托盘应用是可选组件。Go CLI 可以独立使用，不依赖 .NET 或 WPF。本教程会以 CLI 为主线讲解，并用专门的章节介绍 WPF 托盘应用。

1.4 核心特性一览

robotgo-flow 的功能相当丰富，下面先做一个整体的鸟瞰，后续章节会逐一深入。

1.4.1 YAML 声明式驱动

用一份 YAML 文件描述整个自动化流程，无需编写 Go 代码。工作流由「元信息 + 运行时变量 + 全局设置 + 步骤列表」构成，每个步骤又包含若干动作。框架支持 19 种动作类型，覆盖鼠标、键盘、等待、滚动、浏览器、延时、交互等场景。

1.4.2 图像模板匹配定位

robotgo-flow 不依赖控件句柄或 DOM，而是通过预先截取的 UI 元素截图（PNG 模板）在屏幕上查找目标位置。这种「看图找位置」的方式适应窗口移动、适应各种无法通过常规接口访问的程序（例如 Web 页面、游戏、第三方软件）。框架采用「窗口内优先搜索、全屏回退」的策略提升准确率。

1.4.3 运行时变量注入

工作流中的文本可以使用 $input.<变量名> 占位符，执行前提示用户输入实际值，从而实现「同一份工作流、不同的输入参数」。密码类变量支持 mask: true 隐藏输入。

1.4.4 交互式动作（人工决策节点）

框架内置 prompt（运行时输入框）、confirm（确认对话框）、notify（系统通知）三种交互式动作，允许在自动化流程中插入「人工介入」的环节，例如让用户手动输入验证码、确认是否提交等。

1.4.5 人类行为模拟

启用后，鼠标移动会走贝塞尔曲线轨迹并在接近目标时减速；打字会按 mistake_rate 概率引入相邻键错误、漏字、顺序颠倒并自动修正；操作间隔随机变化；滚动分块执行并偶有回滚；长时间等待时鼠标会有轻微抖动。这些都能降低被检测为「机器人」的风险。

1.4.6 容错、重试与调试

框架支持三种错误处理策略：abort（终止）、skip（跳过）、retry（重试）。可以从指定步骤恢复执行（--from N），可以开启调试模式（--debug）为每一步自动截图，失败时也会自动保存现场截图。

1.4.7 交互式录制器与截图工具

record 命令通过命令行逐步引导你录制工作流，自动创建模板截图；capture 命令则用于单独截取模板，交互式地框选屏幕区域。

1.4.8 安全停止与中文编码支持

执行过程中可随时取消（基于 Go 的 context 取消机制），保证协程安全退出。针对 Windows 中文环境，框架通过 internal/encoding 包自动处理 GBK 与 UTF-8 之间的编码转换，用户无需手动处理中文路径和 YAML 编码问题。

1.5 典型应用场景

robotgo-flow 特别适合以下场景：

• Web 表单自动填写与提交：登录系统、批量录入数据、定时导出报表。
• 无 API 的老旧系统自动化：对于无法通过接口对接的桌面软件或内网系统，通过图像识别模拟人工操作。
• 重复性办公流程自动化：在多个系统之间搬运数据、批量处理。
• 需要人工决策的半自动流程：利用交互式动作，在关键节点让人工输入验证码或确认操作。
• 需要「拟人」操作的场景：借助人类行为模拟，降低被风控系统识别的概率。

1.6 环境与平台要求

robotgo-flow 当前仅支持 Windows 平台（Windows 10 / 11），核心依赖如下：

框架大量使用了 Windows 特有的 API（例如浏览器窗口检测使用 robotgo.FindIds、robotgo.ActivePid，截图工具使用 user32.dll 的 GetAsyncKeyState），因此虽然底层 robotgo 理论上跨平台，但 robotgo-flow 目前的实现聚焦于 Windows。跨平台的可能性会在最后一章讨论。

1.7 本教程的学习路线

本教程会按照「概念 → 环境 → 入门 → 语法 → 动作 → 机制 → 工具 → 进阶 → 实战」的顺序循序渐进，整体规划如下：

1. 概述与环境（第 1～3 章）：理解 robotgo-flow 是什么，搭建开发环境，跑通第一个工作流。
2. YAML 与动作详解（第 4～9 章）：系统讲解工作流文件结构，以及鼠标、键盘、等待、滚动、浏览器、交互式动作等全部 19 种动作。
3. 核心机制（第 10～11 章）：深入图像模板匹配与人类行为模拟两大核心机制。
4. 工具与容错（第 12～14 章）：CLI 命令、录制器与截图工具、错误处理与调试。
5. 图形界面与架构（第 15～16 章）：WPF 托盘应用、整体架构与源码剖析。
6. 进阶与实战（第 17～19 章）：二次开发扩展新动作、综合实战项目、最佳实践与常见问题。

建议读者具备基础的命令行操作能力，了解 YAML 的基本语法。若想深入源码或做二次开发，则需要具备 Go 语言基础。准备一台 Windows 10/11 开发机，以便边学边动手实践。

1.8 小结

本章我们认识了 robotgo-flow 的整体定位：一个基于 robotgo、以 YAML 驱动、面向 Windows 桌面的 RPA 自动化框架。我们梳理了它与底层 robotgo 的分层关系，介绍了 Go CLI 与 WPF 托盘应用两大组件，概览了 YAML 驱动、图像模板匹配、运行时变量、交互式动作、人类行为模拟、容错重试等核心特性，并明确了平台要求与学习路线。下一章，我们将正式动手搭建 robotgo-flow 的开发与运行环境。