faster-chrome-devtools-skill

更快的 Chrome DevTools：直接使用 CDP

使用随附的 CLI，通过 Chrome DevTools Protocol （CDP）控制 Chrome。它使用 Node.js 内置功能直接连接到 Chrome 的浏览器 WebSocket。 无需 MCP 服务、Puppeteer 安装、Playwright 安装或软件包安装。

node <skill-directory>/scripts/cdp.mjs --help

将 <skill-directory> 替换为包含此 SKILL.md 的目录。 需要 Node.js 22 或更高版本。

连接之前

访问本地 Chrome 会暴露用户打开的标签页和已登录的浏览器状态。 在检查或操作用户的浏览器之前，请先征得用户同意。如果尚未启用远程调试，请让用户前往 chrome://inspect/#remote-debugging 启用。Chrome 也可能显示 Allow debugging 提示。

如需使用不含登录状态的干净会话，请在本地启动单独的匿名 Chrome （参见下文“匿名本地 Chrome”），或连接到远程浏览器， 而不要使用用户的 Chrome。

连接

CLI 按以下顺序尝试连接方式：

1. --ws-endpoint 或 CDP_WS_ENDPOINT
2. --http-endpoint 或 CDP_HTTP_ENDPOINT，通过 /json/version 发现端点
3. macOS、Windows 或 Linux 上的 Chrome DevToolsActivePort 文件
4. http://127.0.0.1:9222/json/version

示例：

# Discover a local Chrome automatically
node <skill-directory>/scripts/cdp.mjs list

# Discover through an HTTP debugging port
node <skill-directory>/scripts/cdp.mjs \
  --http-endpoint http://127.0.0.1:9222 list

# Connect directly to a local or remote browser WebSocket
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint 'wss://browser.example/devtools/browser/...' list

# Authenticated remote endpoint
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint "$CDP_WS_ENDPOINT" \
  --headers '{"Authorization":"Bearer ..."}' list

请优先使用环境变量保存密钥，避免凭据进入 shell 历史记录：

export CDP_WS_ENDPOINT='wss://...'
export CDP_HEADERS='{"Authorization":"Bearer ..."}'
node <skill-directory>/scripts/cdp.mjs list

匿名本地 Chrome

如需使用不含登录状态的干净实例，而非用户的浏览器， 请使用临时配置文件启动单独的 Chrome，并开启远程调试，然后 连接到该端口。必须使用非默认的 --user-data-dir（Chrome 136+ 会拒绝在默认配置文件上启用调试端口），这样也能让此实例 与用户的会话隔离：

nohup "$CHROME" --remote-debugging-port=9333 --user-data-dir="$(mktemp -d)" \
  --no-first-run --no-default-browser-check about:blank >/dev/null 2>&1 &
node <skill-directory>/scripts/cdp.mjs --http-endpoint http://127.0.0.1:9333 list

$CHROME 是 Chrome 或 Chromium 二进制文件，例如 macOS 上的 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome，或 Linux 上的 google-chrome。如果 9333 端口已被占用，请选择一个空闲端口。如果浏览器 在启动命令返回后立即退出，请改为分离启动（在 macOS 上：open -na "Google Chrome" --args --remote-debugging-port=9333 --user-data-dir=<dir> about:blank）。

后台守护进程会在最后一条命令执行后，让一个浏览器连接保持 20 分钟。 这样可避免重复建立连接和反复出现 Chrome 审批提示。完成后请明确停止它：

# Stops the daemon when exactly one is running; no browser discovery is needed
node <skill-directory>/scripts/cdp.mjs stop

# Select one when several endpoints have active daemons
node <skill-directory>/scripts/cdp.mjs stop --id <daemon-id>

# Stop only the daemon created for this endpoint, without reconnecting to it
node <skill-directory>/scripts/cdp.mjs \
  --ws-endpoint 'wss://browser.example/devtools/browser/...' stop

# Deliberately stop every daemon
node <skill-directory>/scripts/cdp.mjs stop --all

