agent-device

agent-device 是一个用于 iOS、tvOS、macOS、Android 和 AndroidTV UI 自动化的 CLI 工具。它专为 AI Agent 驱动的工作流而设计：检查 UI、确定性地执行操作，并保持会话感知（session-aware）且可重放。

如果你了解 Vercel 的 agent-browser，那么本项目将同样的理念应用于移动应用和设备。

项目目标

• 为 AI Agent 提供一种通过结构化快照理解移动 UI 状态的实用方法。
• 保持自动化流程的 Token 效率，以适应真实的 Agent 循环。
• 使常见的交互操作足够可靠，能够支持重复的自动化运行。
• 让自动化工作基于会话、选择器（selectors）和可重放流程，而非一次性脚本。

核心理念

• 会话 (Sessions)：打开一次目标，在会话内进行交互，然后干净地关闭。
• 快照 (Snapshots)：以紧凑的形式检查当前无障碍树（accessibility tree），并获取用于探索的稳定引用（refs）。
• 引用 vs 选择器 (Refs vs Selectors)：使用引用进行发现，使用选择器进行持久化的重放和断言。
• 测试 (Tests)：运行确定的 .ad 脚本作为轻量级 e2e 测试套件。
• 重放脚本 (Replay scripts)：使用 --save-script 保存 .ad 流程，使用 replay 重放单个脚本，或使用 test 将文件夹/全局模式作为串行套件运行。 test 支持最多 3 次元数据感知重试、单测试超时、不稳定性通过报告，以及默认存储在 .agent-device/test-artifacts 下的运行程序管理工件。每次尝试都会写入 replay.ad 和 result.txt；失败的尝试在可用时还会保留复制的日志和工件。
• 人类文档 vs Agent 技能 (Human docs vs agent skills)：文档向人类解释系统；技能为 Agent 提供简洁的操作指南。

命令流程

典型的循环如下：

agent-device open SampleApp --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device fill @e5 "search" --delay-ms 80
agent-device close

在实践中，大多数工作遵循相同的模式：

1. open 目标应用或 URL。
2. snapshot -i 检查当前屏幕。
3. 使用引用或选择器进行 press、fill、scroll、get 或 wait 操作。
4. 在 UI 更改后使用 diff snapshot 或重新拍摄快照。
5. 会话结束时执行 close。

在非 JSON 模式下，核心变动命令会打印简短的成功确认信息，以便 Agent 和人类能够区分成功执行的操作与丢失或静默的空操作。

后续步骤

对于人类用户：

• 官方网站
• 文档

对于 AI Agent：

• agent-device 技能
• dogfood 技能
• ClawHub 上的 agent-device 技能

安装

npm install -g agent-device

在 macOS 上，agent-device 包含一个本地的 agent-device-macos-helper 源码包，可按需构建以处理桌面权限检查、警报处理以及基于辅助工具的桌面快照表面。发布版本应使用已签名/公证的辅助工具构建；源码检出则回退到本地 Swift 构建。

贡献

请参阅 CONTRIBUTING.md。

由 Callstack 制作

agent-device 是一个开源项目，并将永远保持免费使用。Callstack 是一群热爱 React 和 React Native 的技术极客。如果您在这些技术方面需要任何帮助，或者只是想打个招呼，请联系我们：hello@callstack.com。