说明

1
---
2
name: ec-android-cli
3
description: >-
4
  中文说明：EasyClick ec-android-cli 的安装前提、子命令、参数与示例。
5
  在用户或 Agent 需要执行、脚本化或排查该 CLI 时使用；不包含实现细节。
6
---
7

8
# ec-android-cli 使用说明
9

10
## 使用前提
11

12
- 本机已启动 **IntelliJ IDEA**，并已加载 **EasyClick 开发工具**插件；插件需处于可响应命令的状态。
13
- 命令行中的 **模块名** 与 IDEA 里该脚本工程对应的 **模块名** 一致。
14
- 多窗口、多工程时，建议用 **`-p`** 传入与 IDEA 中打开路径一致的 **工程根目录**，便于匹配到正确实例。
15

16
## 程序名与帮助
17

18
- **本仓库自带可执行文件**（相对仓库根目录）：**`ec_work_config/android/bin/ec-android-cli`**
19
    - 在仓库根下：`./ec_work_config/android/bin/ec-android-cli -h`
20
    - Agent / 脚本优先使用该路径，避免依赖全局 PATH。
21
    - 并且输出的日志格式设置为json格式
22
- 若本机已单独安装并加入 PATH，也可直接执行 **`ec-android-cli`**（与上述为同一程序；本地若改名，请将命令中的名称一并替换）。
23
- 查看总帮助：`./ec_work_config/android/bin/ec-android-cli -h`（或在 PATH 已配置时：`ec-android-cli -h`）
24
- 查看子命令帮助：`./ec_work_config/android/bin/ec-android-cli <子命令> -h`
25

26
## 子命令一览
27

28
| 子命令               | 作用                         |
29
|-------------------|----------------------------|
30
| `preview`         | 预览工程                       |
31
| `run`             | 运行工程                       |
32
| `stop`            | 停止当前运行                     |
33
| `build`           | 构建 IEC                     |
34
| `capture-screen`  | 截图（从 IDEA 已连接设备抓取截图并返回路径）  |
35
| `capture-node`    | 抓取 UI 节点（UIX，本质为 XML）并返回路径 |
36
| `ocr-local-image` | OCR 识别本地图像并输出识别结果          |
37
| `ocr-screen`      | OCR 识别当前屏幕并输出识别结果          |
38
| `test-image`      | 图片模板匹配测试（本图/抓屏）并输出测试结果     |
39
| `monitor`         | 仅持续输出日志流（不要求 `-m`）         |
40

41
**说明：** 除 `monitor` 外，其余子命令均需 **`-m`（模块名）**；`monitor` 不需要模块名。
42

43
## 通用参数（除 `monitor` 外的大多数子命令）
44

45
| 参数                          | 含义                                                                                                                                                                                   |
46
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
47
| **`-m` / `--module`**       | **必填**。IDEA 模块名。                                                                                                                                                                     |
48
| **`-p` / `--project`**      | 可选。工程根目录路径（与 IDEA 中打开路径一致）。                                                                                                                                                          |
49
| **`-f` / `--format`**       | 可选。日志行格式：`text` 或 `json`；**省略时默认为 `json`**。                                                                                                                                          |
50
| **`-o` / `--log`**          | 可选。将日志**追加**写入指定文件路径。                                                                                                                                                                |
51
| **`-k` / `--stop-on`**      | 可选。日志中**包含**该子串时，打印提示并**退出**（结束本次日志监控）。多个条件为**或**关系时，可用 **`                                                                                                                          |||`** 连接多个子串（任一子串命中即退出）。 |
52
| **`-w` / `--monitor-logs`** | 可选。`true` / `false`。**`preview` / `run` / `stop`**：未写 `-w` 时视为 **`true`**（持续跟日志至 **Ctrl+C** 或命中 `-k`）。**`build`**：未写 `-w` 时为 **`false`**（操作结束后即结束日志）。显式写 `-w true` / `-w false` 可覆盖。 |
53
| **`-r` / `--random-log`**   | 可选。`true` / `false`。为 `true` 时在 **`ai_logs/`** 下自动生成日志文件名；**不可与 `-o` 同时使用**。                                                                                                         |
54

