• AI 技能
  • AI 插件
  • 人工智能

【免费下载链接】agentic-awesome-skills

AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.

项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills
点击查看 免费下载

本文以 Agentic Awesome Skills 仓库中的 apify-ecommerce 技能为主体,系统讲解如何利用 Apify 的 E-commerce Scraping Tool,从 Amazon、Walmart、IKEA 等 20+ 电商平台提取商品、价格、评论和卖家数据,并深入剖析其底层 run_actor.js 执行脚本的实现原理。

apify-ecommerce 是 Agentic Awesome Skills 项目(AAS Core)中一个风险等级为 critical 的社区来源技能,其功能定义与分类元数据均收录在 data/catalog.json 中(category: automation,tags 为 apify、ecommerce)。该技能的核心能力是:通过一个标准化的 CLI 脚本调用 Apify 平台上的 apify/e-commerce-scraping-tool Actor,把"电商数据采集"这一复杂任务封装成三个可复用的工作流——商品与价格监控、客户评论分析、卖家情报挖掘。无论你是做价格监测、MAP(最低广告价)合规检查、竞品对比,还是品牌保护与渠道管理,都可以直接套用本文给出的配置模板与命令,几分钟内跑通第一条数据管线。


一、技能定位与适用场景

该技能的官方描述(见 SKILL.md 的 frontmatter)是:

Extract product data, prices, reviews, and seller information from any e-commerce platform using Apify's E-commerce Scraping Tool.

结合其"何时使用"(When to Use)说明,典型场景包括:

  • 需要来自电商站点的商品、定价、库存、评论或卖家数据;
  • 任务涉及价格监控、竞品商品对比、MAP 执行或评论分析;
  • 需要一套引导式工作流来提取市场数据并汇总发现。

技能按用户需求把任务拆解为三条工作流,选择依据如下表:

用户需求工作流最佳适用
跟踪价格、对比商品工作流 1:商品与定价(Products & Pricing)价格监控、MAP 合规、竞品分析;可附加 AI 摘要生成洞察
分析评论(情感或质量)工作流 2:评论(Reviews)品牌感知、客户情感、质量问题、缺陷模式
跨店铺寻找卖家工作流 3:卖家(Sellers)未授权经销商、通过 Google Shopping 进行供应商发现

技能还内建了进度追踪清单,供 Agent 在执行时逐项勾选:

Task Progress:
- [ ] Step 1: Select workflow and determine data source
- [ ] Step 2: Configure Actor input
- [ ] Step 3: Ask user preferences (format, filename)
- [ ] Step 4: Run the extraction script
- [ ] Step 5: Summarize results

二、环境前置条件

在运行任何提取任务之前,需要准备:

  • .env 文件:包含 APIFY_TOKEN,存放路径为 ~/.claude/.env;
  • Node.js 20.6+:脚本依赖原生 --env-file 参数从环境文件加载令牌。

从 run_actor.js 的源码可以看到,脚本启动时会读取 process.env.APIFY_TOKEN,若缺失会直接报错并退出,并提示前往 Apify 控制台 https://console.apify.com/account/integrations 获取令牌。因此令牌缺失是最常见的首个失败点,建议在跑任务前先确认环境变量可被 Node 正确注入。


三、工作流 1:商品与价格提取

适用场景:提取商品数据、价格与库存状态;跟踪竞品价格、检测 MAP 违规、商品对标或市场调研。

目标角色:定价分析师、产品经理、市场研究员。

3.1 三种输入方式

输入类型字段说明
商品 URLdetailsUrls商品详情页直链(建议使用对象格式)
分类 URLlistingUrls分类页 / 搜索结果页 URL
关键词搜索keyword + marketplaces在所选市场中的关键词搜索

3.2 配置示例

示例 A:直接指定商品 URL

{
  "detailsUrls": [
    {"url": "https://www.amazon.com/dp/B09V3KXJPB"},
    {"url": "https://www.walmart.com/ip/123456789"}
  ],
  "additionalProperties": true
}

示例 B:关键词搜索

