mobilecli

移动端 CLI

适用于 iOS 和 Android 设备、模拟器、仿真器及移动应用的通用自动化和管理技能。本技能将指导你使用 mobilecli 命令行界面与设备交互、自动化应用、执行手势、捕获屏幕状态、检查 WebView。

---

安装

首次执行设备命令前，请确保 mobilecli 二进制文件已存在。如果缺失，请使用 npm 全局安装。无需事先征求用户同意；安装是预期操作。

command -v mobilecli >/dev/null || npm install -g mobilecli@latest
mobilecli --version

如果 npm install -g 因权限错误失败，请重试 sudo npm install -g mobilecli@latest，或询问用户。如果 mobilecli 不在 Agent 的 PATH 中，但用户表示已安装，请运行 npm bin -g（或 npm prefix -g），并使用对应位置的二进制文件。

不要为每条命令都运行 npx mobilecli@latest；它会每次重新解析软件包，使自动化变慢。

每条设备命令都会与后台守护进程通信（自动启动，空闲 30 分钟后退出；mobilecli daemon status|stop）。无需进行任何设置。

平台前置条件（如果用户一直在这台机器上使用设备，则已满足）：

• Android：PATH 中有 adb（brew install --cask android-platform-tools）。
• iOS 模拟器：安装了 Xcode，且有已启动的模拟器。

---

快速入门（TL;DR）

立即开始操作。不要先使用 --help 或 --version 探查。

# 1. List devices and note the device id. This starts the background daemon,
#    which keeps devices, tunnels and agents alive so following commands are fast.
mobilecli devices

# 2. Boot the target device (only if offline)
mobilecli device boot --device <device-id>

# 3. Launch the app and dump the UI in one go. Every element gets a ref like @e5.
mobilecli apps launch com.example.myapp --device <device-id> && \
  mobilecli snapshot --device <device-id>

# 4. Act on a ref, then re-dump to verify. Chain with && so one bash call does both.
mobilecli io tap @e5 --device <device-id> && \
  mobilecli snapshot --device <device-id>

# 5. Confirm visually when needed
mobilecli screenshot --device <device-id> --output screenshot.png

串联命令

每次调用 mobilecli 都是一个独立进程，因此请在单次 bash 调用中用 && 串联相关步骤。&& 会在首次失败时停止执行，这正是自动化所需要的行为：

# fill a login form and check the result with one bash call
mobilecli io tap @e3 --device <id> && mobilecli io text "[email protected]" --device <id> && \
mobilecli io tap @e4 --device <id> && mobilecli io text "secret" --device <id> && \
mobilecli io tap @e7 --device <id> && sleep 1 && mobilecli snapshot --device <id>

Ref（@e1、@e2 等）按最近一次 snapshot 或 dump ui 的结果编号。任何点击、文本输入或导航都可能改变界面树，因此重新转储后再使用 Ref。阅读界面时优先使用 snapshot（文本）；需要 rect 坐标或对输出进行脚本处理时，使用 dump ui（JSON）。

---

AI 自动化工作流

执行移动端自动化或应用测试时，请遵循以下结构化循环：

graph TD
    A[List Devices & Select Target] --> B[Launch Target Application]
    B --> C[Inspect State: UI Tree / Screenshot]
    C --> D{Is Goal Achieved?}
    D -- No --> E[Find Target Element Coordinates]
    E --> F[Perform Gesture: Tap/Swipe/Text]
    F --> C
    D -- Yes --> G[Finish Automation / Report Results]
    C -- Error/Crash --> H[Pull Crash Log / Restart App]
    H --> C

1. 查找并选择设备：运行 mobilecli devices 查看在线设备和模拟器。如果只有一台设备在线，系统会自动选择；否则，请通过 --device <id> 标志传入设备 ID。
2. 启动应用：使用 mobilecli apps launch <bundle-id> 将目标应用置于前台。
3. 捕获状态：
   • 转储界面树：使用 mobilecli snapshot 查找元素，或使用 mobilecli dump ui 获取包含 rect 坐标的 JSON。
   • 截取屏幕：使用 mobilecli screenshot 直观确认当前显示内容。
4. 交互：点击转储结果中的元素 Ref（mobilecli io tap @e5），或计算其 rect 的中心并点击 x,y。然后使用 mobilecli io text 输入文本。
5. 重复或调试：通过新的界面转储或屏幕截图确认更改，处理弹窗，并在应用终止时检查崩溃报告。

---

AI Agent 最佳实践

