lijianfei.com

随着大语言模型在桌面端“Computer Use”能力的突飞猛进，让 AI Agent 代替人类操作操作系统已成为各大前沿实验室的必争之地。然而，相比于开放度极高的桌面系统或拥有完善 ADB 调试通道的 Android，苹果 iOS 生态因其极其严苛的安全沙盒、代码签名（Code Signing）、W^X 内存防护以及高度封闭的驱动接口，始终是自动化智能体难以攻克的“数字孤岛”。

近日，开源项目 iPhone Use（GitHub 仓库：zhongerxin/iPhone-use）以极其优雅的工程解法打破了这一僵局。该项目不仅让 OpenAI Codex 能够通过纯物理 USB 直连操控一台真实的非越狱 iPhone，更开创性地提出了一整套 Phone Use Agent（PUA） 交互协议、零外部依赖的标准库级 MCP 服务端、带租约的 MJPEG 屏幕流总线、Unicode 字形簇分段键入算法，以及颠覆性的“控件失效自动降级视觉坐标点击”容灾机制。本文将从系统拓扑、通信协议、容灾架构到交互渲染，对该项目的工程内核进行全景拆解。

1. 移动端 Agent 困境：为什么操控 iPhone 比桌面端难上百倍？

在桌面端（macOS / Linux / Windows），Agent 操控本质上是一套相对成熟的系统级 API 组合拳：拥有 root/sudo 权限的终端、系统级辅助功能无障碍（Accessibility）接口，或者直接调用 pyautogui、nut-js 等库向底层输入子系统分派事件。

但在未经越狱的物理真实 iPhone 上，自动化面临着四道难以逾越的天堑：

1. 没有系统级 Shell 与后台注入权限：iOS 严格禁止任何第三方守护进程常驻，应用间完全沙盒隔离，不存在类似 Android ADB 的万能调试桥；
2. 重型 Appium 框架的高延迟与脆弱性：业界传统的 iOS 自动化方案往往基于庞大的 Appium Server（臃肿的 Node.js 运行时、繁琐的会话管理、数百毫秒的 HTTP 往返延迟），在 Agent 多轮交互决策（ReAct Loop）中极其容易发生累积超时；
3. 无障碍树的“上下文爆炸”与性能泥潭：iOS 原生 Accessibility XML 树动辄数百层、数千个节点，体积动辄 100KB~500KB。一次完整的原生快照遍历甚至需要耗时 2~5 秒，直接撑爆大语言模型的上下文窗口并导致单次调用成本急剧攀升；
4. Agent 的选择器死循环幻觉：当 iOS 界面发生动态动画、弹窗遮挡、自绘 UI（Flutter / React Native / Unity）或标签缺失时，传统 Agent 往往会在 label、name 或 XPath 选择器中陷入“反复猜测、反复报错、反复重试”的逻辑死锁，最终耗尽 Token 并导致任务崩溃。

iPhone-use 的核心创新，正是针对上述工程痛点，量身定制了一套轻量、确定性、高容错且深度契合 Agent 决策链路的自愈型架构。

2. 系统拓扑总览：零依赖 USB 桥接与双通道并行设计

iPhone-use 摒弃了笨重的 Appium Server 中转，转而基于底层的 usbmuxd 协议与苹果 XCTest 自动化框架，构建了端到端的极简双通道通信架构。

