文档中心

UIA 脚本

Windows UI Automation 脚本的完整语法与命令参考。

UIA 脚本是什么

UIA 脚本是数字员工在 Windows 桌面上的执行脚本。它不再经过浏览器自动化,而是进程内直接调用 Windows UI Automation(UIA),按「窗口 → 元素 → 动作」的顺序驱动 Chrome、Edge、记事本、Office、各类桌面客户端。

一行一条命令,从上到下顺序执行;任一命令失败即停止,并在日志中给出行号与错误码(find optional 除外)。

  • 定位只看窗口标题与元素属性,不需要写 URL、也不需要装浏览器驱动
  • 两条执行通道:通道 A = UIA Pattern(后台可用);通道 B = SendInput 键鼠注入;默认 natural 档优先真实鼠标与键盘,Pattern 只作兜底
  • 脚本可以声明输入 / 输出,直接被工作流节点与能力调用;节点入参为空时可用脚本内默认值
  • 支持条件分支、循环、遍历、正则文本处理与截图,方便做等待、重试与清洗
  • 纯文本脚本,可纳入版本管理、可评审

输入与输出声明

脚本最外层可以用 @input / @output 声明能力参数与产物。声明是元数据:执行时把参数值通过 {参数名} 插值到字符串与选择器中。

输入(含默认值)

@input url 目标网址 =https://example.com
@input count 重复次数 =3
@input index 编辑器序号 =1

输出

@output result 读取到的结果

声明格式为「@input 名称 说明 =默认值」:名称之后、等号之前的文字都是说明,等号之后是默认值(可带引号)。调用方没传或传空字符串时自动使用默认值。

  • 参数可以插进字符串、name/id/class 选择器,也可以写 index:{参数} 让序号入参化
  • name: 的实参如果写成 /正则/,运行时自动按正则匹配,一个参数即可切换匹配方式
@input / @output 只能写在最外层,不能出现在 if / repeat / foreach 块里;emit 的输出名必须在 @output 中声明,否则解析阶段就报错。

执行模型与边界

维度说明
执行位置数字员工桌面端进程内(Rust + Windows UIA COM),不启动 Node、不下载浏览器驱动
作用范围当前登录的 Windows 桌面会话:前台窗口、托盘程序、浏览器与客户端
元素来源UIA 元素树:名称、AutomationId、ClassName、ControlType 等属性
权限与被操作程序同级即可;操作以管理员身份运行的程序时,数字员工也需要管理员权限
不受支持锁定屏幕、未登录会话、远程桌面断开状态下的交互
扫描上限单次查找最多检查 20000 个候选元素,只为防止极端页面拖死线程;触顶仍未命中时日志会提示「可能有遗漏」
稳定建议优先 name: 精确匹配;界面语言变化时用 name~: 或正则;位置易变时用 next/prev/near 相对定位;必要时加 index: 与 timeout:

本文目录

1. 词法与书写规则

基本规则

  • 一行一条命令,空行忽略
  • 井号到行尾为注释;字符串里的井号不算注释
  • 字符串用双引号,例如 name:"记事本"
  • 变量写作 $name:find 产出元素,get / collect / let / extract / matches / strip 产出文本,read lines / json 可产出列表
  • 参数插值写作 {参数名},只替换已声明的 @input(或调用方传入的参数)
  • 日志与字符串里也可写 $变量,执行时替换为该变量当前的文本值

注释

# 打开 Chrome 窗口
window name~:"Chrome"        # 行尾注释同样有效

参数与变量插值

@input kw 关键词 =数字员工
set name:"搜索框" "搜索 {kw}"
get name:"搜索框" -> $text
log "关键词:{kw},输入框里现在是 $text"
变量分三类:$元素(find 得到的 UIA 元素)、$文本(get / collect / let 等得到的字符串)与 $列表(read lines / collect / json 等得到的多值列表),不能混用。

2. 选择器

选择器用「键:值」描述元素,多个键用空格并列,相互之间是 AND 关系。

键含义示例
name:名称精确匹配name:"发送"
name~:名称包含子串name~:"地址"
name:/…/名称正则匹配name:/Chrome.*/
type:UIA 控件类型type:button
id:AutomationId(元素定位用;浏览器顶层窗口通常为空,window 不使用 id)id:"submit"
id~:AutomationId 包含子串(也可写 / 正则/)id~:"send"
class:窗口 / 控件 ClassNameclass:"Chrome_WidgetWin_1"
class~:ClassName 包含子串(也可写 / 正则/)class~:"WidgetWin"
value:按当前值过滤(ValuePattern → TextPattern → 名称)value:"已发布"
value~:当前值包含子串(也可写 / 正则/)value~:"成功"
visible:只要可见元素;0 取反,支持 true/falsevisible:1
enabled:只要可用元素;0 取反enabled:1
childof:只找该元素的直接子级childof:$panel
limit:最多取前 N 个结果(仅 collect / count 生效)limit:20
index:第 N 个匹配项,从 1 开始;可写 index:{参数}index:2
min:最小边长(像素),排除小图标 / 头像min:24
timeout:定位超时毫秒,默认 3000timeout:8000
under:只在该元素子树里搜索(浮层 / 对话框)under:$tip
next:锚点之后的下一个同级元素next:$box
prev:锚点之前的上一个同级元素prev:$box
near:锚点附近的元素(按方向 / 距离)near:$box
side:near 的方向:right / left / above / below / anyside:right
gap:near 的最小间距(像素)gap:12
depth:next / prev 向上找同级的层数,1-3depth:2

