搜索你想找的开源项目

输入名称、用途或关键词,也可粘贴 GitHub 仓库链接

分享到微信

当前解读页的微信分享二维码

用微信扫一扫打开,点击右上角「···」分享给朋友或朋友圈。

手机上可截屏后,在微信扫一扫中从相册识别二维码。

hridaya423/phonedriver

AI 工程

让 AI 代理通过 MCP 和命令行读取并操控 Android 手机与 iPhone 屏幕,付款类操作前先向人确认。

150
16
Rust
AGPL-3.0
创建于 10 天前

项目介绍

phonedriver 是一个基于 stdio 的标准 MCP 服务器,同时提供功能相同的命令行工具,把 Android 手机、Android 模拟器、iOS 模拟器或真机 iPhone/iPad 交给 AI 代理操作。代理看到的每个界面都是一份简短的编号文本列表,按编号点击元素,因此不用解析图片,也不用轮询等待界面加载。本机常驻一个守护进程保持设备连接,并记住 @e 编号对应哪个元素,列表滚动后点击依然落在正确位置。

它面向只有手机才能完成的任务:在真实网站上点单、走一遍 App 的注册/引导流程、或带代理找出注册流程里的缺陷。已适配 Claude Code、Codex、Cursor、VS Code 等 MCP 客户端。

快速使用

把 MCP 服务器注册到 Claude Code:

claude mcp add phonedriver -- npx -y phonedriver mcp

也可以改用 Homebrew 安装二进制,或安装同时带服务器和 skill 的插件;两种方式只选一种,否则工具会重复列出。Cursor 和 VS Code 在 README 中有了一键安装入口。

给代理派活之前,先启动 Android 模拟器、插好开启了 USB 调试的 Android 手机,或启动 iOS 模拟器。再运行 phonedriver doctor 检查 adb、Xcode 和已连接设备,按提示修复问题。设备就绪后,直接用自然语言给代理下达一个手机任务。

首次运行会自动下载一份对应平台(macOS、Linux 或 Windows)的二进制并缓存。Shell / PowerShell 安装脚本、真机 iPhone 配置和各客户端接入方式见安装指南与参考文档。

读取界面

命令行打印的界面是紧凑文本:

$ phonedriver snapshot
app com.android.settings (Settings) · keyboard hidden · settled in 0ms
@e1 button "Search Settings"
@e2 group scrollable↓
  @e3 button "Google" "Services & preferences"

点击之后只返回变化部分:+ 表示新增,- 表示消失,~ 表示内容改变。只有模型需要看图时才截图。

付款前确认

当点击落在 Pay、Buy now、Buy with GPay、Place order、Start subscription、Transfer 或 Delete account 这类按钮上时,phonedriver 会暂缓这次点击,并在客户端自己的提示框中询问真人。模型看不到这个问题,也无法代答;你可以选择允许、本次会话允许或拒绝。

通过 PHONEDRIVER_ASK 可以把检查扩展到 send、delete、install 类按钮。若要让代理无人值守运行,可在代理指令中传 autonomous: true,或设置 PHONEDRIVER_GUARD=off 关闭检查。按钮文案识别覆盖英语、西班牙语、葡萄牙语、法语、德语、意大利语、荷兰语、日语、简体中文、韩语和印地语,但识别不了纯图标的付款按钮和其他语言的标签。

运行要求与限制

Android 路径需要 adb,真机还需开启 USB 调试。iOS 模拟器需要装有 Xcode 的 Mac;真机 iPhone/iPad 在此基础上还需要 Apple 开发证书,并运行 phonedriver ios setup。Android 侧无需安装 App,连接时通过 adb 推送辅助程序;iOS 侧则在 Mac 上构建一个 XCTest runner。

完成配置后可以拔线:iPhone 用 phonedriver ios wifi on,Android 用 phonedriver pair 或 phonedriver untether。Android 13 及以上可以通过 --display hidden 或 PHONEDRIVER_DISPLAY=hidden 让代理在隐藏的第二屏幕上工作。

代理能做的事和你用手指能做的一样多,但它无法输入锁屏密码,也无法通过 Face ID / 指纹验证,锁屏时命令会直接停止并提示设备已锁定。禁止截屏的 App(如部分银行应用)截出来是黑屏,但文字仍可读取。MCP 共 14 个工具(devices、apps、snapshot、screenshot、tap、type、swipe、scroll、press、launch、wait、batch、clipboard、shell),其中三个标记为只读。终端使用过的设备闲置 30 秒后会交给代理。许可证为 AGPL-3.0-only,将修改版本作为网络服务提供需公开改动;二进制内的 OpenH264 由源码构建,不附带 H.264 专利许可。

HotRepo 点评

README 记录了 2026 年 11 月 10 日作者自测的一组对比:在同一个 Android 模拟器和 Claude Sonnet 5.5 下跑九个手机任务,phonedriver 27/27 通过,用 658 千 token、5.1 分钟;mobile-mcp 为 18 次中通过 17 次、4.6 百万 token;phone-harness 为 18 次中通过 14 次、1.1 百万 token。这是作者自己的测试集和硬件,每次运行、版本和校验方式都公布在基准记录里。另一组速度测试在 Android 17 模拟器上取 50 次中位数,读屏 13 ms,对比 adb shell uiautomator dump 的 2,164 ms,方法和原始数据见测速记录。

本站的 Star 采样显示,截至 2026-11-15 的 24 小时内星数从 100 缓慢升到 125,未记录到 GitHub 全语言日榜名次。真正需要读者判断的是安全模型:付款前确认是一个有用的默认值,但它识别的是按钮文案而非交易状态,所以当代理被允许接近结账流程时,语言覆盖范围和纯图标按钮的缺口就变得很关键。

本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。

相关推荐

  1. phone-harness/mcp这是一个托管 MCP 服务,让 AI 智能体在云端操控真实 iPhone 和 Android 模拟器。Python812
  2. callstack/agent-device面向 AI 编程 Agent 的设备控制层,提供 CLI、MCP 服务和 Node.js API,用于在模拟器、真机及云设备上检查、操作和验证移动端、电视、Web 与桌面应用。TypeScript5,368
  3. JosssphZhou/poki让 Claude Code、Codex 等 MCP 客户端通过 Mac 操控真实 iPhone,无需越狱或额外硬件。JavaScript109
  4. ZSeven-W/dsh-ios为编程 Agent 提供 22 个工具,在会话内启动、构建并操控 iOS 模拟器或 USB 真机,带可点拖的实时侧栏。TypeScript469
  5. ZSeven-W/dsh-android把 Android 模拟器或 USB 手机实时串流进对话,并通过 adb 驱动它完成构建、安装与 UI 操作。TypeScript355