API 手册（D11版）

适用版本：v3.3.5.5 及以上。

兼容说明：本版本对api做了大量优化, 如果部分原API命令出现异常，可以在API命令前添加“old-"向后兼容。

← 返回主页

连接方式

WebSocket

地址: ws://127.0.0.1:50001/

参数: JSON 格式

HTTP POST

地址: http://127.0.0.1:65001/

参数: JSON 格式

HTTP GET

地址: http://127.0.0.1:65001/?type=post

参数: URL 拼接，如打开设置 http://127.0.0.1:65001/?type=post&id=id123&num=2,3&cmd=StartAppName 设置

请求与响应格式

请求 (JSON)

{
  "id": "id123",
  "num": "3,7-12,15",
  "group": "组1,组2",
  "cmd": "click 50,250"
}

num 和 group 二选一，都不填或 num="" 表示全局命令。

响应 (JSON)

{
  "id": "id123",
  "msg": "success",
  "data": "300,500"
}

注意：msg="success" 只表示命令已发送执行；投屏操作的实际结果需要另外检测判断。

通用术语

设备或手机

指被操作的手机。

api发送端

指向api发送post请求的脚本、程序或软件。

批量脚本

指在手机内部批量执行的脚本，执行过程手机可与电脑断开连接，不需要由api发送端进行交互控制。

设备管理

消息提示

本组为消息弹窗提示功能，分为短时弹窗、长时弹窗、全局弹窗三类。

短时弹窗

命令: Toast <内容>

功能描述：设备上显示消息，2秒自动消失,最长 40 字符（超出截断）。

