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

診斷流程

先用既有 crawler/API 重現問題，保存失敗 SKU、搜尋詞、候選網址與 matcher diagnostics。
使用 browse 開同一頁，查看搜尋結果 DOM、network 與 console。
若找到穩定 XHR/API，優先回補到 Python crawler；若只能走 DOM，才更新 selector。
新增或更新單元測試，至少覆蓋搜尋詞、候選解析與 matcher hard veto。
只在測試通過後部署 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() 決定。

PixelRAG-style 視覺證據 fallback

2026-07-09 評估 PixelRAG 後，結論是「可導入，但不可直接取代正式爬蟲」。PixelRAG 的核心價值是把渲染後頁面截圖切成 tiles，讓 AI 讀到 HTML parser 可能丟失的視覺結構；本專案第一階段只採用這個視覺證據思路，不直接拉外部 runtime、不用外部 embedding API、不把像素結果寫入正式價格表。

導入順序：

既有 PChome API / MOMO structured parser 先跑；若 parser 結果為空、價格欄位缺失、規格/組合資訊疑似只存在渲染畫面，才啟動視覺證據 fallback。
Phase 1 只輸出 screenshot/tile manifest：URL、platform、crawler、parse failure、viewport、tile coordinates、artifact path、evidence intent。
Phase 2 用 manifest 收集 replay samples，對照 marketplace_product_matcher 與 competitor_match_attempts 的診斷結果，評估是否提高身份證據覆蓋率。
Phase 3 才評估 Ollama-first multimodal embedding；未完成 GCP-A → GCP-B → 111 視覺 embedding 驗證前，不做自動像素檢索。
Phase 4 若需要索引，優先設計 pgvector-compatible evidence metadata；FAISS 只能先當本地研究/ADR 候選，不直接進 production。
Phase 5 才談 crawler fusion；正式 competitor_prices / competitor_price_history 寫入仍需 matcher replay/canary 證據。

機器可讀評估：

python scripts/ops/report_pixelrag_crawler_integration.py
python scripts/ops/report_pixelrag_crawler_integration.py --platform momo
python scripts/ops/report_pixelrag_crawler_integration.py --capability ollama_multimodal_ready --capability pgvector_visual_ready
python scripts/ops/report_pixelrag_crawler_integration.py \
  --platform momo \
  --manifest-url "https://m.momoshop.com.tw/search.momo?searchKeyword=test" \
  --crawler MomoCrawler.search_products \
  --trigger-reason parser_empty \
  --page-size page=1440x1900 \
  --tile-size tile=512x512

登入後 API 回讀：

/api/ai-automation/pixelrag-crawler-integration?platform=momo
/api/ai-automation/pixelrag-crawler-integration?platform=pchome&manifest_url=https://24h.pchome.com.tw/prod/TEST-000000001&crawler=PChomeCrawler.search_products&trigger_reason=parser_empty
/api/ai-automation/pixelrag-visual-evidence-readback?platform=pchome&manifest_id=4a93e95e5afb414bc8c3

視覺證據 capture worker：

python3 scripts/ops/report_pixelrag_crawler_integration.py \
  --platform momo \
  --manifest-url "https://m.momoshop.com.tw/search.momo?searchKeyword=test" \
  --crawler MomoCrawler.search_products \
  --trigger-reason parser_empty \
  --page-size page=1440x1900 \
  --tile-size tile=512x512 \
  > /tmp/pixelrag_manifest.json

node scripts/ops/capture_pixelrag_visual_evidence.js \
  --manifest-file /tmp/pixelrag_manifest.json \
  --output-dir runtime_artifacts/pixelrag_visual_evidence \
  --dry-run

node scripts/ops/capture_pixelrag_visual_evidence.js \
  --manifest-file /tmp/pixelrag_manifest.json \
  --output-dir runtime_artifacts/pixelrag_visual_evidence

# Production host can use the Python Playwright worker when Node modules are not installed.
python3 scripts/ops/capture_pixelrag_visual_evidence.py \
  --manifest-file /tmp/pixelrag_manifest.json \
  --output-dir runtime_artifacts/pixelrag_visual_evidence \
  --max-tiles 12

capture 成功後，receipt 會落在：

runtime_artifacts/pixelrag_visual_evidence/<platform>/<manifest_id>/capture_receipt.json

API readback 只讀 receipt 和檔案存在狀態，不重新抓外站、不寫資料庫。正式 app 容器內的 readback 預設讀 /app/data/ai_automation/pixelrag_visual_evidence；host worker 若直接在 188 執行，預設仍可用 runtime_artifacts/pixelrag_visual_evidence，需要給 API 回讀時再同步到容器掛載的 data/ai_automation。

安全邊界：

read-only；不登入、不下單、不加入購物車、不寫第三方狀態。
不從像素結果直接寫正式價格或同款判斷，只寫 artifact / review diagnostics。
不使用 GitHub runtime 依賴；不讀 secrets / sessions / cookies。
不呼叫 hosted embedding / VLM API；如需 embedding，必須走 Ollama-first 並保留成本/品質 benchmark。
若穩定 XHR/API 可取得同樣資訊，仍優先回補 structured parser，不把視覺 fallback 變成主路徑。

7.1 KiB Raw Blame History Unescape Escape