55
**约束：** 凡写出的可选参数须带**有效取值**；**`-r` 与 `-o` 不能同时使用**。
56

57
**`-k` 多关键字（通用）：** 所有支持 **`-k`** 的子命令——**`preview` / `run` / `stop` / `build` / `monitor`**——均可用 *
58
*`|||`** 连接多个子串，表示**或**：日志中**任一**子串出现即结束本次监控。
59

60
**`preview` 专用：** 未写 **`-k` / `--stop-on`** 时，默认停止关键字为 **`执行UI结束`**；未写 **`-w`** 时默认**持续监控日志
61
**（等同 `-w true`）。
62

63
**`run` 专用：** 未写 **`-k`** 时，默认停止关键字为 **`脚本已运行结束`**；未写 **`-w`** 时默认**持续监控日志**（等同
64
`-w true`）。
65

66
**`stop` 专用：** 未写 **`-k`** 时，默认在日志中出现 **`停止失败`**、**`停止运行成功`** 或 **`无设备连接`** 时结束监控（**任一
67
**命中即可）；未写 **`-w`** 时默认**持续监控日志**（等同 `-w true`）。若显式传入 **`-k`**，则以你设置的关键字为准（仍可用 *
68
*`|||`** 表示多关键字“或”）。
69

70
**`build`（编译 IEC）专用：** 未写 **`-k`** 时，默认在日志中出现 **`release.iec`**、**`编译IEC成功`** 或 **`编译失败`**
71
时结束本次日志监控（**任一**命中即可）。
72

73
## `monitor` 专用参数
74

75
仅日志流；不使用 `-m`、`-p`、`-w`。
76

77
| 参数                        | 含义                             |
78
|---------------------------|--------------------------------|
79
| **`-f` / `--format`**     | 同上文，`text` 或 `json`，默认 `json`。 |
80
| **`-o` / `--log`**        | 同上文。                           |
81
| **`-k` / `--stop-on`**    | 同上文。                           |
82
| **`-r` / `--random-log`** | 同上文（勿与 `-o` 同用）。               |
83

84
## 日志输出习惯
85

86
- 常规日志多输出到 **标准错误（stderr）**；使用 **`-o`** 或 **`-r`** 时还会写入文件。
87
- 默认日志行格式为 **JSON**，除非指定 **`-f text`**。
88

89
## 示例
90

91
# 以下假定当前目录为仓库根；`EC` 即 ./ec_work_config/android/bin/ec-android-cli
92
EC=./ec_work_config/android/bin/ec-android-cli
93
$EC preview -m app
94
$EC preview -m app -f json
95
$EC run -m app -f json -o /tmp/easyclick.log
96
$EC run -m app -r true
97
$EC run -m app -w false
98
$EC stop -m app
99
$EC build -m app
100
$EC capture-screen -m app
101
$EC capture-node -m app -d /tmp/nodes
102
$EC ocr-local-image -m app -i /tmp/a.png
103
$EC ocr-screen -m app
104
$EC test-image -m app -s /tmp/s.png
105
$EC monitor
106
$EC monitor -f text -o /tmp/monitor.log -k "完成"
107

108
多工程时示例：
109

110
./ec_work_config/android/bin/ec-android-cli run -m app -p /path/to/project/root
111

112
## `capture-screen`（截图）
113

114
- **用途**：调用截图，成功后会输出路径。
115
- **常用短参数**：
116
    - `-n`：`--only-network`
117
    - `-d`：`--dir`
118

119
EC=./ec_work_config/android/bin/ec-android-cli
120
$EC capture-screen -m app
121
$EC capture-screen -m app -n -d /tmp/shots
122

