SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sim-use

sim-use

智能体与模型

查看项目

更新于 10-16 09:24

技能介绍

用途

sim-use 是面向 AI 智能体的移动端自动化技能，让你用命令行驱动 iOS Simulator、Android 模拟器/设备，以及实体 iPhone/iPad 的屏幕。适用于需要自动化操作模拟器或真机界面的任务。

主要能力

  • 界面读取：sim-use ui --device <UDID> 读取界面轮廓，每个元素带 @N 别名，可选带 #<id> 标识符；列表单元带 #N（dominant list）或 #N@M（scoped）。
  • 选择器操作：支持 tap @N（缓存最快）、tap #<id>（跨小布局变化稳定）、tap --label 'X'、tap --label-regex '...'、tap --label-contains 'X'，以及最后的 tap -x N -y N / tap --point x,y。可用 --element-type 或 --frame minY=0.7r 消歧。
  • 常见动作：滚动（gesture scroll-up）、输入（type）、粘贴 Unicode（paste）、硬件按键（button home / button back）、滑动（swipe）、捏合（gesture pinch-out）、旋转（gesture rotate-cw）。
  • 证据录制：record-video --output demo.gif，用 SIGINT/SIGTERM 停止，停止后转码，可在 PR 中内联播放，支持 --gif-markers。
  • 批量执行：iOS 上可用 sim-use ios batch 一次调用完成已知多步序列。
  • 崩溃检测：命令之间检测目标进程消失并给出 PROCESS DISAPPEARED 提示；Android 上 ui 还能从无障碍树直接检测 AOSP 系统崩溃对话框。

使用方式

  1. 预检：首次与设备交互前运行 python3 scripts/preflight.py --device <UDID>，验证 sim-use 已安装且兼容、设备可达、守护进程健康。没有脚本时手动检查：sim-use --version、sim-use devices、sim-use ui --device <UDID>。
  2. 观察—操作—验证循环：每步都遵循 observe → act → verify。命令是「发出后不等待反馈」，操作后必须重新读取界面或截图确认。
  3. 保持输出精简：优先使用默认文本轮廓而非 --json；使用 --json 时加 --no-raw；每步操作只跑一次 ui（第 N 步的 Verify 读取即第 N+1 步的 Observe 读取）；用文本轮廓验证而非截图。

只有一台模拟器启动或一个守护进程运行时，--device 可选。Android 需先执行一次 sim-use android init --device <serial> 安装桥接 APK。

实体 iOS 设备（实验性）

只有三个动词会自动路由到实体 UDID：ui、tap（#<id> / --id / --label / --label-contains / --element-type 形式）和 screenshot。其他动词或形式会以原因和最近替代方案拒绝，应读取提示而不是重试。

硬性要求（ui / tap）：设备必须已配对、受信任、已解锁并处于 Developer Mode，且前台目标应用必须以 get-task-allow=true 开发签名。使用 Development 配置文件安装的 Release 配置二进制受支持；Distribution/Ad Hoc、TestFlight、App Store 和系统应用不受支持。screenshot 不受签名规则限制，可捕获任何屏幕。

实体设备上应按 #id 或 label 点击，不能用 @N（元素句柄随 DTX 连接失效）。--json 在所有动词上可用，实体结果带 "kind":"physical" 并省略几何字段。完整树需几秒，不要用紧凑循环轮询。

适用场景

  • 自动化模拟器/模拟器或真机屏幕以完成 GUI 任务。
  • 在 iOS/Android 界面间执行点击、输入、滑动等交互序列。
  • 录制演示 GIF 作为证据或用于 PR。

限制与注意事项

  • 输出成本：每个字节的命令输出都消耗上下文，需按上述规则精简。
  • 坐标空间：--json 中的 frame 使用平台原生单位（iOS points、Android pixels），跨平台计算坐标前先看 envelope 的 platform 字段。显式 -x/-y/--point 默认是设备原生竖屏空间，设备可能旋转时加 --coordinate-space ui。
  • 常见陷阱：label 冲突需加 --frame 或 --element-type；导航后 @N 缓存失效需重新 ui；系统层（弹窗、分享面板）遮挡需先关闭；多匹配报错需更具体的选择器；点击无反应可加 --pre-delay 或 --wait-timeout；iOS 软键盘下粘贴可能丢失，用 paste --via-menu --target-id <id>；Android 后台剪贴板访问被拒时改用 type。
  • Resize Mode：iOS 模拟器处于 Xcode 27 Resize Mode 时，触摸输入无法到达应用，sim-use 拒绝触摸而非报告已送达的点击；此时可自由读取 ui 和截图，仅可用 type、Cmd+V 粘贴和按键动词驱动。
  • 崩溃处理：检测到进程消失必须停止、报告崩溃横幅文本并等待指示，不能静默重启或继续。
  • Linux 构建：仅支持 Android，缺少 ios、record-video / stream-video、viewer 和 init，每个动词都需要 --device <serial>。
  • 升级询问：选择器冲突无法消歧、预检失败且无法自动修复、需要破坏性操作（删数据、卸载应用）、同一动作重试 3 次无进展时，应停止并询问用户。

退出检查清单

报告任务完成前：运行 sim-use ui（或截图）捕获最终状态；确认屏幕符合预期结果；若结果不明确，将最终 ui 输出或截图展示给用户。