# 策展 · X (Twitter) 🔥🔥

> 作者：derek (@derekmeegan) · 平台：X (Twitter) · 日期：2026-04-29

> 原始來源：https://x.com/derekmeegan/status/2049218109807198331

## 中文摘要

Browser Trace 技能提供 Agent 瀏覽器 100% 可觀測性。

「Browser Trace」技能讓 Agent 自動化瀏覽器過程擁有完整可觀測性，透過附加唯讀 CDP 客戶端記錄網路請求、DOM 內容、螢幕截圖及 CDP 日誌，並匯入可搜尋檔案系統，適用於逆向工程、自動研究迴圈及即時監控。

**核心功能**

Browser Trace 不主動驅動頁面，僅監聽 CDP 事件，搭配「browser」技能、「bb」、「Stagehand」、「Playwright」或其他 CDP 相容工具使用。主要用於：
- 除錯瀏覽器自動化（如表單失敗、元素遺失、導航卡住、JS 例外）。
- 中途附加追蹤至運行中自動化，不需重啟。
- 分割 CDP 事件火管成網路、主控台、DOM、頁面等桶子。
- 依時間戳記錄螢幕截圖 + DOM 快照。

若僅需驅動瀏覽器，改用「browser」技能。

**運作機制**

Chrome DevTools 每個目標接受多個並發 CDP 客戶端，主自動化佔一個，Browser Trace 附加第二個，僅啟用觀測領域（Network、Console、Runtime、Log、Page），絕不發送動作指令。三個核心組件：
- **Firehose**：`browse cdp <target>` 串流所有 CDP 事件為 NDJSON 格式，每行一 JSON 物件至 `cdp/raw.ndjson`。
- **Sampler**：輪詢迴圈每隔間隔（預設 2 秒）呼叫 `browse --ws <target> screenshot` 及 `browse --ws <target> get html body`，--ws 為一次性連線，不干擾主自動化。
- **Bisector**：執行後 `bisect-cdp.mjs` 走訪 raw.ndjson，按 CDP 方法切割成各桶 JSONL 檔案，並以頂層 Page.frameNavigated 事件為邊界，按頁切割。

**本地 Chrome 快速入門**

1. 啟動 Chrome 帶除錯埠（9222）及隔離使用者資料夾：
   ```
   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
     --remote-debugging-port=9222 \
     --user-data-dir=/tmp/chrome-o11y \
     about:blank &
   ```
2. 啟動追蹤：`node scripts/start-capture.mjs 9222 my-run`。
3. 對埠 9222 執行主自動化，如 `browse env local 9222`、`browse open https://example.com`。
4. 停止並切割：`node scripts/stop-capture.mjs my-run`、`node scripts/bisect-cdp.mjs my-run`。

**Browserbase 遠端快速入門**

使用 `bb-capture.mjs` 及 `bb-finalize.mjs` 處理平台會計。Browserbase 於最後 CDP 客戶端斷線即結束工作階段，務必用 `--keep-alive` 建立，並先附加自動化客戶端。步驟：
1. 建立 keep-alive 工作階段並啟動追蹤：`node scripts/bb-capture.mjs --new my-run`，輸出 session id、connectUrl 前綴及即時除錯 URL。
2. 驅動自動化：`SID=$(jq -r .browserbase.session_id .o11y/my-run/manifest.json)`，然後 `browse --connect "$SID" open https://example.com`。
3. 停止、切割、拉取平台文物並釋放：`node scripts/stop-capture.mjs my-run`、`node scripts/bisect-cdp.mjs my-run`、`node scripts/bb-finalize.mjs my-run --release`。

中途附加運行中工作階段：`bb sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'` 選取 id，`node scripts/bb-capture.mjs <session-id> mid-flight-debug`，無干擾。

**檔案系統結構**

輸出至 `.o11y/<run-id>/`：
- `manifest.json`：執行中繼資料（target、domains、started_at、stopped_at）。
- `index.jsonl`：每樣本一行 {ts, screenshot, dom, url}。
- `cdp/raw.ndjson`：完整 CDP 火管。
- `cdp/summary.json`：會話總計（sessionId、duration、totalEvents、pages[]），pages 依 Page.frameNavigated 順序索引，每頁含 pageId、url、計時、事件數、domains 統計（如 Network 錯誤數）、network 細項（requests、failed、byType）。
- 分桶如 `cdp/network/{requests,responses,finished,failed,websocket}.jsonl`、`cdp/console/{logs,exceptions}.jsonl` 等。
- `cdp/pages/000/` 等按頁子目錄，重複桶子結構。
- `screenshots/<iso-ts>.png` 及 `dom/<iso-ts>.html`：每間隔樣本。
- Browserbase 專屬 `browserbase/`：`session.json`（proxyBytes、status 等）、`logs.json`（常空）、`downloads.zip`。

範例 summary.json 片段：
```
{
  "sessionId": "45f28023-…",
  "duration": { "startMs": 1777312533000, "endMs": 1777312609000, "totalMs": 76000 },
  "totalEvents": 420,
  "pages": [{ "pageId": 0, "url": "https://example.com/", "durationMs": 5886, "eventCount": 60, ... }]
}
```

**查詢與分析工具**

`scripts/query.mjs <run-id> <command>` 互動探索：
- `list`：頁面表格。
- `page 1`：頁 1 摘要。
- `page 1 network/failed`：頁 1 失敗請求。
- `errors`：全錯誤，按頁歸因。
- `hosts`：頂級主機請求數。
- `summary`：完整摘要。

進階 jq 配方如：
- 所有失敗網路：`jq -c '.params' .o11y/<run>/cdp/network/failed.jsonl`。
- 特定主機請求：篩選 url 含 "api\\.example\\.com"。
- 4xx/5xx 回應：status >= 400。
- 主控台錯誤：type == "error"。
- 造訪 URL 序列：Page.frameNavigated 的 frame.url。

**最佳實務與疑難排解**

**最佳實務**：
- Browserbase 用 `bb-capture.mjs`，自動 --keep-alive 並記錄 debugger URL，手動易錯。
- 非自有工作階段勿 --release。
- 遠端順序：自動化客戶端先附加，--keep-alive 建立。
- 輪詢勿快於 1 秒，預設 2 秒。
- 精選領域，預設 Network/Console/Runtime/Log/Page；DOM 極吵。
- 總執行 `stop-capture.mjs`，即使崩潰。
- `bisect-cdp.mjs` 單次 idempotent。

**疑難排解**：
- `browse cdp` 即退出：目標不可及或工作階段結束，驗 `bb sessions get <id>`。
- `raw.ndjson` 空：確認主客戶端驅動頁面，閒置僅 ~5 行。
- 截圖相同：查 `index.jsonl` url 未變。
- 工作階段中斷：超 --timeout，調高 BB_SESSION_TIMEOUT。
- `logs.json` 空：正常，CDP 火管為真實來源。
- rrweb 錄影棄用，用 screenshots/dom 取代。

完整參考見 REFERENCE.md，範例除錯見 EXAMPLES.md。此技能強化 Agent 瀏覽器除錯，強調不干擾監聽及細緻切割，提供生產級可觀測性。

## 標籤

Skills, Agent, 自動化, Browser Trace, Playwright, Stagehand