介绍
# Shopping Expert
通过智能推荐在线查找和比较本地及线上产品。
## 快速开始
在线查找产品：
```bash uv run {baseDir}/scripts/shop.py "coffee maker" \ --budget medium \ --max-results 5 ```
带预算限制搜索：
```bash uv run {baseDir}/scripts/shop.py "running shoes" \ --budget "$100" \ --preferences "Nike, cushioned, waterproof" ```
查找本地商店：
```bash uv run {baseDir}/scripts/shop.py "Bio Gemüse" \ --mode local \ --location "Hamburg, Germany" ```
混合搜索（线上 + 本地）：
```bash uv run {baseDir}/scripts/shop.py "Spiegelreflexkamera" \ --mode hybrid \ --location "München, Germany" \ --budget high \ --preferences "Canon, 4K Video" ```
搜索美国商店：
```bash uv run {baseDir}/scripts/shop.py "running shoes" \ --country us \ --budget "$100" ```
## 搜索模式
- **online**：通过 Google Shopping 访问电商网站（Amazon、Walmart 等） - **local**：通过 Google Places API 访问附近商店 - **hybrid**：合并并排序线上和本地结果 - **auto**：基于查询的智能模式选择（默认）
## 参数
- `query`：产品搜索查询（必需） - `--mode`：搜索模式（online|local|hybrid|auto，默认：auto） - `--budget`：“low/medium/high”或“€X”/“$X”金额（默认：medium） - `--location`：本地/混合搜索的位置 - `--preferences`：逗号分隔（例如，“brand:Sony, wireless, black”） - `--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”）
## 输出格式
**默认（text）**：包含产品详情、评分、可用性和购买链接的 Markdown 表格
**JSON**：包含所有产品元数据、评分和链接的结构化数据
## 评分算法
产品使用加权评分进行排名： - **价格匹配（30%）**：在预算范围内得满分 - **评分（25%）**：评分越高得分越高 - **可用性（20%）**：有库存 > 库存有限 > 缺货 - **评论数（15%）**：评论越多 = 越可信 - **配送/距离（10%）**：免费配送或附近商店得分更高 - **偏好匹配（加分）**：产品描述中的关键词
## 所需 API 密钥
- **SERPAPI_API_KEY**：在线购物必需（除仅本地模式外的所有模式） - **GOOGLE_PLACES_API_KEY**：仅本地和混合模式需要
## 限制
- **API 限制**：SerpAPI 和 Google Places 有使用配额 - **实时数据**：价格和可用性可能会变化 - **库存准确性**：在线可用性反映的是最后一次 API 更新 - **本地库存**：商店库存无法通过 Places API 保证
## 错误处理
- 无效查询 → 返回带有建议的错误 - 未找到结果 → 放宽过滤条件并重试 - API 故障 → 使用指数退避重试（3 次尝试） - 缺少 API 密钥 → 返回带有设置说明的明确错误信息