技术拆解 021｜iPhone-use：让 Codex 通过 USB 操作真实 iPhone，四天 1719 星

10 月 6 日，GitHub 上出现仓库 zhongerxin/iPhone-use，中文名就是它的一句话定位：让 Codex 通过 USB 操作真实 iPhone。四天后星数到 1719。用自然语言描述任务，Codex 打开 App、读页面、点击、滚动、输入文字、整理列表，侧边栏里实时显示手机屏幕。技术栈是 Python 写的本地 MCP 服务，配上 Codex 插件体系和屏幕侧边栏 widget。有意思的是 README 里写着「仓库目前为私有」，而仓库实际公开可访问，这个矛盾后文说。这篇按六件事拆：是什么、为什么现在、核心机制、数字与边界、怎么跑、价值判断。

一、它是什么

一个 Codex 插件，装在本机之后，agent 可以操作你自己的真机 iPhone。能力面写在功能表里：App 导航与操作，页面读取，点击与手势，中文与长文本输入，连续任务，列表搜索与采集，实时手机屏幕。全部动作走 USB 线，画面不出本机。

组成三块。本地 MCP 服务，server 目录 3921 行 Python；两个技能包，iphone-use 与 iphone-use-setup，分别管使用与安装；实时屏幕 widget，带 iPhone 外壳、操作光效、点击与拖动提示。工具名统一以 pua_ 开头，PUA 是 Phone Use Agent 的缩写，0.3.6 版从 wda_ 前缀改过来。最新版 0.3.8，落款 10 月 9 日。作者 ZHONG XIN，中文开发者项目，README 中文为主，附英文版，协议 MIT。

生态位先说清楚。它不发明底层：跑在手机上的执行服务是 WebDriverAgent，Appium 生态打磨多年的组件；USB 设备通信与端口转发来自 appium-ios-device。项目自己做的是把这条通道接进 Codex 的插件体系，外加安装引导、工具分层和屏幕体验。

发布形态值得注意。git 历史只有一次提交，80 个文件一次落库，0.2.x 到 0.3.7 的演进过程只留在更新记录里。开源快，交出来的却是一份成品仓。

README 尾部有一句「仓库目前为私有，需要有 GitHub 访问权限，或者使用已取得的源代码包」。仓库当前公开可访问、可 clone，GitHub 上能看到 1719 星。声明与实际状态不一致，可能是历史遗留。把它写出来，因为它影响你对这个仓库的预期：这份代码按成品交付的口径维护，参与式的贡献文化未必在这里。

二、为什么现在值得看

三个理由。

第一，agent 操作计算机是这一年落地最密的方向。操作桌面、操作浏览器都有成熟方案在跑，模型看屏幕、动指针的能力被各家推着涨。手机是真机里最难的一段，iOS 尤其封闭，agent 想碰真 iPhone，此前一直缺公开可用的工程样本。

第二，MCP 生态把接入成本降下来了。工具怎么挂进 agent，标准已经统一，剩下的问题是挂什么。iOS 自动化测试积累多年的 WebDriverAgent，此前主要服务测试脚本，还没人按 agent 的使用方式重新包一遍。iPhone-use 补的正是这个空位。

第三，它示范了一条务实路线。底层全部复用成熟组件，力气花在 agent 体验的分寸上：怎么省上下文，失败了怎么兜底，危险动作怎么留给人。这些分寸决定 agent 工具能不能日常用，比底层新东西更值得照着学。

三、核心技术机制

四件东西：USB 通道、工具面、截图回退、安装即用提示词。逐个说。

WDA over USB 通道。 WebDriverAgent 跑在手机上，负责把指令变成 iOS 里的真实操作。本机的 Python MCP 服务通过 appium-ios-device 与 USB 设备通信，做端口转发，默认走本机 18100 端口，远程地址会被拒绝。设计口径写得很直白：运行数据和签名构建保留在本机。代价是前置依赖重。macOS、完整 Xcode（仅 Command Line Tools 不够）、Xcode 里可用的 Apple 账号与开发团队、USB 连接的真机，再加自己完成 WDA Runner 的签名与启动。这是苹果签名链决定的门槛，绕不开。

17+2 工具面。 模型可用 17 个工具，另有 2 个仅供屏幕 widget 使用。分层清晰。pua_doctor 管环境诊断，pua_setup 管设备配置，pua_ready 管就绪检查，诊断三件套，任何任务开始前先过一遍。观察层两件，pua_observe 返回紧凑控件树加截图，pua_find 做目标查询。操作层覆盖点击、滑动、实体按键、Unicode 文字输入与有界等待。效率组合三件值得细看：pua_batch 把已知步骤一次打包执行，减少模型往返；pua_scroll_find 有界滚动查找，一次最多滑一次，找不到可点击目标就暂停，不盲滑；pua_collect_list 做列表采集，带覆盖边界与去重。观察设计处处在省 token。控件树省略重复字段，仅需截图时不生成 XML；0.3.7 版把整页 XML 排除掉未使用的 accessible 属性，按更新日志自述，微信、淘宝、相册页面的原始 XML 缩小约 7% 到 8%，节点内容不变。

