使用 Chrome 开发者工具 CLI 自动执行可重复的浏览器工作流

José Luis Zapata
Matthias Rohmer

面向智能体的 Chrome 开发者工具包含一个命令行界面 (CLI)，可让您的编码智能体或您自己以标准 shell 命令的形式运行开发者工具。 您的智能体无需通过 MCP 服务器动态调用工具，而是将相同的操作编写为 shell 命令，并将其串联成一个脚本，您可以随时重新运行该脚本。例如，您的智能体可能会生成如下脚本：

chrome-devtools new_page "https://example.com"
chrome-devtools take_snapshot 1
chrome-devtools fill 1 "1_4" "hello"

MCP 服务器和 CLI 都连接到同一个引擎：一个通过 Chrome DevTools Protocol (CDP) 与 Chrome 通信的持久后台守护程序。区别在于智能体如何访问该引擎：

  • MCP 服务器：您的智能体通过标准输入/输出使用 JSON-RPC 进行连接，并将每个浏览器工具视为一个交互式函数调用。
  • CLI：智能体直接针对同一后台守护程序执行 shell 命令。

您可以使用 CLI 执行以下操作：

  • 持久保存工作流：将智能体在探索性调试会话期间执行的操作转换为可重复使用的脚本。
  • 重现应用状态：重新运行脚本，使浏览器恢复到已知状态，然后再进行调试。
  • 批量操作：运行一系列导航、输入、模拟和检查命令，而无需在每个步骤之间进行对话轮次。
  • 在没有 AI 智能体的情况下运行脚本：从任何可以执行 shell 脚本的终端、子 shell 或 CI 容器执行生成的脚本，而无需活跃的 LLM 会话或 MCP 客户端。

在 CLI 和 MCP 服务器之间进行选择

在 CLI 和 MCP 服务器之间进行选择是一项工程决策，涉及成本、上下文和工作流。

  • 上下文窗口成本：注册 MCP 服务器后，每个工具定义和 JSON 架构都会在每次对话中注入到 LLM 的系统提示中。借助 CLI 技能，智能体仅加载精简的 Markdown 摘要，并在决定读取完整技能并构建所需命令时才支付 token 费用。对于长时间、多轮的智能体对话，这种差异会在成本和延迟方面不断累积。
  • 探索与执行：MCP 工具擅长动态、探索性调试，适用于您和智能体都还不确定需要检查什么的情况。由于智能体事先知道所有可用工具，因此更有可能使用这些工具来实现其目标。如果路径已知， CLI 允许您仅运行所需的步骤。
  • 可重用性：您可以保存 CLI 脚本，在技能中重复使用，或在智能体循环之外手动运行。MCP 工具调用无法实现这一点。
在以下情况下使用 MCP 服务器 在以下情况下使用 CLI
您正在调查一个未知问题，需要使用完整的工具箱。 您已经知道这些步骤，并希望可靠地重复这些步骤。
您希望实时、动态地解决问题并深入探究浏览器。 您希望获得高效利用 token 的智能体技能或基于终端的自动化。
您的智能体在支持 MCP 的 IDE 或客户端中运行。 您的环境不支持 MCP 客户端。

使用 CLI 时，请注意以下几点：

  • 工具覆盖范围：CLI 支持大多数面向智能体的 Chrome 开发者工具，可用于基于 shell 的自动化。如需查看命令的完整列表，请参阅 CLI 技能参考文档。
  • 隐式启动：后台服务器会在首次使用时自动启动；您无需在每个命令之前运行 start、status 或 stop。
  • 持久状态：浏览器状态在不同命令之间保持不变，因此，如果您在某个命令中打开了一个页面，只要没有明确关闭，该页面在下一个命令中仍然可用。
  • 页面 ID 和元素 UID：大多数命令都将页面 ID 作为其第一个参数。运行 chrome-devtools list_pages 找到它，然后运行 chrome-devtools take_snapshot 获取要与之交互的元素的 UID。
  • 输出格式：输出默认为类似 Markdown 的纯文本。如果您想在其他脚本或 CI 流水线中使用结果，请传递 --output-format=json。
  • 文件访问权限：默认情况下，CLI 拥有完整的文件系统访问权限，可用于文件保存参数和 upload_file。传递 --allowUnrestrictedPaths=false 以将文件访问权限限制为操作系统临时目录。
  • CI 中的 Lighthouse：您可以从 CLI 运行 lighthouse_audit，但如果您只需要 CI 中的 Lighthouse 得分，则独立的 Lighthouse CLI 及其 GitHub Actions 更轻量。
  • 比浏览器自动化脚本更简单的抽象：与使用 JavaScript 或 TypeScript 编写完整的 Puppeteer 或 Playwright 脚本不同，DevTools CLI 提供了有限且高度针对性的 API 接口。这种 shell 语法更易于人类阅读和维护，即使是低层级模型也能更轻松地可靠生成，而不会出现幻觉。

前提条件

