Phone Harness 深度拆解：不越狱、不装 App，让 AI Agent 静默接管真机（附实测打车演示视频）

让 AI Agent（智能体）替人类操作电脑已经不再新鲜，但如何让 AI 真正接管我们口袋里的真实智能手机？

长期以来，移动端设备自动化是一条布满荆棘的泥潭：你要么需要将 iPhone 越狱（Jailbreak）破坏安全沙盒，要么必须在 Xcode 里挂载 WebDriverAgent 签名证书，要么只能在脱离真实 SIM 卡和硬件环境的模拟器里自娱自乐。一旦遇到依赖手机号短信 2FA、真实指纹支付、或者仅在 App Store 上架的特定闭源商业应用，传统的自动化方案便彻底瘫痪。

近期在开源社区爆火的 ShawnPana/phone-harness，给出了一种堪称惊艳的“降维打击”解法：不越狱、不装 App、不改固件，将 Claude Code、Cursor、AGY 等 AI Coding Agent 直接接入真实 iPhone 与 Android 手机。

Agent 可以像人一样“看屏幕（OCR / Vision）”、“点按钮（Tap）”、“输文字（Type）”并根据屏幕变动实时反馈。

下面是项目最震撼的一段实测演示 —— 开发者对终端里的 AI 下达一句话指令：“从我当前位置打一辆 Waymo 无人驾驶出租车去 Delah Coffee”，AI 全程自动操作真机完成了唤醒、搜索、车型选择与下单确认：

本文将为你深度拆解 phone-harness 内部的工程架构、黑客级实现细节以及如何将其装配进你的日常 Agent 工作流。

🔬 核心底层架构拆解：双端截然不同的“降维打击”

phone-harness 之所以能够做到在完全不触碰手机安全沙盒的前提下实现控制，核心在于它巧妙借力了桌面端现存的官方系统通道：

flowchart TD
    subgraph AgentLayer["1. AI Agent 决策大脑"]
        AgentPrompt["开发者意图：打开备忘录并记录灵感"]
        LLM["AI Agent：Claude Code / Cursor / Codex"]
        ScriptGen["生成声明式控制脚本 (phone-harness CLI)"]
        AgentPrompt --> LLM --> ScriptGen
    end

    subgraph iOSPipeline["2. iOS 架构：iPhone 镜像 + 私有底层事件"]
        MirrorWindow["macOS iPhone 镜像 (ScreenContinuity)"]
        WindowCapture["CGWindowListCreateImage 隐式窗口捕获"]
        AppleVision["Apple Silicon Vision 框架本地秒级 OCR"]
        SkyLightHID["SkyLight 私有 API：SLPSPostEventRecordTo 注入事件"]
        MirrorWindow --> WindowCapture --> AppleVision
        SkyLightHID --> MirrorWindow
    end

    subgraph AndroidPipeline["3. Android 架构：ADB 直连通道"]
        AdbBridge["ADB 调试通道 (USB 或 Wi-Fi 无线)"]
        ScreenCap["adb screencap 抓取位图"]
        A11yTree["Accessibility 无障碍节点树提取文本与边界"]
        InputTap["adb shell input tap / swipe / text 注入"]
        AdbBridge --> ScreenCap
        AdbBridge --> A11yTree
        InputTap --> AdbBridge
    end

    subgraph HardwarePhone["4. 真实物理手机终端"]
        RealIPhone["真实 iPhone (保持锁屏静默)"]
        RealAndroid["真实 Android 设备"]
    end

    ScriptGen --> iOSPipeline
    ScriptGen --> AndroidPipeline
    iOSPipeline --> RealIPhone
    AndroidPipeline --> RealAndroid

1. iOS 端黑科技：SkyLight 私有事件注入（静默后台执行，不抢占焦点）

很多 macOS 自动化脚本最烦人的一点在于：它每点一下，你的屏幕窗口就会弹起一次，鼠标也会乱窜，彻底剥夺你的工作电脑控制权。

phone-harness 在 background.py 中实现了一套极其硬核的方案，直接借用了平铺窗口管理器 yabai 的底层黑客技术：

视觉之眼（Eyes）：调用 CoreGraphics 的 CGWindowListCreateImage，通过 Window ID 直接抓取 iPhone 镜像窗口的离屏图像缓冲。哪怕这个镜像窗口被其他浏览器、IDE 窗口完全遮挡，也能瞬间精准截帧；
文本坐标提取（OCR）：丢弃昂贵且缓慢的云端大模型 OCR，直接调用 Apple Silicon 神经网络引擎上的苹果官方 Vision.framework（VNRecognizeTextRequest），在几毫秒内返回画面中所有字词及其在全局屏幕空间的中心点击坐标 (x, y)；
双手（Hands）：这是整个项目最精妙的一笔。macOS 默认不允许向未激活（Inactive）的窗口投递 CGEvent，但系统底层的窗口服务（Window Server）允许通过私有框架 SkyLight.framework 中的 SLPSPostEventRecordTo 发送合成事件记录。
- 它构建了一个 0xf8 字节的二进制结构体；
- 写入 CGSEventType（按下、抬起、拖拽）；
- 写入目标窗口 ID 与精准局部坐标；
- 投递给 com.apple.ScreenContinuity 进程。

