AB
AiBoss站
project

phonedriver - 让 AI 智能体直接操作真机或模拟器的手机控制层

phonedriver 是一个让 AI 智能体操作 Android 与 iOS 手机(真机或模拟器)的开源项目:它把屏幕读成带编号的元素列表,智能体按编号点击,并只返回变化部分。项目以 MCP 服务器和命令行两种方式接入 Claude Code、Codex、Cursor 等客户端,采用 AGPL-3.0 许可。

phonedriver 是一个给 AI 智能体「配一部手机」的开源项目。按项目自述,它让智能体获得对 Android 手机或 iPhone(真机或虚拟设备)的控制权:读取屏幕、点击按钮、报告屏幕发生了什么变化,并在执行支付这类敏感操作前先向人确认。它面向的使用场景很具体——让智能体去测试注册表单、翻到藏在三层菜单深处的某个设置、找出应用在哪一步开始出错,或者跑一遍只有手机才能完成的任务。接入方式有两种:作为 MCP 服务器配合 Claude Code、Codex、Cursor 等客户端使用,或直接从命令行调用。

维护者与状态

项目由 hridaya423 维护,仓库创建于 2026-11-08,最后一次提交在 2026-11-21,属于非常年轻的项目。最新正式版本为 v0.1.6,发布于 2026-11-20。截至 2026-11-21,仓库获得 335 个星标。项目另有一个官网用于承载文档与说明。

从时间线看,创建到最新版本之间只有十余天,版本号仍停留在 0.1.x,接口与行为存在变动的可能性较高,采用前应留意版本差异。

主要能力

以下能力均来自项目自述(README),未经独立验证。

  • 结构化的屏幕表示:每个屏幕以简短的编号列表返回,例如 @e10 button "Display & touch",模型按编号点击,无需理解像素坐标。
  • 只回传变化:一次点击后,回复只列出新增(+)、消失(-)和改变(~)的行,减少上下文消耗。项目称其会在屏幕停止变化后才返回,模型不必轮询或猜测加载时间。
  • 按需截图:只有在确实需要看图像时才截图。
  • 录制与回放:可把一次成功的智能体会话保存为步骤文件(phonedriver save),再用 phonedriver replay 无模型重放;回放遇到第一个不匹配的步骤即停止并展示该屏。带 --screens 时会在每步后保留截图,后续回放据此比对文本差异。输入过的密钥以环境变量名(如 PHONEDRIVER_SECRET_1)保存而非明文,便于在 CI 中重放登录流程。
  • 屏幕录制:在 Android 与 iOS 模拟器上录制 MP4,并附带带时间点的操作列表。
  • 可访问性检查:用文字描述两张截图之间的差异,并列出屏幕阅读器无法命名的控件与过小的点击目标。
  • 崩溃信息:在 Android 上,若某次操作期间应用崩溃,回复中会带上异常与抛出位置,logs 可打印应用最后的日志行。
  • 整页读取:snapshot 配合 page: true 可通过浏览器自身的调试接口一次性读取 Chrome 或调试版 WebView 中的整页文本。
  • 像素级兜底:对没有元素列表的界面(关闭可访问性的 WebView、Flutter 或游戏画布),在 macOS 与 Windows 上借助系统自带文字识别、在 Linux 上借助已安装的 Tesseract 从像素中取字,识别出的文本可按名称点击。
  • 其他:press fingerprint 可触发 Android 模拟器的指纹传感器;在 Android 17 上,setting 可按 key 一次调用修改系统设置。

项目自述还提到,其实现方式是在 Android 上通过 adb 在手机端启动一个 Java 辅助进程,经 UiAutomation 读取可访问性树并以 H.264 视频流判断屏幕是否稳定;iOS 上由 XCTest runner 承担同样职责;电脑端有一个守护进程维持连接并记住 @e 编号与元素的对应关系,MCP 服务器与 CLI 都是该守护进程的轻客户端。

使用入口

仓库地址:hridaya423/phonedriver;官网与文档:phonedriver.dev。

据项目说明,最简初始化命令为:

npx -y phonedriver init

该命令会把 phonedriver 写入它在本机找到的智能体客户端(Claude Code、Codex、Cursor、VS Code、Gemini CLI),随后检查 adb、Xcode 与设备状态并提示需要修复的项;--dry-run 可预览将要执行的动作。也可以手动注册为 MCP 服务器:

claude mcp add phonedriver -- npx -y phonedriver mcp

项目还提供插件形式(Claude Code、Codex、Cursor),并说明插件与 MCP 手动配置二选一,否则工具会被重复列出。连接多台设备时,可通过环境变量 PHONEDRIVER_DEVICE 指定目标,phonedriver devices 列出可用 id。phonedriver doctor 可随时复查环境。

许可与限制

许可证为 AGPL-3.0,使用与分发时需遵守该许可证的相应义务。

项目自述中提到的前置条件与边界包括:需要先启动 Android 模拟器或 iOS 模拟器,或插入开启 USB 调试的 Android 手机;首次运行会为当前机器(macOS、Linux 或 Windows)下载一个二进制并缓存。像素级文字识别在 Linux 上依赖已安装的 Tesseract。项目自述中的性能与 token 对比数据来自维护者自己的测试集与特定环境,属于自述内容,本文不将其作为中立结论引用。此外,项目版本仍处于 0.1.x 阶段,功能与配置方式可能随版本变化。