Midscene 纯视觉 GUI Agent 指南：一张截图驱动 Web 与移动端 UI 自动化

Midscene 纯视觉 GUI Agent 指南一张截图驱动 Web 与移动端 UI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个面向 E2E 测试的开源 GUI Agent它只拿界面截图作为输入你用自然语言描述操作与断言它通过统一 API 驱动 Web、Android、iOS 和桌面端界面。适合不想再维护选择器、需要跨平台跑 UI 用例的测试工程师。一句话定位Midscene 是什么它是一个视觉驱动的 UI 测试与自动化 SDK见 introduction.mdx你用 JavaScript SDK 或 YAML 写自动化aiAct、aiQuery、aiAssert等 API 在一套接口下覆盖所有平台。官方定位是 UI 测试优先但同一套视觉引擎可用于任意 UI 自动化任务。与 DOM 自动化的对比纯视觉定位的区别在哪业界做元素定位主要有两条路DOM 数据 标注截图或纯视觉截图定位见 model-strategy.mdx。Midscene 选了后者差异可以量化选择器方案在每次重构后失效且对无语义标记的元素纯图标按钮、canvas、跨域 iframe不可见原生 App 基本够不到纯视觉方案下人能看到的元素Midscene 就能点并且能断言用户实际看到的东西——颜色、高亮状态、布局而不只是某个 DOM 节点存在token 消耗只取决于页面分辨率和任务复杂度不随 DOM 节点数膨胀。代价文档也写明纯视觉要求模型具备稳定的 GUI 操作能力不能拿任意 LLM 顶替。原理一次 aiAct 调用的完整链路核心链路可以拆成输入→处理→输出三段源码都在 packages/core/src/agent/。输入当前截图 自然语言目标。处理多模态模型先规划任务、拆成原子操作再逐个在截图上视觉定位元素并执行。输出设备端动作序列每次运行还会生成可逐步回放的可视化报告。模型侧默认一个 Default 模型承担规划、定位、页面理解遇到复杂场景可以追加 Planning 模型增强规划和 Insight 模型增强数据提取与断言。成本侧的关键是缓存task-cache.ts 把规划与定位结果持久化为.cache.yaml文件字段结构如下字段含义typeplan规划结果或locate定位结果prompt自然语言指令是缓存命中的键yamlWorkflow规划出的 YAML 工作流plan 类型cache.xpaths定位结果附带的 DOM 交叉校验信息locate 类型缓存还做了防退化处理版本低于 0.16.10 的旧缓存直接拒绝当某个缓存命中的元素导致动作失败时该条记录被标记为 stale 并原地替换而不是追加重复项源码注释指向 issue #2529。能力验证aiAct、aiQuery、aiAssert 三个核心 APIquick-start.mdx 里的示例证明了三类能力各一行代码即可表达await agent.aiAct(Click the login button); // 规划并执行 const items await agent.aiQuery{ name: string; price: number }[]( Products on the page, {name: string, price: number}[]); // 提取结构化数据 await agent.aiAssert(A navigation bar appears at the top of the page); // 视觉断言basics.mdx 还提供两个按调用粒度调节的开关代价是更多模型调用与延迟await agent.aiAct(Complete the checkout form, { deepThink: true, // 规划与定位拆成独立模型调用 deepLocate: true, // 小目标元素增加一次定位调用 });除 JS SDK 外YAML 脚本可交给 CLI 批量执行packages/cli/ 下有完整的批量运行器与测试用例。上手从 0 到跑通的最短路径 三条路线按时间从短到长Chrome 扩展 Playground装好扩展、把模型配置粘贴进侧边栏直接在网页上输入自然语言指令零项目依赖见 quick-start.mdx接入 Playwright / Puppeteer 测试套件把在 Playground 里验证过的指令转成 Agent 调用import { PlaywrightAgent } from midscene/web/playwright; import { chromium } from playwright; const browser await chromium.launch(); const page await browser.newPage(); await page.goto(https://example.com); const agent new PlaywrightAgent(page); // 页面与模型在此接线 await agent.aiAct(click the login button);需要看完整实现时克隆仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene要求 Node^20.19.0 || ^22.12.0 || 24.0.0、pnpm9.3.0见 AGENTS.md。Android 侧走 ADB scrcpy实现见 packages/android/。数据AndroidWorld 与 MobileWorld 基准说了什么introduction.mdx 给出的官方基准结果如下注意数字绑定具体版本与模型不是框架的理论上限基准运行配置结果AndroidWorld Pass1Midscene 1.9.5 Gemini-3.5-Flash93.10%AndroidWorld Pass2 / Pass3同上95.69% / 97.41%MobileWorld Pass1Midscene 1.10.3 Gemini-3.6-Flash78.63%92/117AppControlBench60 任务iOS 模拟器Midscene 1.12.03 个视觉模型详见 报告AppControlBench 报告附带了按模型分组的通过率与成本图表成本按 OpenRouter 价格计算边界模型门槛、延迟与 token 成本以及什么时候别选它⚖️ 几个真实代价全部有文档出处模型能力门槛只有对 GUI 操作稳定的指定模型可用换模型需要重新验证通过率延迟aiAct在每步都用 AI 重新规划官方明确它比即时交互更耗时、更费 token毫秒级实时控制不适用多模型组合Planning Insight会进一步增加延迟和 token 消耗文档建议只在遇到明确能力瓶颈时再加JavaScript 编排只能响应代码里已处理的界面变化比如分辨率变化导致需要额外滚动时工作流会失败缓存命中依赖 UI 跨次运行稳定界面改动后对应条目会失效并触发重新定位完全离线场景需要自托管开源模型Qwen、UI-TARS 等默认路径是调用云端 API。收尾三句话选型结论如果你的自动化要同时覆盖 Web、移动端和桌面或界面含 canvas、自定义渲染Midscene 的纯视觉路线值得第一个进评估清单。若你的目标是纯后端 API 或毫秒级延迟链路它不是合适的工具。建议路径先用 Chrome 扩展在单页验证指令再把验证过的自然语言步骤迁移进 Playwright 套件的aiAct/aiQuery调用。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考