绝对定位

find type:edit name~:"搜索" -> $box
find type:button name:/Chrome.*/ index:{btn_index} timeout:8000 -> $btn

相对定位

相对定位以一个已定位的元素为锚点。next / prev 先按控件树同级顺序找(可 depth 上溯),结构上没有命中时退化为几何邻近;near 直接按包围盒方向与距离排序。

find type:text name~:"标题" -> $title
find next:$title type:text -> $nextItem
find prev:$title type:text depth:2 -> $prevItem
find near:$title type:button side:below gap:8 -> $btn
side / gap 只能和 near: 一起用;一个选择器只能有一个相对锚点;锚点变量必须先用 find 定位。

作用域

find type:tooltip optional timeout:3000 -> $tip
find under:$tip type:text name~:"候选" optional -> $option
name~: 与 name:/…/ 无法用 UIA 属性条件表达,引擎会先按类型 / id / class 取候选,再在本地按名称过滤(单次扫描上限 20000 个候选)。正则里含 # 时要把整段用双引号包住,否则 # 会被当成行尾注释。

3. type 支持的控件类型

type: 取值对应 UIA ControlType,常用值如下;未列出的类型同样可用其小写名称。

取值控件
button按钮
edit输入框
text文本
checkbox复选框
radiobutton单选框
combobox下拉框
list / listitem列表 / 列表项
tab / tabitem选项卡 / 选项卡页
menu / menuitem菜单 / 菜单项
tree / treeitem树 / 树节点
table / dataitem表格 / 单元格
hyperlink超链接
image图片
tooltip提示浮层
group / pane分组 / 面板(常做子范围)
document文档页(浏览器页面主体)
window窗口

4. 命令总览

当前引擎共 48 条命令,下表按用途排列,后文按分组逐条展开。

命令作用
window按标题定位顶层窗口并置前;window back 回退、window close 关闭当前窗口
goto在浏览器地址栏打开网址,回读地址栏并等待标题 expect 命中
url读取当前页面地址 → $地址
tab列出 / 切换 / 新建 / 关闭浏览器标签页
find定位元素 → $元素;可选视觉兜底 find image / find text 产出坐标
click点击元素(真实鼠标优先,失败按 Pattern 兜底);click at 按坐标点击
hover把真实鼠标移到元素上停留,用于悬停菜单
drag从起点按下拖到终点,用于滑块 / 排序 / 拖放
select选择下拉选项(先按展开模式找,找不到再真实点开)
toggle按目标状态切换勾选 / 开关,已是目标状态不重复点击
invoke按 UIA Pattern 触发控件,不移动鼠标
focus只把焦点交给元素,不改内容
expand展开虚拟滚动内容(点向下按钮,兜底 Ctrl+End)
set写入文本(natural 档真实输入优先,light/off 先 ValuePattern)
let把字面量或变量存入 $文本
type向当前焦点输入文本;≥40 字自动分段粘贴,可 type $变量
key发送组合键,如 ctrl+l
scroll在窗口中心滚动滚轮
clipboard读取 / 写入系统剪贴板
dialog确认或取消系统原生对话框(Enter / Esc)
download等待浏览器下载完成 → $文件路径
get读取元素文本 → $文本
check断言内容 / 状态 / 数量,失败中止;带 -> $ok 时改为软断言
collect收集全部匹配文本 → $文本,可截取锚点区间
count统计匹配元素数量 → $文本;可写 timeout: 轮询等待
extract正则截取第一个捕获组
matches正则取出全部匹配
strip正则删除匹配内容
first取列表第一项 → $变量;空列表为空串
drop从列表移除第一个匹配项 → $剩余列表
push向列表末尾追加一项
len列表项数 → $变量
inc整数自增(inc $变量 2)
read读取文本文件 → $变量;lines 按行拆成列表
append向文本文件追加一行
write用列表覆盖写文本文件(每项一行)
post发送 JSON POST → $响应;非 2xx 失败,可 retry
json按点路径取 JSON 字段 → $变量
newest取下载目录里最新的图片路径;加 optional 时超时置空不中止
wait固定等待毫秒;wait visible / gone / stable 做条件等待
retry失败重试块:整块失败时重试,最多 n 次
log向运行日志输出一行
emit写入能力输出
shot截取当前窗口为 PNG
if条件分支(== / != / contains / in 等)
repeat按次数循环(可用参数次数)
foreach遍历列表变量(可加 quiet 静默成功步骤)
break跳出最近的循环

5. window:定位窗口核心

按标题定位顶层窗口并置于前台,之后的 find / click 都在该窗口内查找。每次切换会把当前窗口压栈。定位时会依次做前置检查:窗口仍然存在、标题/类名匹配、位置可用(最小化或移出屏幕才还原并摆到左侧 1/3)、必要时置前台。

window name:"记事本"
window name~:"Chrome"
window name:/.*Excel.*/
window class:"Chrome_WidgetWin_1"
window name~:"Chrome" expect:"币安广场" timeout:8000

expect:窗口内容断言

expect:"文本" 让 window 在定位后继续等待窗口标题出现该文本,用来确认页面已经加载到目标站点,而不是停在空白页或登录页;超时返回 E_WINDOW_MISMATCH。等待时长沿用 window 的 timeout(默认 5000 ms)。

window back:回到上一个窗口

处理文件对话框等临时窗口后,用 window back 复原到切换前的窗口,避免重复写窗口标题。

