lijianfei.com

长期以来，让 AI 智能体（Agent）自动化接管并操控一部真实的 iPhone，一直是移动端工程领域的硬骨头。传统的方案（无论是 WebDriverAgent、Appium 还是各类投屏自动化脚本）都极度依赖外接 Mac 主机与长长的 USB 数据线，不仅通信链路冗长脆弱，一旦遇到应用沙盒隔离、熄屏锁屏或系统弹窗就极易断流卡死。

最近我在深入研读开源项目 witchan/ios-mcp 的源码时发现，作者另辟蹊径，直接把 Model Context Protocol（MCP）服务做成越狱插件打入了 iOS 的核心心脏 —— SpringBoard。整部 iPhone 无需任何宿主电脑辅助，通过局域网暴露一套标准 JSON-RPC 2.0 接口，直接向 Claude、Cursor 等 AI 客户端交付了 46 个原生工具。本文我将深入拆解其系统级常驻、点位归一化、跨进程无障碍透传与多进程容错架构。

移动端智能体的架构困局与原生 MCP 破局

在桌面端（macOS/Windows/Linux），AI Agent 通过 MCP 获取终端权限、文件系统与浏览器驱动已经非常成熟。但移动操作系统天然具备严苛的沙盒机制与权限屏障，过去的主流移动端操控方案普遍存在三大硬伤：

1. 主机强依赖与线缆羁绊：依赖 Mac 上运行的 Xcode 调试服务或 WDA（WebDriverAgent），设备无法脱离电脑独立行动；
2. 坐标系尺度混乱：iPhone 的 Retina 视网膜屏幕存在物理像素（Pixel）、逻辑点（Point）以及“放大显示”（Display Zoom）下物理采样的 nativeScale 差异，视觉多模态大模型给出的坐标往往需要复杂的数学折算，极易点击偏移；
3. 系统核心与第三方进程隔离：普通应用沙盒无法读取全局视图层级，更无法获取跨进程的统一日志（Unified Logging）与底层硬件按键事件。

witchan/ios-mcp 的解法非常干脆：借助越狱环境，直接让 MCP 服务成为 SpringBoard 进程的一部分。

flowchart TD
    subgraph Client ["AI 智能体客户端 (Claude / Cursor / OpenAPI)"]
        Agent["AI Agent / LLM 核心"]
    end

    subgraph iPhone ["iPhone (越狱系统 SpringBoard 宿主)"]
        MCPServer["MCPServer (HTTP + JSON-RPC 2.0 / Port 8090)"]
        
        subgraph Subsystems ["系统能力子系统"]
            HID["HIDManager (IOHIDEvent / 物理按键 / 触控手势)"]
            Screen["ScreenManager (点位归一化截屏 / 几何方向判定)"]
            AX["AccessibilityManager (AXRuntime / 跨进程 UI 树透传)"]
            App["AppManager (LSApplicationWorkspace / AppSync / 沙盒透视)"]
        end

        subgraph Helpers ["进程级隔离外挂服务"]
            Worker["mcp-ocr-worker (ONNX Runtime CPU + PaddleOCR)"]
            LogReader["mcp-logreader (diagnosticd 实时日志流)"]
            RootHelper["mcp-root (白名单受限提权工具)"]
        end
    end

    Agent <-->|"局域网 HTTP (MCP 协议 2025-11-25)"| MCPServer
    MCPServer --> Subsystems
    MCPServer <-->|"UNIX Domain Socket (socketpair)"| Worker
    MCPServer -->|"Mach-O Spawn (com.apple.private.logging.stream)"| LogReader
    MCPServer -->|"Setuid Root (严格参数校验)"| RootHelper

AI 客户端只需在配置中添加一条简单的 SSE/HTTP MCP 服务端地址：

{
  "mcpServers": {
    "iphone": {
      "url": "http://192.168.1.100:8090/mcp"
    }
  }
}

整部 iPhone 的触控、按键、屏幕、应用安装、UI 树与逆向日志探针，便全量映射成了大模型可调用的 Tools。

一、为什么寄宿在 SpringBoard？生命周期与自愈设计

很多初次接触 iOS 越狱开发的人会问：为什么不写一个独立的 LaunchDaemon 后台守护进程，而要通过 MobileSubstrate / ElleKit 把动态库注入到 SpringBoard？

我在阅读 Tweak.x 与 MCPServer.m 时深感作者的架构取舍非常精准：

