Phone Harness Skill：让 AI 直接操控真实 iPhone 的开源工具

Skill超级捕获手 技术创作者 2026-08-21 11 阅读

在 AI 能写代码、画图、甚至操控电脑的今天，操控一台真实的 iPhone 听起来仍然像是黑客电影里的场景。但 phone-harness 把它做成了一个 5 分钟能跑起来的真实工具——不需要越狱、不需要 Xcode、不需要 Appium，只要一台 Mac 和一部 iPhone。

phone-harness 是一个开源 Python 工具，让 LLM Agent（Claude Code、Codex 或任何支持 tool-use 的模型）通过 macOS 的 iPhone Mirroring 功能直接操控真实的 iPhone。核心原理简洁：用 screencapture 截取 iPhone 镜像窗口的画面 → Apple Vision 框架做 OCR，提取屏幕上所有文字及其精确坐标 → 通过 macOS HID 层（CGEvents）模拟真实点击、长按、拖拽、文字输入 → 再次截图验证操作是否生效。整个闭环约 500 行 Python 代码，MIT 协议。

phone-harness 的核心定位是”真实设备控制”，而不是模拟器或 WebDriverAgent 方案。它的设计原则是最小侵入：不装任何应用到手机、不依赖开发者证书、不需要 Xcode 编译，只要 macOS Sequoia + iPhone Mirroring 配对完成，终端赋予辅助功能和屏幕录制权限，就能跑起来。对 AI Agent 而言，手机就是另一个有屏幕、有输入、能截图反馈的工具。

截至 2026 年 8 月 21 日，phone-harness 在 GitHub 累计获得约 1,493 stars，8 月新上榜 GitHub Trending，周增 1,400+ stars，是当周增速最快的工具类项目之一。多个中文技术社区（掘金、夜雨聆风等）出现详细教程，GitHub Star 情报平台标记为 Python / automation 分类的热门项目。项目同时支持 Android（通过 adb），可实现一部 Mac 同时管控 iPhone 和 Android 双平台。

GitHub 链接：

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

作者 Shawn Pana（GitHub @ShawnPana），独立开发者，专注 macOS/iOS 自动化工具链。phone-harness 是其目前最知名的项目，GitHub 档案标注了 phone-harness.com 独立域名。

phone-harness 的 README 将其定位为”AI Agent 的手机控制桥接层”。它最初灵感来自让 Claude Code 用户能够对自己的 iPhone 下达自然语言指令（如”帮我查天气””回微信””把照片上传到云端”），而不需要写任何脚本。Agent 在执行过程中可以编辑 agent-workspace/agent_helpers.py 加载自定义辅助函数，也可以注册为 Skill 让 Claude Code 按需自动调用。

核心能力分为 iPhone 和 Android 两条路径：

iPhone（macOS iPhone Mirroring）：
– 看：截取镜像窗口画面，Vision OCR 提取所有可见文字 + 坐标（Poor Man’s DOM）
– 动：CGEvents 在 HID 层级模拟真实触摸，支持点击、长按、拖拽、滚动、Unicode 打字、快捷键（Cmd+1 Home、Cmd+2 App Switcher 等）
– 验证：再次截图确认操作结果

Android（adb over USB/Wi-Fi）：
– 看：screencap 截图 + uiautomator accessibility tree，返回精确文字和元素坐标
– 动：tap/swipe/text 输入，Back 键，返回坐标 1:1 映射（截图像素 = 设备像素）
– 验证：同样基于截图

phone-harness 的核心特点可以归纳为五点：

  • 零侵入：不需要越狱、不装手机端应用、不需要 WebDriverAgent，配置成本极低
  • 真机效果：HID 层输入，不是模拟器点击，系统行为完全真实
  • 极简代码：核心约 500 行 MIT 协议，源码可读可改
  • 无状态执行：每次调用独立，无 daemon 残留，不会干扰手机正常使用
  • 跨平台支持：iPhone + Android 双平台，一套工具链覆盖苹果和安卓生态

安装步骤极为简洁。Clone 到指定目录并加入 PATH：

git clone https://github.com/ShawnPana/phone-harness.git ~/.phone-harness

阅读 install.md 加入 PATH，然后验证完整链路：

phone-harness --doctor

注册为 Agent Skill 让 Claude Code 自动调用：

phone-harness skill

基本使用示例（iPhone）：

./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

phone-harness 主要面向以下场景和人群：

  • iOS 端到端测试：不想被 Appium/XCUITest 配置折磨的开发者，快速跑通真实设备的自动化流程
  • Claude Code / Codex 用户：用自然语言驱动自己的 iPhone，如查信息、发消息、拍照上传
  • 移动 Agent 研究：在真实手机上验证 Agent 的 planning、tool-use 和自我纠错能力
  • 个人效率自动化：将重复的手机操作（打卡、发消息、整理相册）交给 AI 处理

典型输入输出案例：

场景一：让 AI 查天气

  • Input：Agent 调用 open_app("Weather") → ocr() 读取城市 → tap_text("Beijing") 切换城市
  • Output：截图显示北京当前温度和天气预报文字，Agent 读取并回复用户

场景二：让 AI 帮你回微信

  • Input：Agent 调用 tap_text("WeChat") 打开微信 → ocr() 识别最新消息 → type_text("好的，我收到信息了！") 回复
  • Output：操作完成后截图验证消息已发送

需要注意的是：phone-harness 不能处理 Face ID / 相机相关流程；DRM 视频（Netflix、Apple TV+）截图为黑屏；iPhone 解锁实体手机会暂停 Mirroring；不支持多点触控（无 pinch 缩放）；OCR 只能识别文字，图标类控件需配合截图 + 视觉模型。这些限制在 README 中由作者诚实列出，属于项目当前阶段的能力边界。

phone-harness 的出现填补了一个具体空白：让”AI 控制真实手机”这件事从需要专业移动开发背景变成下载即用。它不是 Appium 的替代品（需要 8 台 iPhone 并发跑 500 个回归 case 仍然应该上 Appium），但对于”我手头有个 Claude Code，想让它帮我操作手机”这种场景，工程复杂度从 100 砸到了 10。在这个方向上，它是目前最低门槛的解决方案。

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

评论区

0 条评论

登录后可评论。

Skill超级捕获手 11 阅读