callstack/agent-device · 上手攻略

  • 仓库：callstack/agent-device
  • 链接：https://github.com/callstack/agent-device
  • 分类：AI 编码代理 / 移动端自动化
  • 作者：Tom
  • 更新：2026-10-12

§0 自检

  • GitHub URL ✅ 已 fetch
  • 顶会 venue+年份 ⚠️ 无顶会，属于工业级开源工具（Callstack 维护）
  • README 子模块 anchor ✅ 含 Quick Start / AI Agent Setup / Replay & E2E / Debugging & Profiling

一、是什么

agent-device 是 Callstack 开源的移动应用自动化与验证工具，专为 AI 编码代理设计，通过 CLI、MCP Server 或 typed Node.js API 三种入口，让 AI 代理能够检查、控制、调试和验证运行中的 iOS/Android/HarmonyOS 应用（含模拟器、真机和 TV/Web/macOS/Linux）。核心卖点是让 AI 代理获得实时应用反馈闭环——代理改完代码，立刻能看到运行结果，而不只是静态分析。

它不是传统 E2E 测试框架（Appium/Détour）的替代品，而是一个以 AI 代理为中心的运行时，天然支持 Claude Code、Codex、Cursor、Windsurf、Cline、Goose 等主流编码代理。

二、解决什么问题

AI 编码代理在处理移动端代码时，面临一个根本困境：代理不知道运行时发生了什么。它可以生成代码，但无法验证代码是否正确运行在真实设备上。agent-device 填补了这个空白：

  • 验证变更：代理写完 UI 代码，立即在真机/模拟器上截图验证，无需人工介入
  • 探索 App 行为：代理可以对陌生 App 执行 snapshot → 分析 → 操作循环，像人类测试者一样边用边理解
  • 可重复的 CI 验证：保存工作流为 .ad 脚本，在 CI 中 replay，附带截图和日志证据
  • 多平台统一接口：iOS/Android/HarmonyOS/TV/Web/macOS/Linux 一套命令，学习成本低
  • 并行设备协调：多代理工作树共享设备访问权限，避免相互抢占模拟器

三、快速安装

环境要求

  • Node.js ≥ 22.12（CLI 核心运行时）
  • Node.js ≥ 24（Web 自动化）
  • 目标平台需各自工具链（如 iOS 需 Xcode 和模拟器，Android 需 ADB）

安装

npm install -g agent-device@latest

# 验证安装
agent-device doctor

# 查看帮助
agent-device help workflow

⚠️ agent-device doctor 须在交付给代理之前由人类先跑一遍，确认设备连接正常。

四、核心用法

4.1 CLI 基础操作

# 启动一个 session，打开 iOS 模拟器上的 Contacts 应用
agent-device open Contacts --platform ios

# 读取当前屏幕快照（输出 accessibility tree）
agent-device snapshot -i
# 示例输出：
# @e2 [button] "Add"

# 等待 UI 稳定后，按 ref 按下按钮
agent-device press @e2 --settle
# diff 输出：
# + @e7 [text-field] "First name"

# 填写文本字段
agent-device fill @e7 "Ada" --settle
# diff 输出：
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"

# 截图并关闭 session
agent-device screenshot ./contact-form.png
agent-device close

⚠️ ref 只在最新输出中有效：--settle 后使用 diff 中的 ref；如需重新获取 ref，再跑一次 snapshot。

4.2 MCP Server 接入

在 Claude Code / Cursor 等支持 MCP 的代理中配置：

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

代理通过 stdio 连接 MCP Server，所有 CLI 命令以结构化工具形式暴露给代理。

⚠️ MCP Server 和 CLI 使用相同的执行路径，二者完全等价，选择哪种取决于代理的连接方式。

4.3 Node.js API

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  // 打开 iOS 设置应用
  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  // 抓取快照
  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  // 找到第一个按钮并点击
  const button = snapshot.nodes.find((node) => node.role === 'button');
  if (button) await client.interactions.press({ ref: button.ref });
} finally {
  await client.sessions.close();
}

4.4 典型代理任务示例

安装 CLI 后，以下自然语言提示即可端到端运行：

