當 AI Agent 學會「邊跑邊修」

2026 年，AI Agent 的瀏覽器操控賽道已經捲成了紅海——Browser Use、Agent-E、WebVoyager 各顯神通。但一個來自 browser-use 團隊的開源專案，用不到 600 行 Python 程式碼殺出重圍：Browser Harness。

截至 2026 年 8 月，這個專案在 GitHub 上已斬獲 17,100+ Star，成為瀏覽器 Agent 領域成長最快的專案之一。它的核心理念只有一句話：把 LLM 直接連到 Chrome 的 CDP 端口，缺什麼函數讓 AI 自己寫。

這不是又一個「封裝 Playwright」的中間層框架。Browser Harness 的設計哲學是極簡主義——沒有選擇器引擎，沒有頁面模型，沒有預定義的工作流程。它只提供一組最小化的 CDP 輔助函數，剩下的交給 LLM 在執行時動態產生。

更驚人的是它的自修復能力：當 Agent 遇到框架沒有覆蓋的操作時，它不會報錯退出，而是自己編寫一個新的 helper 函數，儲存到本機工作區，下次直接複用。框架越用越強，這就是「自修復」的含義。

與 Playwright/Puppeteer 的本質區別

很多人會問：這不就是 Playwright 的 Python 封裝嗎？答案是否定的。

Playwright 和 Puppeteer 是傳統自動化框架。它們的設計目標是「人類編寫腳本控制瀏覽器」，提供了豐富的選擇器引擎（CSS、XPath、text）、頁面模型、等待機制和斷言庫。你需要預先知道要點擊什麼元素、填寫什麼表單、等待什麼條件。

Browser Harness 是 AI 原生框架。它假設控制瀏覽器的不是人類腳本，而是 LLM。因此它： - 不依賴選擇器，而是透過 CDP 直接操作座標和 DOM - 不提供進階等待機制，而是讓 LLM 自己判斷何時頁面就緒 - 不預定義工作流程，而是讓 LLM 根據當前頁面狀態決定下一步 - 不報錯退出，而是讓 LLM 動態產生缺失的輔助函數

這種設計讓 Browser Harness 能夠處理從未見過的網頁結構。傳統自動化腳本遇到新的 DOM 結構就會失敗，但 Browser Harness 的 Agent 會「看懂」頁面，然後編寫新的程式碼來完成任務。

核心架構：592 行程式碼的組織方式

Browser Harness 的程式碼庫極其精簡，核心只有 5 個檔案：

src/browser_harness/
├── __init__.py      # 37 行，套件初始化
├── _ipc.py          # 201 行，Unix Socket/TCP 行程間通訊
├── helpers.py       # 564 行，核心 CDP 輔助函數
├── daemon.py        # 850 行，背景守護行程管理
├── run.py           # 407 行，CLI 入口和 REPL
└── admin.py         # 1191 行，安裝、更新、診斷工具

總計約 3,250 行程式碼（不是 592 行，592 行是早期版本的程式碼量）。但即使擴展到 3,000+ 行，這個程式碼量仍然只有 Playwright 的 1/50。

關鍵模組解析

helpers.py 是整個框架的靈魂。它只提供 20 多個基礎函數：

PYTHON 
# 導航和頁面資訊
goto_url(url)              # 導航到 URL
page_info()                # 取得當前頁面資訊（URL、標題、尺寸、捲動位置）
wait_for_load()            # 等待頁面載入完成

# 元素互動
click_at_xy(x, y)          # 點擊座標
type_text(text)            # 輸入文字
fill_input(selector, text) # 填充表單欄位

# JavaScript 執行
js(expression)             # 執行 JavaScript 並回傳結果

# CDP 原始存取
cdp(method, **params)      # 直接呼叫 Chrome DevTools Protocol

# 截圖和錄製
capture_screenshot(path)   # 截圖
start_recording(name)      # 開始錄製操作
stop_recording()           # 停止錄製

這些函數透過 Unix Socket（或 Windows TCP）與背景 daemon 行程通訊。daemon 維護著與 Chrome CDP 端口的 WebSocket 連線。

daemon.py 負責： - 自動發現執行中的 Chrome 執行個體 - 啟動背景守護行程 - 管理 CDP 連線池 - 處理多分頁切換 - 支援雲端瀏覽器（Browser Use Cloud）

run.py 是 CLI 入口。它啟動一個 REPL（Read-Eval-Print Loop），讓 LLM 可以透過 heredoc 方式執行 Python 程式碼：

BASH 
browser-harness <<'PY'
goto_url("https://example.com")
print(page_info())
PY

這種設計讓 LLM 可以像呼叫函數一樣控制瀏覽器，而不需要理解底層的 CDP 協定細節。