flowchart TB
    subgraph HostMac ["macOS 宿主工作站 (Host Environment)"]
        subgraph CodexRuntime ["OpenAI Codex 桌面端 / CLI"]
            AgentBrain["Codex Agent 核心逻辑<br/>(Prompt / ReAct Loop)"]
            SidebarUI["Ext-Apps 实时屏幕侧边栏<br/>(ui/src/app.ts / Web Components)"]
        end

        subgraph MCPServer ["本地 MCP 协议服务 (server/iphone_use.py)"]
            StdioHandler["MCP Stdio 通信管道"]
            SetupEngine["SetupManager<br/>(Xcode构建 / 诊断 / 异步作业状态机)"]
            PhoneCtrl["PhoneController<br/>(状态机 / 坐标换算 / 容灾拦截)"]
            ScreenHub["ScreenHub<br/>(无依赖 MJPEG 帧切片 / 租约生命周期)"]
            TextEngine["wda_text.py<br/>(Unicode 字形簇分词 / 动态超时)"]
        end

        subgraph ForwardLayer ["轻量 Node 转发层 (tooling/)"]
            CmdForward["forward.mjs<br/>(127.0.0.1:18100 ➔ USB:8100 转发)"]
            StreamForward["screen-stream.mjs<br/>(USB:9100 ➔ MJPEG 标准流管道)"]
        end
    end

    subgraph PhysicalIPhone ["物理真实 iPhone (Unjailbroken iOS)"]
        subgraph UsbmuxdLayer ["usbmuxd 物理 USB-C / Lightning 数据总线"]
            Port8100["TCP 8100: WDA HTTP 控制通道"]
            Port9100["TCP 9100: WDA MJPEG 视频流通道"]
        end

        subgraph WDARunner ["WebDriverAgentRunner (XCTest 宿主)"]
            SpringBoardHook["SpringBoard 宿主注入 / 私有 XCTest 接口"]
            NativeAX["iOS 原生 Accessibility 辅助功能树"]
            InputSubsystem["XCTest 手势合成 (Tap / Swipe / Type)"]
            FrameCapturer["AVFoundation 屏幕帧采集模块"]
        end
    end

    AgentBrain <-->|"MCP 工具调用 (JSON-RPC 2.0)"| StdioHandler
    StdioHandler --> PhoneCtrl
    StdioHandler --> SetupEngine
    PhoneCtrl -->|"HTTP 请求 (127.0.0.1:18100)"| CmdForward
    CmdForward <-->|"appium-ios-device (usbmuxd)"| Port8100
    Port8100 <--> SpringBoardHook
    
    Port9100 -->|"独立 MJPEG 流 (TCP 9100)"| StreamForward
    StreamForward -->|"内存管道喂帧"| ScreenHub
    ScreenHub <-->|"UI 渲染事件 / 租约保活"| SidebarUI
    SidebarUI -.->|"用户反向交互 (点击/主屏幕/刷新)"| StdioHandler

该拓扑具备三大极其硬核的架构特色：

1. Python 服务端零外部 Pip 依赖：server/ 目录下的所有 Python 脚本（iphone_use.py、wda_controller.py、wda_setup.py、wda_screen.py、wda_text.py）均 完全依赖 Python 3.9+ 标准库（urllib、socket、xml.etree.ElementTree、fcntl、hashlib 等），免去了任何虚拟环境配置与 pip install 失败的风险；
2. 双通道数据流物理隔离：控制通道（端口 8100）与视频预览通道（端口 9100）在底层完全独立。屏幕视频流的高频 I/O 永远不会占用或阻塞控制通道的 HTTP 长轮询与锁机制；
3. 私有状态与跨进程安全隔离：运行时数据存放在本地专有的 ~/.local/share/iphone-use/ 目录中，目录权限严格锁定为 0700，配置文件与截图锁定为 0600，且强制排斥 Git 仓库目录，彻底杜绝证书或敏感快照泄露风险。

3. PUA 工具矩阵：乐观执行与认知卸载的协议哲学

在 iPhone-use 中，所有对手机的交互接口被统一封装在 PUA（Phone Use Agent）协议命名空间下。系统对外暴露了 17 个供大模型调用的工具，以及 2 个专供屏幕 Widget 内部使用的私有工具。

3.1 核心工具分工与语义边界

3.2 乐观执行（Optimistic Execution）设计哲学

传统自动化测试（如 Selenium 或 Appium 典型脚本）习惯于在每个动作后追加“强制断言”（例如：点击按钮后必须轮询 5 次等待页面元素改变）。但在大语言模型作为主控大脑的场景下，这种模式会导致极其严重的 “模型往返税”（Model Roundtrip Tax）。

iPhone-use 确立了清晰的执行准则：

