phone-harness 0.2：不越狱，Agent 真机操控 iPhone

它控制的是镜像窗口，不是 iOS

很多人第一反应是”这又找到一个 iOS 后门了”。没有。

phone-harness 站在 macOS 自带的 iPhone 镜像（iPhone Mirroring）上面。这个功能从 macOS Sequoia 15 开始内置，作用是把 iPhone 画面变成一个 Mac 窗口，同时接收鼠标和键盘，转成手机上的触摸。

phone-harness 干的事，就是接管这个窗口：截下来，用苹果 Vision 框架做 OCR，拿到屏幕上每条文字和它的坐标；要操作了，用 CGEvents 在 HID 层发点击、长按、滑动、滚轮和键盘事件。

所以”不用越狱、不用 Xcode”是真的，但”Agent 拿到了 iPhone 的控制权”不准确。它拿到的是 Mac 上那个窗口的控制权，另一端还是苹果官方的镜像通道。

没有 DOM，那就每次都重看一眼

网页自动化之所以稳，是因为有 DOM。按钮在不在、输入框什么状态，读一下就知道。

镜像窗口没有这些东西。它本质上是一段视频流，苹果的辅助功能树在这里是空的。README 里把 OCR 的结果叫”穷人的 DOM”。能拿到可见文字和坐标，但不知道这块文字是标题、按钮还是一段说明。

于是就有了它最核心的一条循环：看，做，再看一次。

比如让 Agent 打开天气。先截图 OCR 找到 Weather 在哪，点下去，调用 wait_stable() 等画面稳定，再截一次图确认页面真的开了。

截图就是唯一的事实来源。窗口可能被拖动，页面会滚动，旧坐标不能缓存，每次都得重新查。

对应到代码上，它把常用动作都封成了助手函数，脚本里直接就能用：

ocr() 返回可见文字和中心坐标，整套系统的眼睛。

tap_text("New Note") 按文字点，点不到时会把它当前看见的东西抛出来，方便下一步重试。

type_text("hello") 输入文本。

scroll()、swipe("up")、home()、app_switcher()、open_app("Notes") 负责导航和滚动。

wait_stable() 等连续两帧一致，动画结束再走下一步。

一段典型脚本长这样，用 heredoc 喂给命令行就行，助手函数已经预导入了：

phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in ocr()][:10])
PY

有个细节我挺喜欢。处理长列表时，它没有用”这次有没有解析出新行”来判断滚到底，而是比较前后两屏文字集合的 Jaccard 重合度，低于 0.6 才算屏幕真的动了，连续几次不动才认为到底。OCR 偶尔漏读一行，不会让整个遍历提前收工。

缺什么，Agent 自己补

agent-workspace/agent_helpers.py 是项目里比较有意思的设计。

核心代码负责截图、OCR、点击这些基础能力，保持稳定。任务需要的额外能力，Agent 可以自己写进这个文件，它每次执行都会自动注入脚本的命名空间。

也就是说，遇到重复操作，不用每次都重新规划一遍，Agent 给自己补个 helper，下次直接调。底层给手和脚，上层自己长工具。这跟一般的”手机自动点击脚本”拉开了距离。

安装基本是 Agent 自己干

作者的思路延续到底：把一段 Setup Prompt 丢给 Claude Code 或 Codex，让它自己克隆仓库、读 install.md、装依赖、注册成 skill。

真正需要你动手的主要两件事。一是第一次把 iPhone 和 Mac 的镜像配对好，二是给终端开辅助功能和屏幕录制权限。

这里有个坑值得记一下：屏幕录制权限给完之后要重启终端才生效，辅助功能是立即生效的。另外官方建议装在 ~/.phone-harness 这个固定目录，venv 里的命令只在当前 shell 有效，想全局用得自己加个软链，不然新开终端就找不到命令了。

装完跑一下：

phone-harness --doctor

它会按顺序体检：pyobjc、辅助功能、屏幕录制、镜像 App、窗口发现、截图、OCR。哪一层 FAIL 就先修哪一层，后面的检查依赖前面的。

现在不止 iPhone 了

这是原文没提到的部分。仓库到 0.2.0 之后，Android 也接进来了，走 adb 传输，USB 或 Wi-Fi 都行，不需要窗口。

两边的助手函数是一套。有意思的是，Android 那边的 ocr() 直接读手机的无障碍树，比 iPhone 这种像素级 OCR 要准。可以用 phone-harness config set platform ios|android 切默认值。

作者还做了个云托管版本，提供带真实号码和 2FA 的远程设备，那个是商业服务，跟本地开源这套是两回事。

限制得先看清楚

项目文档把这些写得挺坦白，我按自己的理解重排一遍：

