GF-CLI 使用说明

Android 设备自动化测试命令行工具，提供脚本拉取、应用安装、SO 文件管理、日志收集、应用操作等功能。

目录

• 环境要求
• 快速开始
• 功能详解
  • 1. 拉取线上包名脚本
  • 2. 创建脚本项目模版
  • 3. 生成 project.json 配置文件
  • 4. 安装应用到设备
  • 5. 安装线上工具包到设备
  • 6. 安装线上 SO 文件到设备
  • 7. 运行 SO 文件通关
  • 8. 拉取设备日志
  • 9. 推送文件到设备
  • 10. 拉取设备下载目录内容
  • 11. 打开指定包名应用
  • 12. 关闭指定包名应用
  • 13. 清空指定包名应用数据
  • 14. 获取测试代理 IP
  • 15. 设置任务信息
• 输入缓存
• 自动更新
• 常见问题

环境要求

• Node.js 18 或更高版本
• ADB（Android Debug Bridge）已配置到系统环境变量
• Android 设备 已通过 USB 或网络连接到本机

检查 ADB 连接

adb devices

输出示例：

List of devices attached
10.73.202.89:5555   device

快速开始

安装

npm install -g gf-cli-package

启动

gf

进入主菜单：

╔══════════════════════════════════════╗
║          GF-CLI 自动化工具           ║
║      版本 1.0.0 · Android CLI        ║
╚══════════════════════════════════════╝

? 请选择要使用的功能：
 ────── 脚本管理 ──────
   1. 拉取线上包名脚本
   2. 创建脚本项目模版
   3. 生成 project.json 配置文件
 ────── 设备操作 ──────
   4. 安装应用到设备
   5. 安装线上工具包到设备
   6. 安装线上 SO 文件到设备
   7. 运行 SO 文件通关
   8. 拉取设备日志
   9. 推送文件到设备
   10. 拉取设备下载目录内容
 ────── 应用操作 ──────
   11. 打开指定包名应用
   12. 关闭指定包名应用
   13. 清空指定包名应用数据
 ────── 其他 ──────
   14. 获取测试代理 IP
   15. 设置任务信息

↑↓ 方向键导航，回车键确认选择。

功能详解

1. 拉取线上包名脚本

从内部 FTP 服务器下载指定包名的自动化测试脚本到本地。

操作步骤：

1. 在主菜单中选择 1. 拉取线上包名脚本
2. 输入包名（格式：com.xxx.xxx，至少两段）
3. 程序自动创建 {包名}/ 目录并同步下载脚本文件

输入示例：

? 请输入要拉取的线上包名： com.starbucks.mobilecard

2. 创建脚本项目模版

快速生成自动化脚本的脚手架文件，包含入口脚本和项目配置。

操作步骤：

1. 在主菜单中选择 2. 创建脚本项目模版
2. 输入包名

生成的文件：

com.example.demo/
├── com.example.demo.js     # 脚本入口文件（含完整框架）
└── project.json            # 项目配置

生成的脚本入口文件 包含：

• gameAction() — 游戏行为逻辑入口
• taskMainThread() — 主线程调度
• appCommonAction() — 通用操作（支持 IAA 广告）

3. 生成 project.json 配置文件

为已有的脚本项目生成 project.json 配置文件。

操作步骤：

1. 在主菜单中选择 3. 生成 project.json 配置文件
2. 输入包名
3. 程序自动扫描当前目录及包含该包名的子目录，列出所有匹配的 JS 文件
4. 选择要作为 main 入口的 JS 文件
5. 程序在所选文件所在的目录中生成 project.json

自动扫描范围：

• 当前目录下包含包名的 .js 文件（如 com.example.demo.js）
• 包含包名的子目录内的所有 .js 文件（如 com.example.demo/game.js）

生成的 project.json：

{
  "name": "zzap",
  "main": "game.js",
  "ignore": [],
  "packageName": "com.script.zzad",
  "versionName": "1.0.0",
  "versionCode": 1
}

4. 安装应用到设备

将应用安装到 Android 设备，支持本地安装和线上安装两种方式。

方式 A：安装线上应用

1. 选择 安装线上应用
2. 输入包名，程序自动搜索 9 个 FTP 目录下的 APK 文件
3. 从搜索结果中选择要安装的版本

? 请输入想要安装的包名： com.starbucks.mobilecard
? 请选择要安装的线上应用：
   com.starbucks.mobilecard_6.124_apkcombo.apk
   com.starbucks.mobilecard_6.123_apkcombo.apk

方式 B：安装本地应用

1. 选择 安装本地应用
2. 输入本地 APK 文件所在目录（绝对路径）
3. 从列表中选择要安装的文件（支持 .apk / .xapk / .apks）

? 请输入本地应用存在的目录： D:\apk-files
? 请选择要安装的本地应用：
   com.example.app_1.0.0.apk
   com.example.app_2.0.0.xapk

自动处理：

• 自动关闭设备的安装验证
• 普通 .apk 使用 pm install -r -d 安装
• .xapk / .apks 使用 Split APK 会话安装

5. 安装线上工具包到设备

将通用工具包（zzCommonUtil）安装到设备并解压。

操作步骤：

1. 在主菜单中选择 4. 安装线上工具包到设备
2. 选择设备
3. 从版本列表中选择要安装的工具包版本

版本列表（部分）：