• 默认 verify=false, observe="none"：点击、滑动或输入命令一旦被 WDA 底层接受，工具立即返回成功（action_complete=true），绝不为了证明“点击是否生效”而额外进行耗时数秒的 XML 树重读；
• 顺带校验（Piggyback Verification）：模型在规划下一个动作时，若确实需要下一页的信息，只需在本次调用中将 observe 设置为 "tree" 或 "screenshot"，在获取下一步决策上下文的同时顺带核验上一步的执行成果；
• 只有关键最终交付才显式验收：密码输入完成、表单最终提交、转账确认等不可逆操作，才显式传入 verify=true 或 expect 选择器。

4. 核心技术突破：容灾、分词与生命周期工程学

4.1 颠覆性的视觉降级机制：switch_to_coordinates

在大模型操作 UI 的过程中，最常遭遇的滑铁卢是：无障碍标签缺失或被前端框架覆盖。例如微信聊天气泡、小红书瀑布流卡片或游戏界面，底层的 Accessibility 树往往只有一个空白的 XCUIElementTypeOther。如果模型坚持寻找特定的 label，调用会直接抛出 no_such_element，导致传统 Agent 反复尝试构造 XPath 而卡死。

iPhone-use 在 server/wda_controller.py 中实现了一套极其精妙的 “失败自动降级视觉坐标” 闭环：

sequenceDiagram
    autonumber
    actor Model as Codex Agent
    participant Ctrl as PhoneController (wda_controller.py)
    participant WDA as WebDriverAgentRunner (iOS)

    Model->>Ctrl: 调用 pua_tap(selector={"label": "立即购买"})
    Ctrl->>WDA: POST /elements (查找谓词)
    WDA-->>Ctrl: 返回空列表 (未匹配到元素)
    Note over Ctrl: 触发 VISUAL_FAILURES 错误拦截器<br/>(switch_to_coordinates)
    Ctrl->>WDA: GET /screenshot (快速拉取底层 PNG 截图)
    WDA-->>Ctrl: 返回原始设备截图二进制
    Note over Ctrl: 1. 保存本地排障截图 (0600权限)<br/>2. 提取 JPEG/PNG 真实物理像素宽高<br/>3. 计算设备逻辑视口比例: pixel_to_point = [scale_x, scale_y]
    Ctrl-->>Model: 抛出 WDAError(no_such_element)<br/>附带 observation: { image, pixel_to_point: [0.333, 0.333] }
    Note over Model: 模型读取视觉截图与错误提示：<br/>严禁重试选择器，改用坐标点击！<br/>模型识别画面上的目标像素 (px=360, py=1200)<br/>计算逻辑点: x = 360 * 0.333 = 120, y = 1200 * 0.333 = 400
    Model->>Ctrl: 调用 pua_tap(x=120, y=400)
    Ctrl->>WDA: POST /wda/tap (直接下发物理坐标点击)
    WDA-->>Ctrl: 点击成功
    Ctrl-->>Model: 返回成功，业务流程畅通推进

通过这一机制，系统在底层强行将异常收敛：

1. 拦截所有视觉类失败（包括 no_such_element、ambiguous_target、occluded_target、offscreen_target、no_focused_field 等）；
2. 捕获瞬时屏幕图像，并通过 wda_image 模块精确解析设备的物理像素与逻辑点（Points）比例矩阵；
3. 将包含缩放比例和截图路径的上下文直接喂回大模型，强行引导模型执行 “基于截图像素点换算 -> 直接点坐标” 的自愈路径，彻底终结了选择器幻觉死循环。

4.2 保护 Unicode 字形簇的动态分段键入（wda_text.py）

向真实手机输入长文本（如中文段落、表情符号、URL）面临着底层物理限制：WDA 在 iOS 上是通过模拟硬件键盘事件逐字敲击的，速率被严格限制在约 每秒 30 个字符（TYPING_FREQUENCY = 30）。

如果让模型一次性输入 300 字的长文本，单次 HTTP 请求将在 iOS 端阻塞长达 10 秒以上，极易引发宿主 HTTP 超时、中间代理断开以及未可知的中断状态。

server/wda_text.py 实现了一套极其考究的 字形簇（Grapheme Cluster）安全切分算法：

