browser-use/browser-harness 開源網頁技能外殼教學:用 Markdown 指令讓代理安全操作複雜網站

browser-use/browser-harness 將特定網站的操作知識封裝為 Markdown 技能與隔離執行外殼,大幅降低網頁代理迷航與權限外洩風險,一篇看懂架構與設定方法。

Share
browser-harness官方 GitHub 專案封面圖:browser-harness 教學
browser-harness官方開源專案視覺圖。 圖片來源:官方原文。

讓 AI 代理幫你操作網頁聽起來很美好,但只要實際跑過幾次就會發現現實非常骨感。代理不是在複雜的下拉選單裡瘋狂點擊迷航,就是每次都要把整個網頁龐大的 DOM 樹與截圖反覆塞進模型上下文,跑一趟任務就燒掉好幾百萬個 Token,速度又慢得令人抓狂。

更讓人擔心的是登入狀態與資安問題。許多內部後台或社群平台都綁定了雙重驗證與個人登入憑證,用傳統無頭瀏覽器開一個乾淨設定檔根本進不去;但若直接把所有控制權交給外部腳本,又怕代理失控亂點刪除按鈕或把密碼傳出去。

開源專案 browser-use/browser-harness 正是為了解決這個痛點而誕生。根據官方最新說明,它目前已正式整併成為知名專案 Browser Use 的底層核心引擎,透過 Chrome DevTools Protocol 直接連線到你本機已經登入的真實瀏覽器,並用一份純文字 Markdown 技能檔案教會代理正確的操作紀律。

這篇 browser-harness 教學會帶你拆解它的自我學習輔助機制、安裝與 Chrome 遠端除錯連線步驟、實測效能數據對比,以及絕對不可輕忽的權限邊界。

為什麼需要網頁技能外殼:從硬寫腳本走向自我演化

傳統網頁自動化工具像是 Playwright 或 Selenium,要求工程師事先把每一個 CSS 選擇器與等待時間寫死。只要目標網站改版一個按鈕名稱,整支腳本就會立刻報錯癱瘓。相反地,早期純靠視覺模型硬闖的網頁代理雖然不怕改版,卻因為缺乏對特定網站的經驗積累,每次開啟同一個網站都要從頭試錯。

browser-harness 採取了一種非常聰明的折衷架構,把整個系統拆成「受保護的核心引擎」、「可複寫的本機工作區」與「Markdown 領域技能書」三個部分:

  • 受保護的核心層:位於 src/browser_harness/ 目錄下的底層連線與基礎操作保持唯讀與穩定,代理執行任務時不會隨意篡改核心驅動程式,確保系統不會因為模型一次寫錯程式而整組崩潰。
  • 動態累積的本機助手:當代理在執行任務過程中,發現某個複雜網站缺少特定的上傳或擷取輔助函式時,它會把新寫好的小工具存進 agent-workspace/agent_helpers.py。下次遇到類似任務就能直接複用,讓外殼隨著使用次數越來越聰明。
  • Markdown 技能規範:透過 SKILL.md 與 install.md 這兩份人類與 AI 都讀得懂的純文字指南,明確規範代理何時該用 curl 直接抓公開資料、何時才該動用瀏覽器、如何重複利用同一個分頁避免開出幾十個視窗,以及怎麼在背景靜默執行而不搶奪使用者的螢幕焦點。

這套設計讓網頁自動化不再是一次性的消耗品,而是一個會把操作經驗沉澱成領域技能的輕量級工作流。

browser-harness官方 GitHub 專案封面圖:browser-harness 教學
browser-harness官方開源專案視覺圖。 圖片來源:官方原文。

安裝步驟與連線真實 Chrome 瀏覽器設定

目前官方建議直接透過整合後的 browser-use 命令列工具來使用這套引擎,原有的 browser-harness 指令也依然保留相容。團隊推薦使用 Python 現代套件管理工具 uv 來進行全域工具安裝,步驟非常簡潔。

# 安裝整合了 browser-harness 引擎的 browser-use 工具
uv tool install browser-use

# 將標準瀏覽器操作技能註冊給本機的編碼代理使用
browser-use skill install

如果你使用的是 Claude Code 或 Codex 等編碼代理,只需要把官方提供的設定提示詞貼給代理,它就會自動協助完成安裝與環境檢查。若遇到任何連線問題,可以直接執行內建的診斷指令:

# 執行系統健康檢查,診斷 Chrome 連線與背景守護進程狀態
browser-use --doctor

初次連線到你本機正在執行的 Chrome 瀏覽器時,基於新版 Chrome 的安全機制,瀏覽器會自動開啟 chrome://inspect/#remote-debugging 設定頁面。你必須手動勾選遠端除錯選項並點擊允許連線,這道手動授權門檻確保了沒有經過你親眼確認的程式無法偷偷接管瀏覽器。

