ewoooc/docs/guides/browse_sh_crawler_playbook.md

Browse.sh Crawler Playbook

Scope: MOMO / PChome 動態頁診斷、selector 探勘、XHR/network trace。正式價格資料仍以既有 Python crawler、PChome API 與資料庫閉環為準。

評估結論

• browse.sh 是 Browserbase 提供的 browser CLI，主打 open web catalog、browser primitives、debugging、cloud sessions 與 network/console tail。
• 官方安裝入口為 npm install -g browse，CLI 名稱是 browse。
• 對本專案最有價值的地方不是取代爬蟲，而是當 MOMO/PChome HTML 或前端 XHR 改版時，快速看 selector、console、network 與可重放 skill。
• 本機目前 Node 16 因 icu4c 動態庫缺失無法啟動，不能在本機直接安裝或執行 browse。導入方式先採 optional wrapper，不影響 production scheduler。

使用邊界

• 只允許做 read-only 診斷，不登入、不下單、不加入購物車、不寫第三方狀態。
• 不把 browse 放進排程主路徑；若未來要排程化，需另開 ADR 與 feature flag。
• 不把 browse 輸出直接寫成正式價格；所有正式比價仍需經 services/pchome_crawler.py、services/momo_crawler.py、services/marketplace_product_matcher.py 與 competitor_match_attempts 診斷。
• Cloud sessions 可能需要 Browserbase 帳號與憑證；憑證不可寫入 repo。

本地檢查

python scripts/tools/browse_sh_probe.py

可用時會輸出 available=true 與版本；不可用時會輸出原因。若 browse 不在 PATH，可用：

BROWSE_SH_CLI=/path/to/browse python scripts/tools/browse_sh_probe.py

診斷流程

1. 先用既有 crawler/API 重現問題，保存失敗 SKU、搜尋詞、候選網址與 matcher diagnostics。
2. 使用 browse 開同一頁，查看搜尋結果 DOM、network 與 console。
3. 若找到穩定 XHR/API，優先回補到 Python crawler；若只能走 DOM，才更新 selector。
4. 新增或更新單元測試，至少覆蓋搜尋詞、候選解析與 matcher hard veto。
5. 只在測試通過後部署 app/scheduler/bot；不得重建或重啟 momo-db。

常用命令

python scripts/tools/browse_sh_probe.py -- --version
python scripts/tools/browse_sh_probe.py -- skills list
python scripts/tools/browse_sh_probe.py -- open "https://24h.pchome.com.tw/"
python scripts/tools/browse_sh_probe.py -- network --tail
python scripts/tools/browse_sh_probe.py -- screenshot

MOMO/PChome 導入策略

• PChome：目前已有搜尋 API 與商品 API，browse 只用於確認 API 參數、分頁行為、前端是否切新 endpoint。
• MOMO：若既有 BeautifulSoup selector 失效，先用 browse 找出前端實際 XHR；找到 API 時優先改成 structured API parser。
• Matcher：browse 只提供候選證據；是否為同款仍由 marketplace_product_matcher.score_marketplace_match() 決定。