最终实现的效果：AI 在后台疯狂操作手机，你桌面上的光标和打字焦点纹丝不动，你可以一边写代码，一边看着 AI 在角落里帮你打车、点咖啡、查快递！

2. Android 端：ADB 极速无缝通道

在 Android 端，phone-harness 走的是经过工业检验的 ADB 桥接：

画面与层级：通过 adb exec-out screencap -p 极速拉取当前帧；同时读取 Android 系统的无障碍层级树（Accessibility Tree），直接拿到原生控件的语义文本与无障碍标签；
交互模拟：通过 adb shell input tap 与 input swipe 完成触控；
支持 USB 直连与局域网 Wi-Fi 无线连接，甚至无需在 Mac 屏幕上渲染任何模拟器窗口。

🎯 实战方法论：AI 操控真机的“闭环四大铁律”

操作手机与写代码最大的不同在于：手机没有浏览器那样的 DOM 树可以 assert，也无法通过函数返回值获知点击是否成功。绝大多数真机故障都是“毫无报错的无响应（Silent No-op）”。

phone-harness 在其官方 SKILL.md 中为 AI 注入了一套严格的工程纪律：

铁律一：行胜于言，先设预期再动笔（Name what should change）

在每次点击之前，AI 必须在脑海或注释中明确断言“点击后哪个控件或文字应该改变”。如果连预期都说不清楚，AI 根本无法区分“点击成功”还是“网络卡顿没反应”。

铁律二：轻量验证（OCR 优先，截图保底）

文字按钮：优先使用 tap_text("设置") 或 find_text("Waymo")。OCR 计算成本极低、速度极快；
图形图标：当遇到底栏没有文字的纯图标时，AI 触发 screenshot() 获取截图，利用自身多模态视觉能力定位相对坐标，再调用 tap_image_point(x, y) 精确点击。

铁律三：验证成功后立刻打包（Batching）

逐条命令交互会消耗大量的对话轮次和网络往返。一旦 AI 验证了“打开 App $ o$ 点击搜索框 $ o$ 输入文字”这一段逻辑的稳定性，后续调用会自动将这一串动作合并为单个 Python 脚本批量下发，执行速度媲美人类肌肉记忆。

铁律四：发生故障，单步隔离（Isolate on failure）

一旦断言失败，严禁盲目重试。AI 会退回单步执行模式，重新拉取当前最新画面，分析是弹出了系统权限弹窗、网络加载慢了、还是按钮被浮动键盘挡住了，进而自适应调整。

💻 极速上手体验

1. 一键安装与环境自检

在 macOS 终端中运行：

# 克隆至本地目录
git clone https://github.com/ShawnPana/phone-harness.git ~/.phone-harness
cd ~/.phone-harness

# 运行自检工具，检查 iPhone 镜像配对、辅助功能权限与录屏权限
phone-harness --doctor

2. 作为 Agent Skill 注册到你的 AI 助手

如果你使用的是 Claude Code、Cursor 或 AGY，可以直接在会话中对其下发指令：

请阅读 ~/.phone-harness/SKILL.md，将 phone-harness 作为你的专属移动端控制技能引入。

3. 在命令行中直观驱动

你可以通过简单的 Python Heredoc 代码块直接与手机交互：

phone-harness <<'PY'
# task: 打开备忘录并记录一条临时灵感
# step: 启动 Notes，新建备忘录并键入内容
open_app("Notes")
tap_text("新建备忘录")
type_text("Hello, this note was written entirely by an autonomous AI agent!")
print([item["text"] for item in ocr()][:5])
PY

⚠️ 现有边界与安全底线

尽管 phone-harness 展现出了无与伦比的优雅，但在使用时仍需了解当前的技术边界：

生物识别与安全锁屏（Face ID / PIN）：
当 iPhone 镜像检测到需要 Face ID 授权或处于设备物理锁屏状态时，镜像会主动暂停（这是苹果系统底层的硬件级安全保护），此时必须由用户本人扫脸或输入密码；
DRM 受保护视频流：
Netflix、Disney+ 等受版权保护的内容在镜像窗口中会被系统渲染为纯黑画面，AI 无法读取；
多指复杂手势：
目前支持单指点击、长按、滑动和键盘输入，双指缩放（Pinch-to-zoom）等复杂手势尚在开发演进中。

🚀 结语：从“网页爬虫”到“物理世界接管”

过去两年，我们见证了 AI Agent 在浏览器（Web Browser）环境下的长足进步。然而，互联网上最具商业价值、最贴近个人生活隐私的场景（如打车、外卖、移动支付、健康监测、即时社交），70% 以上都只沉淀在移动原生 App 的围墙花园之中。

phone-harness 用极具智慧的系统级工程思维，利用 macOS 原生功能和 Apple Silicon 硬件加速，为广大开发者撕开了一道直通移动真机的全自动天窗。

它不仅是一个让人大呼过瘾的开源项目，更是未来个人全能 AI 助理真正走进我们日常数字生活的关键拼图！

lijianfei.com