CLI Agent-Device 让智能体操控真机做移动测试

一、项目介绍

移动端测试的自动化脚本，写起来枯燥又脆弱：每个控件都要记 selector，元素一改版就全线崩掉；而 Agent 想验证"点了这个按钮之后页面变成了什么样"，就需要能看到界面并留下证据——这两件事，传统的 Appium 脚本都很难提供。

Agent-Device 是面向 AI Agent 的设备层，同时提供 CLI、MCP 服务与类型化的 Node.js API。它把设备操作抽象成一套 Agent 能读懂的命令：先 snapshot 拿到当前界面的元素引用，再按引用做点击、输入，每次操作后返回与上一次的差异。

它的后端覆盖相当广：iOS 模拟器快照走本地辅助桥、iOS 真机与 tvOS 用 XCTest，Android / Android TV / Fire OS 走 ADB，HarmonyOS 走 HDC 与 ArkUI uitest，macOS 上的 Electron 应用走本地辅助桥，Linux 走 AT-SPI。MIT 协议，Callstack 出品。

Agent-Device 解决的是移动端自动化里一个长期存在的错配：脚本要写死选择器，Agent 却需要"看懂"界面。传统 Appium 脚本里每个控件都得记 id 或 xpath，改版一次全线崩；Agent 想要的是"这个按钮在哪、点了之后页面变成了什么样"。

它的答案是基于无障碍树的元素引用。snapshot -i 返回的不是坐标或 id，而是一组带语义的信息：@e2 [button] "Add"——既是引用，也是控件类型和可访问名称。人看得懂，Agent 也读得懂。

--settle 的设计同样关键。执行操作后等界面稳定，然后返回与上一次的差异：哪些元素新增了、哪些文本变了。Agent 不需要重新拍一张全屏快照再自己比对，差异是直接给的。这既省 token，也让判断更准确。

后端覆盖面是它的工程量所在：iOS 模拟器快照走本地辅助桥，iOS 真机与 tvOS 用 XCTest；Android、Android TV、Fire OS 走 ADB 与快照辅助工具；HarmonyOS 用 HDC 与 ArkUI uitest；Vega 用 Vega CLI/VDA；macOS 上的 Electron 等 Chromium 应用走本地辅助桥，Linux 走 AT-SPI。不同后端支持深度不一，官方提供了 capabilities 查询命令。

它还有一层面向工程实践的设计：会话按调用方的 Git worktree 划分，宿主级的设备占用机制避免并行 Agent 抢占同一个模拟器；录制的 .ad 脚本能在 CI 里回放，配合截图与日志作为产物存档。

二、项目基本信息

三、核心优势

• snapshot 输出带稳定引用的元素列表，Agent 不必自己记 selector
• 每次操作返回与上一次的界面差异，Agent 能据此判断下一步
• CLI、MCP 服务、类型化 Node.js API 三种接入方式，覆盖脚本、Agent 与集成场景
• 支持截图与录像作为证据，回归结果可留档
• 录制为 .ad 脚本后可在 CI 中回放，把本地验证搬进流水线
• 会话按 Git worktree 划分，并行的 Agent 不会互相抢模拟器
• 后端覆盖 iOS、Android、HarmonyOS、桌面与浏览器平台
• 元素引用同时携带控件类型与可访问名称，人与 Agent 都能读懂
• 操作后直接返回界面差异，避免重复全屏快照带来的 token 浪费
• 基于无障碍树取信息，界面有清晰标签与测试 ID 时运行更可靠
• 提供 agent-readable 文档（llms-full.txt），Agent 可自行查阅用法

四、适用场景

适合做移动应用 QA 自动化、希望把真机 / 模拟器操作交给 AI Agent 的团队；也适合需要在 CI 中回放 UI 流程、留存测试证据的研发流水线。

它的价值在"Agent 驱动的移动端 QA"这个具体场景上。如果你的团队还在写传统 Appium 脚本、且应用结构稳定，那继续用现有方案更划算。

