@rynx-ai/emulator

@rynx-ai/emulator 提供一组命令行工具和 Node.js API，用于检查、启动和控制本机 iOS Simulator、Android 模拟器以及 adb 可见的 Android 真机。

功能

• 检查本机 iOS/Android 模拟器环境和依赖状态。
• 列出 iOS Simulator、Android AVD、已启动的 Android 模拟器和真机。
• 启动并连接 iOS Simulator 或 Android AVD。
• 通过归一化坐标执行点击、输入、按键、旋转和手势操作。
• 执行原始 serve-sim 或 adb 命令。
• 安装、导出、打包或打印可供智能体使用的 rynx-emulator skill。
• 当 Rynx daemon 正在运行时，命令会优先通过 daemon API 执行，避免 Codex sandbox 直接访问 iOS CoreSimulatorService。

安装

独立安装：

npm install -g @rynx-ai/emulator

在 Rynx 仓库内使用：

pnpm emulator:doctor
pnpm emulator:setup
pnpm emulator:devices

环境检查

如果要在 Codex sandbox 内控制 iOS Simulator，先在普通 Terminal 或 Rynx App 进程中启动 daemon：

rynx start

如果使用 Rynx App，只需要重新打开 App。App 启动的 server 会把实际访问地址写入 ~/.rynx/control.json，rynx-emulator 会自动读取该地址。

检查当前机器是否具备可用的 iOS/Android 模拟器能力：

rynx-emulator doctor
rynx-emulator doctor --json

输出本机安装和配置提示：

rynx-emulator setup --print
rynx-emulator setup --json

rynx-emulator 会优先访问 Rynx daemon 的 emulator API；如果 daemon 不可用，会回落到当前进程直接执行。需要强制本地直连时可以设置：

RYNX_EMULATOR_DAEMON=0 rynx-emulator doctor

也可以显式指定 daemon/App 地址：

RYNX_EMULATOR_ORIGIN=http://127.0.0.1:3000 rynx-emulator doctor

设备列表

列出所有可发现的设备：

rynx-emulator devices
rynx-emulator devices --json

设备可能包括：

• iOS Simulator。
• Android AVD。
• 已启动的 Android 模拟器。
• 通过 USB 或无线调试连接的 Android 真机。

连接设备

连接 iOS Simulator：

rynx-emulator attach "iPhone 17 Pro" --json

连接或启动 Android AVD：

rynx-emulator attach "Pixel_9_API_35" --json

连接 Android 真机时，先确认 adb devices -l 能看到设备，然后使用设备 serial：

rynx-emulator attach R5GYA16GZ7J --json

attach 会写入 active session。后续命令不传 --device 时，会优先使用当前 active session。

查看 active session：

rynx-emulator active --json

基础控制

坐标使用 0..1 的归一化值，左上角为 (0, 0)，右下角为 (1, 1)。

rynx-emulator tap 0.5 0.8 --json
rynx-emulator type "hello" --json
rynx-emulator type --mode keys "hello" --json
rynx-emulator button home --json
rynx-emulator button backspace --json
rynx-emulator button back --json
rynx-emulator button appswitch --json
rynx-emulator screenshot --json
rynx-emulator rotate landscape --json
rynx-emulator rotate portrait --json
rynx-emulator launch com.example.MyApp --json

launch 只接受真实标识符：iOS 必须传 CFBundleIdentifier，Android 必须传 package name。不要把图标下面显示的名称传给 launch；如果只知道显示名称， 应先从可信上下文解析真实标识，或者交给 agent 通过视觉导航打开。

type 表示原文输入。iOS 默认会写入模拟器剪贴板并发送粘贴，因此 JSON 里的英文引号不会被系统 Smart Quotes 改成弯引号。需要测试真实硬件键盘事件时， 显式使用 rynx-emulator type --mode keys "hello" --json。

button appswitch 在 iOS 上会从屏幕最底部慢速上滑到屏幕中央，停顿后放手； 在 Android 上会发送 KEYCODE_APP_SWITCH。

也可以显式指定设备：

rynx-emulator tap 0.5 0.8 --device R5GYA16GZ7J --json

视觉确认

截图当前设备画面，默认写入 ~/.rynx/emulator/screenshots/ 并返回 PNG 路径：

rynx-emulator screenshot --json
rynx-emulator screenshot --device "iPhone 17 Pro" --out /tmp/rynx-shot.png --json

手势

rynx-emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --json

iOS 会在一个 serve-sim helper WebSocket 中把点数组紧凑采样为一次拖拽，避免密集 move 帧触发重复滑动； Android 会将起止点转换为带距离时长的 adb shell input swipe。不要把整个点数组直接传给原始 serve-sim gesture 子命令；该子命令只接收单个触摸事件。

执行原始命令

iOS 目标下，exec --command 接收 serve-sim 参数：

rynx-emulator exec --command "ca-debug blended on" --json

Android 目标下，exec --command 接收 adb 参数，不需要写 adb 本身：

rynx-emulator exec --device emulator-5554 --command "shell getprop ro.build.version.release" --json

关闭设备

关闭 iOS Simulator：

rynx-emulator shutdown --device "iPhone 17 Pro" --json

关闭 Android 模拟器：

rynx-emulator shutdown --device emulator-5554 --json

shutdown/kill 只适用于模拟器；Android 真机不能通过该命令关闭。

Agent Skill 包

安装 skill（通过 skills CLI 完成）：

rynx-emulator skill install

默认自动识别 rynx home（RYNX_HOME 或 ~/.rynx）：存在则装入其 skills/ 目录；随后在交互终端上询问是否也为其他 agent（claude/codex/…）安装。 非交互场景用参数直达：

rynx-emulator skill install --agents claude-code,codex   # 指定 agent，非交互
rynx-emulator skill install --dir /path/to/catalog        # 显式 catalog 目录

Rynx Daemon 入口

emulator 命令只有一个 CLI 面：独立的 rynx-emulator。daemon 运行时它自动经 daemon 代理执行（沙箱内的 agent 无需直接访问 CoreSimulatorService），daemon 不可达时回退本地直连。