多平台 API 路由動態容錯工作流

在社群媒體與網路數據抓取的開發中，API 被限流或遭遇封禁是極為常見的。多平台 API 路由動態容錯工作流是 Agent Reach 用來確保 AI 代理連線高可用的核心流程。當主通道失效時，系統能快速、無感地在數秒內切換到備選通道。

這套工作流包含 4 個判斷與重試階段：

graph TD
    A["步驟 1：發起請求 (Request)"] --> B{"步驟 2：官方 API 可用？"}
    B -->|是| C["執行成功 (回傳數據)"]
    B -->|否：發生限流／錯誤| D["步驟 3：切換網頁模擬 (Web Fallback)"]
    D --> E{"網頁模擬成功？"}
    E -->|是| C
    E -->|否：遭遇 Cloudflare / WAF 阻擋| F["步驟 4：切換無頭瀏覽器 (Headless Browser)"]
    F --> G{"瀏覽器渲染成功？"}
    G -->|是| C
    G -->|否| H["回報連線失敗 (診斷報告)"]

工作流詳細步驟

1. 發起請求 (Request Initiated)

AI 代理發出數據讀取指令（例如 agent-reach read --platform=twitter --query="#AI"）。

2. 官方 API 探針與判斷 (API Probe)

Agent Reach 引擎首先調用配置的官方 API Key 進行查詢。如果 API 返回 200，則正常獲取並格式化 JSON 數據回傳給代理，本次工作流結束。

3. 切換網頁模擬 (Web-Fallback Switching)

若官方 API 返回 429 (Rate Limit) 或 401 (Unauthorized)，引擎會截獲此錯誤，並自動切換至網頁模擬後端。它會隨機選擇一組 User-Agent，並發送與真實瀏覽器一致的 HTTP GET 請求，直接抓取 HTML 頁面並進行解析。

4. 啟動無頭瀏覽器 (Headless Browser Activation)

若網頁模擬請求遭遇了 IP 封鎖或 Cloudflare 盾牌阻擋，引擎會自動在背景啟動無頭瀏覽器 (Puppeteer/Playwright 核心)。瀏覽器會加載完整網頁、等待 JavaScript 執行完畢以渲染出 DOM，再將內容提取出來。這是最慢但成功率最高的一道防線。