# Agent Eyes：为 AI 编码智能体赋予浏览器运行时观测能力 > 一个基于 Playwright 的 MCP 服务器与 Claude Code Skill 组合方案，让 AI 编码助手能够实时观测浏览器运行时的控制台错误、网络请求和 DOM 状态，闭合代码交付的反馈环路。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-05-06T12:15:27.000Z - 最近活动: 2026-05-06T12:23:19.803Z - 热度: 114.9 - 关键词: Claude Code, MCP, 浏览器自动化, AI编码, Playwright, 智能体, Workflow, 软件测试 - 页面链接: https://www.zingnex.cn/forum/thread/agent-eyes-ai - Canonical: https://www.zingnex.cn/forum/thread/agent-eyes-ai - Markdown 来源: ingested_event --- # Agent Eyes：为 AI 编码智能体赋予浏览器运行时观测能力\n\n现代 AI 编码助手（如 Claude Code、Cursor、Codex CLI）已经能够编写代码、运行测试、交付实现。然而，它们普遍面临一个**结构性盲点**：代码部署后，智能体无法感知浏览器运行时实际发生了什么。组件通过了单元测试、构建成功，但 `useEffect` 死循环可能正在刷爆控制台，某个 API 调用返回 500，或者一条 CSS 规则悄悄破坏了布局——智能体对此完全无从知晓。\n\n**Agent Eyes** 项目正是为了闭合这个关键的反馈环路而诞生。它通过 MCP（Model Context Protocol）服务器与 Claude Code Skill 的组合，为 AI 编码智能体赋予了真正的"视觉"能力，使其能够实时观测部署后的浏览器应用状态。\n\n## 问题背景：AI 编码助手的盲区\n\n当前的 AI 编码工作流通常遵循以下模式：\n\n1. 智能体根据需求编写代码\n2. 运行单元测试和构建\n3. 报告任务完成\n\n这个流程的根本缺陷在于，**测试通过不等于功能正常**。在真实浏览器环境中，可能出现的问题包括：\n\n- JavaScript 运行时错误（如未处理的 Promise 拒绝、变量未定义）\n- 网络请求失败（CORS 错误、超时、服务端 500 错误）\n- 性能问题（长任务阻塞主线程、内存泄漏）\n- 视觉回归（CSS 冲突、响应式布局失效）\n\n传统上，这些问题需要开发者手动打开浏览器开发者工具进行排查。Agent Eyes 的目标是让智能体能够自主完成这一诊断过程。\n\n## 解决方案：双组件架构\n\nAgent Eyes 采用 pnpm monorepo 结构，包含两个协同工作的核心组件：\n\n### 1. browser-eyes-mcp（MCP 服务器）\n\n这是一个基于 Playwright 的 MCP 服务器，为任何 AI 智能体提供浏览器运行时观测能力。它实现了以下核心工具：\n\n- **getConsoleErrors**：捕获浏览器控制台的错误和警告信息\n- **getNetworkRequests**：监控所有网络请求及其响应状态\n- **getDOMSnapshot**：获取当前页面的 DOM 结构快照\n- **getPerfMetrics**：收集性能指标（如 LCP、FID、CLS 等 Core Web Vitals）\n\n该服务器采用**令牌感知截断（token-aware truncation）**设计，确保观测结果能够干净地放入智能体的上下文窗口，避免信息过载。\n\n### 2. vibe-delivery（Claude Code Skill）\n\n这是一个 Claude Code Skill，负责编排完整的代码交付流程。它定义了 9 个明确的阶段：\n\n```\n/prd → /prototype → /plan → /test-plan → /setup-test → /gen-test → /implement → /test → /ship\n```\n\n这种设计体现了 **Workflow 与 Agent Loop 的有机结合**：\n\n- **外层 9 阶段是 Workflow**：步骤可预测、有状态、可恢复，适合 PRD 编写、测试计划生成等结构化任务\n- **内层 /implement 和 /test 是 Agent Loop**：迭代次数不可预测，智能体根据环境反馈自主决定下一步动作\n\n## 核心设计理念：何时使用 Workflow，何时使用 Agent\n\nAgent Eyes 的设计深受 Anthropic《Building Effective Agents》研究框架的影响，明确区分了两类执行模式：\n\n### 适合 Workflow 的场景\n\n当任务的步骤序列是**可预测且结构化**时，应该使用 Workflow：\n\n- PRD（产品需求文档）编写：遵循固定模板和检查清单\n- 测试计划生成：基于代码结构生成对应的测试用例\n- 归档和文档整理：标准化的文件组织流程\n\nWorkflow 的优势在于**可预测性**和**可恢复性**——如果某个步骤失败，可以精确定位并从该步骤重试，而不必重新开始整个流程。\n\n### 适合 Agent Loop 的场景\n\n当任务的**迭代次数不可预测**时，应该使用 Agent Loop：\n\n- 编译-修复循环：编译错误可能需要多轮修复才能解决\n- 测试-修复循环：测试失败的原因可能需要智能体自主探索\n- UI 调试：根据运行时观测结果动态调整修复策略\n\nAgent Loop 的优势在于**灵活性**——智能体可以根据实时反馈调整策略，而不是被预定义的步骤束缚。\n\n## 技术实现：浏览器观测能力详解\n\n### Playwright 基础\n\nbrowser-eyes-mcp 基于 Playwright 构建，这是一个由 Microsoft 开发的现代浏览器自动化框架。相比传统的 Selenium，Playwright 提供了：\n\n- 更可靠的等待机制（自动等待元素就绪）\n- 跨浏览器支持（Chromium、Firefox、WebKit）\n- 强大的网络拦截和监控能力\n- 原生支持移动端模拟\n\n### Token-Aware 截断\n\nLLM 的上下文窗口是有限的，而浏览器观测数据（完整的 DOM 结构、网络请求列表、性能指标）可能非常庞大。browser-eyes-mcp 实现了智能截断策略：\n\n- **错误信息优先**：控制台错误总是完整保留，因为这对调试最关键\n- **分层摘要**：DOM 快照提供结构摘要，而非完整的 HTML\n- **请求过滤**：默认只包含失败的网络请求，成功的请求仅提供统计摘要\n- **可配置深度**：用户可以根据需要调整观测的详细程度\n\n### 与 Claude Code 的集成\n\nMCP 协议是 Anthropic 提出的开放标准，用于标准化 AI 模型与外部工具的交互。通过将 browser-eyes-mcp 注册为 Claude Code 的 MCP 服务器，智能体可以在推理过程中自然地调用浏览器观测工具，就像调用其他函数一样。\n\n## 使用场景与工作流程\n\n### 场景一：React 组件调试\n\n假设智能体刚刚实现了一个 React 组件，单元测试全部通过。使用 Agent Eyes 的完整流程如下：\n\n1. **部署应用**：智能体启动本地开发服务器\n2. **DOM 检查**：调用 `getDOMSnapshot` 验证组件是否正确渲染\n3. **控制台监控**：调用 `getConsoleErrors` 检查是否有 React 警告或错误\n4. **网络验证**：调用 `getNetworkRequests` 确认数据获取请求成功\n5. **性能评估**：调用 `getPerfMetrics` 确保组件渲染性能符合预期\n6. **迭代修复**：如果发现问题，智能体自主决定修复策略并重复测试\n\n### 场景二：端到端测试失败诊断\n\n当端到端测试失败时，智能体传统上只能看到测试框架的错误摘要。有了 Agent Eyes：\n\n1. 智能体可以在测试运行时同步观测浏览器状态\n2. 识别是测试代码的问题还是被测应用的问题\n3. 获取详细的错误堆栈和网络失败原因\n4. 基于实际观测结果生成精准的修复方案\n\n## 项目现状与未来规划\n\nAgent Eyes 目前处于活跃开发阶段，首个公开版本发布于 2026 年 5 月。已实现的功能包括：\n\n- ✅ Monorepo 脚手架搭建\n- ✅ vibe-delivery Skill（Workflow + Agent 混合架构）\n- ✅ browser-eyes-mcp：getConsoleErrors（MVP）\n- ✅ browser-eyes-mcp：getNetworkRequests\n- ✅ browser-eyes-mcp：getDOMSnapshot\n- ✅ browser-eyes-mcp：getPerfMetrics\n\n计划中的功能：\n\n- 端到端演示：vibe-delivery + browser-eyes-mcp 构建完整应用\n- 移动端浏览器支持\n- 视觉回归检测（截图对比）\n- 性能瓶颈自动分析\n\n## 快速开始\n\n### 环境要求\n\n- Node.js ≥ 20\n- pnpm ≥ 9\n- Claude Code CLI 已安装\n\n### 安装步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/mohanli-eng/agent-eyes.git\ncd agent-eyes\n\n# 安装依赖\npnpm install\n\n# 安装 Playwright 浏览器\ncd packages/browser-eyes-mcp\npnpm exec playwright install chromium\npnpm build\n```\n\n### 配置 Claude Code\n\n安装 Skill：\n\n```bash\nbash packages/vibe-delivery/install.sh --link --project\n```\n\n注册 MCP 服务器（编辑 `~/.claude.json`）：\n\n```json\n{\n \"mcpServers\": {\n \"browser-eyes\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/agent-eyes/packages/browser-eyes-mcp/dist/index.js\"]\n }\n }\n}\n```\n\n重启 Claude Code 后即可使用。\n\n## 总结与启示\n\nAgent Eyes 项目揭示了一个重要的趋势：**下一代 AI 编码助手不仅需要会写代码，还需要能够验证代码在真实环境中的运行效果**。\n\n这种"观测-推理-修复"的闭环能力，是 AI 从"代码生成器"进化为"可靠软件工程师"的关键一步。通过 MCP 协议标准化工具接口，通过 Workflow 与 Agent Loop 的混合架构平衡效率与灵活性，Agent Eyes 为未来的 AI 编码工具链提供了有价值的参考范式。\n\n正如项目文档所强调的：\n\n> \"智能体的能力来自于工具 + 反馈 + 循环，而不是越来越复杂的提示词。\"\n\n这或许是 AI 编码助手发展的正确方向——不是让模型变得更复杂，而是让它能够感知和作用于更丰富的环境。