一个基于 Playwright 的 MCP 服务器与 Claude Code Skill 组合方案，让 AI 编码助手能够实时观测浏览器运行时的控制台错误、网络请求和 DOM 状态，闭合代码交付的反馈环路。

Agent Eyes：为 AI 编码智能体赋予浏览器运行时观测能力\n\n现代 AI 编码助手（如 Claude Code、Cursor、Codex CLI）已经能够编写代码、运行测试、交付实现。然而，它们普遍面临一个结构性盲点：代码部署后，智能体无法感知浏览器运行时实际发生了什么。组件通过了单元测试、构建成功，但 useEffect 死循环可能正在刷爆控制台，某个 API 调用返回 500，或者一条 CSS 规则悄悄破坏了布局——智能体对此完全无从知晓。\n\nAgent 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\nbash\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\nbash\nbash packages/vibe-delivery/install.sh --link --project\n\n\n注册 MCP 服务器（编辑 ~/.claude.json）：\n\njson\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 编码助手发展的正确方向——不是让模型变得更复杂，而是让它能够感知和作用于更丰富的环境。

Agent Eyes：为 AI 编码智能体赋予浏览器运行时观测能力\n\n现代 AI 编码助手（如 Claude Code、Cursor、Codex CLI）已经能够编写代码、运行测试、交付实现。然而，它们普遍面临一个结构性盲点：代码部署后，智能体无法感知浏览器运行时实际发生了什么。组件通过了单元测试、构建成功，但 useEffect 死循环可能正在刷爆控制台，某个 API 调用返回 500，或者一条 CSS 规则悄悄破坏了布局——智能体对此完全无从知晓。\n\nAgent 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\n1. 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\n2. 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\nPlaywright 基础\n\nbrowser-eyes-mcp 基于 Playwright 构建，这是一个由 Microsoft 开发的现代浏览器自动化框架。相比传统的 Selenium，Playwright 提供了：\n\n- 更可靠的等待机制（自动等待元素就绪）\n- 跨浏览器支持（Chromium、Firefox、WebKit）\n- 强大的网络拦截和监控能力\n- 原生支持移动端模拟\n\nToken-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\nbash\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\nbash\nbash packages/vibe-delivery/install.sh --link --project\n\n\n注册 MCP 服务器（编辑 ~/.claude.json）：\n\njson\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 编码助手发展的正确方向——不是让模型变得更复杂，而是让它能够感知和作用于更丰富的环境。