# ai-passport-iphone-use **Repository Path**: dashingmonkey/ai-passport-iphone-use ## Basic Information - **Project Name**: ai-passport-iphone-use - **Description**: 让 AI 直接操控真实 iPhone / iPad:Windows 接收 AirPlay 画面,AI Passport 作为蓝牙键鼠,通过 MCP 供 Agent 点击、滚动与输入(无需 Xcode / 越狱) - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-11 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

AI Passport iPhone Use

AI Passport iPhone Use

让 AI 直接操作 iPhone / iPad —— 不用 Xcode,不用越狱

为 AI Passport 硬件设计:Windows 直连 AirPlay 画面,AI Passport 通过蓝牙模拟键鼠输入。
人在电脑前看画面,Agent 用一套 MCP 接口点按钮、滑列表、打字。

版本 1.0.1 固件 1.0.1-p1 Windows MCP MIT

快速开始 · 校准 · Agent 接入 · 能力与限制 · 构建

[English](README.md) ## 为什么用它 - **为 AI Passport 而做。** 一块 USB 蓝牙桥接器:USB 插电脑、蓝牙连手机,把电脑的鼠标键盘变成手机认得的蓝牙输入。设备自带小屏和 UP / OK / DOWN 三个键(OK 急停、再按恢复,长按 DOWN 六秒重配蓝牙),换手机不用换设备。 - **不需要 Xcode、开发者账号、越狱、WebDriverAgent 或 Appium。** 手机不用装任何工具,也不用开 USB 调试。 - **手机不必摆在电脑边。** 画面走局域网 AirPlay,输入走蓝牙;只有 AI Passport 需要插在电脑 USB 上。 - **一套接口给所有 Agent。** 软件内置 MCP 服务器,Claude Code、CodeBuddy、WorkBuddy 等任何支持 MCP 的客户端都能直接接进去,不必为每个 Agent 写适配。 - **iPhone 和 iPad 用同一套流程。** 实测点 20–57px 的小按钮,落点误差 0.37–4.67 px;指针移动误差 0.57–7 px。 - **每一步都有回执。** 每次点击回报"画面有没有变化"(`click_effect`),每次拖拽回报"页面有没有翻"(`page_changed`),Agent 不必靠猜。 ## 它是怎么工作的

PC 通过 USB 连接 AI Passport,AI Passport 通过蓝牙连接 iPhone,画面与声音经无线投屏回到 PC

