[V10.359] 導入 browse.sh 診斷與色號防錯配

docs/guides/browse_sh_crawler_playbook.md

@@ -0,0 +1,53 @@
+# 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。
+
+## 本地檢查
+
+```bash
+python scripts/tools/browse_sh_probe.py
+```
+
+可用時會輸出 `available=true` 與版本；不可用時會輸出原因。若 `browse` 不在 PATH，可用：
+
+```bash
+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`。
+
+## 常用命令
+
+```bash
+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()` 決定。