Magnitude 如何通过视觉而非脆弱的选择器实现浏览器自动化

任何使用 Playwright 和 Selenium 编写端到端测试或解析器的人都深知这种痛苦。前端开发者更新了构建，Tailwind 重新生成了类名，布局偏移了十个像素，一半的测试场景就会因为 ElementNotFound 错误而崩溃。即使你在上面叠加一个标准语言模型，它也会很快在现代 SPA 应用的臃肿 DOM 树或完全没有标记节点的画布面前陷入困境。

开源项目 Magnitude 的创建者决定从不同的角度来解决这个问题。他们没有向 LLM 输入兆字节的原始 HTML 或在按钮上绘制带数字的标记，而是围绕直接计算机视觉构建了这个工具。

为什么选择器和叠加标记不再有效

大多数现代浏览器 AI 代理都采用 Set-of-Marks 方法。脚本找到页面上所有可交互元素，在它们周围绘制明亮的彩色框和数字，截取截图，然后让模型选择目标按钮的数字。

在简单的着陆页上，这个技巧很有效。但试着打开一个复杂的管理面板、一个交互式地图，或者像 Figma 这样的编辑器。首先，标记脚本开始卡顿。其次，元素经常相互重叠，数字会爬到文本上，下拉菜单在注入辅助 DOM 的瞬间就会关闭。

Magnitude 使用视觉锚定的 LLM。神经网络像人一样查看干净的页面截图，然后立即输出精确的像素坐标用于点击。这消除了处理页面结构的需求，并在 WebVoyager 基准测试中达到了 94% 的成功率。

代理代码的工作原理

在代码中，Magnitude 看起来像一个标准的异步 TypeScript 库。你可以用自然语言发出顶层命令，也可以显式指定底层操作。

以下是处理看板任务的基本示例：

import { agent } from 'magnitude';
import { z } from 'zod';

// Агент сам найдет нужные поля и заполнит форму
await agent.act('Create a task', {
    data: {
        title: 'Use Magnitude',
        description: 'Run "npx create-magnitude-app" and follow the instructions',
    },
});

// Низкоуровневое действие с пониманием контекста интерфейса
await agent.act('Drag "Use Magnitude" to the top of the in progress column');

单独值得称赞的是数据解析功能。通常你不仅需要点击按钮，还需要从页面中提取结构化信息。Magnitude 包含一个 extract 方法，它接受 Zod 验证模式。

// Извлечение данных прямо по схеме с дополнительным анализом
const tasks = await agent.extract(
    'List in progress tasks',
    z.array(z.object({
        title: z.string(),
        description: z.string(),
        difficulty: z.number().describe('Rate the difficulty between 1-5')
    })),
);

注意 difficulty 字段。代理不只是从标记中提取原始文本，还能使用量表实时评估任务复杂度，如果你通过字段描述请求的话。

内置测试运行器

除了灵活的自动化功能，作者还为 Web 应用程序测试准备了一个现成的运行器。你可以在现有仓库中安装它：

npm i --save-dev magnitude-test
npx magnitude init

该命令会创建一个包含配置和测试示例的 tests/magnitude 文件夹。与标准测试不同，这里的断言基于视觉检查。你用简单的语言编写场景，代理会逐步执行并验证界面是否正确响应。

如果你需要一个全新的自动化项目，可以更快地启动环境：

npx create-magnitude-app

模型要求和隐藏的细微差别

这种方法的主要权衡是计算资源和 API 成本。小的开源模型无法可靠地命中正确的坐标。

开发者建议使用 Claude Sonnet 4，它目前在图像中的空间定向方面比其他任何模型都更好。如果你需要一个用于本地部署或私有环境的开源权重选项，支持 Qwen-2.5VL（720 亿参数）。但要在本地运行这样的模型，需要配备多块高端显卡的强大硬件。

第二件需要记住的事情是速度。每个代理步骤都需要向模型发送截图并等待响应。每个操作需要几秒钟，所以这个工具不适合负载测试。目前，作者正在开发原生操作缓存系统，以便重复场景能够确定性执行，而无需持续向 LLM 发送请求。

项目目前已经适合哪些场景

1. 自动化没有开放 API 的服务。 如果你需要从封闭的银行面板或第三方 CRM 系统导出报告，而这些系统的 API 要么是付费的，要么根本不存在。
2. 复杂 UI 的端到端测试。 当项目有很多拖放操作、嵌套 iframe 或画布组件，而它们的选择器支持会变成噩梦时。
3. 智能数据收集。 解析具有复杂布局、无限滚动和动态内容加载的目录。

Magnitude 的亮点在于它没有试图成为一个通用的"魔法按钮"，而是为开发者提供了清晰的 TypeScript API，包含类型验证和对每个步骤的控制。如果你厌倦了在每次重新设计后修复失败的测试，它绝对值得一试。