关于 browser-debug-toolkit
browser-debug-toolkit 是面向 Web 开发调试的技能，帮助开发者根据页面问题选择运行时检查工具。它提供场景到工具的决策表，并说明 MCP、浏览器自动化和手动 DevTools 等路径。
主要功能
- 01按问题场景选择调试工具
- 02检查 DOM、样式与布局
- 03检查网络、控制台和交互
- 04比较截图并验证视觉变化
- 05提供 MCP 缺失时的替代路径
适用场景
- 01定位 CSS 优先级或布局异常
- 02检查点击无响应及运行时错误
- 03排查页面加载与网络请求
- 04对比修复前后的页面截图
MCP 相关
指导检查并配置 chrome-devtools-mcp，以便通过 MCP 客户端检查浏览器中的 DOM、CSS、网络和控制台。MCP 不可用时也提供手动 DevTools 等替代方案。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/browser-debug-toolkit确认已加载。
附带文件reference.md
详细介绍
浏览器运行时调试工具包
概述
UI/CSS/DOM 布局问题的根本原因往往只会在运行时显现——例如动态生成的 DOM 结构、CSS 优先级冲突、布局计算异常。静态代码分析（Read/Grep）和基于控制台的调试（console.log）都有一个根本局限：它们无法观察渲染后的 DOM 树、计算后的 CSS 属性或盒模型几何信息。
本技能提供场景到工具的决策表，以及每种工具的使用指南。PDCA 宿主通过 frontmatter dependencies 引用本技能（检测到可通过浏览器复现的场景后，在完成前置检查时调用）。宿主是该依赖关系的 SoT。
前置条件
步骤 1：检查 MCP 是否可用
使用浏览器调试工具前，请检查是否已安装 chrome-devtools-mcp（有时称为 chrome-devtools-connect）：
| 平台 | 检查方法 |
|---|---|
| Claude Code | 运行 claude mcp list，查找 "chrome-devtools" |
| OpenCode | 检查可用工具，或运行 cat ~/.config/opencode/opencode.json |
| Cursor | 设置 → MCP → 查看服务列表 |
步骤 2：如果缺少 MCP — 自适应选择
如果 chrome-devtools-mcp 不可用，请向用户提供三个选项：
选项 A：自动安装（推荐）
AI 直接为检测到的平台运行安装命令：
| 平台 | 安装命令 |
|---|---|
| Claude Code | claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest |
| OpenCode | 将 MCP 配置添加到 ~/.config/opencode/opencode.json |
| Cursor | 使用官方 README中的 "Install in Cursor" 按钮，或手动添加到 MCP 设置 |
安装后，重启 AI 工具以加载 MCP 服务。
选项 B：手动安装
向用户提供准确的命令（与选项 A 相同），供其复制并自行运行。继续操作前等待用户确认。
选项 C：跳过 — 使用手动 DevTools
回退方案：指导用户手动打开浏览器 DevTools（F12）并检查元素。速度比 MCP 慢，但无需进行任何设置。
步骤 3：环境前置条件
- Node.js LTS + npm（chrome-devtools-mcp 所需）
- Chrome 浏览器（稳定版；Google Chrome 或 Chrome for Testing）
步骤 4：验证安装
安装/启用后，验证 MCP 已加载：
| 平台 | 验证方式 |
|---|---|
| Claude Code | claude mcp list 显示 chrome-devtools |
| OpenCode | 配置文件包含 chrome-devtools 条目 |
| Cursor | 设置 → MCP 显示状态为绿色的服务 |
场景 → 工具决策表
| 问题场景 | 默认：ego-browser | 备用：chrome-devtools-mcp | 备用：web-access CDP Proxy | 关键能力 |
|---|---|---|---|---|
| DOM 结构异常（元素缺失或错误） | snapshotText() 无障碍树 + js() 遍历 DOM | Elements 面板 | /eval 读取 DOM | 实时 DOM 树、元素选择、属性检查 |
| CSS 未生效／优先级冲突 | js() 获取 getComputedStyle + 遍历覆盖链 | Elements → Styles | /eval getComputedStyle | 计算样式、覆盖链、盒模型 |
| 布局偏移／盒模型异常 | js() 获取 getBoundingClientRect + 遍历祖先元素 | Computed / Layout 面板 | /eval getBoundingClientRect | 盒模型可视化、flex/grid 辅助线 |
| 交互异常（点击无响应） | click(@N) + js() 检查监听器／状态 + cdp() Console | Console + Event Listeners | 对比 /click 与 /clickAt 的真实手势 | 事件监听器检查、JS 运行时错误 |
| 登录墙／验证码中断调试流程 | handOffTaskSpace → 用户操作 → takeOverTaskSpace（独有） | — | — | 调试过程中原子化地在人类与 AI 之间交接；Agent 与用户共用一个浏览器，不会争夺控制权 |
| 选择器脆弱的 UI（Canvas／虚拟列表／经常换肤的页面） | snapshotText() 的 @N 引用 + 视觉模式（截图 + 坐标） | —（非 macOS：playwright-mcp 无障碍快照） | — | 无障碍树引用可在 CSS／标记频繁变化时保持有效；变更后重新获取快照 |
| 同时需要登录状态和完整 CDP 域（例如登录后查看网络瀑布图） | 在已登录的任务空间中使用 cdp('Network.*') | 连接到现有的已登录 Chrome | /eval 仅可读取；不支持完整域 | 继承登录状态的原始 CDP 透传 |
| 渲染性能（卡顿／帧丢失） | cdp('Performance.*') 原始跟踪记录 | Performance 面板（专用工具，性能分析首选） | — | 火焰图、长任务、渲染统计；搭配 perf-optimize-workflow |
| 视觉回归（样式被覆盖） | 使用 captureScreenshot() 对比前后截图 | — | 使用 /screenshot 对比前后截图 | 截图对比；搭配 visual-qa 技能 |
| 异步加载／网络问题 | cdp('Network.*') + drainEvents() | Network 面板 | — | 请求／响应、瀑布图、状态码 |
| 状态管理异常（React/Vue） | 使用 js() 检查 store／组件状态 | React/Vue DevTools（由用户操作的扩展） | — | 组件树、props/state、时间旅行 |
默认渠道：ego-browser（外部技能，仅限 macOS）——先在运行时检查；它是运行时本地依赖，不会在 frontmatter
dependencies中声明，因此上游工作流（如 solve-workflow）无需依赖任何外部插件。如果 ego-browser 不可用（未安装／非 macOS），或在任务中途失败（报错、无法访问页面、cdp()过于底层而无法满足需求），则按以下链路降级，并告知用户当前使用的渠道——绝不能静默切换。备用列指向chrome-devtools-mcp（MCP 服务，见 Prerequisites）和外部web-access技能的 CDP Proxy（遵循相同的弱引用规则：验证是否可用；若缺失，则中止并提示安装）。ego-browser 对应行在非 macOS 环境下的替代方案：playwright-mcp（MCP，无障碍树快照）→ agent-browser（CLI）。
工具使用指南
chrome-devtools-mcp（MCP 服务）
类型：MCP 服务（Chrome DevTools Protocol）/ 可用性：取决于环境（请参阅先决条件）
适用场景：实时检查页面 DOM、CSS、网络和控制台——AI 可直接操作 DevTools，无需手动切换上下文。
核心功能：DOM 检查（querySelector、计算样式、元素属性）、CSS 调试（匹配规则、覆盖链、盒模型）、控制台（执行 JS、读取输出）、网络（检查请求/响应）、截图（捕获页面或元素）。
使用模式：MCP 可用时，在工作流的分析阶段连接浏览器 → 重现问题并检查运行时状态（DOM 结构、计算样式、控制台、网络）→ 对比预期与实际情况，确定根本原因；在验证阶段，确认修复有效。
注意：如果尚未安装 MCP，请参阅上方的先决条件部分，了解可选的自适应设置方式（自动安装 / 手动安装 / 跳过）。
playwright / webapp-testing（技能）
类型：技能（浏览器自动化）/ 可用性：OpenCode 内置 playwright；用户技能 webapp-testing
适用场景：自动重现交互（点击、输入、导航）、截图对比、端到端验证。
与 chrome-devtools-mcp 的区别：Playwright 专注于自动化操作（由脚本驱动、批量验证）；chrome-devtools-mcp 专注于实时检查（交互式调试、即时反馈）。
visual-qa（技能）
类型：技能（视觉质量保证）/ 可用性：shared/opencode 技能
适用场景：截图对比、设计审查、视觉回归验证。尤其适用于修复前后对比场景。
框架 DevTools（浏览器扩展）
| 框架 | DevTools | 核心功能 |
|---|---|---|
| React | React DevTools | 组件树、props/state、Profiler 时间线 |
| Vue | Vue DevTools | 组件树、Vuex/Pinia 状态、路由 |
| Angular | Angular DevTools | 组件树、变更检测、Signal 依赖关系图 |
框架 DevTools 是 AI 无法直接操作的浏览器扩展。请引导用户自行安装并手动检查。
三个渠道，三种工作方式——根据需求信号选择
根据调试会话需要什么来选择渠道，而不是凭习惯。三者在基本交互（点击／填充／求值／截图）方面有所重叠，但工作方式截然不同：
| 方面 | chrome-devtools-mcp | web-access CDP Proxy | ego-browser（macOS） |
|---|---|---|---|
| 工作方式 | 检查（DevTools 面板：Elements／Network／Performance） | 轻量控制 + 验证（操作页面、捕获状态） | 全面控制 + 原始 CDP + 人机交接 |
| 登录状态 | 默认使用全新会话；可连接到现有 Chrome | 连接到用户的日常浏览器——原生继承登录状态 | 继承用户浏览器的登录状态——原生继承登录状态 |
| 元素定位 | CSS／文本查询 | 通过 /eval 使用 CSS | snapshotText() 无障碍引用（@N）+ CSS + xpath + 坐标 |
| 完整 CDP 域（Network／Performance／Console） | ✅ 通过面板 | ❌（代理子集：求值／点击／滚动／截图） | ✅ 通过 cdp() 原始透传 |
| 调试期间的人机交接 | ❌ | ❌ | ✅ handOffTaskSpace / takeOverTaskSpace |
| 浏览器隔离 | 独立的全新实例 | 与用户共用浏览器（后台标签页，可安全并行） | 隔离的 Task Space——绝不干扰用户的标签页 |
| 脚本编写方式 | MCP 工具（交互式） | curl HTTP API（批处理、并行 Agent） | heredoc JS 批处理（一次完成多个步骤） |
| 平台 | 跨平台（基于 Chrome 的浏览器） | 跨平台 | 仅限 macOS |
默认优先使用 ego-browser。 每次浏览器调试／控制会话都从 ego-browser 渠道开始（先运行时检查可用性）。它是唯一整合了完整交互 + 页面 JS + 原始 CDP + 继承的登录状态 + 隔离的任务空间 + 人机交接的渠道，因此一个渠道就能覆盖整个观察 → 复现 → 验证循环。只有在它不可用（未安装／非 macOS）或无法满足当前需求时才降级：
ego-browser (macOS, default — runtime-checked)
├─ unavailable or failed?
│ ├─ non-macOS → playwright-mcp (MCP, a11y snapshots) → agent-browser (CLI)
│ ├─ need purpose-built panels (perf trace / network waterfall / computed style),
│ │ where raw cdp() is too low-level or fails → chrome-devtools-mcp
│ ├─ need lightweight login-state control or curl-parallel sub-agents → web-access CDP Proxy
│ └─ nothing available → guide user to manual DevTools (F12)
└─ still tell the user which channel you are on (never silently fall back)
有两种特殊情况，即使 ego-browser 可用，备用方案也可能是更好的首选：性能跟踪（chrome-devtools-mcp 专门打造的 Performance 工具优于原始 cdp('Performance.*')）以及无人值守的 CI 回归测试（Playwright / webapp-testing——CI 中不存在用户浏览器）。纯粹的信息检索（搜索／抓取／反爬平台）不属于调试任务——这应由 effective-web-research + web-access 处理，而不是本技能。
有关 web-access curl API 速查表、ego-browser heredoc 示例和各渠道的调试示例，请参阅 reference.md。
工作流集成
PDCA 宿主通过 frontmatter dependencies 引用（缺失时 → 宿主中止）。debug-workflow 等类似工作流技能也会通过环境能力探索发现本技能。hybrid-debug 在混合应用（WebView/WKWebView/Electron + H5）调试中委派本技能提供运行时证据，runtime-evidence-debug 则在常规调试中委派本技能进行 UI/CSS/DOM 埋点：
- 分析阶段：可通过浏览器复现的问题（典型场景为 UI/CSS/DOM）→ 优先使用浏览器工具复现问题并检查运行时状态
- 使用 console.log 调试之前：对于 UI 问题，先用浏览器 DevTools 检查（比 console.log 更高效）；如果仍未解决，再改用日志记录
- 验证阶段：修复后，使用浏览器工具验证修复是否有效（对比修复前后的运行时状态）
渐进式增强：本技能不会取代宿主工作流的核心流程。作为强依赖加载时，宿主的前置条件检查会确保本技能可用；在其他工作流（例如
debug-workflow）中，如果浏览器工具不可用，则原有流程照常执行。
快速参考
Scene detection: Can this problem be reproduced in a browser? (UI/CSS/DOM issues are the typical scenes)
Signal keywords: style, layout, render, display, visibility, position, size, color, animation
→ Yes → Prioritize browser tools to reproduce and inspect (this skill's decision table guides selection)
→ No → Follow original static analysis / console.log debugging process
Tool selection (default + degradation — full table in "Three channels" section):
1. ego-browser (macOS, runtime-checked) — DEFAULT: full interaction / js() / raw cdp() / login state / task space / handoff
2. unavailable or failed → non-macOS: playwright-mcp → agent-browser
3. → purpose-built panels (perf / network / computed style): chrome-devtools-mcp
4. → lightweight login-state control, curl-parallel: web-access CDP Proxy
5. Unattended CI / batch E2E → playwright / webapp-testing (specialist exception)
6. Visual comparison / design review → visual-qa
7. No browser tooling → guide user to manual DevTools
MCP prerequisite check:
→ MCP missing? Present adaptive choice: A=auto-install / B=manual / C=skip
→ See Prerequisites section for platform-specific commands