Read Text (OCR)（读取文本）

读取屏幕上的动态值，让后续节点按它们分支、把它们打回去，或按它们点击。

用途

从一个或多个矩形读取文字——坐标、金币、计时、状态词——并写入变量。

你告诉它区域含什么（What to read 类型），它自动调优 OCR 引擎并产出正确类型的变量。你不配置引擎；你描述内容。

何时用

• 读要比较的数字——金币、负载、槽位数。
• 提取坐标供后续节点按它动作。
• 读状态词来分支。
• 读 3/5 之类计数器或 04:20 计时。

何时不用

• 找按钮或图标——用 Find Image。OCR 对图形更慢更不可靠。
• 检测无文字的状态——用 Check Region。
• 检查文字是否存在——读它，再用带 Is Empty 的 If。

前提

两样，缺则节点 Fatal：

1. OCR 引擎和语言必须可用。
2. 流程的 ocrEnabled 功能开关必须开。

OCR 按流程门控

Read Text 节点立刻失败且无输出？调试区域之前先查流程设置里的 features.ocrEnabled。这是最常见的成因。

如何运行

设置

设置	类型	范围	默认	作用
Region	矩形	屏幕百分比	—	要读的区域
What to read (Type)	选择	auto、text、number、counter、time、percentage、custom	auto	调优 OCR 并决定输出变量
Read multiple regions	boolean	—	false	在一个节点里读多个区域
Regions	列表	≤ 20	—	多区域条目，各有自己的变量、类型和清洗
Outputs	列表	每区域 ≤ 8	—	命名输出 → 变量，带可选 Default
Pattern	string	≤ 500 字符	—	Custom 类型：命名组正则
Auto convert	boolean	—	—	逐捕获组推断 int/float/bool
Character whitelist	string	≤ 200 字符	—	引擎只识别这些字符
Post-process	列表	≤ 16 步	—	有序清洗：raw、digits、whitelist、regexFilter
Language	string	≤ 32 字符	Auto	OCR 语言；空 = 配置的默认
Timeout	integer	1–120000 ms	5000	尝试取新文字多久
Poll interval	integer	50–120000 ms	250	多久重抓一次

内容类型

最重要的设置。选对类型胜过任何手动调优。

类型	产出	用于
auto	原始文本	真不知道时
text	字符串	状态词、名字
number	一个数	金币、负载、任何要比较的值
counter	<名>_current 和 <名>_max	3/5 式计数器
time	<名>_hours 和 <名>_minutes	04:20 计时
percentage	一个数	85%
custom	每命名正则组一个变量	坐标之类结构化文本

选具体类型，别用 Auto

Auto 返回原始文本。原始字符串 "1167" 不是数字，所以 {{gold}} > 100 会悄悄失败。选 Number 让比较生效。

自定义正则提取

custom 类型取一个带命名组的正则并每组产出一个变量：

Pattern:  X:(?P<x>\d+)\s+Y:(?P<y>\d+)
屏幕:     X:1167 Y:1120
结果:     x = 1167   y = 1120   （数字）

模式必须含至少一个命名组 (?P<name>…)。无效或无组的模式让节点在任何抓取之前 Fatal——它不会悄悄提取出空。

解析不出就留空

解析不出的 Number 或 Counter 写空，不是 0。

刻意如此：捏造的 0 会悄悄流进比较、做出错误决策；空值则显形。要具体回退就给逐输出 Default。

因此，把绑 OCR 的变量声明为可空——number?，不是 number。

多区域读取

一个节点、多个矩形、各写各的变量。当你需要一屏上两三个相关值时用它——一个节点里读取意味着一张截图，不是三张。

每个区域带自己的类型、清洗和默认值，所以只含数字的价格能挨着文字标签。

只有扁平变量

结构化类型写扁平名（slot_current，不是 slot.current）。因为 {{name}} 引用按扁平名解析——嵌套对象在 If 里能用，但作 Click 坐标会失败。

端口

端口	走它的时机	必接
Success	读取完成——包括空区域。 无文字不是失败	否
Failure	超时内无新帧，或 Custom 模式无匹配	否
Cancelled	读取中途运行被停	否——永不被走
Fatal	OCR 引擎缺失、无语言、区域无效、Custom 正则或后处理无效	否——永不被走

