agent-browser

一個為 AI 代理強化的本機瀏覽器。零依賴。 透過 DevTools 協定驅動你既有的 Chrome，擷取節省 token 的 Markdown，而且不會被輕而易舉地標記為自動化程式。

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

一切都在本機執行。不需要帳號、不需要 API 金鑰、沒有遠端服務、沒有流量限制。

為什麼

將原始 HTML 餵給代理程式會浪費其大部分上下文。在真實頁面上實測結果：

而且一個宣告自己是自動化程式的瀏覽器，會被封鎖、降級，或提供不同的內容——這會悄悄污染代理程式所做出的任何結論。

Related MCP server: Browser-MCP Navigator

安裝

作為 MCP 伺服器

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

工具：browser_markdown、browser_text、browser_html、browser_links、browser_screenshot、browser_evaluate、browser_accessibility_tree、browser_pdf、browser_probe。

作為函式庫使用

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

作為 DSH / Cordis 外掛

一行式安裝（建議——當你想要 純正的 DSH 時自動連接）：

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

重新啟動 dsh——browser_markdown、browser_text、browser_links、browser_evaluate、browser_screenshot、browser_probe 以及以下工具會以原生工具形式出現。在一般 npm install 上運作時，並不會執行任何處理程序；必須明確 install 才行。

手動安裝（如果你偏好自行編輯 composition）：

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

需要 Node ≥ 18 和已安裝的 Chrome/Chromium。接著新增至 宿主 的 composition（工具登錄表位於宿主，而非每個代理各自擁有）：

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

簡短形式（當 composition 已包覆 insert 時）：

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

環境變數覆寫：AGENT_BROWSER_BIN（Chrome 執行檔）、AGENT_BROWSER_ENDPOINT（透過 --endpoint 連接到長駐瀏覽器）、或 config.cli。

命令行工具 (CLI)

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

選項：--headful、--no-stealth、--block-images、--gpu/--no-gpu、--width、--height、--viewport WxH、--main、--raw、--full、--endpoint <ws>、--timeout、--json、-o。

--endpoint 會連接到已經執行中的瀏覽器，而不是啟動一個新瀏覽器——這在做越多個呼叫、並重複使用跨越多次呼叫的單一長駐瀏覽器，特別有用。

相關文章 機器偵測

你可以自行執行測試：npm run test:bot。最新結果：

普通的無頭 Chrome 在 sannysoft 四行會失敗（HEADCHR_UA、CHR_MEMORY、WebGL SwiftShader、舊 UA）並會被回報為機器人。

無法連到的偵測器將計為 SKIP，不會被視為通過；而門檻需要三個可連到的偵測器通過——因此測試網站當機的日子不能被誤認為成功。

環境比修補程式更重要

相同的程式碼，在兩個地方測量的結果：

每個 CDP 層面的訊號在兩邊都是乾淨的——這部分屬於程式碼，且程式碼正確無誤。而改變判定的就是環境：資料中心 ASN 加上軟體渲染會觸發一個弱訊號綜合指標，無論如何修補指紋都無法解決。

這就是問題的原貌。強化瀏覽器可以移除 基本線索；你在哪裡運行它才是決定勝負的關鍵。

強化的內容及其原因

每個項目都是因為偵測器告訴我們錯了才加入的：

• 不開啟 --enable-automation。 這是 Puppeteer 與 Playwright 會加上的旗標——正式它設定了 navigator.webdriver = true。原始 CDP 不會設定它，所以它會維持 false 並保持乾淨。

• 沒有使用 Runtime.enable。 它是最明顯的 CDP 訊號，也是經典 console/Error.stack 偵測器的力量源頭。Runtime.evaluate 不需要它也能正常運作。

• 視窗與螢幕一起移動。 --window-size 沒有搭配 --ozone-override-screen-size 就會產生 outerWidth > screen.width，這在 physical 上不可能——比一般無頭更強烈的訊號。

• 不預設覆寫裝置度量值。 常見的 1280×720 是 Playwright 的預設視窗大小，偵測器會 透過名稱 標記它。只有在需要時才設定 --viewport。

