Google Lens Agent 技能
此技能允许 AI Agent 执行反向图片搜索、提取光学字符识别（OCR）文本、检测视觉实体，并通过 Google Lens 查找购物匹配项和价格。
前提条件与安装
如果环境中尚未安装 google-lens，请安装该包并下载 stealth Chromium 浏览器二进制文件：
pip install google-lens-scraper
patchright install chromium
注意： 快速路径 OCR 模式（
--ocr-only）仅需 Python 包，无需下载 Chromium 二进制文件即可立即工作。
快速入门示例
1. 反向图片搜索与视觉智能（默认模式）
要查找匹配的产品、网络来源、归一化价格分析以及多模态属性分析：
google-lens search "<image-url-or-path>" --json-output
注意：默认情况下，如果环境中存在 GEMINI_API_KEY，google-lens search 会自动执行电商价格归一化（--enrich）和深度多模态属性分析（--analyze），并通过 Gemini 3.8 Flash 完成。
Agent 内上下文回退策略：如果
results.analysis为null（因为主机环境中未配置GEMINI_API_KEY），你（AI Agent） 应在自己的对话上下文中直接检查查询图片和返回的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 与对象检测（亚秒级，无验证码）
用于从图片中提取文本或边界框（使用 Chromium Protobuf 端点，零浏览器开销）：
google-lens search "<image-url-or-path>" --ocr-only --json-output
4. 电子商务与转售套利智能（专业版）
用于解析简洁的规范 URL、归一化的价格范围（最低/最高/平均），并识别最低价认证卖家（"最佳交易"）：
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. 许可证激活与设置（专业版）
专业版功能（市场价格智能、简洁 URL、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 / 验证码）：如果视觉匹配请求受到速率限制，请切换到
--ocr-only（保证无验证码）或通过google-lens login或LENS_STORAGE_STATE_JSON进行身份验证。 - 本地图片：本地文件路径（
.png,.jpg,.jpeg,.webp,.bmp,.gif）会自动上传到 Google 的快速上传端点。 - 无头执行：默认情况下搜索在无头模式下运行。在调试环境中，传递
--no-headless来检查浏览器。
有关完整的 CLI 标志、配置参数和详细的 JSON 模式，请参阅 references/REFERENCE.md。