API 手册（用户版）

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/?id=id123&num=2,3&cmd=StartApp com.android.settings

二、请求与响应格式

请求 (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" 只表示命令已发送执行；投屏操作的实际结果需要另外检测判断。

三、设备操作命令

启动 App

命令: StartApp <包名>/<Activity>

{ "id": "id1", "num": "2,3", "cmd": "StartApp com.android.settings/com.android.settings.homepage.SettingsHomepageActivity" }

操作数量：单个或多个。无返回数据。

停止 App

命令: StopApp <包名>

{ "id": "id1", "num": "2,3", "cmd": "StopApp com.android.settings" }

操作数量：单个或多个。无返回数据。

点击

命令: click <x>,<y>

{ "id": "id1", "num": "2,3", "cmd": "click 50,250" }

操作数量：单个或多个。无返回数据。

滑动

命令: swipe <x1>,<y1>,<x2>,<y2>,<时长毫秒>

相同坐标为长按，不同坐标为慢速拖动。

{ "id": "id1", "num": "2,3", "cmd": "swipe 50,250,500,250,600" }

操作数量：单个或多个。无返回数据。

拖动

命令: drag <x1>,<y1>,<x2>,<y2>,<时长毫秒>

比 swipe 更快，相同坐标为长按。

{ "id": "id1", "num": "2,3", "cmd": "drag 50,250,500,250,600" }

操作数量：单个或多个。无返回数据。

滚动

命令: scroll <x>,<y>,<方向>,<轴向>,<次数>

• 方向：1 = 前进，-1 = 后退
• 轴向：v = 垂直，h = 水平

{ "id": "id1", "num": "2,3", "cmd": "scroll 50,250,1,v,10" }

操作数量：单个或多个。无返回数据。

输入文本

命令: setText <文本内容>

\r 表示换行。

{ "id": "id1", "num": "2,3", "cmd": "setText hello world" }

操作数量：单个或多个。无返回数据。

按键

命令: Key <键码或名称>

常用键名：HOME（主页）、BACK（返回）、APP_SWITCH（切换应用）、VOLUME_UP（音量+）、VOLUME_DOWN（音量-）、VOLUME_MUTE（静音）。

也支持数字键码和完整键码名（省略 KEYCODE_ 前缀）。

{ "id": "id1", "num": "2", "cmd": "Key HOME" }

操作数量：单个或多个。无返回数据。

四、脚本相关

执行已保存的脚本

命令: RunScript <脚本名称>

执行【脚本管理器】中保存的脚本。支持类型：中控脚本、AutoJS、EasyClick。

{ "id": "id1", "num": "2,3", "cmd": "RunScript test1" }

操作数量：单个或多个。无返回数据。

执行脚本文件

命令: RunScriptFile <文件路径>

执行电脑上的脚本文件。

{ "id": "id1", "num": "2,3", "cmd": "RunScriptFile d:\\脚本3.js" }

操作数量：单个或多个。无返回数据。

查看脚本日志

命令: GetRunLog

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

{ "id": "id1", "num": "2", "cmd": "GetRunLog" }

操作数量：单个。返回换行分隔的日志文本。

停止脚本

命令: StopScript

停止指定设备上正在执行的批量脚本（包括单条和多条批量脚本）。

{ "id": "id1", "num": "2", "cmd": "StopScript" }

操作数量：单个或多个。无返回数据。

五、批量指令脚本

是什么

可以在一个请求中发送多条指令，用 {} 花括号包裹每条命令，脚本引擎会逐条顺序执行。支持循环、延时、坐标随机抖动。

语法格式

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

执行规则

• 每条指令必须用 {} 包裹
• 1 条指令 → 同步执行（等待完成）
• 多条指令 或 1 条 for → 异步执行（后台运行）
• 指令间按顺序执行
• for 循环体内再用 {} 包裹子命令

公共参数

适用命令：click、swipe、longtap、multiClick、swipeUp/Down/Left/Right。不适用于 for、sleep、filter。

批量脚本示例

基础示例 — 打开设置 → 等待 → 点击 → 滑动 → 返回：

{
  "id": "id1",
  "num": "2,3",
  "cmd": "{StartApp com.android.settings}{sleep 1000}{click 300,500 wait=500,jitter=3}{swipe 300,800,300,400,500}{Key BACK}"
}

循环点击 — 点击 5 次，间隔 300ms，坐标随机偏移 ±2px：

{ "id": "id1", "num": "2", "cmd": "{for 5 {click 100,200 wait=300,jitter=2}}" }

嵌套循环 + 多点同按：

{ "id": "id1", "num": "2", "cmd": "{swipeDown 300}{for 3 {multiClick 100,200,300,200,500,200 wait=200}{sleep 500}}{Key HOME}" }

批量脚本命令速查表

各命令详细说明

sleep（延时）

{sleep <毫秒>}

{ "id": "id1", "num": "2", "cmd": "{click 100,200}{sleep 1500}{click 300,400}" }

multiClick（多点同按）

{multiClick <x1>,<y1>,<x2>,<y2>[,...][,holdMs]}

至少 2 对坐标。最后可选持续时间 holdMs（默认 100ms）。

{ "id": "id1", "num": "2", "cmd": "{multiClick 100,200,300,400,200}" }

swipeUp / swipeDown / swipeLeft / swipeRight（方向滑动）

{swipeUp <duration>}
{swipeDown <duration>}
{swipeLeft <duration>}
{swipeRight <duration>}

自动基于屏幕尺寸计算滑动距离（半屏），贝塞尔曲线生成随机轨迹。必填参数，单位毫秒，如 500。

{ "id": "id1", "num": "2", "cmd": "{swipeUp 300}" }

longtap（长按）

{longtap <x>,<y>,<ms>}

{ "id": "id1", "num": "2", "cmd": "{longtap 200,300,1000}" }

adb（脚本内）

{adb <完整 adb 命令>}

在批量脚本中执行 ADB 命令（Fire-and-forget，不等待结果）。

{ "id": "id1", "num": "2", "cmd": "{adb shell input tap 100 200}{sleep 500}{adb shell am start -n com.android.settings/.Settings}" }

filter（UI 筛选点击）

{filter <筛选条件>}

格式同 GetUiJson 的简化参数，详见第六章。

{ "id": "id1", "num": "2", "cmd": "{filter text@~@确定,, clickable@?,, mode=1}" }

for（循环）

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

循环 N 次执行子命令块。支持嵌套。循环日志带前缀如 for 1/5:。

{ "id": "id1", "num": "3", "cmd": "{for 5 {click 100,200 wait=300,jitter=3}}" }

六、ADB 命令

无返回值模式（Fire-and-Forget）

adb <完整 adb 命令>

适合安装应用、修改设置等不需要返回结果的场景。

{ "id": "id1", "num": "all", "cmd": "adb shell pm install /sdcard/app.apk" }

操作数量：单个或多个/all。无返回数据。

有返回值模式

在命令末尾加 || 分隔符即可获取返回结果。

// 返回所有包名
{ "id": "id1", "num": "2", "cmd": "adb shell pm list packages ||" }

// 只返回包含 sogou 的包名
{ "id": "id1", "num": "2", "cmd": "adb shell pm list packages || sogou" }

返回结果通过 :adb: 长消息分段传输，默认 30 秒超时（可通过 ReceiveMessageTimeOut 设置）。

设置超时

命令: ReceiveMessageTimeOut <毫秒>

设置需要返回消息的命令（如 ADB 有返回值模式）的超时时间。此参数必须设置，脚本中只需设置一次。若不设置，默认 30 秒（30000ms）。

{ "id": "id1", "num": "all", "cmd": "ReceiveMessageTimeOut 30000" }

操作数量：全局。无返回数据。

此参数只需设置一次，后续所有有返回值的命令均使用该超时时间。

七、截屏

保存为文件

命令: ImgScreenCapture <路径>,<是否加编号>

• 路径会自动追加 .png 后缀
• 加编号 = true：文件名如 a2.png、a3.png

{ "id": "id1", "num": "2,3", "cmd": "ImgScreenCapture d:\\cls\\a,true" }

操作数量：多个（加编号=true）或单个（加编号=false）。

返回 Base64

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

• 坐标全填 0 表示全屏
• 格式：jpg、png、bmp

返回 Gzip 压缩后的 Base64 编码（不含 data:image/... 前缀）。仅支持单个设备。

{ "id": "id1", "num": "2", "cmd": "ImgCaptureScreenBase64 0,0,0,0,jpg" }

快速截屏（从电脑显示画面）

需要在设置中将【硬件加速 → 画面加速模式】设为【加速模式2】。画质取决于小图分辨率。

{ "id": "id1", "num": "2,3", "cmd": "FastImgScreenCapture d:\\cls\\a,true" }

八、UI 元素操作

获取 UI 布局（XML）

命令: GetUiXml

{ "id": "id1", "num": "3", "cmd": "GetUiXml" }

仅单个设备。返回 XML 文本。

获取 UI 布局（JSON，支持筛选）

命令: GetUiJson [筛选条件]

详见本章末尾的「UI 筛选参数格式」。

{ "id": "id1", "num": "3", "cmd": "GetUiJson" }

仅单个设备。返回 JSON 文本。

保存 UI 布局到文件

命令: UiSaveXml <路径>,<加编号>

{ "id": "id1", "num": "2,3", "cmd": "UiSaveXml d:\\cls\\a,true" }

查找单个元素（XPath）

命令: UiFindElement <xpath>,,<左>,,<上>,,<右>,,<下>,,<是否点击>,,<返回类型>

• xpath：如 //node[@text='hello']
• 坐标全填 0 = 全屏查找
• 是否点击：true / false
• 返回类型：point（坐标）、node（属性）、nodes（含子节点属性）

{ "id": "id1", "num": "2", "cmd": "UiFindElement //node[@text='hello'],,0,,0,,0,,0,,true,,point" }

仅单个设备。返回坐标或属性，未找到不返回数据。

查找多个元素（XPath）

命令: UiFindElements <过滤空文本>,,<xpath>[,,<返回类型>]

• 过滤空文本：true = 跳过空文本节点
• 多个坐标用 ;; 分隔

{ "id": "id1", "num": "2", "cmd": "UiFindElements true,,//node[@text='hello']" }

仅单个设备。

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

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

三个模块用 ,, 分隔，均可省略。

f 部分：筛选条件

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

匹配类型：

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

s 部分：输出字段选择

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

a 部分：动作配置

Range 简写规则：

• range=3 → 只点第 3 个
• range=-1 → 点最后一个
• range=1-3 → 点第 1 到第 3 个

筛选示例

// 查找区域内可点击元素，点击第一个，抖动 ±5px
bounds@in@100,200,500,800 ,, clickable@? ,, mode=1,range=1,jitter=5,wait=200

// 查找包含"确定"的可点击按钮，返回文本/类名/坐标
text@~@确定 ,, clickable@=@true ,, tcb

// 点击最后一个包含"提交"的元素
text@~@提交 ,,  ,, mode=1,range=-1

// 按 resource-id 精确匹配，不动作
resource-id@=@com.example:id/login_btn

// 复杂条件：depth=3 + enabled + class含Button，点前3个
depth@=@3 ,, enabled@=@true ,, class@~@Button ,, tdcb ,, mode=1,range=1-3,jitter=3,wait=150

九、找色 / 找图

找色

命令: ImgFindColor <颜色>,<左>,<上>,<右>,<下>,<相似度>,<是否点击>

从设备屏幕高清原图查找，全图查找坐标全填 0。

{ "id": "id1", "num": "2", "cmd": "ImgFindColor #ffffff,0,0,0,0,90,true" }

仅单个设备。返回坐标 x,y，未找到无返回。

快速版（从电脑画面查找，需加速模式2）：FastImgFindColor，参数相同。

找图

命令: ImgFindImg <图片路径>,<左>,<上>,<右>,<下>,<相似度>,<是否点击>

{ "id": "id1", "num": "2", "cmd": "ImgFindImg d:\\cls\\a.png,0,0,0,0,90,false" }

仅单个设备。返回坐标 x,y，未找到无返回。

快速版（从电脑画面查找，需加速模式2）：FastImgFindImg，参数相同。

十、OCR 文字识别

提取文本

命令: OcrGetText <左>,<上>,<右>,<下>,<相似度>,<返回全部>

全屏提取坐标全填 0。返回格式：text:文本,score:置信度,point:四角坐标。

{ "id": "id1", "num": "2", "cmd": "OcrGetText 0,0,0,0,50,true" }

仅单个设备。多个结果用 ;; 分隔。

快速版（从电脑画面识别，需加速模式2）：FastOcrGetText，参数相同。

查找文本

命令: OcrFindText <关键词>,,<左>,,<上>,,<右>,,<下>,,<相似度>,,<点击>,,<匹配方式>,,<返回全部>

• 匹配方式：true = 包含判断（默认），false = 完全相等

{ "id": "id1", "num": "2", "cmd": "OcrFindText hello,,0,,0,,0,,0,,90,,true,,false,,true" }

仅单个设备。返回坐标，未找到无返回。

快速版（从电脑画面识别，需加速模式2）：FastOcrFindText，参数相同。

十一、文件传输

上传文件

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

{ "id": "id1", "num": "2", "cmd": "PushFile d:\\abc\\a1.txt,/sdcard/Download/b1.txt" }

操作数量：单个或多个。

下载文件

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

{ "id": "id1", "num": "2", "cmd": "PullFile /sdcard/Download/b1.png,d:\\abc\\" }

操作数量：仅单个。

十二、设备管理（PC 端命令）

消息提示

窗口消息：Toast <时长毫秒>,<内容>

{ "id": "id1", "num": "2", "cmd": "Toast 3000,hello" }

全局消息：GlobalToast <内容>,<类型>

类型：i=普通（自动消失）、w=警告、e=错误（需手动关闭）

{ "id": "id1", "num": "2", "cmd": "GlobalToast 操作完成,i" }

设备选取

显示控制

分组管理

{ "id": "id1", "num": "", "cmd": "ImportGroup 分组1,192.168.1.2:5555,192.168.1.3:5555;测试组,192.168.1.4:5555" }

设备信息查询

获取在线设备: OnlineDevice <范围>,<信息类型>

• 范围：all（全部）/ select（已选中）/ display（当前显示）
• 信息类型：number / title / deviceid / pixels / all

{ "id": "id1", "num": "", "cmd": "OnlineDevice all,all" }

返回格式：编号/标题/DeviceID;编号/标题/DeviceID;...

获取分组设备: GroupDevice <组名>,<信息类型>

{ "id": "id1", "num": "", "cmd": "GroupDevice 分组1,all" }

IP 连接管理

修改 IP 列表：EditIpList <操作>,<后续动作>,<IP列表>

• 操作：add（追加）/ clear（清除重建）
• 后续动作：none / connect（添加后刷新连接）/ reconnect（先断再连）
• IP 列表：ip:端口 逗号分隔

{ "id": "id1", "num": "", "cmd": "EditIpList clear,connect,192.168.1.1:5555,192.168.1.2:5555" }

输入法切换

命令: SetInputMethod <输入法>

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

{ "id": "id1", "num": "2", "cmd": "SetInputMethod 讯飞" }

客服消息 & 剪贴板