无需越狱、无需 Xcode、无需 WebDriverAgent——仅用 macOS iPhone Mirroring让 Claude 和 Codex 直接操控你的 iPhone。这是 AI Agent 从能思考到能动手的关键一步。 这个项目解决什么问题2026 年 8 月GitHub 上出现了一个 5 天涨到 1500 Star 的项目——phone-harness。它的定位简单粗暴让 LLM 直接控制你的真机 iPhone。过去让 AI 操作手机通常要走三条路越狱 TouchHID门槛高、风险大、iOS 版本限制严格WebDriverAgent Xcode需要 Mac 装 Xcode、跑 Appium 服务器、配置复杂云手机方案延迟高、隐私差、付费成本Phone Harness 走的是第四条路——利用 macOS Sequoia 的 iPhone Mirroring 窗口把它当成一块可截图、可 OCR、可发 HID 事件的屏幕。LLM 看到的是 Vision Framework 解析出的文字和坐标执行的是 CGEvent 级别的精确点击。核心洞察这个项目解决的不是AI 能不能控手机而是AI 能否以最低成本、最低摩擦地获得一个真实设备操作入口。 快速上手动手环节前置条件要求说明macOS15 Sequoia自带 iPhone MirroringiPhoneiOS 18已与 Mac 配对权限终端需 Accessibility点击/拖拽 Screen Recording截图模型Claude Code 或 Codex CLI一键安装把下面的 prompt 贴给 Claude Code 或 CodexSet up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness into ~/.phone-harness and 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. Then read SKILL.md for normal usage. Always read src/phone_harness/helpers.py because that is where the functions are. Setup needs two things only I can do: pairing iPhone Mirroring with my phone once, and granting the terminal Accessibility Screen Recording. Walk me through those and wait for me. Verify with ./phone-harness --doctor.然后完成两步人工操作在 iPhone 上配对 iPhone Mirroring在系统设置 → 隐私与安全中给终端授予辅助功能和屏幕录制权限验证./phone-harness --doctor全部通过即可。第一次调用./phone-harnessPY open_app(Notes) tap_text(New Note) type_text(hello from the harness) print([o[text] for o in ocr()][:10]) PY3 秒之内你的 iPhone 上应该多了一条来自 AI 的笔记。⚙️ 技术原理架构图生成 Python 脚本exec stdin导入tap/click 坐标状态反馈结果返回LLM / Agentphone-harness CLIrun.pyhelpers.py 原语函数mirror.pyocr.pyMac 窗口发现窗口截图 screencaptureCGEvent 输入注入Apple Vision Framework OCR文字 坐标定位数据流说明LLM 生成一段 Python 脚本调用helpers.py中的 APIrun.py通过 stdin 执行脚本helpers.py的所有函数在作用域内可用mirror.py负责找到 iPhone Mirroring 窗口、截图、注入 CGEventocr.py用 Vision Framework 把截图转成「文字坐标」的点击坐标表关键设计决策为什么用 CGEvent 而不是 AppleScript作者在 README 里明确写了踩坑记录iPhone Mirroring 渲染的是一个视频流窗口没有 Accessibility TreeAppleScript 的click at调用会被静默忽略。唯一可靠的方式是直接向 HID 层注入 CGEvent。为什么用 Vision Framework 而不是外接 OCRVision Framework 是 macOS 原生框架对中文支持好、无需安装第三方依赖、零 API Key。它返回的是VNRecognizedTextObservation每条都自带边界框坐标——这正是点击定位需要的。状态无设计每次调用都是全新的重新查询窗口边界、重新截图、重新注入事件。没有守护进程没有状态机没有 session 管理。这种无状态设计让每次调用都是独立、可追溯、可重复的。️ 架构分析目录结构phone-harness/ ├── SKILL.md ← Agent 面向的日常工作流产品表面 ├── install.md ← 权限引导和故障排查 ├── README.md ├── src/phone_harness/ ← 核心~500 行 │ ├── mirror.py ← 窗口发现、聚焦、截图、CGEvent │ ├── ocr.py ← Vision Framework → 文字坐标 │ ├── helpers.py ← 预导入的原语函数 │ ├── admin.py ← --doctor 诊断 │ └── run.py ← CLIexec stdinhelpers 在作用域 ├── agent-workspace/ │ └── agent_helpers.py ← Agent 运行时可编辑的辅助函数自动加载 └── ...原语函数层次Agent 可扩展层语义层 (Semantic)原语层 (Primitives)ocr()tap(x, y)type_text(s)screen_info()tap_text(text)open_app(name)scroll_down()agent_helpers.py自定义函数设计亮点agent_helpers.py允许 Agent 在运行过程中动态扩展工具函数。如果 LLM 发现某个高频操作需要封装可以直接往这个文件里写代码下次调用时自动加载。这是一个Agent 自进化的工具链设计。输入模式对比输入方式机制适用场景tap(x, y)CGEvent 坐标点击精确位置点击tap_text(确定)OCR 找文字 → 点击界面交互最常用type_text(hello)HID 键盘码注入文本输入flick()快速手势 → 页面切换滑动导航scroll()鼠标滚轮事件列表滚动✅ 优缺点 适用场景优势零基础设施不需要 Xcode、不需要 Appium、不需要越狱原生权限模型CGEvent 需要 macOS 授予辅助功能权限和终端用 SSH 同等级别Agent 友好SKILL.md 直接注册为 Agent skillLLM 会自动感知和调用自进化agent_helpers.py让 Agent 能自行扩展工具局限性只能看文字不能理解图标OCR 返回的是文本坐标未标注的图标需要 Vision 模型补全多触点不支持没有多指手势缩放、旋转DRM 视频为黑色受版权保护的视频流渲染为全黑必须 iPhone 解锁手机锁屏后 Mirroring 暂停Agent 无法操作仅限单设备同时只能连接一台 iPhone适用场景场景推荐度说明iOS App 自动化测试⭐⭐⭐⭐替代 XCUITest 的轻量方案手机操作 Agent 原型⭐⭐⭐⭐⭐快速验证想法日常辅助天气、备忘录⭐⭐⭐有趣但需要手机解锁生产级持续集成⭐⭐缺少并行和多设备支持总结Phone Harness 的价值不在于又一个手机控制工具而在于它验证了一个关键假设LLM Agent 可以通过 macOS 原生能力以极低的工程成本获得对真实移动设备的一手操作权限。从 Agent 生态的角度看agent_helpers.py的自进化设计、SKILL.md 的 Agent skill 注册机制、无状态调用模型——这些设计都是在为Agent 作为一等公民铺路。收藏钩子完整安装指南见install.mdAPI 速查见src/phone_harness/helpers.pyAgent 日常用法见SKILL.md。项目地址https://github.com/ShawnPana/phone-harness开源协议MIT