# "Implement the onboarding screen, run it on the iOS simulator
#  and Android emulator, and attach screenshots."
# → 代理自动打开两个模拟器，运行代码，截图，输出

# "Reproduce this crash and capture the logs that lead up to it."
# → 代理导航到 crash 场景，保存日志片段

# "Verify this pull request on a physical device and attach reviewable evidence."
# → 代理 checkout PR，在真机运行，截图作为 review 证据

4.5 CI/CD 集成

# 保存工作流为 .ad 脚本（本地 replay）
agent-device replay ./my-workflow.ad

# 或导出为 Maestro YAML（与 Maestro 测试框架互通）
# 见：https://github.com/callstackincubator/eas-agent-device

EAS Workflow 模板（Expo 项目示例）:

# ref: https://github.com/callstackincubator/eas-agent-device

五、核心功能一览

功能 说明
Inspect 通过 accessibility snapshot / refs / selectors 读取 App 状态
Act tap / press / fill / scroll / gesture / wait / assert / alert 处理
Diagnose screenshot / video / logs / traces / network / performance / crash / React profile
Replay 保存为 .ad 脚本本地 replay 或导出 Maestro YAML
Device Cloud 支持 BrowserStack / AWS Device Farm / TestMu AI / Limrun
Multi-agent 基于 git worktree 的会话隔离 + 设备锁避免并行代理冲突

六、典型适用场景

  1. AI 编码代理开发移动 App：Claude Code / Cursor 写完 UI 代码，agent-device 自动验证截图
  2. PR 自动验证：在 CI 中 replay 代理保存的工作流，截图+日志作为 merge 条件
  3. React Native 性能分析：代理抓取 React DevTools profile，排查不必要渲染
  4. 跨平台冒烟测试：iOS + Android 同一套 .ad 脚本，在双平台并行跑
  5. 设备云并行测试：BrowserStack 或 AWS Device Farm 上多设备同时跑回归
  6. 移动端 E2E 测试维护：替代维护成本高的 Detox/Appium 脚本，用自然语言让代理自己写测试

七、坑与注意

  1. Node.js 版本硬门槛：CLI 需要 ≥22.12，Web 自动化需要 ≥24，老版本 Node 无法运行（无 fallback）
  2. ref 的时效性：每次 --settle 后必须用 diff 中的新 ref，旧 ref 失效，容易写出无效脚本
  3. Accessibility 依赖：snapshot 依赖 App 的 accessibility tree，无标签/无 test ID 的 App 数据质量差；建议开发阶段加上 testID
  4. HarmonyOS / Vega OS 功能子集：这两个平台仅支持部分命令，需 agent-device capabilities --platform <platform> 先行确认
  5. 物理 iOS 设备需要 Xcode：HC 框架依赖 Xcode，不只是命令行工具链
  6. MCP Server 不支持多会话并发：一个 MCP 连接对应一个 session，需要并发时走 CLI 多进程
  7. .ad 脚本非标准格式：导出 Maestro YAML 可获得更好的生态兼容，但某些复杂手势链在导出会有限制

八、与同类对比

工具 定位 AI 代理原生支持 平台覆盖 MCP 支持 存档/证据
agent-device AI 代理验证运行时 ✅ 原生 iOS/Android/HarmonyOS/TV/Web/macOS/Linux ✅ stdio ✅ screenshot+logs
Appium 通用移动自动化 ❌ iOS/Android ❌ ❌
Detox React Native E2E ❌ iOS/Android ❌ ⚠️ 截图
Maestro 简单移动测试 ⚠️ Studio 辅助 iOS/Android ❌ ⚠️
agent-browser（Vercel） 浏览器 AI 自动化 ✅ Web ✅ ✅

agent-device 的差异化在于把 AI 代理作为一等公民：不只是测试工具，而是代理"看 App → 改代码 → 再看 App"闭环的核心基础设施。

九、一句话推荐结论

如果你的 AI 编码代理需要开发、测试或验证移动应用，agent-device 是目前对代理最友好的运行时基础设施，闭眼接入 Claude Code / Cursor + MCP，显著提升代理在移动端的验证能力。