使用 Chrome 開發人員工具 CLI 自動執行可重複的瀏覽器工作流程

José Luis Zapata

Matthias Rohmer

代理專用 Chrome 開發人員工具包含指令列介面 (CLI)，可讓您或程式設計代理，以標準殼層指令的形式執行開發人員工具。代理不會透過 MCP 伺服器動態呼叫工具，而是將相同動作寫成殼層指令，並鏈結成指令碼，方便您隨時重新執行。舉例來說，代理可能會生成類似以下的指令碼：

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

MCP 伺服器和 CLI 都會連線至同一個引擎：一個持續執行的背景 Daemon，透過 Chrome 開發人員工具通訊協定 (CDP) 與 Chrome 通訊。差別在於代理如何連上該引擎：

• MCP 伺服器：代理會使用 JSON-RPC 透過標準輸入/輸出連線，並將每個瀏覽器工具視為互動式函式呼叫。
• CLI：代理會直接對同一個背景 Daemon 執行殼層指令。

您可以使用 CLI 執行下列操作：

• 保留工作流程：將代理在探索式偵錯工作階段中採取的動作，轉換為可重複使用的指令碼。
• 重現應用程式狀態：重新執行指令碼，將瀏覽器恢復至已知狀態，再重新偵錯。
• 批次動作：執行一連串導覽、輸入、模擬和檢查指令，每個步驟之間不需進行對話。
• 不使用 AI 代理執行指令碼：從任何可執行殼層指令碼的終端機、子殼層或 CI 容器執行生成的指令碼，不需要有效的 LLM 工作階段或 MCP 用戶端。

選擇 CLI 或 MCP 伺服器

選擇 CLI 或 MCP 伺服器，是考量成本、情境和工作流程的工程決策。

• 脈絡窗口成本：註冊 MCP 伺服器時，每項工具定義和 JSON 結構定義都會插入 LLM 的系統提示，並在每段對話中出現。有了 CLI 技能，代理只會載入精簡的 Markdown 摘要，並在決定讀取完整技能並建構所需指令時，支付權杖費用。如果代理工作階段很長且有多輪對話，成本和延遲時間就會大幅增加。
• 探索與執行：當您或代理尚不清楚需要檢查什麼時，MCP 工具非常適合用於動態、探索式的偵錯。由於代理預先知道所有可用工具，因此更有可能使用這些工具達成目標。如果已知路徑，CLI 可讓您只執行所需步驟。
• 可重複使用：您可以儲存 CLI 指令碼，在技能中重複使用，或在代理迴圈外手動執行。MCP 工具呼叫無法執行這項操作。

使用 CLI 時，請注意下列事項：

• 工具涵蓋範圍：CLI 支援大多數代理專用 Chrome 開發人員工具，可用於殼層自動化。如需完整的指令清單，請參閱 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，將檔案存取權限制在 OS 暫存目錄。
• CI 中的 Lighthouse：您可以從 CLI 執行 lighthouse_audit，但如果只需要 CI 中的 Lighthouse 分數，獨立的 Lighthouse CLI 及其 GitHub Actions 會是更輕量的選擇。
• 比瀏覽器自動化指令碼更簡單的抽象化：與使用 JavaScript 或 TypeScript 編寫完整的 Puppeteer 或 Playwright 指令碼不同，DevTools CLI 提供有限且高度針對性的 API 介面。這種殼層語法更容易閱讀和維護，即使是低階模型，也能輕鬆可靠地生成，不會產生幻覺。

必要條件

使用 CLI 前，請確認您具備下列條件：

• 已安裝代理專用 Chrome 開發人員工具：請按照入門指南操作。代理專屬的外掛程式和擴充功能 (例如 Gemini CLI 擴充功能) 包含代理技能和 MCP 伺服器。
• 殼層中可用的 CLI：安裝是一次性步驟，不屬於一般 Agentic Workflows。請參閱安裝參考資料。
• chrome-devtools-cli 技能 (隨代理專用 Chrome 開發人員工具安裝)：這項技能會教導代理如何編寫殼層指令碼，或使用 CLI 執行殼層指令。

指令結構

指令格式為 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 用戶端。幾乎所有終端機、子殼層、CI 容器和代理程式架構都支援執行標準殼層指令碼和讀取 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 輸出內容，決定結束代碼。

將工作流程封裝為輕量技能

如果某個流程對多個專案或團隊成員都有用，代理可以將指令碼包裝成技能。這就是開發人員工具 CLI 技能：輕量級參考資料，可讓代理執行特定瀏覽器指令，而不必預先支付所有工具的權杖費用。

提示詞範例：

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，並提供名稱、一行說明 (指出技能適用時機)，以及參照指令碼的操作說明。在後續工作階段中，只有在工作符合說明時，代理程式才會讀取完整技能。

後續步驟

• 如需 CLI 指令和旗標的完整清單，請參閱 CLI 技能參考資料。
• 如要設定基礎伺服器 (無頭模式、管道、實驗類別)，請參閱「設定」。