搜索你想找的开源项目

输入名称、用途或关键词,也可粘贴 GitHub 仓库链接

分享到微信

当前解读页的微信分享二维码

用微信扫一扫打开,点击右上角「···」分享给朋友或朋友圈。

手机上可截屏后,在微信扫一扫中从相册识别二维码。

zhongerxin/iPhone-use

AI 工程

让 Codex、WorkBuddy 或豆包工作通过 USB 操作真实 iPhone,完成 App 自动化、屏幕预览与截图回退。

5,022
502
Python
MIT
创建于 42 天前

项目介绍

iPhone Use 让 macOS 上的 AI 助手(Codex、WorkBuddy 或豆包工作)通过 USB 操作真实 iPhone。你用自然语言描述任务,助手就能打开 App、读取控件树、点击、滚动、输入 Unicode 文字、整理列表,并在侧边栏 widget 中显示实时手机画面。手机端执行服务是 WebDriverAgent,项目固定使用已验证的版本;Mac 端是一个本地 MCP 服务加安装与配置技能。

在 Appium 的 WDA 之上,项目提供了 Codex 插件封装、18 个模型可用工具和屏幕 widget,无需单独启动 Appium Server。它适合希望用助手完成真机自动化(列表采集、App 导航、文字输入)而不想手写 XCUITest 的人。

使用前提

  • macOS,以及受支持的宿主之一:Codex(Codex 版安装另需 Codex CLI)、WorkBuddy 或豆包工作。
  • 完整安装并完成首次启动配置的 Xcode,以及可在 Xcode 中使用的 Apple 账号和开发团队,用于签名 WDA Runner;仅有 Command Line Tools 不够。
  • 通过 USB 连接的真实 iPhone,信任此 Mac,开启开发者模式,安装与启动期间保持解锁。
  • Python 3.9+,Node.js 20.19+/22.12+/24+ 及 npm 10+。
  • Xcode 需要支持手机当前 iOS 版本。无需越狱。

快速使用

  1. 克隆仓库并运行安装脚本:
git clone https://github.com/zhongerxin/iPhone-use.git
cd iPhone-use
sh scripts/install.sh

脚本会验证并暂存源码,通过 Codex CLI 注册本地 marketplace、安装插件和技能,并将 MCP 服务注册为 iphone_use。完成后重连或新开 Codex 聊天。

  1. 在新聊天中启用 iPhone Use,让配置技能处理设备,例如输入:「用 iphone-use-setup 帮我配置通过 USB 连接的 iPhone,安装并启动 WDA,验证 READY,然后显示手机屏幕。」技能会引导完成诊断、设备发现、签名配置、获取 WDA 以及后台构建与启动。签名使用你自己的 Apple 账号、开发团队和 bundle ID,而不是作者的。

  2. 等 pua_ready 返回 ready=true 后开始手机任务,例如:「打开备忘录,新建一条草稿,输入下面的中文内容,核对文字后保留。」工具返回控件树和截图,实时预览显示在 widget 中。

WorkBuddy 版在源码目录运行 python3 workbuddy/install.py,然后在「连接器管理」信任 iphone_use(见 WorkBuddy 说明);豆包工作版运行 python3 doubao/install.py,按安装器输出新建 STDIO 连接器并上传两个技能文件夹(见 豆包工作说明)。这两个适配版不需要 Codex CLI,默认关闭匿名统计。

使用约束

  • WDA 签名、安装和启动按设备进行;已配置的设备与构建会被复用,正常任务无需每次重装。
  • 工具默认不提交输入文字,输入与提交分开,模型需要核对关键页面、接收人、数量和最终结果。
  • 密码、验证码、Face ID 等认证由用户完成;需要接管时 widget 暂停并显示「请在手机上接管操作」提示。
  • 多进程共享操作锁,两个宿主同时操作同一部手机需要按提示等待;动作超时或断线可能被标记为不确定,应先读取实际状态,避免盲目重放点击或提交。
  • 运行数据默认位于 ~/.local/share/iphone-use/,可用 IPHONE_USE_STATE_DIR 指定;目录权限 700,配置和图像文件 600。预览流不落盘。WDA_URL 仅接受本机地址,默认转发端口 18100。
  • 插件默认向 PostHog 和 GA4 发送匿名使用统计,包括使用开始、工具调用、连接状态、耗时、错误类别、显式启动的 App 标识和公开目录名称;可用 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1 并重启 MCP 服务关闭,详见 埋点说明。
  • MIT 许可证,第三方组件说明见 THIRD_PARTY_NOTICES.md。

HotRepo 点评

HotRepo 目前没有该仓库的榜单或涨星记录,站内数据看不出热度趋势。可观察的是设计取舍:它把 Appium 的 WDA 封装进 MCP 层和配置技能,让助手无需写自动化代码即可驱动真机,并明确说明了匿名统计范围、状态目录权限和仅限本机的 WDA 转发;控件定位失败时改用截图兜底的策略也便于在投入签名配置前评估。成本同样真实:需要 Mac、完整 Xcode、Apple 开发团队和 USB 手机,并非开箱即用的工具。

本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。

相关推荐

  1. JosssphZhou/poki让 Claude Code、Codex 等 MCP 客户端通过 Mac 操控真实 iPhone,无需越狱或额外硬件。JavaScript109
  2. phoneuse-official/phoneuse在 Mac 上通过提示词、实时画面、REST 与 MCP 控制 USB 连接的 iPhone 的开源本地工具。Python132
  3. ZSeven-W/dsh-ios为编程 Agent 提供 22 个工具,在会话内启动、构建并操控 iOS 模拟器或 USB 真机,带可点拖的实时侧栏。TypeScript469
  4. phone-harness/mcp这是一个托管 MCP 服务,让 AI 智能体在云端操控真实 iPhone 和 Android 模拟器。Python812
  5. DIYgod/pinky在电脑上把真实 iPhone 或 Android 手机交给任意支持 MCP 的 AI agent 操作,高风险步骤由你审批。Go151