自修復機制：AI 如何動態產生缺失函數

Browser Harness 最核心的創新是自修復（Self-Healing）機制。傳統框架遇到不支援的操作時會拋出例外，而 Browser Harness 讓 LLM 自己寫程式碼解決問題。

工作流程

1. Agent 收到任務：下載 X(Twitter) 上最新的 20 個影片
2. Agent 呼叫 goto_url("https://x.com/profile")
3. Agent 呼叫 page_info() 取得頁面資訊
4. Agent 需要捲動頁面載入更多貼文，但框架沒有 scroll_to_bottom() 函數
5. Agent 自己編寫：
   def scroll_to_bottom(times=10):
       for _ in range(times):
           js("window.scrollTo(0, document.body.scrollHeight)")
           time.sleep(2)
6. 儲存到 agent-workspace/agent_helpers.py
7. 下次任務直接複用

這種機制的關鍵在於 agent_helpers.py 檔案。它位於 Agent 的工作區，不在框架原始碼目錄中。Agent 可以自由修改這個檔案，新增任何需要的輔助函數。

程式碼範例

PYTHON 
# agent-workspace/agent_helpers.py
# Agent 自動產生的輔助函數

def scroll_to_bottom(times=10):
    """捲動到頁面底部，載入更多內容"""
    for _ in range(times):
        js("window.scrollTo(0, document.body.scrollHeight)")
        time.sleep(2)

def extract_video_urls():
    """提取頁面中所有影片連結"""
    return js("""
        Array.from(document.querySelectorAll('video source'))
            .map(el => el.src)
            .filter(src => src)
    """)

def download_file(url, filename):
    """下載檔案到本機"""
    import urllib.request
    urllib.request.urlretrieve(url, filename)

當 Agent 執行任務時，這些自訂函數會被自動載入。框架透過 from agent_helpers import * 將它們注入到 REPL 環境中。

為什麼這很重要

傳統自動化框架的擴展需要： 1. 理解框架的外掛機制 2. 遵循嚴格的 API 規範 3. 發佈到套件管理器 4. 等待使用者安裝

Browser Harness 的自修復機制讓擴展變得即時且個人化： - Agent 根據當前任務需求產生程式碼 - 程式碼儲存在本機，立即可用 - 不需要發佈或安裝 - 每個使用者的 Agent 會根據自己的使用模式進化

這就是「框架越用越強」的含義。你的 Agent 處理過的任務越多，它累積的輔助函數就越豐富，未來處理類似任務的效率就越高。

技術實作細節

Chrome DevTools Protocol (CDP)

Browser Harness 的核心通訊協定是 CDP。CDP 是 Chrome 瀏覽器提供的除錯介面，允許外部程式控制瀏覽器的幾乎所有行為。

PYTHON 
# helpers.py 中的 cdp() 函數
def cdp(method, session_id=None, **params):
    """直接呼叫 CDP 方法"""
    return _send({
        "method": method,
        "params": params,
        "session_id": session_id
    }).get("result", {})

# 使用範例
cdp("Page.navigate", url="https://example.com")
cdp("Input.dispatchMouseEvent", type="mousePressed", x=100, y=200)
cdp("Runtime.evaluate", expression="document.title")

CDP 的優勢在於： - 無需選擇器：直接透過座標點擊，繞過複雜的 CSS/XPath 選擇器 - 跨域支援：CDP 在瀏覽器底層運作，不受同源策略限制 - 完整控制：可以存取網路請求、DOM、JavaScript 執行環境、效能資料等

行程間通訊 (IPC)

Browser Harness 使用 Unix Socket（POSIX）或 TCP（Windows）實作 CLI 與 daemon 之間的通訊。

PYTHON 
# _ipc.py 中的核心邏輯
def connect(name, timeout=1.0):
    """連線到 daemon"""
    if not IS_WINDOWS:
        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        s.connect(str(_sock_path(name)))
        return s, None
    # Windows 使用 TCP
    port, token = _read_port_file(name)
    s = socket.create_connection(("127.0.0.1", port))
    return s, token

def request(c, token, req):
    """發送請求並接收回應"""
    if token:
        req = {**req, "token": token}
    c.sendall((json.dumps(req) + "\n").encode())
    data = b""
    while not data.endswith(b"\n"):
        chunk = c.recv(1 << 16)
        if not chunk:
            break
        data += chunk
    return json.loads(data or b"{}")

這種設計的優勢： - 低延遲：Unix Socket 比 HTTP 快得多 - 安全性：Unix Socket 透過檔案權限控制存取 - 簡潔性：不需要 HTTP 伺服器、路由、序列化等複雜邏輯

自動發現 Chrome 執行個體

daemon.py 會自動掃描系統中執行中的 Chrome 執行個體：

