跳到主要内容

工作流步骤参考

工作流由多个 步骤 按顺序组成。在编辑器里 插入步骤 时，下表对应菜单里的各项。本节供 查阅参数 用，不必通读。

几个常用概念
  • 保存到变量（saveAs）：某步的结果存个名字，后面步骤用 {{名字}} 或 从上一步读取 引用
  • 变量池：编辑器工具栏可查看 流程配置 与 步骤结果，试跑后可看实际值
  • 跳过条件：满足条件时跳过这一步
  • 失败处理：这一步失败时跳转到别的步骤或执行补救
环境与授权

步骤能否成功，取决于 环境与授权：USB 设备授权、自动化 IPA 环境（多数 UI 步骤）、蓝牙/OTG（ble_* 步骤）。试跑失败时先查环境，再查参数。

一、环境与 App​

步骤 op名称说明主要参数
device_auth_ok设备授权检查检查 USB/投屏授权是否有效；流程开始前也会自动检查type：1=USB授权，2=投屏授权
ensure_auto_env启动自动化环境启动设备自动化服务并轮询就绪—
open_app打开应用按 Bundle ID 启动 AppbundleId；可选 resetUsb
home返回主页模拟 Home 键—

二、等待与日志​

步骤 op名称说明主要参数
wait等待固定毫秒延迟duration（毫秒）
log打印日志输出到运行日志message 或 messageFromVar

三、界面与手势（需自动化环境）​

步骤 op名称说明主要参数
fetch_nodes节点抓取dump UI 树并解析为节点列表match.dumpXml 过滤；saveAs
vlm_locateVLM·视觉定位视觉大模型在截图中定位元素坐标intent 中文描述；saveAs；可选 imageFromParam
capture_screen_no_auto无自动化截图Bridge 直截全屏saveAs
capture_screen_auto自动化截图Agent 截全屏，需 ensure_auto_envsaveAs
click_point点击坐标点击x,y 或 fromParam
swipe_to_point滑动起点滑到终点startX,startY,endX,endY,duration
long_click_point长按指定坐标长按x,y,duration
double_click_point双击指定坐标双击x,y
multi_touch多点触控多指轨迹fingers 数组
input_text输入文字向焦点控件输入content

截图与 OCR 步骤​

步骤 op何时用
capture_screen_no_auto无自动化全屏截图
capture_screen_auto自动化全屏截图
ocr_screen_no_auto无自动化 OCR
ocr_screen_auto自动化 OCR

AI 对话里名称一致，直接说「无自动化截图」「自动化 OCR」等即可。

OCR 引擎类型（ocrType）​

ocrType说明
paddleOcrNcnnV5（默认）本地 NCNN，速度与精度均衡
v5 / paddleOcrOnnxV5ONNX v5
v4 / paddleOcrOnnxV4ONNX v4
ocrLiteOcrLite

同一台设备 不同 ocrType 会分别缓存；正式任务结束后引擎会释放，下次 OCR 可能重新初始化（首包略慢属正常）。编辑器 OCR 预览 默认保持引擎以便连续调试。

可选参数：padding、maxSideLen、region（识别区域）。

fetch_nodes 默认 dumpXml 过滤​

未配置 match.dumpXml 时使用：

  • visibleFilter=1, labelFilter=1, boundsFilter=1
  • maxDepth=50
  • excludedAttributes=visible,selected,enable,accessible
  • maxChildCount=200

VLM 语义定位 请用独立步骤 vlm_locate（菜单 视觉定位 (VLM)），不要在 fetch_nodes 里混用。

vlm_locate​

参数说明
intent中文描述目标，如「右上角设置按钮」
saveAs写入坐标等结果
imageFromParam可选，引用上一步截图；空则实时截屏

需先在 配置与数据目录 中配置 VLM 模型（vlm_config.json）。

四、连接恢复​

步骤 op名称说明主要参数
reset_usb_conn重置 USB软件层 usbmuxd 重置—
reconnect_usb闪断 USB等同拔插数据线，仅 Windows执行后建议 wait 5–10 秒

适用于无法开自动化、无法打开 App 等连接异常场景。

五、相册​

步骤 op名称说明主要参数
album_request_auth请求相册权限触发相册授权弹窗—
album_delete_photos清空图片删除相册全部图片（不可恢复）—
album_delete_videos清空视频删除相册全部视频—
album_insert_img_folder导入图片扫描本机文件夹图片写入设备相册folderPath（绝对路径）
album_insert_video_folder导入视频扫描本机文件夹视频写入设备相册folderPath
注意

相册清空操作 不可恢复，试跑前请确认设备与路径。

六、IME 输入法​

各 IME 步骤执行前会自动检查输入法可用（等效 ime_ok）。

步骤 op名称说明
ime_ok检查可用检查 IME 是否就绪（兼容旧流程；新流程可省略）
ime_input输入文字通过 IME 输入
ime_paste粘贴content 为空则用剪贴板
ime_press_del删除键模拟退格
ime_press_enter回车模拟回车
ime_copy_to_clipboard复制到剪贴板复制输入框内容
ime_get_text读取输入框读取当前框文字
ime_get_clipboard读剪贴板读取设备剪贴板
ime_set_clipboard设剪贴板设置剪贴板内容
ime_open_url打开链接通过 IME 打开 URL
ime_remove_all_content清空输入框清空全部内容
ime_change_keyboard切换键盘切换输入法键盘
ime_dismiss隐藏键盘收起键盘

七、BLE 蓝牙外设​

适用于 BLE 键盘、鼠标等外接输入设备。使用前请完成 蓝牙 BLE 教程 与（如需要）OTG 教程 中的绑定与测试。