• 顶层视窗与事件中枢：SpringBoard 是 iOS 的“桌面与系统管理器”，全局唯一的触摸分发队列、屏幕旋转矩阵、按键拦截和锁屏状态全部汇聚于此。一个独立的 LaunchDaemon 进程哪怕拥有 root 权限，也难以直接拦截并注入原生的 UIKit/Quartz 视窗上下文；
• 免握手访问私有框架：SpringBoard 原生加载了 FrontBoard、BackBoardServices、Accessibility 等内部框架，很多非导出的内部 C 符号无需通过跨进程 IPC 即可直接 dlsym 调用。

但注入 SpringBoard 带来的最大挑战是：系统注销（Respring / sbreload）与启动时序极不稳定。

如果仅仅挂钩 - [SpringBoard applicationDidFinishLaunching:]，在部分 rootful 或 Substitute 环境下，该通知可能被推迟到用户发生首次物理 Home 键交互后才触发，导致手机刚注销重启后 MCP 无法连接。

作者在 Tweak.x 中实现了一套极其严密的构造函数立即启动 + 指数级延迟退避（Exponential Retry）组合拳：

// Tweak.x 中的自愈启动时序
static void ios_mcp_schedule_bootstrap_autostart(NSString *reason) {
    if (!ios_mcp_is_springboard_process()) {
        return;
    }

    // 梯度延迟探测，确保即使 SpringBoard 启动初期端口被占用或 runloop 未准备好也能自愈
    const NSTimeInterval delays[] = {0.2, 1.0, 2.0, 5.0, 10.0, 20.0};
    const size_t count = sizeof(delays) / sizeof(delays[0]);
    for (size_t i = 0; i < count; i++) {
        NSString *attemptReason = [NSString stringWithFormat:@"%@#%zu", reason ?: @"bootstrap", i + 1];
        ios_mcp_schedule_autostart_attempt(attemptReason, delays[i]);
    }
}

__attribute__((constructor)) static void ios_mcp_init(void) {
    IOS_MCP_LOG(@"dylib loaded into process: %@", [[NSProcessInfo processInfo] processName]);
    ios_mcp_register_control_notifications();

    if (ios_mcp_is_springboard_process()) {
        ios_mcp_register_lifecycle_notifications();
        // 构造函数加载阶段立即尝试首轮启动
        ios_mcp_autostart_if_needed(@"constructor-immediate");
        // 同时排期梯度重试，提供双重兜底
        ios_mcp_schedule_bootstrap_autostart(@"constructor");
    }
}

无论设备是开机冷启动、还是通过 SSH 执行 sbreload、抑或用户在“设置”面板中关闭后重新开启，服务都能在几百毫秒内迅速拉起，完全不需要人工掏出手机解锁干预。

二、破解多倍率屏幕：点位归一化（Point-Space）与精准手势流

做过自动化视觉对齐的人，几乎都踩过 Retina 缩放率与显示缩放（Display Zoom）的深坑。

• iPhone 的实际物理渲染分辨率是像素（Pixels），如 1170 x 2532；
• UIKit 控件布局使用逻辑点（Points），如 390 x 844（scale 为 @3x）；
• 若开启了“显示缩放”，系统会以非整数比率进行采样重渲染，此时 UIScreen.mainScreen.scale 与 nativeScale 并不相等；
• 一旦屏幕发生横屏或倒转，屏幕实际坐标系还会伴随矩阵仿射变换。

如果把原始的高清截图像素直接传给 AI 多模态模型，大模型识别到的文字坐标是物理像素，而传递给操作系统的触摸指令却需要逻辑点，Agent 就必须反复计算缩放系数，稍有不慎就会点偏。

1. 截图端的“点对点”归一化（Point-Sized Screenshot）

ScreenManager.m 采用了非常惊艳的设计：截屏即点位。

// ScreenManager.m 中的核心尺度计算
static CGSize MCPPointSizeForPixelSize(CGSize pixelSize) {
    if (pixelSize.width < 1.0 || pixelSize.height < 1.0) return CGSizeZero;

    CGSize screenSize = [UIScreen mainScreen].fixedCoordinateSpace.bounds.size;
    CGFloat pointLongEdge = MAX(screenSize.width, screenSize.height);
    if (pointLongEdge < 1.0) return CGSizeZero;

    CGFloat pixelLongEdge = MAX(pixelSize.width, pixelSize.height);
    CGFloat ratio = pixelLongEdge / pointLongEdge;
    if (ratio <= 1.01) return CGSizeZero; // 已是点位尺寸

    // 动态向下重采样至 1 图片像素 = 1 屏幕逻辑点
    return CGSizeMake(MAX(round(pixelSize.width / ratio), 1.0),
                      MAX(round(pixelSize.height / ratio), 1.0));
}

