名称： ios-simulator
描述： 自动化 iOS 模拟器工作流（simctl + idb）：创建/启动/擦除设备，安装/启动应用，推送通知，授予隐私权限，截图，以及基于辅助功能的 UI 导航。适用于 iOS 应用、Xcode、模拟器、simctl、idb、UI 自动化或 iOS 测试场景。
元数据： {"clawdbot":{"emoji":"📱","os":["darwin"],"requires":{"bins":["xcrun"]},"install":[{"brew":{"formula":"idb-companion","bins":["idb_companion"],"tap":"facebook/fb"}}]}}

iOS 模拟器自动化

本技能提供了一个仅限 Node.js 的 CLI 封装，底层整合了：
- xcrun simctl：用于模拟器/设备/应用管理
- idb：用于辅助功能树检查与合成 UI 输入（点击/文本/按钮）

专为AI 代理设计：默认输出简洁、结构化，同时支持按需获取详细信息。

重要限制

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

快速开始

# 1) 环境检查
node {baseDir}/scripts/ios-sim.mjs health

# 2) 列出模拟器（简洁模式）
node {baseDir}/scripts/ios-sim.mjs list

# 3) 选择默认模拟器（将在当前目录生成 .ios-sim-state.json 状态文件）
node {baseDir}/scripts/ios-sim.mjs select --name "iPhone" --runtime "iOS" --boot

# 4) 安装并启动 .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) 检查当前 UI（需要 idb）
node {baseDir}/scripts/ios-sim.mjs ui summary
node {baseDir}/scripts/ios-sim.mjs ui tap --query "登录"
node {baseDir}/scripts/ios-sim.mjs ui type --text "hello world"

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

远程 macOS 节点

若当前环境非 macOS，可通过 ClawdBot 的节点执行功能（例如使用 exec 并指定 host: node 或节点工具）在 macOS 节点上运行相同命令。请确保技能文件夹存在于该节点上，或将其复制过去。

输出约定（节省 Token）

• 默认输出：单行 JSON（精简摘要对象）。
• 添加 --pretty 参数可美化打印 JSON。
• 添加 --text 参数可获取简短的人类可读摘要（如果命令支持）。
• 可能产生大量输出的命令（如 ui tree、list --full）需显式请求。

状态 / 默认 UDID

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

可通过以下环境变量覆盖状态文件位置：
- IOS_SIM_STATE_FILE=/path/to/state.json

依赖说明

Xcode / simctl 可用性

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

idb（用于辅助功能自动化）

安装 idb_companion 和 idb CLI：

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

安全等级

命令索引

所有命令均遵循以下结构：

node {baseDir}/scripts/ios-sim.mjs <命令> [子命令] [参数]

核心模拟器生命周期

• 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 <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