find type:button name~:"上传" -> $up
click $up
window class:"#32770"
type "C:\tmp\cover.png"
key enter
window back

window close:关闭当前窗口

向当前定位的窗口发送关闭请求,用于任务结束后清理临时窗口;窗口有未保存提示时不会强杀,需要脚本继续处理弹窗。关闭后当前窗口失效,再次操作前要重新执行 window。

window 必须提供 name: / name~: / name:/…/ / class: 之一;窗口找不到时返回 E_WINDOW_NOT_FOUND。没有可复原窗口时执行 window back 同样报 E_WINDOW_NOT_FOUND。id: 是元素的 AutomationId,不用于窗口定位。

浏览器窗口归属

数字员工启动浏览器后,会给识别到的主窗口打上归属标记。此后脚本里的 window 选择器只要看起来指向浏览器(名称含 Chrome / Chromium / Edge / Firefox / 浏览器 / Browser,或 class 为 Chrome_WidgetWin_* / MozillaWindowClass),就只匹配带标记的窗口;用户自己手动打开的 Chrome 不会被误当成执行目标。

没有带标记的浏览器窗口时,执行前会按设置里的「启动命令」打开浏览器,并把新窗口收归数字员工。对 Chrome / Edge / Chromium / Firefox 会自动追加新窗口参数(--new-window / -new-window),保证标记落在新窗口而不是用户的旧窗口;如果确实没有产生新窗口,则把当前主窗口收归。标记保存在窗口对象上,数字员工重启后仍然有效,直到窗口关闭。

6. find:定位元素核心

在已定位窗口的后代里查找元素,结果存入 $元素 变量,后续动作直接使用该变量。

find type:edit name:"地址栏" timeout:10000 -> $addr
find name~:"搜索" type:button -> $searchBtn
find near:$searchBtn type:text side:below gap:8 -> $hint

必须带「-> $变量」;未找到时按 timeout: 反复重试(每 200ms 一次),超时返回 E_ELEMENT_NOT_FOUND。

optional:允许找不到

find type:button name~:"上传" optional timeout:5000 -> $up
if $up == "" {
    log "没有上传按钮,跳过配图"
}

加 optional 后找不到不报错:变量置为空字符串,后续用 if 判空走降级分支。元素同时保存名称文本,便于日志与判断;无名元素记为 1(表示已找到,避免误判为空)。

optional 只是不报错,不会让 click 变得更宽容:拿空变量去 click 仍会报 E_ELEMENT_NOT_FOUND,所以降级逻辑要写在 if 里。
元素树里找不到目标时(Canvas、自绘控件、远程桌面画面、图片按钮),改用下一节的「视觉兜底」:find image 做模板匹配、find text 做 OCR,产出坐标后 click at 点击。

7. 视觉兜底:模板匹配与 OCR

find image 在当前窗口画面里做本地模板匹配(找锚图),find text 用 Windows OCR 识别屏幕上的文字。两者都把命中的「x,y」屏幕物理坐标写入变量,再用 click at $pt 点击,适合元素树拿不到坐标的场景。

find image:"compose.png" region:$panel min:0.88 scales:0.8~1.25 -> $pt
click at $pt
find text:"导出" region:$panel min:0.8 timeout:5000 -> $txtPt
click at $txtPt

参数

参数说明
image:"锚图.png"锚图路径:绝对路径、~/(用户目录)或相对路径;相对路径在执行存储目录下查找(可先用 shot 截图再裁切)
text:"导出"要识别的文字,按 OCR 结果做相似度匹配
region:$容器先用 find 定位容器元素,把搜索范围限制在它的可见矩形内;省略则搜索整个窗口
min:0.88相似度阈值:image 默认 0.88,text 默认 0.8
scales:0.8~1.25锚图缩放范围,适配系统缩放 / DPI 差异;仅 find image 支持
timeout:ms未命中时每 200ms 重试一次,默认沿用能力超时
optional超时不报错,变量置为空串,便于用 if 走降级分支

锚图怎么准备

锚图就是目标区域的 PNG 截图,只保留按钮 / 图标本身,不要带大片背景;尺寸建议不超过 300×300。用 shot 截当前窗口后裁切,或从设计稿导出。系统缩放变化时用 scales 放宽范围。

视觉定位前必须先执行 window:运行时会先置前台再抓屏。窗口被其他程序遮挡、目标滚出可视区、系统缩放变化都会影响命中;OCR 需要系统安装对应语言的 OCR 语言包,否则识别为空。

8. click:点击

目标是 $元素 变量或内联选择器(选择器同样支持 under / next / prev / near)。默认 natural 档用真实鼠标沿轨迹移入可见区落点并点击;点完用 ElementFromPoint 核对落点,点空时按新位置重点或改走 UIA Pattern(Invoke → Toggle → SelectionItem → LegacyIAccessible),不会硬失败。light / off 档直接走 Pattern,light 仍会先移入悬停。

click $searchBtn
click name:"发送" type:button
click name~:"确定" index:2

click at:按坐标点击

元素定位不到时可按坐标点击,三种写法:click at 120,340 点屏幕物理坐标;click at $el 50%,30% 点元素可见矩形内的相对位置(0~100,省略纵向为居中);click at $pt 点 find image / find text 产出的视觉坐标。坐标点击同样带前台校验。

click at 120,340
click at $canvas 50%,30%
find image:"play.png" -> $pt
click at $pt
只有退化成坐标点击时才做前台校验:先确认归属窗口仍存在,不在前台则先激活,激活被拒绝就报 E_WINDOW_NOT_FOREGROUND 并中止,避免点击落到被遮挡后露出的其他窗口。UIA Pattern 点击不需要前台,不会抢焦点。

