流程解剖
流程是一份保存的文档。知道里面有什么，编辑器就变得可预测，也解释了为什么有的东西可复用有的不行，还告诉你把流程导出到另一台机器时真正带走的是什么。
目的
本页描述流程的各个部分及其关系。在你第一个非平凡流程之前读它，开始把工作拆成子流程时再读一遍。
组成部分
图上的一切都存在流程里。导出的流程全部带走。
节点
节点是一个带类型的步骤。每个节点有：
| 字段 | 含义 |
|---|---|
id | 稳定标识——永不改变，改名后仍在 |
type | 节点种类（action.click、detect.image……） |
name | 画布上看到的标签——自由文本，随便改 |
params | 节点设置，因类型而异 |
retryPolicy | 可选的按节点重试，或没有 |
outputMappings | 可选：把节点输出写入变量 |
ui | 画布位置、颜色、折叠状态 |
重要推论：id 是身份，name 是标签。 改名永不断开连接，两个节点可以同名。
节点不拥有自己的路由。节点报告自己从哪个端口离开；流程的连线决定去哪。所以你能重接整张图而不动任何节点的设置。
端口
端口是节点上的命名出口。多数节点类型是固定集合：
- 多数节点：
success、failure、timeout、cancelled、fatal - 简单 If：
true/false - Memory Match：
matched/notMatched - Captcha：
solved/unsolved/failure
有几种节点从自身设置计算端口：
| 节点 | 端口取决于 |
|---|---|
| If 的 Multiple Branches 模式 | 每分支一个 case1…caseN，外加 default |
| If 的 Text-match 模式 | match / noMatch |
| Find Image 的 Branch-by-template 模式 | 每个选中模板一个端口，外加 notFound |
| Branch（随机分支） | 由分支数得出 branch1…branchN |
调低数量时，尾部端口消失，编辑器替你剪掉孤儿连线。
必接端口与可选端口
有的端口必须接上流程才有效；有的可以有意留空。
- 必接——留空是校验错误。多数节点的
success。 - 可选（宽容）——留空是合法的"到此为止"。走到就平静结束。
Branch 是严格派：每个分支端口都必须连接，因为运行时可能选中任何一 个，空着的分支会随机把运行带进死胡同。
连线
连线把一个节点的端口接到另一个节点。连线携带：
| 字段 | 含义 |
|---|---|
fromNodeId + fromPort | 从哪离开 |
toNodeId | 去哪 |
priority | 多条连线共用一个端口时的顺序 |
condition | 可选守卫，解析时求值 |
同一端口可以出多条连线，按优先级依次尝试；见连线解析。
区域
**区域（region）**是命名矩形，按屏幕百分比存储，不是像素。
百分比存储正是流程在一种分辨率上搭好、换分辨率照样能跑的原因。盖住 1280×720 右上四分之一的区域，在 1920×1080 上盖的还是右上四分之一。
区域有 id（身份）和 name（标签）。节点绑定 id，改名不影响使用它的节点。
区域可存入 Region Library 跨流程复用。
素材——模板图像
**素材（asset）**是 Find Image 节点用来匹配的已截取模板图。每条记录：
- 图像文件与校验和，
- 像素尺寸，
- 截取时的分辨率，
- 一份质量评估——熵、边缘密度、主色占比，以及是否推荐。
质量评估就是应用能警告"模板太平淡或太杂乱、难以稳定匹配"的原因。
几乎纯色的模板熵低，会在屏幕上到处匹配。带大量背景的模板在背后任何东西变化时就失效。截取目标最有辨识度的部分，贴紧裁剪。
分组
分组是画在画布局部周围的命名框，可加注释，可折叠。
分组是纯创作家具。没有端口，没有设置，永不执行。成员资格是几何的——框住谁谁就是成员——把节点拖进拖出就是一次拖拽，没有节点保存会过期的父 id。
只有注释、没有成员的分组就是你的注释框。不用学第二种注释概念。
设置
流程设置分四块。
Target
流程期望的模拟器：首选实例名、ADB 序列号、期望分辨率与朝向。
Defaults
节点未自行指定时使用的回退值：
| 设置 | 范围 | 覆盖 |
|---|---|---|
timeoutMs | 100–120000 | 默认节点超时 |
pollIntervalMs | 50–5000 | 默认检测轮询间隔 |
waitAfterActionMs | 0–60000 | 默认操作后稳定时间 |
imageThreshold | 0.5–0.99 | 默认匹配置信度 |
Runtime
护栏与执行策略：
| 设置 | 范围 | 作用 |
|---|---|---|
maxNodeExecutions | 1–100000 | 总执行节点数硬上限 |
maxRuntimeDurationMs | 1000–86400000 | 墙钟时长硬上限 |
maxConsecutiveFailures | 1–1000 | 连续失败硬上限 |
captureFailureScreenshots | boolean | 节点失败时保存截图 |
inputMode | adb / native | 输入投递方式 |
frameSync | object | 帧新鲜度规则 （下文） |
Features
按流程的功能开关：ocrEnabled、nativeInputEnabled、multiScaleImageDetectionEnabled。
ocrEnabled 关闭的流程里 Read Text 不会运行。Read Text 节点立刻失败且无输出？先查这个设置，再去调试区域。
帧同步
检测必须读屏幕的当前画面，不是旧画面。frameSync 设置管这件事：
| 设置 | 范围 | 含义 |
|---|---|---|
requireFreshFrameAfterInput | boolean | 发送输入后，等待真正的新帧 |
maxFrameAgeMs | 16–5000 | 帧多旧仍算可用 |
freshFrameTimeoutMs | 100–30000 | 等新帧等多久 |
visualStabilityFrames | 0–10 | 需要连续多少帧稳定 |
帧可用的条件：now - frame.capturedAt <= maxFrameAgeMs。
这挡住了经典的自动化 bug：点了按钮，立刻"看见"点击前的屏幕。
身份对复用意味着什么
许多东西以稳定 id 而非名字标识，因此以下都安全：
- 重命名节点、区域或模板。
- 在画布上移动节点。
- 重排分支（端口按位置，但连线跟随）。
以下则不安全：
- 删除某个 branch-by-template Find Image 正用来分流的模板——它的端口随之消失。
- 把分支数降到已接线的分支之下——尾部连线被剪。
最佳实践
- 按意图命名节点、按阅读顺序编号。
1. Find a gem on screen、2. Swipe it to the centre。本文档的参考自动化正是如此，13 个节点的流程一眼可读。 - 用分组标注阶段，折叠你不在做的那些。
- 可复用矩形进 Region Library，别重画。
- 流程默认值设一次，别在二十个节点上重复同一个超时。
- 一个流程一件事。 一句话说不清的流程，想被拆成 Sub Flow。
性能笔记
- 限定区域的检测明显快于全屏检测——匹配器在裁剪上工作。设 search region 是现成最便宜的提速。
- 模板数量放大匹配成本。16 模板的多模板 Find Image 对同一帧做约 16 倍的匹配工作。
- 流程默认值运行时零成本——编译期已解析。
内存笔记
- 模板素材被加载并缓存用于匹配。模板多而大的流程工作集更大；紧裁剪在每个意义上都更小。
- 分组、区域和节点
ui数据仅供创作。存在流程里，但永不进入运行时热路径。
常见错误
| 错误 | 后果 | 修复 |
|---|---|---|
| 脑子里按像素记坐标 | 换分辨率流程崩 | 用区域——它们按百分比 |
| 截模板带背景 | 背景一变就不匹配 | 贴紧裁剪辨识部分 |
| 指望节点名参与接线 | 无效——名字是标签 | 接端口；id 是身份 |
ocrEnabled 关着 | Read Text 毫无动作 | 在流程设置里打开 |
| 一个巨型流程 | 读不了，测不了 | 拆成 Sub Flow |
故障排查
流程校验通 过，但某分支变灰或消失。 If（多分支/文本匹配）、Find Image（按模板分支）与 Branch 的端口集由设置计算。查分支数或模板选择。
改了模拟器分辨率后模板不匹配了。 模板匹配基于像素。要么重截模板，要么在流程功能开关里启用多尺度检测。
Read Text 什么都不返回。
先查流程设置里的 features.ocrEnabled。
FAQ
重命名流程会弄断对它的 Sub Flow 调用吗？ 不会。调用绑定流程 id；名字是显示缓存。
分组随流程导出吗？ 导出。它们是流程文档的一部分。
两个节点能同名吗？ 能。名字是标签，不是身份。
区域住在流程里还是库里？ 都可以。就地画的矩形属于流程；存入 Region Library 则跨流程复用。