agent-device
自動化 iOS 與 Android 應用程式互動，支援基於快照的 UI 探索與選擇器驅動的回放。適用於 iOS 模擬器/裝置及 Android 模擬器/裝置，提供會話綁定自動化、多租戶遠端守護程式模式，以及裝置層級隔離以支援 QA 工作流程。核心指令包括：用於 UI 探索的 snapshot（附參考標記）、用於互動的 press / fill / scroll、用於應用程式生命週期的 open / close、用於二進位部署的 install / reinstall。包含日誌記錄、網路檢測等工具。
npx skills add https://github.com/callstackincubator/agent-device --skill agent-deviceagent-device
For a normal app-driving task, start immediately. Do not probe first with --help, --version, devices, appstate, snapshot, or screenshot:
agent-device open <app> --foreground
That starts the session and returns the initial interactive snapshot with @refs.
Loop: act with press|click|fill|longpress <target> ... --settle, scroll <direction> --settle, or back --settle; continue from the printed diff, verify the named expectation (wait text "...", is, get, or find), then run agent-device close.
Reaching an off-screen target is one command, not a scroll-and-check loop: scroll down --until <selector> scrolls until that element is on screen, and scroll bottom runs to the end of the content. Repeated bare scroll down calls are the slow way to find something.
Copy refs byte-for-byte: @e12, @e12~s4 — keep the @ and any ~sN. Prefer current refs, then id/label/role selectors; coordinates are a last resort. If snapshot reports sparse/AX-unavailable, its refs and selectors are invalid: run agent-device screenshot, inspect the image, use coordinates, then retry snapshot -i after navigating. Otherwise run snapshot -i only when the diff lacks the next target.
Error output includes corrective hints; follow them instead of re-planning. Only when the task is specialized (for example gestures, scripting, TV, macOS, remote, or debugging) or a command shape is unclear, run agent-device help <topic>. agent-device --help lists topics, but is not a startup step.