Agent Device让AI自己验收App

AI会写界面，却还不会证明界面正确

AI 编码工具已经能修改 React Native、Swift、Android 或 Flutter 项目，但代码编译通过，不等于用户可以完成操作。按钮可能被浮层挡住，输入框看似填入却没有触发状态更新，登录请求可能返回成功而页面仍停在原处；只看一张截图，也无法证明控件真的可点击。

浏览器自动化有 DOM 和 Playwright，原生 App 却要面对 accessibility tree、XCTest、ADB、系统权限、模拟器状态与真机差异。Agent Device^[1] 想补上的正是这段反馈链：让编码 Agent 读取界面结构、执行操作，再用结构变化、截图、日志、录屏与回放证明发生了什么。

截至 2026 年 9 月 27 日，GitHub 仓库 API^[2] 显示其有 4,789 个 star、313 个 fork、106 个开放 issue 与 PR；最新正式版 v0.21.15^[3] 发布于 9 月 25 日，主分支当天仍有提交。这些数字说明项目活跃，却不能证明测试成功率。本文选择它，是因为它不只会“点屏幕”，还试图把观察、动作、断言和失败证据组织成一条可审计的闭环；如果你的首要要求是工具本身必须带可视化 GUI，它并不是最贴切的选择。

它不是模型，也不是Claude专属插件

Agent Device 本身不提供大模型，也不是 Claude Code 的专属插件。它是一套由命令行工具、stdio MCP Server 与类型化 Node.js API 组成的本地自动化运行时；Claude Code、Codex、Cursor、Windsurf 等宿主负责理解需求和规划步骤，Agent Device 负责读取设备状态、执行命令并返回结构化结果。换一个支持 CLI 或 MCP 的 Agent，底层执行能力仍可复用。

本地链路可以简化为：宿主模型调用 MCP 工具，MCP 通过同一套 AgentDeviceClient 合同连接本地 daemon，daemon 再驱动 iOS 模拟器、Android 模拟器或真机后端。MCP 暴露的是经过定义的设备命令，不是任意 Shell；CLI、MCP 和 Node API 也不是三套互不相干的产品，而是同一会话、设备占用和证据模型的不同入口。

实际使用时，先安装并检查 CLI，再在编码 Agent 中把 agent-device mcp 配成 stdio MCP。随后让 Agent 按 open → snapshot → act → re-snapshot → verify → close 工作：先打开 App 和会话，读取可交互快照，再点击、输入或滚动，最后复查界面并关闭会话。它可以在本机运行并成为 MCP，但前提仍是机器已经具备对应平台的开发工具、模拟器或设备连接；“MCP 已连上”只说明工具入口可用，不代表 iOS、Android 后端已经就绪。

UI正确与否，取决于你定义的准入条件

Agent Device 不知道产品设计意图，因此不能独立判断一个 UI “正确”。它能回答的是：当前有哪些可访问元素、某个动作是否发出、界面是否稳定、动作前后结构有何变化，以及产生了哪些证据。真正的正确性必须由团队先写成可验证的准入条件；命令成功、界面稳定和业务正确是三件不同的事。

以登录页为例，最小验收合同应先固定测试账号、设备型号、系统版本和初始页面。操作层要求邮箱框、密码框与登录按钮能从语义快照中唯一定位，没有歧义、没有被遮挡；输入后要复核字段状态。点击登录时可以使用 --settle 等待短暂静默，但 settled: true 只表示观察窗口内界面不再变化，既不证明请求成功，也不证明用户已经进入正确账户。

业务层还要写出显式断言，例如登录表单消失、首页唯一元素出现、错误提示不存在；高风险流程可再核对网络响应、日志或后端测试数据。失败时保留截图、结构差分与日志，才能区分是控件没点中、页面没稳定、接口失败，还是验收规则本身写错。只有这些条件同时成立，才应把该次运行判为通过。

准入规则还要规定超时和不确定状态如何处理。例如十秒内没有出现首页标志，应判为失败并保留现场，而不是继续尝试到“碰巧成功”；快照缺失、元素匹配不唯一或证据采集失败，则应判为不可判定并交给人处理，不能降级成通过。把未知状态单独列出，才能避免自动化把自身盲区包装成业务成功。

它对误点还设置了一道机制门禁：快照里的 @e12 一类 ref 只对当前引用帧有效，可能改变 UI 的动作会让旧 ref 过期。导航后若继续使用旧引用，工具应返回 ref_frame_expired，而不是碰巧点击新页面同一位置的元素。探索路径确认后，可以保存为 .ad 脚本并用 replay 做确定性回放；目标漂移会产生结构化 divergence 和候选建议，不会静默改写脚本。

本文在主分支提交 16e07572 上运行了引用帧、settle 和输出相关测试，42 项通过，完整 TypeScript typecheck 也通过。这只能说明当前代码中的关键合同在该环境下自洽，不能外推为所有 App、真机和系统版本都可靠。公开 issue #1571^[4] 记录过冷启动后首个快照为空的竞态，#2996^[5] 则显示 iOS 浮动栏可能被误判为遮挡物；工具可以暴露不确定性，却不能消除平台本身的不确定性。

