andy922200 browser-web-data-discovery
何時使用
以下任一情境出現即套用本規範：
- 使用者要求爬取／收集／擷取某網站的資料。
- 需要觀察 JS 渲染後的實際 DOM（而非原始 HTML）。
- 需要模擬點擊、捲動、表單輸入等互動才能看到目標資料。
- 需要側錄 network request 才能找出資料實際來源的 API endpoint。
- 先前用 WebFetch／curl 抓不到預期資料，需要進一步確認是否真的沒有結構化來源。
- 資料可能因自動套用的頁面條件、分頁、無限捲動、限流或暫時性失敗而不完整。
不適用：目標已有明確、已知的 REST/JSON API（不需要模擬瀏覽器互動）、使用者已明確指定要用 特定 HTTP 工具、任務本身與網頁擷取無關。
核心規則
- 先盤點當前環境是否有可操作真實瀏覽器、讀取渲染後 DOM，或檢視網路請求的能力。依環境選擇合適的 工具與其既有操作方式；不要假定某個 MCP、CLI、函式名稱或延遲載入機制一定存在。
- 實際開啟目標頁面並讀取渲染後內容。需要找資料來源時，檢視頁面發出的網路請求，確認實際使用的 API endpoint、參數與回應格式。
- 明確禁止：只憑直接 HTTP 請求取得的靜態 HTML 就判斷「網站沒有結構化資料」或「爬不到」——必須先 用可用的瀏覽器能力實際開頁驗證過，才能下這個結論。僅確認工具存在、沒有實際操作，不算完成。
- 例外／fallback 條件（符合下列任一才可以改用直接 HTTP 請求）：
- 目標明確有公開、已知結構的 REST/JSON API。
- 使用者已明確指定要用特定 HTTP 工具。
- 當前環境沒有可用的瀏覽器能力，或實際操作持續失敗。
- 因能力缺失或工具失敗而 fallback 時，必須在回覆中說明原因與已嘗試的方式，不可默默切換工具。
- 避免觸發 JS 的
alert/confirm/prompt等 modal dialog，會卡住後續操作；如果頁面可能跳出 dialog，先確認所用工具如何偵測或處理 dialog，不要直接點擊可能觸發 dialog 的元素。
目標條件與資料完整性
- 先從官方入口以真實瀏覽器確認渲染後內容，並記錄入口 URL、觀察時間及實際導向結果。
- 網站會依地區、語言、配送設定或其他條件改變結果時，優先使用頁面提供的控制項；以網域、頁面標示、 語言、貨幣或其他可見訊號驗證預定條件。不得猜測 URL、cookie 或未觀察到的 API 規則。
- 無法找到或驗證預定條件時，保存已嘗試的路徑與實際結果，停止收集並請使用者提供有效入口或必要條件。
- 條件確認後才探索官方可觀察到的結構化資料、network response、分頁參數或 cursor。每項觀測保留來源 URL、 時間、原始文字或回應，以及解析結果。
- 以官方總數、最後頁、空 cursor 或
hasNextPage: false等來源停止訊號，加上累積唯一資料筆數，共同判定 完成；錯誤、timeout、空白畫面或單次空回應不是停止訊號。
可恢復收集與限制處理
每個可獨立完成的階段都要將 checkpoint 落盤，不可只放在記憶體、瀏覽器 session 或 localStorage。checkpoint 至少記錄已完成範圍與最後成功位置、累積唯一資料數、來源時間、目標條件驗證結果、觀測資料位置、錯誤類型、 嘗試次數、建議重試時間及未完成範圍。
- 分別記錄 HTTP 429、
Retry-After、5xx、timeout、連線錯誤和 session 遺失。 - 預設採有限次數、帶抖動的退避重試；尊重
Retry-After，不提高併發、不更換識別，也不規避反爬措施。 - 重試預算耗盡後，停止並交付 checkpoint。只有使用者明確指定重試時間與範圍，才安排自動恢復。
- session 中斷後，建立新 session、重新驗證目標條件，再從已落盤 checkpoint 繼續。
Evidence 與資料交付
- Evidence 至少包含入口與狀態變化、目標條件驗證方式、資料來源與停止條件、重試紀錄、唯一筆數與官方總數對帳、 限制及未完成項目。
- 不保存 cookie、token、授權標頭、帳號資料或其他機敏資訊；只記錄可公開重現的狀態與 URL。
- 正式資料只能由已保存的觀測資料產生。更新前先驗證唯一性、欄位解析、來源對帳與跨檔一致性；不可補造來源或 覆寫歷史價格點。
- 最終明確回報為「完成」、「部分完成且可恢復」或「因存取限制停止」，並對後兩者提供 checkpoint 或使用者 所需協助。
完成前檢查
- 是否先使用了當前可用的瀏覽器能力，而非直接發出 HTTP 請求
- 若最終改用直接 HTTP 請求，是否有明確理由並已告知使用者
- 是否觀察了渲染後內容／network request，而非只看原始 HTML 就下結論
- 結果受頁面條件影響時，是否已透過官方控制項設定並驗證預定條件
- 是否以來源停止訊號與唯一資料筆數共同確認完整性
- 是否保存可恢復 checkpoint 與不含機敏資訊的 evidence