Midscene.js纯视觉AI:一行自然语言,掌控Web、Android、iOS、PC任意界面自动化

AI驱动、纯视觉（Vision-Driven）的跨平台UI自动化框架，开源项目——Midscene.js（GitHub：web-infra-dev/midscene）。最核心的能力是：用自然语言描述想做什么，就能自动规划步骤、定位元素、执行操作，彻底摆脱传统Selector、XPath或DOM依赖的痛点。

支持Web（Puppeteer/Playwright）、Android、iOS、桌面应用（macOS/Windows/Linux），甚至任意自定义界面（包括Canvas、重度WebView等）。纯视觉路线让它在复杂、动态、非标准UI场景下表现出色，同时大幅降低token消耗和提升稳定性。

一、Midscene.js核心功能

Midscene.js的核心理念是“Write Automation with Natural Language”，通过JavaScript SDK或YAML编写自动化脚本。

主要功能模块：

1.跨平台统一控制：

○Web：集成Puppeteer、Playwright，或使用Bridge Mode控制桌面Chrome。

○Android：通过ADB + @midscene/android控制真机/模拟器。

○iOS：通过WebDriverAgent (WDA) + @midscene/ios控制真机/模拟器（macOS必备）。

○PC/桌面：支持macOS、Windows、Linux桌面应用控制。

○Any Interface：提供通用JavaScript SDK，可适配自定义界面。

○统一API设计，跨平台体验一致。

2.三大类API（开发者最常用）：

○Interaction API（交互类）：aiAct()（多步智能规划执行）、aiTap()（点击）、aiInput()（输入）、aiHover()（悬停，Web专属）等。

○Data Extraction API（数据提取类）：aiQuery()—— 用自然语言描述返回JSON结构的数据提取。

○Utility API：aiAssert()（断言）、aiLocate()（定位）、aiWaitFor()（等待条件）、aiBoolean()/aiNumber()/aiString()等快捷方法。

3.纯视觉（Pure-Vision）驱动（1.0+版本核心）：

○完全基于截图（Screenshot） + Vision Language Model（VLM）进行元素定位和动作规划。

○不再依赖DOM提取（旧版DOM+标注模式已移除），完美支持Canvas、背景图、跨域iframe、无accessibility的场景。

○优势：稳定性高、token消耗降低约80%、适用范围极广、支持自托管开源模型。

○数据提取/页面理解时仍可选择性包含DOM信息。

4.模型策略与多模型组合：

○支持Qwen3-VL、Doubao Seed（火山引擎）、Gemini-3系列、Zhipu GLM-4.6V、UI-TARS等强视觉 grounding 模型。

○支持Planning Model（任务规划） + Insight Model（数据/断言理解） + 默认定位模型的多模型组合，提升复杂任务成功率。

○推荐通过MIDSCENE_MODEL_FAMILY等环境变量或modelConfig精确指定模型家族。

5.高效调试与可视化：

○自动生成HTML报告（单文件或带外部资源），包含每步截图、AI思考过程、执行日志、token消耗统计。

○内置Playground（Android/iOS有专用CLI playground）。

○Chrome Extension（零代码快速体验，支持Act/Query/Assert/Tap）。

○报告支持single-html（base64嵌入）和html-and-external-assets两种输出格式。

6.Caching机制（生产效率神器）：

○缓存AI规划结果和Web元素定位信息（XPath）。

○支持read-write/read-only/write-only策略，极大降低重复执行的耗时和费用。

○CI环境中提交cache文件即可复用，报告中会显示cache命中提示。

7.MCP（Model Context Protocol）集成：

○将Midscene原子动作（Tap、Scroll、Assert等）暴露为MCP Tools。

○上层Agent（如Claude、Cursor等）可通过自然语言调用Midscene控制设备，实现“Agent调用Agent”。

8.高级扩展能力：

○customActions：开发者自定义动作，扩展Action Space。

○YAML编写流程。

○Bridge Mode（Web桌面浏览器控制）。

○自定义OpenAI Client（支持LangSmith等可观测性）。

○AbortSignal支持、waitAfterAction、screenshotShrinkFactor等细粒度控制。

9.其他实用特性：

○零代码Chrome Extension快速上手。

○详细的Replay Report和Debug日志。

○社区Showcases：GitHub注册、iOS美团点单、Android酒店预订、机械臂+视觉测试等。

二、安装方法

1. 标准npm安装

不同平台安装对应包：