Figma可以成为设计基线，但不能直接当测试脚本

如果已经有 Figma，确实可以和 Agent Device 组合成基础 UI self-test，但中间必须增加一层“UI 验收合同”。当前官方仓库没有 Figma 直连能力，也没有证据表明它能读取设计稿后自动生成可靠测试；更现实的链路是：从 Figma 指定 Frame 并导出基准图，由人定义设备、页面状态、关键文案、必备控件、视觉容差和动态区域遮罩，再让 Agent Device 执行流程、采集语义快照与实际截图，最后输出结构差异、视觉差异和待人工确认项。

这套验收至少分三层。功能验证检查“用户能否完成登录”；结构验证检查输入框、按钮、错误态与首页标志是否存在且可操作；视觉验证才比较实现截图与 Figma 基准图。三者不能互相替代：流程走通不代表间距、字号和颜色正确，像素相似也不代表按钮可以点击。

一份最低可用的登录页合同，可以写明：以 iPhone 指定机型的浅色模式为基准；页面必须出现标题、两个输入框和一个主按钮；按钮文案与 Figma 一致；提交后十秒内首页标志出现；状态栏和头像区域不参与视觉差分，其余区域超过约定阈值就输出差异图并等待人工确认。这样的合同才能同时约束测试状态、功能结果和视觉边界。

视觉比较还必须先控制变量。设备分辨率、像素密度、字体版本、深浅色模式、状态栏、安全区、键盘、时间、电量以及异步图片都会制造无意义差异；头像、推荐流、时间戳等动态区域应固定测试数据或设置遮罩。Agent Device 可以负责把 App 导航到指定状态并采集截图，但像素差分、感知相似度和阈值判定需要另接视觉比较工具或团队自己的脚本，不能把“有截图”写成“已有视觉验收”。

适合第一轮试点的不是整个 App，而是登录页、设置页或权限页这类状态有限的流程。先为一个固定设备和一个固定页面状态写清结构断言与视觉容差，让 Agent 自动执行、人工复核差异；等误报来源稳定后，再把确认过的路径沉淀为回归测试。这样，Figma 是设计基线，验收合同是判断标准，Agent Device 是执行与取证层，三者职责不会混淆。

本地MCP风险可控，远程控制要更谨慎

纯本地使用时，通常不需要手工填写 Token。官方 Security & Trust^[6] 文档说明，daemon 默认只监听 127.0.0.1 的临时端口，每次启动生成 24 字节随机 Token，并把记录它的 daemon.json 权限设为 0600；stdio MCP 和 CLI 在本机复用这套内部认证。这个 Token 是本地进程间的防护，不是需要提交到项目配置的产品密钥。

Remote Proxy^[7] 解决的是另一种场景：运行 Agent 的远程机器碰不到本地模拟器或真机，于是在设备所在的 Mac 上启动代理，再通过隧道转发 daemon 的有限 HTTP 接口。它不是本地 MCP 的必要组成部分。代理使用直接的 Bearer Token，任何拿到 Token 的人都可能控制被代理设备；因此 Token 不应写入仓库内的 agent-device.json，应放在受保护的环境变量或运维配置中，并在会话结束后停止代理和隧道。

风险不只来自控制通道。截图、录屏、日志、网络包、trace、回放文件和云设备链接都可能包含账号、Token、客户信息或内部页面；如果宿主使用云端模型，快照、日志和提示上下文本身也会离开本机边界。证据目录应默认不入 Git，测试使用假账号和脱敏数据，并在发送给外部模型或分享给同事前审查。

回放脚本同样不能视为无害文本。官方文档明确指出，Maestro 的 runScript 与 evalScript 通过 node:vm 在进程内执行，而 node:vm 不是安全沙箱；runScript 还可以发出网络请求。远程 HTTP 会拒绝 evalScript，但这不等于可以执行来源不明的测试仓库或脚本。2026 年披露的 GHSA-m7q5-6423-2mwq^[8] 就与项目配置重定向远程端点并泄露凭据有关，影响 0.8.0–0.20.3，0.20.4 起修复；当前核实的 0.21.15 不在受影响范围，但团队仍应固定并审查版本。

更稳妥的落地方式是：使用专用模拟器和假账号，先只启用本地 MCP；把截图、日志和回放目录排除出版本控制；涉及删除、购买、授权或真实数据的步骤保留人工确认；连续两周只跑一个固定关键流程，记录通过率、人工纠错次数和耗时。只有错误能被证据定位、同一环境下可以重复、维护成本低于节省的手工验收时间，才扩大覆盖。Agent Device 的价值不是替你定义“正确”，而是让 AI 的每次 UI 判断都能追溯到明确规则和可检查证据。

引用链接