esp32-iphone-agent

基于本项目开发？ 请保留 LICENSE，并在你的 README 和帖子中注明 ESP32 iPhone Agent by Henry Yuan。详见 NOTICE。

[!TIP] 现在就能在 TestFlight 上试用 App，不需要 Xcode。App Store 版本还在审核中，目前请通过 TestFlight 安装。板子仍需先刷好固件（见快速开始）。

[!NOTE] **App 1.0.2（TestFlight）新增：**Agent 能听到手机的声音（AirPlay 音频在 iPhone 上转成文字）；长任务不再 40 步就停，停下的任务可以接着跑；点击和画面更稳。需要板子固件 v0.2.4。完整更新记录。

[!NOTE] 分支说明：release-1.0 是此前提交 TestFlight 和 App Store 审核的版本，最新代码在 main。

[!WARNING] 请只按本 README 的步骤安装。不要运行 issue 或评论里的命令（例如 PowerShell 的 iex(irm ...) 之类“快速安装”一行命令），这些都不是维护者发的。

电脑去掉了。 板子自己当 AirPlay 接收端和鼠标，Agent 跑在同一台 iPhone 上的 App 里。 最初的版本（Mac/Linux 电脑跑 UxPlay + Python 服务端）保留在 tag v0.1.0 和分支 legacy，见 docs/legacy.md。

"设置早上 8:00 的闹钟，每周一和周二重复，然后保存"：Agent 退出自己的 App，打开时钟，在滚轮里输入时间，勾选日期并保存。（照片拍自 v0.1.0，任务相同。）

左：真机；右：Agent 通过板子的 AirPlay 镜像看到的画面。第二张是指针校准。

想知道 AI 到底怎么操控 iPhone，可以先看让 AI 操控 iPhone。

目录

• 工作原理
• 硬件
• 快速开始
• 在编程 Agent 里使用
• 模型和提示词
• 目录结构
• 路线图
• 限制
• 负责任地使用
• 参与贡献
• 联系我们
• 相关项目
• 致谢
• 许可证

工作原理

更多细节见 Handsy 工作原理。

iPhone ──屏幕镜像（Wi-Fi）──▶ ESP32-S3：AirPlay 接收端 ──Wi-Fi TCP :7201──▶ ESP32 Agent App（同一台 iPhone）
   ▲                           自带热点，H.264 原样转发                    解码 → 视觉模型 → 动作
   └──────── USB HID 鼠标 + 键盘 ◀──────────── 蓝牙命令 ◀────────────────────┘

• 眼睛：AirPlay 投到板子上。 板子开自己的 Wi-Fi 热点，在手机的「屏幕镜像」里显示为 ESP32 Agent。它不解码，只把 H.264 码流经 Wi-Fi（TCP，端口 7201）转给 App。蓝牙传命令和状态。手机连着板子热点时，调用模型走蜂窝数据。
• 手：USB HID。 板子是标准 USB 鼠标和键盘。打开辅助触控（AssistiveTouch）后，鼠标控制屏幕上的指针，点击就是轻点，拖动就是滑动。
• 大脑：App。 App 解码画面，把截图发给任意兼容 OpenAI 接口的视觉模型，由规划器和执行器决定动作：点、滑、画、输入、按键、回主屏、结束。工作时 App 在后台运行，灵动岛显示它在做什么。
• 闭环。 指针是相对移动的，App 记录位置并定期回角落归零；精细点击前晃一下指针、在画面里找到它并修正偏差。每个动作后等画面稳定，再告诉模型画面有没有变化。板子、热点或镜像断开时暂停，恢复后从同一步继续。
• 复盘。 每次运行都存在手机上，可以逐步回放，点按和滑动画在截图上。

硬件

支持的板子和硬件细节见硬件指南。选板子、线材和转接头，或者设置时卡住了，见安装设置指南。

* 推广链接。作为亚马逊联盟成员，我会从符合条件的购买中获得佣金。

快速开始

