web-eval-agent

场景切入：让 AI 替你当 QA 测试员

凌晨两点，你刚写完一个新功能，CI 全部变绿，部署到 staging 准备交给产品验收。产品发来消息：「注册流程卡住了，点提交没反应。」你打开浏览器、手动走了一遍注册流程，发现是个隐藏的 JS 报错——这类"人工回归测试"正在消耗大量开发时间。

web-eval-agent（项目已 Sunset，见文末说明）就是来解决这个问题的：它是一个 MCP Server，连接 AI 编程助手（Cursor、Cline、Windsurf）和真实的浏览器环境，让 AI 自动执行端到端测试、捕获控制台报错和网络请求，最后返回一份结构化的 UX 报告。

背景：MCP 协议与 AI 编程工具的崛起

2024 年底，Anthropic 推出 Model Context Protocol（MCP）开放协议，任何工具都可以通过标准化接口接入 Claude 等 AI 编程助手。Cursor、Cline、Windsurf 等主流 AI IDE 纷纷支持 MCP 扩展生态——这催生了一个新赛道：让专业工具变成 AI 的"手脚"。

Operative（项目开发方）看准了"AI 写完代码后谁来测试"这个痛点，开发了 web-eval-agent：它让 AI 编程助手直接驱动 Playwright 浏览器，执行真实用户操作，检测 UX 问题，而无需人工介入。

⚠️ 重要通知：项目已在 2025 年初宣布 Sunset（停止维护），开发团队正在 withrefresh.com 构建新产品。现有仓库保持开源但不再更新。

核心功能：AI 驱动的自动化 UX 评估

工具一：web_eval_agent（自动评估工具）

这是 MCP Server 的核心工具。开发者只需在 AI 编程助手的聊天框中输入自然语言指令，例如：

Evaluate my app at http://localhost:3000 — run web_eval_agent with the task "Try the full signup flow and report UX issues"

AI 便会启动 Playwright 浏览器，执行以下操作：

• 自动导航：模拟真实用户访问指定 URL（支持 http://localhost:3000 等本地地址）
• 截图捕获：在关键步骤自动截屏，生成操作轨迹图
• 控制台监控：实时捕获 JS 错误、console.log、warnings，识别代码质量问题
• 网络请求分析：记录页面发出的 XHR/Fetch 请求，过滤出错误响应（4xx/5xx）
• 自然语言报告：综合以上数据，AI 生成一份"UX 问题清单"和改善建议

关键参数：

参数	说明
url	被测应用地址（必填，支持本地 localhost）
task	自然语言测试任务描述（必填，越详细越好）
headless_browser	是否隐藏浏览器窗口（默认 false，显示浏览器）

工具二：setup_browser_state（认证状态复用）

这是项目的一个巧妙设计。web 应用的很多功能需要登录才能测试。传统自动化测试需要每次在代码里塞入 Cookie 或 token，维护成本高。setup_browser_state 允许开发者先手动在浏览器中完成一次登录（可视化的非 headless 模式），系统自动将登录状态（Cookie、LocalStorage）保存到本地文件。随后 web_eval_agent 执行测试时自动加载该状态，无需任何凭证配置。

日志仪表盘：Operative Control Center

项目内置了一个 Flask + WebSocket 的实时日志服务器（端口 5009）。工具执行期间会自动打开一个浏览器标签页，展示：

• 实时控制台输出和错误日志
• 网络请求瀑布流
• 当前测试 URL 和任务描述
• 截图缩略图序列

这让开发者在 AI 执行期间就能观察进度，而非等 AI 跑完才看到结果。

技术架构：分层解耦的 MCP Server

项目采用 MCP 协议接入 AI IDE，核心执行层使用 browser-use（一个基于 Playwright 的浏览器自动化库），AI 推理后端支持 Google Gemini 和 Anthropic Claude（通过 Operative 云端服务代理）。代码结构如下：

webEvalAgent/
├── mcp_server.py          # FastMCP 服务入口，定义两个工具
├── src/
│   ├── browser_manager.py  # Playwright 单例管理器（CDP 截图驱动）
│   ├── browser_utils.py    # 核心浏览器任务执行逻辑（最大文件 45KB）
│   ├── tool_handlers.py   # 工具调用处理（截图收集、结果格式化）
│   ├── log_server.py      # Flask + SocketIO 实时日志服务
│   ├── api_utils.py       # Operative 后端 API key 验证
│   ├── env_utils.py       # 环境变量和后端 URL 管理
│   └── prompts.py         # 评估任务 Prompt 模板
└── templates/static/
    └── index.html          # 日志仪表盘前端（34KB）