系统抓取到底层 Framebuffer 图像后，会立刻按照当前设备的真实长短边比例重采样。这意味着：大模型在返回的 Base64 截屏图片上量出的像素值，就是底层的逻辑点数值。

不仅如此，get_ui_elements 吐出的无障碍节点 Bounds、ocr_screen 吐出的文字位置，全部统一落在同一尺度空间中。Agent 看到什么坐标，就直接将什么坐标原封不动传给 tap_screen，彻底消除了换算心智负担。

2. 底层 IOHIDEvent 手势拟真与 50ms 延时哲学

在触控下发层，HIDManager.m 绕过了易被反作弊检测的私有 UIWindow 手势派发，直接在 IOKit 层构造原生数字转换器事件（IOHIDDigitizerEvent）：

// 构造原生手指事件
IOHIDEventRef child = IOHIDEventCreateDigitizerFingerEvent(
    kCFAllocatorDefault,
    mach_absolute_time(),
    index,
    3,
    eventMask,
    normalizedTouchX(point.x), // 归一化到 0.0 ~ 1.0
    normalizedTouchY(point.y),
    0.0f, 0.0f, 0.0f,
    range, touch, 0
);

而在实现单击（Tap）序列时，代码中有一处极其用心的细节：

// Keep a tap down long enough for UIKit controls such as UISwitch to observe it as a real touch.
static const useconds_t kIOSMCPTapPhaseDelayUs = 50 * 1000; // 50毫秒延时

- (BOOL)performTapSequenceAtPoint:(CGPoint)point error:(NSString **)error {
    if (![self performTouchAtPoint:point phase:TouchPhaseBegan error:error]) return NO;
    usleep(kIOSMCPTapPhaseDelayUs);

    if (![self performTouchAtPoint:point phase:TouchPhaseMoved error:error]) return NO;
    usleep(kIOSMCPTapPhaseDelayUs);

    return [self performTouchAtPoint:point phase:TouchPhaseEnded error:error];
}

如果连续在零微秒间隔内下发 Began 与 Ended，底层 UIKit 的 RunLoop 事件合并机制会直接将两个事件当做抖动丢弃，导致如 UISwitch、复选框或长列表项无法响应。加上精心调优的 50ms 状态间隔，能确保系统控件将其作为一次真实的手指按压并顺利触发状态切换。

三、穿透沙盒：跨进程 AXUIElement 树提取机制

在许多没有提供标准 Accessibility 标签或结构复杂的界面上，AI 如果仅仅依靠视觉多模态，容易出现幻觉。而 ios-mcp 的核心王牌之一，就是长达几千行的无障碍解析引擎（MCPAXNodeSource.m 与 MCPAXRemoteContextResolver.m）。

sequenceDiagram
    autonumber
    actor Agent as AI 客户端
    participant Server as MCPServer (SpringBoard)
    participant Resolver as MCPAXRemoteContextResolver
    participant FB as FrontBoard / AXRuntime
    participant App as 目标前台 App

    Agent->>Server: tools/call: get_ui_elements
    Server->>Resolver: 解析当前前台进程上下文 (PID & Scene)
    Resolver->>FB: 查询 AXFrontBoardFocusedApps()
    FB-->>Resolver: 返回前台活动进程 PID (如 2841)
    Resolver->>FB: 模拟 XCTest 行为 (__AXSetRequestingClient: 2)
    Resolver->>App: AXUIElementCreateApplication(PID)
    App-->>Resolver: 跨进程 IPC 获取根无障碍节点
    Resolver->>Server: 递归提取 (Role, Title, Label, Frame, Identifier)
    Server-->>Agent: 返回完整 JSON 节点树 (附带统一点位 Bounds)

在 iOS 内部，无障碍层级是通过 AXRuntime.framework 建立的进程间通信。普通应用没有权限跨越沙盒去遍历别的进程，但 SpringBoard 拥有最高控制权。

项目通过 dlsym 动态加载私有符号：

• AXFrontBoardFocusedApps()：动态嗅探当前屏幕正在焦点的应用 PID；
• AXSetRequestingClient(2) / AXOverrideRequestingClientTypeFunc：将当前调用方的客户端身份伪装为 XCTest。这是整个逆向工程中极其精妙的一笔 —— iOS 系统的无障碍守护程序对 XCTest 拥有极高的信任级，一旦模拟此身份，即可绕过大量常规限制，批量提取多进程联合上下文；
• AXUIElementCopyMultipleAttributeValues：通过单次 IPC 批量拉取 Role、Title、Value、Frame 与 Traits，避免了海量小包 IPC 导致的卡死现象。

