agent-device Skill 技能

是什么

agent-device 是 Callstack 开源的移动端应用自动化和验证工具，为 AI 编程 Agent 提供实时应用反馈回路。通过 CLI、内置 MCP Server 或类型化 Node.js API，让 Agent 在 iOS、Android、HarmonyOS（模拟器、真机）、tvOS、Android TV、Amazon Vega OS TV（Vega Virtual Device）、Web、macOS 和 Linux 上检查、控制、调试和验证应用。

核心能力

检查（Inspect） — Agent 通过无障碍树（Accessibility Tree）的高效 Token 快照而非截图推理来读取应用状态，精度更高且消耗更低。

操作（Act） — Agent 通过 Ref 引用和选择器对可见 UI 元素执行点击、输入、滚动、等待、断言状态、处理弹窗等操作。

诊断（Diagnose） — 支持截图、视频、日志、Trace、网络数据、性能采样、崩溃信息和 React Profile 全套诊断。

重复执行 — 将验证步骤保存为 .ad 脚本用于本地或 CI 重放，并可导出为严格 Maestro YAML 格式。

多平台覆盖 — iOS（XCTest）、Android（ADB）、HarmonyOS（HDC + ArkUI uitest）、Vega OS TV（Vega CLI/VDA）、macOS 本地 Helper、Linux（AT-SPI）、Web（agent-browser）。

安装与快速上手

npm install -g agent-device@latest
agent-device doctor
agent-device help workflow

配置 MCP Server（支持 Claude Code、Cursor、Windsurf、Cline、Goose 等主流 AI 编程工具）：

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

Node.js API 示例：

import { createAgentDeviceClient } from "agent-device";
const client = createAgentDeviceClient({ session: "qa-run" });
await client.apps.open({ app: "com.apple.Preferences", platform: "ios" });
const snapshot = await client.capture.snapshot({ interactiveOnly: true });

使用场景

• 让 AI Agent 在开发过程中验证移动端改动（无需人工操作手机）
• 自动化回归测试：保存验证步骤为 .ad 脚本，CI 持续运行
• 移动端 Bug 复现和日志收集
• React Native 性能分析（Re-render 检查）
• 跨平台（iOS + Android）并行验证

CI/CD 集成

agent-device 原生支持 CI 环境。EAS 提供了现成的 workflow 模板，可直接用于 GitHub Actions 等 CI 系统，将每次 PR 的移动端验证截图和日志作为 Review 附件保留。

评估

适合：使用 Cursor、Claude Code、Windsurf 等 AI 编程工具开发移动端（原生 / React Native / Flutter / Expo）的团队；需要自动化移动端 UI 验证但不想维护 Appium / Detox 老式测试套件的项目；在 CI 中为每个代码改动运行移动端检查。

资源

• GitHub：https://github.com/Callstack/agent-device
• npm：https://www.npmjs.com/package/agent-device
• 文档：https://oss.callstack.com/agent-device/
• AI Agent 配置指南：https://oss.callstack.com/agent-device/docs/agent-setup