故障排查

根据实际返回状态恢复，不盲目重复设备输入。

常见问题

iphone-use: command not found

检查安装与客户端 PATH，然后重启客户端。插件不包含可执行文件。

Plugin installed, skill missing

确认插件启用，使用命名空间调用并开始新会话；更新时同时刷新 marketplace 与已安装插件。

setup_required / setup_update_required

仅在 Runner 模式下，使用发布版 CLI 执行提示的 setup 命令，再重新连接。

profile_not_found / signing mismatch

核对描述文件、证书与私钥、设备、团队和 bundle ID，传入匹配的签名参数。

coredevice_initialization_timeout

在获准的本机执行环境中对照一次只读 devices 调用。沙盒超时不代表手机断开；不要全局关闭沙盒或反复重置服务。

Locked phone / trust incomplete

解锁 iPhone，完成信任与开发者模式弹窗，再重新连接。

screen_changed / not_dispatched

阅读错误与 requiresObservation，按要求获取新引用，不要仅为绕过拒绝而提高阈值。

unknown

输入可能已发生。先观察并读取 PNG，再决定下一步。

Action succeeded, observation failed

保留 action.outcome，通过 observe 恢复；重复输入无法修复截图读取。

结束 Device Hub 或其他客户端的设备控制会话，再按返回的 recovery 恢复并重新观察。不关闭他人会话，也不重放结果未知的输入。

客户端无法读取配置时，先解决版本或配置不匹配，不要用示例覆盖完整配置。所选模型要求更新客户端也属于客户端版本问题：按原安装方式更新，或选择当前版本支持的模型。

请 Agent 尽可能断开会话。记录命令、错误、已验证内容与仍不确定的结果，并提供客户端、CLI、Xcode、macOS 和 iOS 版本。