# wda_text.py 核心字形簇安全边界判定抽象
def safe_boundary(text, index):
    if index <= 0 or index >= len(text):
        return True
    previous, following = text[index - 1], text[index]
    # 严禁在零宽连接符 (ZWJ) 或组合音调符号处截断
    if previous == ZERO_WIDTH_JOINER or _extends_previous(following):
        return False
    # 严禁截断 Windows / 网络标准换行符 \r\n
    if previous == "\r" and following == "\n":
        return False
    # 国旗表情是由两个 Regional Indicator 代码点配对组成的，必须成对切分
    if ord(previous) in REGIONAL_INDICATORS and ord(following) in REGIONAL_INDICATORS:
        run = 0
        cursor = index - 1
        while cursor >= 0 and ord(text[cursor]) in REGIONAL_INDICATORS:
            run += 1
            cursor -= 1
        return run % 2 == 0
    return True

该算法的精密之处体现在：

• 拒绝粗暴切分：普通字符串的 text[:200] 切分极易将复杂的复合 Emoji（如由肤色修饰符、性别符号和 ZWJ 连接的表情 👨‍👩‍👧‍👦，或由两个国家区域指示符拼成的国旗 🇨🇳）拦腰截断，导致手机端呈现为破坏性的方块问号乱码；
• 动态超时预估：通过 request_timeout(characters, frequency) 公式，根据切片字符量精准计算底层 HTTP 超时容限，既保证请求不提前超频挂死，又留出充分的网卡缓冲；
• 断点续传 Token（continue_token）：单次模型调用设置了严格的全局时间预算（CALL_BUDGET = 90s）。若长文本未能在一个调用周期内输完，服务层会返回 input_complete=false 与一个加密的 continue_token，模型只需在下轮对话中带回该 Token，即可实现无缝断点续输，严禁重复输入造成文字翻倍。

4.3 异步作业机与进程宿主安全防护（wda_setup.py）

编译、签名和拉起 WDA 涉及庞大的 xcodebuild 命令与私有证书握手，耗时通常长达 10~30 秒。若将其放在同步 MCP 请求中执行，会导致整个智能体终端假死甚至被宿主协议引擎强制 Kill。

server/wda_setup.py 设计了一套独立的 跨会话持久化作业状态机（Job State Machine）：

stateDiagram-v2
    [*] --> Queued: pua_setup(action="start")
    Queued --> Running: 派生独立 Worker 进程<br/>(分配 Job ID 与 Owner Token)
    
    state Running {
        [*] --> XcodeCheck: 校验本地完整 Xcode 环境
        XcodeCheck --> SourceVerify: 校验 WDA 源码 Pinned Commit
        SourceVerify --> CodeSign: 校验 Team ID 与 Bundle ID 签名配置
        CodeSign --> BuildAndDeploy: xcodebuild test 编译部署
        BuildAndDeploy --> PortForward: 唤起 Node 本地端口转发通道
    }

    Running --> Ready: /status 探针就绪且端口连通
    Running --> Failed: 触发错误分类器 (诊断注入)
    
    Failed --> [*]: 记录脱敏日志并提供自愈指引
    Ready --> [*]: 写入 runtime/config.json 固化配置

在进程管理上，作者注入了深刻的防御性编程思考：

• 进程组 Ownership Token 校验：派生的后台 Worker 进程拥有独立的 Process Group，并在命令参数中注入专有的 owner_token。当后续命令执行 stop 时，必须严格比对当前存活进程的命令行签名与 Token，绝对禁止盲目调用 killall xcodebuild 或按端口号误杀系统内其他无关的开发进程；
• 专家级错误模式诊断器（Heuristic Diagnoser）：
  • 自动识别个人开发者证书（Personal Team）的 3 个 App 数量上限报错（0xe8008029），提示用户人工清理而非盲目卸载；
  • 自动识别 XCTest 自动化未授权错误（xctdaemonerror code=41），引导开启 iOS 开发者选项中的 UI 自动化开关；
  • 自动检测 macOS 15 的“iPhone 镜像（iPhone Mirroring）”应用冲突，提示退出镜像以释放屏幕独占锁；
