如何快速上手 atx-agent：Android 设备统一接口服务的终极指南 🚀

atx-agent 是一款强大的 Android 设备 HTTP 服务器工具，专为屏蔽不同安卓设备差异、提供统一接口给 openatx/uiautomator2 使用而设计。通过自动化处理截图、文件传输、应用管理等复杂操作，帮助开发者和测试人员轻松实现 Android 设备远程控制与管理。

📋 项目核心功能与优势

atx-agent 作为轻量级后台服务，解决了 Android 设备碎片化带来的兼容性难题。其核心优势包括：

• 统一接口抽象：自动适配不同设备的硬件差异，提供标准化 HTTP 接口
• 高效截图机制：智能选择 minicap/uiautomator/screencap 三种方式，兼顾速度与兼容性
• 全功能设备管理：支持应用安装、文件传输、进程监控、WebView 调试等 20+ 实用功能
• 后台稳定运行：采用守护进程模式，支持自动重启与状态恢复

🔍 项目目录结构解析

atx-agent/
├── assets/            # 静态资源目录（网页控制台相关）
├── cmdctrl/           # 命令控制逻辑模块
├── jsonrpc/           # JSON-RPC 通信协议实现
├── logger/            # 日志处理组件
├── pubsub/            # 发布订阅模式实现
├── subcmd/            # 子命令处理模块
├── main.go            # 应用入口文件
└── README.md          # 官方文档与快速入门指南

关键文件功能说明：

• main.go：程序启动入口，负责服务器初始化与端口监听（默认 7912 端口）
• httpserver.go：HTTP 服务核心实现，定义所有 API 路由
• screenshot.go：多策略截图功能实现，处理设备兼容性逻辑
• minitouch.go：触摸事件模拟模块，支持多点触控操作

🚀 三步快速安装指南

1️⃣ 获取项目源码

git clone https://gitcode.com/gh_mirrors/at/atx-agent
cd atx-agent

2️⃣ 编译二进制文件（可选）

如需自定义功能，可修改源码后重新编译：

# 确保已安装 Go 环境（1.13+）
go mod tidy
GOOS=linux GOARCH=arm go build -o atx-agent

3️⃣ 部署到 Android 设备

# 推送二进制文件到设备
adb push atx-agent /data/local/tmp

# 添加执行权限
adb shell chmod 755 /data/local/tmp/atx-agent

# 启动守护进程模式
adb shell /data/local/tmp/atx-agent server -d --stop

✨ 提示：--stop 参数确保先停止已有实例，避免端口冲突。服务默认监听 7912 端口，可通过 -p 参数自定义端口号。

🔑 常用接口实战示例

📸 快速获取设备截图

# 基础截图（自动选择最佳方式）
curl http://设备IP:7912/screenshot > screenshot.jpg

# 指定使用 uiautomator 截图（适用于部分模拟器）
curl "http://设备IP:7912/screenshot/0?minicap=false" > uiauto_screenshot.jpg

📱 应用安装与管理

# 远程安装 APK（支持 HTTP/HTTPS 链接）
curl -X POST -d url="http://example.com/app.apk" http://设备IP:7912/install

# 查询安装进度（返回安装ID后使用）
curl http://设备IP:7912/install/1

# 获取已安装应用列表
curl http://设备IP:7912/packages

💻 后台 Shell 命令执行

# 执行普通命令
curl -X POST -d command="ps | grep com.android" http://设备IP:7912/shell

# 后台运行长时间任务（不会被终端断开影响）
curl -X POST -d command="nohup logcat > /sdcard/log.txt &" http://设备IP:7912/shell/background

📊 设备性能监控

获取应用内存使用情况：

curl http://设备IP:7912/proc/com.netease.cloudmusic/meminfo

返回结果示例：

{
  "code": 17236,
  "graphics": 20740,
  "java heap": 22288,
  "native heap": 20576,
  "total": 202445  // 总PSS内存（KB）
}

🎮 高级功能：多点触控模拟

通过 WebSocket 接口实现复杂触摸操作：

// 触摸事件序列示例（点击并滑动）
{"operation": "d", "index": 0, "xP": 0.2, "yP": 0.5, "pressure": 50}
{"operation": "c"}  // 提交事件
{"operation": "m", "index": 0, "xP": 0.8, "yP": 0.5, "pressure": 50}
{"operation": "c"}
{"operation": "u", "index": 0}
{"operation": "c"}

⚠️ 注意：坐标采用百分比形式（0.0-1.0），原点为设备左上角，需自行处理屏幕旋转问题。

📝 常见问题解决

🔌 服务启动失败怎么办？

1. 检查端口占用情况：

adb shell netstat -tulpn | grep 7912

2. 查看详细日志定位问题：

adb shell cat /sdcard/atx-agent.log

3. 强制重启服务：

adb shell /data/local/tmp/atx-agent server -d --stop

📡 设备连接超时排查

• 确保手机与电脑在同一局域网
• 关闭 Android 设备防火墙：adb shell settings put global http_proxy :0
• 尝试重启 ADB 端口转发：adb reverse tcp:7912 tcp:7912

📚 扩展学习资源

• 官方文档：DEVELOP.md - 开发者指南与贡献说明
• API 参考：完整接口文档可通过访问 http://设备IP:7912/help 获取
• 相关项目：openatx/uiautomator2 - 自动化测试框架

🔄 版本更新与维护

atx-agent 采用滚动更新策略，建议定期检查新版本：

# 查看当前版本
curl http://设备IP:7912/version

# 手动更新（需重新推送二进制文件）
adb push new-atx-agent /data/local/tmp/atx-agent
adb shell /data/local/tmp/atx-agent server -d --stop

---

atx-agent 凭借其轻量级设计与强大兼容性，已成为 Android 自动化测试与远程控制领域的重要工具。无论是移动应用开发者、测试工程师还是 Android 爱好者，都能通过这套工具链显著提升设备管理效率。立即尝试，开启你的 Android 设备智能管理之旅吧！ 📱💻