123
## `capture-node`（抓取节点 UIX）
124

125
- **用途**：调用抓节点功功能，成功后在 输出 uix文件路径。
126
- **常用短参数**：
127
    - `-d`：`--dir`
128

129
EC=./ec_work_config/android/bin/ec-android-cli
130
$EC capture-node -m app
131
$EC capture-node -m app -d /tmp/nodes
132

133
## `ocr-local-image`（OCR 本地图像）
134

135
- **用途**：调用 成功后输出 OCR 结果字符串。
136
- **必填**：`-i/--path` 本地图像路径
137
- **可选**：
138
    - `-t/--ocr-type`：`paddleOcrNcnnV5|paddleOcrOnnxV4|paddleOcrOnnxV5|ocrLite`（默认 `paddleOcrNcnnV5`）
139
    - `-P/--padding`：默认 `32`
140
    - `-X/--max-side-len`：默认 `640`
141
    - `-R/--release`：默认 `false`
142

143
EC=./ec_work_config/android/bin/ec-android-cli
144
$EC ocr-local-image -m app -i /path/to/image.png
145
$EC ocr-local-image -m app -i a.jpg -t paddleOcrOnnxV5 -P 48 -X 960 -R
146

147
## `ocr-screen`（OCR 屏幕）
148

149
- **用途**：调用成功后在OCR 结果字符串。
150
- **可选**（同 `ocr-local-image`，但不需要 `--path`）：
151
    - `-t/--ocr-type`（默认 `paddleOcrNcnnV5`）
152
    - `-P/--padding`（默认 `32`）
153
    - `-X/--max-side-len`（默认 `640`）
154
    - `-R/--release`（默认 `false`）
155

156
EC=./ec_work_config/android/bin/ec-android-cli
157
$EC ocr-screen -m app
158
$EC ocr-screen -m app -t paddleOcrOnnxV5 -P 48 -X 960 -R
159

160
## `test-image`（图片测试）
161

162
- **用途**：调用成功后在 测试结果字符串。
163
- **必填**：`-s/--small-image-path` 小图路径
164
- **可选**（均为字符串格式）：
165
    - `-T/--test-type`：`1` 本图测试；`2` 抓屏测试（默认 `2`）。`test-type=2` 时无需 `--big-image-path`
166
    - `-B/--big-image-path`：大图路径（仅 `test-type=1` 时需要）
167
    - `-F/--func`：`findImageByColor|findImage|matchTemplate`（默认 `findImage`）
168
    - `-M/--method`：模板匹配方式（默认 `5`）
169
    - `-g/--range`：默认 `0,0,0,0`
170
    - `-l/--limit`：默认 `1`
171
    - `-L/--max-level`：默认 `-1`
172
    - `-E/--weak-threshold`：默认 `0.7`
173
    - `-H/--threshold`：默认 `0.8`
174
    - `-C/--opencv-mat`：`1` 否；`2` 是（默认 `1`）
175

176
EC=./ec_work_config/android/bin/ec-android-cli
177
$EC test-image -m app -s /tmp/s.png
178
$EC test-image -m app -T 1 -s s.png -B b.png -F matchTemplate -M 5
179
$EC test-image -m app -F findImage -g 0,0,0,0 -l 1 -E 0.7 -H 0.8

1
logd(msg)/logi(msg)/logw(msg)/loge(msg)   // 日志输出（蓝/绿/黄/红）
2
toast(msg)                                // Toast提示
3
sleep(ms)                                 // 休眠（毫秒）
4
exit()                                    // 退出脚本
5
startEnv()                                // 启动无障碍服务
6
isServiceOk()                             // 检查服务是否正常

1
text(str)/textMatch(reg)                  // 文本包含/正则
2
textStartsWith(str)/textEndsWith(str)     // 文本开头/结尾
3
desc(str)/descMatch(reg)                  // 描述包含/正则
4
id(str)/idMatch(reg)                      // ID包含/正则
5
clz(str)/clzMatch(reg)                    // 类名包含/正则
6
pkg(str)/pkgMatch(reg)                    // 包名包含/正则
7
bounds(l,t,r,b)                           // 边界范围
8
selector.and(s2)/selector.or(s2)          // 与/或条件