{
  "keyword": "Samsung Galaxy S24",
  "marketplaces": ["www.amazon.com", "www.walmart.com"],
  "additionalProperties": true,
  "maxProductResults": 50
}

其中 maxProductResults 用于限制返回商品数量,additionalProperties: true 会额外返回卖家与库存等附加信息(详见下文"输出字段")。

3.3 可选:AI 摘要

在输入中追加以下字段,可让 Actor 生成 AI 洞察:

字段说明
fieldsToAnalyze需要分析的数据点,如 ["name", "offers", "brand", "description"]
customPrompt自定义分析指令

带 AI 摘要的完整示例:

{
  "keyword": "robot vacuum",
  "marketplaces": ["www.amazon.com"],
  "maxProductResults": 50,
  "additionalProperties": true,
  "fieldsToAnalyze": ["name", "offers", "brand"],
  "customPrompt": "Summarize price range and identify top brands"
}

3.4 输出字段说明

  • name —— 商品名称
  • url —— 商品 URL
  • offers.price —— 当前价格
  • offers.priceCurrency —— 货币代码(可能因卖家区域而异)
  • brand.slogan —— 品牌名(嵌套在对象中)
  • image —— 商品图片 URL
  • 当 additionalProperties: true 时,还会包含额外的卖家 / 库存信息

注意:即使是美国区的搜索,结果中的货币也可能不一致——因为价格反映的是不同卖家所在区域。做跨区价格对比时,建议在后续分析中按 offers.priceCurrency 归一化处理。


四、工作流 2:客户评论提取

适用场景:提取评论用于情感分析、品牌感知监控或质量问题检测。

目标角色:品牌经理、客户体验团队、QA 团队、产品经理。

4.1 输入选项

输入类型字段说明
商品 URLreviewListingUrls要提取评论的商品页
关键词搜索keywordReviews + marketplacesReviews按关键词搜索商品评论

4.2 配置示例

示例 A:从商品页提取评论

{
  "reviewListingUrls": [
    {"url": "https://www.amazon.com/dp/B09V3KXJPB"}
  ],
  "sortReview": "Most recent",
  "additionalReviewProperties": true,
  "maxReviewResults": 500
}

示例 B:关键词搜索评论

{
  "keywordReviews": "wireless earbuds",
  "marketplacesReviews": ["www.amazon.com"],
  "sortReview": "Most recent",
  "additionalReviewProperties": true,
  "maxReviewResults": 200
}

4.3 排序选项

  • Most recent —— 最新评论优先(推荐)
  • Most relevant —— 平台默认相关性排序
  • Most helpful —— 最高投票评论
  • Highest rated —— 5 星评论优先
  • Lowest rated —— 1 星评论优先

注意:sortReview: "Lowest rated" 在某些市场可能无法稳定生效。若要做质量问题分析,建议采集大样本,在后处理阶段按评分自行过滤,而不是依赖排序选项。

4.4 质量分析技巧

  • 设置较高的 maxReviewResults 以保证统计显著性;
  • 关注高频关键词,如 "broke"、"defect"、"quality"、"returned";
  • 若排序不如预期,按评分过滤结果;
  • 与竞品商品交叉对比,用于基准评测。

五、工作流 3:卖家情报

适用场景:跨店铺寻找卖家、发现未授权经销商、评估供应商选项。

目标角色:品牌保护团队、采购、供应链经理。

注意:该工作流通过 Google Shopping 跨店铺寻找卖家;直接使用卖家主页 URL 的方式并不可靠。

5.1 输入配置示例

{
  "googleShoppingSearchKeyword": "Nike Air Max 90",
  "scrapeSellersFromGoogleShopping": true,
  "countryCode": "us",
  "maxGoogleShoppingSellersPerProduct": 20,
  "maxGoogleShoppingResults": 100
}

5.2 配置项说明

字段说明
googleShoppingSearchKeyword要搜索的商品名称
scrapeSellersFromGoogleShopping设为 true 以提取卖家
scrapeProductsFromGoogleShopping设为 true 以同时提取商品详情
countryCode目标国家代码(如 us、uk、de)
maxGoogleShoppingSellersPerProduct每个商品最多返回的卖家数
maxGoogleShoppingResults总结果数上限