9. focus:聚焦元素

只把焦点交给元素(SetFocus),不改动内容与光标位置;适合先聚焦再发送组合键。

focus $editor
key ctrl+home
type "开头的话"

10. set:写入文本核心

默认 natural 档先聚焦并写入:先把焦点交给控件,只有 SetFocus 没拿到键盘焦点时才补一次可见区内真实点击;≥40 字用分段剪贴板粘贴,短文本 Unicode 逐字注入。写入后自动回读,读回为空或明显缺字会换另一种方式重试一次,仍不一致就报 E_ACTION_FAILED,避免「写成功但内容为空」。light / off 档先走 ValuePattern.SetValue,不支持或写入未生效再转真实输入。正文里的换行原样保留、不额外补空行(\r\n、单独的 \r、\n 都算一个换行)。写入时按行分段:行内粘贴或逐字,行与行之间发真实换行键(默认 Shift+Enter,聊天编辑器里不会被当成发送)——Slate / Draft 这类编辑器粘贴纯文本时不会把 \n 拆成段落,只靠剪贴板里的换行符会整段挤成一行。只认单独 Enter 的编辑器可在能力配置里写 "newlineKey": "enter"。

set $addr "https://example.com"
set name:"搜索框" "搜索 {kw}"
set $title $text
写入内容在最后:可以是字符串字面量,也可以是 $变量(set $var $src)。目标(变量或选择器)写在它前面。

11. type:逐字输入

把文本输入当前焦点控件,走 Unicode 通道,不依赖输入法,中文与符号同样可用;≥40 字自动改为分段剪贴板粘贴(12~25 字/段),短文本逐字输入并带拟人节奏,换行会发真实回车键。内容也可以来自变量:type $变量。输入前会校验焦点:若仍停在浏览器地址栏则直接报 E_ACTION_FAILED,避免整段文字变成网址。

type "你好,世界"
type "{kw}"
type $text
type / key / scroll / shot 执行前会确认目标窗口仍然存在且在前台:不在前台先尝试置前,系统拒绝激活则直接报 E_WINDOW_NOT_FOREGROUND 并中止,避免输入落到其他窗口;窗口已关闭则报 E_WINDOW_CLOSED。

12. key:组合键

用加号分隔按键,末位为主键;支持 ctrl / shift / alt / enter / tab / esc / space / delete / backspace / home / end / 方向键 / pageup / pagedown 与单个字母数字。

key ctrl+l
key enter
key ctrl+shift+tab

13. scroll:滚轮

在窗口中心滚动滚轮,格式为 scroll up/down 格数;格数可写整数或 {参数},单条命令最多 100 格,省略时默认 3。

scroll down 3
scroll up {max_scroll}
滚动前必须先用 window 指定窗口;需要精确到元素时,先用 near: 定位再点击,而不是盲滚。

14. get:读取文本核心

超链接优先取 Name(Value 是跳转地址),其余依次尝试 ValuePattern → TextPattern → Name,把结果写入 $文本 变量,供 log / emit / if 与文本处理命令使用。

get $addr -> $url
get name~:"结果" -> $result
emit answer $result

与 find 一样必须带「-> $变量」。

15. collect:收集文本

收集全部匹配元素的文本,用中文分号连接成一个 $文本 变量;超链接同样取 Name。选择器支持 under / next / prev / near。

collect type:hyperlink -> $links
collect type:text after:"提示词" until:"复制" timeout:15000 -> $answer

加 after: / until: 后改为截取「锚点之后、结束标记之前」的片段,并用换行连接。它们只是文本锚点(可写 /正则/),不是元素变量;页面边生成边渲染时,引擎要求连续两次采样一致才返回。

collect 在 timeout: 内反复重扫(默认 3000ms,命中候选后放慢节奏);超时仍未收集到内容返回 E_ELEMENT_NOT_FOUND。需要单条元素时用 find。

16. expand:展开全部内容

用于虚拟滚动的输入框 / 会话区:在输入框上方靠右找一个小号无名称按钮(向下箭头)并点击,让历史内容完整渲染;10 秒内找不到则 Ctrl+End 滚到底部。

find type:edit index:1 -> $box
expand $box
collect type:text after:"提示词" until:"复制" -> $body
expand 需要先用 find 定位输入框;它只是尽力展开,找不到向下按钮也不报错。

17. hover / drag:悬停与拖拽

hover 把真实鼠标移到元素中心并停留(不点击),用于悬停菜单、浮层和 tooltip;drag $起点 to $终点 真实按下 → 分段移动 → 抬起,用于滑块、列表排序和拖放上传。两者都支持 $元素变量与内联选择器。

hover $menu
find type:listitem name~:"导出报表" -> $item
click $item
drag $slider to $target
drag type:"listitem" name~:"卡片 1" to type:"list" name~:"回收站"
悬停菜单出现后通常需要几十毫秒动画,紧接 click 前可加 wait visible <目标> 或 wait stable,避免点空。拖拽距离过短时系统可能识别为点击,滑动条建议分多段移动。

18. select / toggle:下拉与开关

select $el "选项文本"(也可传 $变量)先按展开模式打开下拉,在该元素的子树里按文本匹配选项,找不到才真实点开后选择;toggle $el on|off 先读当前状态,已是目标状态时不重复点击,也接受 true/false、1/0。

