# 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 直接操作 iPhone / iPad —— 不用 Xcode,不用越狱
为 AI Passport 硬件设计:Windows 直连 AirPlay 画面,AI Passport 通过蓝牙模拟键鼠输入。
人在电脑前看画面,Agent 用一套 MCP 接口点按钮、滑列表、打字。
快速开始 ·
校准 ·
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 不必靠猜。
## 它是怎么工作的
操作指令从电脑出发,由 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