Android RPA（uiautomator2 版）

PC 端 Python 脚本通过 adb 控制安卓手机，自动执行 BOSS直聘打招呼、微信发消息 等 RPA 任务。

快速接入你自己的手机

本项目零硬编码：adb 路径自动发现、设备序列号自动识别、坐标全部按屏幕比例计算， clone 后只需三步：

1. 一键环境自检/安装

   git clone <this-repo> && cd android-rpa
   python bootstrap.py --install   # 自动创建 .venv + 装依赖 + 找 adb + 检测手机

   脚本会逐项检查 Python 版本、依赖、adb、设备连接，缺什么提示什么。 也可以手动来（效果等价）：

   python -m venv .venv
   .venv\Scripts\activate        # Windows；macOS/Linux 用 source .venv/bin/activate
   pip install -r requirements.txt
   # 手机开启「开发者选项 -> USB 调试」插线后，验证：
   adb devices                    # 需要 adb 在 PATH；或设环境变量 ANDROID_RPA_ADB 指向 adb.exe
   python -m uiautomator2 init    # 向手机安装控制端组件（免 root，见下节）

2. 按需改 config.py（全部可留空/用默认值）

   配置	默认	说明
   ADB_PATH	自动发现	环境变量 ANDROID_RPA_ADB 可覆盖
   DEVICE_SERIAL	空=自动	多台设备时填序列号，或用 ANDROID_RPA_SERIAL
   WIFI_DEVICES	空	无线 adb 设备列表，如 ["192.168.1.100:5555"]，见下
   PACKAGES	已填常用 App	换目标 App 改这里
   BOSS.greetings	通用示例	建议在 BOSS App 内设置「自动打招呼语」，脚本直接复用
   WECHAT.targets	空	{联系人备注: 消息}
   RATE	已调好	频率/分神概率/单轮上限

3. 先 dry-run 再 --live

   python main.py --task boss     # 只找控件不点击，验证选择器
   python main.py --task boss --live

多设备 / adb 不在 PATH：复制 config_local.example.py 为 config_local.py 填入 ADB_PATH / DEVICE_SERIAL（该文件被 git 忽略，不会提交）；或用环境变量 ANDROID_RPA_ADB / ANDROID_RPA_SERIAL。

无线 adb（免插线）：手机与电脑连同一 Wi-Fi，两种方式任选：

• Android 11+「开发者选项 -> 无线调试」：端口随机，先在电脑上 adb pair IP:配对端口 配对 （配对码在手机无线调试页面），之后把「IP:端口」填入 WIFI_DEVICES；

• 任意 Android 版本：插一次 USB 执行 adb tcpip 5555 后拔线，填 手机IP 即可 （重启手机后失效，需重新执行）。

环境变量方式：ANDROID_RPA_WIFI="192.168.1.100:5555,192.168.1.101"（逗号分隔，端口可省略默认 5555）。 任务启动时会自动 adb connect 列表里的设备，连接失败不影响 USB 设备。

Related MCP server: phone-mcp-server

手机端装了什么 & 如何卸载

uiautomator2 init 会向手机安装两个组件（免 root，uiautomator2 v3.x 方案）：

不用了？一键清干净：

adb uninstall com.github.uiautomator
adb shell rm /data/local/tmp/u2.jar

老教程里的 atx-agent（Go 常驻代理）是 uiautomator2 v2.x 的机制，v3 已移除，本项目不依赖。

实时屏幕预览 / 投屏

两种方式按需选：

浏览器预览：纯 Python + adb，启动后打开 http://127.0.0.1:8766， 只读不写、不干扰 RPA 任务；浏览器关掉页面采集自动停止。磁盘占用为 0（帧在内存里流转）。 常用参数：--port 9001 换端口、--fps 5 提高刷新率、--serial xxx 指定设备。

scrcpy 投屏：--mirror 会自动找 scrcpy 并拉起独立投屏窗口（60fps、可直接鼠标操作手机）， 找不到时会打印下载地址和配置方法。安装任选其一：

1. 从 scrcpy releases 下载 zip， 解压到 %LOCALAPPDATA%\scrcpy\（自动识别）

2. 或解压到任意位置后设置环境变量 ANDROID_RPA_SCRCPY 指向 scrcpy.exe

3. 或把 scrcpy.exe 所在目录加入 PATH

scrcpy 是独立软件，不装它只用浏览器预览即可，不影响本项目其他功能。 无线设备同样支持：adb connect 手机IP:端口 后，--serial 手机IP:端口。