如果有多个守护进程处于活动状态，直接执行 stop 会拒绝操作，并显示它们安全的 ID 和 主机。它绝不会打印端点查询字符串或身份验证标头。

标准交互循环

首先列出页面。命令需要使用此输出中的唯一目标 ID 前缀：

node <skill-directory>/scripts/cdp.mjs list
node <skill-directory>/scripts/cdp.mjs snapshot <target>

使用无障碍快照检查页面状态。交互节点包含稳定的后端 DOM 引用，例如 ref=123；请以 ref:123 的形式传入：

node <skill-directory>/scripts/cdp.mjs click <target> ref:123
node <skill-directory>/scripts/cdp.mjs wait-for <target> text 'Sign in' 5000
node <skill-directory>/scripts/cdp.mjs fill <target> ref:456 '[email protected]'
node <skill-directory>/scripts/cdp.mjs press <target> Enter
node <skill-directory>/scripts/cdp.mjs wait-for <target> text 'Welcome' 10000

没有可用的快照引用时，可以使用 CSS 选择器：

node <skill-directory>/scripts/cdp.mjs click <target> 'button[type=submit]'
node <skill-directory>/scripts/cdp.mjs fill <target> 'input[name=email]' '[email protected]'

使用 wait-for 确认每次状态转换；不要添加随意的等待时间。 wait-for 使用 MutationObserver，如果预期文本 或选择器已经存在，就会立即返回。

命令参考

list
open [url]
snapshot <target>
screenshot <target> [file] [--format jpeg|webp|png] [--quality 75] [--full-page]
navigate <target> <url> [timeout-ms]
evaluate <target> <expression>
html <target> [selector]
click <target> <selector|ref:123>
fill <target> <selector|ref:123> <value>
type <target> <text>
press <target> <key>
wait-for <target> <text|selector> <value> [timeout-ms]
live-view <target> [expires-ms]
handoff <target> <instructions> [timeout-ms]
handoff-state <target>
console <target>
failures <target>
raw <target> <CDP.method> [json-params]
stop [--id <daemon-id> | --all]

全局选项必须放在命令之前：

--ws-endpoint <ws://...>
--http-endpoint <http://...>
--headers <json>
--timeout <ms>

当 JavaScript 无法触达元素时，例如位于跨域 iframe 内的输入框，先聚焦该元素，再使用 type。 它使用 CDP 的 Input.insertText，而不是 DOM 求值。

使用 raw 作为任意协议方法的备用入口：

node <skill-directory>/scripts/cdp.mjs raw <target> DOM.getDocument '{}'

截图之前先获取快照

使用 snapshot 了解或操作页面。它速度更快，会生成文本，并提供元素引用。只有在外观很重要时才使用 screenshot，例如需要查看 CSS 渲染、图像、画布、图表或布局。

截图默认使用 JPEG 质量 75，并保存到文件，以避免产生大型内联 base64 载荷。PNG 无损，但通常 大得多。整页图像仍可能占用大量资源，因此只在必要时使用：

# Safe default: viewport JPEG at quality 75
node <skill-directory>/scripts/cdp.mjs screenshot <target> /tmp/page.jpg

# Full page, still compressed
node <skill-directory>/scripts/cdp.mjs screenshot <target> /tmp/page.webp \
  --format webp --quality 75 --full-page

避免使用整页 PNG。它们通常会达到数 MB，如果随后附加，还会占用模型上下文。

导航与等待

默认情况下，所有协议调用的超时时间均为 15 秒。请为导航设置合理的超时时间，而不要让浏览器操作一直挂起：

node <skill-directory>/scripts/cdp.mjs navigate <target> \
  https://example.com 15000

建议的超时限制：

场景	超时时间
本地开发服务	10,000ms
普通网页	15,000ms
资源较重的页面	30,000ms
OAuth 或外部重定向	60,000ms

navigate 会等待 document.readyState === "complete"。动态应用状态可能稍后才会出现，因此导航后请使用 wait-for 或 snapshot。

调试

无需打开 DevTools，即可读取捕获的控制台输出和加载失败的网络请求：