在 macOS 環境下,如果系統跳出遠端除錯權限確認視窗而卡住,官方也提供了一支輔助指令 mac-approve。只要保持原本的瀏覽器指令繼續等待,另外開啟一個終端機執行授權輔助程式,就能順利完成接管,但前提是終端機或編輯器已在系統設定的輔助使用權限清單內獲得授權。

完成連線後,就能直接透過標準輸入傳送 Python 操作腳本給背景守護進程執行,例如開啟分頁並取得頁面資訊:

browser-use <<'PY'
new_tab("https://example.com")
print(page_info())
PY

如果想把這套瀏覽器控制能力當作 MCP 伺服器掛載給 Cursor、Claude Code 或其他相容用戶端使用,官方也內建了標準輸出入模式的啟動參數。只要在專案的 .cursor/mcp.json 或全域設定中加入以下配置即可完成串接:

{
  "mcpServers": {
    "browser-use": {
      "type": "stdio",
      "command": "uvx",
      "args": ["browser-use", "--cli-mcp"]
    }
  }
}

設定完成後,任何支援 MCP 協定的開發助手都能直接呼叫這組瀏覽器控制工具,不需要各自重複實作底層 CDP 通訊協定。

延伸閱讀:Apple 宣布 macOS 27.3 拆分裝置控制與資料存取權限:AI 代理時代的 Mac 資安新防線

用 Markdown 技能規範控制代理行為:看懂 SKILL.md 的設計巧思

許多開發者好奇,一份 Markdown 文件真的能管得住自由奔放的 AI 代理嗎?打開 browser-harness 官方倉庫的 SKILL.md 檔案,就會發現裡面寫滿了極具工程智慧的紀律條款,每一條都是為了解決真實世界的操作災難。

首先是「殺雞不用牛刀」的邊界判斷。技能文件第一段就明確警告代理,如果目標只是一個公開頁面、純文字文件或開放 API,應該直接使用 curl 或一般網路請求工具抓取,完全不需要啟動瀏覽器。只有當任務需要互動點擊、填寫表單、讀取使用者的已登入狀態,或是遇到必須經過 JavaScript 渲染與防爬蟲保護的頁面時,才允許動用瀏覽器引擎。

其次是「單一分頁與背景靜默原則」。技能規範要求代理為每個網站任務只維護一個工作分頁,每次導航前先透過 current_tab() 與 list_tabs() 檢查是否已有開啟的對應分頁,避免代理每跑一步就重開新視窗把電腦記憶體吃光。更重要的是,它嚴格禁止代理隨便呼叫會把瀏覽器拉到螢幕最上層的 activate_tab(),所有操作與截圖都在背景透過 CDP 完成,讓開發者可以繼續寫程式不被打擾。

最後是「領域專屬技能掛載機制」。只要在環境變數中設定 BH_DOMAIN_SKILLS=1,代理在進入特定網站前,就會先去讀取 $BH_AGENT_WORKSPACE/domain-skills/ 對應網站資料夾底下的所有說明文件,直接套用前人整理好的操作訣竅與注意事項,大幅降低重複踩坑的機率。

實測數據與主流瀏覽器工具橫向對比

為了驗證這種輕量化命令列外殼加上技能檔的架構到底省不省錢,Browser Use 團隊在公開的 BU Bench V2.1 基準測試集上抽樣了 100 道題目,在相同的測試模型與雲端瀏覽器環境下,與市面上三大熱門開源瀏覽器控制工具進行了嚴格的對比測試。

工具名稱 平均評分零至一百 完全解題率 單任務中位數輸入 Token 單任務中位數模型成本 單任務中位數耗時
Browser Harness 60.4 11% 2.1M 0.042 美元 9.0 分鐘
Playwright MCP 60.0 11% 4.4M 0.066 美元 8.3 分鐘
Chrome DevTools MCP 61.0 11% 6.7M 0.097 美元 8.7 分鐘
agent-browser 56.3 9% 3.3M 0.056 美元 11.2 分鐘

從這份實測數據可以看出兩個非常關鍵的結論。在任務解題能力與評分上,四款工具其實在伯仲之間,統計誤差範圍內沒有明顯勝負,單任務耗時也都在八到十一分鐘左右。然而在 Token 消耗與金錢成本上,差距卻非常驚人。

Browser Harness 單一任務的中位數輸入 Token 只有 2.1M,明顯低於 Playwright MCP 的 4.4M,更不到 Chrome DevTools MCP 6.7M 的三分之一,直接把模型成本壓低到每次 0.042 美元。原因就在於它不依賴冗長的 MCP 工具描述與龐大的結構化樹狀回傳,而是讓代理直接寫簡潔的 Python 指令只印出真正需要的頁面資訊。