重要

优先使用引用而非坐标： mobilecli io tap @e5 会点击最新 snapshot 或 dump ui 中元素 5 的中心。只有在需要点击非元素的位置（例如滑动的起点或终点）时，才使用坐标。如果使用坐标，请取元素 rect 的中心：centerX = x + width/2，centerY = y + height/2。任何 UI 变更都会使引用失效，因此重新使用前请重新转储。

提示

使用 && 串联步骤： 在一次 bash 调用中运行操作和验证：mobilecli io tap @e5 --device <id> && mobilecli snapshot --device <id>。这样往返调用更少，且链条会在首个失败步骤处停止。

警告

释放远程设备： Mobile Next Cloud 上的远程设备会持续占用并产生费用，直到运行 mobilecli remote release --device <id>。请在任务结束时释放设备，即使任务失败也不例外。请注意，最低计费时长为 5 分钟，因此在确实用完设备之前不要释放。

说明

输入文本前先与输入框交互： 要在文本字段中输入文本，请先点击该字段中心使其获得焦点，等待几百毫秒让软键盘出现，然后调用 mobilecli io text。

警告

自动选择注意事项： 当仅连接一台在线设备时，mobilecli 会自动选择目标设备，但仍应先确认已连接设备列表。如果有多台设备在线，必须传入准确的设备 ID，以避免命令失败。

---

快速交互参考

以下速查表将常见用户操作与 mobilecli 命令对应起来：

用户操作	CLI 命令	说明
点击	mobilecli io tap @e5 或 mobilecli io tap <x,y>	点击 snapshot 或 dump ui 中的引用，或点击指定坐标
长按	mobilecli io longpress <x,y | @ref> --duration <ms>	按住指定时长
滑动	mobilecli io swipe <x1,y1,x2,y2>	从起点坐标拖动到终点坐标
捏合	mobilecli io pinch [x,y] --direction in|out	以 x,y 坐标或屏幕中心为中心，用双指缩小（in）或放大（out）
输入文本	mobilecli io text "<text>"	将原始文本发送到当前获得焦点的字段
按键	mobilecli io button <BUTTON_NAME>	按下硬件按钮（例如 HOME、POWER）
读取剪贴板	mobilecli io clipboard get	读取设备剪贴板中的文本
写入剪贴板	mobilecli io clipboard set "<text>"	替换设备剪贴板中的文本

---

远程设备（Mobile Next Cloud）

由 Mobile Next 托管的真实 iOS 和 Android 设备。分配后，远程设备会在 mobilecli devices 中显示，且其 "type" 为 "remote"；以上所有命令均可通过 --device <id> 原样用于该设备。

1. 认证一次

# device-code flow: prints a URL and a code for the user to enter in a browser.
# the user must do this step; it cannot be completed by the agent.
mobilecli auth login

# headless hosts with no OS keyring
mobilecli auth login --insecure-storage

# verify
mobilecli auth status

令牌查找顺序：先检查 MOBILECLI_TOKEN 环境变量，然后检查操作系统密钥环（或使用 --insecure-storage 指定的凭据文件）。在 CI 中，请设置 MOBILECLI_TOKEN，而不是登录。未登录且没有令牌时，所有 remote 命令都会失败；请让用户运行 mobilecli auth login。

2. 分配、使用、释放

# see what the fleet has
mobilecli remote list-devices

# allocate and block until the device is ready (default timeout 900s)
mobilecli remote allocate --platform ios --version ">=18" --name "iPhone*" --wait
mobilecli remote allocate --platform android --version 14 --wait

# the response includes the device id; from here it is a normal device
mobilecli devices
mobilecli apps install ./app.ipa --device <remote-id> && \
  mobilecli apps launch com.example.app --device <remote-id> && \
  mobilecli snapshot --device <remote-id>

# always release when done, devices are billed while allocated
mobilecli remote release --device <remote-id>

筛选条件：--platform ios|android、--version（可重复，条件之间为 AND 关系，支持 >=、>、<=、< 或精确匹配）、--name（精确匹配或以 * 结尾的前缀匹配）。始终传入 --wait；否则命令会在设备仍处于 allocating 状态时返回。

---

---

完整参考

其他所有命令（应用、屏幕录制、滑动/长按/按钮、剪贴板、WebView、文件系统、崩溃报告、设备日志、深层链接、方向）、平台特有行为，以及 JSON-RPC/WebSocket API，均见 reference.md。mobilecli <command> --help 始终提供最新信息。