node <skill-directory>/scripts/cdp.mjs console <target>
node <skill-directory>/scripts/cdp.mjs failures <target>

守护进程首次连接到页面后，才会开始捕获消息。如果初始结果为空，请在运行任意页面命令后重现问题。

使用 evaluate 检查应用状态或操作自定义控件：

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  '({url: location.href, state: document.querySelector(".status")?.dataset.state})'

如果 DOM 可能发生变化，请避免在不同命令中使用基于索引的选择器。优先使用快照引用、稳定的 CSS 选择器，或通过一次求值收集所有所需数据。

故障排除

找不到浏览器

在 chrome://inspect/#remote-debugging 启用远程调试；如果 Chrome 提示，请授予访问权限，然后重试一次。如果 Chrome 使用特定调试端口启动，请传入 --http-endpoint http://127.0.0.1:<port>。

不要反复重试相同的连接错误；通常需要用户执行操作或修正端点才能解决。

目标已失效

标签页可能会关闭，或重新加载到新的目标。再次运行 list，并使用当前的唯一前缀。

交互引用无法解析

快照引用属于当前 DOM。发生重大导航或重新渲染后，请重新获取快照。

自定义 UI 忽略填充或点击

尝试使用稳定的 CSS 选择器、evaluate，或先用 click 聚焦，再使用 type。某些 React 控件需要使用原生 setter 以及合成的 input/change 事件；对于普通输入框和文本区域，fill 已会执行这一流程。

远程 Cloudflare Browser Run

同一 CLI 可以直接连接到 Cloudflare Browser Run CDP WebSocket。请传入该服务提供的端点和授权标头。此过程不涉及 MCP 进程。

设置

设置 CLI 读取的两个环境变量，这两个变量由你的账户 ID 和 API 令牌构建，然后运行任意命令：

export CLOUDFLARE_ACCOUNT_ID=<account-id>
export CLOUDFLARE_API_TOKEN=<token>   # needs Browser Rendering: Edit
export CDP_WS_ENDPOINT="wss://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/browser-run/devtools/browser?keep_alive=600000&lab=true"
export CDP_HEADERS="{\"Authorization\":\"Bearer $CLOUDFLARE_API_TOKEN\"}"
node <skill-directory>/scripts/cdp.mjs list

当用户要求使用 Cloudflare Browser Run 时，请使用 Browser Run，不要退回到本地 Chrome。如果未设置 CDP_WS_ENDPOINT 和 CDP_HEADERS， 请检查是否设置了 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN，并据此 生成 CLI 变量。如果这两组变量都不可用，请停止并告知用户：必须先设置这些变量，Browser Run 才能启动。除非用户同意使用该回退方案或明确要求进行本地浏览器自动化，否则不要默认使用本地 Chrome。调试时绝不要打印令牌值。

使用 Browser Run 时，默认保持 lab=true，以选择 Browser Run 的实验性 Chrome beta 池。这样可以使用 beta 浏览器功能，包括 WebMCP。只有在稳定版 Chrome 池比 beta 功能更重要时（例如生产工作负载），才移除 lab=true。

CLI 只使用 CDP_WS_ENDPOINT 和 CDP_HEADERS；CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN 只是用于构建这两个变量的输入。请在每个 shell 会话中导出这些变量，或从本地 .env 加载（无依赖的 CLI 本身不会读取 .env），不要在命令行中传入 --headers，否则令牌会记录在 shell 历史记录和进程参数中。

要创建令牌，请打开 Cloudflare 控制面板，前往 Profile > API Tokens，选择 Create Token；如果提供 Browser Rendering 模板，请选择该模板；或者创建一个自定义令牌，并将 Browser Rendering: Edit 权限限定在该账户范围内。只复制一次密钥。账户 ID 显示在账户首页。

如果 Cloudflare 返回 10000 Authentication error，说明令牌缺失、无效，或没有 Browser Rendering 访问权限。请让用户创建具有 Browser Rendering: Edit 权限的令牌，并设置 CLOUDFLARE_API_TOKEN。绝不要打印令牌值。

