常见连接问题
排查设备发现、握手、截图同步和终端无响应
排障时先确定问题发生在哪一层：设备是否在线、接收端是否发现设备、握手是否成功，以及具体 功能请求是否得到回复。不要一开始就重复安装全部组件。
接收端找不到设备
- 确认手环已与小米运动健康或 AstroBox 连接。
- 确保后端lua表盘处于start状态
- 在 AstroBoxV2 中手动刷新设备列表。
- 如果设备本身已离线，先恢复基础配对连接。
能看到设备，但握手超时
- 在手环上打开 Shell++ Quick App，并保持应用运行。
- 确认 Quick App 与 Lua 资源均已安装且为同一最新版本。
- 检查各组件是否来自兼容版本。
- AstroBoxV2 用户应检查 Interconnect 和接收注册权限。
- Android 用户可重新进入应用，强制发起一次新握手。
截图列表为空
先在手环端生成一张新截图，等待文件写入完成，再刷新列表。若新截图仍不出现，查看接收端日志中是否存在列表请求失败、权限不足或协议解析错误。
截图同步停在接收中
- 保持手环和接收端在线，不要同时启动多个同步批次。
- 等待当前重试结束后再重新请求。
- Android 局域网传输模式下，确认双方位于可互访的同一网络。
终端只有确认，没有结果
这通常表示命令请求已经到达通信层，但 Lua 后端没有返回最终 execResult。检查 Lua 资源、手环端运行状态和命令是否仍在执行。先用 pwd 之类能够快速结束的只读命令测试。
仍无法解决
请前往QQ交流群提交问题，提交问题时请包含：
- 手环或手表型号与系统版本。
- Quick App、Lua、Android 或插件版本。
- 使用 Android 还是 AstroBoxV2。
- 从正常状态开始的完整复现步骤。
- 接收端日志和手环端可获得的相关日志。
- 错误发生的大致时间，便于对应请求和结果。
如果升级后才出现问题，先使用回退并重新测试。