select $category "发布能力"
select $city $targetCity
toggle $remember on
toggle $switch false
选项文本必须与界面显示一致(空格、全角字符、省略号都会影响匹配);自绘下拉(不是标准 ComboBox)不支持时,改用 click 展开 + find/click 选项。

19. clipboard:剪贴板

clipboard get -> $变量 读取系统剪贴板文本;clipboard set "文本" 或 clipboard set $变量 写入剪贴板。适合从无法直接读取的控件取值,或把长文本一次性粘贴到输入框。

clipboard get -> $code
check $code matches:/^\d{6}$/
clipboard set "已处理:{name}"
clipboard set $text
clipboard set 会覆盖用户当前剪贴板;读取前先确认目标应用已完成复制(可加 wait stable 或固定 wait)。

20. dialog:原生对话框

在 window 指定的窗口上处理系统原生对话框(会先置前台),不需要单独定位对话框自身:dialog accept 按 Enter 确认,dialog dismiss 按 Esc 取消。常见于下载确认、证书警告、退出确认。

click $download
wait visible class:"#32770" timeout:15000
dialog accept
wait gone class:"#32770" timeout:10000 -> $closed
网页内弹窗不是原生对话框,仍用 find / click;dialog 只响应真实系统对话框,且依赖 window 先定位到对话框所属窗口。

21. url:读取当前地址

url -> $变量 通过 UIA 从浏览器地址栏读取当前页面地址,不启动任何浏览器接口,适合确认跳转结果或把链接写入文件。

window name~:"Chrome"
url -> $link
check $link contains "/publish"
append "~/published-urls.txt" $link
需要先 window 定位到浏览器窗口;非浏览器窗口或读不到地址栏时报 E_ELEMENT_NOT_FOUND。

22. tab:标签页

tab list -> $变量 列出全部标签标题;tab switch 2 或 tab switch "标题" 切换标签;tab new ["URL"] 新建标签;tab close [序号] 关闭指定标签(省略则关闭当前)。依赖浏览器向 UIA 暴露的标签栏。

tab list -> $tabs
tab new "https://example.com"
tab switch "工作台"
wait stable type:document stable:1000 timeout:60000 -> $body
tab close 1
不同 Chromium 版本的标签栏结构可能不同,找不到标签栏时会报 E_ELEMENT_NOT_FOUND,可改用 key ctrl+tab 切换;切换后页面可能仍在加载,建议接 wait visible / wait stable。标题重复时改用序号。

23. download wait:等待下载完成

download wait timeout:60000 -> $变量 轮询浏览器下载目录,跳过 .crdownload / .part 等临时文件,只认本次执行前后新写出的文件,待文件大小稳定后返回绝对路径。

click $export
wait gone type:progressbar timeout:120000
download wait timeout:180000 -> $file
log "已下载:$file"
依赖浏览器使用默认下载目录;并发下载多个文件时返回最先稳定的那个。网络慢或文件大时放大 timeout。

24. read / append / write:读写文本文件

read "路径" -> $变量 读取文本,加 lines 时按行拆成列表(跳过空行);append "路径" "内容" 追加一行(内容里的换行会折成空格);write "路径" $列表 覆盖写,列表每项一行,空列表清空文件。路径支持绝对路径、~/ 与 %USERPROFILE%,相对路径基于用户目录。

read "~/queue.txt" lines -> $queue
first $queue -> $item
append "~/done.txt" "{name}\t$item"
drop $queue $item -> $rest
write "~/queue.txt" $rest
文件不存在时 read 按空串处理,首次运行不会中断;append / write 会自动创建父目录。列表要用 read lines / collect 生成,不要用字符串拼接,否则 first / drop 会按整串处理。

25. post / json:接口请求与取值

post "地址" "{\"key\":$var}" -> $响应 发送 JSON POST,非 2xx 视为失败,可加 retry 3 自动重试;json $响应 "data.items" -> $值 按点路径取值,数组按项拼成列表,路径不存在为空串。适合对接自己的业务接口做数据补充。

post "https://api.example.com/tasks" "{\"page\":$page}" retry 2 -> $resp
json $resp "data.items" -> $items
len $items -> $n
foreach $item in $items {
    log "任务:$item"
}
接口返回必须是 JSON 才能用 json 取值;请求体中的 {参数} 与 $变量都会展开。不要把 API Key 直接写进脚本,敏感配置放在能力 config 里。

26. let:存入变量

把字面量或另一个变量的值存入 $文本 变量,用于在脚本内先做一次拷贝再反复处理。

let $raw "{body}"
let $copy $raw

27. extract:正则截取

用 /正则/ 截取变量内容:有捕获组取第 1 组,没有捕获组取整个匹配;完全不匹配时保留原值。

let $raw "{body}"
extract $raw /^([^;]+)/ -> $head
extract $raw /^[^;]+;?/ -> $rest

28. matches:取出全部匹配

用 /正则/ 取出全部匹配(取完整匹配文本,不是捕获组),用中文分号连接;无匹配结果为空字符串。

let $raw "{body}"
matches $raw "/#[^#,。!?;:、]+/" -> $tags
foreach $t in $tags {
    log "标签:$t"
}

29. strip:删除匹配内容

用 /正则/ 删除变量里所有匹配内容,常用于把正文里的标签剥离成纯文本。

let $raw "{body}"
strip $raw "/#[^#,。!?;:、]+/" -> $plain
set $editor $plain

30. 列表与计数:first / drop / push / len / inc