人工介入

当自动化遇到 MFA、SSO、CAPTCHA、敏感数据输入、一次性的复杂交互，或需要人工批准的操作时，请使用结构化交接。此功能仅适用于 Browser Run，不适用于本地 Chrome。

首先生成 Live View URL。该 URL 默认 10 分钟后过期，其有效期应至少覆盖计划的交接时长：

node <skill-directory>/scripts/cdp.mjs live-view <target> 600000

将返回的 URL 视为临时浏览器访问凭据。只能分享给人工操作员。请操作员打开该 URL，并在开始交接前确认他们能看到页面。然后运行：

node <skill-directory>/scripts/cdp.mjs handoff <target> \
  'Please complete MFA, then select Done. Select Failed if you cannot continue.' \
  600000

该命令会先订阅 Cloudflare.handoffComplete，再调用 Cloudflare.handoff，随后阻塞等待操作员选择 Done 或 Failed，或者交接超时。超时默认为 10 分钟，且不能超过 Cloudflare 的 30 分钟限制。恢复自动化前，请检查 JSON 结果中的 success 和 reason 字段，然后运行 snapshot 验证新页面状态。不要仅凭页面跳转就认定操作成功。

如果交接可能已经处于活动状态，请在启动另一个交接前进行检查：

node <skill-directory>/scripts/cdp.mjs handoff-state <target>

请提供具体、可执行的说明，明确要做什么，以及何时选择 Done 或 Failed。人工控制不会隐藏 Browser Run 的机器人身份，因此某些网站仍可能阻止该会话。对于没有结构化 Done 或 Failed 控件的手动流程，请分享 live-view，并使用 wait-for 检测预期的页面状态。

WebMCP 和浏览器 beta 功能

Browser Run 实验室会话提供 Chrome beta 功能。启用了 WebMCP 的网站可以通过 document.modelContext 发布结构化工具，这比截图、点击和输入循环更快，也不易出错。

导航到页面后，检查页面是否提供 WebMCP 工具：

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  'document.modelContext?.listTools?.() ?? []'

如果存在相关工具，优先使用它，而不是与 DOM 交互，并以 JSON 格式传递参数：

node <skill-directory>/scripts/cdp.mjs evaluate <target> \
  '(async () => await document.modelContext.executeTool("tool_name", JSON.stringify({})))()'

导航或调用工具后，请重新列出工具，因为可用工具会随页面状态变化。如果不存在相关 WebMCP 工具，则回退到常规 CDP 交互。有些工具在完成敏感操作前会暂停并等待人工确认。

如果需要干净的匿名会话、CI 执行，或与用户的真实浏览器隔离，请优先使用远程浏览器。如果需要用户现有的登录状态，或正在调试用户当前查看的确切标签页，请优先使用本地 Chrome。

对于 Cloudflare Worker 中的单个无状态输出，例如截图、PDF、Markdown 提取、抓取或无障碍树（quickAction("accessibilityTree", ...)），请优先使用 Browser Rendering 绑定的 env.BROWSER.quickAction(...)。它会返回纯粹的角色／名称／状态树，不包含交互引用，因此适用于一次性的“描述此页面结构”调用，而不是点击、填写、等待循环。对于多步导航、页面修改或调试，启动交互式 CDP 会话更合适；此时请改用此技能自带的 snapshot 命令，因为它的无障碍树包含稳定的 ref=123 句柄，可供后续 click／fill 命令使用。

可选的 MCP 兼容性

如果环境已提供 Chrome DevTools MCP 工具，仍可使用这些工具。相同的操作原则也适用：先获取快照，再截图；重复使用标签页；设置导航超时；并等待状态转换。MCP 是一种兼容路径，并非此技能的必需条件。

有关如何使用 MCP 作为 CLI 替代方案的说明，请参阅这篇博客文章：https://github.com/zeke/zeke.sikelianos.com/blob/abb5b6b1d3c1f1a9beeb76d652f8de6dcda92b05/content/browsers-in-the-cloud/index.md