Failure 不意味着"无文字"

普通读取即便没找到文字也成功。Failure 意味着没抓到帧，或 Custom 模式无匹配。要按空文字分支，读它再用带 Is Empty 的 If。

基础示例

读金币计数：

• Region：数字周围的紧矩形
• What to read：Number
• 变量：gold

然后 {{gold}} > 1000 作为数值比较生效。

实际示例——读坐标再决定

一次 OCR 把屏幕标签变成两个驱动真实决策的数值变量。

高级示例——多区域容量检查

在一个节点里读两个槽位计数，队列满就停：

• Read multiple regions：开
• 区域 1 → slot_1，类型 Counter → 产出 slot_1_current、slot_1_max
• 区域 2 → slot_2，类型 Counter → 产出 slot_2_current、slot_2_max

然后一个表达式模式的 If：

{{slot_1_current}} == {{slot_1_max}} || {{slot_2_current}} == {{slot_2_max}}

路由到消息 "All slots full" 的 Stop: success。

一个节点、一张截图、四个类型正确的变量、一个决策。

最佳实践

• 区域紧贴文字部分。 周边 UI 是读错的主因。
• 总选具体 Type 而非 Auto。
• 小字先放大。 OCR 准确率强烈依赖字形大小——与 Zoom 搭配。
• OCR 变量声明可空（number?），让解析不出的读取不会拖垮运行。
• 用 Test Node 运行流程前预览读取和提取的变量。
• 用多区域而非多个读同一屏的 Read Text 节点。
• 含杂字符的数字字段用仅数字清洗。

性能笔记

• OCR 明显比模板匹配贵。只需知道某物是否在场时，优先 Find Image。
• 成本随区域面积。紧区域又快又准。
• 多区域读取共用一张截图，所以一个节点两区域远便宜于两个节点。
• 字符白名单既提速引擎又提高准确率，因它收窄搜索空间。
• 默认超时 5000 ms、轮询 250 ms——最坏约 20 次尝试。对要么立刻在要么不在的值降低超时。

内存笔记

• 每次轮询抓新帧并对裁剪跑 OCR 管线。帧短暂但管线每轮分配。
• 多区域对同一抓取帧处理每个区域，所以内存随区域数、不随抓取次数。
• 提取的变量是普通流程变量，存活整次运行。

常见错误

错误	后果	修复
用 Auto 再做数值比较	比较对字符串悄悄失败	用 Number 类型
区域含周边 UI	准确率差	收紧区域
指望无文字时 Failure	普通读取成功	用 If → Is Empty
Custom 正则无命名组	抓取前 Fatal	加 (?P<name>…)
不可空变量绑 OCR	运行被 TYPE_MISMATCH 拒	声明 number? / string?
忘了 ocrEnabled	节点立刻 Fatal	在流程设置里开
不放大读小字	读取不稳	先放大

故障排查

节点立刻 Fatal。 查流程设置里的 features.ocrEnabled，再查 Custom 正则（若用）。

数字回空。 解析不出为数。空是刻意的——查区域，考虑仅数字清洗或 Default。

{{gold}} > 100 之类比较从不触发。 值是文本，不是数字。切到 Number 类型。

读取在多次运行间不稳。 区域多半抓到变化的背景边缘。收紧它，或加字符白名单。

Custom 模式偶尔走 Failure。 该帧上模式无匹配。放宽模式，或把 Failure 接到重试路径。

FAQ

空区域意味着 Failure 吗？ 不——Success。只有缺帧或 Custom 模式无匹配才路由 Failure。

一个节点读几个区域？ 最多 20。

我的计数器变量为何叫 slot_current？ 结构化类型写扁平名，让 {{name}} 引用处处解析。

读取失败时能设回退吗？ 能——逐输出 Default。

OCR 和 Find Image 谁快？ Find Image，差距大。只在需要值时用 OCR。

相关节点

• Find Image——定位图形
• Check Region——无文字的状态
• If——按读到的内容分支
• Variable——存储与计算
• Zoom——先放大小字

相关页面

• 变量与记忆——可空类型与默认值
• 流程解剖——OCR 功能开关