列表是引擎里的结构化变量,由 read lines / collect 等产出:first $列表 -> $项 取第 1 项,len $列表 -> $n 取项数,drop $列表 $项 -> $剩余 移除第一个匹配项,push $列表 值 在末尾追加一项,inc $变量 2 做整数自增(变量缺失按 0 起算)。日志与输出里列表显示为以「;」分隔。

read "~/queue.txt" lines -> $queue
len $queue -> $n
first $queue -> $item
drop $queue $item -> $rest
write "~/queue.txt" $rest
push $done $item
inc $page {page_size}
列表必须由 read lines / collect 等命令生成,手工用字符串拼接会被当成一整项,first / drop 失效;first 遇到空列表返回空串,drop 只删除第一个匹配项,重复记录需要循环处理。

31. newest:最新图片

取下载目录里最新的图片路径。目录参数为空时用 %USERPROFILE%\Downloads;30 秒内轮询,只接受 5 分钟内写出的文件,支持 png / jpg / jpeg / webp / gif。

默认等到 30 秒超时就抛 E_ELEMENT_NOT_FOUND 中止整条脚本。配图是可选环节时加 optional:超时只把变量置空并继续,日志写明「没有新图片」,后续用 if $img == "" 分流即可。注意用 if 包住 newest 并不能兜底,错误发生在块内同样会中止。

# 必需:等不到就中止
newest "" -> $img

# 可选:等不到就置空并继续
newest "" -> $img optional
if $img == "" {
    log "本次没有配图"
}
newest 只负责找路径,不会帮你上传;需要上传时把路径填进文件对话框再回车。下载中的临时文件会被自动排除。

32. wait:等待

wait 800
wait {wait_ms}

等待指定毫秒(单次最多 600000ms);界面切换、页面加载后用固定等待兜底,更推荐用 find / collect 的 timeout: 做条件等待。

33. log:运行日志

log "开始执行"
log "关键词:{kw},结果:$result"

输出到工作日志,参与实时推送与执行记录;支持 {参数名} 与 $变量 插值。

34. if:条件分支

条件由「左操作数」「比较符」「右操作数」三部分组成,操作数可以是 $变量 或字面量,比较符支持 ==、!=、contains;块以行尾的 { 开头、单独一行 } 收尾。

get $addr -> $url
if $url contains "example.com" {
    log "已在目标站点"
}
if $up == "" {
    log "按钮不存在,走备用路径"
}

35. repeat:循环

次数可以是整数,也可以是 {参数名};单次执行上限 1000 次。循环体内可以用 break 提前结束。

repeat 3 {
    key tab
    wait 300
}

36. foreach:遍历列表

列表变量按中文分号拆成多项(自动去空白、跳过空项),每轮把当前项写入 $item,循环变量只在循环体内可见。

let $raw "{body}"
matches $raw "/#[^#,。!?;:、]+/" -> $tags
foreach $t in $tags {
    log "标签:$t"
}

37. break:跳出循环

跳出最近的 repeat / foreach;写在 if 里时会一路传到外层循环。

repeat 10 {
    get name~:"状态" -> $s
    if $s contains "完成" {
        break
    }
    wait 500
}

38. emit:写入输出

把 $文本 变量或字面量写入能力输出,名称需与 @output 声明一致;输出会出现在执行结果里,可供后续节点使用。

emit result $result
emit site "示例站点"

39. shot:截图

截取当前已定位窗口为 PNG,保存到执行存储目录;输出名为文件名,值为绝对路径。

shot "step1.png"
截图前必须先执行 window,否则返回 E_WINDOW_NOT_FOUND。

40. goto:打开网址并确认加载核心

在已定位的浏览器窗口里打开地址:先用 UIA 找到地址栏并真实点击聚焦,输入网址后回读地址栏,确认真的写进去了才回车;没写进去先按 Esc 收起「要恢复页面吗?」一类浮窗再重试(最多 3 次),始终不落地就报 E_ACTION_FAILED 且不按回车。首次 goto 还会先等 config.humanize.gotoSettleMs(默认 5000ms,0 表示不等),避开浏览器冷启动的欢迎页和提示。输入时会在网址末尾自动补一个空格,阻止地址栏按历史记录/联想词改写输入(避免回车打开联想出来的另一个地址);回读比较会忽略这个空格,导航本身也不受影响。

@input url 目标网址 =https://example.com
@input expect 标题关键词 =示例
window name:/.../ timeout:8000
goto "{url}" expect:"{expect}" timeout:20000

expect 支持普通文本或 /正则/,接入 window expect 同样的标题断言,仅在标题出现后继续;超时返回 E_NAVIGATE_TIMEOUT。地址也可以来自变量:goto $url。

不要再用 key ctrl+l + wait 1500 的老写法:固定等待既慢又不可靠,goto 会回读地址栏并用标题确认页面真的加载完成。

41. invoke:模式触发控件

不移动鼠标,直接按 UIA Pattern 触发控件(Invoke → Toggle → SelectionItem → LegacyIAccessible)。适合真实点击点不准的控件:Chrome 里隐藏的 <input type=file> 矩形会横跨工具栏多个图标且不参与命中测试,click 只能碰运气,invoke 每次都能弹出文件对话框。失败时会按原选择器重新定位一次再试。

find type:button name~:"上传" -> $up
invoke $up
invoke 不会抢焦点,也不会移动到控件上;需要悬停 / 真实点击时仍用 click。

42. check:断言内容与状态核心

