Midscene：字节跳动开源的视觉驱动 E2E 测试 GUI Agent

Midscene 来自字节跳动的 web-infra-dev 组织，以 MIT 协议开源（© 2024–至今 ByteDance Inc.），官网显示 GitHub 星标已超 15k，曾冲上 GitHub 趋势榜第 2 名。它的口号是”像人一样使用软件，用自然语言完成 E2E 测试”。和传统 Playwright 脚本靠 CSS 选择器定位不同，Midscene 是一个基于视觉（screenshot）的 GUI Agent：它截图、看屏幕、像人一样凭外观找到按钮再点下去。本文基于其官方仓库 README 与中文文档站，拆解它的机制、官方 benchmark 与成本口径。

一、背景：选择器够不到的地方

传统 E2E 测试有个长期痛点：脚本依赖精确的选择器，一改版就全红；而且对图标按钮、自定义控件、<canvas> 绘制内容、跨域 iframe、以及原生 App 界面，DOM 选择器根本无能为力。Midscene 的思路是绕开 DOM——“凡可截图皆可自动化”，直接让多模态模型看截图来定位和判断。

二、是什么：五个自然语言 API

接入 Playwright 后，测试用例长得像这样：

await agent.aiAct('Search for headphones, then filter the results to under $100');
await agent.aiWaitFor('The filtered search results are displayed');
await agent.aiAssert('Every product has a price below $100');

对外的核心 API 分两类：自主流程类（aiAct 让 Agent 自己走完一个流程），以及原子操作类（aiTap、aiInput），再加 aiAssert（自然语言断言”这个套餐有蓝色边框和对勾”）和 aiQuery（结构化数据抽取）。断言也走视觉路线——像人工测试员一样看屏幕判断预期效果是否出现。

同一套 Agent API 横跨 Web、PC（macOS/Windows/Linux）、移动端（Android/iOS/HarmonyOS），还能通过提供截图与动作能力接入自定义界面。

三、技术机制：截图即输入，多模型可组合

Midscene 不给模型灌整棵 DOM 树，而是以截图作为主要输入来做定位与判断，这也是它能触达 canvas、原生界面的根本原因。模型策略上，默认用一个多模态模型同时负责规划、元素定位与页面理解；复杂任务可再加一个专门的 Planning 或 Insight 模型；做数据抽取时才可选性地把 DOM 一起喂进去。官方称这种”视觉为主、按需补 DOM”的策略是在效果与成本之间取平衡。

它支持的多模态模型很广：豆包 Seed 2.1（官方推荐的稳妥默认）、Qwen3.x、DeepSeek V4 Flash、GLM-4.6V、gemini-3.5-flash、UI-TARS 等，其中含可自托管的开源模型。工程上还附带 Midscene Test（Beta，用 YAML 写声明式意图、TypeScript Node 包业务逻辑）、逐步回放的 HTML 报告（记录每一步截图、元素位置、AI 决策过程）和 Playground。

具体到定位这一步，它和 DOM 选择器是两套范式：拿到截图后，由视觉模型在图上圈出候选元素的边界框，再换算成视口坐标去点击或输入——这正是它能命中图标按钮与 canvas 的原因，这些地方在 DOM 里根本没有可选中的节点。代价是每个动作都要付一次”截图+视觉推理”，所以它才强调默认”视觉为主、按需补 DOM”：纯靠截图跑长流程会又慢又贵，遇到需要精确读字时再把 DOM 作为补充上下文喂进去。

四、关键数据：官方 benchmark 与成本

官网公布的成绩如下：

成本方面，官方给出最有说服力的一个数字：在 AppControlBench 的 60 项任务上，用豆包 Seed 2.1 Turbo 跑完，模型调用总费用仅 $0.59。

五、评测方法批判：数字要分开读

这些数字好看，但有几个口径必须打折：

1. 三个榜用了三个不同模型：AndroidWorld 用 Gemini-3.5-Flash、MobileWorld 用 Gemini-3.6-Flash、AppControlBench 用豆包 Seed 2.1 Turbo，并不是同一个模型打全场，横向并不能直接比较难度或模型强弱。
2. AndroidWorld 报告自曝”validator adjustments”：官方在报告里说明该榜做了环境与校验器调整，意味着成绩不是开箱即得的原始分。
3. $0.59 是 60 个任务的累计，且高度依赖所用模型单价；换成昂贵的闭源模型成本会成倍上升——官方主推豆包 Seed 正是因为它”视觉定位可靠且便宜”。
4. Pass@1 vs Pass@3：93.1% 是一次通过率，Pass@3（允许重试三次）才到 97.4%，真实 CI 里 flaky 重试的成本要自己算。
5. 视觉路线天然更慢更贵：每个动作都要”截图→模型推理→点击”，比直接调一次 DOM 接口慢；它省的是维护成本，不是运行时间。

六、优势与局限

优势： 一是真正跨端，Web/移动/桌面一套 API，且能测 canvas、跨域 iframe、原生 App 这些选择器盲区；二是免选择器、改版维护成本低；三是背靠字节内部大规模使用（官网列出 ByteDance、火山引擎、抖音、TikTok、飞书、豆包，以及阿里、携程、小米等），工程成熟度与报告/Playground 工具体系完整；四是模型不锁定、可自托管开源模型。

局限： 视觉断言比 DOM 断言更”模糊”，对精确数值、像素级样式的判定仍可能误判；每个动作都付模型调用费，高频跑全量 E2E 要做成本预算；Midscene Test 仍标 Beta；效果强依赖所选视觉模型，换模型就是换一套成功率。

七、谁该关注

• 维护选择器成本高、经常改版的中后台/移动端团队：自然语言用例 + 视觉断言能显著降低 flaky 与改版返工；
• 需要测 canvas、跨端 App、原生界面的团队：这是 DOM 类工具（Playwright 原生）覆盖不到的场景；
• 已经在用 Playwright/Puppeteer：可以只把视觉能力（aiTap/aiAssert）嵌进现有框架，渐进采用，不必推倒重来。

如果你的测试追求毫秒级速度、像素级精确断言，且界面稳定，传统 DOM 测试依然更快更省；Midscene 的主场是”选择器够不到、改版又频繁”的那类界面。

参考来源

• Midscene GitHub 仓库（web-infra-dev/midscene）
• Midscene 官方文档站
• Koala 项目库条目