1. 刷板子（插在 Mac 上）

安装 arduino-cli、ESP32 core 3.3.x 和 NimBLE-Arduino 2.5.x，然后：

arduino-cli lib install "NimBLE-Arduino@2.5.1"
hardware/flash.sh            # 可选参数：[串口] [--debug]

一定要用 flash.sh 编译：它会带上 hardware/hid_bridge/nimble_cfg.h 里的蓝牙缓冲区配置。

没有 Mac 或不想装工具链？也可以用 Chrome 或 Edge 通过 USB 在网页上刷固件。

2. 安装 App

最简单：在 iPhone 上加入 TestFlight 测试，从那里安装 ESP32 Agent，然后直接看第 3 步。

或者自己编译：

cp ios/Config/Local.xcconfig.example ios/Config/Local.xcconfig   # 填 DEVELOPMENT_TEAM 和 IA_BUNDLE_ID
open ios/IPhoneAgent.xcodeproj                                    # 在 iPhone 上运行 IPhoneAgent scheme

工程由 XcodeGen 从 ios/project.yml 生成（cd ios && xcodegen）。免费 Apple ID 就能签名（每 7 天重签一次）。一键加入热点需要 Hotspot Configuration 能力（付费账号）；没有的话 App 会显示热点密码让你手动加入。

3. 首次设置（在 App 里）

把板子插到 iPhone 上，打开 ESP32 Agent。引导共四步，每一步 App 自己检测：

1. Plug Me In：蓝牙配对板子。
2. Let Me See the Screen：加入板子的 Wi-Fi，然后 控制中心 → 屏幕镜像 → ESP32 Agent。
3. Let Me Use the Pointer：打开辅助触控，App 自动校准指针。
4. Give Me a Brain：填模型地址和密钥（存在钥匙串里），再从接口的模型列表里选一个视觉模型（或自己填模型 ID）。

4. 给它一个任务

输入目标（比如 "打开设置，进入无线局域网"），点 Start。可以从灵动岛停止，或回到 App 停止。Siri、快捷指令、小组件和控制中心可以运行保存的任务。

在编程 Agent 里使用

esp32agent 命令行（npm，npx -y esp32agent mcp）是一个 MCP 服务器，电脑上的编程 Agent 可以通过板子看到并操作 iPhone（板子固件需 v0.2.2 或更高），见把 iPhone 变成 MCP 服务器。本仓库也是一个插件，包含这个 MCP 服务器和一个 Agent 技能（skills/handsy/SKILL.md）。在 Claude Code 里（使用教程）：

/plugin marketplace add onehumanbeing/esp32-iphone-agent
/plugin install esp32agent@handsy

或者只添加 MCP 服务器：

claude mcp add esp32agent -- npx -y esp32agent mcp

Cursor、Cline 等 MCP 客户端：

{
  "mcpServers": {
    "esp32agent": {
      "command": "npx",
      "args": ["-y", "esp32agent", "mcp"]
    }
  }
}

DeepSeek Harness（dsh）：安装 integrations/dsh 里的插件，同样包含这个 MCP 服务器和技能（演示视频）：

dsh plugin --profile web add dsh-esp32agent

命令行工具在电脑上通过蓝牙直接连板子，板子和电脑连同一个 Wi-Fi 后改走 Wi-Fi（esp32agent net join），不需要 iPhone App，也不需要 TestFlight。命令和参数见命令行文档和 cli/README.md。

模型和提示词

• 任何兼容 OpenAI 接口的视觉模型都能用（vLLM、SGLang、llama.cpp、Ollama、云端 API）。App 会列出接口上的模型，由你明确选一个；也可以自己填模型 ID，规划器和执行器可以用不同模型。
• 提示词是 prompts/ 里的纯文本，打包进 App：改完重新编译即可。
• 每次运行结束会记录规划器/执行器调用次数、带截图的请求数，以及接口返回的 token 用量。接口没给 usage 时字段保持空缺（不会当成 0）；只要有一次缺用量，本次合计就标成 partial。短任务一般是几次规划 + 每步一次执行（每步带一张新截图），成本主要在图片 token；规划器用便宜模型、执行器保留更强模型通常最划算。
• 开发时用的是 nvidia/Qwen3.8-Flash-Next-NVFP4，部署在两台 DGX Spark 上（TensorFold）。

