开源项目让AI直控iPhone：phone-harness技术原理解析
最近在GitHub上出现了一个引人注目的开源项目phone-harness，它实现了一个让AI Agent直接操控真实iPhone的方案，目前已经获得了2.3K的Star。这个项目最大的亮点在于：无需越狱、无需安装WebDriverAgent，甚至不需要复杂的配置，就能让Claude、Codex这类Agent操作你手中的iPhone。
从模拟器到真实设备
在phone-harness出现之前，如果想让AI Agent操作手机，通常需要借助模拟器、ADB调试桥或专门的自动化框架。以iOS平台为例，开发者往往需要配置Xcode、安装WebDriverAgent、处理签名问题、设置开发者选项等，这一套流程下来，光环境配置就足以让很多人望而却步。
phone-harness则另辟蹊径，它并没有直接去控制iOS系统，而是巧妙地利用了苹果官方提供的iPhone Mirroring功能。简单来说，就是通过控制Mac上的iPhone镜像窗口来实现对真机的操作。
核心技术原理：三步走通控制链路
整个技术方案可以概括为三个核心步骤：看屏幕、找位置、点下去。
截图与OCR识别
phone-harness首先会截取Mac上iPhone镜像窗口的画面，然后利用苹果原生的Vision Framework进行OCR处理。这个过程不仅仅是把文字识别出来，更重要的是能够返回文字在屏幕上的精确坐标。
举个例子，当屏幕上出现「天气」「地图」「照片」「备忘录」这些文字时，OCR模块不仅能识别出这些文字内容，还能告诉系统这些文字具体出现在屏幕的哪个位置。这样一来，Agent在看到「地图」这个指令后，就能够准确地知道应该点击屏幕上的哪个坐标。
CGEvents模拟输入
找到坐标之后，下一步就是执行操作。phone-harness使用macOS的CGEvents来模拟各种输入事件，包括点击、长按、滑动、滚动以及文字输入等，并将这些操作精确地发送到iPhone镜像窗口中。
基于这套能力，项目封装了一系列实用的操作方法：
home()- 返回桌面open_app("Notes")- 打开指定应用tap_text("New Note")- 定位并点击屏幕上包含特定文字的元素type_text("hello")- 输入文本内容
从Agent的角度来看，它不需要了解底层是如何控制iPhone的，只需要调用这些封装好的接口即可。
操作后重新确认
这里有一个非常关键的设计细节。网页自动化可以通过读取DOM来获取按钮、输入框等元素的实时状态，但iPhone镜像并没有提供类似的接口。phone-harness的解决方案是：操作完成后，再次「看」一下屏幕。
比如说，Agent要让系统打开天气应用。它首先通过OCR找到天气图标的坐标，然后点击对应位置，等待页面稳定加载，最后再次截图进行OCR识别，确认天气页面是否真的已经打开。
整个流程可以概括为：识别 → 操作 → 再识别 → 确认结果。Agent所看到的屏幕画面就是最终的判断依据，而不是依赖任何系统接口的反馈。
视觉模型处理无文字图标
OCR技术非常适合处理带有文字标签的按钮，但实际使用中，手机界面上还存在大量没有任何文字说明的图标。针对这种情况，phone-harness也给出了解决方案。
Agent可以直接截取屏幕截图，然后调用视觉模型来判断图标的位置和含义，再据此计算出点击坐标进行操作。因此，phone-harness实际上拥有两只「眼睛」：
- 有文字的地方：优先使用OCR，速度快、坐标精确
- 无文字的地方：使用视觉模型分析截图
虽然这种方案不如DOM那样精确，但已经能够覆盖大多数真实的手机操作场景。
Agent自扩展能力
phone-harness还有一个颇具特色的设计——agent-workspace。这个目录下的agent_helpers.py文件定义了截图、OCR、点击等基础能力，这部分保持相对稳定。
但对于任务所需的额外能力，Agent可以自己写入到agent_helpers.py中。这意味着当遇到重复性操作时，不需要每次都重新规划执行路径，Agent可以直接为自己添加一个新的helper函数，下次直接调用即可。
这种「底层提供手和脚，Agent根据任务给自身补充工具」的设计理念，让phone-harness与普通的手机自动点击脚本有着本质的区别。
安装与配置
项目的安装过程也经过了精心设计。用户可以直接将一段Setup Prompt发送给Codex或Claude，让Agent自动完成以下步骤：克隆项目代码、读取install.md文档、安装依赖项、注册为phone-harness Skill。
整个安装过程中，真正需要用户手动操作的主要有两件事：
- 首次使用时要将iPhone和Mac进行iPhone Mirroring配对
- 为终端应用开启Accessibility和Screen Recording权限
安装完成后，运行phone-harness --doctor命令即可检查整条控制链路是否正常工作。
现存局限性
作为一个轻量级的实验项目，phone-harness目前还存在一些明显的限制：
- 单设备控制：一次只能控制一台iPhone
- 解锁状态要求：实体iPhone解锁后，镜像功能会暂停
- 无多点触控：不支持双指缩放等需要多点触控的操作
- 功能限制：相机、Face ID验证流程存在限制，DRM版权视频会直接显示为黑屏
- 语义理解不足：OCR只能识别文字本身，无法理解没有标签的图标代表什么功能
轻量化设计带来的启示
phone-harness最有价值的地方，并不在于它又做了一套手机自动化框架，恰恰相反，它的方案非常轻量。
项目没有从零开始构建复杂的控制体系，而是充分利用苹果官方提供的iPhone Mirroring能力，将Mac变成了AI Agent与真实iPhone之间的桥梁。Agent通过截图和OCR来感知屏幕，通过CGEvents来执行操作，通过重新截图来确认结果。这套链路的每个环节都很容易理解，也为类似场景提供了可复用的设计思路。
更重要的是，这种「借助现有能力、快速搭建原型」的开发思路，对于端侧Agent的发展具有重要的参考价值。