Midscene.js

基于人工智能与视觉驱动的跨平台UI自动化工具。

📣 Midscene Skills来了！

使用Midscene Skills，结合OpenClaw即可控制任意平台。

展示案例

• Web自动化 - 自动在浏览器中填写GitHub注册表单并完成所有字段验证
• iOS自动化 - 美团咖啡下单
• iOS自动化 - 自动为第一条@midscene_ai推文点赞
• Android自动化 - DCar：小米SU7规格查询
• Android自动化 - 预订圣诞节酒店
• MCP集成 - Midscene MCP UI预发布
• 机械臂+视觉+语音用于车载测试

💡 核心功能

使用自然语言编写自动化脚本

• 描述你的目标和步骤，Midscene将为你规划并操作用户界面。
• 支持通过JavaScript SDK或YAML编写自动化脚本。

适用于Web、移动端及任何界面

• Web自动化：可与Puppeteer、Playwright集成，或使用桥接模式控制桌面浏览器。
• Android自动化：通过JavaScript SDK配合adb控制本地Android设备。
• iOS自动化：通过JavaScript SDK配合WebDriverAgent控制本地iOS设备及模拟器。
• 任意界面自动化：使用JavaScript SDK控制自定义界面。

面向开发者

• 三种API：
  • 交互API：用于与用户界面交互。
  • 数据提取API：从用户界面和DOM中提取数据。
  • 工具API：提供aiAssert()、aiLocate()、aiWaitFor()等实用函数。
• MCP：Midscene提供MCP服务，将原子级的Midscene Agent动作封装为MCP工具，使上层智能体能够以自然语言检查和操作UI。文档
• 高效缓存机制：利用缓存重放脚本，大幅提升执行速度。
• 调试体验：Midscene.js提供可视化回放报告文件、内置游乐场以及Chrome扩展程序，简化调试流程。这些都是开发者真正需要的工具。

👉 无需代码的快速体验

• Chrome扩展：无需编写任何代码，直接通过Chrome扩展开始浏览器内的体验。
• Android游乐场：内置Android游乐场，可直接控制本地Android设备。
• iOS游乐场：内置iOS游乐场，可直接控制本地iOS设备。

✨ 由视觉语言模型驱动

Midscene.js完全采用纯视觉路线进行UI操作：元素定位和交互仅基于截图。它支持诸如Qwen3-VL、Doubao-1.6-vision、gemini-3-pro和UI-TARS等视觉语言模型。在数据提取和页面理解方面，您仍可根据需要选择是否包含DOM。

• UI操作完全基于纯视觉定位；已移除DOM提取模式。
• 可跨Web、移动、桌面甚至<canvas>表面运行。
• 由于操作时不再使用DOM，大幅减少Token消耗，从而降低成本并加快运行速度。
• 在需要进行数据提取和页面理解时，仍可选择包含DOM。
• 提供强大的开源选项，方便自行部署。

更多关于模型策略的信息请参阅。

📄 资源

• 官方网站：https://midscenejs.com
• 文档：https://midscenejs.com
• 示例项目：https://github.com/web-infra-dev/midscene-example
• API参考：https://midscenejs.com/api
• GitHub：https://github.com/web-infra-dev/midscene

🤝 社区

• Discord
• 关注我们在X上
• 飞书交流群

🌟 令人惊叹的 Midscene

扩展 Midscene.js 功能的社区项目：

• midscene-ios - 为 Midscene 提供 iOS 镜像自动化支持
• midscene-pc - 适用于 Windows、macOS 和 Linux 的 PC 操作设备
• midscene-pc-docker - 预装 Midscene-PC 服务器的 Docker 镜像
• Midscene-Python - 用于 Midscene 自动化的 Python SDK
• midscene-java 由 @Master-Frank 开发 - 用于 Midscene 自动化的 Java SDK
• midscene-java 由 @alstafeev 开发 - 用于 Midscene 自动化的 Java SDK

📝 致谢

我们衷心感谢以下项目：

• Rsbuild 和 Rslib，为我们提供了构建工具。
• UI-TARS，开源代理模型 UI-TARS。
• Qwen-VL，开源 VL 模型 Qwen-VL。
• scrcpy 和 yume-chan，使我们能够通过浏览器控制 Android 设备。
• appium-adb，提供 adb 的 JavaScript 桥接。
• appium-webdriveragent，用于通过 JavaScript 操作 XCTest。
• YADB，一款提升文本输入性能的 yadb 工具。
• libnut-core，提供跨平台的原生键盘和鼠标控制。
• Puppeteer，用于浏览器自动化与控制。
• Playwright，用于浏览器自动化、控制及测试。

