callstackincubator/agent-device

CLI to control iOS and Android devices for AI agents

adbagentic-aiagentsai-agentsandroid-emulatorautomatione2e-testingexpoflutterios-simulatormcpmobilemobile-testingperformance-optimizationreact-nativetestingxcuitest

GAI 中文摘要

agent-device 是一个专为 AI Agent 设计的移动端设备自动化控制命令行工具，旨在通过统一的接口让 Agent 实现对 iOS、Android 及桌面端应用程序的真实交互与验证。该项目弥补了 AI 模型仅凭代码进行推理的局限性，通过提供实时的 UI 快照和反馈闭环，确保 Agent 能够准确感知并操作移动端应用。

它能够通过紧凑的无障碍快照与语义化引用机制，高效地完成对应用界面元素的识别与 UI 结构解析。支持包括点击、输入、滚动、手势操作及弹窗处理在内的全方位交互功能。提供截图、日志、网络流量、性能监控及崩溃上下文等多种调试证据的捕获能力。支持将操作录制为脚本，以便在本地开发、CI 流水线及端到端测试中进行工作流重放。具备跨平台兼容性，完美适配 iOS 模拟器、Android 模拟器、物理设备以及 TV 和桌面端环境。

适用于需要进行移动端应用开发、自动化测试及性能优化的团队。开发者可利用该工具为 AI 编程助手构建真实的反馈回路，从而实现功能自动验证、回归测试执行及复杂应用场景的故障排查。

⭐

2.4k

Stars

🔱

130

Forks

👁

Watchers

📋

Issues

TypeScriptMIT创建于 2026/1/30更新于今天

在 GitHub 上查看访问主页

README

由 Gemini 翻译整理

agent-device

为 AI Agent 提供移动应用验证能力。

这是一个用于 iOS、Android、TV 和桌面端真实应用的设备自动化 CLI 工具。它能够为 Agent 提供高 token 效率的快照、语义引用（semantic refs），并仅在需要时捕获证据。

agent-device 让编码类 Agent 能够通过一个 CLI 打开应用、检查当前 UI、与可见元素交互并收集调试证据。当 Agent 不仅仅需要根据代码进行逻辑推理，而是需要验证设备上实际发生的情况时，请使用该工具。

如果你了解 Vercel 的 agent-browser，那么 agent-device 就是移动端、TV 端和桌面应用的同类产品。

它适用于原生 iOS 和 Android 应用，以及使用 Expo、Flutter 和 React Native 构建的应用，只要目标应用可以在受支持的设备、模拟器、仿真器或桌面环境中运行即可。

agent-device 演示：Codex 使用 agent-device 通过简单提示在 iOS 联系人应用中创建新联系人

功能特性

检查 (Inspect)：通过紧凑的无障碍（accessibility）快照、交互式引用（如 @e3）、选择器和 React Native 组件树来检查真实的应用 UI。
交互 (Interact)：执行打开应用、点击、输入、滚动、执行手势、等待、断言状态、处理弹窗以及关闭会话等操作。
证据捕获 (Capture evidence)：通过截图、视频、日志、追踪（traces）、网络流量、性能采样、崩溃上下文和 React 性能分析记录来捕获证据。
重放工作流 (Replay workflows)：通过录制 .ad 脚本实现本地运行、CI 以及可重复的 E2E 检查。
跨平台运行 (Run across platforms)：支持 iOS 模拟器、Android 仿真器、物理设备、tvOS、Android TV、macOS、Linux 以及桌面应用自动化，让 Agent 能够“亲眼所见、亲手感知”其所处理的应用。

使用场景

在代码审查或合并之前，在真实设备、模拟器和仿真器上验证移动端更改。
为 AI 编码 Agent 提供实现功能时的真实应用反馈闭环。
使用截图、日志、追踪、网络证据和崩溃上下文调试回归问题。
在需要时通过 CPU/内存采样和 React 渲染配置文件分析性能问题。
将探索性的应用交互转化为可重放的 E2E CI 检查。
在原生 iOS、Android、Expo、Flutter、React Native、TV 和桌面应用中使用统一的 Agent 工作流。

示意图：agent-device 作为 Agent 开发闭环中的实时应用验证层

快速开始

安装 CLI：

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

已安装的 CLI 帮助文档是 Agent 的事实来源。从 agent-device help workflow 开始，当任务需要进行验证（dogfooding）、调试、重放或 React Native 性能分析时，请参考特定主题的帮助信息。

前置条件取决于目标平台：Node.js 22+、iOS/tvOS/macOS 目标需要 Xcode、Android 需要 Android SDK + ADB，桌面自动化需要 macOS 无障碍权限。请参阅安装指南进行平台设置。

尝试基础循环：

# 查找应用
agent-device apps --platform ios
agent-device apps --platform android

# 开启会话
agent-device open SampleApp --platform ios

# 检查当前屏幕。-i 仅返回交互式元素
agent-device snapshot -i
# @e1 [heading] "Settings"
# @e2 [button] "Sign In"
# @e3 [text-field] "Email"

# 执行操作、捕获证据并关闭
agent-device fill @e3 "test@example.com"
agent-device screenshot ./artifacts/settings.png
agent-device close

快照会为当前屏幕上的元素分配如 @e1、@e2 和 @e3 等引用。最新快照中的引用可立即执行操作；在滚动或切换屏幕后，请重新获取快照。

后续步骤

配置你的 Agent：从 Cursor、Codex、Claude Code、Windsurf 或其他 Agent 终端运行 CLI。有关技能、规则、直接 MCP 工具和特定客户端的设置，请参阅 AI Agent 设置。
尝试示例应用：克隆仓库并运行捆绑的 Expo 固定装置（fixture），进行首次带有截图、重放和性能证据的引导式体验。请参阅快速开始。
深入了解：使用命令文档、重放与 E2E 等更多资源。