步骤 op名称说明
ble_clickBLE 点击坐标点击
ble_double_clickBLE 双击坐标双击
ble_swipeBLE 滑动start/end 坐标 + duration
ble_touch_down / ble_touch_up / ble_touch_move按下/抬起/移动配合实现拖拽
ble_pressBLE 长按x, y, delay
ble_key_pressBLE 按键prefix + code
ble_key_press_charBLE 字符字符输入
ble_system_key系统键Home、音量等
ble_toggle_keyboard切换软键盘显隐软键盘
ble_resetBLE 重置重置外设
ble_set_wifiBLE 配网SSID + 密码

八、OCR 与数据提取​

步骤 op名称说明主要参数
ocr_screen_no_auto无自动化 OCRBridge 截屏并识别ocrType；saveAs；可选 region
ocr_screen_auto自动化 OCRAgent 截屏并识别，需 ensure_auto_env同左
pick_node节点数据提取从节点变量提取字段、区域、坐标条件、saveAs
pick_ocrOCR 数据提取从 OCR 结果选行、字段、中心点匹配规则、saveAs
pick_match找图数据提取从模板/偏色找图结果取中心点或最佳匹配fromParam；pick.mode；saveAs

pick_* 步骤支持 快捷模板（编辑器步骤卡片上的按钮）和 上次试跑预览。

九、图色识别​

详细用法见 图色找图。

步骤 op名称说明
match_template_no_auto无自动化找图Bridge 截屏 + OpenCV 模板匹配
match_template_auto自动化找图Agent 截屏 + 模板匹配
find_image_by_color_no_auto无自动化偏色找图Bridge + findImageByColorEx
find_image_by_color_auto自动化偏色找图Agent + findImageByColorEx

主要参数：templatePath（相对工作目录，如 assets/templates/xxx.png）、imageFromParam、region、threshold / weakThreshold、saveAs。

典型链路：match_template_* → pick_match（mode=center）→ click_point。

十、本机文件​

文件步骤操作 中控主机 文件系统（非设备内文件）。

步骤 op名称说明主要参数
save_file保存文件变量内容写入文件baseDir：runtime_data / external；fromParam；filename；format
read_file读取文件读 JSON/文本baseDir：readdata / external；filename；saveAs
delete_file删除文件删文件或递归删目录baseDir + 相对路径，或 external 绝对路径
list_dir列出目录返回路径数组folderPath；recursive
file_exists路径是否存在写入 {exists, path, isDir?}path 绝对路径
默认不必设置工作目录

未在 流程配置 里设置工作目录时，保存/删除走 Agent 默认目录 runtime_data/{deviceId}/，读取走 runtime_data/readdata/（共享，不按设备分子目录）。设置了 工作目录 后，保存/删除为 {workDir}/{deviceId}/，读取为 {workDir}/。

目录说明（baseDir）：

baseDir 值路径
runtime_data{dataDir}/runtime_data/{deviceId}/（保存、删除默认）
readdata{dataDir}/runtime_data/readdata/（读取默认，共享）
external用户指定的本机绝对路径
audit{dataDir}/audit/{taskId}/{deviceId}/{workflowId}/

旧版 datatmp 与 {dataDir}/datatmp/ 仍兼容；新工作流请使用 runtime_data。保存路径 不含 taskId。

十一、外部集成​

步骤 op名称说明主要参数
call_httpHTTP 请求调用注册表端点或指定 URLendpoint/url；method；body；saveAs
run_cliCLI 执行执行注册表命令cliId；args；saveAs
call_mcpMCP 执行调用注册表 MCP Toolserver；tool；arguments；saveAs

旧版 pick_cli / pick_mcp 打开时会 自动迁移 为新步骤格式。

详见 外部集成。

十二、流程控制​

步骤 op名称说明
branch条件分支if/else 两组嵌套步骤
switch多路分支按顺序匹配 case，否则 default
pause_human人工暂停任务暂停，等待人工在任务面板 继续
invoke_workflow调用子流程同步执行另一工作流，可传参、写回变量

invoke_workflow（子流程）​

参数说明
workflowId子流程 ID
params / 传入参数传给子流程的键值
exportParams / 写回变量子流程里哪些变量带回父流程
saveAs可选，记录调用成功标记 { workflowId, status }
returnMode结果标记内容：仅状态 / 含写回变量 / 子流程 params 快照

子流程 失败 或 人工暂停 时，默认 不会 写回内部变量（除非配置了失败时也写入）。

branch / switch 条件​

  • 支持 when 表达式（模板展开后求值）
  • 可结合 dumpXml 节点存在性判断（编辑器内配置 pick 条件）

十三、步骤插入菜单分类​

编辑器「添加步骤」按类别分组：

常用 · 代理事件 · OCR识别 · 视觉定位 (VLM) · 图色识别 · 相册 · 输入法输入 · BLE 蓝牙 · 链接管理 · 数据处理 · 文件 · HTTP/CLI/MCP · 子工作流 (FSM)

变量与模板​

  • 流程配置：全局默认值（界面合并了原 globals / fsm.context 等概念，分 工作流默认 与 本流程启动 两种范围）
  • 任务参数通过试跑 Params 或 invoke 传入参数 覆盖启动值
  • 字符串字段支持 {{var}}、{{stepVar.field}} 模板语法
  • 变量池（编辑器工具栏）：查看配置项、步骤结果；试跑后切 运行 视图看实际值；点击可高亮画布引用

校验规则（保存/试跑前）​

编辑器 校验 会检查例如：

  • 工作流 ID、FSM initial/final 可达性
  • 相册步骤是否填写 folderPath
  • 找图步骤是否提供模板路径或 Base64
  • 文件步骤 external 模式是否指定目录
  • invoke 是否形成循环依赖
  • 全局变量名冲突、保留字

失败时在界面展示第一条错误信息。