ESP32 Agent

屏幕镜像没有画面

AirPlay 源必须是 iPhone。不支持从 macOS 屏幕镜像。握手可以看起来正常，但板子始终收不到视频，ESP32 iPhone Agent 就没有可以操作的画面。

看起来是什么样

镜像可以显示为已连接。AirPlay 握手可以看起来正常，但板子始终收不到视频。板子状态可以是 "ap":"connected" 但并没有在传流，截图请求也可能回答 err no video。

源是 Mac 时就是这样。请停止 macOS 上的屏幕镜像，改从 iPhone 发起。Mac 不能代替手机。

从 iPhone 开始镜像

把板子插到 iPhone 上。使用 App 时，完成 Plug Me In（把我插上）。使用 Handsy CLI 时，在电脑上运行 esp32agent pair。
加入板子的 Wi-Fi，并让板子靠近手机。这个热点没有外网；调用模型走手机的蜂窝数据。
打开控制中心 → 屏幕镜像 → ESP32 Agent。接收端名称是 ESP32 Agent。
保持 iPhone 解锁。锁屏会停止屏幕镜像。先切到另一个画面，确认预览跟着变化，再开始任务。

如果列表里没有这块板子，天线、热点密码和配对见常见问题。

画面卡住、很慢，或提示「err no video」

这和 Mac 从未把视频发过来不是同一个问题。预览卡住、任务一开始就报 err no video，或者反复执行同一个动作、看起来很慢，这些在 Issue #25、#29 和 #44 里都有反馈。App 1.0 和板子固件 0.2.2 修复了已知原因：重新连接后画面会自动恢复，手机长时间停在同一画面之后也一样。

检查版本。App 版本在设置 → 关于，板子固件版本在设置 → 开发板。那里提示有更新就先更新：更新 ESP32 Agent 固件。
重新连接镜像。停止任务，关闭屏幕镜像，再重新选择 ESP32 Agent。保持 iPhone 解锁。
切换画面。换到另一个画面，确认预览跟着变化。
重试任务。还是卡住时，在 Runs（记录）里打开这次运行，选择 ⋯ → Export trace，连同版本号发到 [email protected]。

有画面但特别慢，可能是 App 没有「本地网络」权限，画面退回走蓝牙。见 iPhone 连到家里 Wi-Fi 而不是 ESP32 Agent 热点怎么办。

还是没有画面

保持镜像开启，在 App 里打开 Settings → Diagnostics → Video（设置 → 诊断 → 视频），把看到的内容发给帮助。
开机日志里出现 video: no PSRAM for the GOP buffer，说明板子没有可用的 PSRAM。请使用带 8 MB PSRAM 的标准版 XIAO ESP32S3。
各部分如何配合：ESP32 iPhone Agent 如何工作。日志：调试与拉日志。

安装器提示「Failed to connect with the device」

运行 Handsy 固件的板子可能没有安装器能用的串口。拔下板子，按住 BOOT 键再插上，然后重新点连接板子。详细步骤：连不上板子。