开源项目 phone-harness 让 AI 直接操作手机，两周斩获两千星

在 GitHub 上线仅两周多，开源工具 phone-harness 迅速收获了超过 2090 颗星标。过去开发者想要让 Claude Code 或 Codex 等 AI Agent（智能代理）操作移动设备，通常需要搭建庞大的 Appium 集群或在手机端强行植入自动化后台服务。这一项目打破了传统思路，完全依托宿主机 Mac 作为传输中继，实现零侵入、免越狱的手机控制。

表面上看这是一款普通的手机自动化脚本，本质上它是一套极薄的“硬件级代理封装层”。它抛弃了复杂的移动端测试框架，通过纯系统级视觉捕获与事件注入，把一台连着电脑的 iPhone 或 Android 变成 AI 视野里随时可以读写的标准画布。

架构逻辑：零侵入的视听中枢与机械臂

在 iOS 端，phone-harness 避开了传统的 WebDriverAgent 与 Xcode 签名配置流程。macOS Sequoia 引入了 iPhone Mirroring（iPhone 镜像）功能，该工具直接以镜像窗口为跳板，使用系统的 screencapture 截取图像，结合苹果原生 Vision 框架进行本地高精度 OCR（光学字符识别）提取文字与坐标，充当代理的“眼睛”；在操作层面，它直接调用 macOS 底层 CGEvent 注入 HID 级（人机接口设备）键鼠事件，作为代理的“手”。

Android 端的实现同样轻量。系统借助 adb（Android 调试桥）直接抓取截屏，同时读取 Android 自身的 Accessibility Tree（无障碍功能树）来获取精准控件信息与文本坐标；输入端则通过 adb input 指令分发点击、滑动与文本输入。无论是苹果还是安卓，手机端都不需要安装任何定制 App，所有运算和决策全部发生在电脑端。

为了兼顾开发者的实际工作，工具默认开启后台工作模式。系统直接通过窗口 ID 捕获画面并将输入定向投递给目标应用，不会抢占开发者的鼠标焦点。如果遇到特殊窗口渲染问题，也可以通过环境变量 PHONE_HARNESS_BACKGROUND=0 回退到经典聚焦模式。


+-------------------------------------------------------------+
|                      Claude Code / Codex                    |
+------------------------------+------------------------------+
| (Python Helpers API)
v
+-------------------------------------------------------------+
|                     phone-harness (Mac)                     |
+------------------------------+------------------------------+
|                               |
(Vision OCR / CGEvent)            (ADB / a11y tree)
v                               v
+------------------------------+ +----------------------------+
|    iPhone Mirroring 窗口     | |    Android 设备 (USB/Wi-Fi) |
|   (免越狱 / 零安装 App)      | |      (开启开发者调试)      |
+------------------------------+ +----------------------------+

部署实操：一行注入让 Claude 与 Codex 秒获真机技能

将工具注入 Agent 的流程被压缩到了极致。开发者首先克隆仓库并完成本地 Python 环境安装，随后直接导出规范的 Skill 文件并注入对应目录。


# 1. 克隆项目到标准路径
git clone https://github.com/ShawnPana/phone-harness ~/.phone-harness

# 2. 本地可编辑安装（自动拉取 pyobjc 系列依赖）
cd ~/.phone-harness && pip install -e .

# 3. 注册为 Claude Code 或 Codex 技能
mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md

# 若使用 Codex 则同步配置目录
mkdir -p ~/.codex/skills/phone-harness
cp ~/.claude/skills/phone-harness/SKILL.md ~/.codex/skills/phone-harness/SKILL.md

如果你希望全程自动化，可以直接将以下引导提示词复制粘贴给 Claude Code 或 Codex，智能代理会自行完成依赖检查、技能挂载与环境自检：

Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness into ~/.phone-harness (its canonical home), read install.md first, install it so phone-harness is a command on my PATH, and register it as an agent skill named phone-harness using phone-harness skill as the body, so you reach for it automatically. Then read SKILL.md for normal usage, and always read src/phone_harness/helpers.py because that is where the functions are. Then read onboarding.md and walk me through it.

双端初始化配置与日常调用范式

在 iPhone 端，首次使用需确保 Mac 已升级至 macOS Sequoia 并与实体 iPhone 建立镜像配对。接着前往“系统设置 → 隐私与安全性”，为运行终端授予两项关键权限：Accessibility（辅助功能，授权后立即可用）与 Screen Recording（屏幕录制，需重启终端生效）。最后执行 phone-harness --doctor ios 完成全链路健康度检测。