check 是只读断言,不移动焦点、不改内容。内容比较支持 ==(忽略零宽字符与空白差异)、contains、~=(编辑距离相似度,tolerance:0~1,默认 0.9)、matches:/正则/;状态检查支持 exists:1 / visible:1 / enabled:1 / focused:1 / checked:1;数量用 check $n >= 2。

find type:edit index:1 -> $editor
get $editor -> $text
check $text contains "已发布"
check $text ~= "{expected}" tolerance:0.9
check $editor exists:1 visible:1
count type:listitem visible:1 -> $n
check $n >= 1
不带 -> $ok 是硬断言,未通过抛 E_CHECK_FAILED 并中止;带 -> $ok 是软断言,只把 1/0 写进变量。check 加 timeout: 时会每 200ms 轮询到满足为止,适合等按钮从禁用变为可用、等「已保存」出现。set / type 不保证写入结果,写后必须用 check 判定。

43. count:统计元素数量

统计匹配元素的数量写入 $文本 变量,常用于确认列表真的渲染出了条目。写了 timeout: 时每 200ms 轮询到出现匹配再计数;不写只做一次即时统计,数量为 0 也不报错。limit:n 只统计前 n 个。

count type:listitem visible:1 timeout:5000 -> $n
log "列表项数量:$n"
check $n >= 1

44. retry:失败重试块

retry n { … } 是整块重试:块内任一语句失败就从块首重新执行,最多 n 次(整数或 {参数},上限 1000);每次失败单独记一条日志,全部失败后上抛最后一次错误。与固定重复的 repeat 不同,retry 只在失败时重来。

retry 3 {
    find name:"保存" type:button timeout:5000 -> $btn
    click $btn
    wait stable name:"已保存" timeout:5000 -> $state
}
if $state contains "已保存" {
    emit result "ok"
}
失败时会自动保存一张现场截图,路径写在错误信息与日志里;块内尽量只放可重复执行的动作,避免重复提交。

45. wait visible / gone / stable:条件等待

wait visible <目标> [timeout:ms] 等元素出现并可见(默认 10000ms);wait gone <目标> [timeout:ms] [-> $ok] 等元素消失或窗口关闭(默认 5000ms),加 -> $ok 时变成检测:消失写 1、超时写 0 且不中止;wait stable <目标> [stable:ms] [timeout:ms] [-> $out] 等文本连续 stable 毫秒不变且非空,stable 默认 800、timeout 默认 20000,可直接接稳定后的文本。

click $up
window class:"#32770" timeout:8000
type "C:\tmp\cover.png"
key enter
window back
wait gone class:"#32770" timeout:20000 -> $closed
if $closed != "1" {
    log "文件对话框没有关闭,上传可能未提交"
}
wait stable type:document stable:1500 timeout:90000 -> $answer
log "回答已稳定:$answer"
固定 wait 只增不减且受总时长预算封顶;能等状态的场景优先用 wait visible / gone / stable,速度与稳定性都更好。

46. 拟人化(默认开启)

拟人化在引擎层实现,所有脚本不改也生效:鼠标沿三次贝塞尔轨迹移动(两端慢中段快、带抖动与过冲回拉)、落点不取正中;文字逐字输入并带节奏,长文本分段粘贴;滚轮分段逐格;切换窗口 / 打开网址 / 页面加载后按档位停留;显式 wait 只增不减。每次运行首行会输出一条 humanize 日志说明档位。

"humanize": {
  "level": "natural",   # off | light | natural | careful(默认 natural)
  "speed": 1.0,         # 节奏倍率 0.3~3.0,越大越快
  "mouse": true,
  "typing": true,
  "dwell": true,
  "pasteOver": 40,      # ≥ 该字数走粘贴
  "gotoSettleMs": 5000, # 首次 goto 前等待浏览器稳定
  "seed": 0
}
可在系统设置里写全局默认(settings 表 key=humanize,值为档位名或 JSON),再用能力内 config.humanize 覆盖;写成 "off" 或 false 表示整份关闭。动作内部停顿都受 config.maxMs 封顶。某站点在 natural 下不稳定时,可降为 light 或把 speed 调大。

执行期屏幕保活与锁屏

通道 B 注入的真实键鼠事件在息屏 / 睡眠期间会被系统丢弃(表现为脚本跑完但页面一个字没写)。所以每条能力执行期间默认阻止息屏与睡眠(顺带挡掉空闲自动锁屏),结束时恢复;显示器若已黑掉会先点亮。这两项走能力 config:keepAwake(默认 true)、allowLockedScreen(默认 false)。

"keepAwake": true,        # 执行期阻止息屏/睡眠,结束恢复
"allowLockedScreen": false, # 锁屏时直接报 E_SESSION_LOCKED
锁屏(Win+L / 锁屏界面)无法被程序解除:那是 Winlogon 安全桌面,模拟输入会被系统丢掉,程序自己代输密码也不安全。能做的只有「不让它因空闲而锁」和「锁了就直接报 E_SESSION_LOCKED 提示先解锁」。

47. 参考用法:校验优先

以下片段可直接复制改造。核心原则:每个「看起来成功」的动作后面都补一条 check / wait,避免点了没生效却上报成功。

打开 → 写入 → 发送 → 确认

@input url 目标网址
@input body 正文
window name:/.../ timeout:8000
goto "{url}" expect:/.../ timeout:20000
find type:edit index:1 -> $editor
set $editor "{body}"
check $editor exists:1
find name:/发送|Send/ type:button timeout:5000 -> $send
click $send
wait gone type:edit index:1 timeout:15000 -> $closed
if $closed != "1" {
    log "编辑器没有收起,发送可能未生效"
}