PYTHON 
# daemon.py 中的瀏覽器發現邏輯
_MAC_PROFILES = (
    "Library/Application Support/Google/Chrome",
    "Library/Application Support/Google/Chrome Canary",
    "Library/Application Support/Arc/User Data",
    # ... 更多瀏覽器
)

_LINUX_PROFILES = (
    ".config/google-chrome",
    ".config/chromium",
    ".config/microsoft-edge",
    # ... 更多瀏覽器
)

def supported_browser_running():
    """檢測是否有支援的瀏覽器在執行"""
    return any(browser_running_for_profile(base) for base in PROFILES)

它透過檢查 SingletonLock 檔案和 DevToolsActivePort 檔案來判斷瀏覽器是否在執行，以及是否啟用了遠端除錯。

與其他瀏覽器 Agent 對比

特性 Browser Harness Browser Use Agent-E WebVoyager
程式碼量 3,250 行 15,000+ 行 20,000+ 行 10,000+ 行
設計哲學 極簡主義 功能完整 企業級 研究導向
自修復 ✅ 核心特性 ❌ ❌ ❌
CDP 直接存取 ✅ ✅ ✅ ✅
選擇器引擎 ❌ 座標優先 ✅ ✅ ✅
雲端瀏覽器 ✅ ✅ ❌ ❌
錄製功能 ✅ ✅ ❌ ❌
學習曲線 低 中 高 高

Browser Harness 的核心優勢是極簡 + 自修復。它不試圖提供所有功能，而是讓 LLM 根據需求動態產生程式碼。這種設計讓它能夠處理從未見過的場景，而其他框架需要預先編寫配接器。

實戰案例：自動化完成複雜網頁任務

案例 1：下載 X(Twitter) 影片

PYTHON 
# 任務：下載 X 上最新的 20 個影片

browser-harness <<'PY'
# 1. 導航到 X 個人主頁
goto_url("https://x.com/username/media")
wait_for_load()

# 2. 捲動載入更多貼文
scroll_to_bottom(20)  # Agent 自動產生的函數

# 3. 提取影片 URL
videos = extract_video_urls()  # Agent 自動產生的函數

# 4. 下載影片
for i, url in enumerate(videos[:20]):
    download_file(url, f"video_{i+1}.mp4")
    print(f"Downloaded {i+1}/20")
PY

案例 2：填寫複雜表單

PYTHON 
# 任務：自動填寫註冊表單

browser-harness <<'PY'
goto_url("https://example.com/register")
wait_for_load()

# 取得頁面資訊
info = page_info()
print(f"Page: {info['title']}")

# 使用 Accessibility Tree 找到表單元素
tree = cdp("Accessibility.getFullAXTree")["nodes"]
# 篩選出輸入框
inputs = [n for n in tree if n.get("role") == "textbox"]

# 填寫表單
for input_node in inputs:
    # 取得座標
    box = cdp("DOM.getBoxModel", backendNodeId=input_node["backendDOMNodeId"])
    x = sum(box["model"]["content"][0::2]) / 4
    y = sum(box["model"]["content"][1::2]) / 4

    # 點擊並輸入
    click_at_xy(x, y)
    type_text("test@example.com")
PY

案例 3：抓取動態載入的內容

PYTHON 
# 任務：抓取無限捲動的商品列表

browser-harness <<'PY'
goto_url("https://example.com/products")
wait_for_load()

products = []
last_height = 0

# 捲動直到沒有新內容
for _ in range(50):
    # 取得當前產品
    new_products = js("""
        Array.from(document.querySelectorAll('.product-card'))
            .map(card => ({
                name: card.querySelector('.name').textContent,
                price: card.querySelector('.price').textContent
            }))
    """)

    # 檢查是否有新內容
    if len(new_products) == len(products):
        break

    products = new_products

    # 捲動
    js("window.scrollTo(0, document.body.scrollHeight)")
    time.sleep(2)

print(f"Found {len(products)} products")
PY

限制性和適用場景

限制性

  1. 依賴 Chrome：只支援 Chrome/Chromium 系瀏覽器，不支援 Firefox/Safari
  2. 需要手動啟用遠端除錯：首次使用需要在 chrome://inspect 中勾選「允許遠端除錯」
  3. 座標點擊不穩定：頁面版面配置變化會導致座標失效（但 LLM 可以自適應）
  4. 不適合大規模爬蟲：單執行個體設計，不適合並行抓取數千個頁面
  5. 需要 LLM 支援：沒有 LLM 就無法發揮自修復能力

適用場景