六、支持的市场平台清单

该技能覆盖的市场范围非常广,选择 marketplaces 时必须与下述列表完全一致(技能的错误处理表中专门列出了 Invalid marketplace 场景)。

Amazon(20+ 区域站点)

www.amazon.com、www.amazon.co.uk、www.amazon.de、www.amazon.fr、www.amazon.it、www.amazon.es、www.amazon.ca、www.amazon.com.au、www.amazon.co.jp、www.amazon.in、www.amazon.com.br、www.amazon.com.mx、www.amazon.nl、www.amazon.pl、www.amazon.se、www.amazon.ae、www.amazon.sa、www.amazon.sg、www.amazon.com.tr、www.amazon.eg

美国主要零售商

www.walmart.com、www.costco.com、www.costco.ca、www.homedepot.com

欧洲零售商

allegro.pl、allegro.cz、allegro.sk、www.alza.cz、www.alza.sk、www.alza.de、www.alza.at、www.alza.hu、www.kaufland.de、www.kaufland.pl、www.kaufland.cz、www.kaufland.sk、www.kaufland.at、www.kaufland.fr、www.kaufland.it、www.cdiscount.com

IKEA(40+ 国家 / 语言组合)

支持所有主要的 IKEA 区域站点及多种语言选项。

Google Shopping

用于跨店铺的卖家发现。


七、运行提取:从命令到源码实现

7.1 Step 1:设置技能路径

SKILL_PATH=~/.claude/skills/apify-ecommerce

7.2 Step 2:运行脚本

快速问答模式(直接在对话中展示结果,不落盘):

node --env-file=~/.claude/.env $SKILL_PATH/reference/scripts/run_actor.js \
  --actor "apify/e-commerce-scraping-tool" \
  --input 'JSON_INPUT'

CSV 导出:

node --env-file=~/.claude/.env $SKILL_PATH/reference/scripts/run_actor.js \
  --actor "apify/e-commerce-scraping-tool" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_filename.csv \
  --format csv

JSON 导出:

node --env-file=~/.claude/.env $SKILL_PATH/reference/scripts/run_actor.js \
  --actor "apify/e-commerce-scraping-tool" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_filename.json \
  --format json

7.3 底层执行脚本剖析:run_actor.js

脚本本体位于 reference/scripts/run_actor.js,依赖声明仅在 reference/scripts/package.json 中(仅需 "type": "module",无第三方依赖,直接使用 Node 原生 fetch 与 parseArgs)。其执行链路可分四段:

① 参数解析(L20-L58)

使用 Node 内置的 node:util 的 parseArgs,支持的完整参数如下:

参数短别名默认值说明
--actor-a必填Actor ID,如 apify/e-commerce-scraping-tool
--input-i必填以 JSON 字符串形式传入的 Actor 输入
--output-o无输出文件路径;不传则进入快速问答模式
--format-fcsv输出格式:csv 或 json
--timeout-t600最长等待秒数(对应文档中 Timeout 错误的处理手段)
--poll-interval—5状态轮询间隔(秒)
--help-h—打印帮助并退出

② 启动 Actor 运行(L102-L140)

  • 将 author/actor 格式转换为 Apify API 所需的 author~actor 格式(actorId.replace('/', '~'));
  • 向 https://api.apify.com/v2/acts/{author~actor}/runs 发起 POST,在 query 中携带 token;
  • 对 input 做 JSON 解析校验,非法 JSON 会直接报错退出;
  • 返回 runId 与 defaultDatasetId,后者用于后续拉取结果。

③ 轮询运行状态(L143-L177)

  • 每 poll-interval 秒查询一次 https://api.apify.com/v2/actor-runs/{runId};
  • 只在状态变化时打印 Status: xxx,避免刷屏;
  • 终止状态包括 SUCCEEDED / FAILED / ABORTED / TIMED-OUT;
  • 超过 timeout 秒仍未结束则返回 TIMED-OUT——这正是文档错误表中"Timeout 时减少 maxProductResults 或增大 --timeout"建议的代码依据。

