Shopping Expert
Find and compare products online and locally with smart recommendations.
Quick Start
Find products online:
CODEBLOCK0
Search with budget constraint:
CODEBLOCK1
Find local stores:
CODEBLOCK2
Hybrid search (online + local):
CODEBLOCK3
Search US stores:
CODEBLOCK4
Search Modes
- - online: E-commerce sites (Amazon, Walmart, etc.) via Google Shopping
- local: Nearby stores via Google Places API
- hybrid: Both online and local results merged and ranked
- auto: Intelligent mode selection based on query (default)
Parameters
- -
query: Product search query (required) - INLINECODE1 : Search mode (online|local|hybrid|auto, default: auto)
- INLINECODE2 : "low/medium/high" or "€X"/"$X" amount (default: medium)
- INLINECODE3 : Location for local/hybrid searches
- INLINECODE4 : Comma-separated (e.g., "brand:Sony, wireless, black")
- INLINECODE5 : Maximum products to return (default: 5, max: 20)
- INLINECODE6 : Sort order (relevance|price-low|price-high|rating)
- INLINECODE7 : text|json (default: text)
- INLINECODE8 : Country code for search (default: de). Use "us" for US, "uk" for UK, etc.
Budget Levels
- - low: Under €50
- medium: €50-€150
- high: Over €150
- exact: "€75", "€250" (or "$X" for US searches)
Output Format
Default (text): Markdown table with product details, ratings, availability, and buy links
JSON: Structured data with all product metadata, scores, and links
Scoring Algorithm
Products are ranked using weighted scoring:
- - Price match (30%): Within budget range gets full points
- Rating (25%): Higher ratings score better
- Availability (20%): In stock > limited > out of stock
- Review count (15%): More reviews = more trustworthy
- Shipping/Distance (10%): Free shipping or nearby stores score higher
- Preference match (bonus): Keywords in product description
API Keys Required
- - SERPAPIAPIKEY: Required for online shopping (all modes except local-only)
- GOOGLEPLACESAPI_KEY: Only required for local and hybrid modes
Limitations
- - API limits: SerpAPI and Google Places have usage quotas
- Real-time data: Prices and availability may change
- Stock accuracy: Online availability reflects last API update
- Local inventory: Store stock not guaranteed via Places API
Error Handling
- - Invalid query → Returns error with suggestions
- No results found → Relaxes filters and retries
- API failures → Retry with exponential backoff (3 attempts)
- Missing API keys → Clear error message with setup instructions
购物专家
通过智能推荐在线和本地查找并比较产品。
快速开始
在线查找产品：
bash
uv run {baseDir}/scripts/shop.py 咖啡机 \
--budget medium \
--max-results 5
带预算限制搜索：
bash
uv run {baseDir}/scripts/shop.py 跑鞋 \
--budget $100 \
--preferences 耐克, 缓震, 防水
查找本地商店：
bash
uv run {baseDir}/scripts/shop.py 有机蔬菜 \
--mode local \
--location 德国汉堡
混合搜索（在线+本地）：
bash
uv run {baseDir}/scripts/shop.py 单反相机 \
--mode hybrid \
--location 德国慕尼黑 \
--budget high \
--preferences 佳能, 4K视频
搜索美国商店：
bash
uv run {baseDir}/scripts/shop.py 跑鞋 \
--country us \
--budget $100
搜索模式
- - online：通过Google购物搜索电商网站（亚马逊、沃尔玛等）
- local：通过Google Places API搜索附近商店
- hybrid：合并并排序在线和本地结果
- auto：根据查询智能选择模式（默认）
参数
- - query：产品搜索查询（必填）
- --mode：搜索模式（online|local|hybrid|auto，默认：auto）
- --budget：low/medium/high或€X/$X金额（默认：medium）
- --location：本地/混合搜索的位置
- --preferences：逗号分隔（例如：品牌:索尼, 无线, 黑色）
- --max-results：返回的最大产品数（默认：5，最大：20）
- --sort-by：排序方式（relevance|price-low|price-high|rating）
- --output：text|json（默认：text）
- --country：搜索的国家代码（默认：de）。美国用us，英国用uk等
预算级别
- - low：50欧元以下
- medium：50-150欧元
- high：150欧元以上
- exact：€75、€250（美国搜索用$X）
输出格式
默认（文本）：包含产品详情、评分、库存和购买链接的Markdown表格
JSON：包含所有产品元数据、评分和链接的结构化数据
评分算法
产品使用加权评分进行排名：
- - 价格匹配（30%）：在预算范围内得满分
- 评分（25%）：评分越高得分越好
- 库存（20%）：有货 > 限量 > 缺货
- 评论数量（15%）：评论越多越可信
- 运费/距离（10%）：免运费或附近商店得分更高
- 偏好匹配（加分）：产品描述中的关键词
所需API密钥
- - SERPAPIAPIKEY：在线购物必需（除仅本地模式外的所有模式）
- GOOGLEPLACESAPI_KEY：仅本地和混合模式需要
限制
- - API限制：SerpAPI和Google Places有使用配额
- 实时数据：价格和库存可能发生变化
- 库存准确性：在线库存反映上次API更新状态
- 本地库存：通过Places API无法保证商店库存
错误处理
- - 无效查询 → 返回错误并附带建议
- 未找到结果 → 放宽过滤器并重试
- API失败 → 使用指数退避重试（3次尝试）
- 缺少API密钥 → 清晰的错误信息及设置说明
