ESP32 iPhone Agent 的工作原理

当前系统由 iPhone、ESP32-S3 和视觉模型服务组成。Agent 运行在 iPhone App 中；板子负责接收屏幕，以及向手机提供鼠标和键盘输入。

眼睛：AirPlay 与蓝牙

板子开启自己的 Wi-Fi 热点。iPhone 加入热点，并在屏幕镜像列表中选择 ESP32 Agent。

ESP32 不解码 H.264 视频，而是通过 BLE 将码流转回同一台 iPhone 上的 App。App 解码画面，再取出截图交给视觉模型。

iPhone 屏幕 → AirPlay / Wi-Fi → ESP32-S3
ESP32-S3 → H.264 / BLE → iPhone App → 视觉模型

Wi-Fi 用于板子热点时，模型请求通过蜂窝数据发送。

规划器和执行器根据任务与截图决定动作，包括点按、滑动、画线、输入、按键和返回主屏。模型可以是云端 API，也可以是手机能够访问的自建服务。

Agent 在后台运行并操作其他 App，支持的设备可以通过实时活动看到进度。模型推理并不发生在 ESP32 上。

板子被 iOS 识别为 USB 鼠标和键盘。开启辅助触控后，点击指针就是点按，拖动指针可以形成滑动。

iPhone App → BLE 操作指令 → ESP32-S3
ESP32-S3 → USB 鼠标 / 键盘 → iPhone

USB 同时承担输入连接和板子供电。蓝牙传输 App 指令与画面码流，不要把这条 BLE 连接理解成已经实现了无需 USB 的蓝牙 HID 鼠标。

鼠标移动是相对的。App 会跟踪指针位置、定期回角落归零，并可在精确点击前通过画面确认指针位置。操作后等待页面稳定，再决定下一步。

这是基于视觉的操作循环，并不等同于直接调用每个 App 的语义接口。模型误判、细小目标、画面歧义和延迟都会影响结果。

ESP32 把 iOS 已有的投屏和鼠标键盘输入连接起来，提供实际的输入通道。仅仅把屏幕投到另一台设备，并不会自动让手机中的 Agent 获得操作能力。

这样可以跨 App 探索，而不必先给每个 App 开发专用接口。但它没有消除首次安装和系统限制：当前 App 仍需 Xcode 安装，受保护画面也无法被看到。

v0.1.0 使用 Mac 或 Linux 运行 UxPlay 和 Python 服务，目前保留在 legacy 分支。当前主线将 AirPlay 接收端移到板子，把 Agent 移到 iPhone App。

新安装请跟随当前搭建指南。只有明确要运行旧版时，才使用 legacy 文档。