MCP：让 Agent 直接看屏 + 操作手机

本项目内置 stdio MCP Server（mcp_server.py），任何支持 MCP 的客户端 （WorkBuddy / Claude Code / Cursor 等）都能让 Agent 直接控制手机。 在其他客户端注册只需一段 JSON（路径换成你的项目位置）：

{
  "mcpServers": {
    "android-rpa": {
      "command": "/path/to/android-rpa/.venv/Scripts/python.exe",
      "args": ["/path/to/android-rpa/mcp_server.py"]
    }
  }
}

（Windows 下 command 形如 E:/android-rpa/.venv/Scripts/python.exe）

提供的工具：

典型用法：直接对 Agent 说「帮我看看手机现在什么页面」「帮我在微信里给 XX 发条消息」， Agent 会 截图 → 看内容 → 点坐标/文本 → 再截图验证，形成感知-操作闭环。

目录结构

android-rpa/
├── bootstrap.py         # 一键环境自检/安装（clone 后先跑这个）
├── main.py              # 入口
├── config.py            # 包名 / 话术 / 频率控制 / 联系人列表（唯一需要按需修改的文件）
├── config_local.example.py  # 个人配置模板（复制为 config_local.py 使用，git 忽略）
├── mcp_server.py        # MCP Server：让 Agent 实时看屏 + 操作手机
├── stop_agent.bat/.sh   # 【双击/运行】人为打断一切任务
├── resume_agent.bat/.sh # 【双击/运行】清除打断，恢复运行
├── core/
│   ├── device.py        # adb 检测 + u2 连接
│   ├── control.py       # 人为打断开关（INTERRUPT 文件）
└── actions.py       # Robot：人味延迟、查找、点击/长按/双击、滑动/手势/拖拽、输入、截图、操作预算
├── apps/
│   ├── boss_zhipin.py   # BOSS直聘自动打招呼
│   └── wechat.py        # 微信自动发消息
└── logs/                # 运行日志 + 异常截图（git 忽略）

人为打断（随时急停）

• Windows：双击 stop_agent.bat 急停，双击 resume_agent.bat 恢复

• macOS/Linux：./stop_agent.sh / ./resume_agent.sh（或手动 touch INTERRUPT / rm INTERRUPT）

• 正在跑的批量任务会在下一步（点击前 / 延迟中）立即停止；MCP 的所有写操作 （点击/滑动/输入）会被拒绝。

• 截图/读文本等只读操作不受打断影响，急停后仍可查看手机状态。

运行

# 1. 先空跑：只找控件不点击，验证选择器是否匹配当前 App 版本
python main.py --task boss
python main.py --task wechat

# 2. 确认日志无 [X]/未找到 后，真实执行
python main.py --task boss --live
python main.py --task wechat --live

核心设计

• dry-run 优先：默认只定位控件不操作，日志能看到每一步找到什么，避免盲点误触。

• 风控三板斧（config.RATE）：

  • 每次点击后随机延迟 3–8 秒，另有 18% 概率「分神」停顿 8–18 秒（像人）

  • 单次会话最多 150 个操作，超了主动停

  • 选择器用文本/描述而非控件 id，App 更新不易失效

• 异常留痕：找不到预期控件时自动截图到 logs/，方便对照修正。

• 跨设备适配：坐标按屏幕比例计算，控件找不到时有多级兜底（文本 → 描述 → 已知 id → 相对坐标）。

手势能力（Robot 通用原语）

core/actions.py 的 Robot 封装了与具体 App 无关的操作原语，扩展新任务直接复用：

所有手势都受 dry-run、操作预算与人为打断保护。底层为 uiautomator2 单指手势； 多指/画布类界面需图像识别方案，不在当前范围内。

加一个新 App 任务：config.py 的 PACKAGES 加一行 "别名": "包名"， 再在 apps/ 下参照 boss_zhipin.py 写一个 run(r) 流程模块、在 main.py 挂上即可。

元素定位调试

App 控件 id/hint 文字随版本会变。用 weditor 在浏览器里实时看控件树：

pip install weditor
python -m weditor    # 打开 http://localhost:17310

选中控件后把它的 text / resource-id / description 更新到对应 apps/*.py 的 find(...) 里即可。

风险提醒

• BOSS直聘 / 微信都有自动化行为检测：保持低频、用小号先试、话术别群发同一句。

• 账号被限制的代价远大于省下的时间，--live 模式务必从小批量开始。

学AI，上L站