购物专家

通过智能推荐在线及本地查找和比较产品。

快速开始

在线查找产品：

uv run {baseDir}/scripts/shop.py "coffee maker" \
  --budget medium \
  --max-results 5

按预算限制搜索：

uv run {baseDir}/scripts/shop.py "running shoes" \
  --budget "$100" \
  --preferences "Nike, cushioned, waterproof"

查找本地商店：

uv run {baseDir}/scripts/shop.py "Bio Gemüse" \
  --mode local \
  --location "Hamburg, Germany"

混合搜索（在线 + 本地）：

uv run {baseDir}/scripts/shop.py "Spiegelreflexkamera" \
  --mode hybrid \
  --location "München, Germany" \
  --budget high \
  --preferences "Canon, 4K Video"

搜索美国商店：

uv run {baseDir}/scripts/shop.py "running shoes" \
  --country us \
  --budget "$100"

搜索模式

• 在线：通过谷歌购物搜索电商网站（亚马逊、沃尔玛等）
• 本地：通过谷歌地点API搜索附近商店
• 混合：合并并排序在线和本地结果
• 自动：基于查询智能选择模式（默认）

参数

• query：产品搜索查询（必需）
• --mode：搜索模式（在线|本地|混合|自动，默认：自动）
• --budget： "低/中/高" 或 "€X"/"$X" 具体金额 (默认值：中)
• --location： 用于本地/混合搜索的位置
• --preferences： 以逗号分隔 (例如："品牌:索尼, 无线, 黑色")
• --max-results： 返回产品的最大数量 (默认值：5， 最大值：20)
• --sort-by： 排序方式 (相关性|价格从低到高|价格从高到低|评分)
• --output： text|json (默认值：text)
• --country： 搜索的国家代码 (默认值：de)。使用 "us" 代表美国，"uk" 代表英国等。

预算等级

• 低： 低于 €50
• 中： €50 - €150
• 高： 高于 €150
• 精确金额： "€75", "€250" (或为美国搜索使用 "$X")

输出格式

默认（文本）：包含产品详情、评分、可用性和购买链接的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 密钥 → 显示明确的错误信息和设置说明