1
// 获取节点
2
selector.getOneNodeInfo(timeout)          // 获取单个节点
3
selector.getNodeInfo(timeout)             // 获取所有匹配节点
4
selector.has()                            // 判断是否存在
5
selector.waitExistNode(timeout)           // 等待节点出现
6
// 节点属性
7
node.text/node.desc/node.id/node.clz/node.pkg     // 文本/描述/ID/类名/包名
8
node.bounds                               // 边界{l,t,r,b}
9
node.clickable/node.visible/node.childCount       // 是否可点击/可见/子节点数
10
// 节点操作
11
node.click()/node.longClick()             // 点击/长按
12
node.inputText(content)/node.clearText()  // 输入/清空文本
13
node.scrollForward()/node.scrollBackward()// 向前/后滚动
14
node.parent()/node.child(index)           // 获取父/子节点

1
clickPoint(x,y)/longClickPoint(x,y)/doubleClickPoint(x,y)   // 点击/长按/双击
2
swipeToPoint(x1,y1,x2,y2,duration)        // 滑动到指定坐标
3
swipeUp()/swipeDown()/swipeLeft()/swipeRight()              // 上/下/左/右滑
4
touchDown(x,y)/touchMove(x,y)/touchUp(x,y)// 触摸控制
5
inputText(selectors,content)              // 输入文本
6
clearTextField(selectors)                 // 清空文本
7
getOneNodeInfo(selectors,timeout)         // 获取单个节点
8
has(selectors)/waitExistNode(selectors,timeout) // 判断/等待节点
9
dumpXml()                                 // 获取节点XML

1
device.getScreenWidth()/getScreenHeight() // 屏幕宽高
2
device.getIMEI()/getBrand()/getModel()    // IMEI/品牌/机型
3
device.getAndroidId()/getMacAddress()     // Android ID/MAC
4
device.getBrightness()/setBrightness(b)   // 获取/设置亮度
5
device.getBattery()                       // 电量
6
device.vibrate(millis)                    // 震动

1
utils.openApp(packageName)                // 打开应用
2
utils.openAppByName(appName)              // 通过名称打开
3
utils.isAppExist(packageName)             // 判断是否已安装
4
utils.getAppVersionCode(packageName)      // 获取版本号
5
utils.showLogWindow()/hideLogWindow()     // 显示/隐藏日志窗

1
image.requestScreenCapture(timeout,type)  // 请求截图权限
2
image.captureScreen()                     // 截图
3
image.captureToFile(retry,x,y,ex,ey,path) // 截图到文件
4
image.readImage(path)/saveImage(img,path) // 读取/保存图片
5
image.findImageEx(template,x,y,ex,ey,weakThresh,thresh,limit,method)  // 找图
6
image.findColorEx(color,thresh,x,y,ex,ey,limit,orz)                   // 找色
7
image.findMultiColorEx(firstColor,points,thresh,x,y,ex,ey,limit,orz)  // 多点找色
8
img.getWidth()/getHeight()                // 获取宽高
9
img.pixel(x,y)                            // 获取像素颜色
10
img.recycle()                             // 回收图像

1
let ocrInst=ocr.newOcr()
2
ocrInst.initOcr({"type":"paddleOcrNcnnV5","numThread":2,"padding":32,"maxSideLen":640})
3
let results=ocrInst.ocrImage(img,timeout,map)  // 返回[{label,confidence,x,y,width,height}]
4
ocrInst.ocrFile(path,timeout,map)           // 识别图片文件
5
ocrInst.releaseAll()                        // 释放资源

