Google Lens 代理技能
此技能允許 AI 代理執行反向圖片搜尋、擷取光學字元辨識 (OCR) 文字、偵測視覺實體，並透過 Google Lens 尋找購物比對結果與價格。
先決條件與安裝
如果環境中尚未安裝 google-lens，請安裝套件並下載隱匿 Chromium 瀏覽器二進位檔：
pip install google-lens-scraper
patchright install chromium
注意： 快速路徑 OCR 模式 (
--ocr-only) 僅需 Python 套件，可立即運作，無需下載 Chromium 二進位檔。
快速入門範例
1. 反向圖片搜尋與視覺智慧（預設模式）
若要尋找比對產品、網路來源、標準化價格分析與多模態屬性分析：
google-lens search "<image-url-or-path>" --json-output
注意：根據預設，google-lens search 會在存在 GEMINI_API_KEY 時自動執行電子商務價格標準化 (--enrich) 與深度多模態屬性分析 (--analyze)（透過 Gemini 3.8 Flash）。
代理情境備援策略：如果
results.analysis為null（因為主機環境未設定GEMINI_API_KEY），**您（AI 代理）**應在自身對話脈絡中直接檢查查詢圖片與回傳的visual_matches，以推斷產品屬性（品牌、型號輪廓、材質、狀況、預估建議售價、真偽線索）。這保證了使用者無需額外 API 金鑰即可獲得零摩擦體驗。
2. Nano Banana Pro 8K AI 工作室包裝生成
若要從參考圖片合成解析度極高的 8K 商業目錄包裝（置於純白背景上）：
google-lens search "<image-url-or-path>" --studio --studio-output ./packshot.png
您可以選擇性地提供自訂提示：
google-lens search "<image-url-or-path>" --studio --studio-prompt "8K 工作室目錄拍攝，背景為黑色刷紋花崗岩，搭配柔和的戲劇性邊緣光"
3. 快速路徑 OCR 與物件偵測（次秒級，無 CAPTCHA）
若要從圖片中擷取文字或邊界框（使用 Chromium Protobuf 端點，無瀏覽器開銷）：
google-lens search "<image-url-or-path>" --ocr-only --json-output
4. 電子商務與轉售套利智慧（專業版）
若要解析乾淨的標準網址、標準化價格範圍（最低/最高/平均），並找出價格最低的已驗證賣家（「最佳交易」）：
google-lens search "<image-url-or-path>" --enrich --json-output
若要將豐富化後的商務資料直接匯出為乾淨的 JSON：
google-lens search "<image-url-or-path>" --export-json deals.json
5. 即時代幣與成本會計
每次 Gemini API 呼叫（Gemini 3.8 Flash 與 Nano Banana Pro）都會使用內建的 gemini-cost-calculator 自動追蹤。透過 CLI 或 SDK 呼叫時，results.cost 會傳回精確的代幣使用量與以美元計價的財務成本：
"cost": {
"model": "gemini-3.8-flash",
"calls_count": 1,
"tokens": { "prompt": 450, "output": 180, "total": 630 },
"cost_usd": { "total": 0.001013 }
}
6. 授權啟用與設定（專業版）
專業版功能（市場定價情報、乾淨網址、JSON 匯出、工作室包裝）需要有效的 Polar.sh 授權。
購買授權（瀏覽器）：
google-lens buy pro
# 或指定方案：
google-lens buy --plan annual
直接於瀏覽器中開啟 Polar.sh 結帳頁面，以便選擇方案（終身、年度或月費）。
在終端機中啟用：
google-lens pro activate "<your-polar-license-key>"
# 或以互動方式執行：
google-lens pro activate
# 或設定環境變數：
export LENS_LICENSE_KEY="<your-polar-license-key>"
檢查授權狀態：
google-lens pro status
在此機器上停用：
google-lens pro deactivate
7. Google AI Studio 金鑰（選用，僅供 --studio 使用）
Google Lens Scraper 在一般搜尋或產品屬性上不需要任何 Gemini API 金鑰——這些屬性會直接從 Lens 元資料中推斷，實現零摩擦。
若要合成 8K AI 工作室包裝 (--studio)，請設定您的金鑰一次：
google-lens setup-ai --key "<your-gemini-api-key>"
# 或設定環境變數：
export GEMINI_API_KEY="<your-gemini-api-key>"
8. 工作階段狀態與 Google 驗證
Google Lens 需要已驗證的 Google 工作階段才能獲得完整的視覺比對結果，並避免 /sorry/index 速率限制：
google-lens status
如果未通過驗證且在互動式桌面環境中執行：
google-lens login
若在無頭/雲端/CI 環境中，請透過環境變數傳遞工作階段狀態：
export LENS_STORAGE_STATE_JSON="<base64-or-raw-json-storage-state>"
隨附輔助指令碼
針對程式化工作流程與批次作業，請使用位於 scripts/ 目錄中的隨附指令碼。這些指令碼包含 PEP 723 內嵌依賴元資料。
單一圖片搜尋與篩選 (scripts/search_image.py)
搜尋圖片並內建價格、結果數量或模式篩選功能：
# 基本搜尋並輸出 JSON
python3 scripts/search_image.py "https://example.com/photo.jpg" --json
# 篩選視覺比對結果（例如最多 5 個結果）
python3 scripts/search_image.py "path/to/image.png" --max-results 5 --json
# 快速 OCR 擷取
python3 scripts/search_image.py "path/to/receipt.jpg" --ocr-only --json
批次圖片處理 (scripts/batch_search.py)
非同步處理目錄中的圖片或 URL 清單：
# 處理目錄中的所有圖片
python3 scripts/batch_search.py --dir ./images/ --output ./batch_results.json
# 從檔案處理 URL 清單
python3 scripts/batch_search.py --urls-file ./image_urls.txt --output ./batch_results.json --concurrency 3
解讀輸出
當使用 --json-output 時，JSON 負載遵循以下結構：
{
"query": "https://example.com/item.jpg",
"ocr_text": "從圖片偵測到的文字...",
"knowledge_graph": {
"title": "已識別物件 / 實體名稱",
"subtitle": "分類（例如 鞋類 / 植物）",
"description": "簡短的百科式描述",
"website": "https://..."
},
"visual_matches": [
{
"title": "產品標題",
"link": "https://store.com/item",
"source": "商店名稱",
"price": "$99.00",
"thumbnail": "https://..."
}
],
"detected_objects": [
{
"id": "item_1",
"bounding_box": {
"center_x": 0.5,
"center_y": 0.5,
"width": 0.3,
"height": 0.4
}
}
]
}
疑難排解與最佳做法
- 機器人防護 (HTTP 429 / CAPTCHA)：如果視覺比對請求受到速率限制，請切換至
--ocr-only（保證無 CAPTCHA），或透過google-lens login或LENS_STORAGE_STATE_JSON進行驗證。 - 本地圖片：本地檔案路徑（
.png、.jpg、.jpeg、.webp、.bmp、.gif）會自動上傳至 Google 的快速上傳端點。 - 無頭執行：搜尋預設以無頭模式執行。在除錯環境中，可傳遞
--no-headless以檢視瀏覽器。
如需完整的 CLI 標誌、設定參數與詳細的 JSON 綱要，請參閱 references/REFERENCE.md。