企业官网建设流程全解析

Midscene.js 视觉UI自动化速成指南：从克隆到跑通首脚本的 4 步

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

产品页一改版，回归脚本里几十个 CSS 选择器集体归零，测试套件一夜变红。Midscene.js 是一个用视觉大模型"看"屏幕、再驱动鼠标键盘的开源跨平台 GUI 自动化框架，官方定位是面向 E2E 测试的 GUI Agent。

📷 原理：它是如何"看懂"屏幕的

每一步操作的输入都来自截图。当你写下"点击右下角蓝色提交按钮"，Midscene 会先对当前画面截图，连同指令一起发给具备 UI 定位能力的多模态模型（Qwen、豆包 Seed、GLM、Gemini、UI-TARS 等，其中不少可自部署），模型返回目标坐标，运行时再把坐标换算成真实的点击、输入或滚动。复杂指令则循环执行"截图—规划—操作"，直到完成。

正因为如此，canvas 里画出来的控件、没有任何语义标签的图标按钮、网页摸不到的原生应用，它都能操作——只要人眼在屏幕上看得见。做数据提取和页面理解时，也可以按需在提示中附带 DOM，但它不是必需的。

对照传统方案：基于 DOM 选择器或可访问性树的自动化，结构一变就失效，DOM 里不存在的东西更无从下手；Midscene 只以屏幕像素为准绳，代价是每步都要模型参与、比直接点击慢，换回来的是不再维护选择器。

🚀 上手主线：克隆仓库到首脚本只有一条路

环境要求 Node.js 20.19+ 与 pnpm 9.3+。先把仓库构建出来：

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene pnpm install && pnpm build

接着配置一个有 UI 定位能力的模型，以豆包 Seed 为例：

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"

在独立目录执行npm install @midscene/web playwright tsx，照下面写 demo.mts，再用npx tsx demo.mts运行：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; 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('在搜索框输入 Headphones 并回车'); const items = await agent.aiQuery('{title: string, price: number}[]'); await agent.aiAssert('页面左侧有类目筛选功能');

跑完后控制台会打印一份 HTML 报告文件路径，浏览器打开即可回看每一步的截图与规划。不想写代码的话，也可以构建仓库里的插件工程apps/chrome-extension/，以解压方式加载进 Chrome，在任意网页的侧边栏直接输入自然语言指令。

能力：一套 API，两种形态，五个端

JS SDK 与 YAML 两种写法

交互类用aiAct自动规划、aiTap/aiInput/aiScroll即时操作；提取类用aiQuery/aiString/aiNumber；验证类用aiAssert，等待用aiWaitFor。不想搭测试框架时，写一份.yaml声明page:/browser:/android:/ios:/harmony:/computer:环境加tasks步骤，用midscene命令执行即可；官方的 Test Runner（Beta）正在取代老版 YAML 方案。

五个端共享同一套视觉 API

Web 端可接 Playwright、Puppeteer 或 Chrome 扩展；Android 走 adb，iOS 走 WebDriverAgent，HarmonyOS 走 hdc，桌面端直接操控鼠标键盘。API 在五个端之间保持一致，各端都配有可交互的 Playground，仓库apps/目录下有对应的示例工程。

Bridge 模式：脚本接管你的桌面 Chrome

AgentOverChromeBridge让本地脚本连接日常使用的 Chrome，复用现成的登录态、cookie 与插件，适合"人机协作"场景；YAML 里加一行bridgeMode: newTabWithUrl同样可以开启。

报告与缓存

每次运行自动产出单文件 HTML 报告，截图、操作、断言结果都能回看；配合agent.cache缓存策略，未变化的步骤重跑时命中缓存，省下模型调用与等待时间。

实战：两个最小可运行用例

Web 端：搜索并提取商品数据

把流程写进 YAML，用midscene ./search.yaml执行，name字段的值会进入 JSON 输出：

page: url: https://www.ebay.com tasks: - name: 搜索耳机 flow: - ai: 在搜索框输入 Headphones 并回车 - aiWaitFor: 搜索结果列表已加载 - name: 提取商品信息 flow: - aiQuery: 找出列表中的商品标题和对应价格 name: items

Android 端：同一套语言驱动真机

环境声明换成android:段，步骤写法与 Web 完全一致。先用adb devices确认设备已连接，再执行midscene ./android-search.yaml：

android: launch: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息

⚙️ 调优速查：先动哪几个参数

模型连通与速度问题，九成集中在MIDSCENE_MODEL_*环境变量：必选 4 个是BASE_URL、API_KEY、NAME、FAMILY，其中 FAMILY 决定坐标解析方式，必须与模型匹配。

稳定性相关通常只调这三个：

export MIDSCENE_MODEL_TIMEOUT=180000 # 模型调用硬超时（毫秒），默认 180 秒 export MIDSCENE_MODEL_RETRY_COUNT=1 # 调用失败重试次数，默认 1 export MIDSCENE_MODEL_RETRY_INTERVAL=2000 # 重试间隔（毫秒），默认 2 秒

另外两个影响体感的是：Agent 入参replanningCycleLimit限制aiAct的重规划轮数（默认 20），waitForNetworkIdleTimeout控制操作后的网络空闲等待（默认 2000 毫秒，设 0 关闭）。完整清单见模型配置文档。

🧭 更多资料入口

建议阅读顺序：快速开始 → YAML 自动化脚本 → 集成到 Playwright → 桥接模式。可直接照抄的示例脚本在packages/web-integration/demo/与packages/cli/tests/midscene_scripts/。

社区方面，官方 Discord 与 X（@midscene_ai）更新活跃；项目为 MIT 许可，可以放心用于生产。

行动建议：挑一条你正用选择器维护的回归路径，改写成aiAct+aiAssert两句描述先跑起来，确认报告可读之后，再把它推进 CI。

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