截图回退双模定位。 这是 agent 鲁棒性上最值得记的设计。控件定位失败时，工具不是报错了事，而是返回当前截图与处理指引；模型看图选位置，图像像素乘以 image.pixel_to_point 换算成 iPhone 点坐标，再交给 pua_tap 点击。控件被遮挡、输入焦点丢失、控件树不完整时同样处理，看新截图重新选点。等于把元素找不到就换眼睛看、按坐标点这套兜底写进了工具协议，而不是指望模型临场发挥。已有截图直接复用，不自动盲滑、不重放操作。

安装即用提示词。 安装文档被产品化成对 agent 说的一段话。README 给出可直接粘贴的自然语言：让 Codex 自己读仓库文档与安装脚本，检查本机依赖，跑 install.sh，读取 setup 技能，发现设备，用使用者自己的开发团队签名 WDA，构建启动，直到 pua_ready 返回 ready=true，并明确写上「不要照搬作者的设备标识或签名信息」。安装任务全程异步：下载、构建、启动都返回可查询的工作 ID，重复 setup 会复用进行中的工作，start 默认最多等 20 秒，超时后按同一任务继续查询，不重复启动。

四、数字与边界

数字摆全：1719 星（10 月 10 日时点，四天）；35 个 py/ts/js 文件，server 目录 3921 行 Python；git 追踪 80 个文件，单次提交；0.3.8 版落款 10 月 9 日；MIT 协议；中英双语 README。

边界说四条。

其一，星数量的是题目热度。「让 agent 操作真 iPhone」自带传播力，四天 1719 星里有多少会变成日常使用者，现在看不出来。仓库没有使用规模数据，效果描述全部出自 README 与更新日志的自述口径。

其二，安全边界是它最见分寸的部分，三根支柱。输入与提交分开：工具默认不提交文字，模型需要核对关键页面、接收人、数量和最终结果，最后一步留给人确认。认证交还人类：密码、验证码、Face ID 由用户本人完成，接管期间可以暂停预览。屏幕流不落盘：预览画面不写磁盘，明确调用的截图有保留上限，运行目录权限 700。另有跨进程的操作锁与明确失败语义，动作超时或断线会被标记为不确定，先读实际状态再决定下一步，避免盲目重放。

其三，埋点默认开启。插件向独立的 PostHog 项目匿名上报启动、工具调用、连接状态、耗时和错误类别，用随机安装 UUID 标识，官方文档写明不上传画面、输入内容、设备标识、无障碍树、剪贴板、bundle ID、UDID、签名团队与文件路径，也没有人物档案与 GeoIP。想关可以设 IPHONE_USE_ANALYTICS=0 或 DO_NOT_TRACK=1，重启服务生效。字段清单收得克制，但默认开启这一点，与多数本地工具默认安静的预期不同。装完就想清楚要不要关，是合理要求。

其四，依赖门槛重。完整 Xcode、开发团队签名、USB 真机，三样把大量非 iOS 开发者挡在门外。跑起来的前提，要么你本来就会这套签名流程，要么愿意照着文档完整走一遍。

五、怎么跑、谁能玩

完整准备清单：一台 Mac 与 Codex 桌面端或 CLI；完整 Xcode 且完成过首次启动配置；Xcode 里可用的 Apple 账号与开发团队；一台 USB 连接的 iPhone。然后 clone 仓库，sh scripts/install.sh，重开聊天加载工具，把 README 那段安装提示词粘给 Codex，剩下的检查、签名、构建、启动由它自己走。有两类动作必须本人完成：Apple 账号登录、设备信任、开发者模式开启、手机解锁，这些 Codex 会停下来等你；以及一切涉及密码、验证码、Face ID 的认证环节。pua_ready 返回 ready=true 之后才开始真机任务，已配置过的设备复用已有构建，不用每次重装。

分三类人说。iOS 开发者与测试工程师：WDA 这套你们熟，插件把它变成日常可用的 agent 入口，改造成本最低，收益直接。做 agent 工具的人：17+2 的工具分层、紧凑观察、截图回退、输入与提交分开，都是可以整段搬走的参考实现。只想体验的人：门槛在苹果签名链，不在 AI；装不动的部分，读 README 的依赖表与那段安装提示词，本身就有参考价值。

六、价值判断与适合谁

样本价值：高。底层没有新发明，WDA 与 USB 通信都是成熟组件；它的分量在组装与分寸。判断一个 agent 工具的真实完成度，我看三处：观察是否省上下文，失败是否有语义，危险动作是否有边界。三处它都给了工程答案：紧凑控件树与按需截图，截图回退与明确失败语义，输入提交分开加认证交还人类。这三条不挑平台，桌面 agent、浏览器 agent、Android 真机同样适用，搬走就能用。

边界再钉一次：星数是题目热度，不是使用规模；效果是自述口径，没有第三方评测；签名链门槛把多数人挡在外面，这不算缺点，是真机自动化的本钱。

一句话判断：iPhone-use 把 agent 动真设备最要紧的三件事，看得省、失败会兜底、危险留给人，写进了工具设计，「AI 会用手机」只是它的题目。真机自动化从来不缺演示，缺的是这种带分寸的工程。

参考来源

• 仓库本体：github.com/zhongerxin/iPhone-use（本地 clone 后逐项比对 README、CHANGELOG、ANALYTICS.md、plugin.json、server 源码结构与 git log；未执行任何构建与安装）
• Appium WebDriverAgent 与 appium-ios-device（依赖组件，README 致谢节声明）
• 星数 1719★ 为 2026-10-10 时点数据，仍在变化