Agent Device 设备验证 CLI
让编码代理在真实运行的应用中检查、操作并验证改动。
- Star 数
- ★ 4.7k
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 50/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 开始前需要
- 典型场景
- React Native 或 Expo 开发者在 iOS Simulator 或 Android Emulator 上修改界面后，让编码代理通过 snapshot、press 和 fill 验证关键流程。
- 主要局限
- 需要 Node.js 22.12 或更高版本；若使用 Web 自动化，则要求 Node.js 24 或更高版本。
- 源码审查
- 50/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
agent-device 是面向编码代理和 QA 工具的命令行设备自动化工具，用于检查、操作和验证正在运行的应用。它支持 iOS、Android、tvOS、Android TV、Vega Virtual Device 上的 Amazon Vega OS TV、Web、macOS 和 Linux，但各目标可用的命令与证据类型不同。CLI 以会话保存设备状态，并通过 iOS/tvOS 的 XCTest、Android 的 ADB 与 snapshot helper、VVD 的 Vega CLI/VDA、macOS 本地 helper 及 Linux AT-SPI 执行操作。它可输出无障碍快照、截图、视频、日志、trace、网络与性能数据等证据，并可将成功流程保存为 .ad 脚本或导出为严格的 Maestro YAML。它既可在本地调试设备和模拟器，也可用于 CI/CD 重放验证，或配置为云端/远程执行。
先用 agent-device open <应用> --platform ios 等命令启动会话，再用 agent-device snapshot -i 读取无障碍树并取得当前 @eN 引用。代理可对最新快照中的引用或 selector 执行 press、fill、滚动、手势、等待、断言和 alert 处理，并通过 --settle 获取界面变化。它还能调用 screenshot 保存截图，以及收集视频、日志、trace、网络数据、性能样本、崩溃详情和 React profile。工作流可保存为 .ad 脚本以供本地或 CI 重放，必要时导出严格的 Maestro YAML；Node.js 项目也可使用 typed client 或公开 subpath，其中 agent-device/android-adb 提供 Android ADB、logcat、剪贴板、键盘、应用和端口反向管理接口。
- React Native 或 Expo 开发者在 iOS Simulator 或 Android Emulator 上修改界面后，让编码代理通过 snapshot、press 和 fill 验证关键流程。
- 移动端 QA 工程师把一次已成功的登录、表单或支付前置流程保存为 .ad 脚本，并在 CI 中重放并保留截图与日志。
- 原生 iOS、Android 或 Flutter 团队在无障碍信息不足时，使用截图、视频和诊断数据为缺陷报告保留可审查证据。
- 电视应用团队在 Vega Virtual Device 上发现应用、控制生命周期，并执行完整的 TV 遥控器操作。
- 负责性能排查的 React Native 团队在复现 UI 问题时收集性能样本、trace、网络数据或 React profile。
如何安装或部署这个 Agent？
安装前需准备 Node.js 22.12 或更高版本；Web 自动化需 Node.js 24 或更高版本。执行：npm install -g agent-device@latest；随后执行：agent-device doctor。README 未列出安装 CLI 所需的账号或凭据；不同目标的设备与运行环境要求由安装文档说明。
如何使用这个 Agent？
先执行 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。@eN 引用只能使用最新输出中的引用；在 --settle 后应使用 diff 中的新引用。
这个 Agent 有哪些优点和局限？
- 采用 inspect-act-verify 流程：代理可读取当前状态后逐步决定下一条命令，而不是仅执行预写测试。
- 在一个 CLI 中覆盖移动端、TV、桌面和基础 Web 自动化，并为不同目标调用其对应的底层自动化接口。
- 无障碍快照提供 token-efficient 的界面状态，且可结合 refs、selectors、截图和视频作为操作与审查证据。
- 可将已验证流程保存为 .ad 脚本，或导出严格的 Maestro YAML，便于重复执行和接入 CI。
- 为 React Native 诊断提供 React component tree、React profile 与性能相关证据能力。
- 需要 Node.js 22.12 或更高版本；若使用 Web 自动化，则要求 Node.js 24 或更高版本。
- 各平台支持的命令和证据类型不同，不能假设某个目标具备所有能力。
- Vega OS 初期仅支持 VVD，且仅覆盖发现、应用生命周期和完整遥控器控制；物理 Fire TV、capture 与 selector backend 尚不支持。
- 操作引用会随界面变化失效，必须使用最新 snapshot 或 --settle diff 中的 @eN 引用。
- 无障碍标签、角色和 test ID 不佳时，快照可靠性会下降，需依赖截图或视频等替代证据。
这个 Agent 与同类方案有什么区别？
与 Appium、Detox、Maestro 这类需要团队编写和维护测试套件的工具相比，agent-device 的定位是让代理在运行时读取应用状态并逐步选择命令。它也可作为补充：将运行保存为 .ad 脚本，或导出为严格的 Maestro YAML。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Agent Device 设备验证 CLI 当前 | 50 · 缺口较多 | ★ 4.7k | 今天 | TypeScript | Codex · Claude Code |
| iOS 模拟器技能包 | 62 · 存在缺口 | ★ 1.3k | 10 天前 | Python | Claude Code |
| Expo Skills —— Expo 官方 AI 代理技能集 | 49 · 缺口较多 | ★ 2.6k | 今天 | Shell | Codex · Claude Code |
| Docker-Android：容器化 Android 模拟器 | 41 · 缺口较多 | ★ 16k | 3 天前 | Python | — |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 建议用户先运行 doctor 检查，但未明确要求用户确认每个操作；CLI 可执行设备操作（如 press、fill），但未提及权限最小化或用户确认机制。数据流方面，README 提到保存证据（截图、日志），但未说明数据流向何处。敏感数据处理未提及。依赖仅两个运行时依赖（@limrun/api, yaml），但未提供依赖安全审计证据。外部影响：CLI 控制设备，可能产生副作用，但未说明回滚机制。来源归属：未验证发布者身份，但 README 和 package.json 明确标注 Callstack。扣分原因：缺乏明确的权限最小化、用户确认、数据流透明、敏感数据处理、依赖安全、外部影响控制、回滚机制和来源验证。
证据显示：README 和 package.json 描述一致，CLI 命令示例与文档一致，自洽性较好。依赖可用性：依赖数量少，但未提供依赖可用性保证。失败消息：README 未详细说明错误处理或失败消息。扣分原因：依赖可用性和失败消息缺乏证据。
证据显示：README 明确目标受众为 AI 编码代理，场景包括本地、CI/CD、云端。能力边界：README 列出支持平台和命令，并说明 Vega OS 初始支持限制。触发精度：命令示例明确，但未详细说明触发条件。环境适配：要求 Node.js 22.12+，web 需要 24+，并说明目标要求。扣分原因：触发精度和环境适配细节不足。
证据显示：README 结构清晰，包含快速开始、命令、FAQ、文档链接。安装说明明确（npm install -g）。命名稳定性：版本号存在，但未提供命名稳定性保证。示例和 FAQ 丰富。已知限制：README 提到 Vega OS 物理设备不支持。许可证：MIT 许可证文件存在。版本变更日志：未提供 CHANGELOG。维护责任：README 和 SECURITY.md 表明 Callstack 维护，但未验证。扣分原因：缺少版本变更日志和命名稳定性证据。
证据显示：输出可用性：CLI 提供快照、截图等输出，便于代理使用。边际价值：与 Appium/Detox/Maestro 相比，提供代理原生交互，有独特价值。成本效益：开源 MIT，免费使用，但未提供性能数据。扣分原因：成本效益缺乏量化数据。
证据显示：README 中的声明（如支持平台）与 package.json 和代码结构一致，但未提供独立验证。交叉来源：README 引用博客和视频，但未提供独立验证。事实与推断分离：README 区分了事实（支持平台）和推断（如何工作），但未明确标注。扣分原因：缺乏独立验证和明确的事实推断分离。
- 发布者身份未验证，使用前应确认来源可信。
- CLI 可执行设备操作，可能产生副作用，建议在隔离环境中使用。
- 未提供数据流透明性说明，注意证据文件可能包含敏感信息。