CLI 工作流

发现、连接、观察、操作，并明确判断执行事实。

发现与连接

先完成设备准备。将设备与会话占位值替换为实际返回的 ID；任务结束后断开会话。

iphone-use devices
iphone-use connect --device "$IOS_UDID" --mode standard
export SESSION='SESSION_FROM_CONNECT'
iphone-use --session "$SESSION" apps --query Settings
iphone-use --session "$SESSION" open com.apple.Preferences
iphone-use --session "$SESSION" observe
iphone-use --session "$SESSION" disconnect

devices 列出 CoreDevice 已知设备，不保证都已就绪。apps --query 搜索已安装 App 名称与 bundle ID。open 先核对安装，再激活或启动 App，不负责安装或重启。

读取观察

标准模式返回 Apple PNG 路径、观察 ID 和屏幕几何信息。必须读取实际图片；坐标使用屏幕点而非图片像素，应按本次观察的尺寸换算。Runner 另可提供 o1:e10 等已采集无障碍元素；inspect 只搜索缓存快照。

使用当前观察

以下只说明语法，观察 ID 和坐标必须来自刚读取的真实画面。

iphone-use --session "$SESSION" tap o1 --x 100 --y 200 --observe
iphone-use --session "$SESSION" swipe o2 --from-x 100 --from-y 420 --to-x 100 --to-y 240 --observe

输入文字前必须确认焦点。标准模式的 type 绑定观察和完整输入框范围；Unicode 使用剪贴板粘贴，可能触发 iOS 授权。核对可见结果后通过 text-finish 完成剪贴板事务，不重放结果未知的输入。Runner 使用元素引用和 XCTest。文本与换行支持因模式不同，详见动作契约与已安装命令帮助。

--observe 分别返回动作和观察回执。标准模式在动作后有界等待画面稳定；有效截图仍可能带判稳超时。画面稳定或命令成功均不能代替业务结果验证。

执行结果

completed: 输入完成且执行检查通过。仍需读取屏幕来确认预期结果。
not_dispatched: 输入未发送。根据错误及 requiresObservation 修正请求或刷新引用。
unknown: 输入可能已经发生。先观察实际结果，再决定下一步，不能盲目重放。

画面校验

动作派发前对比当前画面与原观察。场景改变时读取返回的新图并重新选择动作；视频排除范围和光标位置必须依据当前画面显式指定，不通过扩大容差强行输入。标准截图不依赖常驻媒体流，录屏才拥有媒体会话；输入仍会检查其他客户端占用。遇到 native_media_busy，自行结束其他客户端的控制并按 recovery 恢复，不关闭他人会话。