turbo-browser-mcp 把瀏覽器操作合併處理,減少 AI 助理等待與讀取的文字
Show HN: Turbo-Browser-MCP – Batch forms, DOM deltas and submit guards for MCP
AI 助理操作瀏覽器時,常得分好幾次讀取頁面、填表和確認結果,每一回合還要重新帶上先前的對話。
- turbo-browser-mcp 是一款以 Playwright 為基礎的 MCP 伺服器,把多個細碎操作合併成較少的工具呼叫,也能只回報頁面有變動的部分、一次填好表單,並直接從磁碟上傳檔案。
- 作者在本機 Chromium 測試中,10 欄表單從 11 回合降到 1 回合,回傳文字量也明顯減少。
- 送出表單等動作預設會先攔下來,需明確允許才會執行。
AI 伴隨問答
針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:
作者以本機 Chromium 基準比較表單、頁面檢視與檔案上傳流程,呈現批次操作如何減少工具往返與送回模型的文字量。
turbo-browser-mcp 是以 Playwright 為基礎的 Model Context Protocol (MCP) 伺服器,旨在減少瀏覽器自動化中的 LLM token 浪費和多輪延遲。它將 25-33 個細粒度瀏覽器基本操作整合成 10 個批次工具,支援差異 DOM 快照、在單輪中預填 React/Shadow DOM/iframe 表單、直接從磁碟上傳檔案(內容中不含 Base64)、平行分頁工作階段、網路封鎖預設設定,以及預設的人在迴圈中的送出防護機制。
效能與 Token 節省一覽
以下所有資料皆來自 benchmarks/benchmark.mjs (npm run benchmark),於本機執行無頭 Chromium,並使用精確的 OpenAI o200k_base token 化方式 (tiktoken 0.14.0):
| 功能 | 一般基準 | turbo-browser-mcp |
速度/輪次提升 | Token 節省(o200k_base) |
|---|---|---|---|---|
| 密集 UI 快照(140 個按鈕的 SaaS 主控臺) | 18,654 tok HTML / 3,568 tok 完整 ARIA |
1,135 tok 精簡版(28 ms) |
1 次呼叫 |
比 HTML 少 93.9%(比 ARIA 少 68.2%) |
點選後的差異快照(onlyChanged: true) |
3,582 tok 完整 ARIA 重新掃描 |
56 tok 變更行(18 ms) |
1 次呼叫 |
比 ARIA 少 98.4%(比 HTML 少 99.7%) |
10 欄複雜表單 + 快照(smart_fill_form) |
11 輪(574 ms,12,197 直接/72,614 累計 tok) |
1 輪(82 ms,811 tok) |
快 7x,少 11 -> 1 輪 |
直接節省 93.4%/累計節省 98.9% |
上傳 48 KiB PDF(49,152 位元組) |
44,728 tok 行內 Base64 工具引數 |
85 tok 磁碟路徑(68 ms) |
不需產生 Base64 | 節省 99.8% |
6 步互動式 UI 流程(batch_actions) |
6 輪(411 ms,955 直接/3,162 累計 tok) |
1 輪(357 ms,406 tok) |
快 1.15x,少 6 -> 1 輪 |
直接節省 57.5%/累計節省 87.2% |
同時開啟 6 個分頁(open_many) |
循序執行需 6 輪(998 ms) |
批次執行只需 1 輪(420 ms) |
快 2.38x,少 6x 輪 |
少 5 次提示重播 |
大量媒體載入(preset: "turbo",304 KiB 個資源) |
252 ms 次、9 個媒體請求(304 KiB) |
165 ms 次、0 個媒體請求(0 KiB) |
快 1.53x |
減少 100% 媒體頻寬 |
文章 Markdown 擷取(extract_clean_text) |
3,595 tok 原始 HTML(10,844 個字元) |
156 tok 乾淨 Markdown(641 個字元) |
輸出乾淨易讀 | 節省 95.7% |
診斷問題分流(僅錯誤,page_diagnostics) |
3,460 tok 未篩選(32 次請求/26 則主控臺訊息) |
601 tok 預設錯誤(2 次請求/6 則主控臺訊息) |
無雜訊捲動 | 節省 82.6% |
| 靜態 MCP 工具結構描述(每輪額外負擔) | 3,917 tok Playwright / 6,737 tok DevTools |
3,010 tok 精簡版(3,314 完整版,含註解) |
10 個工具,相較於 25/33 |
相較於 Playwright 少 23.2%/相較於 DevTools 少 55.3% |
延遲與 LLM 推論輪次的說明:在 10 欄表單中消除
10次往返,可同時節省瀏覽器執行時間7x(574 ms -> 82 ms)、10次獨立的 LLM 推論往返(代理程式迴圈中每輪2-5s),以及~71,800個重播的歷史 token。
瀏覽器代理程式為何停滯:工作流程並列比較
標準 MCP 伺服器會讓 LLM 在每次取得快照、填入欄位、選擇 <select>、上傳檔案和驗證時,都多進行一次往返。每一輪都會把不斷增長的對話歷史重新傳給模型。
sequenceDiagram
autonumber
participant Agent as LLM Agent
participant Std as Standard MCP (Playwright / DevTools)
participant Turbo as turbo-browser-mcp
Note over Agent,Std: Standard MCP (12+ LLM turns, full ARIA tree + history replay each step)
Agent->>Std: 1. snapshot() -> full ARIA (~3,568 tok)
loop Repeats 10+ times across fields, selects, checkboxes, upload
Agent->>Std: fill / select_option / click
Std-->>Agent: full ARIA or confirmation re-added to history
end
Agent->>Std: 12. upload inline or click chooser
Note over Agent,Turbo: turbo-browser-mcp (2 LLM turns total, delta & inline snapshot)
Agent->>Turbo: 1. inspect_compact(mode: "forms") -> compact refs (1,135 tok)
Agent->>Turbo: 2. smart_fill_form(fields: [...10 fields + disk PDF...], returnSnapshot: true)
Turbo-->>Agent: Filled 10 fields + guarded before Submit + inline snapshot (811 tok)
載入中
turbo-browser-mcp 支援的功能
1. 連線與工作階段隔離
- 4 connection modes (
--mode auto|cdp|persistent|launch):auto(預設):會先探測--cdp http://127.0.0.1:9222,讓代理程式重用現有的已登入瀏覽器工作階段;若無法使用,則改為啟動 Chromium。cdp:直接連線到正在執行的 Chromium/Chrome/Edge 遠端偵錯連線埠。persistent:啟動時使用可在多次執行間重複使用的--user-data-dir設定檔。launch:啟動乾淨的瀏覽器工作階段(預設為--headless,或--headed)。
- 自動探索瀏覽器執行檔(
src/playwright-loader.mjs):檢查 Windows、macOS 和 Linux 上的playwright-core快取版本、系統安裝的 Google Chrome、Microsoft Edge、Brave 和 Chromium,或使用明確指定的--executable <path>。 - 分頁隔離(
tabs_batch):在具名的isolatedContext沙箱中開啟分頁,各自使用獨立的 Cookie 和儲存空間;批次同時開啟最多 10 個網址(open_many)、啟用、重新載入、前往back/forward、resize視窗大小,並模擬colorScheme、media、reducedMotion、contrast、forcedColors或自訂userAgent。
2. DOM、iframe 與 Shadow DOM 檢視(inspect_compact)
- 快照模式:
interactive、forms、article和all。 - 跨邊界遍歷:扁平化主要框架 DOM、子 iframe(
includeFrames、frameIdx)和開放的 Shadow DOM。注入初始化指令碼,攔截Element.prototype.attachShadow(WeakMap+WeakRef/FinalizationRegistry+window.__tbmGetShadowRoot),讓初始化後建立的封閉式 Shadow root 仍可供檢視並受到保護;遍歷<slot>assignedNodes({ flatten: true }),並支援與表單關聯的自訂元素。 - Token 控制:
onlyChanged: true僅輸出自前一個快照後新增或變更的元素;query依正規表示式或子字串篩選;boxes: true僅在需要時加入[box=x,y,w,h];maxChars限制負載大小;savePath將完整輸出寫入磁碟。
3. 單回合智慧表單引擎(smart_fill_form)
在單次 MCP 呼叫中預先填入整份表單,並在處理各個受控輸入欄位之間清空微任務與巨集任務佇列:
- 標準與框架輸入欄位:文字、電子郵件、密碼、數字、日期、textarea、
<input type="range">、核取方塊、單選按鈕群組(check、not、overwrite)。透過原生屬性設定器和合成事件觸發 React 受控狀態更新。 - 選取欄位與自訂元件:
<select>和<select multiple>(option/values)、ARIA combobox、ARIA 開關、contenteditable豐富文字編輯器,以及 Gmail 撰寫郵件對話方塊(gmail: { to, subject, body })。 - 框架與萬用字元定位:透過
frameIdx指定目標 iframe,或設定all: true,以填入各框架中符合條件的控制項。 - 直接從磁碟上傳:將
file或files路徑直接傳給 PlaywrightsetInputFiles,無須將二進位檔案或 Base64 字串載入 LLM 脈絡。 - 原子化驗證:傳入
returnSnapshot: true,即可在同一個工具回應中檢視更新後的表單狀態。
4. 16 種互動操作與多步驟串接(act_fast、batch_actions)
act_fast操作:click、dblclick、hover、focus、clear、fill、type(slowly、delayMs、submit)、select、check、uncheck、drag、drop(file、files或自訂 MIMEdropData)、press(key+modifiers:Alt、Control、ControlOrMeta、Meta、Shift)、scroll(dx、dy)、wait(ms、state、loadState、text、textGone、url),以及upload。- 定位方式:精簡的
[eN]ref、CSSselector、可見的text、label或視窗(x, y)座標,可搭配button(left、right、middle)和frameIdx。 batch_actions:在單次 MCP 呼叫中依序執行 DOM 操作清單和巢狀smart_fill_form步驟;若受到 Submit 防護機制阻擋,便安全停止,也可選擇在步驟發生錯誤時繼續執行(continueOnError)。
5. 純淨擷取、評估與媒體擷取(extract_clean_text、evaluate_js、capture_page)
extract_clean_text:從主要內容或文章容器及 iframe 中擷取易讀的純文字或精簡 Markdown(format: "text" | "markdown"),並去除指令碼和樣式的雜訊。evaluate_js:在任何框架中執行 JS 運算式或(el, arg)元素函式(frameIdx),回傳 JSON 序列化結果,並可選擇匯出savePath。capture_page:擷取整頁或指定元素的螢幕截圖(png或jpeg,可搭配quality、css或device比例,並可選擇加入returnImage),也可產生 PDF 並儲存至受限的savePath。
6. 網路封鎖、儲存狀態與診斷(network_session、page_diagnostics)
network_session預設設定:turbo、no-images、no-media和clean(解除所有封鎖),並可使用自訂的blockResources和blockUrls模式。- 工作階段與儲存空間管理:讀取/寫入/清除瀏覽器
cookies、localStorage/sessionStorage,並匯出或重新載入完整的 PlaywrightstorageStateJSON 檔案(saveStorageStatePath、loadStorageStatePath)。 page_diagnostics:預設僅顯示錯誤(level: "errors"、statusFilter: "errors"),清楚呈現失敗狀況而不讓上下文被大量訊息淹沒;同時支援all、includeStatic、urlFilter、深入檢視要求/回應(reqId+part)、已完成的下載,以及對話方塊自動處理(dialogPolicy:accept/dismiss)。
可重現的基準測試(npm run benchmark)
安裝 Chromium 和 Playwright 後,執行基準測試套件:
npm run benchmark
環境與方法:透過 playwright-core 使用無頭模式 Chromium,並以 Python tiktoken 精確計算 OpenAI o200k_base token(若無法使用 tiktoken,則改用 approx-bpe)。累計工作流程 token 數以 $N$ 個連續回合中的標準聊天記錄重播方式估算:$\sum_{i=1}^{N} (N - i + 1) \cdot T_i$,另提供一次性基準值,其中第一回合會在執行操作前擷取上下文。
1. 快照與閱讀器擷取(字元數與精確 o200k_base token 數)
| 情境 | 原始 HTML | 完整 Playwright ARIA | turbo-browser-mcp 輸出 |
相較於 ARIA 的節省量 | 相較於 HTML 的節省量 |
|---|---|---|---|---|---|
140 個按鈕的 SaaS 主控臺(inspect_compact) |
61,010 個字元(18,654 個 token) |
12,771 個字元(3,568 個 token) |
3,968 個字元(1,135 個 token) |
68.2% |
93.9% |
點選後差異(onlyChanged: true) |
61,010 個字元(18,654 個 token) |
12,825 個字元(3,582 個 token) |
168 個字元(56 個 token) |
98.4% |
99.7% |
文章 Markdown 擷取(extract_clean_text) |
10,844 個字元(3,595 個 token) |
n/a | 641 個字元(156 個 token) |
n/a | 95.7% |
診斷篩選(32 個要求、26 則主控臺記錄) |
9,651 個字元(3,460 個 token,all) |
n/a | 1,761 個字元(601 個 token,errors) |
n/a | 82.6% |
2. 多回合表單、工作流程、上傳與網路速度
| 情境 | 逐步執行基準 | turbo-browser-mcp |
執行速度提升 | Token 節省量 |
|---|---|---|---|---|
10 欄複雜表單 + 驗證(smart_fill_form) |
11 回合、574 ms、12,197 個直接/72,614 個累計 token |
1 回合、82 ms、811 個 token(filled=10) |
快 7x 倍 |
直接節省 93.4%/累計節省 98.9% |
上傳 48 KiB PDF(透過 file 傳送 49,152 位元組) |
65,679 個字元(44,728 個 token)的 Base64 資料 |
263 個字元(85 個 token)的磁碟路徑(68 ms) |
不需 LLM 進行 Base64 編碼 | 99.8% |
6 步驟 UI 流程(batch_actions) |
6 回合、411 ms、直接節省 955/累計節省 3,162 個 token |
1 回合、357 ms、406 個 token |
快 1.15x 倍 |
直接節省 57.5%/累計節省 87.2% |
開啟 6 個分頁(tabs_batch open_many、60 ms TTFB) |
依序執行 6 回合(998 ms) |
批次執行 1 回合(420 ms) |
快 2.38x 倍(6 -> 1 回合) |
省下 5 回合 |
大量媒體載入(8x32 KiB 張圖片 + 48 KiB 個字型) |
252 ms、9 次媒體請求(304 KiB) |
165 ms、0 次媒體請求(0 KiB) |
快 1.53x 倍 |
省下 100% 次媒體請求 |
3. MCP 工具定義的靜態佔用量
根據磁碟上已安裝的 MCP JSON 結構描述測量(精簡引數結構描述,不含 annotations):
| MCP 伺服器 | 工具數量 | 精簡結構描述字元數 | 精確 o200k_base token 數 |
使用 turbo-browser-mcp 節省的數量 |
|---|---|---|---|---|
turbo-browser-mcp |
10(14,186 個完整/12,796 個精簡) |
12,796 |
3,010(3,314 個含註解的完整版本) |
基準(10 個工具) |
@playwright/mcp |
25 |
18,457 |
3,917 |
少用 23.2% 個靜態 token |
chrome-devtools-mcp |
33 |
30,252 |
6,737 |
少用 55.3% 個靜態 token |
與 @playwright/mcp 和 chrome-devtools-mcp 比較
| 功能 | turbo-browser-mcp |
@playwright/mcp |
chrome-devtools-mcp |
|---|---|---|---|
| 工具介面規模 | 10 個批次工具 | 25 個細分工具 | 33 個細分工具 |
差異快照(onlyChanged) |
內建 | 每次快照都提供完整樹狀結構 | 每次快照都提供完整樹狀結構 |
| 封閉式 Shadow DOM 掛鉤 | 初始化後的 attachShadow 掛鉤 + <slot> 扁平化 |
開放式 Shadow DOM | CDP/標準 DOM 存取 |
| 單次呼叫處理智慧型表單 + 可編輯內容 | 支援(React、Shadow DOM、iframe、Gmail、ranges) | 多回合填寫 + 分開呼叫選取 | 基本 fill_form |
| 磁碟檔案上傳(不使用 Base64) | smart_fill_form 中的原生 file/files 路徑 & act_fast |
專用的 browser_file_upload 回合 |
專用的 upload_file 回合 |
| 預設的人機協作提交防護機制 | 是(allowSubmit=false、表單/iframe/Enter 鉤子) |
否 | 否 |
平行 open_many + isolatedContext |
單次批次呼叫 | 分開依序呼叫分頁 | 分開呼叫頁面 |
單次呼叫即可封鎖 turbo 媒體 |
內建(turbo、no-images、no-media) |
手動 JS / 路由 | 網路模擬 |
| 效能 / Heap 剖析 | 未包含 | 未包含 | 追蹤記錄、Lighthouse、Heap Snapshot |
何時要搭配
turbo-browser-mcp使用 Chrome DevTools MCP:chrome-devtools-mcp提供 Lighthouse 稽核、效能追蹤分析、CSS 計算樣式面板和 V8 Heap Snapshot。turbo-browser-mcp著重於快速執行多步驟 UI 自動化、表單操作和資料擷取,並將 Token 開銷降至最低。
工具功能對照表
| 功能 | turbo-browser-mcp |
@playwright/mcp |
chrome-devtools-mcp |
|---|---|---|---|
| 開啟、列出、切換、調整大小及模擬多個分頁 | tabs_batch |
browser_tabs、browser_navigate、browser_resize、... |
new_page、list_pages、select_page、resize_page、... |
| DOM / 無障礙檢查 | inspect_compact |
browser_snapshot |
take_snapshot |
| 多欄位表單與檔案上傳 | smart_fill_form |
browser_fill_form + browser_select_option + browser_file_upload |
fill_form + upload_file |
| 點選、輸入文字、拖曳、按鍵、捲動、等待 | act_fast |
browser_click、browser_type、browser_drag、... |
click、type_text、drag、press_key、wait_for |
| 多步驟依序執行的巨集 | batch_actions |
browser_run_code_unsafe 或 N 次工具呼叫 |
N 次獨立工具呼叫 |
| 擷取乾淨的文章內容 | extract_clean_text |
browser_evaluate 自訂 JS |
evaluate_script 自訂 JS |
| Frame/元素 JS 評估 | evaluate_js |
browser_evaluate |
evaluate_script |
| 錯誤、網路與主控臺問題排查 | page_diagnostics |
browser_console_messages、browser_network_requests |
list_console_messages、list_network_requests、... |
| 螢幕截圖與 PDF 匯出 | capture_page |
browser_take_screenshot |
take_screenshot |
| 封鎖預設值、Cookie 與儲存空間 | network_session |
browser_evaluate + context 設定 |
透過 evaluate_script / emulate 部分支援 |
安全性:人機協作提交防護機制與路徑限制
- Human-in-the-loop Submit Guard (
allowSubmit=falseby default):smart_fill_form(stopBeforeSubmit: true)、act_fast和batch_actions會檢查符合條件的元素、W3C AccName 標籤(isSafeSubmitter)、HTML 表單中按下 Enter 會觸發的隱式提交、按鍵組合(Shift+Enter、Enter+Shift)、HTMLFormElement.prototype.submit/requestSubmit,以及同源 iframecontentWindow/contentDocument代理。- 類似
Submit、Publish、Send、Post、Apply、Confirm的最終操作或付款觸發行為都會遭到封鎖,除非明確傳入allowSubmit: true或在啟動時啟用--allow-submit。 - 取捨:在初始化指令碼執行前就已開啟的 CDP 分頁中,若存在先前建立的封閉 Shadow root,或遇到嚴格的跨來源沙箱 frame,就會改用 Playwright frame 控制程式碼、座標操作和鍵盤輸入。
- Workspace Path Confinement (
TURBO_BROWSER_SAVE_ROOT):- 檔案輸出(
savePath、saveStorageStatePath)和狀態輸入(loadStorageStatePath)都嚴格限制在目前工作目錄或TURBO_BROWSER_SAVE_ROOT內。 - 在讀取或寫入前,詞法檢查、
lstatSync/readlinkSync符號連結驗證和realpathSync驗證會封鎖..路徑遍歷、UNC 網路路徑、失效的符號連結、迴圈符號連結和 Windows 接合點。
- 檔案輸出(
全部 10 項工具參考
| 工具 | 用途 | 主要引數 |
|---|---|---|
tabs_batch |
依序管理分頁與瀏覽器生命週期 | operations[](list、open、open_many、navigate、activate、resize、emulate、reload、back、forward、close、close_browser)、isolatedContext、concurrency(1-10) |
inspect_compact |
依 Token 數量限制擷取元素/表單/文章快照 | mode(interactive、forms、article、all)、onlyChanged、query、boxes、maxChars、includeFrames、savePath |
smart_fill_form |
批次預填表單、編輯器與磁碟檔案 | fields[](ref、selector、value、option、values、check、not、keys、file、files、frameIdx、all)、gmail、overwrite、stopBeforeSubmit、returnSnapshot |
act_fast |
單一目標頁面操作 | action(16 個操作)、ref/selector/text/label/(x, y)、modifiers、dropData、allowSubmit、returnSnapshot |
batch_actions |
依序執行一連串操作與表單步驟 | steps[]、continueOnError、allowSubmit、returnSnapshot、snapshotMaxChars |
extract_clean_text |
讀取乾淨文字或精簡 Markdown | format(text、markdown)、selector、includeFrames、maxChars、savePath |
evaluate_js |
限定範圍的 JS 運算式或 (el, arg) 呼叫 |
expression、arg、frameIdx、ref/selector/text、savePath |
page_diagnostics |
主控臺、網路、下載專案與對話方塊 | level(errors、all)、statusFilter(errors、all)、includeStatic、urlFilter、reqId、part、dialogPolicy、clear、savePath |
capture_page |
PNG/JPEG 螢幕截圖與 PDF 匯出 | mode(screenshot、pdf)、type、quality、fullPage、scale(css、device)、ref/selector/text、returnImage、savePath |
network_session |
資源封鎖器、Cookie 與儲存空間 | preset(turbo、no-images、no-media、clean)、blockResources、blockUrls、cookieAction、storageAction、loadStorageStatePath、saveStorageStatePath |
JSON 範例,可直接複製貼上
1. 在 1 個回合內填寫包含磁碟 PDF 的 10 欄位表單並檢查結果
{
"name": "smart_fill_form",
"arguments": {
"fields": [
{ "selector": "#full_name", "value": "Alex Nguyen" },
{ "selector": "#email", "value": "alex@example.com" },
{ "selector": "#country", "option": "United States" },
{ "selector": "#skills", "values": ["TypeScript", "Playwright"] },
{ "selector": "#agree_terms", "check": true },
{ "selector": "#resume_pdf", "file": "./assets/resume.pdf" }
],
"stopBeforeSubmit": true,
"returnSnapshot": true
}
}2. 開啟模態視窗後,只讀取有變更的控制項(onlyChanged)
{
"name": "inspect_compact",
"arguments": {
"mode": "interactive",
"onlyChanged": true,
"maxChars": 3000
}
}3. 在隔離的內容環境中同時開啟分頁,並使用 turbo 加快載入速度
{
"name": "tabs_batch",
"arguments": {
"operations": [
{ "action": "open", "url": "https://example.com/app", "isolatedContext": "acct-a" },
{ "action": "open_many", "urls": ["https://example.com/docs", "https://example.com/pricing"], "concurrency": 4 }
]
}
}快速入門
安裝與檢查環境
git clone https://github.com/Tthanh2k6/turbo-browser-mcp.git
cd turbo-browser-mcp
npm install
npm run doctor如果你需要 Playwright 隨附的 Chromium(或系統未安裝 Chrome/Edge/Brave):
npx playwright-core install chromium
MCP 使用者端設定(Claude Code、Cursor、Antigravity、Codex)
使用本機複製版本:
{
"mcpServers": {
"turbo-browser": {
"command": "node",
"args": ["/absolute/path/to/turbo-browser-mcp/src/index.mjs"],
"env": {
"TURBO_BROWSER_SAVE_ROOT": "/absolute/path/to/allowed/workspace"
}
}
}
}使用 npx/二進位檔入口點:
{
"mcpServers": {
"turbo-browser": {
"command": "npx",
"args": ["-y", "turbo-browser-mcp"]
}
}
}CLI 選項與環境變數
| CLI 旗標 | 環境變數 | 預設值 | 說明 |
|---|---|---|---|
--mode <auto|cdp|persistent|launch> |
TURBO_BROWSER_MODE |
auto |
連線策略(先使用 cdp,再於 auto 中啟動) |
--cdp <url> |
TURBO_BROWSER_CDP_URL |
http://127.0.0.1:9222 |
Chrome DevTools Protocol HTTP 端點 |
--user-data-dir <path> |
TURBO_BROWSER_USER_DATA_DIR |
"" |
持續性設定檔目錄路徑 |
--executable <path> |
- | 自動偵測 | 自訂 Chromium、Chrome、Edge 或 Brave 執行檔 |
--timeout <ms> |
TURBO_BROWSER_TIMEOUT_MS |
15000 |
Playwright 動作/導覽的預設逾時時間(毫秒) |
--headless/--headed |
TURBO_BROWSER_HEADLESS |
true(無頭模式) |
以無頭模式或可見的瀏覽器視窗執行("false" 表示有頭模式) |
--allow-submit |
- | false |
停用預設的提交/發布確認防護 |
--doctor |
- | - | 以 JSON 格式列印 Node、Playwright、Chromium 和 CDP 診斷資訊 |
--bridge |
TURBO_BROWSER_BRIDGE_PORT |
9224 |
啟動/驗證 Chrome 144+ DevToolsActivePort 的持續性 CDP Keep-Alive Bridge 常駐程式(核准一次,之後可無限次重新連線,無須看管) |
--launch-chrome |
- | ~/.turbo-browser-mcp/chrome-profile |
使用專用設定檔與 --remote-debugging-port=9222 啟動 Chrome(永遠只需核准 0 次) |
--version/-v |
- | - | 列印伺服器版本(0.4.0) |
--help/-h |
- | - | 列印 CLI 使用方式摘要 |
| - | TURBO_BROWSER_SAVE_ROOT |
process.cwd() |
限制 savePath 和 storageState 檔案存取範圍的根目錄 |
| - | PLAYWRIGHT_CORE_PATH |
自動解析 | playwright-core/index.mjs 的明確路徑 |
無人值守的夜間/離席自動化(消除 Chrome 144+ 核准提示)
在 Chrome 136+/144+ 中,若於預設的 User Data 目錄啟用 chrome://inspect/#remote-debugging,Chrome 會在 DevToolsActivePort 中顯示 WebSocket;每當新的 WebSocket 使用者端連線時,就會出現 「允許遠端偵錯嗎?」 提示。turbo-browser-mcp 提供兩種內建解決方案,讓夜間無人值守的多代理程式執行不會卡在提示上:
- Automatic CDP Keep-Alive Bridge Daemon (
npm run bridge/--bridge, enabled automatically onDevToolsActivePort):- 啟動一個分離的背景多工器(於
http://127.0.0.1:9224上執行src/cdp-bridge.mjs),讓它無限期維持與 Chrome 的單一持續性上游 WebSocket 連線,並攔截Browser.close,避免下游指令碼終止瀏覽器。 - 啟動工作階段時點選一次允許;之後,任意數量的 MCP 伺服器、CLI 指令碼或子代理程式都能整晚連線與中斷連線,且不會再出現任何提示。
- 啟動一個分離的背景多工器(於
- Zero-Prompt Dedicated Profile Launcher (
npm run launch-chrome/--launch-chrome):- 使用
--remote-debugging-port=9222和專用的--user-data-dir(~/.turbo-browser-mcp/chrome-profile)啟動 Chrome;此時 Chrome 會提供標準 HTTP/WS CDP,即使第一次連線也不會出現確認對話方塊。
- 使用
驗證
npm test # 407 passing tests across 86 suites (26 test files under test/*.test.mjs) npm run doctor # Environment check for Node, Playwright, Chromium, and CDP npm run bridge # Start/verify persistent CDP Keep-Alive Bridge daemon npm run benchmark # Local Chromium speed & exact o200k_base token benchmark
已在 GitHub Actions(ubuntu-latest)上使用 Node 20 和 Node 22 自動測試。