callstack/agent-device

项目介绍

agent-device 解决的是「Agent 写完代码后如何验证运行中的应用」这个问题。Agent 可以读取当前界面的无障碍树快照，通过 ref 或选择器操作元素，并保存截图、录屏、日志、trace、网络数据、性能采样和 React Native 渲染分析结果，作为可审阅的证据。

同一套运行时提供三种入口：CLI、通过 agent-device mcp 启动的 stdio MCP 服务，以及带类型的 Node.js 客户端。无论 Agent 走 MCP 工具、执行 shell 命令，还是在自建程序里调用 API，命令集合、会话、设备归属、回放和云端路由都保持一致。

支持的目标包括 iOS、Android、HarmonyOS 的模拟器、仿真器和真机，tvOS、Android TV、Fire TV、Vega OS TV，以及 Web、macOS 和 Linux。原生应用、React Native、Expo 和 Flutter 应用都在范围内，但不同目标可用的命令和证据类型不同。

快速使用

需要 Node.js 22.12 或更高版本，Web 自动化需要 Node.js 24 或更高版本。建议先装好 CLI 并自行检查环境，再把命令交给 Agent：

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

接着用命令行操作一个应用，例如 iOS 自带通讯录：

agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device fill @e7 "Ada" --settle
agent-device screenshot ./contact-form.png
agent-device close

snapshot -i 的输出会列出元素及其 ref，例如 @e2 [button] "Add"。ref 只在最近一次输出中有效；执行带 --settle 的命令后应使用 diff 中的新 ref，只有 diff 缺少所需内容时才重新快照。各目标的安装要求见安装文档，完整流程见快速开始。

若要把这些命令作为 MCP 工具暴露给 Agent，在客户端配置中加入：

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

Claude Code、Codex、Cursor、Windsurf、Cline、Goose 等客户端的配置方式见 AI agent 配置指南。

在代码中调用

Node.js 客户端封装同一套运行时，适合编排代码或自行构建的 Agent：

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  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();
}

可运行示例在 SDK examples，另有 Node.js API、AI SDK 和 Eve 的独立文档。

使用约束

• 各后端支持程度不同。HarmonyOS 和 Vega OS 只覆盖部分命令；可用 agent-device capabilities --platform <平台> 和能力矩阵查看各目标、桌面、Web 及云服务商支持哪些命令。
• 快照质量取决于应用的无障碍信息。清晰的标签、角色和 test ID 能让 Agent 运行更稳定；无障碍信息不足时，截图和视频可作为证据或兜底手段。
• 会话按调用方的 git worktree 隔离，设备占用声明可防止并行 Agent 互相抢占模拟器和仿真器。用 agent-device device status 查看归属，用 agent-device device release --stale 释放所有者已确定不再运行的声明。
• 使用远程或托管设备时，需要配置远程代理，或接入 BrowserStack、AWS Device Farm、TestMu AI、Limrun 等受支持的设备云。
• 回放脚本保存为 .ad 文件，也可导出为严格的 Maestro YAML；长期稳定的确定性测试套件，README 指向独立的 TypeScript 测试框架 e2e。
• 项目采用 MIT 许可证。

HotRepo 点评

2026 年 11 月 13 日，该项目进入 TypeScript 日榜第 15 名，当天新增 26 Star，总量为 5,368 Star、399 Fork。单次快照只能说明当日的关注度，不足以判断趋势。更具体的信号在设计本身：CLI、MCP 和类型化客户端共用一套运行时，并用会话和设备占用声明处理并行 Agent 的协作问题，针对的是实际存在的协调难点，而不只是封装一次截图操作。