架構

go-browser 系統架構 — Launcher、Fetch 管線、互動式分頁、Cookie 提取與內容處理模組。

系統概覽

graph TB
    A[Fetch / CreateTab] --> B[Launcher]
    B --> C{Headless?}
    C -->|Yes| D[Stealth JS]
    C -->|No| E[Cookie Session]
    D --> F[Page Navigate + Scroll]
    E --> F
    F --> G[Snapshot Merge]
    G --> H[Readability + Dedup]
    H --> I[Markdown / HTML / JSON]

模組層級

模組	套件	職責
Launcher	`core/launcher.go`	Chrome 生命週期管理、單例 headless 瀏覽器（含閒置回收）、暫存設定檔快照實例
Fetch	`core/fetch.go`	內容提取管線 — 導航、滾動、快照擷取、格式輸出
Interactive Tabs	`core/browser.go`	有狀態分頁管理 — 點擊、輸入、滾動、執行 JS、快照
Cookie Extraction	`core/cookie.go`	跨平台 Chrome Cookie 解密，從本機設定檔 SQLite 提取
Content Processing	`core/markdown.go`	快照合併、時間元素內聯、readability 解析、Markdown/HTML/JSON 轉換、去重

Launcher

管理兩種瀏覽器模式：

單例 headless — 跨請求重複使用的單一 headless 瀏覽器實例，具 5 分鐘閒置回收 goroutine。用於 Headless: true 或無顯示器可用時。
設定檔快照 — 從本機 Chrome 設定檔提取 Cookie 後啟動的暫存瀏覽器。用於 SameSession: true 或 headed 擷取失敗後的回退。

Launcher 設定的 Chrome 旗標包含 disable-blink-features=AutomationControlled、no-sandbox、disable-dev-shm-usage 及自訂 user-agent。macOS 上於 /Applications/Google Chrome.app 尋找 Chrome；Linux 上搜尋 PATH。

Fetch 管線

URL 解析 — 透過 parseHref 驗證 scheme 與 hostname。
模式選擇 — 根據 Option.Headless、Option.SameSession 及 domain 判斷 headless 或 session 模式。
頁面建立 — 建立頁面並設定 viewport，透過 EvalOnNewDocument 注入 stealth.js。
導航 — 導航至目標 URL，等待載入完成，檢查最終 URL 是否含 404/403 模式。
DOM 穩定 — 等待 DOM 穩定並執行 settle.js 處理延遲載入內容。
滾動迴圈 — 擷取初始快照後，以隨機延遲平滑滾動，每次滾動後擷取快照。
內容處理 — 依 Option.Type 合併 HTML 快照、執行 readability 提取、轉換為 Markdown/HTML/JSON 並去重。

Interactive Tabs

有狀態分頁管理，支援多步驟瀏覽器互動：

CreateTab — 啟動或重複使用互動瀏覽器，建立頁面、導航、回傳分頁 ID。
TabClick — 透過 document.querySelector(s)?.click() 點擊元素。
TabType — 透過原型屬性描述子設定輸入值，並觸發 input/change 事件。
TabScroll — 以隨機延遲滾動至頁面底部。
TabEval — 執行自訂 JavaScript 並回傳結果。
TabSnapshot — 將目前頁面擷取為 Markdown/HTML/JSON。
CloseTab — 關閉分頁並釋放 semaphore；無剩餘分頁時關閉互動瀏覽器。

跨平台 Chrome Cookie 解密（core/cookie.go，僅 darwin 與 linux）：

透過 OS 鑰匙圈取得 Chrome Safe Storage 密碼（macOS 用 security，Linux 用 secret-tool）。
使用 PBKDF2-SHA1 搭配 1003 次疊代推導 AES 金鑰。
查詢 Chrome 設定檔 SQLite Cookies 資料庫，取得 host_key、name、value、encrypted_value、path、expires_utc、is_secure、is_httponly、samesite。
使用 AES-CBC 搭配空格填充的 IV 解密 v10 前綴的加密值。
回傳 NetworkCookieParam 物件供注入暫存瀏覽器。

Content Processing

Merge — 將後續快照的 body 子節點附加至基礎文件的 body，合併多個 HTML 快照。
InlineTimeElements — 將 <time> 元素取代為其 datetime 屬性與內部文字。
HTMLToMarkdown — 遍歷 HTML 樹，將標籤對應至 Markdown 語法（標題、列表、連結、程式碼區塊等）。
HTMLToNode — 將 HTML 轉換為結構化 []*Node 樹，供 JSON 輸出。
DedupMarkdownParagraphs — 透過雜湊移除重複段落。
DedupTree — 透過 FNV-64a 雜湊從 JSON 樹移除重複節點。

架構