值得引入的信号是：你已经让 AI 参与测试或修复，但 Agent 卡在"看不见界面"这一步；或者你的应用迭代频繁，选择器维护成本已经超过写测试本身。

跨平台能力需要实测。不同后端支持的命令集不完全一致，HarmonyOS 与 Vega OS 只覆盖部分命令，跑之前先执行 agent-device capabilities --platform <platform> 查清楚，能避免很多"为什么这一步不行"的困惑。

环境要求是硬门槛：Node.js 22.12 以上，网页自动化要 24 以上。用之前先跑 agent-device doctor，把运行环境问题在开工前暴露掉。

集成到 CI 的路径是现成的：录成 .ad 脚本、在流水线里回放、把截图与日志作为构建产物保存。官方还提供了 EAS workflow 模板可以直接参考。

如果你正被同类问题反复绊住——要么是人肉重复劳动没完，要么是工具装不上跑不通、要么是产出的结果根本没法用——那这个项目值得先花十分钟装一遍试试。

五、安装教程

当前最新版本 v0.21.35。下面是可直接执行的安装方式：

# 需要 Node.js 22.12 以上；网页自动化需要 Node.js 24 以上
npm install -g agent-device@latest

# 检查环境是否就绪
agent-device doctor

# 查看工作流指南（调试、回放、性能分析）
agent-device help workflow

常见报错与处理：依赖缺失时先确认运行时版本（Node、Python、Rust、PHP 等）是否满足项目要求；网络超时多半是镜像或代理问题，可换源重试；权限类报错请检查当前账号是否已登录对应平台，以及脚本是否需要管理员权限执行。

六、使用示例

下面这段是可以直接参照的真实用法：

# 开启一个 iOS 设备会话
agent-device open Contacts --platform ios

# 查看当前界面，返回元素引用
agent-device snapshot -i
# @e2 [button] "Add"

# 按引用点击，等待界面稳定后返回差异
agent-device press @e2 --settle
# 差异包含：
# + @e7 [text-field] "First name"

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

# 留下证据并关闭会话
agent-device screenshot ./contact-form.png
agent-device close

七、常见问题

问：元素引用（ref）能一直用吗？答：只在最新一次输出里有效。执行 --settle 命令后应使用它返回的差异中的 ref，只有当差异里没有你需要的元素时才重新 snapshot。

问：怎么接入 MCP？答：执行 agent-device mcp 会启动官方 stdio MCP 服务，把已安装的命令以结构化工具暴露给 Agent，执行路径与 CLI 完全一致。

问：能在 CI 里跑吗？答：可以。把一次运行录成 .ad 脚本，在 CI 中回放，并把截图与日志作为产物保存；官方提供了 EAS workflow 模板示例。

问：各平台支持深度一样吗？答：不完全一样。HarmonyOS 与 Vega OS 等后端只覆盖部分命令，可用 agent-device capabilities --platform <platform> 查看具体支持范围。

问：怎么提升元素识别的稳定性？答：给控件加上清晰的可访问标签、角色与测试 ID，识别质量会明显提升。

问：并行跑多个 Agent 会抢设备吗？答：宿主级设备占用机制会阻止这种情况，可用 agent-device device status 查看占用情况。

以上是实际使用中最常被问到的几个问题。若遇到文档未覆盖的情况，可以先翻项目的 Issues 与 Discussions 区，那里有更多真实踩坑记录。

八、总结

Agent-Device 在把高频动作压缩成一条命令这件事上做到了足够扎实的程度：它不追求大而全，而是把一个具体环节做透，让原本要靠人盯的流程变成可以交给工具执行的流程。

从上面的安装步骤和使用示例可以看出，它的接入成本并不高：一条命令装好，按提示完成配置，然后就能把它放进你原有的工作流里。如果你正在被同类问题困扰，不妨先在自己的一小块任务上试一轮，确认顺手了再推广到日常流程中。