●●●bash
# Web (Puppeteer示例)npm install @midscene/web puppeteer tsx dotenv --save-dev# Androidnpm install @midscene/android dotenv --save-dev# iOS (macOS)npm install @midscene/ios dotenv --save-dev

2. 必须配置模型环境变量（所有平台通用）：

●●●bash
export MIDSCENE_MODEL_BASE_URL="https://你的模型服务/v1"export MIDSCENE_MODEL_API_KEY="sk-xxx"export MIDSCENE_MODEL_NAME="qwen3-vl-plus"   # 或 doubao-seed 等export MIDSCENE_MODEL_FAMILY="qwen3-vl"      # 必须指定家族，影响定位逻辑

三、从源码安装与本地开发

Midscene是Nx + pnpm monorepo结构：

1.Clone仓库：

●●●bash
git clone https://github.com/web-infra-dev/midscene.git   cd midscene

2.环境要求：Node.js 20.9.0+，启用corepack：

●●●bash
corepack enable   pnpm install

3.构建：

●●●bash
pnpm run build          # 全量构建   # 或单独构建某个包   npx nx build @midscene/web

4.开发模式：

●●●bash
pnpm run dev            # 全monorepo watch   # 或进入具体app：cd apps/chrome-extension && pnpm run dev

核心packages结构：

●@midscene/core：Agent、规划、模型调用、设备抽象（最核心）。

●@midscene/web/ web-integration：浏览器集成。

●@midscene/android、@midscene/ios、@midscene/computer：平台特定运行时。

●apps/report、apps/site、apps/chrome-extension：可视化与工具。

四、详细高效使用方法

Web（Puppeteer）示例：

●●●typescript
import'dotenv/config';import puppeteer from'puppeteer';import { PuppeteerAgent } from'@midscene/web/puppeteer';const browser = await puppeteer.launch({ headless: false });const page = await browser.newPage();await page.goto('https://www.ebay.com');const agent = new PuppeteerAgent(page);await agent.aiAct('type "Headphones" in search box, hit Enter');const items = await agent.aiQuery('{itemTitle: string, price: Number}[], find items and prices');await agent.aiAssert('There is a category filter on the left');await browser.close();

Android示例（需ADB设备连接）：

●●●typescript
import { AndroidAgent, AndroidDevice, getConnectedDevices } from'@midscene/android';const devices = awaitgetConnectedDevices();const device = new AndroidDevice(devices[0].udid);const agent = new AndroidAgent(device);await device.connect();await agent.aiAct('open browser and navigate to ebay.com');await agent.aiAct('type "Headphones" in search box, hit Enter');

iOS示例（需WDA运行）类似，使用IOSDevice+ IOSAgent。

通用高级选项：

●cache: { id: 'my-cache' }开启缓存。

●modelConfig对象实现单Agent多模型。

●customActions扩展自定义手势。

零代码体验：安装Chrome Extension（Web Store或GitHub Releases），侧边栏直接输入自然语言操作当前页面。

五、技术原理与架构实现

Midscene的核心架构采用纯视觉路线：

1.Screenshot Capture：根据平台使用不同方式截取当前屏幕（Puppeteer page.screenshot、ADB/scrcpy、WDA MJPEG等）。

2.Vision Language Model调用：

○将截图（可缩放screenshotShrinkFactor降低token）发送给VLM。

○区分Planning（任务分解）、Locate（元素视觉grounding）、Insight（数据/断言理解）三种意图。

○支持多模型组合：默认模型负责定位，专用Planning/Insight模型提升质量。

3.Action Planning & Execution：

○VLM返回结构化动作计划（点击坐标、输入内容、滚动等）。

○平台Driver执行低级操作（Puppeteer click、ADB input tap、WDA tap等）。

4.Caching层：

○以prompt + 上下文为key缓存规划结果。

○Web额外缓存XPath（带文本和DOM结构校验防漂移）。

5.Report系统：每步记录截图、AI原始响应、执行结果，生成可交互HTML报告。

6.MCP Server：将原子Action封装为MCP Tool，供上层LLM Agent调用。

纯视觉更优

●传统DOM+标注易受Canvas、无障碍、样式变化影响。

●纯视觉直接“看”屏幕，更接近人类操作，适用范围更广，token更少。

源代码层面，@midscene/core负责Agent抽象和VLM交互逻辑，各平台包提供具体的Device实现和Action Executor。

Midscene.js真正做到了“让AI替你操作界面”，从测试、爬虫、RPA到Agentic Workflow都有巨大价值。提供了一套完整、稳定、可扩展的#视觉自动化基础设施。