夜雨聆风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都有巨大价值。提供了一套完整、稳定、可扩展的#视觉自动化基础设施。