准备 iPhone

优先使用标准模式；仅 Runner 模式需要开发签名。

开始前

安装完整 Xcode，首次打开以完成安装，并在 Xcode 设置 → Locations 中选中它。xcode-select -p 应以应用内的 Contents/Developer 结尾；仅安装 Command Line Tools 不够。
通过 USB 连接 iPhone，信任 Mac，开启开发者模式并保持解锁。
仅 Runner 模式：Keychain 中需有 Apple Development 证书与对应私钥；iOS 开发描述文件需授权该证书、设备和 Runner bundle ID。

首次信任、开发者模式、Apple 登录及权限弹窗需要你在设备上操作。全新 Mac 与免费 Personal Team 的首次配置及续签尚未验收。

使用标准模式连接

iphone-use devices
export IOS_UDID='YOUR_DEVICE_ID'
iphone-use connect --device "$IOS_UDID" --mode standard

使用实际设备 ID，检查 controlAvailable=true，保留返回的会话 ID，观察后在完成时断开。标准模式不启动 Runner，也不隐式回退 XCTest。新用户默认 standard；旧配置可能保留 runner，可显式指定模式。

iphone-use --session "SESSION_FROM_CONNECT" observe
iphone-use --session "SESSION_FROM_CONNECT" disconnect

可选 Runner 准备

setup 使用已有凭据，不登录 Apple、不创建证书或描述文件。Xcode 中没有可用缓存时，通过开发团队的 Apple 开发描述文件流程准备。

iphone-use setup --device "$IOS_UDID" \
  --profile '/absolute/path/to/development.mobileprovision' \
  --team 'YOUR_TEAM_ID'

默认 Runner bundle ID 为 com.iphone-use.runner.xctrunner。若描述文件授权其他标识，请同时传入 --bundle-id 'com.example.iphone-use.xctrunner'。--identity 接收匹配开发证书的 SHA-1 标识，不是私钥内容。

iphone-use connect --device "$IOS_UDID" --mode runner

保存的准备状态

准备状态保存在 ~/Library/Application Support/iphone-use，私钥仍在 Keychain。后续连接复用成功记录。描述文件过期、Runner 文件变化或包升级可能要求重新 setup。

不要通过 build-runner 绕过发布包接入错误；源码开发属于另一条工作流。请根据实际诊断信息排查。