| 版本 | 文件 | |---|---| | v1.2.0-release | zzCommonUtil-v1.2.0-release.zip | | v1.1.9-snapshots | zzCommonUtil-v1.1.9-snapshots.zip | | ... | ... |

自动完成： 下载 → 推送设备 → 解压

6. 安装线上 SO 文件到设备

将 SO 动态库安装到指定应用的私有目录中，用于注入或替换原生库。

操作步骤：

1. 输入包名搜索 FTP 上的 SO 文件
2. 从搜索结果中选择要安装的文件
3. 程序自动完成：下载 → 推送 → 解压（ZIP） → 写入 → 权限设置

自动处理流程：

1. 创建目标目录 /data/user/0/{包名}/files/
2. 获取应用用户 ID（uid）
3. 设置目录所有者（chown）
4. 复制 SO 文件到目标目录
5. 设置文件权限（chmod 771 / 777）
6. 额外处理 ZIP 包中的 .js 文件和 hdinject 工具

7. 运行 SO 文件通关

通过 Android 广播机制触发应用内的 SO 逻辑执行。

操作步骤：

1. 输入包名
2. 选择运行模式

三种模式：

| 模式 | 说明 | 广播 Action | |---|---|---| | next | 下一步 | unity.imp.next | | tips | 提示 | unity.imp.tips | | other | 自定义（输入数字参数） | unity.imp.other |

8. 拉取设备日志

从设备拉取自动化运行日志到本地。

操作步骤：

1. 选择设备
2. 自动执行拉取

路径： 设备 /data/data/com.cloudcontrol/files/logs/ → 本地当前目录

9. 推送文件到设备

将当前目录下的文件推送到设备的 /sdcard/Download/ 目录。

操作步骤：

1. 选择设备和目标文件
2. 自动推送

10. 拉取设备下载目录内容

将设备 /sdcard/Download/ 目录下的文件拉取到本地。

操作步骤：

1. 选择设备和目标文件
2. 自动拉取到当前目录

11. 打开指定包名应用

通过解析应用的 LAUNCHER Activity 来启动指定应用。

操作步骤：

1. 输入要打开的包名
2. 程序自动解析 dumpsys package 输出，找到启动 Activity
3. 通过 am start 命令启动应用

技术细节：

程序会解析 dumpsys package {包名} 输出中的 Non-Data Actions: 区域，查找同时声明了 android.intent.action.MAIN 和 android.intent.category.LAUNCHER 的 Activity。

12. 关闭指定包名应用

通过 am force-stop 强制关闭指定应用。

操作步骤：

1. 输入要关闭的包名
2. 程序执行 am force-stop {包名}

13. 清空指定包名应用数据

通过 pm clear 清除指定应用的全部用户数据。

操作步骤：

1. 输入要清除数据的包名
2. 程序执行 pm clear {包名}

注意： 此操作会清除应用的所有本地数据，包括登录状态、缓存等，不可恢复。

14. 获取测试代理 IP

从代理服务获取 SOCKS5 代理信息，用于测试环境。

输出示例：

国家： US
代理地址： 123.45.67.89
代理端口： 1080
用户名： proxy_user_001
密码： xxxxxxxx
代理类型： socks5

15. 设置任务信息

管理设备上的自动化任务配置，通过生成 XML 配置文件实现。

设置任务信息：

1. 输入任务 ID
2. 程序从 API 获取任务脚本配置
3. 生成 XML 配置文件并推送到设备
4. 自动设置文件权限并关闭目标应用

清空任务信息：

1. 选择清空操作
2. 程序生成空配置并推送到设备覆盖

输入缓存

程序会自动记住你上一次输入的值，下次使用相同功能时自动填入作为默认值。

• 缓存保存在项目目录下的 .gf-cli-package-cache.json 文件中
• 所有功能共享同一份缓存（如输入过 packageName，在所有需要包名的功能中都会自动填入）
• 缓存文件已加入 .gitignore，不会被提交到仓库
• 清除缓存只需删除该文件

支持缓存的字段：

| 字段 | 涉及的功能 | |---|---| | packageName | 功能 1-6、11-13 | | localApkPath | 功能 4（安装本地应用） | | customMode | 功能 7（other 模式） | | taskId | 功能 15（设置任务信息） | | mainFile | 功能 3（生成 project.json） |

自动更新

每次启动程序时，会自动检查 npm 上 gf-cli-package 的最新版本：

发现新版本更新：当前版本 1.0.0 低于 1.0.1
是否立即升级到最新版本？ (Y/n)

• 选择 是：自动执行 npm install -g gf-cli-package@latest
• 选择 否：跳过更新，继续使用当前版本

常见问题

Q: 运行 gf 提示命令不存在

# 确保已全局安装
npm install -g gf-cli-package

# 或使用 npx
npx gf-cli-package

Q: 列表中没有已连接的设备

# 确认 ADB 能识别设备
adb devices

# 尝试网络连接设备
adb connect 设备IP地址:5555

Q: 包名格式校验规则

包名必须满足：

• 至少两段，用 . 分隔（如 com.example.app）
• 每段以字母开头
• 只能包含字母、数字、下划线

Q: 安装应用时提示验证错误

程序会自动关闭 Android 安装验证，但如果设备策略限制严格，可手动执行：

adb shell settings put global verifier_verify_adb_installs 0
adb shell settings put global package_verifier_enable 0