用一句自然语言驱动浏览器：Midscene 完整指南

用一句自然语言驱动浏览器：Midscene 完整指南

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

每天早上登录后台、核对页面数据、截图存档——这套动作你每天在做吗？Midscene 是一个开源 GUI Agent：你用一句自然语言描述目标，它看截图、规划步骤、替你把界面操作走完，还能把看到的内容抽成结构化数据。

能力速览：四个 API 各管什么

所有方法的参数和用法，可在 API 参考 里按名查找。

两行命令装好环境，跑通第一条指令

安装依赖，一条命令把 Agent、浏览器驱动和运行器都装齐：

npm install @midscene/web playwright @playwright/test tsx --save-dev

接着配置模型。Midscene 需要一个有 UI 定位能力的多模态模型，配置通过环境变量传入，建议直接写进.env：

export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MIDSCENE_MODEL_FAMILY="doubao-seed"

支持哪些模型、怎么选，见 支持的模型与配置。

然后写一个demo.ts。这段脚本让浏览器打开 eBay，用一句自然语言完成搜索，再把结果抽成结构化数据：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; import 'dotenv/config'; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('https://www.ebay.com'); const agent = new PlaywrightAgent(page); await agent.aiAct('type "Headphones" in search box, hit Enter'); const items = await agent.aiQuery( '{itemTitle: string, price: number}[]', ); console.log(items); await browser.close();

接着打开终端，执行npx tsx demo.ts。几秒后命令行会打印出商品标题和价格的数组；控制台同时输出一行报告路径，用浏览器打开那个 HTML 文件，能逐步回放开头的每一步——截图、AI 规划了什么、点到了哪里，一目了然。

不想写代码也可以：Chrome 扩展版 Playground 里，打开任意网页就能直接输入自然语言指令体验交互、提取和校验，完整流程见 快速开始文档。

自然语言替代 CSS 选择器：重构不再打断用例

如果你正在维护一批 UI 用例，应该熟悉这种处境：前端一次样式重构，几十个选择器集体失效，测试工程师花一整天追选择器。Midscene 不读 DOM（网页元素的树状结构），只凭截图工作——只要人眼能看到的元素，它就能定位。纯图标按钮、<canvas>渲染的控件、跨域 iframe 里的内容，这些靠结构化工具够不到的地方，反而是它的用武之地。样式怎么改、节点怎么挪，只要界面上还能认出来，用例就不用动。

校验用户真正看到的效果

当你需要确认"用户看到的界面对不对"时，光查某个节点是否存在不够。aiAssert校验的是视觉结果：颜色、高亮、布局、渲染状态，而不是节点在不在。每次运行还会生成可逐步回放的可视化报告，失败时直接看那一步的截图和耗时，不用翻日志猜：

重复跑的用例，让缓存替你省时间

如果在 CI 里反复跑同一批脚本，模型调用次数会持续累积。Midscene 会把 AI 规划结果和元素定位信息写进./midscene_run/cache目录，相同指令在相似页面下直接命中缓存。官方文档给出的实测案例里，一次任务耗时从 51 秒降到 28 秒：

启用方式和策略选择见 缓存文档。两点先说清楚：查询类操作（aiQuery、aiAssert）永不缓存，每次都是真实模型调用；如果缓存下来的规划执行失败（比如偶现弹窗这次没出现），它会自动回退到 AI 重新规划，不用手动清缓存。

三个可以直接抄的实战场景

回归关键路径。目标：把"打开页面 + 搜索 + 出现结果"这条主链路变成每晚必跑的用例。做法：用 YAML 描述流程，不搭框架，midscene命令直接执行；校验不通过时，报告里直接带失败那步的截图。你会得到：一条每晚自动跑的守卫，链路断了在合并前就能发现。

page: url: https://www.ebay.com tasks: - name: 搜索并校验 flow: - ai: type "Headphones" in search box, hit Enter - aiAssert: 结果列表中至少出现一个耳机商品

多设备界面巡检。目标：确认同一套 App 在不同型号手机上，关键界面都正常。做法：设备接上 adb，脚本循环连接每台设备，对"我的"页、设置页分别发一句aiAssert，例如"页面显示设备名和存储信息"；也可以在 Android Playground 里看着手机屏幕被逐步操作、逐步规划，效果就是下面这张图的样子。你会得到：一张每台设备、每个界面的通过/失败清单，失败项自带截图。

报表抽数入库。目标：每天早上 9 点把运营后台报表页的数据变成 JSON。做法：aiAct负责翻页、选日期区间，aiQuery按{orderNo: string, amount: number}[]这样的结构取出表格内容，落库或推给下游任务。你会得到：一份每天准时到达的结构化数据，不再有人手工复制粘贴。

几个容易踩的坑

• 注意：aiQuery这类查询操作不缓存，高频轮询型脚本要单独评估模型成本。
• 建议：API Key 放.env，别写死在脚本里，团队共享脚本时尤其如此。
• 建议：指令写得越具体越好，"右上角蓝色按钮"比"按钮"的命中率高得多。
• 如果headless: true时看不到浏览器窗口，别慌，报告里每一步都带截图，照样能回放定位问题。

想动手的话，最快的路是打开 Playwright 集成文档，把上面的 demo 换成自己天天点的那个页面，今晚就跑起来。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene