shop-app-research

Shop.app 研究

在 Shop.app 上搜索、浏览和分析商品、款式、店铺和评论。Shop.app 是 Shopify 的跨店购物／发现应用（不要与单个 Shopify 店面混淆）。所有数据均由 Crawlora API 返回为标准化 JSON，无需抓取 HTML。

何时使用此技能

• “在 Shop.app 上找 X”／“在 Shop.app 上搜索跑鞋。”
• “Shop.app 上 X 的价格范围是多少／有多少家店铺在售？”
• “查找这个 Shop.app 店铺”／“列出商家的 Shop.app 商品目录或系列。”
• “获取这款 Shop.app 商品或店铺的评论。”
• “获取这款 Shop.app 商品的款式／选项／库存情况。”
• 在 Shop.app 上进行跨店发现、市场概览或商家尽职调查。

设置（一次性）

• 获取免费的 Crawlora API 密钥（每月 2,000 个积分，无需银行卡）：https://crawlora.net。
• 运行辅助程序前，在环境中设置 CRAWLORA_API_KEY。
• 辅助程序会从环境中读取 CRAWLORA_API_KEY，并向 https://api.crawlora.net/api/v1 发送请求。密钥缺失或无效时会返回 401。

工作原理

1. 搜索／发现 — 使用 /shop-app/search（query，以及 deep_search、in_stock、on_sale、limit，最多为 50）按关键词查找候选商品。/shop-app/suggestions 会返回自动补全查询建议，/shop-app/categories 会列出公开商品类别，供你浏览而非搜索。
2. 市场概览 — /shop-app/analysis 执行相同的搜索，但会返回汇总概览（价格范围、货币、促销数量、折扣、热门店铺），而不是原始商品列表。无需自行翻页，即可用它回答“Shop.app 上 X 的价格范围是多少”。
3. 商品详情 — 使用 /shop-app/products/{id} 获取标准化商品详情（添加 variant_id 可指定特定款式）。
4. 款式 — 使用 /shop-app/products/{id}/variant 获取与 selected_options 完全匹配的款式，或使用 /shop-app/products/{id}/variants 获取相邻款式，以比较选项和价格。
5. 相关商品和评论 — 使用 /shop-app/products/{id}/related 和 /shop-app/products/{id}/reviews。
6. 解析店铺 — /shop-app/products/{id}/shop 可查找商品所属的商家；/shop-app/shops/{handle} 可直接获取商家资料，/shop-app/shops/{handle}/locations 可列出零售地点。
7. 浏览店铺的商品目录 — 使用 /shop-app/shops/{handle}/products（可通过 sort_by 排序），或使用 /shop-app/shops/{handle}/collections/{collection_id}/products 查看某个系列；/shop-app/shops/{handle}/typeahead 可在单个店铺内搜索；/shop-app/shops/{handle}/reviews 可获取商家评论。

完整的端点列表、方法和参数：reference/endpoints.md。

调用 API

# Search Shop.app (GET, key=value params):
scripts/crawlora.sh /shop-app/search query="running shoes" in_stock=true | jq '.'

# Product detail:
scripts/crawlora.sh /shop-app/products/12345 | jq '.data'

# Browse a shop's catalog, sorted low-to-high:
scripts/crawlora.sh /shop-app/shops/some-shop-handle/products sort_by=PRICE_LOW_TO_HIGH | jq '.'

所有请求均使用 scripts/crawlora.sh；它会避免将 API 密钥暴露在命令行参数中。

端点参考

请参阅 reference/endpoints.md，了解此技能使用的所有 Shop.app 端点（方法、路径、参数和说明）。

示例

• 购买前查看市场概览： 使用 /shop-app/analysis，设置 query="wireless earbuds" 和 on_sale=true，查看当前价格范围、折扣以及销售折扣商品的热门店铺。
• 商家尽职调查： 使用 /shop-app/shops/{handle} 和 /shop-app/shops/{handle}/reviews，在推荐商家前总结其 Shop.app 资料和近期评论。
• 系列审查： 使用 /shop-app/shops/{handle}/products（通过 limit 翻页），或使用特定的 /shop-app/shops/{handle}/collections/{collection_id}/products，列出商家的商品目录及价格，并标记高于／低于阈值的商品。

说明和限制

• **积分 / 成功后付费：**仅在返回 2xx 时计费；免费套餐每月提供 2,000 个积分。 在 https://crawlora.net 获取密钥。
• 仅限公开数据——Shop.app 上公开的商品 / 商店页面；请遵守 Shop.app 的条款。
• **安全性：**密钥仅存放在 CRAWLORA_API_KEY 中——切勿硬编码、放入查询参数或提交。
• 结果数量有限，且不支持基于偏移量的分页——search、analysis、related、 reviews、shop/collection products 和 suggestions/typeahead 的结果都会受 limit 限制（各端点的上限不同，变体的上限为 20 到 100）。
• selected_options 是 JSON 对象，不是扁平的 key=value 键值对——请将其作为 JSON 字符串传入（例如 selected_options='{"Color":"Black"}'），或改用重复的 option.Name=value / option[Name]=value 筛选条件。
• 商店 / 商品集合商品列表的 sort_by 仅接受 MOST_SALES、 PRICE_LOW_TO_HIGH、PRICE_HIGH_TO_LOW 或 RELEVANCE。