browser_utils.py（45KB）是整个项目最核心的文件，负责：

• 初始化 Playwright Chromium 实例
• CDP（Chrome DevTools Protocol）截图录屏
• 监听控制台和网络事件
• 调用 browser-use Agent 执行评测任务

log_server.py 实现了实时推送能力：Flask 提供 HTTP 服务，SocketIO 将浏览器事件实时广播到仪表盘页面，实现了 AI 执行过程的可视化。

依赖与技术栈

组件	技术选型	说明
MCP 协议	mcp==1.6.0 + FastMCP	标准 MCP Server 实现
浏览器自动化	playwright>=1.41 + browser-use==0.1.40	browser-use 基于 Playwright 封装
AI 推理	google-genai / google-generativeai	Gemini API；Claude 通过 Operative 云端
日志服务	Flask>=3.1 + Flask-SocketIO>=5.5	实时日志推送
依赖管理	uv（astral）	现代 Python 包管理器，安装速度比 pip 快 10-100 倍
代码规范	ruff>=0.11.9	Python Linter/Formatter

上手门槛与部署

安装前置条件

需要同时具备：

• Python 3.11+（项目明确要求 >= 3.11）
• Node.js（用于安装 Playwright Chromium）
• uv：Astral 出品的极速包管理器，curl -LsSf https://astral.sh/uv/install.sh | sh
• Playwright Chromium：npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

安装方式（官方一键脚本）

curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh

脚本会自动安装 uv、Playwright，并向 IDE 的 MCP 配置文件中写入 JSON（需手动在 Cursor/Cline/Windsurf 中重启 MCP）。

配置 IDE

在 AI 编程工具中添加 MCP Server 配置（以 uvx 方式从 GitHub 实时安装）：

{
  "web-eval-agent": {
    "command": "uvx",
    "args": ["--refresh-package", "webEvalAgent", "--from", "git+https://github.com/Operative-Sh/web-eval-agent.git", "webEvalAgent"],
    "env": { "OPERATIVE_API_KEY": "<YOUR_KEY>" }
  }
}

需要到 operative.sh/mcp 注册获取免费 API Key（有一定用量限制，超出需付费订阅）。

局限性：不回避的问题

1. 项目已停止维护 README 明确标注了 "Sunset"，开发团队正在 withrefresh.com 开发新产品。现有代码不再更新，可能存在未修复的 bug 和兼容性问题。

2. 强依赖 Operative 云端服务 API key 验证依赖 operative-backend.onrender.com，当该后端服务不可用时（如免费额度耗尽），工具完全失效，无法绕过。完全离线的私有化部署目前不支持。

3. 浏览器资源消耗大 每次执行都会启动完整的 Chromium 实例（无 Docker 隔离），截图以 base64 编码直接嵌入 MCP 响应，单次任务可能产生数十 MB 的数据量，对网络和内存都有压力。

4. 截图数据体积问题 demo.gif 演示文件本身 32MB，ImageContent 以 base64 传输会进一步膨胀（约 1.37 倍），在 MCP 协议的消息大小限制下，大型 SPA 的多步测试截图可能溢出。

5. 登录态复用方案的局限 setup_browser_state 基于文件存储 Cookie，切换测试环境（staging → production）时需要重新配置，对多环境并行测试不够友好。

行业意义与趋势

web-eval-agent 代表了一个正在快速扩张的细分领域：AI-native Testing。传统测试工具（Selenium、Playwright）需要人类编写测试脚本；browser-use 类框架让 AI 直接驱动浏览器执行自然语言指令，降低了端到端测试的门槛。

从发展趋势来看，下一代工具可能会：

• 完全本地化运行（不依赖云端 API key）
• 集成视觉模型直接分析截图内容，识别样式错位等视觉问题
• 与 CI/CD 流水线深度集成，实现"PR 即测试"的自动化闭环

web-eval-agent 的 Sunset 并不代表方向错了，更可能是因为依赖 Operative 云端服务的模式限制了它的扩展性。新一代工具（如 browser-use 本身的发展）正在向更轻量、更自主的方向演进。

总结：适合谁用？

维度	评估
开发者自助测试	⭐⭐⭐⭐ 适合 AI 编程工具重度用户，在本地快速验证新功能
自动化流水线	⭐⭐ 依赖云端 API key，生产级 CI 风险较高
开源贡献	⭐⭐⭐⭐ 代码清晰，适合学习 MCP + Playwright 集成
生产使用	⚠️ 项目已停止维护，生产环境慎用

提示：如果你对这类工具感兴趣，可以关注 withrefresh.com 的后续产品动态，或直接研究 browser-use 项目的最新进展。