本页步骤 · 直接跳转
先保留状态，再采取动作
出现问题时，先保存工程选择器、就绪状态、权限、活动操作、配对期限和服务端返回的具体错误。已有操作的 ID 和回执应保留，避免重试时丢失上下文。
Mac 锁屏、连接中断或客户端超时，都不能单独证明原生操作已取消。先查询现有操作，再决定是否重试。
按这个顺序检查
| 现象 | 检查什么 | 下一步 |
|---|---|---|
| 离线或暂停 | Mac 是否可用、App 是否运行、网络与暂停状态 | 恢复本机条件，明确恢复连接后重新读取状态。 |
| 已连接但原生未就绪 | Xcode 是否打开目标工程、原生 MCP 权限与绑定 | 在本机查看具体失败原因，完成所需授权。 |
| 工具缺失 | 服务端工具目录、客户端导入清单和本地审核状态 | 分别对照真实清单；更新后按客户端支持方式刷新。 |
| 操作被拒绝 | 读取、编辑、执行、模拟器的授权范围 | 只开启任务所需权限，再核对返回的状态。 |
| 设备忙碌 | 活动操作及其 ID | 查询已有操作，不并发重复派发。 |
| 只有路径，没有图片 | 图片输出目录权限、操作结果和传输错误 | 确认实际图片内容返回，再做视觉验收。 |
| 模拟器不可用 | 原配对设备、配对状态、到期时间与能力 | 先读取现有配对；确需续期时在 Mac 完成。 |
不要只看一项“正常”
在线、原生就绪、工程正确、工具可用、派发开放与模拟器已配对，是不同的状态。某一项成功不能替代整个链路的检查。
工程与工具发生变化时
关闭已绑定的工程 tab、改用另一个工程，或升级 Xcode 后出现工具 schema 变化，都可能需要本机重新确认。不要为了消除错误而静默切换到其他工程。
准备有用的诊断信息
- macOS、Xcode 和 relayard 版本。
- 发生时间、目标工程和预期动作。
- 完整错误码与服务端建议的下一步。
- 已有操作 ID、脱敏日志与配对到期时间。
- 客户端实际可用工具，以及缺失的预期结果。
可使用 App 中的诊断导出功能。分享前检查并移除令牌、验证码、敏感路径和业务源码。
文档更新: 2026-10-08