在使用 CLI 之前，请确保您已具备以下条件：

  • 已安装面向智能体的 Chrome 开发者工具：请按照入门指南操作。智能体专用插件和扩展程序（例如 Gemini CLI 扩展程序）包含智能体技能以及 MCP 服务器。
  • Shell 中提供的 CLI：安装是一次性步骤，不属于常规 Agentic Workflows。请参阅安装参考。
  • chrome-devtools-cli 技能（随 Chrome 代理开发者工具一起安装）：此技能可让代理了解如何使用 CLI 编写 shell 脚本或运行 shell 命令。

命令结构

命令遵循 chrome-devtools <tool> [arguments] [flags] 模式。 必需参数是位置参数，可选参数使用标志。对任何命令使用 --help 可查看详细信息。

例如：

chrome-devtools new_page "https://example.com"      # Open a page
chrome-devtools list_pages                          # Find the page ID
chrome-devtools take_snapshot 1                     # Get element UIDs for page 1
chrome-devtools fill 1 "1_4" "hello"                # Fill an input
chrome-devtools click 1 "1_7" --includeSnapshot true
chrome-devtools list_console_messages 1 --types error
chrome-devtools take_screenshot 1 --filePath "result.png"

Chrome 开发者工具 CLI 的应用场景

指示智能体将已确定的步骤捕获为脚本，而不是在每个会话中重新解决相同的浏览器流程。

将调试会话持久保存为可重复使用的脚本

在通过 MCP 进行探索性调试会话后，您通常无法保证同一问题不会再次出现。下次无需再次解释重现步骤，只需让智能体写下它刚刚执行的流程即可。

提示示例：

Please write a chrome-devtools CLI script for this user flow, and save it as test.sh.

智能体执行示例：智能体回顾其在会话期间执行的导航、输入和检查步骤，并将其转换为一系列 chrome-devtools 命令，例如 new_page、take_snapshot、fill、click 和 list_console_messages。它会将脚本保存为 test.sh。下次调试此区域时，您可以让智能体指向该脚本，以再次达到相同的状态，也可以在智能体循环之外运行该脚本，以手动进行调试。

在调查之前重现应用状态

对于智能体来说，每次都通过对话方式重新构建复杂状态（例如多步骤结账或经过滤的信息中心）的成本很高。使用已保存的脚本作为新调查的起点。

提示示例：

Run ./scripts/checkout-flow.sh to get the browser into the payment step, then check why the "Pay now" button stays disabled after I select Google Pay.

智能体执行示例：智能体运行脚本，该脚本会导航到结账页面、填写地址表单并选择配送选项。由于浏览器状态会在命令之间保持不变，因此您的代理随后会在同一页面上使用 take_snapshot 和 evaluate_script 来检查按钮的状态以及附加到付款选择器的事件处理脚本。

跨视口批量进行视觉检查

在多种屏幕尺寸上验证布局更改是一项重复性工作，通常需要手动完成。让您的代理提供一个脚本，该脚本可应用模拟设置并在单次运行中捕获每个设置的证据。

提示示例：

Write a chrome-devtools CLI script that opens http://localhost:3000/pricing, captures a full-page screenshot at 375x667, 768x1024, and 1920x1080, and saves them to ./screenshots with the viewport size in the filename.

智能体执行示例：智能体编写一个循环，为每个视口调用 chrome-devtools emulate 1 --viewport "<size>"，然后调用 chrome-devtools take_screenshot 1 --fullPage true --filePath "./screenshots/pricing-<size>.png"。您可以在每次更改 CSS 后重新运行脚本，而无需打开对话。

对没有 MCP 客户端可用的流程进行冒烟测试

某些环境（例如 CI 容器或锁定的企业设置）不支持 MCP 客户端。几乎每个终端、子 shell、CI 容器和代理框架都支持运行标准 shell 脚本和读取 stdout，这使得 CLI 适合在这些位置进行轻量级检查。

提示示例：

Create a shell script that opens the sign-up page on the staging URL passed as the first argument, submits the form with test data, and exits with a non-zero code if any console errors are logged. Use --output-format=json so the script can parse the result.

代理执行示例：您的代理编写一个使用 new_page、take_snapshot、fill 和 click 的脚本，然后调用 list_console_messages 1 --types error --output-format=json 并解析 JSON 输出以确定退出代码。

将工作流打包为轻量级技能

如果某个流程对多个项目或团队成员都有用，您的智能体可以将脚本封装在 skill 中。这就是 DevTools CLI 技能：一种轻量级参考，可让您的智能体运行特定的浏览器命令，而无需为所有工具支付前期 token 费用。

提示示例：

Turn ./scripts/checkout-flow.sh into a skill named "reproduce-checkout" with a short description of when to use it, so I can invoke it in future sessions.

智能体执行示例：您的智能体会创建一个 SKILL.md，其中包含名称、一行说明（说明该技能的适用场景）以及引用脚本的指令。在后续会话中，只有当任务与 skill 的说明匹配时，智能体才会读取完整的 skill。

后续步骤

  • 如需查看 CLI 命令和标志的完整列表，请参阅 CLI 技能参考文档。
  • 如需配置底层服务器（无头模式、渠道、实验性类别），请参阅配置。