@derekmeegan：Browser Trace 技能提供 Agent 瀏覽器 100% 可觀測性。 「Browser Trace」技能讓 Agent 自動化瀏覽器過程擁有完整…

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 串流所有 CDP 事件為 NDJSON 格式，每行一 JSON 物件至 cdp/raw.ndjson。 Sampler：輪詢迴圈每隔間隔（預設 2 秒）呼叫 browse --ws screenshot 及 browse --ws get html body，--ws 為一次性連線，不干擾主自動化。 Bisector：執行後 bisect-cdp.mjs 走訪 raw.ndjson，按 CDP 方法切割成各桶 JSONL 檔案，並以頂層 Page.frameNavigated 事件為邊界，按頁切割。 本地 Chrome 快速入門 啟動 Chrome 帶除錯埠（9222）及隔離使用者資料夾： ` "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \ --remote-debugging-port=9222 \ --user-data-dir=/tmp/chrome-o11y \ about:blank & ` 啟動追蹤：node scripts/start-capture.mjs 9222 my-run。 對埠 9222 執行主自動化，如 browse env local 9222、browse open https://example.com。 停止並切割：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 建立，並先附加自動化客戶端。步驟： 建立 keep-alive 工作階段並啟動追蹤：node scripts/bb-capture.mjs --new my-run，輸出 session id、connectUrl 前綴及即時除錯 URL。 驅動自動化：SID=$(jq -r .browserbase.session_id .o11y/my-run/manifest.json)，然後 browse --connect "$SID" open https://example.com。 停止、切割、拉取平台文物並釋放：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 mid-flight-debug，無干擾。 檔案系統結構 輸出至 .o11y//： manifest.json：執行中繼資料（target、domains、startedat、stoppedat）。 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/.png 及 dom/.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 互動探索： list：頁面表格。 page 1：頁 1 摘要。 page 1 network/failed：頁 1 失敗請求。 errors：全錯誤，按頁歸因。 hosts：頂級主機請求數。 summary：完整摘要。 進階 jq 配方如： 所有失敗網路：jq -c '.params' .o11y//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 。 raw.ndjson 空：確認主客戶端驅動頁面，閒置僅 ~5 行。 截圖相同：查 index.jsonl url 未變。 工作階段中斷：超 --timeout，調高 BBSESSIONTIMEOUT。 logs.json 空：正常，CDP 火管為真實來源。 rrweb 錄影棄用，用 screenshots/dom 取代。 完整參考見 REFERENCE.md，範例除錯見 EXAM…