如果遇到 Flutter、React Native 或游戏引擎自绘的纯画布容器（无障碍树只返回一个孤立的 FlutterView），系统也会在返回值中优雅提示，引导 AI 快速回退到视觉 OCR 与坐标点击方案。

四、双擎 OCR 与独立 Worker 容错隔离体系

文字识别是视觉自动化闭环的核心。很多开发者第一反应是直接在 SpringBoard 里面引入一个 OCR 框架。然而，在 SpringBoard 进程内直接运行深度学习推理模型，几乎等同于自杀：

1. iOS Jetsam 内存红线：SpringBoard 的内存占用上限受到内核强监管，一旦加载大尺寸神经网络模型导致内存突增（Spike），内核会立即触发 Jetsam 将 SpringBoard 强杀，手机立刻黑屏进入 Safe Mode；
2. C++ ABI 冲突：ONNX Runtime 和 OpenCV 依赖特定的 C++ 运行时，与 SpringBoard 内的原生库混合编译极易发生符号冲突。

为此，ios-mcp 构建了极为硬核的子进程隔离架构：

flowchart LR
    subgraph SpringBoard ["SpringBoard (主进程)"]
        OCRManager["OCRManager (路由分发器)"]
        PaddleMgr["PaddleOCRManager"]
        VisionEngine["VisionOCREngine (Apple Vision)"]
    end

    subgraph Subprocess ["独立沙盒进程 (/usr/libexec/ios-mcp/mcp-ocr-worker)"]
        WorkerMain["mcp-ocr-worker"]
        ORT["ONNX Runtime 1.20.1 (CPU EP)"]
        Paddle["PP-OCRv5 Mobile (Det + Rec)"]
        CV["OpenCV 4.10.0 + Clipper"]
    end

    OCRManager -->|"engine='vision' (iOS 13+ 系统原生)"| VisionEngine
    OCRManager -->|"engine='paddleocr' (默认)"| PaddleMgr
    PaddleMgr <-->|"UNIX Domain Socket (socketpair)"| WorkerMain
    WorkerMain --> ORT
    WorkerMain --> Paddle
    WorkerMain --> CV

1. 基于 socketpair 的高安全 IPC 通道

PaddleOCRManager.m 并不是通过笨拙的文件读写或外部 Shell 命令传参，而是在启动子进程时创建了一对全双工的 UNIX 域套接字（socketpair(AF_UNIX, SOCK_STREAM, 0, pair)）。

这里还有一个极其老练的底层文件描述符保护技巧：

// SpringBoard 可能关闭了标准描述符 (0, 1, 2)
// 强制将 IPC 描述符转移到 >= 3 的高位，防止被子进程重定向劫持
static BOOL MCPKeepFDAboveStdio(int *fd) {
    if (*fd >= 3) return YES;
    int moved = fcntl(*fd, F_DUPFD_CLOEXEC, 3);
    if (moved < 0) return NO;
    close(*fd);
    *fd = moved;
    return YES;
}

2. 双引擎互补矩阵

在实际使用时，系统支持灵活路由：

当调用 describe_screen(include_ocr=true) 时，系统能并发拉取无障碍节点与 OCR 文本框，两两校验，形成极其可靠的界面感知护城河。

五、状态机感知：锁屏守卫与智能唤醒链

在实际跑自动化的过程中，最容易造成灾难的场景莫过于：设备息屏或锁屏了，Agent 却毫不知情，依然在盲目点击。

在锁屏状态下随意触发点击或滑动，轻则触发密码输入框多次错误导致设备停用数小时，重则在后台唤醒不可预期的功能。

1. 严格的状态拦截（Lock Guard）

MCPServer.m 在每个指令执行前，都会通过 SpringBoard 的底层上下文检查设备屏幕与锁屏状态：

设备处于 Locked / Screen Off 状态
       │
       ├──> 拦截破坏性指令 (Blocked)
       │    ├── tap_screen / swipe_screen / drag_and_drop
       │    ├── input_text / type_text / press_key
       │    ├── launch_app / kill_app
       │    └── run_command / write_file
       │
       └──> 仅放行状态观测与恢复指令 (Allowed)
            ├── screenshot / get_screen_info / get_frontmost_app
            └── wake_and_home

2. wake_and_home 自适应唤醒流水线

在 iOS 设备上，单一的“Home 键”并不等于“解锁回到桌面”。如果屏幕完全熄灭，按下 Home 只是点亮屏幕；如果已经处于锁屏界面，点按 Home 才是请求解锁或退回主屏。

