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: 的实参如果写成 /正则/,运行时自动按正则匹配,一个参数即可切换匹配方式
执行模型与边界
| 维度 | 说明 |
|---|---|
| 执行位置 | 数字员工桌面端进程内(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"2. 选择器
选择器用「键:值」描述元素,多个键用空格并列,相互之间是 AND 关系。
| 键 | 含义 | 示例 |
|---|---|---|
| name: | 名称精确匹配 | name:"发送" |
| name~: | 名称包含子串 | name~:"地址" |
| name:/…/ | 名称正则匹配 | name:/Chrome.*/ |
| type: | UIA 控件类型 | type:button |
| id: | AutomationId(元素定位用;浏览器顶层窗口通常为空,window 不使用 id) | id:"submit" |
| id~: | AutomationId 包含子串(也可写 / 正则/) | id~:"send" |
| class: | 窗口 / 控件 ClassName | class:"Chrome_WidgetWin_1" |
| class~: | ClassName 包含子串(也可写 / 正则/) | class~:"WidgetWin" |
| value: | 按当前值过滤(ValuePattern → TextPattern → 名称) | value:"已发布" |
| value~: | 当前值包含子串(也可写 / 正则/) | value~:"成功" |
| visible: | 只要可见元素;0 取反,支持 true/false | visible:1 |
| enabled: | 只要可用元素;0 取反 | enabled:1 |
| childof: | 只找该元素的直接子级 | childof:$panel |
| limit: | 最多取前 N 个结果(仅 collect / count 生效) | limit:20 |
| index: | 第 N 个匹配项,从 1 开始;可写 index:{参数} | index:2 |
| min: | 最小边长(像素),排除小图标 / 头像 | min:24 |
| timeout: | 定位超时毫秒,默认 3000 | timeout:8000 |
| under: | 只在该元素子树里搜索(浮层 / 对话框) | under:$tip |
| next: | 锚点之后的下一个同级元素 | next:$box |
| prev: | 锚点之前的上一个同级元素 | prev:$box |
| near: | 锚点附近的元素(按方向 / 距离) | near:$box |
| side: | near 的方向:right / left / above / below / any | side:right |
| gap: | near 的最小间距(像素) | gap:12 |
| depth: | next / prev 向上找同级的层数,1-3 | depth: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作用域
find type:tooltip optional timeout:3000 -> $tip
find under:$tip type:text name~:"候选" optional -> $option3. 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:8000expect:窗口内容断言
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 backwindow close:关闭当前窗口
向当前定位的窗口发送关闭请求,用于任务结束后清理临时窗口;窗口有未保存提示时不会强杀,需要脚本继续处理弹窗。关闭后当前窗口失效,再次操作前要重新执行 window。
浏览器窗口归属
数字员工启动浏览器后,会给识别到的主窗口打上归属标记。此后脚本里的 window 选择器只要看起来指向浏览器(名称含 Chrome / Chromium / Edge / Firefox / 浏览器 / Browser,或 class 为 Chrome_WidgetWin_* / MozillaWindowClass),就只匹配带标记的窗口;用户自己手动打开的 Chrome 不会被误当成执行目标。
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(表示已找到,避免误判为空)。
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 放宽范围。
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:2click 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 $pt9. 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 $text11. type:逐字输入
把文本输入当前焦点控件,走 Unicode 通道,不依赖输入法,中文与符号同样可用;≥40 字自动改为分段剪贴板粘贴(12~25 字/段),短文本逐字输入并带拟人节奏,换行会发真实回车键。内容也可以来自变量:type $变量。输入前会校验焦点:若仍停在浏览器地址栏则直接报 E_ACTION_FAILED,避免整段文字变成网址。
type "你好,世界"
type "{kw}"
type $text12. key:组合键
用加号分隔按键,末位为主键;支持 ctrl / shift / alt / enter / tab / esc / space / delete / backspace / home / end / 方向键 / pageup / pagedown 与单个字母数字。
key ctrl+l
key enter
key ctrl+shift+tab13. scroll:滚轮
在窗口中心滚动滚轮,格式为 scroll up/down 格数;格数可写整数或 {参数},单条命令最多 100 格,省略时默认 3。
scroll down 3
scroll up {max_scroll}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: 后改为截取「锚点之后、结束标记之前」的片段,并用换行连接。它们只是文本锚点(可写 /正则/),不是元素变量;页面边生成边渲染时,引擎要求连续两次采样一致才返回。
16. expand:展开全部内容
用于虚拟滚动的输入框 / 会话区:在输入框上方靠右找一个小号无名称按钮(向下箭头)并点击,让历史内容完整渲染;10 秒内找不到则 Ctrl+End 滚到底部。
find type:edit index:1 -> $box
expand $box
collect type:text after:"提示词" until:"复制" -> $body17. 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~:"回收站"18. select / toggle:下拉与开关
select $el "选项文本"(也可传 $变量)先按展开模式打开下拉,在该元素的子树里按文本匹配选项,找不到才真实点开后选择;toggle $el on|off 先读当前状态,已是目标状态时不重复点击,也接受 true/false、1/0。
select $category "发布能力"
select $city $targetCity
toggle $remember on
toggle $switch false19. clipboard:剪贴板
clipboard get -> $变量 读取系统剪贴板文本;clipboard set "文本" 或 clipboard set $变量 写入剪贴板。适合从无法直接读取的控件取值,或把长文本一次性粘贴到输入框。
clipboard get -> $code
check $code matches:/^\d{6}$/
clipboard set "已处理:{name}"
clipboard set $text20. dialog:原生对话框
在 window 指定的窗口上处理系统原生对话框(会先置前台),不需要单独定位对话框自身:dialog accept 按 Enter 确认,dialog dismiss 按 Esc 取消。常见于下载确认、证书警告、退出确认。
click $download
wait visible class:"#32770" timeout:15000
dialog accept
wait gone class:"#32770" timeout:10000 -> $closed21. url:读取当前地址
url -> $变量 通过 UIA 从浏览器地址栏读取当前页面地址,不启动任何浏览器接口,适合确认跳转结果或把链接写入文件。
window name~:"Chrome"
url -> $link
check $link contains "/publish"
append "~/published-urls.txt" $link22. 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 123. download wait:等待下载完成
download wait timeout:60000 -> $变量 轮询浏览器下载目录,跳过 .crdownload / .part 等临时文件,只认本次执行前后新写出的文件,待文件大小稳定后返回绝对路径。
click $export
wait gone type:progressbar timeout:120000
download wait timeout:180000 -> $file
log "已下载:$file"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" $rest25. 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"
}26. let:存入变量
把字面量或另一个变量的值存入 $文本 变量,用于在脚本内先做一次拷贝再反复处理。
let $raw "{body}"
let $copy $raw27. extract:正则截取
用 /正则/ 截取变量内容:有捕获组取第 1 组,没有捕获组取整个匹配;完全不匹配时保留原值。
let $raw "{body}"
extract $raw /^([^;]+)/ -> $head
extract $raw /^[^;]+;?/ -> $rest28. matches:取出全部匹配
用 /正则/ 取出全部匹配(取完整匹配文本,不是捕获组),用中文分号连接;无匹配结果为空字符串。
let $raw "{body}"
matches $raw "/#[^#,。!?;:、]+/" -> $tags
foreach $t in $tags {
log "标签:$t"
}29. strip:删除匹配内容
用 /正则/ 删除变量里所有匹配内容,常用于把正文里的标签剥离成纯文本。
let $raw "{body}"
strip $raw "/#[^#,。!?;:、]+/" -> $plain
set $editor $plain30. 列表与计数: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}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 "本次没有配图"
}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"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:20000expect 支持普通文本或 /正则/,接入 window expect 同样的标题断言,仅在标题出现后继续;超时返回 E_NAVIGATE_TIMEOUT。地址也可以来自变量:goto $url。
41. invoke:模式触发控件
不移动鼠标,直接按 UIA Pattern 触发控件(Invoke → Toggle → SelectionItem → LegacyIAccessible)。适合真实点击点不准的控件:Chrome 里隐藏的 <input type=file> 矩形会横跨工具栏多个图标且不参与命中测试,click 只能碰运气,invoke 每次都能弹出文件对话框。失败时会按原选择器重新定位一次再试。
find type:button name~:"上传" -> $up
invoke $up42. 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 >= 143. count:统计元素数量
统计匹配元素的数量写入 $文本 变量,常用于确认列表真的渲染出了条目。写了 timeout: 时每 200ms 轮询到出现匹配再计数;不写只做一次即时统计,数量为 0 也不报错。limit:n 只统计前 n 个。
count type:listitem visible:1 timeout:5000 -> $n
log "列表项数量:$n"
check $n >= 144. 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"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
}执行期屏幕保活与锁屏
通道 B 注入的真实键鼠事件在息屏 / 睡眠期间会被系统丢弃(表现为脚本跑完但页面一个字没写)。所以每条能力执行期间默认阻止息屏与睡眠(顺带挡掉空闲自动锁屏),结束时恢复;显示器若已黑掉会先点亮。这两项走能力 config:keepAwake(默认 true)、allowLockedScreen(默认 false)。
"keepAwake": true, # 执行期阻止息屏/睡眠,结束恢复
"allowLockedScreen": false, # 锁屏时直接报 E_SESSION_LOCKED47. 参考用法:校验优先
以下片段可直接复制改造。核心原则:每个「看起来成功」的动作后面都补一条 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 $body48. 错误码对照
| 错误码 | 含义 | 排查方向 |
|---|---|---|
| E_SCRIPT_PARSE | 脚本解析失败 | 看日志中的行号与提示;检查 } 是否配对、选择器键名、-> $变量、变量是否先定义、emit 是否已声明 |
| E_PARAM_INVALID | 参数不合法或缺失 | 检查 @input 声明与调用方传参;不支持的按键名;数字参数(wait/repeat/scroll)是否为非负整数 |
| E_UIA_INIT | UIA 初始化失败 | 系统设置 → 环境检测里看 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_TIMEOUT | goto 加载超时 | 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 $donebreak 会立刻结束 repeat;用 done 输出标记是否命中,调用方无需再判断状态文本。
