Midscene.js AI 自动化安装教程：10 分钟从零跑通视觉驱动的 GUI Agent
Midscene.js AI 自动化安装教程10 分钟从零跑通视觉驱动的 GUI Agent【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个基于视觉的 GUI Agent用于 E2E 测试与界面自动化。它只靠截图理解界面你用自然语言描述每一步它就替你点击、输入、取数、断言覆盖 Web、Android、iOS、HarmonyOS 和桌面端。本指南带你从 0 到 1 完成源码搭建、环境验证和模型配置。它能做什么核心价值速览Midscene 不依赖 DOM 或无障碍树而是直接「看」截图因此图标按钮、canvas、原生 App、跨域 iframe 这些语义标注缺失的元素也能命中。界面交互用一句自然语言完成点击、输入、滚动等操作数据提取从截图里结构化地取出价格、列表等字段界面断言校验颜色、高亮、布局等「用户真正看到」的状态多端统一同一套 API 跑 Web、移动端和桌面应用适合谁写 E2E 测试想降低维护成本的测试工程师、希望用自然语言驱动自动化的开发者以及想二次开发 Agent 能力的贡献者。准备工作安装前的前置检查动手前先确认本机工具版本。仓库根package.json通过engines锁定了运行环境不符合要求的版本会在安装时直接报错。依赖项版本要求说明Node.js^20.19.0或^22.12.0或24.0.0官方推荐 20.19.0pnpm9.3.0仓库指定packageManager: pnpm9.3.0Git任意较新版本用于拉取源码与配置内存建议 8 GB 以上monorepo 全量构建较吃内存磁盘建议 2 GB 可用空间存放依赖与构建产物网络可访问模型服务运行时需要调用多模态模型用下面两条命令快速自检node -v pnpm -v如果 Node 不在要求区间建议用 nvm 或 fnm 切到 20.19.0 再开始。安装步骤从 0 到 1整个过程只涉及四条命令每一步只做一件事。获取源码把仓库克隆到本地并进入目录。git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene启用 pnpm通过 corepack 打开 pnpm让版本与仓库锁定的一致。corepack enable安装依赖拉取全部依赖、建立 monorepo 包间软链并触发prepare脚本完成一次构建。pnpm install全量构建如果上一步的构建不完整或你需要单独重跑再执行一次完整构建。pnpm run build构建产物由各包独立管理想只构建某个包时用npx nx build 项目名即可例如npx nx build midscene/web。快速验证确认环境已跑通装完立刻验证别等配置完才发现环境没跑通。先用一条类型检查命令确认依赖与 TypeScript 配置正常pnpm run type-check:tests没有报错说明工具链就位。接着跑一次单元测试确认构建产物可加载AI 相关测试需要配置模型见下文pnpm run test想只验证单个包把测试范围收窄到具体项目即可npx nx test midscene/web命令执行完毕且无致命报错就表示源码、依赖、构建这条链路已经通了。项目结构速览Midscene 是一个 pnpm monorepoapps/放面向用户的应用packages/放核心库。下表覆盖主要模块的用途方便你定位代码。模块路径包名用途packages/core/midscene/coreAgent 执行、规划、模型集成与设备抽象packages/web-integration/midscene/webPlaywright/Puppeteer 集成Web 自动化主入口packages/android、ios、computer、harmonymidscene/*各平台运行时配同名*-playgroundpackages/testmidscene/test可扩展的 YAML 测试运行器与 Node SDKpackages/climidscene/cli命令行批量执行 YAML 脚本packages/visualizermidscene/visualizer报告渲染与回放 UIapps/playground-浏览器里的 Playground 应用apps/chrome-extension-Chrome 扩展版 Playgroundapps/reportmidscene/report执行报告生成与查看apps/site/docs/zh/-中文文档源码含快速开始与平台指南配置要点API 密钥与模型参数Midscene 依赖具备 UI 定位能力的多模态模型需要先配置密钥与模型名再让 Agent 调用。准备多模态模型选用Qwen3.x、UI-TARS等带 UI 定位能力的模型开源模型可自托管。在源码目录创建.env写入OPENAI_API_KEY与MIDSCENE_MODEL_NAMEAI 相关测试与运行都从这里读取密钥。指定模型名例如MIDSCENE_MODEL_NAMEqwen3-vl-plus按你实际接入的模型调整。在 Playground 中粘贴配置使用 Chrome 扩展或 apps/playground 时把同一组配置粘贴到设置页并保存。密钥与模型参数只影响运行时的 AI 能力缺失时构建和单元测试仍可进行但涉及aiAct、aiQuery、aiAssert的调用会失败。上手体验自动化场景一览网页端在浏览器 Playground 里输入一句符合当前页面的自然语言指令即可。规划并执行用「点击登录按钮」提取结构化数据用「页面中的商品{name: string, price: number}[]」检查界面用「页面顶部显示导航栏」。跑通后同样的指令可以直接落到agent.aiAct/aiQuery/aiAssert的 API 里集成进你的 Playwright 测试。移动端以 Android 为例设备接入后即可执行设备信息读取、应用启动、界面元素定位与交互、自动化用例执行。同一套视觉引擎也覆盖 iOS、HarmonyOS 和桌面端接口一致切换平台只需换设备适配器。常见问题 QA问安装或构建时报依赖版本不兼容答先确认 Node 落在^20.19.0 || ^22.12.0 || 24.0.0区间、pnpm 不低于 9.3.0。版本对不上是绝大多数报错的根源用 nvm/fnm 切到 20.19.0 通常能解决。问能只构建midscene/core而不跑全量吗答不建议单独构建 core。报告模板存在包间循环依赖core 的 HTML 模板依赖 report 的构建产物单独构建会出现占位符未解析或缺少模板模块的报错。请跑全量构建。问依赖装不上或状态异常怎么办答先清理再重装。执行pnpm install重试仍异常时可用仓库的清理脚本删除各包dist与缓存后重新安装。问跑 AI 测试提示没有密钥或调用失败答AI 测试依赖.env里的OPENAI_API_KEY和MIDSCENE_MODEL_NAME。补齐后重启终端再运行pnpm run test:ai。下一步学习路径跑通 Playground先看 apps/site/docs/zh/ 里的快速开始在浏览器里完成第一条自然语言指令。读懂核心引擎进 packages/core/ 看 Agent 的执行、规划与模型集成是怎么组织的。接入 Web 测试参考 packages/web-integration/ 与文档里的 Playwright/Puppeteer 集成篇把指令写进真实用例。扩展 YAML 用例熟悉 packages/test 的 YAML 运行器用声明式脚本批量跑自动化。配好模型、跑通 Playground 之后你手上就有一个能看懂截图、听懂指令的自动化助手了。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考