✅ 個人自動化任務：下載影片、填寫表單、抓取資料 ✅ 測試和除錯：快速驗證網頁功能 ✅ 複雜互動流程：需要動態決策的多步驟任務 ✅ 已登入工作階段：利用 Chrome 的登入狀態存取需要認證的網站 ✅ Bot 保護網站：使用真實瀏覽器繞過反爬蟲機制

❌ 大規模資料抓取：使用 Scrapy + Playwright 更合適 ❌ 跨瀏覽器測試：使用 Playwright 的多瀏覽器支援 ❌ 簡單的 HTTP 請求：使用 requests/httpx 更高效

安裝和快速上手

安裝

BASH 
# 使用 uv 安裝（推薦）
uv tool install --python 3.12 browser-harness

# 或使用 pip
pip install browser-harness

首次設定

  1. 開啟 Chrome，存取 chrome://inspect/#remote-debugging
  2. 勾選「允許遠端除錯此瀏覽器執行個體」
  3. 測試連線：
BASH 
browser-harness <<'PY'
print(page_info())
PY

如果看到當前頁面的資訊（URL、標題、尺寸），說明連線成功。

與 Claude Code 整合

BASH 
# 安裝 browser-harness
uv tool install --python 3.12 browser-harness

# 註冊為 skill
mkdir -p ~/.codex/skills/browser-harness
browser-harness skill > ~/.codex/skills/browser-harness/SKILL.md

然後在 Claude Code 中，Agent 會自動使用 browser-harness 處理所有瀏覽器任務。

總結評價

Browser Harness 代表了 AI Agent 工具設計的一個重要趨勢：從複雜框架走向極簡主義。

它的核心洞察是：與其試圖預定義所有可能的瀏覽器操作，不如提供最小化的基礎函數，讓 LLM 根據具體任務動態產生程式碼。這種設計不僅減少了程式碼量，還提高了靈活性——Agent 可以處理從未見過的場景。

優點： - ✅ 程式碼極簡，易於理解和客製 - ✅ 自修復機制讓框架越用越強 - ✅ CDP 直接存取，效能優秀 - ✅ 支援雲端瀏覽器，可擴展到大規模任務 - ✅ 錄製功能方便除錯和回溯

缺點： - ❌ 依賴 Chrome，不支援其他瀏覽器 - ❌ 首次設定需要手動啟用遠端除錯 - ❌ 座標點擊在版面配置變化時不穩定 - ❌ 不適合大規模並行任務

推薦指數：⭐⭐⭐⭐⭐（5/5）

對於需要自動化瀏覽器任務的開發者，Browser Harness 是目前最優雅的選擇。它的極簡設計和自修復能力讓它能夠適應各種複雜場景，而 3,000+ 行的程式碼量意味著你可以輕鬆理解它的每一行實作。

如果你正在建構 AI Agent，或者需要自動化複雜的網頁任務，Browser Harness 值得一試。它可能會改變你對瀏覽器自動化的認知——最好的框架不是功能最多的，而是讓 AI 能夠自己解決問題的。

參考連結： - GitHub: browser-use/browser-harness - 文件: SKILL.md - 安裝指南: install.md - Browser Use Cloud: cloud.browser-use.com

FAQ

1. Browser Harness 和 Playwright 有什麼區別？

Browser Harness 是 AI 原生框架，設計目標是讓 LLM 控制瀏覽器，不提供選擇器引擎和進階等待機制，而是透過 CDP 直接操作座標和 DOM。Playwright 是傳統自動化框架，為人類編寫腳本設計，提供豐富的選擇器和等待機制。Browser Harness 的核心優勢是自修復能力——遇到不支援的操作時，LLM 會自己編寫程式碼。

2. Browser Harness 支援哪些瀏覽器？

目前只支援 Chrome/Chromium 系瀏覽器，包括 Google Chrome、Chrome Canary、Microsoft Edge、Brave、Arc 等。不支援 Firefox 和 Safari，因為 Browser Harness 依賴 Chrome DevTools Protocol (CDP)。

3. 如何啟用 Chrome 的遠端除錯？

開啟 Chrome，存取 chrome://inspect/#remote-debugging，勾選「允許遠端除錯此瀏覽器執行個體」。macOS 使用者可能需要在系統設定中授予終端機 Accessibility 權限。

4. Browser Harness 適合大規模爬蟲嗎？

不適合。Browser Harness 是單執行個體設計，主要面向個人自動化任務。如果需要並行抓取數千個頁面，建議使用 Scrapy + Playwright 或 Browser Use Cloud 的雲端瀏覽器功能。

5. 自修復機制是如何運作的？

當 Agent 遇到框架沒有覆蓋的操作時，它會自己編寫一個新的 Python 函數，儲存到 agent-workspace/agent_helpers.py 檔案中。下次執行任務時，這個函數會被自動載入。這樣框架就「學會」了新的能力，越用越強。