Phone Harness

想让 AI 帮你回微信、查天气或者整理备忘录？通常这需要复杂的自动化脚本、昂贵的企业证书，甚至冒着风险去越狱。Phone Harness 提供了一个极其巧妙的解决方案：利用 macOS Sequoia+ 自带的 iPhone Mirroring（iPhone 镜像） 功能，让 LLM 像人一样“看”屏幕、“点”图标。

它不需要 Xcode，不需要 WebDriverAgent，也没有任何中间层代理。AI 通过截屏和 OCR 识别界面，通过 HID 级事件模拟触控，真正实现了在真实物理设备上的自主操作。

核心原理：把镜像窗口变成“穷人的 DOM”

Phone Harness 的核心逻辑非常纯粹，它利用了 macOS 系统级的能力：

1. 看见（Vision OCR）：
   • 它捕获 iPhone Mirroring 的窗口画面。
   • 调用 Apple 原生的 Vision 框架进行 OCR 识别。
   • 结果不仅是文字，还包含每个字符串在屏幕上的精确 (x, y) 坐标。这对 AI 来说，就是可点击的“DOM 树”。
2. 操作（CGEvents）：
   • 它不发送 AppleScript 命令（因为镜像窗口没有辅助功能树），而是直接在 HID 层面发布 CGEvents。
   • 这意味着点击、长按、滑动、滚轮甚至 Unicode 输入都被转化为真实的触摸信号，发给手机。
3. 验证（截图闭环）：
   • 每次操作后，AI 会再次截屏确认结果。没有 API 返回的状态码，截图就是唯一的真相。

为什么它比传统方案更好？

• 零侵入：无需在手机上安装任何描述文件或 App，完全依靠系统原生镜像功能。
• 高保真：操作的是真实的 iOS 界面，看到的也是真实的渲染结果，避免了模拟器与真机的差异。
• 极简架构：整个核心代码仅约 500 行，无守护进程，每次调用都是独立的，状态干净。

快速上手指南

1. 前置条件

• macOS Sequoia (15.0) 或更高版本。
• 已配对并启用 iPhone Mirroring 的 iPhone。
• Python 环境。

2. 安装与权限配置

将项目克隆到 ~/.phone-harness，然后运行安装脚本。你需要亲自完成两件事：

• 配对：确保 iPhone Mirroring 能正常显示手机画面。
• 授权：在“系统设置 → 隐私与安全性”中，授予终端（Terminal）辅助功能（用于点击）和屏幕录制（用于截屏）权限。

git clone https://github.com/ShawnPana/phone-harness.git ~/.phone-harness
cd ~/.phone-harness
# 按照 install.md 指引完成权限授予
./phone-harness --doctor # 验证链路是否通畅

3. 让 AI 自动调用

如果你使用 Claude Code 或 Codex，只需粘贴以下提示词，它会自动配置技能：

“为我设置 phone-harness。将其注册为一个名为 phone-harness 的代理技能… 阅读 SKILL.md 了解常规用法。”

4. 手动测试

你可以直接在终端运行简单的 Python 脚本来测试：

./phone-harness <<'PY'
open_app("Weather")
tap_text("北京")
print([o["text"] for o in ocr()][:5])
PY

已知限制与避坑

• 单会话限制：一次只能控制一部手机。如果物理手机被解锁或拿起，镜像会暂停，操作也会中断。
• 无多点触控：不支持捏合缩放等手势。
• OCR 局限性：它只能识别文字。对于纯图标按钮，需要结合具有视觉能力的多模态模型来识别。
• 输入技巧：由于镜像转发的是原始 HID 键码，输入中文等特殊字符可能需要特定的键码映射；列表滚动建议使用滚轮而非慢速拖拽。