📖 引用

如果您在研究或项目中使用了 Midscene.js，请引用如下：

@software{Midscene.js,
  author = {Xiao Zhou, Tao Yu, YiBing Lin},
  title = {Midscene.js：您的 Web、Android、iOS 自动化与测试 AI 操作员。},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/web-infra-dev/midscene}
}

✨ 星标历史

📝 许可证

Midscene.js 采用 MIT 许可证。

---

Midscene.js 快速上手指南

Midscene.js 是一个由视觉语言模型（VLM）驱动的 UI 自动化工具。它支持通过自然语言描述来控制 Web、Android、iOS 及任意界面，无需依赖传统的 DOM 定位，仅凭截图即可实现元素识别与交互。

环境准备

系统要求

• 操作系统: Windows, macOS, 或 Linux
• Node.js: 版本 >= 18.0.0
• 包管理器: npm, yarn, 或 pnpm

前置依赖

根据你要自动化的平台，需准备以下环境：

• Web 自动化: 安装 Chrome 浏览器。
• Android 自动化:
  • 安装 Android SDK (包含 adb 工具)。
  • 开启手机的“开发者选项”和"USB 调试”。
  • (可选) 安装 scrcpy 以获得更好的屏幕投射体验。
• iOS 自动化:
  • 安装 Xcode (macOS only)。
  • 配置 WebDriverAgent (WDA)。

模型配置

Midscene 需要调用大模型服务。你可以选择：

• 云端服务: 配置 OpenAI, Azure, 或国内的大模型服务商（如阿里云百炼、火山引擎等）的 API Key。
• 本地部署: 自行部署开源模型（如 Qwen-VL, UI-TARS）。

提示：国内开发者建议在环境变量中配置国内大模型接口以降低延迟。

安装步骤

1. 初始化项目

在终端中创建新项目并安装核心依赖：

mkdir midscene-demo && cd midscene-demo
npm init -y
npm install @midscene/web

2. 配置环境变量

在项目根目录创建 .env 文件，配置你的模型服务凭证。以下以兼容 OpenAI 格式的接口为例（国内用户可替换为相应国内服务商地址）：

# .env
MIDSCENE_MODEL_NAME=Qwen3-VL-Max
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

基本使用

方式一：零代码体验 (Chrome 插件)

如果你只想快速体验而不写代码，推荐直接使用官方 Chrome 扩展程序：

1. 访问 Midscene Chrome Extension 安装插件。
2. 在浏览器中打开任意网页，点击插件图标。
3. 在输入框中输入自然语言指令（例如：“点击登录按钮”或“提取所有商品的价格”），插件将自动执行。

方式二：编写自动化脚本 (JavaScript/TypeScript)

以下是一个控制浏览器自动操作的简单示例。该脚本将打开一个网页，并使用自然语言指令进行搜索。

创建一个 demo.js 文件：

const { launchBrowser, ai, aiQuery } = require('@midscene/web');

(async () => {
  // 1. 启动浏览器
  const browser = await launchBrowser({
    headless: false, // 设置为 true 可在后台运行
  });
  
  // 2. 打开目标页面
  const page = await browser.newPage();
  await page.goto('https://www.bing.com');

  // 3. 使用自然语言进行交互
  // 指令：在搜索框输入 "Midscene JS" 并回车
  await ai(page).action('type "Midscene JS" in the search box and press Enter');

  // 等待结果加载
  await page.waitForTimeout(3000);

  // 4. 提取数据
  // 指令：提取搜索结果中标题和链接
  const data = await aiQuery(page, 'extract the title and link of each search result');
  
  console.log('提取到的数据:', data);

  // 5. 关闭浏览器
  await browser.close();
})();

运行脚本：

node demo.js

关键 API 说明

• ai(page).action(instruction): 执行操作。传入自然语言描述，如 "点击提交按钮"、"滚动到页面底部"。
• aiQuery(page, instruction): 数据提取。传入描述，如 "获取当前页面的所有用户名"，返回结构化 JSON 数据。
• aiAssert(page, instruction): 断言检查。用于测试验证，如 "确认页面上存在欢迎文字"。

进阶：移动端自动化

对于 Android 设备，确保 adb 已连接设备，然后使用类似的 API：

const { connectToDevice, ai } = require('@midscene/web/android');

(async () => {
  const device = await connectToDevice();
  // 对手机屏幕执行操作
  await ai(device).action('Open the settings app');
})();

现在你已经掌握了 Midscene.js 的基础用法，可以开始尝试用自然语言构建复杂的跨平台自动化流程了。