选用建议：常规简短提示优先使用本命令

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：设备2上显示"hello"，2秒后自动消失
{ "id": "id1", "num": "2", "cmd": "Toast hello" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

长时弹窗

命令: HoldToast <时长>,<内容>

功能描述：设备窗口上显示消息，指定显示时间后消失，或鼠标触碰后消失

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：设备2的窗口上显示"hello"，15000毫秒(15秒)后消失
{ "id": "id1", "num": "2", "cmd": "HoldToast 15000,hello" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

全局弹窗

命令: GlobalToast <内容>,<类型>

功能描述：软件右上角显示全局消息

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：软件右上角显示全局普通消息"操作完成"，3秒后会自动消失
{ "id": "id1", "num": "", "cmd": "GlobalToast 操作完成,i" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

设备选取

选中设备

命令: SelectDevice

功能描述：使设备成为选中状态

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：设置2号和3号设备成为选中状态
{ "id": "id1", "num": "2,3", "cmd": "SelectDevice" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

清除设备选取状态

命令: ClearSelectDevice

功能描述：清除所有设备的选取状态

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "ClearSelectDevice" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

显示控制

刷新画面

命令: RefreshImg

功能描述：刷新指定设备画面

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：刷新2号和3号设备的显示画面
{ "id": "id1", "num": "2,3", "cmd": "RefreshImg" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

重新加载设备

命令: LoadDevice

功能描述：重新加载指定设备

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：重新加载2号和3号设备
{ "id": "id1", "num": "2,3", "cmd": "LoadDevice" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换大图

命令: SwitchBigImg

功能描述：把指定设备切换成大图显示模式

操作目标：单个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：把2号设备显示成大图模式
{ "id": "id1", "num": "2", "cmd": "SwitchBigImg" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换下一个大图

命令: NextBigImg

功能描述：把排在当前大图之后的设备切换到大图显示模式

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "NextBigImg" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换上一个大图

命令: BackBigImg

功能描述：把排在当前大图之前的设备切换到大图显示模式

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "BackBigImg" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

分组管理

导入分组

命令: ImportGroup <分组参数>

功能描述：批量导入分组设备信息，执行后清空全部原有分组，仅保留本次传入的分组数据

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：导入“分组1”和“测试组”，分组1里2个设备，测试组里3个设备
{ "id": "id1", "num": "2,3", "cmd": "ImportGroup 分组1,192.168.1.2:5555,192.168.1.3:5555;测试组,192.168.1.4:5555,oidsfsdfowkdksf,192.168.1.6:5555" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换分组

命令: SwitchGroup <组名>

功能描述：仅显示指定分组内的设备画面

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：显示分组1内的设备画面
{ "id": "id1", "num": "", "cmd": "SwitchGroup 分组1" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换下一个分组

命令: NextGroup

功能描述：把排在当前显示分组之后的组切换成显示状态

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "NextGroup" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换上一个分组

命令: BackGroup

功能描述：把排在当前显示分组之前的组切换成显示状态

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "BackGroup" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

设备信息查询

获取在线设备信息

命令: OnlineDevice <筛选类型>,<返回字符>

功能描述：查询当前投屏设备基础信息，包含设备编号、标题、DevicesId、设备屏幕分辨率

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，无具体字段名，需按位置（索引）解析。其中多设备结果以;分隔，单设备结果以/分隔。

// 请求示例：取所有设备的所有信息
{ "id": "id1", "num": "", "cmd": "OnlineDevice all,all" }

// 响应示例: 操作执行成功，多设备用;分隔，单设备字段用/分隔
{ "id": "id1", "msg": "success", "data": "1/标题一/eo7dw6aedss/1920*1080;2/标题二/192.168.7.5:5555/1920*1080" }

获取分组设备信息

命令: GroupDevice <筛选类型>,<返回字段>

功能描述：查询当前连接设备基础信息，包含设备编号、标题、DevicesId、设备屏幕分辨率

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，无具体字段名，需按位置（索引）解析。其中多设备结果以;分隔，单设备结果以/分隔。

// 请求示例：取所有设备的所有信息
{ "id": "id1", "num": "", "cmd": "OnlineDevice all,all" }

// 响应示例: 操作执行成功，多设备用;分隔，单设备字段用/分隔
{ "id": "id1", "msg": "success", "data": "1/标题一/eo7dw6aedss/1080*1920;2/标题二/192.168.7.5:5555/1080*1920" }

获取当前大图设备号

命令: BigImgDevice

功能描述：获取当前大图显示的设备号

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data内容为对应设备的唯一编号

// 请求示例
{ "id": "id1", "num": "", "cmd": "BigImgDevice" }

// 响应示例: 操作执行成功，当前9号是大图显示模式
{ "id": "id1", "msg": "success", "data": "9" }

IP 连接管理

刷新IP连接

命令: RefreshIpConnection

功能描述：IP投屏模式下，根据【使用向导】配置的IP地址列表，刷新设备连接状态

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "RefreshIpConnection" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

关闭IP连接

命令: CloseIpConnection

功能描述：关闭已连接的ip

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "CloseIpConnection" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

切换连接模式

命令: SetConnectWizard <连接模式>

功能描述：切换使用向导里的连接模式

注意事项：使用向导里的第4项USB转WIFI和第5项USB转OTG，最终投屏方式属于连接模式2，只是增加了界面转换引导功能

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例
{ "id": "id1", "num": "", "cmd": "CloseIpConnection" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

修改IP列表

命令: EditIpList <修改方式>,<后处理方式>,<IP地址集合>

功能描述：维护投屏连接用的IP地址列表，支持追加或全量替换

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例：清除原有的ip列表，新增三条投屏IP地址
{ "id": "id1", "num": "", "cmd": "EditIpList clear,192.168.1.1:5555,192.168.1.2:5555,192.168.1.3:5001" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

输入法切换

命令: SetInputMethod <输入法>

可选：搜狗、讯飞、专用、adb，或完整包名/服务类名。

// 请求示例：设备2切换为讯飞输入法
{ "id": "id1", "num": "2", "cmd": "SetInputMethod 讯飞" }

// 响应示例: 操作执行成功
{ "code": 0, "msg": "success", "data": "" }

切换输入法

命令: SetInputMethod <输入法>

功能描述：切换指定手机上的输入法

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号切换上切换成讯飞输入法方法1
{ "id": "id1", "num": "2", "cmd": "SetInputMethod 讯飞" }

// 请求示例：2号切换上切换成讯飞输入法方法2
{ "id": "id1", "num": "2", "cmd": "SetInputMethod com.iflytek.inputmethod/.FlyIME" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

客服消息与剪贴板

获取客服消息

命令: AppMessages <时间戳>

功能描述：获取客服消息系统内的信息

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data内容为JSON数组格式的字符串。

返回参数 (data内容解析)

解析规则：data内容为JSON数组格式的字符串，需先进行JSON反序列化（JSON Parse），解析后为对象数组。

// 请求示例：获取客服系统所有时间段的信息
{ "id": "id1", "num": "", "cmd": "AppMessages 0" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "[{\"number\":\"1\",\"time\":\"375550\",\"appName\":\"微信\",\"title\":\"来自小郑\",\"content\":\"你好\"},{\"number\":\"3\",\"time\":\"377950\",\"appName\":\"微信\",\"title\":\"来自苏\",\"content\":\"你好\"}]" }

删除客服消息

命令: DelAppMessages <时间戳>

功能描述：删除客服消息系统的信息

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data为删除记录的总数量。

// 请求示例：删除时间戳100456700及之前的所有信息，即<=100456700
{ "id": "id1", "num": "", "cmd": "DelAppMessages 100456700" }

// 响应示例: 操作执行成功，删除了7条信息
{ "id": "id1", "msg": "success", "data": "7" }

获取剪贴板记录

命令: GetClipHistory <获取方式>

功能描述：读取手机剪贴板同步至电脑端的剪贴历史记录

操作目标：单个或多个设备。

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，data内容为JSON数组格式的字符串。

返回参数 (data内容解析)

解析规则：data内容为JSON数组格式的字符串，需先进行JSON反序列化（JSON Parse），解析后为对象数组。

// 请求示例：返回所有记录
{ "id": "id1", "num": "", "cmd": "GetClipHistory all" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "[{\"number\":9,\"content\":\"内容1\",\"time\":\"2026-06-22 19:00:57.425\"},{\"number\":9,\"content\":\"内容2\",\"time\":\"2026-06-22 19:00:55.174\"}]" }

删除剪贴板记录

命令: ClearClipHistory <删除方式>

功能描述：删除手机剪贴板同步至电脑端的剪贴历史记录

操作目标：单个或多个设备。

返回说明：返回执行状态，data内容为删除记录的总数量。

// 请求示例：删除所有记录
{ "id": "id1", "num": "", "cmd": "ClearClipHistory all" }

// 响应示例: 操作执行成功，删除了3条信息
{ "id": "id1", "msg": "success", "data": "3" }

同步剪贴板

命令: SyncClip <同步方式>

功能描述：把设备剪切板最后一条内容同步到电脑端

操作目标：单个或多个设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例：同步所有设备
{ "id": "id1", "num": "", "cmd": "SyncClip all" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

设备操作命令

启动App

按包名启动APP

命令: StartApp <包名>/Activity>

功能描述：通过包名和 Activity 类名精确启动指定App（软件【应用管理】里可以查看包名和Activity类名）。

选用建议：知晓包名和Activity的优先使用本命令

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

//请求示例：启动2号和3号设备里的设置
{"id":"id1","num":"2,3","cmd":"StartApp com.android.settings/com.android.settings.homepage.SettingsHomepageActivity"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

按名称启动App

命令: {StartAppName <应用名> [,index=N] [,exact=true]}

功能描述：通过App名称启动App。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：启动2号设备的设置
{"id":"id1","num":"2","cmd":"StartAppName 设置"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

关闭App

按包名关闭App

命令: StopApp <包名>

功能描述：通过包名强制停止App（软件【应用管理】里可以查看包名）。

选用建议：知晓包名的优先使用本命令

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：关闭2号和3号设备的设置
{"id":"id1","num":"2,3","cmd":"StopApp com.android.settings"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

按名称关闭App

命令: {StopAppName <应用名> [,index=N] [,exact=true]}

功能描述：参数同 StartAppName。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：关闭2号设备的设置
{"id":"id1","num":"2","cmd":"StopAppName 设置"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

一键清除后台应用

命令: {StopAllApps [method=B|C|BC] [,mode=kill|notkill] [,pkgs=pkg1,pkg2,...]}

功能描述：一键清除后台应用，支持多种清除和过滤模式。简写：StopAllApps b（等价 ,method=B）、StopAllApps c、StopAllApps bc。

典型用法：

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：一键清除3号设备的后台
{"id":"id1","num":"3","cmd":"StopAllApps bc"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

单击

命令: click <x>,<y> [,jitter=<px>][,wait=<ms>]

功能描述：一个坐标位置单击

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号和3号设备点击坐标50,250
{"id":"id1","num":"2,3","cmd":"click 50,250"}

// 请求示例：2号设备1000毫秒后点击坐标300±3,500±3
{"id":"id1","num":"2,3","cmd":"click 300,500,jitter=3,wait=1000"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"点击:300,500"（如 click 300,500,jitter=3,wait=1000,toast=1）。

双击

命令: doubleClick <x>,<y> [,interval=ms][,jitter=<px>][,wait=<ms>]

功能描述：在一个坐标位置双击

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号和3号设备在坐标50,250上双击
{"id":"id1","num":"2,3","cmd":"doubleClick 50,250"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"点击:300,500"（如 click 300,500,jitter=3,wait=1000,toast=1）。

长按

命令: longtap <x>,<y>,<ms> [,jitter=<px>][,wait=<ms>]

功能描述：在一个坐标上长按

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：在坐标200,300位置长按1000毫秒
{"id":"id1","num":"2,3","cmd":"longtap 200,300,1000"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"长按:(200,300)"（如 longtap 200,300,1000,toast=1）。

多点同按

命令: multiClick <x1>,<y1>,<x2>,<y2>[,...][,holdMs] [,wait=<ms>] [,jitter=<px>]

功能描述：同时点击多个坐标

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：同时点击坐标100,200和300,400，用时200毫秒
{"id":"id1","num":"2,3","cmd":"multiClick 100,200,300,400,200"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"多点同按"（如 multiClick 100,200,300,400,200,toast=1）。

滑动

命令: swipe <x1>,<y1>,<x2>,<y2>,<dur> [,jitter=<px>][,wait=<ms>]

功能描述：贝塞尔曲线滑动，相同坐标为长按。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：等待2000毫秒后，从坐标50,250滑动到500,250，用时600毫秒
{"id":"id1","num":"3","cmd":"swipe 50,250,500,250,600,wait=2000"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"滑动:(50,250)→(500,250)"（如 swipe 50,250,500,250,600,wait=2000,toast=1）。

拖动

命令: drag <x1>,<y1>,<x2>,<y2>,<dur> [,jitter=<px>][,wait=<ms>]

功能描述：快速拖动，相同坐标或无法拖动时为长按

直线拖动，相同坐标为长按。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：等待2000毫秒后，从坐标50,250拖动到500,250，用时600毫秒
{"id":"id1","num":"3","cmd":"drag 50,250,500,250,600,wait=2000"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"拖动:(50,250)→(500,250)"（如 drag 50,250,500,250,600,wait=2000,toast=1）。

滚动

命令: scroll <x>,<y>,<方向>,<轴向>,<次数> [,jitter=<px>][,wait=<ms>]

功能描述：滚动页面，需要页面支持滚动功用

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：在坐标50,250位置垂直向前滚动10次
{"id":"id1","num":"3","cmd":"scroll 50,250,1,v,10"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"滚动:(50,250)"（如 scroll 50,250,1,v,10,toast=1）。

方向滑动

向上滑动

命令: swipeUp <dur> [,jitter=<px>] [,wait=<ms>]

功能描述：向上贝塞尔曲线滑动。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：向上滑动，用时300毫秒
{"id":"id1","num":"2","cmd":"swipeUp 300"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

向下滑动

命令: swipeDown <dur>[,jitter=<px>] [,wait=<ms>]

功能描述：向下贝塞尔曲线滑动。。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：向下滑动，用时300毫秒
{"id":"id1","num":"2","cmd":"swipeDown 300"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

向左滑动

命令: swipeLeft <dur> [,jitter=<px>][,wait=<ms>]

功能描述：向左贝塞尔曲线滑动。。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：向左滑动，用时300毫秒
{"id":"id1","num":"2","cmd":"swipeDown 300"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

向右滑动

命令: swipeRight <dur>[,jitter=<px>] [,wait=<ms>]

功能描述：向右贝塞尔曲线滑动。。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：向右滑动，用时300毫秒
{"id":"id1","num":"2","cmd":"swipeDown 300"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"向上滑动"等（如 swipeUp 300,toast=1）。

输入文本

命令: InputText <文本内容>[,<输入方式>]

功能描述：在焦点位置输入文字内容，\r表示换行。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：在2号设备焦点输入框内输入"hello world"
{"id":"id1","num":"2","cmd":"InputText hello world"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

按键

命令: Key <键码>

功能描述：使用安卓键码进行按键操作

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：返回主页（HOME、3、KEYCODE_HOME三种都可以）
{"id":"id1","num":"2","cmd":"Key HOME"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"按键:HOME"（如 Key HOME,toast=1）。

截屏

原图截屏

截图保存为文件

命令: ImgScreenCapture <路径>,<文件名编号>

功能描述：截取设备屏幕的高清原图并保存到PNG文件

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号和3号设备分别保存截图到 d:\cls\a2.png和a3.png
{"id":"id1","num":"2,3","cmd":"ImgScreenCapture d:\\cls\\a,true"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

截图返回Base64

命令: ImgCaptureScreenBase64 <左>,<上>,<右>,<下>,<格式>

功能描述：截取设备屏幕高清原图的指定区域，并转换成Gzip压缩的Base64编码

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为特殊编码字符串。

返回参数 (data内容解析)

解析规则：data内容是经过Gzip压缩后的图片Base64字符串，且不含“data:image/...;base64,” 前缀。需严格按以下顺序处理：

1.先对字符串进行Gzip解压（Decompress）还原为Base64编码字符串。

2.再对Base64字符串进行解码（Decode），还原为原始图片数据。

// 请求示例：2号设备全屏截图，截图格式为jpg
{"id":"id1","num":"2","cmd":"ImgCaptureScreenBase64 0,0,0,0,jpg"}

// 响应示例: 返回Gzip压缩后由请求时指定的jpg格式的Base64图片数据
{"id":"id1","msg":"success","data":"H4sIAAAAAAAA/..."}

快速截屏

快速截图保存为文件

命令: FastImgScreenCapture <路径>,<文件名编号>

功能描述：截取设备在电脑屏幕显示的画面保存到PNG文件。

选用建议：截图保存为文件时优先使用本命令

注意事项：

1.快速截图需要在软件设置中将【系统设置 → 硬件加速 → 画面加速模式】设为【加速模式2】。

2.画面清晰度与小图画面分辨率有关，取决于【系统设置 → 基础设置 → 小图最大分辨率】，推荐分辨率960，不低于480。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号和3号设备分别保存截图到 d:\cls\a2.png和a3.png
{"id":"id1","num":"2,3","cmd":"FastImgScreenCapture d:\\cls\\a,true"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

快速截图返回Base64

命令: FastImgCaptureScreenBase64 <左>,<上>,<右>,<下>,<格式>

功能描述：截取设备在电脑屏幕显示画面的指定区域，并转换成Gzip压缩的Base64编码。

选用建议：截图返回Base64时优先使用本命令。

注意事项：

1.快速截图需要在软件设置中将【系统设置 → 硬件加速 → 画面加速模式】设为【加速模式2】。

2.画质取决于【系统设置 → 基础设置 → 小图最大分辨率】，推荐分辨率960，不低于480。

3.全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为特殊编码字符串。

返回参数 (data内容解析)

解析规则：data内容是经过Gzip压缩后的图片Base64字符串，且不含“data:image/...;base64,” 前缀。需严格按以下顺序处理：

1.先对字符串进行Gzip解压（Decompress）还原为Base64编码字符串。

2.再对Base64字符串进行解码（Decode），还原为原始图片数据。

// 请求示例：2号设备全屏截图，截图格式为jpg
{"id":"id1","num":"2","cmd":"FastImgCaptureScreenBase64 0,0,0,0,jpg"}

// 响应示例: 返回Gzip压缩后由请求时指定的jpg格式的Base64图片数据
{"id":"id1","msg":"success","data":"H4sIAAAAAAAA/..."}

OCR 文字识别

快速OCR【推荐使用】

启动OCR

命令: OpenOcr

命令: OpenOcr

功能描述：初始化Ocr设置，是调用OcrText、OcrFind、OcrClick接口前的必备前置操作。新设备首次初始化需要较长时间。

注意事项：新设备首次执行初始化时，耗时可能较长，请耐心等待后重试。当返回值为ok时，表示初始化成功。

操作目标：单个或多个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，无具体字段名，需按位置（索引）解析。其中多设备结果以;分隔，单设备结果以,分隔。

// 请求示例
{"id":"id1","num":"all","cmd":"OpenOcr"}

// 响应示例: 操作执行成功，返回初始化ok,可继续执行相关ocr操作
{"id":"id1","msg":"success","data":"9,ok;10,ok;13,ok"}

关闭OCR

命令: CloseOcr

功能描述：关闭并释放 OCR 资源。该命令为可选操作，可根据实际需求决定是否手动释放资源。

操作目标：单个或多个设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例
{"id":"id1","num":"all","cmd":"CloseOcr"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

获取OCR文本

命令: OcrText <左>,<上>,<右>,<下>,<相似度>,<返回全部字段> [,er=<放大比>] [,mg=<合并间距>] [,conn=<连通域>] [,ek=<XOR密钥>] [,dt=<检测阈值>]

功能描述：对设备屏幕指定区域进行OCR文字识别，返回识别到的文本及位置信息。

选用建议：获取ocr文本时优先使用此命令

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。执行此命令前，必须先调用【启动OCR】命令进行初始化。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。其中多设备结果以双分号;;分隔，单设备结果以字段名分隔。

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"提取ocr:..."（如 0,0,0,0,50,true,toast=1）。

// 请求示例：全屏OCR提取文本，并且只返回相似度50%以上的文本内容
{"id":"id1","num":"2","cmd":"OcrText 0,0,0,0,50,true"}

// 响应示例: 返回识别结果
{"id":"id1","msg":"success","data":"text:系统工具,score:99,point:
<!-- AI_NOTE: apiCmd=OcrText; 参数左,上,右,下,相似度,返回全部字段六个必填; 全屏四坐标全填0; 可选er/mg/conn/ek/dt; 需先OpenOcr; 仅限单个设备; data字段text/score/point/center; 支持toast=1  -->86,272,235,272,235,310,86,310,center:160,291;;text:设置,score:100,point:118,1842,207,1842,207,1904,118,1904,center:162,1873;;text:文件,score:100,point:625,1852,701,1852,701,1895,625,1895,center:663,1873"}

OCR查找文本

命令: OcrFind <关键词>,,<左>,,<上>,,<右>,,<下>,,<相似度>,,<点击>,,<匹配方式>,,<返回全部字段> [,er=<放大比>] [,mg=<合并间距>] [,conn=<连通域>] [,v=<日志>] [,ek=<XOR密钥>] [,dt=<检测阈值>]

功能描述：对设备屏幕指定区域进行OCR识别后，进行关键词匹配，可自动点击匹配位置。

选用建议：获取ocr查找文本时优先使用此命令

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。执行此命令前，必须先调用【启动OCR】命令进行初始化。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。其中多设备结果以双分号;;分隔，单设备结果以字段名分隔。

💡 支持 ,toast=1：参数末尾追加可在设备屏幕显示"找ocr:..."。

// 请求示例：全屏查找"系统工具"，如果相似度50%并且内容相等，就点击
{"id":"id1","num":"2","cmd":"OcrFind 工具,,0,,0,,0,,0,,50,,1,,2,,true"}

// 响应示例(找到): 返回匹配结果
{"id":"id1","msg":"success","data":"text:系统工具,score:99,point:
<!-- AI_NOTE: apiCmd=OcrFind; 参数关键词和左,上,右,下,相似度,点击,匹配方式,返回全部字段八个必填; 全屏四坐标全填0; 点击1=自动点击匹配位置; 匹配方式1=等于2=包含6=开头7=结尾8=中间; 需先OpenOcr; 仅限单个设备; 支持toast=1  -->86,272,235,272,235,310,86,310,center:160,291;;text:拓展工具,score:99,point:586,271,740,271,740,314,586,314,center:663,292"}

OCR点击

命令: OcrClick <关键词>,,<左>,,<上>,,<右>,,<下>,,<相似度>,,<匹配方式> [,range=<范围>][,jitter=<像素>] [,wait=<毫秒>]

功能描述：在脚本中通过OCR识别查找文本并自动点击匹配位置，支持范围选择和随机抖动。对应 Controller.java case 71（ScriptExecutor）。

选用建议：获取ocr点击时优先使用此命令

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。执行此命令前，必须先调用【启动OCR】命令进行初始化。

操作目标：仅单个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：查找包含"工具"的图标并点击第2个匹配项
{ "id": "id1", "num": "2", "cmd": "OcrClick 工具,,0,,0,,0,,0,,50,,2 range=2,jitter=3,wait=150" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

标准OCR【兼容使用】

原图获取OCR文本

命令: OcrGetText <左>,<上>,<右>,<下>,<相似度>,<返回全部字段>[,<拼接格式>],

功能描述：对设备屏幕的高清原图指定区域进行OCR文字识别，返回识别到的文本及位置信息。

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。当请求参数里指定使用ocrtext相同格式返回数据时，按ocrtext相同的解析规则进行解析。如果没有指定ocrtext, 就按以下规则进行解析，多设备结果以换行符\n分隔，单设备结果以字段名分隔。

// 请求示例：全屏OCR提取文本，并且只返回相似度50%以上的文本内容
{"id":"id1","num":"2","cmd":"OcrGetText 0,0,0,0,50,true"}

// 响应示例: 返回识别结果
{"id":"id1","msg":"success","data":"text:系统工具,,score:100,,bounds:[79,270],[237,267],[238,313],[80,316],,center:158,291\ntext:拓展工具,,score:100,,bounds:[582,266],[747,266],[747,317],[582,317],,center:664,291"}

原图OCR查找文本

命令: OcrFindText <关键词>,,<左>,,<上>,,<右>,,<下>,,<相似度>,,<点击>,,<匹配方式>,,<返回全部字段> [,er=<放大比>] [,mg=<合并间距>] [,conn=<连通域>] [,v=<日志>] [,ek=<XOR密钥>] [,dt=<检测阈值>]

功能描述：对设备屏幕的高清原图指定区域进行OCR文字查找匹配，返回匹配信息的同时，可以点击匹配位置

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。当请求参数里指定使用ocrtext相同格式返回数据时，按ocrtext相同的解析规则进行解析。如果没有指定ocrtext, 就按以下规则进行解析，多设备结果以换行符\n分隔，单设备结果以字段名分隔。

// 请求示例：全屏查找"系统工具"，如果相似度50%并且内容包含，就点击
{"id":"id1","num":"2","cmd":"OcrFindText 工具,,0,,0,,0,,0,,50,,true,,true,,true"}

// 响应示例(找到): 返回匹配结果
{"id":"id1","msg":"success","data":"text:系统工具,score:99,point:86,272,235,272,235,310,86,310,center:160,291;;text:拓展工具,score:99,point:586,271,740,271,740,314,586,314,center:663,292"}

快速图获取OCR文本

命令: FastOcrGetText <左>,<上>,<右>,<下>,<相似度>,<返回全部字段>[,<拼接格式>],

功能描述：对设备在电脑屏幕显示的画面指定区域进行OCR文字识别，返回识别到的文本及位置信息。

注意事项：

1.全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

2.快速截图需要在软件设置中将【系统设置 → 硬件加速 → 画面加速模式】设为【加速模式2】。

3.画面清晰度与小图画面分辨率有关，取决于【系统设置 → 基础设置 → 小图最大分辨率】，推荐分辨率960，不低于480。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。当请求参数里指定使用ocrtext相同格式返回数据时，按ocrtext相同的解析规则进行解析。如果没有指定ocrtext, 就按以下规则进行解析，多设备结果以换行符\n分隔，单设备结果以字段名分隔。

// 请求示例：全屏OCR提取文本，并且只返回相似度50%以上的文本内容
{"id":"id1","num":"2","cmd":"OcrGetText 0,0,0,0,50,true"}

// 响应示例: 返回识别结果
{"id":"id1","msg":"success","data":"text:系统工具,,score:100,,bounds:[79,270],[237,267],[238,313],[80,316],,center:158,291\ntext:拓展工具,,score:100,,bounds:[582,266],[747,266],[747,317],[582,317],,center:664,291"}

快速图OCR查找文本

命令: FastOcrFindText <关键词>,,<左>,,<上>,,<右>,,<下>,,<相似度>,,<点击>,,<匹配方式>,,<返回全部字段> [,er=<放大比>] [,mg=<合并间距>] [,conn=<连通域>] [,v=<日志>] [,ek=<XOR密钥>] [,dt=<检测阈值>]

功能描述：对设备在电脑屏幕显示的画面指定区域进行OCR文文字查找匹配，返回匹配信息的同时，可以点击匹配位置。

注意事项：

1.全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

2.快速截图需要在软件设置中将【系统设置 → 硬件加速 → 画面加速模式】设为【加速模式2】。

3.画面清晰度与小图画面分辨率有关，取决于【系统设置 → 基础设置 → 小图最大分辨率】，推荐分辨率960，不低于480。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有字段名。当请求参数里指定使用ocrtext相同格式返回数据时，按ocrtext相同的解析规则进行解析。如果没有指定ocrtext, 就按以下规则进行解析，多设备结果以换行符\n分隔，单设备结果以字段名分隔。

// 请求示例：全屏查找"系统工具"，如果相似度50%并且内容包含，就点击
{"id":"id1","num":"2","cmd":"OcrFindText 工具,,0,,0,,0,,0,,50,,true,,true,,true"}

// 响应示例(找到): 返回匹配结果
{"id":"id1","msg":"success","data":"text:系统工具,score:99,point:86,272,235,272,235,310,86,310,center:160,291;;text:拓展工具,score:99,point:586,271,740,271,740,314,586,314,center:663,292"}

UI 元素操作

UI布局

获取XML格式UI

命令: GetUiXml

功能描述：获取设备当前界面XML格式的UI布局

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为标准XML格式字符串。

解析规则：

1.data内容按标准XML格式字符串解析

2.字段命名规范：JSON 中的所有字段名均严格遵循 Android 标准 UI 节点属性命名规范（如 text、content-desc、resource-id 等），开发者可直接参考 Android 官方文档进行解析与映射。

//请求示例：获取3号设备上XML格式的UI布局
{"id":"id1","num":"3","cmd":"GetUiXml"}

// 响应示例：操作执行成功。
{"id":"id1","msg":"success","data":"<?xml version=
<!-- AI_NOTE: apiCmd=GetUiXml; 无参数; 获取设备当前界面XML格式UI布局; 仅限单个设备; data为标准XML字符串; 字段命名遵循Android标准UI节点属性; 推荐用GetUiJson(JSON格式)  -->\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><hierarchy rotation=\"0\"><node index=\"0\" text=\"\" resource-id=\"\" class=\"android.widget.FrameLayout\" package=\"com.android.mxLauncher3\" content-desc=\"\" checkable=\"false\" checked=\"false\" clickable=\"false\" enabled=\"true\" focusable=\"false\" focused=\"false\" scrollable=\"false\" long-clickable=\"false\" password=\"false\" selected=\"false\" bounds=\"[0,0][1080,1920]\">\n </node></hierarchy>"}

获取JSON格式UI

命令: GetUiJson [筛选条件]

功能描述：获取设备当前界面JSON格式的UI布局。

选用建议：需要获取UI布局时优先选用

注意事项：

1.当无筛选条件时（如 {"cmd":"GetUiJson"}），返回完整界面 JSON 节点数据。

2.当带筛选条件时，返回符合筛选条件的节点数据，支持条件组合与字段选择。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为JSON数组格式的字符串。

返回参数 (data内容解析)

解析规则：

1.data内容为JSON数组格式的字符串，需先进行JSON反序列化（JSON Parse），解析后为对象数组。

2.数组的首个对象（depth: -1）为屏幕全局信息，仅包含 screenWidth、screenHeight 和 rotation 字段，不包含具体的 UI 控件属性。从第二个对象（depth: 0）开始为实际的 UI 布局节点。

3.由于已过滤掉无内容的节点，数组中每个对象的字段数量是不固定的。使用前，请务必判断所需字段是否存在，避免出错。

4.字段命名规范：JSON 中的所有字段名均严格遵循 Android 标准 UI 节点属性命名规范（如 text、content-desc、resource-id 等），开发者可直接参考 Android 官方文档进行解析使用。

// 请求示例：获取3号设备完整的JSON格式UI布局
{"id":"id1","num":"3","cmd":"GetUiJson"}

// 请求示例：获取3号设备上UI布局里text属性包含“工具”的元素
{"id":"id1","num":"3","cmd":"GetUiJson text@~@工具"}

// 响应示例:操作执行成功，返回JSON格式的UI布局
{"id":"id1","msg":"success","data":"{\"depth\":-1,\"rotation\":0,\"screenWidth\":1080,\"screenHeight\":1920}\n{\"depth\":0,\"bounds\":\"0,0,1080,1920\",\"center\":\"540,960\",\"class\":\"android.widget.FrameLayout\",\"package\":\"com.android.mxLauncher3\",\"enabled\":true}\n{\"depth\":5,\"bounds\":\"0,1836,1080,1920\",\"center\":\"540,1878\",\"class\":\"android.widget.RelativeLayout\",\"package\":\"com.android.mxLauncher3\",\"resource-id\":\"com.android.mxLauncher3:id/apps_view\",\"enabled\":true}"}

UI筛选点击

命令: UiClick <筛选条件>

功能描述：根据筛选条件查找UI节点并自动点击匹配位置。

注意事项：

1.当无筛选条件时（如 {"cmd":"GetUiJson"}），返回完整界面 JSON 节点数据。

2.当带筛选条件时，返回符合筛选条件的节点数据，支持条件组合与字段选择。

操作目标：仅单个设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例：点击3号设备ui布局text属性等于"设置"且clickable属于等于true的元素节点，点击第1个，抖动5px，延时200ms
{"id":"id1","num":"3","cmd":"UiClick text@=@设置|clickable@=@true,,,range=1,jitter=5,wait=200"}

// 响应示例
{"id":"id1","msg":"success","data":""}

UI 筛选参数格式（用于 GetUiJson / filter）

格式结构：f部分,,s部分 ,, a部分

功能描述：做为多种命令通用的筛选参数。

注意事项：三个模块用,,分隔，均可省略。比如省略s部分：f部分,,,,a部分。

适用命令：适用于GetUiJson筛选模式和UiClick。

f 部分：筛选条件

筛选格式：属性名@匹配类型@值，多个条件用 | 分隔。

支持属性：depth、text、content-desc、class、package、resource-id、bounds、center、checkable、checked、clickable、enabled、focusable、focused、scrollable、long-clickable、password、selected

匹配类型定义：

s 部分：输出字段选择

字段格式：用缩写字母拼接。

注意事项：选择返回字段，如 tb=返回text+bounds，GetUiJson不填返回全部字段。

用缩写字母拼接，不填则输出全部字段。

a 部分：动作配置

筛选请求示例

// 筛选请求示例：查找text包含"设置"且clickable=true的节点，返回text和bounds字段
{"id":"id1","num":"3","cmd":"GetUiJson text@~@设置|clickable@=@true,,tb"}

// 筛选请求示例：3号机等待1到3秒(1000-3000毫秒)后，开始查找text包含"设置"且clickable=true的节点，如果找到就点击第1个匹配项的坐标
{"id":"id1","num":"3","cmd":"UiClick text@~@设置|clickable@=@true,,,,range=1,wait=1000-3000"}

// 筛选请求示例：3号机2000毫秒后，查找区域内的text属性包含“设置”的元素，点击第一个，抖动 ±5px
{"id":"id1","num":"3","cmd":"UiClick text@~@设置|bounds@in@100,200,500,800,,,, range=1,jitter=5,wait=2000"}

// 筛选请求示例：3号机查找resource属性值等于“com.example:id/login_btn”的元素，找到后返回匹配项的text、resource-id、center三个属性内容
{"id":"id1","num":"3","cmd":"GetUiJson resource-id@=@com.example:id/login_btn,,tre"}

保存UI布局到XML文件

命令: UiSaveXml <路径>,<文件名编号>

功能描述：保存设备当前界面的UI布局到XML文件

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：2号和3号设备分别保存截图到 d:\cls\a2.xml和a3.xml
{"id":"id1","num":"2,3","cmd":"UiSaveXml d:\\cls\\a,true"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

找色 / 找图

从屏幕查找颜色

命令: colorfind <颜色>,<左>,<上>,<右>,<下>,<相似度>

功能描述：在设备屏幕指定区域查找颜色，当匹配结果超过50个后停止匹配。

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有4种返回结果，具体含义如下：无具体字段名，需按位置（索引）解析。

data的3种返回类型：

匹配结果解析：

// 请求示例：全屏查找橙红色（#F34805），相似度100%，找到后点击
{ "id": "id1", "num": "2", "cmd": "colorfind #F34805,0,0,0,0,100" }

// 响应示例:操作执行成功，返回匹配到的结果
{ "id": "id1", "msg": "success", "data": "F34805,871,477;F34805,875,477;F34805,877,477;F34805,882,477;F34805,884,477" }

点击颜色

命令: ColorClick <颜色>,<左>,<上>,<右>,<下>,<相似度>,<点击位置>[,wait=<毫秒>]

功能描述：在设备屏幕指定区域查找颜色并点击。

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。数字/ "最短时间-最长时间"

返回说明：返回执行状态，，无额外返回内容。

// 请求示例：指定范围查找并点击橙红色（#F34805），相似度100%，找到后点击第1到3个，每次间隔1000毫秒
{ "id": "id1", "num": "2", "cmd": "ColorClick #F34805,810,330,1020,600,100,1-3,2000" }

// 响应示例:操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

从屏幕查找图片

命令: ImageFind <图片路径>,<左>,<上>,<右>,<下>,<相似度>

功能描述：在设备屏幕指定区域查找图片，当匹配结果超过50个后停止匹配。

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，data内容为自定义结构化字符串。

返回参数 (data内容解析)

解析规则：data为纯文本字符串，有4种返回结果，具体含义如下：无具体字段名，需按位置（索引）解析。

data的3种返回类型：

匹配结果解析：

// 请求示例：在3号机上全屏查找相似度90%的模板图片d:\cls\3_2606241900_x814_y336.png。
{ "id": "id1", "num": "3", "cmd": "ImageFind d:\\cls\\3_2606241900_x814_y336.png,0,0,0,0,50" }

//  响应示例:操作执行成功，返回匹配到的结果
{ "id": "id1", "msg": "success", "data": "100,200;150,250;200,300" }

点击图片

命令: ImageClick <颜色>,<左>,<上>,<右>,<下>,<相似度>,<点击位置>[,wait=<毫秒>]

功能描述：在设备屏幕指定区域查找颜色并点击。

注意事项：全屏提取时四个坐标全填0（即 0,0,0,0）），建议尽可能小范围区域内查找。

操作目标：仅单个设备。

返回说明：返回执行状态，，无额外返回内容。

// 请求示例：在3号机上全屏查找相似度90%的模板图片d:\cls\3_2606241900_x814_y336.png,找到后点击第1到3个，每次间隔1000毫秒
{ "id": "id1", "num": "2", "cmd": "imageclick d:\\cls\\3_2606241900_x814_y336.png,0,0,0,0,50,1-3,1000" }

// 响应示例:操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

ADB 命令

命令: adb <adb命令>[,||[<关键词>]]

功能描述：执行ADB命令

注意事项：

1.adb全局命令(不是adb shell命令)：不操作具体手机的命令，有返回值。

2.adb设备专用命令（adb shell命令）：操作具体手机的命令，默认无返回结果，加||返回结果。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，当有请求设置有返回值时，data内容为adb命令的执行结果。

// 请求示例：获取2号机内部存储里的所有文件和文件夹
{ "id": "id1", "num": "2", "cmd": "adb shell ls -R /sdcard ||" }

// 响应示例: 操作执行成功，data是返回的执行结果
{ "id": "id1", "msg": "success", "data": "/sdcard:\nAlarms\nAndroid\nAudiobooks\nDCIM\nDocuments\nDownload\nMovies\nMusic\nNotifications\nPictures\nPodcasts\nRecordings\nRingtones" }

脚本相关

执行已保存的脚本

命令: RunScript <脚本名称>

功能描述：执行软件【脚本管理器】中保存在本地列表里的脚本。支持类型：中控脚本、AutoJS、EasyClick。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：在2号和3号设备上执行名称为test1的脚本
{"id":"id1","num":"2,3","cmd":"RunScript test1"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

执行脚本文件

命令: RunScriptFile <文件路径>

功能描述：执行电脑上的脚本文件。支持类型：AutoJS、EasyClick。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：在2号和3号设备上执行电脑d盘里"脚本3.js"的脚本文件
{"id":"id1","num":"2,3","cmd":"RunScriptFile d:\\脚本3.js"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

设置超时

命令: ReceiveMessageTimeOut <超时时长>

功能描述：设置等待命令返回执行结果的超时时长，当超时时设置过短时而超时时，可能命令仍在正常执行。可以放在脚本的最前面。

注意事件：此命令只控制等待api内部执行返回结果的超时时长，需要控制post超时时长可以在api发送端里设置

操作目标：系统级命令（不操作设备），无需指定设备。

返回说明：返回执行状态，无额外返回内容。

// 请求示例：设置超时时长为10毫秒，超时后返回执行成功，但data里没有执行结果。
{"id":"id1","num":"all","cmd":"ReceiveMessageTimeOut 10000"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

查看脚本日志

命令: GetRunLog

功能描述：获取最近 20 条脚本执行日志，每条带有时间戳（格式：YYYY-MM-DD HH:MM:SS 命令内容）。

操作目标：操作目标：仅单个设备。

返回说明：返回执行状态，data 字段为自定义结构化字符串。

解析规则：多结果以\n分隔，单结果以空格分隔。需按位置（索引）解析，无具体字段名。

// 请求示例：获取脚本日志
{"id":"id1","num":"2","cmd":"GetRunLog"}

// 响应示例: 操作执行成功，返回日志文本
{"id":"id1","msg":"success","data":"2025-01-01 12:00:00 click 100,200
<!-- AI_NOTE: apiCmd=GetRunLog; 无参数; 获取最近20条脚本执行日志; 仅限单个设备; data多结果\n分隔; 每条格式日期时间命令内容; 用于脚本调试追踪  -->\n2025-01-01 12:00:01 swipe 100,200,300,400,500"}

停止脚本

命令: StopScript

功能描述：停止指定设备上正在执行的批量脚本。

注意事项：此命令只能停止属于批量脚本命令的执行，不能停止中控脚本、easyclick脚本和autojs脚本（这3种脚本可以通过【重新加载设备】命令快速停止）

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：停止设备2上的脚本
{"id":"id1","num":"2","cmd":"StopScript"}

// 响应示例: 操作执行成功
{"id":"id1","msg":"success","data":""}

文件传输

上传文件

命令: PushFile <电脑路径>,<手机路径>

功能描述：上传电脑文件到设备。

操作目标：单个或多个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：上传 d:\abc\a1.txt 到手机 /sdcard/Download/b1.txt
{ "id": "id1", "num": "2", "cmd": "PushFile d:\\abc\\a1.txt,/sdcard/Download/b1.txt" }

// 响应示例: 操作执行成功
{ "id": "id1", "msg": "success", "data": "" }

下载文件

命令: PullFile <手机路径>,<电脑目录>

功能描述：从设备下载文件到电脑

操作目标：仅单个设备。

返回说明：仅返回执行状态，无额外返回内容。

// 请求示例：下载手机 /sdcard/Download/b1.png 到电脑 d:\abc\
{ "id": "id1", "num": "2", "cmd": "PullFile /sdcard/Download/b1.png,d:\\abc\\" }

// 响应示例: 操作执行成功
{ "code": 0, "msg": "success", "data": "" }

批量指令脚本

是什么

1. 可以在一个请求中发送多条指令，发送后都在手机内执行，用 {} 花括号包裹每条命令，脚本会逐条顺序执行。

2. 执行过程手机可与电脑断开连接，不需要由api发送端进行交互控制。

3. 支持循环、延时、坐标随机抖动、toast提示等。

语法格式

{命令1 参数}{命令2 参数}...{for N {子命令1}{子命令2}}

执行规则

每条指令必须用 {} 包裹

1 条指令 → 同步执行（等待完成）

指令间按顺序执行

for 循环体内再用 {} 包裹子命令

公共参数

wait= / jitter= 适用：click、swipe、drag、scroll、longtap、multiClick、doubleClick、swipeUp/Down/Left/Right、ocrClick、uiClick、colorClick、imageClick、Shell、StartAppName、StopAppName、StopAllApps。不适用于 for、sleep、inputtext、Key、adb、toast、set、calc、arr、StopScript。

toast= 适用：除 for 外的所有命令，循环内自动带 for N/M: 前缀。

各命令完整参数具体命令描述。

可用于批量脚本命令速查表

click= 子参数（colorClick / imageClick）：0=不点击(默认)、1=第1个、N=第N个、N-M=第N到M个、-1=最后1个、-N=倒数第N个。

wait= 支持范围格式 500-1000（每次随机取[min,max]）。ocrClick/colorClick/scroll 中身兼二用 — 执行前延时 + 多点点击间隔，每次独立随机。

ocrClick 的 range= 参数：N=第N个、N-M=第N到M个、-1=最后一个(默认1)，与 click= 子参数语义等价。

toast= 适用于除 for 外的所有命令，循环内自动带 for N/M: 前缀。

批量脚本特有命令

以下仅说明批量脚本特有的命令，其余批量脚本可用命令详见各命令说明页。

延时

命令： {sleep <时长>}

功能描述：控制脚本在设备上延时多久后开始执行：{sleep 500-1500} 在500到1500ms之间随机。

注意事项：此处延时仅在手机设备内部的延时，api发送端的延时需要使用发送端语言的延时功能。

// 请求示例：先点击位置100,200，等待1500毫秒（1.5秒）后，再点击位置300,400
{ "id": "id1", "num": "2", "cmd": "{click 100,200}{sleep 1500}{click 300,400}" }

循环

命令： {for <次数>={命令1}{命令2}...}

功能描述：控制脚本在设备上循环执行。

推荐使用：简单不需要与api发送端交互的重复动作，可以使用此循环，比如重复间隔点击。

注意事项：如果需要主动结束循环，可以使用停止脚本【StopScript】命令。

// 请求示例：循环 N 次执行子命令块。支持嵌套。循环日志带前缀如 for 1/5
{ "id": "id1", "num": "3", "cmd": "{for 5={click 100,200,wait=300,jitter=3}{for 3 {click 200,300,wait=1000}}" }

条件

命令： {if <条件类型>=<条件值> {条件成立时执行的命令}}[{else {条件不成立时执行的命令}}]

功能描述：根据条件判断是否执行子命令块，支持 else 分支。

推荐使用：需要根据界面状态决定是否执行后续操作的场景，如判断某个元素是否存在再点击。

注意事项：条件判断失败（如截图失败、OCR未识别到）视为条件不成立，进入 else 分支。

// 请求示例：UI筛选条件+else分支
{ "id": "id1", "num": "3", "cmd": "{if uiClick=设置@~@ {click 100,200}}{else {{click 300,400}}}" }

// 请求示例：OCR条件判断
{ "id": "id1", "num": "3", "cmd": "{if ocrclick=确定 {click 500,600}}{else {{swipeUp 300}}}" }

// 请求示例：找色条件判断
{ "id": "id1", "num": "3", "cmd": "{if colorclick=#FF0000,left=0,top=0,right=1080,bottom=1920,similarity=95 {click 100,200}}" }

// 请求示例：模板匹配条件判断
{ "id": "id1", "num": "3", "cmd": "{if imageclick=/sdcard/btn.png,similarity=90 {click 540,960}}" }

变量

批量脚本支持在命令参数中使用 ${变量名} 引用变量，实现跨命令的数据传递和动态参数构造。

变量系统包含：用户自定义变量（set/calc）、数组（arr）、自动变量（${_x}/${_y}/${_item}/${_index}）、四则运算表达式。

##### 语法规则

所有命令参数在解析前都会先进行变量替换；变量名区分大小写。

##### set — 设置变量

命令： {set <变量名>=<值>}

功能描述：设置一个变量，后续命令可通过 ${变量名} 引用。

// 请求示例：设置变量 x=100，然后点击坐标 (${x},200)
{ "id": "id1", "num": "2", "cmd": "{set x=100}{click ${x},200}" }

##### calc — 计算赋值

命令： {calc <变量名>=<表达式>}

功能描述：对表达式执行四则运算后将结果赋给变量。

// 请求示例：x = 2+3*4 → 14，然后点击 (${x},200)
{ "id": "id1", "num": "2", "cmd": "{calc x=2+3*4}{click ${x},200}" }

表达式异常（除零、格式错误）返回 "0"。

##### arr — 定义数组

命令： {arr <数组名>=<元素1>,<元素2>,...}

功能描述：定义一组逗号分隔的字符串数组，供 for arr=/for rnd= 遍历使用。

// 请求示例：定义数组 names=["张三","李四"]，然后用 toast 分别显示
{ "id": "id1", "num": "2", "cmd": "{arr names=张三,李四}{for arr=names={toast ${_item}}}" }

// 请求示例：变量定义+使用。点击 (100,200) → 通过变量复用坐标 → toast 显示
{ "id": "id1", "num": "2", "cmd": "{set cx=100}{set cy=200}{click ${cx},${cy},wait=300}{toast 已点击(${cx},${cy})}" }

// 请求示例：calc 计算坐标偏移。点击 (100,200) → 计算偏移后点击 (200,300)
{ "id": "id1", "num": "2", "cmd": "{set x=100}{set y=200}{click ${x},${y},wait=300}{calc x2=${x}+100}{calc y2=${y}+100}{click ${x2},${y2}}" }

// 请求示例：：变量嵌套。ocrClick 找到 "设置" 后，用 ${_x} ${_y} 点击偏移位置
{ "id": "id1", "num": "2", "cmd": "{ocrClick 设置,,0,0,1080,1920,0.8}{click ${_x}+50,${_y},wait=200}" }

// 请求示例： 数组+变量组合。定义坐标数组 → 随机顺序依次点击
{ "id": "id1", "num": "2", "cmd": "{arr pts=100,200,300,400,500,600,700,800}{for arr=pts {click ${_item},500,wait=200,jitter=3,toast=1}}" }

##### for 循环扩展：数组遍历

原 for N={body} 固定次数循环基础上新增两种数组遍历模式。

##### for arr= — 顺序遍历数组

命令： {for arr=<数组名> {子命令...}}

按数组元素顺序逐一遍历，循环体内 ${_item} 为当前元素，${_index} 为序号（从 1 开始）。

// 请求示例：顺序遍历 names 数组，逐个 toast 显示
{ "id": "id1", "num": "2", "cmd": "{arr names=张三,李四,王五}{for arr=names {toast ${_index}:${_item},sleep=500}}" }

##### for rnd= — 随机遍历数组

命令： {for rnd=<数组名> {子命令...}}

使用 Fisher-Yates 洗牌算法随机打乱数组后逐一遍历，其他行为与 for arr= 相同。

// 请求示例：随机顺序点击数组中的坐标
{ "id": "id1", "num": "2", "cmd": "{arr pts=100,200,300,400,500,600}{for rnd=pts {click ${_item}}}" }

批量脚本示例

// 请求示例：点击坐标100,200 →等待2000毫秒 → 手机上弹出toast消息框
{ "id": "id1", "num": "2", "cmd": "{click 100,200}{sleep 2000}{toast 任务完成}" }

// 请求示例：打开设置 → 等待1000毫秒 → 等待500毫秒后点击以300,500为基础随机偏移抖动±3px的坐标 → 从坐标300,800滑动到300,400 用时500毫秒 → 等待2000毫秒→ 返回
{ "id": "id1", "num": "2,3", "cmd": "{StartAppName 设置}{sleep 1000}{click 300,500 wait=500,jitter=3}{swipe 300,800,300,400,500}{sleep 2000}{Key BACK}"}

// 请求示例：循环5次→  每次先等待300毫秒，然后点击以100,200为基础随机偏移±5px的坐标
{ "id": "id1", "num": "2", "cmd": "{for 5={click 100,200 wait=300,jitter=5}}" }

// 请求示例：在屏幕上通过ui布局里找一个文本里带“确定”2个字(text@~@确定)，并且可以点击(clickable@?)的地方进行点击
{ "id": "id1", "num": "2", "cmd": "{UiClick text@~@确定,, clickable@?,, mode=1}" }

// 请求示例：上滑一屏 → 循环3次→ 每次都多点同按+等待+返回主页
{ "id": "id1", "num": "2", "cmd": "{swipeDown 300}{for 3={multiClick 100,200,300,200,500,200 wait=200}{sleep 500}}{Key HOME}" }

// 请求示例：使用adb命令先点击坐标100,200 → 等待1000毫秒→ 使用adb命令启动设置
{ "id": "id1", "num": "2", "cmd": "{adb shell input tap 100 200}{sleep 1000}{adb shell am start -n com.android.settings/.Settings}" }

// 请求示例：for 嵌套 if
{for 3={if ocrclick=确定 {click 100,200}}{else {{swipeUp}}}}

//请求示例： if 嵌套 for
{if uiClick=按钮@~@ {for 5 {click 100,200,wait=500}}}

//请求示例： 多层嵌套
{for 3={if ocrclick=下一页 {{swipeUp 500}}{for 2 {click 100,200}}}}