apify-ecommerce

电子商务集群

通过将自然语言电子商务问题路由到合适的 Apify Actor，并通过 apify CLI 提供综合答案。

**CLI 规则：**始终传入 --user-agent apify-awesome-skills/apify-ecommerce、--json（或 datasets get-items 对应的 --format 标志）和 2>/dev/null。--user-agent 标志对遥测至关重要，切勿省略。

先决条件

（无需预先检查）

• Apify CLI v1.5.0+（npm install -g apify-cli）
• jq（建议用于快速提取和筛选；macOS 上运行 brew install jq，Linux 上运行 apt install jq）
• 通过以下任一方式进行身份验证：
  • apify login（OAuth，会打开浏览器）
  • APIFY_TOKEN 环境变量（例如 export APIFY_TOKEN=... 或 .env 文件）
  • 从 Apify Console → Settings → Integrations 获取令牌

验证身份验证：运行 apify info --user-agent apify-awesome-skills/apify-ecommerce，应显示用户名和 userId。

工作流

复制此清单并跟踪进度：

Task Progress:
- [ ] Step 1: Detect intent and select Actor
- [ ] Step 2: Fetch Actor schema
- [ ] Step 3: Ask user preferences (format, result count)
- [ ] Step 4: Run the Actor and fetch results
- [ ] Step 5: Analyze results and deliver synthesized answer

步骤 1：识别意图并选择 Actor

将用户的消息归类为某种意图，然后选择合适的 Actor。

意图信号：

用户消息中的信号	意图
价格、成本、最便宜、比较价格、定价	pricing
评论、评分、情感、星级、反馈	reviews
畅销品、热销、最受欢迎、趋势	bestsellers
卖家、供应商、转售商、谁在卖	sellers
所有商品、抓取商店、完整目录	store-scrape
什么平台、基于什么构建、技术栈、Shopify 还是 WooCommerce	tech-stack
SEO、商品列表质量、商品页面审查	seo-audit
竞争对手销售漏斗、竞争对手定价、转化要素	competitor
搜索意图、关键词意图、SERP 意图	search-intent
匹配商品、不同平台上的同一商品	product-matching
餐厅、外卖、DoorDash、UberEats、TheFork	food-delivery
丰富商店信息、商店元数据、商店列表	store-enrichment
活动、音乐会、门票、Eventbrite	events
房产、房地产、房屋列表、Realtor	real-estate
Facebook 广告、Meta 广告、广告库、竞争对手广告	ads-intelligence
分类信息、Craigslist、待售二手商品	classifieds
汽车、二手车、车辆、汽车行业、Webmotors	automotive
图钉、灵感、Pinterest 画板、视觉搜索、Pinterest 趋势	content-discovery
TikTok Shop、TikTok 商店、TikTok 创作者	tiktok-shop
待售网站、待售域名、Flippa	website-marketplace

如果检测到多个意图，请询问：“您想要 [意图 A] 还是 [意图 B]？”

**Actor 路由表——始终先尝试主要 Actor，只有在其失败或返回 0 条结果时才切换到备用 Actor。**主要 Actor（apify/e-commerce-scraping-tool）只要提供正确的输入模式，就能处理大多数意图：

• 有目标 URL（列表、个人资料或分类页面）→ detailsUrls / listingUrls。
• 有关键词/电商平台 → keyword + marketplaces（商品详情模式）。
• 广泛发现（竞争对手、搜索意图、分类信息、汽车、房地产、网站交易平台、活动） → 使用 searchEngineKeyword（搜索引擎模式），或根据是否有查询词或 URL 使用 keyword / detailsUrls。

例外情况——对于主要 Actor 确实无法处理的意图（数据源不同或需要专门分析），跳过主要 Actor，直接使用备用 Actor：tech-stack、seo-audit、store-enrichment、product-matching、ads-intelligence、content-discovery（Pinterest）和 tiktok-shop。将这些意图路由到主要 Actor 会浪费运行次数和额度。

Intent	Platform	Primary Actor	Fallback Actor
pricing	Amazon / Walmart / generic	apify/e-commerce-scraping-tool	—
pricing	eBay	apify/e-commerce-scraping-tool	ivanvs/ebay-scraper-pay-per-result
pricing	Etsy	apify/e-commerce-scraping-tool	epctex/etsy-scraper
pricing	Google Shopping	apify/e-commerce-scraping-tool	epctex/google-shopping-scraper
pricing	Facebook Marketplace	apify/e-commerce-scraping-tool	apify/facebook-marketplace-scraper
pricing	SHEIN	apify/e-commerce-scraping-tool	seamless_coffer/shein-product-scraper
pricing	Lazada	apify/e-commerce-scraping-tool	fatihtahta/lazada-scraper
pricing	Canadian Tire	apify/e-commerce-scraping-tool	azzouzana/canadiantire-ca-scraper
pricing	Tesco	apify/e-commerce-scraping-tool	radeance/tesco-scraper
pricing	Shopify	apify/e-commerce-scraping-tool	trovevault/shopify-products-scraper
pricing	WooCommerce	apify/e-commerce-scraping-tool	trovevault/woocommerce-products-scraper
reviews	Amazon / Walmart / generic	apify/e-commerce-scraping-tool	junglee/amazon-reviews-scraper
reviews	Trustpilot	apify/e-commerce-scraping-tool	casper11515/trustpilot-reviews-scraper
reviews	TheFork	apify/e-commerce-scraping-tool	jdtpnjtp/thefork-restaurant-scraper-advanced
bestsellers	Amazon	apify/e-commerce-scraping-tool	junglee/amazon-bestsellers
sellers	Amazon	apify/e-commerce-scraping-tool	junglee/amazon-seller-scraper
sellers	eBay	apify/e-commerce-scraping-tool	ivanvs/ebay-scraper-pay-per-result
store-scrape	Shopify	apify/e-commerce-scraping-tool	trovevault/shopify-products-scraper
store-scrape	WooCommerce	apify/e-commerce-scraping-tool	trovevault/woocommerce-products-scraper
store-scrape	Amazon	apify/e-commerce-scraping-tool	junglee/Amazon-crawler
store-scrape	Flippa	apify/e-commerce-scraping-tool	scraped/flippa-scraper
tech-stack	any	apify/e-commerce-scraping-tool	trovevault/e-commerce-tech-stack-detector
seo-audit	any	apify/e-commerce-scraping-tool	trovevault/product-listing-seo-auditor
competitor	any	apify/e-commerce-scraping-tool	trovevault/competitor-intelligence-scraper---funnel-pricing-conversion
search-intent	any	apify/e-commerce-scraping-tool	trovevault/ai-serp-intent-extractor---search-intent-classifier
product-matching	any	apify/e-commerce-scraping-tool	—
store-enrichment	any	apify/e-commerce-scraping-tool	trovevault/e-commerce-store-data-enricher
food-delivery	DoorDash	apify/e-commerce-scraping-tool	tri_angle/doordash-store-details-scraper
food-delivery	UberEats	apify/e-commerce-scraping-tool	e-commerce/ubereats-reviews-scraper
food-delivery	TheFork	apify/e-commerce-scraping-tool	jdtpnjtp/thefork-restaurant-scraper-advanced
ads-intelligence	Facebook / Meta	apify/e-commerce-scraping-tool	apify/facebook-ads-scraper
classifieds	Craigslist	apify/e-commerce-scraping-tool	ivanvs/craigslist-scraper-pay-per-result
automotive	Webmotors	apify/e-commerce-scraping-tool	stealth_mode/webmotors-auto-search-scraper
events	Eventbrite	apify/e-commerce-scraping-tool	aitorsm/eventbrite
real-estate	Realtor.com	apify/e-commerce-scraping-tool	powerai/realtor-properties-search-scraper
content-discovery	Pinterest	apify/e-commerce-scraping-tool	fatihtahta/pinterest-scraper-search
tiktok-shop	TikTok Shop	apify/e-commerce-scraping-tool	lemur/tiktok-shop-creators
website-marketplace	Flippa	apify/e-commerce-scraping-tool	scraped/flippa-scraper

升级处理——如果主选项和备用选项都失败或返回 0 条结果，请实时查找当前可用的替代方案，而不是猜测 ID：

# Find relevant, well-rated, pay-per-event Actors for the platform/intent.
# Keep the default relevance sort — `--sort-by popularity` surfaces generic
# big-name scrapers over the platform you actually asked for.
apify actors search "PLATFORM or INTENT keywords" \
  --pricing-model PAY_PER_EVENT --limit 10 --json \
  --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \
  | jq '[.items[]
      | select(.stats.totalUsers > 100 and .actorReviewRating > 4.5)
      | {id: (.username + "/" + .name), users: .stats.totalUsers,
         rating: (.actorReviewRating | (. * 100 | round / 100)),
         pricing: .currentPricingInfo.pricingModel}]'

选择排名最高的匹配项。运行之前，请确认它仅请求有限权限（查看 Actor 的 Store 页面／README——优先选择不需要完整账户访问权限的 Actor）。如果 PAY_PER_EVENT 筛选器没有返回结果，请移除 --pricing-model 标志并重新运行，同时保留 ≥100 位用户和 ≥4.5 评分的门槛。

步骤 2：获取 Actor 架构

获取 Actor 摘要、输入架构和 README：

# Summary (title, description, pricing, stats)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --json 2>/dev/null

# Input schema — use --input WITHOUT --json to get the clean schema directly.
# (Adding --json returns the full ~250 KB actor object instead, with the schema
#  buried as an escaped string under .taggedBuilds.latest.build.inputSchema.)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --input 2>/dev/null

# README (capabilities, examples, gotchas)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --readme 2>/dev/null

将 ACTOR_ID 替换为选定的 Actor（例如 apify/e-commerce-scraping-tool）。

主 Actor 输入速查表。 apify/e-commerce-scraping-tool 由模式驱动——根据意图选择字段（始终设置对应的 max…Results 上限）：

意图	最简输入
pricing（关键词）	{"keyword": "wireless earbuds", "marketplaces": ["www.amazon.com"], "maxProductResults": 50}
pricing（指定 URL）	{"detailsUrls": [{"url": "https://…"}], "maxProductResults": 50}
store-scrape（类别）	{"listingUrls": [{"url": "https://…/category"}], "maxProductResults": 500}
reviews	{"keywordReviews": "echo dot", "marketplacesReviews": ["www.amazon.com"], "sortReview": "Most recent", "maxReviewResults": 200}
sellers	{"sellerUrls": [{"url": "https://…"}], "maxSellerResults": 50}
pricing（Google Shopping）	{"searchEngineKeyword": "ps5", "countryCode": "us", "maxSearchEngineResults": 50}
food-delivery	{"keywordDelivery": "pizza", "marketplacesDelivery": ["www.doordash.com"], "addressDelivery": "New York, NY", "maxDeliveryResults": 50}

对于任何其他 Actor（或未列出的字段），请使用上方的 --input 命令获取架构。

步骤 3：询问用户偏好

运行之前，请询问：

1. 输出格式：
   • 快速回答（默认）——在聊天中综合回答，不保存文件
   • CSV ——完整导出并保存到磁盘
   • JSON ——完整导出并保存到磁盘
2. 结果数量——按意图建议默认值：

意图	默认值
pricing	50 个商品
reviews	200 条评论
bestsellers	100 个商品
sellers	50 个卖家
store-scrape	全部（不限数量）
food-delivery	50 家餐厅
其他所有意图	20–50

费用安全：始终在 Actor 输入中设置合理的结果数量上限。主 Actor 的上限字段因模式而异——分别为 maxProductResults、maxReviewResults、maxSellerResults、maxSearchEngineResults 或 maxDeliveryResults（没有统一的 maxResults）。对于备用 Actor，请使用架构中提供的字段（如 maxResults、resultsLimit、maxItems、maxCrawledPages 等）。除非用户明确要求更多，否则使用上述按意图设定的默认值。运行大型抓取（1000 条及以上结果）前，请提醒用户，因为这会消耗更多 Apify 积分。

Step 4：运行 Actor 并获取结果

分为两个步骤：运行 Actor（等待其完成），然后以所需格式获取数据集条目。

运行 Actor——以 JSON 格式返回运行元数据；提取 defaultDatasetId 供下一步使用：

apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ecommerce --json 2>/dev/null

从输出中使用 .id（运行 ID）、.status（应为 SUCCEEDED）和 .defaultDatasetId。

获取结果——根据用户的偏好选择对应的变体：

# Quick answer: total count + fields + top 5 in chat (no file)
apify datasets info DATASET_ID --json \
  --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \
  | jq '{itemCount, fields, consoleUrl}'
apify datasets get-items DATASET_ID --limit 5 \
  --user-agent apify-awesome-skills/apify-ecommerce --format json 2>/dev/null

# CSV file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ecommerce --format csv 2>/dev/null > YYYY-MM-DD_OUTPUT_FILE.csv

# JSON file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ecommerce --format json 2>/dev/null > YYYY-MM-DD_OUTPUT_FILE.json

其他 --format 选项：jsonl、xlsx、xml、rss、html。使用 --offset N 对大型数据集进行分页。

提示： 除了快速查看外，建议先将数据集保存到本地文件（使用 > file.json / > file.csv），然后从磁盘读取并进行后续分析。apify datasets get-items 始终通过网络传输数据，因此直接将其输出管道传给 jq 会在每次迭代时重新下载全部内容。

结合 jq 快速提取：

将 jq 作为 apify datasets get-items 的补充，而非替代：服务端的 --limit / --offset / --format 参数可以降低成本和带宽消耗。对样本条目或已保存到文件的数据使用 jq。

# Discover real field names from one sample item (Actor outputs vary —
# use this before composing further jq queries)
apify datasets get-items DATASET_ID --limit 1 --format json \
  --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \
  | jq '.[0]'

# Quick aggregation from a JSON file you already saved with the commands above
jq '[.[] | select(.rating != null and .rating >= 4.5)] | length' YYYY-MM-DD_OUTPUT_FILE.json

Step 5：分析结果并给出答案

运行完成后，给出直接、综合的答案，而不是直接倾倒数据：

• 定价： 价格范围、平均价格、最便宜的前 5 项及其 URL
• 评论： 平均评分、正面和负面主题各前 3 项、近期评论摘录
• 畅销商品： 按排名列出前 10 项，包含名称、价格、评分和 URL
• 卖家： 卖家总数、各卖家的价格范围、未经授权的卖家标记
• 店铺抓取： 商品总数、类别细分、价格范围、库存概况
• 技术栈： 检测到的平台、置信度、值得关注的插件
• 外卖配送： 餐厅数量、平均评分、价格档位细分
• 广告情报： 广告总数、活跃 / 不活跃广告数量细分、主要创意格式

错误处理

• 身份验证错误 → 运行 apify login，或设置 APIFY_TOKEN 环境变量
• Actor not found → 检查路由表中的 Actor ID 拼写
• 运行状态为 FAILED → 打开控制台 URL（运行元数据中的 .consoleUrl）查看日志
• 超时 / 运行时间过长 → 向 apify actors call 传入 --timeout <seconds>
• No results → 扩大关键词范围，切换到备用 Actor；如果两者都失败，则使用 升级处理 发现命令（位于 Step 1 下）
• proxy is required → 在 Actor 输入中添加 "proxy": {"useApifyProxy": true}
• Platform not detected → 默认使用 apify/e-commerce-scraping-tool，并设置 generic 意图

注意事项

• --input --json 是个陷阱。 它返回完整的约 250 KB Actor 对象，而非架构。使用 apify actors info ID --input --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null（不带 --json）获取干净的架构；只有确实需要 JSON 格式时，才查看 .taggedBuilds.latest.build.inputSchema。
• Primary Actor 没有 maxResults 字段。 它的上限因模式而异（maxProductResults、maxReviewResults、maxSellerResults、maxSearchEngineResults、maxDeliveryResults）。设置 maxResults 不会产生任何效果，运行会无限制地抓取。
• Primary 可通过选择正确的输入模式处理大多数意图（URL → detailsUrls/listingUrls；查询 → keyword 或 searchEngineKeyword），包括竞品、搜索意图、分类信息、汽车、房地产、网站市场和活动。它确实无法处理 tech-stack、seo-audit、store-enrichment、product-matching、ads-intelligence、content-discovery（Pinterest）或 tiktok-shop——这些应直接转到 Fallback。
• apify actors call -i 要求单行有效 JSON。 对于包含 URL 数组或引号的输入，请写入文件并传入 -i @input.json，不要直接内联——Shell 引号处理会悄悄破坏复杂输入。
• datasets get-items 始终通过网络流式传输。 将数据保存到文件一次（> file.json），然后对该文件运行 jq——不要反复将命令输出管道传给 jq，否则每次都会重新下载。
• apify actors search --sort-by popularity 会忽略相关性。 它会返回知名度最高的抓取器，而不管查询内容如何（搜索“etsy”会显示 Instagram/Google Maps Actor）。要发现升级方案，请保留默认的相关性排序，并根据 stats.totalUsers/actorReviewRating 进行筛选。
• marketplaces 的值是完整的域名 slug，例如 ["www.amazon.com", "www.ebay.com"]——不能使用 "amazon" 或显示名称。配送模式的限制更严格：marketplacesDelivery 仅接受 ["www.doordash.com", "www.instacart.com"]（不支持 UberEats——请改用 e-commerce/ubereats-reviews-scraper 备用方案）。猜测前，务必通过 --input 架构中的 enum 确认可接受的值。