browser-agent：5 分钟跑通的自然语言浏览器自动化框架

browser-agent：5 分钟跑通的自然语言浏览器自动化框架

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

browser-agent（Magnitude）是一个开源的视觉优先（vision-first）浏览器自动化框架：它用视觉 AI 理解页面截图，让你用自然语言驱动一个真实浏览器——点按钮、填表单、拖拽、提取结构化数据，甚至直接跑端到端测试。如果你受够了"UI 一改、选择器全崩"的 E2E 测试，或者想给编码代理装上"手和眼睛"去操作 Web 应用，这个框架值得看一眼。

一、它凭什么好用

不靠选择器，靠像素坐标。传统浏览器代理在页面上画带编号的框来定位元素，遇到复杂现代站点就容易失效。browser-agent 让"视觉接地"（能理解图片上精确坐标的多模态模型）直接指定点击的像素位置，交互不依赖 DOM 结构。效果是实打实的：官方在 WebVoyager 基准上拿到 94% 的得分（见 README.md）。

测试写成大白话。测试步骤用act('Log in')这种自然语言描述，断言用check('Dashboard is visible')视觉检查。把一段 Playwright 的 todo 用例迁过来，代码能从十几行压到五六行，对比示例见 docs/testing/building-test-cases.mdx。

一套内核，三种形态。同一个浏览器操作内核同时支撑：自动化 SDK（packages/magnitude-core/）、测试运行器（packages/magnitude-test/）、MCP 服务器（packages/magnitude-mcp/）。写自动化脚本和写测试用例共享同一套心智模型。

抽象层级随意切。agent.act()既能接"创建一个任务"这种高层任务，也能接"把某张卡片拖到第一列顶部"这种低层动作，还能在 agent 级和单个 action 级注入自定义 prompt，方便在生产环境里精确控制行为。

二、从零到跑通

1. 两条命令完成初始化

在已有的 Web 项目里加测试：

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

它会生成tests/magnitude目录，里面有magnitude.config.ts（全局配置）和example.mag.ts（示例用例）。如果你是想从零搭一个自动化项目，而不是接入现有测试，用脚手架：

npx create-magnitude-app

2. 写一个最小用例

import { test } from 'magnitude-test'; test('can add and complete todos', { url: 'https://magnitodo.com' }, async (agent) => { await agent.act('create 3 todos', { data: 'Take out trash, Buy groceries, Ship it' }); await agent.check('should see all 3 todos'); // 视觉断言 await agent.act('mark each todo complete'); await agent.check('says 0 items left'); });

步骤描述像跟同事交代事情：目标说清楚即可，不用细化到"先点哪个输入框"。

3. 跑起来

npx magnitude # 运行所有 *.mag.ts 用例 npx magnitude -w 4 # 4 个 worker 并行跑

有任一用例失败时进程以退出码 1 结束，可以直接挂在 CI/CD 里当门禁。

注意一个前置条件：它需要一个视觉接地的模型，推荐 Claude Sonnet 4（设置ANTHROPIC_API_KEY即可），开源替代是 Qwen 2.5 VL 72B。大多数常见模型（包括部分大厂的通用多模态模型）并不支持精确坐标定位，选错模型是最常见的翻车点，清单见 docs/core-concepts/compatible-llms.mdx。

三、真实场景怎么落地

给自己的 Web 应用做端到端测试。适用：想降低 UI 改版带来的测试维护成本，用例数量在几十到上百这个量级。边界：它是概率性判断，不是确定性断言。如果你的场景要求毫秒级时序控制或"必须逐字符相等"这类严格校验，还是该用 Playwright 的精确断言，把它当补充而非替代。

抓取没有 API 的站点数据。用extract()传一段说明加 zod schema，它把页面内容转成结构化数据返回，详见 docs/core-concepts/data-extraction.mdx。边界：受站点条款约束，别拿它做高频爬取；适合"取一次数据喂给下游流程"这类低频集成。

给编码代理装上浏览器。通过 MCP 接入后，Claude Code、Cursor、Cline 这类代理能在开发过程中实时打开页面、看到截图、动手点页面，边写边验证。适合"改完代码自己看一眼页面"的自测循环，不适合无人值守的大批量操作。

四、进阶玩法与生态集成

接入 MCP 服务器。安装后把下面配置贴进你用的客户端（Claude Code 可一行claude mcp add magnitude -- npx magnitude-mcp）：

{ "mcpServers": { "magnitude": { "command": "npx", "args": ["magnitude-mcp"], "env": { "MAGNITUDE_MCP_PROFILE_DIR": "~/.magnitude/profiles/default", // 持久化 cookie "MAGNITUDE_MCP_STEALTH": "true", // 反检测 "MAGNITUDE_MCP_VIEWPORT_WIDTH": "1024" } } } }

测试运行器可调项。magnitude.config.ts里值得留意的几项：browser.contextOptions可传任意 Playwright 上下文参数（比如recordVideo录下每次运行）；webServer配置本地开发服务器命令，跑测试时自动拉起、结束后自动杀掉；continueAfterFailure: true让失败用例不中断整轮。全部选项见 docs/testing/test-configuration.mdx。

提取器是独立包。packages/magnitude-extract/ 提供页面内容转 Markdown 的结构化抽取能力，可以脱离 agent 单独用。

五、踩坑与排错

另外提醒：测试 URL 的解析顺序是环境变量MAGNITUDE_TEST_URL→ 全局配置 → 用例组 → 单条用例，排查"它到底打开了哪个地址"时按这个顺序查。

收尾

一句话：browser-agent 把"操作浏览器"这件事从写选择器换成了说人话，换来的是 UI 改版不再批量击穿你的测试。想深入，可以直接翻 packages/magnitude-core/examples/ 里的可运行示例和 docs/ 下的完整文档，照着改几个act()调用就是最快的上手方式。

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