Magnitude：让AI「看屏幕」执行浏览器自动化

想象一下，你正在开发一个复杂的 Web 应用，测试用例写了几百个，每次迭代都要手动验证功能——这无疑是一场消耗开发者精力的持久战。而 Magnitude 的出现，像是为这场战斗配备了一支不知疲倦的数字侦察兵。

Magnitude 是 magnitudedev 团队开源的视觉优先（Vision-First）浏览器代理框架，GitHub 斩获 4000+ 星，定位是让 AI 直接「看屏幕」理解页面内容，然后用自然语言指令驱动浏览器完成自动化操作——从网页数据提取、跨应用集成，到端到端（E2E）测试、RPA 流程，均可覆盖。

🧭 背景：为什么需要视觉驱动的浏览器代理？

传统的浏览器自动化工具（如 Selenium、Playwright）依赖 XPath、CSS 选择器定位元素，一旦前端改版选择器失效，整个自动化脚本就会崩溃。这种「脆弱的强耦合」是行业痛点。

Magnitude 的解法是彻底换一种思路：不给 AI 任何 DOM 结构信息，只给它屏幕截图，让多模态大模型像人类一样「看」页面——理解按钮位置、识别输入框、感知卡片布局，然后用自然语言执行动作指令。这样做的最大好处是：前端改版对 AI 来说几乎无感知，只要页面视觉逻辑没变，自动化流程就能继续运行。

两位核心作者 Anders Lie 和 Tom Greenwald 将这一理念产品化，背后有多年的 AI + 测试工程经验支撑，团队还同步开源了配套的 WebVoyager benchmark，Magnitude 在该测试中拿到了 94% 的通过率，处于 SOTA 水平。

图1：Magnitude 在终端运行，AI 代理正在操控浏览器执行自动化任务

🔧 核心能力：导航、交互、提取、验证

Magnitude 围绕四个核心能力构建：

• 🧭 导航（Navigate）：AI 理解任意网页界面，规划下一步操作路径，适用于复杂多页面流程。

• 🖱️ 交互（Interact）：精准执行鼠标点击、拖拽、键盘输入等底层操作，底层基于 Playwright/patchright。

• 🔍 提取（Extract）：基于 Zod Schema 智能从 DOM 中提取结构化数据，支持 AI 推理增强（如从文本推断难度评分）。

• ✅ 验证（Verify）：内置测试运行器，支持视觉断言（Visual Assertion），可直接截图比对或描述期望状态让 AI 判断是否通过。

代码示例

Magnitude 提供两种粒度的操作接口——高层任务指令和底层原子操作：

import { Magnitude } from '@magnitude-dev/test';
const agent = new Magnitude({  provider: 'openai',  model: 'gpt-4o',  apiKey: process.env.OPENAI_API_KEY,});
// 高层任务指令
await agent.act('Create a task', {  data: {    title: 'Use Magnitude',    description: 'Run "npx create-magnitude-app"',  },});
// 从页面提取结构化数据
const tasks = await agent.extract(  'List in-progress tasks',  z.array(z.object({    title: z.string(),    description: z.string(),    difficulty: z.number().describe('Rate difficulty 1-5'),  })));```

## 🏗️ 架构：Monorepo 模块化设计

Magnitude 采用 **Turborepo + Bun** 的 Monorepo 架构，共 5 个核心包：

| 包 | 职责 | 技术栈 |
|---|---|---|
| `magnitude-core` | 核心代理引擎 + CLI 工具 `magnus` | TypeScript，依赖 BAML、Zod、patchright |
| `magnitude-test` | E2E 测试运行器，配套 CLI `magnitude` | TypeScript，esbuild、glob、dotenv |
| `magnitude-mcp` | MCP 服务器，集成 Model Context Protocol | TypeScript，@modelcontextprotocol/sdk |
| `magnitude-extract` | DOM 清理与结构化库 `unstructured-ts` | TypeScript，依赖 cheerio |
| `create-magnitude-app` | 脚手架工具 `npx create-magnitude-app` | TypeScript，tsup 打包 |
![Magnitude 模块架构图](/api/v1/images/markdown/41f91030f6f90b5fe357e7b61040451e.png)

**图2：Magnitude 各模块关系与依赖**

技术亮点：

- **视觉优先多模态理解**：底层依赖 GPT-4o/Claude 等多模态模型，patchright 负责浏览器控制。

- **BAML 领域语言**：使用 BoundaryML 的 BAML 定义 Agent 行为和 Schema，提升了大模型在结构化任务中的准确性。

- **MCP 集成**：支持 Model Context Protocol，可接入 Claude Desktop 等 MCP 客户端生态。

- **CLI + SDK 双入口**：既有 `npx create-magnitude-app` 快速上手，也有完整的 SDK 供深度集成。

## ⚙️ 部署与上手

Magnitude 无 Dockerfile，不支持容器化一键部署，需要在本地 Node.js 环境中运行：

```bash
# 方式1：脚手架（推荐）
npx create-magnitude-app
# 方式2：手动安装
npm install @magnitude-dev/test
# 配置 API key（.env）
echo 'OPENAI_API_KEY=sk-xxx' > .env
# 运行测试
npx magnitude test

硬件需求：无需 GPU，普通开发机即可（4GB RAM + 1GB 磁盘）。

🔒 安全与隐私

Magnitude 作为本地工具运行，所有浏览器操作都在本地执行，数据不离开用户机器。需要注意的是：AI API 调用会发送页面截图到第三方模型服务商（如 OpenAI），在意数据隐私的团队需要确认服务商的使用政策。

🌍 行业意义

Magnitude 代表的「视觉优先浏览器代理」方向，正在成为 AI Agent 在 Web 自动化领域的主流范式。相比传统的 DOM 选择器方案，视觉方案具备更高的鲁棒性——在 WebVoyager benchmark 中 94% 的通过率也验证了这一点。

随着 Claude、GPT-4o 等多模态模型能力持续提升，类似的视觉代理工具链将逐步替代传统 RPA 方案，成为 Web 自动化、E2E 测试、跨平台数据采集的新基座。Magnitude 作为开源先行者，提供了完整的技术参考实现，值得 AI 开发者和 QA 工程师重点关注。