iOS 模拟器自动化

此技能提供了一个仅限 Node.js 的命令行界面包装器，围绕以下工具：

• xcrun simctl用于模拟器/设备/应用管理
• 以及 idb用于无障碍功能树检查与合成 UI 输入（点击/文本/按钮）

它专为AI 智能体设计：默认提供最小化、结构化的输出，并可按需提供详细信息。

重要限制

• 必须在 macOS 上运行且需安装 Xcode 命令行工具（或 Xcode）。
• 如果 ClawdBot 网关不是 macOS 系统，请在已连接的macOS 节点上运行这些命令（见下文“远程 macOS 节点”部分）。
• idb是可选的，但进行 UI 树/语义点击操作时需要。（安装步骤见下文。）

快速开始

# 1) Sanity check
node {baseDir}/scripts/ios-sim.mjs health

# 2) List simulators (compact)
node {baseDir}/scripts/ios-sim.mjs list

# 3) Select a default simulator (writes .ios-sim-state.json in the current dir)
node {baseDir}/scripts/ios-sim.mjs select --name "iPhone" --runtime "iOS" --boot

# 4) Install + launch an .app
node {baseDir}/scripts/ios-sim.mjs app install --app path/to/MyApp.app
node {baseDir}/scripts/ios-sim.mjs app launch --bundle-id com.example.MyApp

# 5) Inspect current UI (requires idb)
node {baseDir}/scripts/ios-sim.mjs ui summary
node {baseDir}/scripts/ios-sim.mjs ui tap --query "Log in"
node {baseDir}/scripts/ios-sim.mjs ui type --text "hello world"

# 6) Screenshot
node {baseDir}/scripts/ios-sim.mjs screenshot --out artifacts/screen.png

远程macOS节点

如果您不在macOS系统上，请通过ClawdBot的节点执行功能在macOS节点上运行相同命令（例如使用exec并指定host: node/节点工具）。请确保该节点上存在技能文件夹，或将其复制到该节点。

输出规范（节省标记）

• 默认输出：单行JSON（小型摘要对象）。
• 添加--pretty可美化打印JSON。
• 添加--text可获取简短的人类可读摘要（当命令支持时）。
• 可能产生巨大输出的命令（ui tree、list --full）需要主动选择才能执行。

状态 / 默认 UDID

选择会写入一个状态文件（默认为：./.ios-sim-state.json），用于存储所选的 UDID。 所有命令均接受--udid <UUID>参数，否则将回退到状态文件。

可通过以下方式覆盖位置：

• IOS_SIM_STATE_FILE=/path/to/state.json

依赖项说明

Xcode / simctl 可用性

如果xcrun无法找到simctl，请确保已选择 Xcode CLI 工具（通过 Xcode 设置或xcode-select），并运行首次启动设置：

• xcodebuild -runFirstLaunch

idb（用于无障碍自动化）

安装idb_companion和idb命令行界面：

brew tap facebook/fb
brew install idb-companion
python3 -m pip install --upgrade fb-idb

安全等级

命令索引

所有命令均位于：

node {baseDir}/scripts/ios-sim.mjs <command> [subcommand] [flags]

核心模拟器生命周期命令

• list [--full]
• select --name <子字符串> [--runtime <子字符串>] [--boot]
• boot [--udid <uuid>] [--wait]
• shutdown [--udid <uuid>|--all]
• erase --yes [--udid <uuid>|--all]
• delete --yes [--udid <uuid>]
• create --name <名称> --device-type <子字符串> --runtime <子字符串>

应用管理

• app install --app <路径/至/App.app> [--udid ...]
• app uninstall --bundle-id <标识符> [--udid ...]
• app launch --bundle-id <标识符> [--udid ...] [-- <参数...>]
• app terminate --bundle-id <标识符> [--udid ...]
• app container --bundle-id <标识符> [--type data|app] [--udid ...]

截图与视频

• screenshot --out <文件.png> [--udid ...]
• record-video --out <文件.mp4> [--udid ...]（运行直到按下 Ctrl+C）

剪贴板 / URL

• clipboard get [--udid ...]
• clipboard set --text <文本> [--udid ...]
• openurl --url <网址> [--udid ...]

模拟器权限与推送通知

• privacy grant --bundle-id <标识符> --service <服务[,服务...]> [--udid ...]
• privacy revoke --bundle-id <标识符> --service <服务[,服务...]> [--udid ...]
• privacy reset --bundle-id <标识符> --service <服务[,服务...]> [--udid ...]
• push --bundle-id <标识符> --payload <JSON字符串> [--udid ...]

日志

• logs show [--last 5m] [--predicate <表达式>] [--udid ...]

基于辅助功能的UI自动化（需要 idb）

• ui summary [--limit 12]
• ui tree（完整的UI JSON数组）
• ui find --query <文本> [--limit 20]
• ui tap --query <文本>（查找并点击最佳匹配项）
• ui tap --x <数值> --y <数值>（原始坐标点击）
• ui type --text <文本>
• ui button --name HOME|LOCK|SIRI|SIDE_BUTTON|APPLE_PAY

故障排除

请参阅：references/TROUBLESHOOTING.md