ESP32 iPhone Agent

ESP32 iPhone Agent 是一套开源硬件+App方案，仅需一块40余元的ESP32-S3开发板，无需电脑、无需iPhone越狱，即可让AI视觉模型直接操控真实iPhone，自动完成点击、滑动、输入等手机操作。

整套工作闭环

1. 眼睛（画面采集）：ESP32-S3自建Wi-Fi热点，iPhone开启屏幕镜像（AirPlay）投屏到ESP32。板子不做H.264解码，直接把码流通过蓝牙转发至iPhone上的Agent App；手机接入板子热点后，AI模型访问网络可走蜂窝数据。
2. 手（动作执行）：ESP32作为USB HID键鼠设备接入iPhone。开启iOS辅助触控（AssistiveTouch），板子发送的鼠标指令会控制屏幕悬浮指针，模拟点击、滑动。
3. 大脑（AI决策）：iPhone端App解码视频画面，把截图送入兼容OpenAI接口的视觉模型，由规划器输出动作指令：点击、滑动、绘图、文字输入、返回主页等。App后台运行，灵动岛实时展示任务状态。
4. 动作闭环校准：指针采用相对移动，App持续记录坐标，定期归零；精细点击前会晃动指针，在画面内识别指针位置消除偏移。每一步动作后等待画面稳定，再判断执行结果。网络、镜像断开时自动暂停，恢复后接续任务。
5. 任务复盘：所有操作记录保存在iPhone本地，支持回放，在截图上绘制点击、滑动轨迹。

硬件清单

• ESP32-S3开发板：推荐Seeed XIAO ESP32S3（普通版，8MB PSRAM，非Sense/Plus版本），售价约40~50元；具备原生USB、带PSRAM的ESP32-S3均可。
• iPhone：iOS18及以上，需要蜂窝数据；USB‑C机型直插；Lightning机型需要Lightning转USB相机转换器；板子由iPhone直接供电。
• 视觉模型：任意支持图片输入、OpenAI兼容接口模型，本地llama.cpp/Ollama或云端API都可以。
• Mac（仅一次性烧录编译）：仅刷写ESP32固件、编译iOS App时使用，运行阶段不需要。

快速部署步骤

1. 烧录ESP32固件：Mac安装arduino-cli、ESP32 core 3.3.x、NimBLE-Arduino 2.5.1，执行hardware/flash.sh编译烧录。必须使用该脚本，内置蓝牙缓冲区配置。
2. 编译安装iPhone App：复制示例配置文件，填入开发者账号信息，在Xcode编译工程部署到手机。免费Apple ID可签名，7天需要重签；付费开发者账号支持一键自动加入热点，免费账号只能手动连接热点。
3. App初始化四步引导
   • Plug Me In：蓝牙配对ESP32开发板
   • Let Me See the Screen：接入板子热点，开启屏幕镜像
   • Let Me Use the Pointer：开启辅助触控，自动校准指针
   • Give Me a Brain：填写模型API地址与密钥，密钥存入mac钥匙串
4. 下达任务：输入任务指令，点击Start；支持灵动岛、Siri、快捷指令、小组件启停保存任务。

模型与提示词

兼容所有OpenAI接口视觉模型，vLLM、SGLang、llama.cpp、Ollama、云端API均可。规划器、执行器可以分开选用不同模型。提示词以纯文本打包在App内，修改后重新编译即可。项目开发测试采用Qwen3.8-Flash-Next-NVFP4模型。