# 流程编排使用教程

## 适合什么场景

流程编排适合处理下面这类事情：

- 固定界面中的重复点击。
- 需要按条件分支执行的简单自动化。
- 需要循环检测、切换界面、按键、等待、通知等组合动作。
- 想先把零散操作拼成一个可反复复用的小流程。

如果你的需求已经能被首页现成任务覆盖，例如清体力、每日实训、差分宇宙等，优先使用现成任务即可；

流程编排更适合做“自定义补充逻辑”。

## 基本概念

一个流程由多个步骤组成，步骤以树状结构组织。

- 普通步骤：顺序执行，例如点击图片、点击文字、等待、按键。
- 控制步骤：可以包含子步骤，目前支持 `if`、`for`、`while`。
- 循环控制步骤：可在循环内部使用 `break` 和 `continue`。

你可以把它理解成一个可视化的“小型脚本编辑器”，但不需要自己写代码。

## 进入入口

打开小助手后，进入左侧导航栏中的“流程编排”。

界面主要分成两部分：

- 上半部分：流程列表、运行、停止、导入导出、采集模板等操作。
- 下半部分：步骤树，用来编辑当前流程中的步骤结构。

## 创建第一个流程

### 新建流程

点击“新建流程”，输入一个容易识别的名称。

官方示例流程通常是只读的，只能查看，不能直接修改；

你自己新建的流程可以编辑、重命名、删除、导出。

### 添加步骤

点击“添加步骤”可以在当前层级新增一个步骤。

如果当前选中的是 `if`、`for`、`while` 这类控制步骤，还可以点击“添加子步骤”，把新步骤挂到该节点下面。

### 编辑和调整顺序

- 双击步骤，或者点击“编辑步骤”，可以修改当前步骤。
- 点击“上移”“下移”可以调整同级步骤顺序。
- 右键步骤树，可以直接运行整个流程或只执行当前选中步骤。

## 常用步骤说明

### 点击图片

适合界面上有稳定按钮、图标、提示框时使用。

常用配置项：

- 模板路径：要匹配的图片素材。
- 图片阈值：匹配精度。
- 检测区域：只在指定区域内找图，可以减少误识别。
- 重试次数：找不到时重复尝试的次数。
- 点击动作：点击、按下、松开。
- 按下时长：仅在需要长按时填写；如果留空或为 0，则保持默认点击行为。

### 点击文字

适合按钮文字比较稳定、但图标样式容易变化的场景。

常用配置项：

- 目标文字：OCR 要识别的文字。
- 使用包含匹配：适合目标文字前后可能带额外内容时使用。
- 检测区域：限制 OCR 识别范围。
- 重试次数：找不到时重复尝试。
- 点击动作、按下时长：与点击图片相同。

### 点击坐标

适合目标位置固定，但没有稳定图片或文字可识别的情况。

通常做法是先用截图工具框出一块区域，再把该区域坐标复制到步骤中。

### 查找图片 / 查找文字

这两类步骤本身不点击，只负责判断目标是否存在。

它们常用于 `if` 或 `while` 的条件判断，例如：

- 检测到“开始挑战”时才继续点击。
- 没检测到某张提示图时继续循环等待。

### 等待

最简单的延时步骤，适合在界面切换、动画播放、按钮出现前做缓冲。

### 按下按键

用于模拟键盘按键，可选点击、按下、松开，并可配置按键时长。

### 切换界面

该步骤会调用小助手已有的界面切换逻辑。

可选目标不是任意填写，而是当前程序中已定义、并且可以从 `main` 主界面主动切换到的界面。

如果某个界面不在下拉列表里，说明当前版本不支持直接切过去。

### 播放音频 / 消息推送

这两类步骤适合在关键节点提醒你：

- 播放音频：本地弹出提示音。
- 消息推送：向你当前配置的通知渠道发送文本，也可以附带截图。

## 控制步骤怎么用

### if

当条件成立时，执行它下面的子步骤。

适合“如果看到某个按钮，就点它”这类逻辑。

### for

按固定次数循环执行子步骤。

如果循环次数填 0，则表示无限循环，需要你自己通过条件、停止按钮或 `break` 来结束。

### while

只要条件仍然成立，就持续执行子步骤。

建议同时设置一个合理的最大循环次数，避免条件异常时一直跑不出来。

### break / continue

这两个步骤只能放在循环内部：

- `break`：结束当前循环。
- `continue`：跳过本轮后续步骤，直接开始下一轮循环。

如果把它们放在循环外面，运行日志里会提示该步骤无效。

## 如何采集模板和坐标

### 采集图像模板

点击“采集图像模板”，程序会打开截图窗口。

框选完成后保存，模板会自动放到当前流程自己的素材目录里。

流程素材会跟随流程一起保存，导出流程时也会一并打包。

### 检测区域怎么填

如果你已经用截图工具框过区域，通常可以直接把生成的坐标表达式粘贴到“检测区域”。

不填时，默认就是全屏查找。

为了提高稳定性，建议尽量缩小检测范围，只覆盖目标可能出现的位置。

## 运行与调试

### 运行流程

点击“运行流程”，会执行当前流程中的全部步骤。

流程现在通过日志页的独立任务运行，因此停止时可以直接在日志页强制结束。

### 执行选中步骤

在步骤树中选中某个步骤后，可以通过右键菜单执行“执行选中步骤”。

这个功能非常适合调试某个节点是否能正确识别图片、文字或坐标。

### 停止流程

点击“停止流程”后，会转到日志页终止当前流程任务。

如果流程卡在某个界面识别或等待环节，不需要等它自己返回，可以直接停止。

### 日志怎么看

运行时建议重点看日志页输出：

- 当前执行到第几个步骤。
- 条件判断是否成功。
- 是否达到了最大循环次数。
- 是否发生异常、未找到模板、未识别到目标文字等。

## 导入、导出与素材目录

流程以目录形式保存，通常包含：

- `workflow.yaml`：流程结构本体。
- `templates/`：图片模板素材。

你可以使用“导出流程”把整个流程打成 zip，分享给别人；

也可以通过“导入流程”恢复到自己的小助手中。

## 一个简单示例

下面是一个很常见的思路：

1. `if` 检测文字“开始挑战”。
2. 条件成立后，子步骤中执行“点击文字：开始挑战”。
3. `wait` 等待 1 秒。
4. `while` 检测某个结算提示是否未出现。
5. 循环体里每次等待 1 秒，最多执行若干次。
6. 识别到结算后，播放音频或发送消息。

先把流程做短、做小，确认每个步骤都稳定，再逐步往里加分支和循环，成功率通常更高。

## 常见建议

- 优先使用较小的检测区域，不要默认全屏找图或全屏 OCR。
- 图片模板尽量裁到只保留稳定特征，避免把动态背景一起截进去。
- 能用文字识别的场景，可以优先尝试“点击文字”。
- 调试单个步骤时，优先使用“执行选中步骤”，不要每次都跑完整流程。
- 如果识别结果不稳定，先去“工具箱 → 游戏截图”确认程序拿到的画面是否正确。
- 如果你只是想自动完成现成任务，不建议先从流程编排开始，维护成本会更高。