• 全链路敏感数据实时脱敏（Data Redaction）：系统在记录任何调试日志与错误输出前，强制通过全局正则清洗掉 Apple ID 邮箱、Bearer 授权令牌、私有密码与设备硬件序列号。

5. 实时屏幕流与 Ext-Apps 侧边栏：极致能效与双向交互

在 AI 操控手机的过程中，如果用户对手机当前发生的事情处于“盲盒”状态，不仅会造成极大的心理不安，遇到人脸识别或支付密码时更会直接失控。

iPhone-use 通过接入 Codex 的 @modelcontextprotocol/ext-apps 标准，在 Codex 桌面端侧边栏打造了一座拟真度极高的虚拟 iPhone 交互窗口。

flowchart LR
    subgraph StreamControl ["按需租约流控 (Lease-based Streaming)"]
        Widget["侧边栏 UI Widget"] -->|"轮询请求帧 (带时间戳)"| Hub["ScreenHub (wda_screen.py)"]
        Hub -->|"续租 5 秒 (FRAME_LEASE_SECONDS = 5)"| Lease["活动租约计时器"]
        Lease -.->|"5 秒内无前端拉取"| Sleep["立即切断 USB 视频流管道<br/>停止硬件编码，保护手机电池"]
    end

    subgraph FastParsing ["零依赖二进制帧解析"]
        StreamIn["MJPEG 裸数据流"] --> Parser["MJPEGParser (纯 bytearray 游标)"]
        Parser --> Marker["定位 SOI (0xFFD8) 与 EOI (0xFFD9)"]
        Marker --> SOF["读取 SOF 段标记 (0xC0~0xCF)"]
        SOF --> Dim["直接计算原图宽高，无需解码全量像素"]
    end

5.1 按需租约（Lease-Based Streaming）消灭发热与电量损耗

许多移动端投屏工具最大的缺陷是：只要后台服务启动，就持续不断地从手机硬解 60 帧视频流，导致 iPhone 在半小时内迅速发热、降频并剧烈掉电。

iPhone-use 引入了严格的 租约流控机制：

• 侧边栏 Widget 每次向 MCP 服务拉取帧时，仅授予服务一个极短的 5 秒租约（FRAME_LEASE_SECONDS = 5）；
• 如果用户最小化了 Codex、关闭了屏幕侧边栏或切换了会话，ScreenHub 会在 5 秒倒计时结束后瞬间终止底层的 screen-stream.mjs 进程，切断 USB 数据管道；
• 手机端的 AVFoundation 采集模块随之休眠，整机功耗瞬间归零。

5.2 纯内存级轻量 JPEG 解析器

为了在 Python 端不引入 Pillow（PIL）或 OpenCV 等任何 C 扩展库，作者在 server/wda_screen.py 中纯手写了一个高效的 MJPEGParser：

• 在连续字节流中动态维护内存游标，精准识别 JPEG 的起始标记 0xFF 0xD8（SOI）与结束标记 0xFF 0xD9（EOI）；
• 通过直接解析 JPEG 标头中的 SOF（Start of Frame）标记段，在完全不解码完整图像像素矩阵的前提下，直接读取出当前画面的宽高分辨率；
• 内存开销严格受限（MAX_FRAME_BYTES = 4MB），杜绝了长周期运行下的内存泄露隐患。

5.3 隐私隔离与双向交互闭环

在交互设计上，前端 Widget（ui/src/app.ts）与底层控制层形成了优雅的双向协同：

• 光效指引与手势波纹：当 Codex 模型在后台执行 pua_tap 或 pua_swipe 时，控制器会向前端屏幕总线广播动作坐标，Widget 屏幕上会即时泛起柔和的拟真水波纹与操作光标（Cursor Effect），让用户直观“看清 AI 的每一步操作”；
• 反向物理操控：用户可以直接用鼠标在侧边栏的 iPhone 画面上进行点击、按住拖动或双指滚动，底层通过 screen_action 直接将坐标打入手机；底部常驻的「主屏幕」、「刷新」与「截图到剪贴板」按钮为人工接管提供了极佳的人性化兜底；
• 隐私接管协议（Authentication Takeover）：当遇到短信验证码、银行密码或 Face ID / Touch ID 鉴权时，系统会自动将屏幕流标记为 paused（原因标记为 authentication 或 device_locked），停止将画面向大模型返回，并调用宿主提示用户亲自在物理机上完成生物识别，认证通过后再显式恢复任务。

