项目介绍
agent-device 是 Callstack 面向编码 Agent 开发的跨平台应用自动化工具。它把可访问性快照、稳定元素引用、设备操作和证据采集统一在 CLI、stdio MCP 与 TypeScript API 中，让 Agent 能在写完代码后直接打开应用、验证交互并把截图、日志、网络或性能证据带回修复循环。它覆盖移动设备、电视、网页和桌面，但实际能力取决于目标平台与本机工具链。采用前应把设备控制、系统权限、远程令牌和产物保留视为明确的安全边界。
核心功能
可访问性快照与稳定引用
snapshot -i 返回可交互节点及 @ref，Agent 可用引用、id、label 或 role 选择器操作，并通过 diff 与 wait 检查界面变化。
跨平台应用控制
统一命令覆盖应用打开、点击、输入、滚动、返回、方向、安装和状态查询；具体可用命令由所选设备的 capabilities 返回。
调试与证据采集
可采集截图、屏幕录像、应用日志、网络活动、内存与帧性能、CPU profile 和 trace，供 Agent 验证功能或回归。
MCP 结构化工具
agent-device mcp 通过 stdin/stdout 提供结构化工具，并复用 CLI 执行路径；它不暴露通用 Shell，操作员拥有的路径和令牌也不会成为模型可写工具参数。
回放与测试输出
可将常用流程保存为 .ad 脚本，生成机器可读结果，并导出 Maestro YAML 以衔接既有端到端测试。
安装与连接
由人先安装并运行 doctor，完成目标平台 SDK、设备信任和系统权限后，再把经过评审的固定版本接入 Agent。CLI 是最直接入口；需要结构化工具时再配置本地 stdio MCP。
让 AI Agent 帮你安装
把这段话发送给 Codex、Claude Code 或其他可以操作本地环境的 AI Agent。
请帮我安装并最小验证 agent-device。项目地址：https://github.com/callstack/agent-device。先阅读 README、installation、agent-setup 与 security-trust 文档，确认 Node.js 22.12+ 和目标平台工具链。优先安装我指定的固定版本；如果我未指定，请展示最新正式发布与当前 npm/manifest 版本差异后询问。安装后先运行 agent-device doctor，不要自行授予 macOS 辅助功能或屏幕录制权限，不要信任真机、启用 Developer Mode、配置签名、启动远程代理、连接设备云或使用生产应用。只在隔离的测试模拟器上完成打开应用、读取 snapshot -i、执行一个低风险交互、保存截图和关闭会话。不要把令牌、网络内容或含敏感信息的产物写入版本库；任何安装 SDK、修改系统设置、连接真机或上传外部服务的步骤都先询问我。- Node.js 22.12 或更高版本，并可使用 npm
- iOS 需要 Xcode；Android 需要 Android SDK 与 ADB；其他平台按文档准备对应工具链
- 真机已由用户完成配对、Developer Mode、签名或 ADB 信任
- macOS 自动化所需的辅助功能和屏幕录制权限由用户授予
- 明确选定并固定要交给 Agent 使用的版本
npm install -g agent-device@latest
agent-device doctor- 1安装并检查环境
安装经过评审的 agent-device 版本，运行 agent-device doctor，修复目标平台缺失的 SDK 或命令行工具。
- 2打开隔离测试应用
在模拟器或专用测试设备上运行 agent-device open，并显式指定平台或设备，避免误选生产真机。
- 3用快照引用完成交互
运行 snapshot -i 获取当前 @ref，优先按引用或语义选择器执行 press、click、fill 或 scroll，并用 --settle 或 wait 验证结果。
- 4采集最小证据
把截图、必要日志或测试结果保存到受控目录；发送或提交前检查是否包含账号、令牌、客户数据或私密界面。
- 5关闭并清理会话
执行 agent-device close，确认设备声明与临时会话已释放；远程工作流还应断开云设备、隧道和代理。
运行 `agent-device doctor`，确认目标平台检查通过；随后在测试模拟器执行 `agent-device open <测试应用> --platform <平台>`，用 `snapshot -i` 得到交互引用，完成一次只读导航或低风险点击，保存截图并执行 `agent-device close`。命令返回预期界面状态且截图落到指定路径，才算基础安装可用。
- 仓库建议 Agent 使用全局、项目本地或固定版本安装，避免未经评审直接执行可变的 latest。
- 首次运行部分平台辅助程序时可能触发编译、签名或系统权限提示，应由用户处理。
- 配置 MCP 后需要重新连接或重启客户端才能加载新服务器。
- 先用 capabilities 确认目标设备支持的命令，再编写跨平台流程。
使用场景
编码 Agent 的应用验收循环
Agent 修改应用后立即打开测试构建、完成关键交互、截取证据，再把发现的问题带回代码修复。
跨平台冒烟测试
用相同工作流骨架分别选择 iOS、Android 或其他平台，并依据 capabilities 调整平台特有步骤。
可复现的回归证据
将稳定流程保存为 .ad 脚本，输出 JSON 或 JUnit 报告，并在需要时导出 Maestro YAML。
远程设备实验室
通过受保护的远程代理或设备云让 CI Agent 使用集中设备，同时把令牌、租约、产物和网络范围纳入独立治理。
使用评价
agent-device 的优势是把 Agent 需要的应用操作、状态判断和调试证据放进同一套版本化接口，并认真处理并行设备声明、结构化错误和模型不可写的操作员配置。它适合已有移动或多端工程基础设施的团队。代价是原生工具链、系统权限和平台差异都很真实，远程代理与设备云还会显著扩大信任边界。0.21 系列仍在快速迭代，固定版本和隔离测试设备比追随 latest 更稳妥。
值得一试的地方
- CLI、stdio MCP 与 TypeScript API 复用同一执行路径
- 可访问性快照、稳定引用和差异输出适合 Agent 循环
- 证据类型覆盖截图、录像、日志、网络、性能与追踪
- 工作树会话、设备声明和租约机制降低并行争用
- 安全文档明确本地绑定、令牌、产物和远程代理风险
- MIT 许可证明确，提交和正式发布均保持活跃
使用前要知道
- 平台支持深度不同，跨平台脚本仍需能力检测和分支
- 需要 Node.js 与多套原生 SDK，安装和 CI 镜像维护成本较高
- 系统权限与真机信任不能安全地完全交给 Agent 自动完成
- 网络与日志证据可能捕获敏感数据，必须单独治理
- 远程代理令牌授予实质设备控制权，暴露错误后果严重
- manifest 0.21.1 与最新 GitHub release v0.21.0 暂有版本差异
README
agent-device
Overview
Callstack 维护的跨平台应用自动化工具，通过 stdio MCP、CLI 和 TypeScript API 驱动移动设备、电视、网页与桌面应用，并采集截图、日志、网络和性能证据。 Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
Getting started
- 由人先安装并运行 doctor，完成目标平台 SDK、设备信任和系统权限后，再把经过评审的固定版本接入 Agent。CLI 是最直接入口；需要结构化工具时再配置本地 stdio MCP。
- agent-device 把应用导航、快照、交互、安装、回放与证据采集放进一个面向 Agent 的命令面，并通过相同执行路径暴露 stdio MCP 和 TypeScript API。
- 推荐工作流是打开应用、读取带 @ref 的交互快照、按引用或选择器操作、等待明确状态、采集证据并关闭会话。
- 运行 `agent-device doctor`，确认目标平台检查通过；随后在测试模拟器执行 `agent-device open <测试应用> --platform <平台>`，用 `snapshot -i` 得到交互引用，完成一次只读导航或低风险点击，保存截图并执行 `agent-device close`。命令返回预期界面状态且截图落到指定路径，才算基础安装可用。
Configuration
npm install -g agent-device@latest
agent-device doctor