项目专门设计了 wake_and_home 复合动作：

flowchart TD
    Start["调用 wake_and_home(sequence='auto')"] --> CheckState{"探测当前屏幕状态"}
    CheckState -- "屏幕处于熄屏 (screen_off)" --> Seq1["先发送 Power (点亮屏幕)<br/>延时等待 250ms<br/>再发送 Home (进入解锁流程)"]
    CheckState -- "屏幕已点亮但处于锁屏" --> Seq2["连续发送两次 Home 键<br/>(规避通知中心/锁屏封面驻留)"]
    Seq1 --> Verify["截图与 get_frontmost_app 验证是否抵达 SpringBoard"]
    Seq2 --> Verify

这一整套自适应逻辑把人工操作 iPhone 的直觉全部固化成了底层的防呆策略。

六、逆向级探针：无 Root 实时日志与白名单提权

除了常规的 UI 操作，ios-mcp 还包含了大量让逆向安全研究员狂喜的高级调试能力。

1. get_syslog 与系统日志实时串流

过去要看全系统的实时 os_log（即 macOS Console.app 看到的内容），必须插着 USB 线跑 log stream。

项目附带了一个轻量级二进制 mcp-logreader。它并没有使用危险的 root 权限，而是仅依靠打包时伪签的特权 Entitlement：

<key>com.apple.private.logging.stream</key>
<true/>

借助这个特权，它能直接通过 LoggingSupport.framework 中的私有类 OSLogEventLiveStream，在指定的时间窗口内（如 5 秒）监听系统的 diagnosticd 守护进程，以 NDJSON 格式实时吐出特定进程的系统调用与报错。Agent 在点击某个按钮后，可以顺便调用 get_syslog 验证应用后台是否抛出了网络错误或鉴权异常。

2. mcp-root 的防穿透白名单设计

很多越狱插件为了图方便，直接在设备上放一个无密码的 sudo 或执行任意命令的 setuid root 二进制，这在局域网环境下无疑敞开了后门。

而项目中的 mcp-root（chmod 4755）实现了一套极为严格的只读/有限白名单安全沙箱：

// mcp-root/main.c
typedef enum {
    MCP_ALLOWED_COMMAND_NONE = 0,
    MCP_ALLOWED_COMMAND_ROOTHELPER,
    MCP_ALLOWED_COMMAND_APPINST,
    MCP_ALLOWED_COMMAND_LDID,
    MCP_ALLOWED_COMMAND_CHMOD,
    MCP_ALLOWED_COMMAND_LAUNCHCTL,
    MCP_ALLOWED_COMMAND_ID,
    MCP_ALLOWED_COMMAND_DPKG,
} MCPAllowedCommand;

它仅允许调用内置的签名工具 mcp-ldid、应用安装器 mcp-appinst、无参数的 id，以及带绝对路径校验的 dpkg -i / dpkg -r。所有入参全部经过 realpath 规范化校验，严格禁止目录穿越（../）与 Shell 管道拼接注入。这种兼顾了实机提权能力与安全审计的设计思路，值得所有系统级工具开发者学习。

总结与实战启示

通读 witchan/ios-mcp 的整套工程实现，我最受触动的是它对真实生产环境边界条件的处理。它不仅仅是一个“把接口套上 MCP”的概念玩具，而是在面对多分辨率碎屏、系统注销重启、沙盒权限壁垒、Jetsam 内存压迫、锁屏并发防爆等一系列现实世界毒打后，演化出的工业级落地方案。

它的核心架构精髓可以提炼为四句话：

1. 宿主选在核心处：扎根 SpringBoard，最大化降低对外部主机环境的依赖；
2. 点位归一消抹差异：把所有视觉感知与逻辑触控统一在逻辑点空间（Point Space），让大模型直觉决策；
3. 关键任务隔离做：重型深度学习模型（OCR）坚决下沉到独立守护进程，用 UNIX 套接字保证主系统永远不死；
4. 状态守卫不盲目：感知锁屏，拦截破坏性指令，提供幂等式自愈唤醒。

对于想要尝试让 AI Agent 自动化管理多部 iPhone 设备矩阵、执行自动化逆向测试、或是搭建私人手机管家的开发者来说，ios-mcp 无疑交出了一份极具参考价值的答卷。

原文链接与参考资料

• 开源仓库：witchan/ios-mcp - GitHub
• Model Context Protocol 规范：Model Context Protocol Official Documentation
• PaddleOCR 官方模型与部署指南：PaddleOCR GitHub Repository
• ONNX Runtime 移动端适配文档：ONNX Runtime iOS Compatibility