zhongerxin/iPhone-use

它解决的问题

手动控制真实 iPhone 既慢又重复。这个项目让 Codex、WorkBuddy 或豆包工作等 AI 编码助手通过 USB 操作你的实际 iPhone，因此你可以用自然语言描述任务，助手会自动打开应用、读取屏幕、点击、滚动和输入。它还在侧边栏显示手机屏幕，便于实时监控。

工作原理

该项目使用 WebDriverAgent (WDA)，一个运行在 iPhone 本身上的开源自动化服务。助手通过本地 MCP（模型上下文协议）服务器与 WDA 通信，该服务器通过 USB 转发命令并流式传输屏幕。一次性设置使用你的 Apple 账户和 Xcode 在手机上安装并签名 WDA。设置完成后，助手可以调用一组 18 个工具来检查屏幕、查找 UI 元素、点击、滑动、输入文本、执行批量操作以及从失败中恢复。当元素定位失败时，它会回退到查看截图并按坐标点击。屏幕预览小部件在助手的侧边栏中运行，支持直接点击、拖动和滚动。

适用人群

在 macOS 上使用 Codex、WorkBuddy 或豆包工作，并希望这些助手自动化通过 USB 连接的实体 iPhone 上的任务的开发者和高级用户。它需要一台装有完整 Xcode 的 Mac、Python 3.9+、Node.js 和 npm、一个用于签名的 Apple 开发者账户，以及一部已解锁并启用开发者模式的 iPhone。

亮点

• 本地 USB 连接： 所有流量都保留在你的 Mac 上；无需云或 Appium 服务器。
• 复用现有工作： 健康的 WDA 会话和之前的构建会被复用，以避免重复设置。
• 紧凑的观察和组合操作： 控制树被简化，截图仅在需要时拍摄，批量/滚动/收集工具减少了助手的往返次数。
• 异步设置： 下载、构建和启动返回一个可查询的任务 ID，避免重复启动。
• 截图回退： 如果元素查找失败，系统返回截图，助手通过像素到点的转换选择点击位置。
• 清晰的失败语义： 操作锁防止冲突操作，模糊结果会被标记，以便助手在重试前读取实际状态。
• 带暂停/恢复的实时屏幕： 预览显示 iPhone 外壳、状态和手势；如果用户需要解锁或认证，遮罩会覆盖屏幕，之后自动恢复。