ATX-Agent 是一个用 Go 语言编写、运行在 Android 设备后台的二进制程序，负责屏蔽不同 Android 设备的差异，并为上层框架（如 openatx/uiautomator2）提供统一的 HTTP 接口。

核心目标

  • 统一接口：对外暴露 /screenshot、/dump/hierarchy、/info、/install 等 RESTful API。
  • 差异屏蔽：根据设备能力自动选择最优方案（minicap、uiautomator 截图、screencap）。

架构与原理

  1. 多方案截图
  • Minicap：最快速的截图方案，优先使用。
  • UiAutomator2 API：在 Minicap 不可用时调用。
  • Screencap：模拟器场景下使用，需要根据屏幕旋转调整方向。
  1. Instrumentation 服务
  • 通过 am instrument -w ... 启动 Android Instrumentation，让设备运行自动化测试服务。
  1. HTTP/JSON RPC
  • 内置轻量级 HTTP 服务器（NanoHTTPD）监听默认端口 7912，接收各种控制与查询请求。

开发与编译

  • 语言：Go
  • 源码：https://github.com/openatx/atx-agent
  • 开发说明：详见 DEVELOP.md，需要具备 Go 语言基础。
  • 模块代理：可设置 GOPROXY 来加速依赖下载。

编译示例：

GOOS=linux GOARCH=arm64 go build -o atx-agent

（根据设备架构调整 GOARCH）

安装与启动

  1. 下载二进制包 从 Releases 页面下载以 linux_armv7.tar.gz 结尾的包，绝大多数手机为 armv7 架构。
  1. 部署到设备
   adb push atx-agent /data/local/tmp/
   adb shell chmod 755 /data/local/tmp/atx-agent
  1. 后台启动
   adb shell /data/local/tmp/atx-agent server -d
  • 若已运行，可 --stop 后重新启动。
  • 默认监听：http://<DEVICE_IP>:7912

常用 HTTP 接口

假设设备地址为 $DEVICE_URL，如 http://10.0.0.1:7912

设备与版本信息

  • 版本： GET /version
  • 设备信息： GET /info
  {"udid":"...","brand":"...","model":"...","agentVersion":"..."}

界面结构与截图

  • 截图： GET /screenshot
  • UI 树： GET /dump/hierarchy
  • 自动重启 uiautomator 服务，若失败会等待并返回。
  • 停止 uiautomator： DELETE /uiautomator

应用管理

  • 安装 APK： POST /install（url 参数）
  • 安装进度： GET /install/{id}
  • 卸载、图标、信息： GET /packages/{packageName}/info|/icon

进程与系统信息

  • 运行进程： GET /proc/list
  • 内存与 CPU：
  • GET /proc/{pkg}/meminfo
  • GET /proc/{pkg}/cpuinfo

文件操作

  • 上传： POST /upload/{path}
  • 下载： GET /raw/{path}
  • 目录信息： GET /finfo/{path}
  • 离线下载： POST /download（返回任务ID），GET /download/{id} 查询

Shell 与远程命令

  • 执行命令： POST /shell
  • 后台执行： POST /shell/background

其他功能

  • Webview 列表： GET /webviews
  • NewCommandTimeout： POST /newCommandTimeout
  • 升级 agent： GET /upgrade?version={x}（或不指定下载最新版）
  • Minicap/Minitouch 修复： PUT /minicap / PUT /minitouch

常见场景与注意事项

  • 性能：截屏与 dump 操作耗时，建议预热服务并复用。
  • 权限：操作文件、Shell 需确保设备已开启 USB 调试。
  • 兼容性：模拟器与真机差异大，screencap 仅在模拟器场景。
  • 安全性：HTTP 无认证，建议仅限局域网环境使用。

资源链接