文档总览
安装与运行问题排查
找到失败的那一环，不用每次都从头重装。
按 固件 → App → 蓝牙 → 热点 → 投屏 → 指针 → 模型 的顺序检查。某一层成功，只能证明这一层可用。
USB 找不到开发板
换一条确认能传数据的线，执行 arduino-cli board list，检查是否连接到 S3 原生 USB。必要时按厂商说明进入 bootloader，再运行刷写脚本。
脚本提示路径有问题时，把项目移到不含空格的路径。强制包含配置文件的编译参数有这个要求。
Xcode 签名失败
检查 ios/Config/Local.xcconfig 中的 DEVELOPMENT_TEAM 和 IA_BUNDLE_ID，再看 Xcode 的具体 provisioning 报错。
免费团队可能无法启用可选能力。可以按示例配置将 IA_ENTITLEMENTS 与 IA_WIDGET_ENTITLEMENTS 留空，再手动加入热点。详细操作见 App 安装指南，不要套用其他开发者的签名信息。
免费账号安装的 App 使用七天后无法打开，可能需要重新签名并安装。
蓝牙扫描或配对超时
- 确认 App 获得蓝牙权限，板子也正常供电。
- 将手机与板子靠近，避免金属遮挡。
- 使用 App 的重新扫描或重试入口，等待连接检查结束。
- 排障时，先断开可能占用板子的其他 App 或调试工具。
板子能被 USB 识别，不是蓝牙已经连通的证据。反复失败时应收集日志，不能仅凭亮灯判断。
无法加入板子热点
使用 App 当前显示的名称与密码。无法自动加入时，前往系统无线局域网设置手动连接，并确认手机没有切回其他网络。
「无互联网连接」本身是预期情况；模型访问另查蜂窝数据。不要换成普通家庭 Wi-Fi 后继续期待板子接收端可被发现。
屏幕镜像里没有 ESP32 Agent
先确认热点，再打开「控制中心 → 屏幕镜像」。检查 App 中的板子状态，保持手机解锁；锁屏会停止镜像。
接收端能出现但 App 没有可用画面时，记录固件版本并导出日志。蓝牙配对成功不代表视频流已经正常。
点按总是偏移
开启辅助触控，重新校准，过程中不要触摸屏幕。使用竖屏，先选设置列表这种较大的目标测试。
如果指针位置没问题，但模型选择了错误目标，检查回放中的截图和动作。这可能是视觉理解或规划错误，不是校准问题。
模型连接测试失败
核对 Base URL、密钥、准确模型 ID 与图片输入能力。模型列表读取成功不代表可以处理图片。连接板子热点时，还要检查蜂窝数据能否访问该接口。
按照模型配置指南区分鉴权、模型不存在、拒绝图片与网络超时。
不能输入中文或日文
当前键盘不支持直接输入非 ASCII 文本。网站语言或任务指令语言，不会改变固件的输入能力。请先用不需要中文或日文输入的任务测试。
怎样提交有用的反馈
附上板型、iPhone 与 iOS 版本、源码版本、签名方式和明确失败步骤。模型问题附服务商与模型 ID，不要附 API key。