企业官网建设流程全解析

用自然语言控制浏览器：上手开源浏览器智能体 Magnitude 的完整路径

【免费下载链接】browser-agentOpen-source, vision-first browser agent项目地址: https://gitcode.com/gh_mirrors/magnit/browser-agent

如果你写过浏览器端到端测试，多半被 CSS 选择器折磨过：页面一改版，测试就全挂。Magnitude 是一个开源的视觉优先（vision-first）浏览器智能体，你用一句自然语言描述操作，它自己"看懂"页面并完成点击、输入，适合 Web 应用测试、跨应用自动化和数据抓取等场景。

它为什么不用选择器

传统框架靠选择器定位元素，遇到复杂页面（Shadow DOM、动态渲染）就容易失效。Magnitude 的做法不同：视觉模型直接读取页面画面，给出像素级坐标来执行鼠标和键盘操作，不依赖 DOM 结构。

它提供四种基础能力：

• Navigate：识别任意界面并规划操作路径
• Interact：执行精确的点击、拖拽、输入
• Extract：按你给的数据结构提取结构化内容
• Verify：内置测试运行器，支持视觉断言

最短上手路径

先把仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/magnit/browser-agent

接下来按场景二选一。

场景一：新建一个自动化项目

npx create-magnitude-app

这条命令会用模板生成一个新项目，并一步步引导你配置模型。模板里自带一个示例脚本，进入目录后执行npm start就能看到智能体打开浏览器、执行操作的完整过程，用来验证环境是否配置成功。

场景二：给已有 Web 项目加测试

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

执行后会在tests/magnitude/下生成两个文件：magnitude.config.ts（测试配置）和example.mag.ts（示例测试用例）。

配置模型

⚠️ Magnitude 必须搭配有视觉理解能力（visually grounded）的模型，普通文本模型无法工作。最简单的配置方式是设置ANTHROPIC_API_KEY环境变量，默认使用 Sonnet 4；文档中也列出了 Qwen-2.5VL 72B 等兼容模型。模型选错是新手最常见的第一个卡点。

创建第一个测试用例并运行

先看最小配置片段：

import { type MagnitudeConfig } from 'magnitude-test'; export default { url: 'http://localhost:8080' } satisfies MagnitudeConfig;

url指向被测站点，测试时所有用例默认从它出发。

再看最小测试用例：

import { test } from 'magnitude-test'; test('can add todos', { url: 'localhost:8080/todo' }, async (agent) => { await agent.act('create 3 todos', { data: 'Buy milk, Walk the dog, File the report' }); await agent.check('should see all 3 todos'); });

写法就是把你要同事做的事讲清楚：act是执行的操作，check是期望的结果，全部用自然语言。

运行所有测试（匹配*.mag.ts文件）：

npx magnitude

加-w 4可以并行跑 4 个 worker；有测试失败时进程会以退出码 1 结束，可以直接接进 CI 流水线。

如何判断运行成功，以及常见失败原因

成功的表现：浏览器窗口自动打开，智能体按用例逐步操作，终端同步打印每一步的动作和结果，最后给出通过结论。

测试失败的判定和 Playwright 不一样：不是选择器匹配失败就算失败，而是满足以下两种情况之一——某个act步骤无法完成，或某个check断言不成立。

常见卡点排查顺序：

1. 模型没配好：检查ANTHROPIC_API_KEY是否已设置，模型是否具备视觉能力
2. 提示词太模糊：act里说清目标对象和期望状态，例如"把任务 X 拖到 In Progress 列顶部"，而不是"整理一下任务"
3. 站点没启动：本地站点用例需要先起服务，url指向的地址必须可访问

继续学习路径

仓库内可以直接读的材料：

• docs/目录：完整文档，覆盖快速开始、编写测试用例、运行测试、CI 集成等章节
• evals/basic/tests/：仓库自带的示例测试套件，包含滚动、Shadow DOM 等典型交互场景
• packages/magnitude-core/src/：智能体核心源码，想改默认行为或接入自己流程时从这里入手

【免费下载链接】browser-agentOpen-source, vision-first browser agent项目地址: https://gitcode.com/gh_mirrors/magnit/browser-agent