④ 结果导出与摘要(L187-L315)

  • JSON 模式:把整个数据集以 JSON.stringify(data, null, 2) 美化写盘;
  • CSV 模式:以首行记录的键作为表头,并对字段做三重保护处理(见 csvCell):
    • 长度超过 200 字符的字符串会被截断为 200 字符并追加 ...;
    • 数组 / 对象字段被 JSON.stringify 序列化为字符串;
    • 以 =、+、@、- 等开头且前导为空白字符的值会加前缀 ',用于防御 CSV 公式注入(CSV injection);
  • 快速问答模式:拉取数据后在终端打印 TOP 5 RESULTS (of N total),单值超过 100 字符会截断展示,并输出 Apify 控制台数据集地址供查看完整数据。

脚本还通过自定义 User-Agent: apify-agent-skills/apify-ecommerce-1.0.0 在 Apify 分析中标记技能使用来源(见 L16-L17)。

7.4 Step 3:汇总结果

报告应包括:

  • 提取到的条目数量;
  • 导出文件位置(若已导出);
  • 基于工作流的关键洞察:
    • 商品:价格区间、离群值、MAP 违规;
    • 评论:平均评分、情感趋势、质量问题;
    • 卖家:卖家数量、发现的未授权卖家。

八、错误处理速查表

错误解决方案
APIFY_TOKEN not found确保 ~/.claude/.env 中包含 APIFY_TOKEN=your_token
Actor not found核对 Actor ID:apify/e-commerce-scraping-tool
Run FAILED查看错误输出中的 Apify 控制台链接
Timeout减少 maxProductResults 或增大 --timeout
No results确认 URL 有效且可访问
Invalid marketplace核对市场值是否与支持列表完全一致

从源码看,前三类错误都有明确的代码出口:令牌缺失在 main() 直接退出;Actor not found 对应 startActor 中对 HTTP 404 的拦截(L124-L127);Run FAILED 则由 pollUntilComplete 返回非 SUCCEEDED 状态时触发,并打印 https://console.apify.com/actors/runs/{runId} 便于人工排查。


九、使用边界与限制

  • 仅当任务与上述范围明确匹配时才使用该技能;
  • 不要把输出当作环境特定验证、测试或专家评审的替代品;
  • 若必需的输入、权限、安全边界或成功标准缺失,应停下并向用户澄清。

另外需要注意,技能在 data/catalog.json 中标记的风险等级为 critical——这提示该技能会发起真实的外部网络抓取请求并产生 Apify 平台消耗,在使用时应对目标站点合规性、抓取频率与成本预算保持必要审慎。若需要覆盖商品页之外更广义的抓取能力,仓库还提供了 apify-actor-development、apify-ultimate-scraper 等同族技能(位于 plugins/agentic-awesome-skills-claude/skills/ 下),可按需组合使用。


十、小结

apify-ecommerce 技能把"从任意电商平台抓取结构化数据"压缩为选工作流 → 填 JSON 输入 → 跑一行 Node 命令 → 汇总洞察四步操作。它的价值在于:

  1. 输入标准化:三条工作流各配完整的参数模板,覆盖商品、评论、卖家三类最常见需求;
  2. 输出可落地:原生支持快速问答、CSV、JSON 三种模式,CSV 导出自带注入防护与长字段截断;
  3. 源码透明可审计:整个执行脚本仅依赖 Node 内置模块,运行链路(启动 → 轮询 → 下载)清晰可读,便于二次定制。

对价格监控、竞品对标、MAP 合规、品牌保护等高频业务场景,直接复制本文的 JSON 模板与命令即可投入实战;遇到异常时,对照第八节错误速查表与源码中的退出分支即可快速定位问题。

  • AI 技能
  • AI 插件
  • 人工智能

【免费下载链接】agentic-awesome-skills

AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.

项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills
点击查看 免费下载
Logo

电商企业物流数字化转型必备!快递鸟 API 接口,72 小时快速完成物流系统集成。全流程实战1V1指导,营造开放的API技术生态圈。

更多推荐