當然,這項工具也不是所有情境的最佳解。以下整理不同開發場景下的替代選型建議:

  • 可重複的產品端對端自動化測試:如果你要為自家網站撰寫穩定、不依賴個人登入憑證的持續整合測試,傳統的 Playwright 依然是唯一首選。
  • 效能分析與前端除錯:需要錄製效能追蹤、檢查網路封包或對照原始碼堆疊除錯時,應該選用專業的 Chrome DevTools MCP。
  • 純本地隔離且無登入需求:如果你的代理只需要在獨立乾淨的工作區環境中瀏覽公開網頁,使用編輯器內建的隔離瀏覽器會更安全。

延伸閱讀:Code Mode 是什麼?Claude Code 實驗功能的啟用步驟與限制

安全邊界:接管真實登入瀏覽器的潛在風險

雖然讓代理直接操作你已經登入的 Chrome 非常方便,能瞬間省去處理各種複雜登入驗證的麻煩,但這同時也是整套架構中風險最高的安全邊界。

根據官方對比表說明,透過遠端除錯協定連線並點擊允許後,代理取得的是「整個瀏覽器設定檔」的控制權,而不僅僅是單一分頁。這意味著你同一個瀏覽器視窗裡開著的公司內部後台、網路銀行、電子郵件信箱與雲端控制台,理論上都暴露在同一個操作通道底下。

萬一代理瀏覽的外部網頁暗藏惡意間接提示詞注入,誘導模型去讀取其他分頁的敏感資料或執行轉帳、刪除等高風險動作,後果將不堪設想。因此實務上強烈建議,千萬不要在存放重要個人隱私或公司最高管理權限的主力 Chrome 設定檔上開啟遠端除錯;最安全的作法是另外建立一個專供 AI 代理使用的 Chrome 設定檔,裡面只登入該任務真正需要的帳號。

另外,當團隊需要同時平行啟動幾十個瀏覽器執行爬蟲或批次作業時,本機單一守護進程會面臨分頁搶佔與狀態競爭的問題,官方建議這類高併發場景應轉往隔離的遠端雲端瀏覽器環境執行,避免本機操作互相干擾。

常見問題

browser-harness 跟 browser-use 是兩個不同的專案嗎?

現在已經整併在一起。browser-harness 目前已經成為 browser-use 底層的核心引擎,官方推薦直接安裝並使用 browser-use 指令與 --cli-mcp 參數,同時原有的 browser-harness 指令與這個倉庫裡的 Markdown 領域技能依然保留運作。

為什麼用 browser-harness 比一般 MCP 工具省下這麼多 Token?

因為許多傳統 MCP 工具每次互動都會把完整的頁面元素樹或大量工具定義回傳給語言模型,造成上下文迅速膨脹。browser-harness 讓代理直接傳送簡短的 Python 腳本執行操作並只擷取必要的頁面重點,大幅減少無效文字塞進模型的次數。

代理寫出來的 agent_helpers.py 會破壞原本的程式庫嗎?

不會。框架故意將 src/browser_harness/ 核心程式庫與代理的工作目錄隔離開來,代理根據任務需求動態編寫的輔助函式只會寫入本地的 agent-workspace/agent_helpers.py,確保底層連線與核心指令永遠維持乾淨穩定。

執行任何網頁抓取任務都該用 browser-harness 嗎?

不是。官方在 SKILL.md 中特別規定,只要是一般的公開網頁、文件或開放 API,用 curl 能抓下來的東西就絕對不要啟動瀏覽器,只有遇到需要登入態、點擊表單或動態渲染的複雜網站才需要出動它。

結語

browser-use/browser-harness 示範了一種極為務實的代理設計哲學:與其一直訓練更龐大、更昂貴的通用視覺模型去硬猜網站怎麼點,不如透過清楚的 Markdown 技能規範與可累積的輔助程式庫,讓代理把「操作過一次的經驗」真正留存下來。

  • 適合誰:需要讓本機編碼代理操作已登入網站的進階開發者、追求極致壓低瀏覽器任務 Token 成本的團隊,以及想為特定內部系統沉澱標準化操作技能的工程師。
  • 不適合誰:追求零風險隔離、不願讓 AI 接觸本機任何登入瀏覽器狀態的嚴格資安環境,或是只需要對公開靜態網頁做簡單資料擷取的開發者。
  • 為什麼:因為它的強項在於接管真實登入瀏覽器與透過程式碼外殼省下巨額推論費用,若你的需求不需要登入狀態或極度排斥共用瀏覽器權限,傳統無頭測試框架反而更單純安全。

如果你正在為 AI 代理設計安全可控的工具外殼,想持續追蹤最前線的開源代理架構與資安實測,歡迎免費訂閱 AI 郵報,每週為你送上零廢話的工程實戰筆記。

資料來源