操作指令从电脑出发,由 AI Passport 以蓝牙键鼠的身份交给手机;画面和声音走局域网 AirPlay 回到电脑。因为是视频流,电脑上的窗口被遮挡也不影响截图;因为走标准蓝牙 HID,手机上不用装任何 App。精度靠软件闭环补:截图找光标 → 算位移 → 移动 → 再看一眼,进入容差才点击。 ## 能做到与做不到 | 能做到 | 说明 | | --- | --- | | 点击、长按、拖拽、滑动、输入英文 | 小按钮给 `target_radius` 收紧容差;短距 `fast` 约 0.6 秒 | | 开关 App、返回手势、HOME | `swipe_back`、`open_app_switcher`、`press_key HOME` | | 做不到 / 有限制 | 说明 | | --- | --- | | **不是绝对坐标点击** | 模拟的是蓝牙鼠标:没有"直接点到 (x,y)"的通道,只能移光标再点,靠视觉闭环纠偏。极小(<20px)、低对比或正在播动效的区域,可能失败或耗时 0.5–6 秒 | | 必须先校准一次 | 换手机、换固件版本、改"指针速度"都要重标;未校准时只允许观察,不允许输入 | | 文字输入受输入法影响 | 按键经过当前输入源:中文拼音下字母会变候选词、空格和数字会被候选键吃掉。建议把设备切到英文(US)输入源 | | iOS 忽略 HID Return | 回车既不提交搜索也不换行(有未提交拼音时只提交拼音),请点屏幕上的确认按钮 | | 弹层会吃掉下一次点击 | 购物/社交类 App 常在两步之间弹全屏浮层,所以每个动作后都要重新截图 | | 只支持竖屏 | 手机需解锁、竖屏、开启"辅助触控"并关闭"自动隐藏指针" | | 仅 Windows | 需要 Windows 10/11;接收端和界面都是 Windows 程序 | ## 快速开始 1. 用 USB 线把 AI Passport 连到电脑,手机蓝牙配对 `AI Passport`。 2. 手机上开启:`设置 → 辅助功能 → 触控 → 辅助触控`(关闭"始终显示菜单"),再到 `指针控制` 关闭"自动隐藏指针"。 3. 手机控制中心打开"屏幕镜像",选择程序显示的接收端名称。 4. 打开程序,在「AI 控制」页点击**开始校准**(见下节)。 5. 校准通过后,「手动控制」页可直接操作;要做自动化就到「AI 控制」页复制 MCP 配置。 连接细节见程序左下角的「连接指南」。 ## 校准(必读) 校准只做一次,但它是精度的来源: - 先在手机上新建**空白备忘录**,收起键盘,保持解锁、竖屏、指针可见; - 校准期间不要触碰手机;按 Esc 可取消; - 完成后按手机保存,重启或重连会自动恢复,按钮变为「重新校准」。 换手机、换屏幕尺寸、固件版本变化,或改了手机的"指针速度",旧配置都会失效(`CALIBRATION_BINDING_CHANGED`),需要重标。校准和指针标记只能由本机用户操作,MCP 不提供这两个工具——没有校准时 AI 只能观察和停止。 ## 给 Agent 接入(MCP) 「AI 控制」页会给出可直接粘贴的 MCP 配置。工具覆盖 `screenshot`、`acquire_control`、`move_pointer`、`tap`、`long_press`、`swipe`、`press_key`、`type_text`、`swipe_back` 等,`initialize` 的说明里写清了坐标约定、租约规则和已知坑。 两个最省时间的约定: - **坐标永远取"这次返回的那张图"**:用缩放预览或旧帧估坐标,经常差 30–70 px; - **小目标先锚定再短距点击**:`move_pointer` 到目标 200 px 内的静态高对比处,再 `tap(precision:"fast")`,比在花背景上直接 `verified` 快得多。 ## 构建 构建入口是 `desktop/build.ps1`,在 PowerShell 里运行即可(也可以直接把这一句交给 AI 助手)。依赖:Node.js 22.12+、Python 3.10+、Rust MSVC、Visual Studio C++ 工具。产物在 `desktop/target/release/`: | 文件 | 运行时 | | --- | --- | | `iPhoneUse.exe` | 用系统 WebView2;缺失时询问是否下载并校验签名 | | `iPhoneUse_full.exe` | 内置 WebView2,约 320 MB,不随 Release 发布 | 固件镜像不嵌入 exe:程序在自身目录的 `firmware\` 下查找 `FoloToy-AI-Passport-full.bin`,所以不改固件也能构建桌面端。固件由 `tools/build-p1.ps1` 编译(自动识别已激活的 ESP-IDF 5.5.3,或用 `-IdfPath`),构建过程不会烧录。 ```powershell .\desktop\build.ps1 -Offline -NoPause -NoLaunch # 离线构建 .\tools\validate.ps1 -Offline # 只跑校验 ``` 执行策略拦脚本时,改用 `powershell -NoProfile -ExecutionPolicy Bypass -File .\desktop\build.ps1`。 ## 第三方来源与许可 随程序分发的二进制包含下列第三方组件,各自保留原有许可;本项目自身代码为 MIT。 **相关项目。** [iPhoneMirror](https://github.com/RayrenSX/iPhoneMirror) 走 USB + CoreDevice 绝对触控(GPL-3.0),我们研究过它的协议与工程实践,但**未使用其代码**;同样走蓝牙 HID 路线的 [esp32-iphone-agent](https://github.com/onehumanbeing/esp32-iphone-agent)(MIT)提供了思路与设备 命令协议,未复制源码。 **接收与解码。** [AirPlayServer](https://github.com/xenos1337/AirPlayServer) v1.2.5,提交 `85bb8dcbe82f75f40f30bb603255668f9162a8f9`: 仓库自有代码与复制的公开头文件为 MIT,接收适配层由本项目独立编写(MIT),来源与构建方式见 [AirPlay 来源说明](third_party/airplay-server/SOURCE.md)。其中 **PlayFair 为 GPL-3.0**、 **libplist 为 LGPL-2.1-or-later**,源码与许可原文随接收组件提供。 **FFmpeg 8.1.2** 动态链接 avcodec/avutil/swscale,LGPL-2.1-or-later,未启用 GPL/nonfree/version3 组件,源码 SHA-256 为 `464beb5e7bf0c311e68b45ae2f04e9cc2af88851abb4082231742a74d97b524c` (`https://ffmpeg.org/releases/ffmpeg-8.1.2.tar.xz`),源码与构建配置随发布提供。 **桌面端依赖。** [mdns-sd](https://crates.io/crates/mdns-sd)(Apache-2.0 OR MIT)负责局域网发现; 其余 Rust 与前端依赖沿用各自许可(含 MPL-2.0 的 `serialport`)。Microsoft Visual C++ 运行库适用 微软再分发条款;Microsoft WebView2 适用其运行时条款(标准版使用系统运行时,缺失时经确认下载; 完整版内置 155.0.4283.62)。 **P1 固件。** 随程序分发的 `firmware/FoloToy-AI-Passport-full.bin` 内含 [LVGL](https://lvgl.io/)(MIT,Copyright (c) 2025 LVGL Kft)、Espressif 托管组件 `espressif__button`、`esp_lvgl_port`、`esp_codec_dev`、`cmake_utilities`(Apache-2.0)以及 [ESP-IDF](https://github.com/espressif/esp-idf)(Apache-2.0,个别组件另有条款)。 AirPlay 是苹果的协议与商标,本项目为非官方兼容实现。程序「关于」页展示的就是本节内容。 ## 许可证 [MIT](LICENSE) © 2026 dashingmonkey