# 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()` 決定。