企业官网建设流程全解析

Midscene.js 快速上手指南：3 行自然语言跑通跨平台视觉 E2E 测试

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

在网页上敲一句"搜索耳机并筛选低于 100 美元"，Midscene.js 会自动找到搜索框、输入、回车，再把商品标题和价格整理成 JSON 返回。它靠视觉理解屏幕，让 AI 替你操作和验证界面，同一套 Agent API 覆盖 Web、Android、iOS 与桌面应用。

它和传统 UI 自动化差在哪

Midscene.js 是一个面向 E2E 测试的 GUI Agent：你不需要写选择器，它像人一样"看屏幕—动手—核对结果"，用截图判断点哪里、界面是否符合预期。对写自动化脚本、维护 E2E 用例，或想在多端复用同一套操作逻辑的人来说，它把"定位元素"这件事从代码搬进了自然语言。

和传统方案的主要差别：

零代码先试一把：Chrome 插件与 Playground

写脚本之前，最省事的路径是不装任何东西，直接在浏览器里体验。

在 Chrome Web Store 安装 Midscene 扩展后，浏览器右侧会出现侧边栏。打开任意网页，在侧边栏里输入一句自然语言，点 Run，就能看到 Midscene.js 理解页面并执行操作。

在移动端，可以先启动对应的 Playground，不用写代码就能调用aiAct、aiQuery、aiAssert：

npx --yes @midscene/android-playground

Playground 和脚本 SDK 共享同一套实现，你在面板里验证过的指令，原样搬进代码也能跑通。

最小跑通路径：配好模型，跑通第一个脚本

Playground 验证过后，正式写脚本只有三步：配模型、装依赖、写脚本。

第一步：配置一个多模态模型

Midscene.js 把模型配置放在环境变量里，以豆包 Seed 2.1 Turbo 为例，把 API Key 换成你自己的：

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

配置好后，用dotenv/config可把这组变量放进.env随项目走，脚本里就不用硬编码。

第二步：安装依赖

下面一条命令把 Web 端 SDK、Playwright 和用来跑 TypeScript 脚本的tsx一次装好：

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

第三步：写一个 Playwright 脚本

保存为demo.ts。它会打开 eBay、搜索耳机，并把结果整理成数组打印出来：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; import 'dotenv/config'; const browser = await chromium.launch({ headless: true }); 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}[], find item and corresponding price', ); console.log('headphones in stock', items); await browser.close();

用npx tsx demo.ts运行。命令执行完，控制台会打印Midscene - report file updated: .../report/xxx.html，用浏览器打开就能看到每一步的截图和 AI 决策过程。

核心能力拆解：两个最常打的 API

Midscene.js 的 API 分两类：一类是自主规划的aiAct，一类是"定位一个元素、做一个动作"的即时操作，比如aiTap、aiInput、aiScroll。理解这个区别，你就能在灵活和确定性之间做选择。

aiAct接收一个自然语言目标，自己观察界面、拆解步骤、定位并执行，直到目标完成。它基于最新界面状态持续规划，因此通常比即时操作更耗时、更耗 token，但更抗页面变化，适合路径不确定的任务。

aiQuery只观察界面、不改界面。你在提示词里描述要什么数据、什么结构，它就把屏幕上看到的整理成对应对象返回；aiAssert则做视觉断言：

const items = await agent.aiQuery<Array<{ name: string; price: number }>>( '购物车中的商品，{name: string, price: number}[]', ); await agent.aiAssert('购物车中有一件商品，并且页面显示了小计金额');

返回的items形如[{ name: '无线耳机', price: 99.9 }]，可直接喂给后续逻辑。aiAssert描述的条件成立时正常结束，不成立时抛出错误，并在错误信息里带上模型给出的原因。

一条电商验收工作流

把上面的能力串起来，就是一个真实的验收流程。以"验证搜索结果都低于 100 美元"为例：

打开页面后用aiAct完成"搜索耳机并筛选低于 100 美元"，接着用aiWaitFor等筛选结果加载出来，避免在页面还没稳定时就读数据。数据稳定后，aiQuery把列表里的商品标题和价格取成数组，你不必再为每个价格写一个选择器。最后用aiAssert断言"列表里每件商品的价格都低于 100 美元"——条件不成立会直接抛错，测试就此失败。

整条流程里你只描述意图，Midscene.js 负责"看—做—查"，报告则保留了每一步的证据，方便事后复盘。

边界与排障

Midscene.js 的能力来自视觉理解，也由此带来几个明确的边界，提前知道能少踩坑。

浏览器内核有讲究

Web 端的部分能力依赖 Chrome DevTools Protocol（CDP），例如触摸手势和一些交互兜底路径。用 Playwright 时推荐 Chromium；Firefox 和 WebKit 能覆盖基础的 Playwright 原生操作，但依赖 CDP 的能力可能报错。

元素定位不准怎么查

定位偏移是高频问题。按官方 FAQ 的思路排查：先升级到最新版@midscene/web；再确认MIDSCENE_MODEL_FAMILY配置正确（配置错误会影响模型适配）；把提示词从功能描述改成视觉描述，比如aiTap('页面右上角的人形头像图标')比aiTap('个人中心')更稳；如果定位落在目标附近但有几像素偏差，开启deepLocate选项通常能改善。

隐私：截图会被发到哪里

Midscene.js 会把页面截图发送到你的 AI 模型。调用aiQuery、aiAsk时如果传入domIncluded: true，DOM 信息也会被一并发送。涉及敏感页面时，建议先评估这一点，或按需选择模型服务。

延伸资源

• 安装与模型配置：快速开始
• Playwright 完整集成：integrate-with-playwright
• 模型与配置说明：model-common-config
• 常见问题 FAQ：faq
• Android 平台指南：platforms/android
• 核心 Agent 实现：packages/core/src/agent/
• Web 端 SDK：packages/web-integration/

下一步

先用 Chrome 扩展在你的工作页面上敲一句指令，确认模型配置没问题；再把它搬进demo.ts跑通第一个 Playwright 脚本，打开报告看看每一步。挑一个你每天重复的界面操作开始，剩下的交给 Midscene.js。

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