Android 端则先通过 Homebrew 安装基础套件：brew install android-platform-tools。进入手机“设置 → 关于手机”，连续点击“版本号”7 次开启开发者选项。USB 模式下开启“USB 调试”并允许电脑连接即可。若采用 Wi-Fi 无线连接（需 Android 11 及以上且同局域网），进入“无线调试”点击“使用配对码配对”，执行 phone-harness android pair 123456 完成配对。面对长耗时任务，可使用 phone-harness android awake --bg 防止手机息屏。

日常调度中，Agent 采用 Heredoc 语法直接传递 Python 控制逻辑。核心 helper 函数无需反复引入：


phone-harness <<'PY'
# 打开便签应用
open_app("Notes")
wait_stable()

# 点击新建并键入内容
tap_text("New Note")
type_text("hello from the harness")

# 检查当前屏幕前 10 条 OCR 文字
print([o["text"] for o in ocr()][:10])
PY

核心 API 遵循“操作后必校验”的原则。系统提供 ocr() 返回所有可见字符串及其点击中心坐标，tap_text("Weather") 遇阻时会抛出包含当前所有可见文本的异常。针对没有文本的图标，Agent 可先通过 screenshot() 审视视觉结构，再使用 image_point(x, y) 转换后调用 tap_image_point()。针对长列表遍历，scroll_collect(extract, key=...) 会以实际屏幕像素位移作为停机判据，自动完成去重抓取与触底停止。

阶段	核心问题	留下的硬伤
传统移动自动化（Appium 等）	依赖复杂驱动与证书签名，端内侵入重	环境极易失效，对动态变更的非标准 UI 识别率低
纯系统多模态方案（OS-World 类）	全局截屏分析耗时大，键鼠映射存在严重漂移	易误触其他桌面软件，无法在后台静默执行长任务
phone-harness 方案	严重依赖宿主机传输链路与窗口渲染状态	涉及生物识别与系统底层弹窗时完全无法绕过物理干预

实测避坑指南与使用边界

在 iPhone 镜像体系下，有几个技术陷阱需要规避。AppleScript 的 click at 指令在此处会静默失效，因为镜像窗口实质上是一道硬件视频流，不提供系统无障碍树；Unicode 文本负载也无法直接直传，镜像仅接收原始 HID 键码序列，输入必须走键码模拟。

坐标映射是开发者最容易出错的地方。OCR 解析得到的是截图图像内部像素，而原始 tap() 接收的是 Mac 屏幕的全局绝对坐标。开发者必须使用 image_point(x, y) 进行换算，严禁人工手动估算窗口偏移量。


+-------------------------------------------------------------+
|                      排障速查 (Doctor)                      |
+-------------------------------------------------------------+
| 现象 1：iPhone 截图全黑或空白                                 |
| 根因：终端虽然给了屏幕录制权限但未重启，或镜像正处于锁屏保护态|
+-------------------------------------------------------------+
| 现象 2：iPhone 无法触发点击                                   |
| 根因：缺失辅助功能权限，或目标窗口失去系统事件响应焦点       |
+-------------------------------------------------------------+
| 现象 3：运行报 pyobjc 缺失但已安装                           |
| 根因：系统存在多个 Python 解释器环境冲突，需对齐路径         |
+-------------------------------------------------------------+
| 现象 4：Android 设备报 unauthorized 错误                     |
| 根因：手机端未解锁并勾选“始终允许来自此计算机的调试”         |
+-------------------------------------------------------------+

明确应用边界同样重要。如果某项任务能够在 Web 端、API 层面或 Mac 本地软件中完成，绝不应当派发给手机端执行。该工具的合理战场应当严格限制在 iOS 独占应用操作、短信验证码与 2FA 认证读取、以及真机动态效果回归测试等不可替代的场景。操作过程中必须严格遵循安全准则：绝不代输银行与设备 PIN 码，未经明确确认绝不更改手机系统设置。

综合来看，phone-harness 不是一个试图颠覆传统移动端开发框架的重量级平台，而是一把专为 LLM 打造的轻巧手术刀。它没有发明新的协议，而是利用 macOS 镜像与 adb 这两座既有的系统桥梁，把手机交互压缩成标准输入输出，让大模型在不接触底层驱动细节的前提下直接接管硬件。

一个未解决的问题

尽管 phone-harness 通过视觉与 HID 注入解决了绝大多数交互问题，但当 iOS 触发系统级安全防护策略（例如弹出 Face ID 授权、涉及敏感权限的强制硬件确认弹窗、或是应用禁止投屏渲染导致的黑屏遮罩）时，纯软件传输链路会瞬间中断。如何让 AI Agent 在脱离物理接触的情况下优雅感知这类硬件级阻断并完成可信人机交接，依然是当前架构下尚未解决的难题。