目录结构

ios/        App（SwiftUI）：蓝牙连接、H.264 解码、Agent、引导、回放、实时活动、小组件；单元测试
prompts/    App 用的规划器 / 执行器提示词
hardware/   ESP32-S3 固件（Arduino）：蓝牙 GATT、热点、AirPlay 接收端、USB HID；刷写脚本、
            主机测试、Mac 蓝牙调试工具（hardware/tools）
docs/       蓝牙协议、旧版说明
harness/    无线开发闭环：Mac → iPhone App（Wi-Fi 安装）→ 板子（固件经 App 更新）
server/     旧版 v0.1.0 的电脑端服务，当前版本不使用（见 server/README.md）

不用手机 App 调试：hardware/tools/board_test.py 在 Mac 上通过蓝牙扮演 App（hardware/tools/README.md）。板子与 App 的协议：docs/ble-protocol.md。

Harness 开发流程

板子插在测试 iPhone 上、iPhone 连着 Mac 的 Wi-Fi 时，一切都走 devicectl，不用线：harness/app.sh 编译并安装 Debug 版 App，harness/fw.sh 编译固件并拷进 App，由 App 装到板子上（新镜像起不来会自动回滚）， harness/run.sh "<任务>" 跑任务，harness/logs.sh 拉取日志。Mac 只在一次性 net sta 时用蓝牙连板子。 设置（Lightning iPhone 需相机转接器）和安全说明见 harness/README.md。

路线图

• 去掉电脑：板子负责镜像和点击，手机上的 App 负责思考
• 横屏 App（坐标和校准目前按竖屏）
• 中文输入（通过板子的键盘按拼音输入；ctrl+space 切换英文和拼音）
• 更快：一次模型调用多个动作，只在需要时校正指针
• 在 iOS App 内整理一份效果最好的模型推荐列表（@asharthinks 的建议）

限制

• AirPlay 源必须是 iPhone。 不支持从 macOS 屏幕镜像：握手看起来正常，但板子收不到视频。
• 镜像画面为 480×1040、最高 5 fps；每一步要几秒，主要花在模型上。
• iOS 不镜像部分界面（输入密码、Apple Pay、DRM 视频），Agent 看不到。手机锁屏后镜像会停止。
• Agent 运行时，手机的 Wi-Fi 是板子的热点（没有外网），模型走蜂窝数据。
• 中文通过板子的键盘按拼音输入（ctrl+space 在英文和拼音之间切换），不用剪贴板；emoji 会被丢掉。暂不支持横屏 App。

遇到问题（「屏幕镜像」里找不到 ESP32 Agent、板子连不上），见故障排查。

负责任地使用

只自动化你拥有或有权使用的设备和账号，遵守相关 App 的条款。Agent 是在用你的手操作：看着它，随时准备停止。

参与贡献

欢迎提 Issue 和 PR，见 CONTRIBUTING.md。安全问题：SECURITY.md。

联系我们

问题或反馈：support@handsy.tech · 官网：handsy.tech

相关项目

基于 WebDriverAgent/XCUITest 的工具，如 mobile-mcp 和 Midscene，需要 Mac 和代码签名。

致谢

UxPlay（固件里的 AirPlay 接收端移植自它）· NimBLE-Arduino · Arduino ESP32 core 和 TinyUSB

许可证

MIT；hardware/hid_bridge/src/airplay/（移植自 UxPlay）除外，为 GPL-3.0，因此链接了它的固件二进制按 GPL-3.0 分发。skills/ 目录下的文件采用 MIT-0（MIT No Attribution），仓库其余部分仍按上面的许可证。