6. 实战体验：让 Codex 操控真实 iPhone 的标准流程

要在你自己的 Mac 与真实 iPhone 上跑通 iPhone-use，完全不需要手动去敲复杂的 Xcode 编译命令。整个流程已经被封装为极简的自动化引导。

第一步：准备物理连接与环境

1. 使用 USB-C 或 Lightning 数据线将 iPhone 连接到 Mac；
2. 在 iPhone 上解锁屏幕，并在弹出的对话框中点击 “信任此电脑”；
3. 打开 iPhone 的 「设置」->「隐私与安全性」->「开发者模式」，开启并按提示重启设备（iOS 16+ 必需）；
4. 确保 Mac 上安装了完整的 Xcode，并在 Xcode 的 Settings -> Accounts 中登录了自己的 Apple ID（免费的个人开发者账号即可）。

第二步：安装插件与服务

将仓库克隆至本地并执行一键安装脚本：

git clone https://github.com/zhongerxin/iPhone-use.git
cd iPhone-use
sh scripts/install.sh

该脚本会自动通过 Codex CLI 注册本地插件市场，将标准 MCP 服务接入 Codex。

第三步：对话式引导拉起

在 Codex 桌面端中新开一个聊天，直接贴入以下指令：

“请使用 iphone-use-setup 帮我配置通过 USB 连接的 iPhone，安装并启动 WDA，验证 READY，然后打开手机屏幕。”

Codex 会自动调用 pua_doctor 诊断环境，调用 pua_setup(action="discover") 探测你的真实设备 UDID，引导你确认 Apple Team ID，随后在后台静默完成 WDA 的签名、构建与拉起。当服务验证 pua_ready 返回 ready=true 时，侧边栏便会优雅地弹出一台实时跳动着画面的 iPhone！

此时，你就可以尽情用自然语言指挥它：

• “用 iPhone Use 打开备忘录，新建一条清单，记下今天的开会要点。”
• “打开大众点评，搜索附近的精品咖啡馆，把排名前三家的名字和人均价格整理给我。”
• “帮我读取相册最近的一张发票照片，通过 AirDrop 发回当前这台 Mac 的下载目录。”

7. 架构启示：移动端智能体设计的工程准则

从逆向工程与系统架构的角度审视，iPhone-use 的设计为当下火热的 Agent 基础设施研发带来了极具参考价值的范式转变：

1. “去中间件化”是保证 Agent 低延迟的第一要义：传统的自动化往往热衷于在被测设备与主控端之间搭建层层抽象（从 Appium、Selenium 到各种代理网关）。iPhone-use 证明，直面底层的 usbmuxd 端口映射与标准库 HTTP 客户端，能够将通信延迟削减一个数量级，真正满足大模型实时决策的吞吐需求；
2. 符号与视觉的双轨互补（Dual-Rail Resilience）：纯视觉 Agent（VLM 直接截屏点坐标）速度慢且 Token 消耗巨大；纯语义 Agent（仅依赖 DOM/AX 树）在复杂 App 中极易脆弱断裂。“平时靠语义树高速推进，异常时凭截图坐标智能兜底” 的双轨架构，是兼顾速度、成本与健壮性的终极解法；
3. 把不确定性关进底层框架的笼子：移动端环境充满了不可预测的网络抖动、手势惯性与浮层打断。通过在协议层设计乐观执行、动态字形分词、断点续传 Token 与严格的进程 Ownership 隔离，上层大模型才能摆脱底层的脏活累活，专注于高阶业务逻辑的推理与规划。

原文链接与参考资料

• GitHub 开源仓库：zhongerxin/iPhone-use
• 底层驱动参考：Appium WebDriverAgent
• 底层 USB 通信库：appium-ios-device
• Codex Apps 扩展标准：@modelcontextprotocol/ext-apps