上传配图并确认对话框关闭

newest "" -> $img
find type:button name~:"上传" -> $up
invoke $up
window class:"#32770" timeout:8000
type "$img"
key enter
window back
wait gone class:"#32770" timeout:20000 -> $closed
check $closed == "1"

流式回答:等稳定再取正文

wait stable type:document stable:1500 timeout:90000 -> $answer
collect type:text after:"提示词" until:"复制" timeout:15000 -> $body
extract $body /^([^;]+)/ -> $head
emit reply $body
硬断言用于「这里错了就不该继续」;需要降级分支时写 check … -> $ok,再用 if $ok != "1" 走备用路径。

48. 错误码对照

错误码含义排查方向
E_SCRIPT_PARSE脚本解析失败看日志中的行号与提示;检查 } 是否配对、选择器键名、-> $变量、变量是否先定义、emit 是否已声明
E_PARAM_INVALID参数不合法或缺失检查 @input 声明与调用方传参;不支持的按键名;数字参数(wait/repeat/scroll)是否为非负整数
E_UIA_INITUIA 初始化失败系统设置 → 环境检测里看 UIA 项;必要时一键修复重启引擎
E_WINDOW_NOT_FOUND窗口未找到确认程序已打开;标题用 name~: 或正则做模糊匹配;window back 前需先执行过 window
E_WINDOW_MISMATCH窗口内容不符expect: 断言在 timeout 内未命中:确认页面已加载完、网址/标题正确;必要时放大 timeout: 或换成更稳定的关键词
E_WINDOW_CLOSED窗口已关闭浏览器窗口在运行中被关闭:重新执行 window,让脚本重新定位或重新打开浏览器
E_WINDOW_NOT_FOREGROUND窗口无法置前被全屏程序或更高权限窗口占住前台:关闭遮挡窗口后重试;不会盲发键盘输入
E_ELEMENT_NOT_FOUND元素未找到核对名称与类型;放大 timeout:;加 index: 或改用 next/prev/near;留意日志里「扫描上限」的遗漏提示
E_NAVIGATE_TIMEOUTgoto 加载超时expect 标题在 timeout 内未出现:确认网址正确、页面能打开、标题关键词稳定;必要时放大 goto 的 timeout:
E_WAIT_TIMEOUT条件等待超时wait visible / gone / stable 未在 timeout 内满足:放大 timeout: 或换更稳定的目标(带 -> $变量 的 gone / stable 不会中止)
E_CHECK_FAILED断言未通过硬断言(未写 -> $ok)未通过:错误里带期望 / 实际值与首处差异;先确认上一步真的写入,再考虑放宽为 ~= 或加 timeout: 轮询
E_CHECK_UNSUPPORTED控件不支持检测目标没有 ValuePattern / TextPattern(读不到内容),或没有 TogglePattern(读不到 checked);改用 get + 文本判断
E_TIMEOUT能力执行超时超过 config.maxMs(默认 30 分钟,0 不限):拆分长任务或调大预算;单条语句的 timeout: 也受剩余预算封顶
E_SESSION_LOCKED屏幕已锁定运行前检测到屏幕已锁(Win+L / 锁屏界面)。锁屏是 Winlogon 安全桌面,模拟键鼠会被系统丢弃,程序无法解锁,只能提示先解锁;确有需要可设 config.allowLockedScreen=1 跳过检查
E_IMPL_RETIRED实现已下线调用了已下线的历史浏览器自动化能力:改用 UIA 脚本编写
E_ACTION_FAILED动作执行失败元素可能不可交互(隐藏 / 禁用);先 click 或 focus 再操作

49. 示例:记事本写入

@input text 写入内容 =数字员工 UIA 脚本
@output body 写入后的内容
window name~:"记事本"
set name~:"文本编辑器" "{text}"
get name~:"文本编辑器" -> $read
emit body $read

记事本的编辑区在不同版本里可能叫「文本编辑器」或「文档」,用 name~: 更稳。参数用 {text} 插值。

50. 示例:Chrome 打开网址

@input url 目标网址 =https://example.com
@output after-open.png 截图路径
window name~:"Chrome"
key ctrl+l
type "{url}"
key enter
wait 1200
shot "after-open.png"

地址栏也可以走通道 A:find type:edit name~:"地址栏" -> $addr 再 set $addr "{url}"。

51. 示例:相对定位与可选元素

@input anchor 起始文本 =提示词
@input stop 结束文本 =复制
@output body 读取到的正文
window name~:"Chrome"
find type:text name~:"{anchor}" -> $a
find near:$a type:button side:below gap:8 optional timeout:5000 -> $more
if $more != "" {
    click $more
}
collect type:text after:"{anchor}" until:"{stop}" timeout:15000 -> $body
emit body $body

锚点元素先用 find 定位,再用 near 找它下方的按钮;按钮可能不存在,所以加 optional 并用 if 判空。collect 用文本锚点截取模型回答,不依赖固定元素序号。

52. 示例:轮询状态并提前结束

@input expect 期望文本 =完成
@output status 命中时的状态
@output done 是否命中
let $done "0"
repeat 10 {
    get name~:"状态" -> $s
    if $s contains "{expect}" {
        let $done "1"
        emit status $s
        break
    }
    wait 600
}
emit done $done

break 会立刻结束 repeat;用 done 输出标记是否命中,调用方无需再判断状态文本。