1
file.readFile(path)/writeFile(data,path)  // 读取/写入
2
file.copyFile(src,dest)/moveFile(src,dest)// 复制/移动
3
file.deleteFile(path)                     // 删除
4
file.exists(path)/isFile(path)/isDir(path)// 判断存在/文件/目录
5
file.create(path)/listDir(path)           // 创建/列出目录

1
http.httpGetDefault(url,timeout,headers)  // GET请求
2
http.httpPost(url,params,files,timeout,headers)  // POST请求
3
http.postJSON(url,json,timeout,headers)   // POST JSON
4
http.downloadFile(remoteUrl,file,timeout,headers)  // 下载文件

1
sqlite.connectOrCreateDb(dbName)          // 连接/创建数据库
2
sqlite.createTable(tableName,columns)     // 创建表
3
sqlite.insert(tableName,map)              // 插入数据
4
sqlite.update(tableName,map,where)        // 更新数据
5
sqlite.query(sql)/execSql(sql)            // 查询/执行SQL
6
sqlite.close()                            // 关闭数据库

1
thread.execAsync(runnable)                // 异步执行，返回线程ID
2
thread.cancelThread(threadId)/stopAll()   // 取消线程/全部
3
setTimeout(func,timeout)                  // 延迟执行
4
setInterval(func,interval)                // 周期执行

1
ui.layout(name,content)                   // 加载XML布局
2
ui.findViewById(id)                       // 通过ID查找视图
3
ui.setVisibility(view,visibility)         // 设置可见性
4
ui.setText(view,text)/getText(view)       // 设置/获取文本
5
ui.setEvent(view,eventType,callback)      // 设置事件监听
6
ui.putShareData(key,value)/getShareData(key)  // 存储/获取共享数据
7
ui.customDialog(params,view,bind,dismiss) // 自定义对话框

1
shell.installApp(path)                    // 安装APK
2
shell.uninstallApp(packageName)           // 卸载应用
3
shell.stopApp(packageName)                // 停止应用
4
shell.execCommand(command)                // 执行Shell命令
5
shell.sudo(command)                       // 执行Root命令

1
// 蓝牙HID
2
bleEvent.startConnect(name,save,timeout)  // 连接蓝牙设备
3
bleEvent.isConnected()                    // 是否已连接
4
bleEvent.clickPoint(x,y)/swipe(x0,y0,x1,y1,duration)  // 点击/滑动
5
bleEvent.home()/back()                    // 主页/返回键
6
// OTG HID
7
otgEvent.init()/connectFirst()            // 初始化/连接
8
otgEvent.isConnected()                    // 是否已连接
9
otgEvent.clickPoint(x,y)/swipe(x0,y0,x1,y1,duration)  // 点击/滑动

1
// Point对象
2
point.click()/longClick()/doubleClick()   // 点击/长按/双击
3
// Rect对象
4
rect.click()/clickRandom()                // 点击中心/随机位置
5
// String扩展
6
str.contains(s)/replaceAll(s1,s2)/trim()/toInt()  // 包含/替换/去空格/转整数

1
// 启动环境
2
function main(){if(!autoServiceStart(3)){loge("服务启动失败");return;}}
3
function autoServiceStart(time){for(let i=0;i<time;i++){if(isServiceOk())return true;startEnv();sleep(1000);}return isServiceOk();}
4
main();
5
// 查找点击
6
let node=text("推荐").getOneNodeInfo(0);if(node)node.click();else loge("未找到");
7
// 滑动
8
let w=device.getScreenWidth(),h=device.getScreenHeight();swipeToPoint(w/2,h*0.8,w/2,h*0.2,500);
9
// OCR
10
let ocrInst=ocr.newOcr();ocrInst.initOcr({"type":"paddleOcrNcnnV5","numThread":2,"padding":32,"maxSideLen":640});let img=image.captureScreen();let results=ocrInst.ocrImage(img,5000,null);if(results)for(let i=0;i<results.length;i++)logd(results[i].label);ocrInst.releaseAll();