Midscene.js完整指南视觉驱动的AI UI自动化从入门到落地【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个由视觉语言模型驱动的 AI UI 自动化框架它用截图代替 DOM 选择器驱动 Web、Android、iOS、HarmonyOS 和桌面应用执行操作与断言并自带 HTML 报告、Playground 和 Chrome 扩展适合需要写 E2E 测试、又不想被选择器维护拖垮的测试工程师与开发者。最短上手路径两条命令看到效果不急着理解原理先让一个 Agent 替你点完一个页面。安装依赖并写一个最小脚本仓库的核心 Web 包是midscene/web配合 Playwright 使用集成代码在 packages/web-integration/src/playwright/npm install midscene/web playwright下面这个脚本打开一个页面用一句自然语言完成任务再用视觉断言检查结果——这是 README 里推荐的最小集成方式import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/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(搜索最新新闻并打开第一条结果); await agent.aiWaitFor(文章正文可见); await agent.aiAssert(页面显示了标题和正文); await browser.close();跑完后 Midscene 会自动生成 HTML 报告里面有时间轴、每步截图、元素定位框和 AI 的决策记录这是它和跑完只给一行日志的工具最大的差别。零代码路线Chrome 扩展如果只是想先验证某句话能不能驱动你的界面装 Midscene 的 Chrome 扩展即可不用写任何脚本。它本质上是把 packages/visualizer/ 的 Playground 嵌进了浏览器可以先在扩展里调好指令措辞再搬进脚本。核心机制为什么只靠截图就能找到元素传统方案Playwright 定位器、Appium 选择器的逻辑是先解析 DOM/控件树再按 selector 命中元素。Midscene 走的是另一条路看屏幕 → 按所见操作 → 校验可见结果和人工测试员的思路一致。元素按外观和位置定位不写选择器也不要求页面有语义化标注icon-only 按钮、canvas绘制内容、跨域 iframe 里的控件都能直接点这些正是 DOM 方案的盲区断言同样是视觉的可以断言选中项有蓝色边框和对勾这类 DOM 断言覆盖不到的表现。这套机制带来两个直接后果维度传统选择器自动化Midscene 视觉路线元素定位CSS / XPath / 无障碍树截图 模型判断页面改版后的维护量结构一变选择器批量失效对结构变化更鲁棒canvas / 跨域 iframe需要额外处理或不可用直接可用单步成本几乎为零每步一次模型调用结果确定性高存在模型不确定性需要等待与重试兜底也就是说Midscene 用每步一次模型调用换掉了选择器长期维护 特殊场景不可达值不值取决于你的界面复杂度。官方在 AppControlBench60 个任务上的实测成本是 $0.59Doubao Seed 2.1 TurboPass1 为 96.7%AndroidWorld 达到 93.1%Gemini-3.5-Flash场景选型按你要做什么选入口Midscene 是 monorepopackages/下每个平台一个包但它们共用同一套 Agent APIaiAct、aiTap、aiInput、aiQuery、aiAssert、aiWaitFor所以迁移成本很低。你要做什么用哪个包 / 入口说明接入现有 Playwright 测试midscene/web/playwright→PlaywrightAgent包住已有page即可已用 Puppeteer 的项目midscene/web/puppeteer→PuppeteerAgent同一套 Agent API从终端接管本机正在用的 ChromeBridge 模式midscene/web/bridge-mode实现见 packages/web-integration/src/bridge-mode/通过扩展桥接已登录的桌面浏览器Android 真机 / 模拟器midscene/android→AndroidAgentAndroidDevicepackages/android/src/基于 ADB scrcpy 预览iOS 设备 / 模拟器midscene/iospackages/ios/src/基于 WDAHarmonyOSmidscene/harmonypackages/harmony/src/基于 hdc桌面应用操作midscene/computerpackages/computer/src/含原生键鼠输入驱动声明式 YAML 测试项目midscene/testpackages/test/Beta带脚手架、重试、并发隔离移动端示例Android长这样API 风格和 Web 完全一致import { AndroidAgent, AndroidDevice } from midscene/android; const device new AndroidDevice(); const agent new AndroidAgent(device); await agent.launchApp(com.android.settings); await agent.aiTap(关于手机); const info await agent.aiQuery(型号与版本号);如果任务里要读数据而不是点按钮用aiQuery拿结构化结果传一个期望的 JSON 描述用aiBoolean做是/否判断再把两者放进你自己的循环逻辑里——这比把所有控制流都塞进一句aiAct更稳、更省钱。排坑与调优你大概率会遇到的四类问题模型没配好或配错模型通过环境变量配置而不是代码里的字符串参数解析逻辑在 packages/shared/src/env/export MIDSCENE_MODEL_NAME模型名 export MIDSCENE_MODEL_BASE_URLAPI地址 export MIDSCENE_MODEL_API_KEY密钥支持的多模态模型包括Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS等开源模型可以自托管。建议先固定一个模型把流程跑通再换模型做 A/B 对比别一开始就纠结选型。步骤偶发失败先加等待再拆步骤视觉定位存在不确定性最常见的失败是上一步动画没结束就点了下一步。两个处理习惯关键步骤后加aiWaitFor(某个可见结果)而不是固定sleep长流程拆成查询 → 判断 → 单步操作例如先aiQuery拿到列表再用aiBoolean逐项判断只对需要的项目执行aiTap。成本与耗时控制每一步都是一次模型调用脚本越长越贵。仓库自带缓存机制重复执行相同指令时可以直接复用历史结果MIDSCENE_CACHEtrue npx playwright testCI 里建议日常提交开缓存跑夜间全量关缓存跑一次真模型验证。失败排查从报告而不是日志入手MIDSCENE_REPORTtrue打开报告输出后每个用例会生成独立 HTML 报告包含每步截图、元素定位框、AI 决策文本和断言结果。排查顺序建议是先看截图确认屏幕状态对不对再看 AI 决策链里它以为看到了什么最后才怀疑模型能力问题。进阶扩展YAML 测试项目midscene/test把 UI 流程写成 YAML把 API 调用、数据准备、清理封装成 TypeScript Node声明意图与工程逻辑分离。简单用例- web: url: https://example.com - aiTask: 搜索最新发布的版本 - aiAssert: 页面显示了版本标题Midscene Skills让 AI 编码智能体如 IDE 内的 Agent直接通过技能操作界面源码在 packages/core/src/skill/。录制回放packages/recorder/ 提供操作录制与时间轴回放配合 apps/chrome-extension/ 调试指令措辞。CLI 批量执行packages/cli/ 提供命令行入口支持批量跑 YAML 脚本并输出执行摘要。收尾清单npm install midscene/web playwright对你们内部的一个页面跑通上面的PlaywrightAgent最小脚本打开生成的 HTML 报告配好MIDSCENE_MODEL_*环境变量同一脚本换两个模型各跑一遍记录耗时与失败率打开一次失败用例的报告按截图 → AI 决策链 → 模型能力的顺序定位一次根因用MIDSCENE_CACHEtrue对比开缓存前后的执行时间决定是否纳入 CI 日常任务需要读源码时克隆仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene然后pnpm install pnpm build重点看 packages/core/src/agent/ 里的任务编排逻辑。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考