google-shopping-search

Google Shopping 搜索

通过 Frevana 搜索 Google Shopping 商品列表。

用途

此技能用于查找 Google Shopping 商品结果。

输入：

• q
• 可选的 google_domain
• 可选的 gl
• 可选的 hl
• 可选的 start
• 可选的 device
• 可选的 sort_by

输出：

• 已验证的 Google Shopping 商品结果 JSON 响应
• 每次成功运行时，都会将相同的已验证 JSON 保存到本地文件

此技能会验证响应是否为 JSON，将其保存到磁盘，并在标准输出中原样返回。除非用户明确要求转换，否则不要重写或调整返回的数据结构。

此技能的需求

• 用户提供的 q
• 可选的 google_domain
• 可选的 gl
• 可选的 hl
• 可选的 start
• 可选的 device
• 可选的 sort_by
• 环境变量中的 FREVANA_TOKEN，或本次运行中通过 --token 显式指定的覆盖值
• curl
• bash
• python3

执行顺序

按以下流程操作，让请求保持简单可靠：

1. 确认用户已提供 q 或等效的商品搜索查询。
2. 优先使用脚本，而不是临时编写 curl 命令。
3. 让脚本优先读取 FREVANA_TOKEN。
4. 在交互式 Shell 中，如果缺少 FREVANA_TOKEN，脚本可以提示用户输入。
5. 在非交互式或 Agent 工作流中，如果缺少令牌，则立即失败，并告知用户设置 FREVANA_TOKEN 或显式传入 --token。
6. 运行一次脚本。脚本会将已验证的 JSON 输出到标准输出，并将相同的 JSON 保存到文件。
7. 后续解析或总结时使用已保存的 JSON 文件，不要再次调用搜索 API。
8. 返回已验证的响应 JSON；如果用户不需要完整内容，则总结最相关的商品。

命令

基本商品搜索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds"

--query 可用作 --q 的别名。

按国家/地区、语言和 Google 域名搜索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --google-domain google.com \
  --gl US \
  --hl en

按分页、设备和排序方式搜索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --start 20 \
  --device mobile \
  --sort-by 1

将响应 JSON 保存到指定文件

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --gl US \
  --hl en \
  --output ./out/google-shopping-search-result.json

为本次运行覆盖令牌

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --token "your bearer token"

固定请求格式

脚本会发送以下格式的载荷，并省略未提供的可选字段：

{
  "q": "wireless earbuds",
  "google_domain": "google.com",
  "gl": "US",
  "hl": "en",
  "start": 20,
  "device": "mobile",
  "sort_by": "1"
}

只有 q 是必填项。用户未提供时，不要自行编造 google_domain、gl、hl、start、device 或 sort_by 的值。

响应格式

API 返回 Frevana JSON。此技能会验证响应是否为 JSON，并原样返回。

输出

• 成功：脚本会验证响应正文是否为 JSON，将其写入文件，将保存路径打印到标准错误，并将 JSON 打印到标准输出
• 默认文件路径：./out/google-shopping-search-<UTC timestamp>-<pid>.json
• 使用 --output 时：将相同的 JSON 写入指定文件路径，而不是默认路径
• 失败：脚本会打印响应正文或解析错误，并以非零状态码退出

注意事项

• 必须提供 --q 或 --query
• 不要为了保存和总结结果而运行两次脚本。脚本始终会保存与打印内容相同的 JSON。
• 只有当用户指定了类似 google.com 的 Google 域名时，才使用 --google-domain
• 用户要求指定国家或地区时，使用 --gl
• 用户要求指定语言时，使用 --hl
• 用户要求按结果偏移量分页时，使用 --start
• --device 仅限 desktop、mobile 或 tablet
• 用户要求按 Google Shopping 的排序方式排序时，价格从低到高使用 --sort-by 1，价格从高到低使用 --sort-by 2
• 如果缺少 curl，请停止并告知用户安装 curl
• 如果缺少 python3，请停止并告知用户安装 python3
• 不要向用户回显 Bearer 令牌
• 除非用户要求完整载荷，否则应总结用户实际关注的商品结果，而不是直接倾倒原始 JSON

示例提示

中文

• "搜索 Google Shopping 上的 wireless earbuds"
• "查一下 Google Shopping 里 q=running shoes，gl=US，hl=en"
• "Google Shopping 搜索 wireless earbuds，按价格从低到高排序，并保存原始 JSON"

English

• "搜索 Google Shopping 上的 wireless earbuds"
• "查询 Google Shopping 中 running shoes 的结果，使用 gl=US 和 hl=en"
• "搜索 Google Shopping 上的 wireless earbuds，按价格从低到高排序，并保存原始 JSON"