一次只能控制一台手机一个会话。你把实体 iPhone 解锁，镜像立刻暂停，窗口变成”iPhone 不可用”。想恢复得手动重连并锁屏。

没有多点触控，双指缩放这类手势做不了。相机、Face ID 流程走不通。受 DRM 保护的视频在镜像里直接是黑屏。

OCR 只认文字，不认语义。一个没有标签的图标，它不知道那代表什么，得截图交给视觉模型判断。

后台模式依赖 SkyLight 私有 API，系统更新有可能失效，失效后会回退到前台后端。

还有两条容易被忽略。一是 iPhone 镜像目前在欧盟地区不可用，系统要求也卡得挺死：Apple 芯片或 T2 的 Mac、macOS Sequoia 15 以上、iOS 18 以上、同一 Apple 账户且开了双重认证、蓝牙 Wi-Fi 都开着、手机锁屏且在附近。二是 Mac 正在用隔空播放或随航时，镜像是连不上的。

再补一个文档里不太起眼但值得说的事：从 9 月初那次提交开始，每次 CLI 调用会往 PostHog 发一条遥测事件，包含脚本内容、每个助手调用的参数和耗时、stdout/stderr 尾部、启动它的 Agent 信息和平台版本。作者说只有一个随机的安装 ID 作为标识，也留了关闭方式：

phone-harness config set telemetry false

或者单次调用时加环境变量 PHONE_HARNESS_TELEMETRY=0。我个人的建议是，第一次装完就先关掉，等你确认自己能接受再打开。

权限给了，不等于放手

这个项目没有绕过苹果的安全机制。想让它操作手机，你得主动开两道门：设备授权（同一 Apple 账户 + 双重认证 + 手机上确认配对）和终端授权（屏幕录制 + 辅助功能）。

但这两道门管的是”哪台 Mac 能连手机””哪个终端能控制窗口”，粒度比较粗。一旦放行，它不会在每次发消息、下单、删除之前重新问你。

仓库的 SKILL.md 里写了一条规则：遇到发消息、公开发帖、购买、删除、改设置这类对外或不可撤销的操作，Agent 必须先停下来问用户；浏览照片、邮件等个人内容时，只看完成任务必需的部分。

问题在于，这目前是一条使用规则，不是程序里的强制关卡。Agent 要是不停，核心代码不会自动拦截。

社区里已经有人踩到相关的坑了。有反馈说镜像闲置一段时间后会停在一个需要 Mac 密码或 Touch ID 的锁定页，而 phone-harness 把这个页面判断成了”可以操作”，原本要填进搜索框的文字被输进了密码框。这不是说 Agent 拿到了密码，而是它没认出自己已经站在错误的页面上。

看天气、翻设置，认错了大不了重来。但下一步如果是发消息、确认支付或者删除内容，点错之后没有”再试一次”这个选项。

值不值得折腾

适合的人是这几类：有 Apple 芯片 Mac 和真 iPhone、想研究 OCR 加坐标这条技术路线、或者需要做低风险真机验证的开发者。它给 Agent 补上了一双能看真机的眼睛和一只手，代价是几乎不用装额外东西。

不适合的人也很清楚：需要多设备并发、要稳定的元素选择器、要复杂手势、要跑 CI 回归的团队，还是老老实实用 Appium 或 XCUITest 那套成熟栈。它自己也没打算替代谁。

我的建议是第一次测试选一个无副作用的小任务：打开天气读取页面，或者进备忘录但不保存敏感内容。别一上来就让它碰聊天记录和相册。

合规提醒几句：项目是 MIT 协议，商用和二次分发记得保留许可证声明；整套东西跑在本地，涉及的是你自己的设备和数据，别拿去操作别人的手机；开始前确认硬件满足苹果官方的镜像要求，重要数据提前备份。

获取地址

GitHub 仓库：

https://github.com/ShawnPana/phone-harness

安装文档在仓库的 install.md，日常用法看 SKILL.md，完整的助手函数清单在 src/phone_harness/helpers.py。

官方站点：https://phone-harness.com

最后

我看过的手机自动化方案不算少，大部分死在同一个地方：要么太重，要么要越狱，要么维护成本高到没人愿意碰。

phone-harness 的聪明之处在于，它压根没打算造轮子。苹果已经把 iPhone 镜像这条通道铺好了，它只需要在上面加一层很薄的壳，把截图、OCR、坐标、输入、验证串成一个闭环。核心代码也就一千行上下。

代价是它继承了苹果镜像的全部限制，一机一会话、解锁即断、没有手势。这些不是作者偷懒，是这条路的边界本来就在那儿。

如果你手上正好有台 M 系列芯片的 Mac 和一台闲置 iPhone，这个项目值得花一个下午玩玩。玩之前，先把遥测关掉，再把敏感操作那条规则跟你的 Agent 讲清楚。

就这样。