• 可用的真實 GPU 即用真實 GPU，否則產生真正的 ANGLE (NVIDIA …) 渲染器，而不是 SwiftShader。

• 啟動時就設定 UA，而不是只透過 CDP。 Emulation.setUserAgentOverride 無法到達 Web Workers，所以 worker 會依然回報無頭 UA，而頁面卻回報乾淨的 UA（hasInconsistentWorkerValues）。

• 不覆寫 acceptLanguage。 CDP 會透過分離該標頭來推導 navigator.languages，因此 "en-US,en;q=0.9" 會變成 ["en-US","en;q=0.9"] ——一個合法的 q 值，且兩處的頁面/worker 又不一致。--lang 可以正確設定。

• Client Hints 從執行檔自身的版本推導，因此 Sec-CH-UA 不可能與 navigator.userAgent 不一致。

• 每次 session 使用隔離的瀏覽器 context，並在關閉時清除——每個任務都能有乾淨的狀態，而不需要第二個瀏覽器程序。

重複的教訓：一致性比覆蓋更重要。 其中有四項是部分偽裝反而 更可能 被偵測，只有透過執行真實的偵測器才能發現的問題。

為什麼 WebGL 偽裝預設關閉

spoofWebgl 存在並被仔細實作——以原生 getParameter 包覆 Proxy，讓 Function.prototype.toString 仍然回報 [native code]。它被關閉，因為測量顯示它會適得其反。 來自 test/webgl-spoof-experiment.mjs：

號稱擁有你其實沒有的硬體，可以修好一列外觀問題，卻仍無法通過整體偵測：注入的腳本無法到達 Web Workers，所以 worker 仍然回報 SwiftShader，而 MAX_TEXTURE_SIZE 維持在軟體值，但渲染器字串卻聲稱是獨立顯示卡。

誠實的 SwiftShader 反而能通過。一個令人信服的謊言卻不行。請給瀏覽器一顆真實 GPU——這不用付出任何成本，受益無窮。

這沒有做到的事

指紋層級的偵測是全部範圍。它不會擊敗，也不試圖擊敗：

• TLS/JA3-JA4 與 HTTP/2 指紋識別——在任何 JavaScript 執行之前就決定好了

• IP 名聲——資料中心對比住宅 ASN，常常是真正的障礙

• 行為分析——滑鼠軌跡、時間、停留時間

商業繞過產品通常依賴那些，所以「通過閘門」在實務上等於 不是基本的自動化，而並非完全不可偵測。設計目標是讓你自己有自己的網站、測試、無障礙工作，以及一般的代理瀏覽。

記憶體

一個 Chrome 堆疊大約耗用 450 MB。槓桿在架構而不在旗標，執行一個瀏覽器並把多個隔離 context 放在一起，而不是每個任務一個瀏覽器。啟動一次瀏覽器，然後用它來指向每個呼叫使用 --endpoint / AGENT_BROWSER_ENDPOINT。--block-images 有助於純文字工作場景。

零依賴

執行 dependencies 是空的，包含 WebSocket transport。

Node 全域性 WebSocket（WHATWG）無法傳送要求標頭，這對任何需要驗證或代理的 CDP 端點都是必要的，而 undici 不能獨立匯入。因此 src/ws.mjs 直接基於 node:http(s) 實作 RFC 6455——Handshake、masking、continuation fragments、64-bit lengths、ping/pong——這正是 CDP 所需的完整內容。

Markdown 轉換器使用明確堆疊走訪 DOM，讓 JS 呼叫深度對任何巢狀層級都保持 O(1)、且對葉層級的內斂節點使用原生 innerText。這讓程式在極度巢狀的文件中也沒有遞迴因爆風險，翻譯層級、大型頁面友善。在大型頁面的解析速度也提升明顯。

環境

需求

Node ≥ 18 和已安裝的 Chrome/Chromium。無需建置步驟。

鳴謝

這個專案的強化技術幾乎全部源自先前人發表的偵測研究——請參考 CREDITS.md。特別感謝 rebrowser-bot-detector、bot.sannysoft.com、deviceandbrowserinfo.com，以及 Camoufox，感謝它們示範如何正確進行這項技術。

智慧產財權 License

MIT