【攻略】agent-device使用指南
agent-device给AI编码Agent补上移动端“眼睛和手”：它能读取无障碍树、操作iOS与Android应用、保存截图和日志，并把一次探索沉淀成可在CI复跑的验证脚本。
先说它解决什么问题：AI编码Agent已经能改React Native、Flutter和原生应用代码，却经常卡在最后一步——它不知道改完的页面在真机或模拟器里长什么样，也无法独立完成“打开应用、点击、输入、等待、截图、查看日志、确认结果”这一整套验证。
Callstack开源的agent-device，就是给编码Agent补上这套移动设备反馈回路。它既是命令行工具，也是MCP服务器和Node.js API。Agent可以通过无障碍树读取界面，用稳定的元素引用执行操作，再把截图、视频、日志、性能数据和复现步骤留给人检查。
截至2026年8月24日核验时，仓库约有4200个Star、261个Fork，采用MIT许可证；最新版本是v0.20.10，发布于2026-08-24 07:04 UTC，主分支当天仍有提交。近30天本地攻略索引未出现该仓库。
项目档案
- 项目名称：agent-device
- 维护组织：Callstack
- GitHub仓库：https://github.com/callstack/agent-device
- 许可证：MIT
- 最新版本：v0.20.10
- 主要语言：TypeScript
- 支持入口：CLI、MCP、Node.js API
- 主要平台：iOS、Android、HarmonyOS、tvOS、Android TV、Amazon Vega OS TV、Web、macOS和Linux
- Node.js要求：基础功能需要22.12或更高版本；Web自动化需要24或更高版本
它和传统自动化测试有什么不同
Appium、Detox、Maestro更适合由人预先写好测试用例，然后长期稳定复跑。agent-device的思路不同：Agent先观察当前界面，再决定下一步动作。它可以在探索过程中找到按钮、填写表单、捕获崩溃、检查日志，最后把有效步骤保存成脚本。
这意味着它适合“编码Agent刚改完一个页面，需要自己验证”的动态场景。它也不是传统测试框架的替代品。探索成功后，可以把流程保存为.ad脚本，或者导出严格的Maestro YAML，再放进CI中稳定执行。
它读取的是界面无障碍快照，而不是只对着截图猜坐标。快照会返回按钮、文本框、角色、标签和临时引用，例如@e2。Agent可以对这个引用执行点击或输入。这样既节省视觉模型消耗，也比固定屏幕坐标更能适应不同设备尺寸。
安装前准备
先确认本机Node.js版本：
node --version然后全局安装最新版：
npm install -g agent-device@latest\nagent-device doctor\nagent-device help workflowdoctor会检查运行环境。不要跳过这一步，因为不同平台还依赖各自的设备工具：iOS通常需要Xcode与Simulator，Android需要ADB和模拟器或已授权设备，HarmonyOS与电视平台也有各自后端。
这个工具本身没有必须填写的模型API Key。它只是设备操作与取证层；真正驱动它的Codex、Claude Code或其他Agent，仍按各自的账号或模型提供方配置运行。
第一次完整操作：打开应用、读取界面、点击并留证
官方README用iOS通讯录演示。下面保留相同操作逻辑：
# 打开应用并创建会话\nagent-device open Contacts --platform ios\n\n# 只输出可交互元素\nagent-device snapshot -i\n\n# 对最新快照中的按钮引用执行操作，并等待界面稳定\nagent-device press @e2 --settle\n\n# 填写输入框；具体引用以当前输出为准\nagent-device fill @e7 "Ada" --settle\n\n# 保存审阅证据\nagent-device screenshot ./contact-form.png\n\n# 关闭会话\nagent-device close这里最大的坑是：引用只对最近一次输出有效。按下按钮后，界面结构改变，旧的@e7可能已经变成新的引用。每次--settle都会输出差异，后续动作应该使用差异中的最新引用。只有当差异没有包含目标元素时，再重新执行snapshot。
接入Codex或其他支持MCP的Agent
agent-device自带标准输入输出模式的MCP服务器：
{\n "mcpServers": {\n "agent-device": {\n "command": "agent-device",\n "args": ["mcp"]\n }\n }\n}配置完成后，Agent可以用结构化工具调用打开应用、读取快照、执行手势、查看日志和保存证据。CLI与MCP走的是同一套运行时，所以会话、设备占用、选择器与证据模型保持一致。
如果只是让编码Agent在终端里做一次验证，CLI往往更直接；如果你正在开发自己的QA Agent，或者希望工具参数有明确类型，MCP与Node.js API更适合。
在Node.js中调用
项目公开了类型化客户端：
import { createAgentDeviceClient } from "agent-device";\n\nconst client = createAgentDeviceClient({ session: "qa-run" });\n\ntry {\n await client.apps.open({ app: "com.apple.Preferences", platform: "ios" });\n const snapshot = await client.capture.snapshot({ interactiveOnly: true });\n const button = snapshot.nodes.find((node) => node.role === "button");\n if (button) {\n await client.interactions.press({ ref: button.ref });\n }\n} finally {\n await client.sessions.close();\n}这套API适合把移动端验证嵌入PR机器人、内部发布流水线或多Agent编排系统。finally中的会话关闭很重要：没有正常释放设备，后续任务可能误以为模拟器仍被占用。
一个实用工作流
把它用在真实项目里，可以按以下顺序：
- 让编码Agent实现页面或修复缺陷。
- 启动对应平台的模拟器或连接测试设备。
- 运行
agent-device doctor确认工具链。 - 让Agent打开应用并执行
snapshot -i。 - 按“观察—操作—等待—再观察”的节奏走完整流程。
- 对关键节点保存截图、日志或视频。
- 把确认有效的步骤保存为
.ad脚本。 - 在CI里复跑，并把证据文件作为构建产物保留。
最适合Agent执行的提示词，不是“帮我测一下”，而是带明确验收目标，例如：
实现注册页后，在iOS模拟器和Android模拟器分别走完一次注册流程；检查错误提示和成功页面；保存两端截图与日志；如果流程稳定，把步骤保存成可复跑脚本。
常见坑
1. 无障碍标签差，Agent就会“看不清”
agent-device主要依赖无障碍树。按钮没有清楚标签、多个元素角色相同、测试ID混乱时，Agent会得到一棵信息贫乏的树。移动端可访问性不仅服务用户，也直接决定Agent自动化的稳定性。
2. 不同平台的能力并不完全一致
iOS、Android的后端成熟度较高，HarmonyOS和Vega OS等较新后端只覆盖部分命令。开始任务前可以运行：
agent-device capabilities --platform android不要因为README列出了某个平台，就默认所有操作、日志和性能功能都完全相同。
3. 并行Agent会争抢设备
项目用会话和本机设备声明来避免多个工作树互相接管模拟器，但团队仍要给设备资源制定规则。若同时跑多个任务，最好为每个任务分配独立模拟器、会话名和测试账号。
4. 真机数据要隔离
Agent可以输入、点击、读取界面并保存证据。不要直接拿个人手机、真实客户账号或生产环境支付流程做实验。使用专门测试设备、最小权限账号和可清理数据集。
5. 探索成功不等于稳定测试
Agent临场走通一次，只能证明当时环境下可行。要把它变成工程保障，还需要保存脚本、固定前置数据、设置明确断言，并在CI里重复验证。
适合谁，不适合谁
适合：使用AI编码Agent开发移动应用的团队；React Native、Expo、Flutter或原生应用开发者；希望让PR机器人完成端到端冒烟验证的人；需要把截图、日志、视频和复现步骤一起交付的QA团队。
不适合：只开发后端服务且没有界面验证需求的项目；无法提供模拟器或测试设备的团队；希望一次探索就代替完整测试体系的人；对Agent操作设备没有权限隔离和数据清理机制的组织。
agent-device最有价值的地方，不是让AI“自动点手机”，而是把编码、运行、观察、修正和留证接成一个闭环。AI写代码已经不稀奇，能让它对自己的改动拿出可检查证据，才是开发流程真正往前走的一步。