介绍
# iOS Simulator Automation
此技能提供了一个 **仅限 Node** 的 CLI 包装器，封装了： - `xcrun simctl`，用于模拟器/设备/应用管理 - `idb`，用于 **accessibility-tree**（辅助功能树）检查 + 合成 UI 输入（点击/文本/按钮）
专为 **AI 智能体** 设计：默认输出极简、结构化的数据，并可选择查看详细信息。
## 重要约束
- **必须在 macOS 上运行**，且需安装 Xcode Command Line Tools（或 Xcode）。 - 如果 ClawdBot 网关不是 macOS，请在连接的 **macOS 节点** 上运行这些命令（见下文“Remote macOS node”）。 - `idb` 是可选的，但进行 UI 树/语义点击时必须安装。（安装步骤见下文。）
## 快速开始
```bash # 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 ```
## Remote macOS node
如果你不在 macOS 上，请使用 ClawdBot 的节点执行功能在 macOS 节点上运行相同的命令（例如使用 `host: node` 的 `exec` 或节点工具）。请确保该节点上存在技能文件夹，或将其复制到该节点。
## 输出约定（节省 Token）
- 默认输出：**单行 JSON**（小型摘要对象）。 - 添加 `--pretty` 以美化打印 JSON。 - 添加 `--text` 以获取简短的人类可读摘要（当命令支持时）。 - 可能产生大量输出的命令（`ui tree`、`list --full`）是 **可选启用** 的。
## 状态 / 默认 UDID
`select` 会写入一个状态文件（默认：`./.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` CLI： ```bash brew tap facebook/fb brew install idb-companion python3 -m pip install --upgrade fb-idb ```
## 安全等级
| 等级 | 命令 | 备注 | |------|----------|------| | 安全 | `list`, `health`, `boot`, `shutdown`, `screenshot`, `ui *` | 无数据丢失 | | 谨慎 | `privacy *`, `push`, `clipboard *`, `openurl` | 改变模拟器/应用状态 | | 危险 | `erase`, `delete` | 需要 `--yes` |
## 命令索引
所有命令位于： ```bash node {baseDir}/scripts/ios-sim.mjs <command> [subcommand] [flags] ```
### 核心模拟器生命周期 - `list [--full]` - `select --name <substr> [--runtime <substr>] [--boot]` - `boot [--udid <uuid>] [--wait]` - `shutdown [--udid <uuid>|--all]` - `erase --yes [--udid <uuid>|--all]` - `delete --yes [--udid <uuid>]` - `create --name <name> --device-type <substr> --runtime <substr>`
### 应用管理 - `app install --app <path/to/App.app> [--udid ...]` - `app uninstall --bundle-id <id> [--udid ...]` - `app launch --bundle-id <id> [--udid ...] [-- <args...>]` - `app terminate --bundle-id <id> [--udid ...]` - `app container --bundle-id <id> [--type data|app] [--udid ...]`
### 截图与视频 - `screenshot --out <file.png> [--udid ...]` - `record-video --out <file.mp4> [--udid ...]` (运行直到 Ctrl+C)
### 剪贴板 / URL - `clipboard get [--udid ...]` - `clipboard set --text <text> [--udid ...]` - `openurl --url <url> [--udid ...]`
### 模拟器权限与推送通知 - `privacy grant --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy revoke --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy reset --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `push --bundle-id <id> --payload <json-string> [--udid ...]`
### 日志 - `logs show [--last 5m] [--predicate <expr>] [--udid ...]`
### 基于辅助功能的 UI 自动化（需要 idb） - `ui summary [--limit 12]` - `ui tree` (完整的 UI JSON 数组) - `ui find --query <text> [--limit 20]` - `ui tap --query <text>` (查找并点击最佳匹配项) - `ui tap --x <num> --y <num>` (原始坐标点击) - `ui type --text <text>` - `ui button --name HOME|LOCK|SIRI|SIDE_BUTTON|APPLE_PAY`
## 故障排除
参见：[references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)