使用 Apify Actors 构建品牌声誉监控管线：AAS 技能实战指南

【免费下载链接】agentic-awesome-skillsAAS 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

本篇技术指南以 AAS（agentic-awesome-skills）仓库中的apify-brand-reputation-monitoring技能为主体，讲解如何基于 Apify 云 Actor 自动采集 Google Maps、Booking.com、TripAdvisor、Facebook、Instagram、YouTube、TikTok 等平台的评论、评分与品牌提及，并导出为 CSV/JSON 或直接在对话中呈现快速结论。读完本文，你将掌握 Actor 的选型方法、基于mcpc的动态 Schema 获取、以及配套run_actor.js脚本的完整调用链与参数含义，可直接落地为可复用的品牌舆情监控工作流。

技能定位：Agent 自主调用的品牌声誉监控能力

apify-brand-reputation-monitoring是 AAS 生态中面向自动化场景（category: "automation"）的社区来源技能，在 data/catalog.json 中被标记为risk: critical，并挂载了apify、brand、reputation、monitoring等标签，触发器覆盖reviews、ratings、mentions、scrape、actors等关键词——这意味着当 Agent 收到"监控品牌评论 / 抓取评分 / 追踪提及"类任务时，会自动路由到该技能。

技能的核心思路非常朴素：你不需要自己写爬虫。Apify 生态中已经存在大量针对单一平台的成熟 Actor（云托管爬虫），本技能负责的只是"选对 Actor → 取回其输入 Schema → 按用户偏好运行 → 汇总结果"这条编排链路。其工作流在 SKILL.md 中被固化为 5 步检查清单：

Task Progress: - [ ] Step 1: Determine data source (select Actor) - [ ] Step 2: Fetch Actor schema via mcpc - [ ] Step 3: Ask user preferences (format, filename) - [ ] Step 4: Run the monitoring script - [ ] Step 5: Summarize results

适用场景（When to Use）

该技能专门服务于以下三类任务形态：

• 需要在社交平台、旅游平台或地图平台上监控评论、评分或品牌提及；
• 任务本质是"选择并运行一个 Apify Actor"来完成品牌情感或声誉追踪；
• 需要导出的监控结果文件以及一份声誉信号摘要。

反过来，它不适用于与上述范围无关的通用爬取需求——技能自身也明确要求：仅在任务与上述范围精确匹配时使用。

前置条件（Prerequisites）

运行本技能前需要准备三样东西，其中.env的检查不需要预先进行（脚本会在运行时自行校验并给出友好报错）：

1. .env文件，内含APIFY_TOKEN（Apify API 令牌）；
2. Node.js 20.6+——这个版本要求非常具体：只有 20.6 及以上才原生支持node --env-file=.env加载环境变量，这正是脚本的运行方式；
3. mcpcCLI 工具：npm install -g @apify/mcpc——用于在运行前动态拉取 Actor 的输入 Schema。

Step 1：确定数据源（Actor 选型）

这是整个流程的决策核心。技能内置了一张覆盖 4 类平台的 Actor 对照表，按"用户需求 → Actor ID → 适用场景"组织。选择时只需匹配"我要监控哪个平台、什么类型的信号"即可：

选型经验：跨平台评论对比（如连锁品牌在多平台的口碑）时优先选各平台"评论专用"Actor；需要结构化字段全量导出时，优先选带export语义的 Actor；仅需观测单点信号（如 Instagram 某话题热度）则选对应平台的轻量 Actor 即可。

Step 2：通过 mcpc 动态获取 Actor Schema

选中 Actor 后，不要凭记忆猜输入参数——不同 Actor 的输入结构差异很大（Google 商家需要searchStringsArray+locationQuery，Booking 需要酒店 URL 列表，TikTok 需要用户名等）。技能通过 Apify 官方 MCP 端点动态拉取：

export $(grep APIFY_TOKEN .env | xargs) && mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call fetch-actor-details actor:="ACTOR_ID" | jq -r ".content"

将ACTOR_ID替换为 Step 1 选定的 Actor（例如compass/crawler-google-places）。该命令会依次完成：从.env导出令牌 → 通过mcpc调用 Apify MCP 的fetch-actor-details工具 → 用jq提取返回内容。返回结果包括：

• Actor 的描述与 README；
• 必填与可选输入参数（即后续--inputJSON 的依据）；
• 输出字段（若 Actor 提供）。

拿到 Schema 后，--input参数就有了事实依据，而不是凭空构造 JSON。

Step 3：确认用户偏好

在真正运行前，必须与用户确认两个问题，避免产出与预期不符：

1. 输出格式（三选一）：
   • Quick answer：仅在对话中展示前几条结果，不保存文件；
   • CSV：全字段导出，适合 Excel/BI 二次分析；
   • JSON：全量 JSON 导出，适合程序化处理。
2. 结果数量：根据用例性质决定抓取深度（例如品牌舆情快照 vs 季度深度报告，数据量需求完全不同）。

Step 4：运行监控脚本（三种模式）

技能的核心执行体是位于 reference/scripts/run_actor.js 的 Node 脚本，通过${CLAUDE_PLUGIN_ROOT}环境变量定位。三种模式对应三种命令形态：

Quick answer（对话内展示，不落盘）：

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \ --actor "ACTOR_ID" \ --input 'JSON_INPUT'

CSV 导出：

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \ --actor "ACTOR_ID" \ --input 'JSON_INPUT' \ --output YYYY-MM-DD_OUTPUT_FILE.csv \ --format csv

JSON 导出：

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \ --actor "ACTOR_ID" \ --input 'JSON_INPUT' \ --output YYYY-MM-DD_OUTPUT_FILE.json \ --format json

从源码看脚本的完整参数契约

run_actor.js基于 Node 原生node:util的parseArgs解析参数，其完整参数表（与脚本--help输出一致）如下：

一个值得注意的实现细节：parseArgs配置中format、timeout、poll-interval都被声明为string类型，随后在parseCliArgs()返回值中通过parseInt(...)显式转为整数——这是为了让--help在没有令牌的环境下也能工作，同时保持参数校验的统一性。另外，脚本要求--actor与--input均为必填，缺失时直接打印帮助并exit(1)。

底层 API 调用链：从 Actor ID 到结果文件

脚本的main()流程清晰勾勒出一条完整的 Apify REST API 调用链（所有请求都携带自定义User-Agent：apify-agent-skills/apify-brand-reputation-monitoring-1.1.1，便于在 Apify 侧统计技能用量）：

1. startActor(token, actorId, inputJson)：将author/actor格式转换为 API 兼容的author~actor（actorId.replace('/', '~')），向POST https://api.apify.com/v2/acts/{author~actor}/runs提交输入 JSON，返回{ runId, defaultDatasetId }。若收到 HTTP 404 则判定"Actor 不存在"。
2. pollUntilComplete(token, runId, timeout, interval)：轮询GET https://api.apify.com/v2/actor-runs/{runId}，仅在状态变化时打印（避免刷屏），直到进入SUCCEEDED/FAILED/ABORTED/TIMED-OUT终态；超过--timeout秒后强制返回TIMED-OUT。
3. 分流输出：
   • 指定--output时调用downloadResults()：从GET https://api.apify.com/v2/datasets/{datasetId}/items?format=json拉取全部条目；JSON 模式美化缩进写入，CSV 模式以首条记录的键为表头逐行生成；
   • 未指定--output时调用displayQuickAnswer()：从同一数据集端点取数据，在对话中打印TOP 5结果（每字段截断到 100 字符），并输出console.apify.com/storage/datasets/{datasetId}的完整数据入口。

两个值得称道的工程细节：

• CSV 注入防护：csvCell()会检测以= + @ -开头的单元格并前置单引号，防止评论内容被解析为公式注入（spreadsheet injection）；
• 长文本截断：CSV 模式下字符串字段超过 200 字符截断为...，数组/对象字段自动JSON.stringify，兼顾可读性与 Excel 兼容性。

导出完成后，reportSummary()还会打印记录数与文件字节大小（JSON 按数组长度计数，CSV 按行数减表头计数）。

Step 5：汇总结果

任务收尾时，向用户报告以下声誉信号：

• 找到的评论/提及数量；
• 结果文件的位置与文件名；
• 数据中可用的关键字段（如评分、评论正文、作者、时间等）；
• 建议的后续动作（如情感分析、按评分过滤、跨平台对比）。

错误处理速查

技能在 SKILL.md 中给出了 5 类常见故障的处置方式，与脚本源码的报错路径一一对应：

使用边界与注意事项

• 仅当任务与技能描述的范围精确匹配时才使用（评论/评分/品牌提及监控），不要泛化到其他爬取需求；
• 输出结果不能替代环境专属的验证、测试或专家评审——抓取数据需结合业务上下文人工判断；
• 当必填输入、权限、安全边界或成功标准缺失时，停下来向用户澄清，而不是擅自假设。

深入阅读

• 技能主文档：SKILL.md
• 执行脚本（含完整参数与 API 调用链）：reference/scripts/run_actor.js
• 技能在目录中的元数据（分类/风险/标签/触发器）：data/catalog.json（检索apify-brand-reputation-monitoring）
• 同系列技能（共享同一套run_actor.js执行框架）：apify-audience-analysis、apify-competitor-intelligence、apify-content-analytics、apify-lead-generation、apify-market-research、apify-trend-analysis、apify-ultimate-scraper等，均位于 plugins/agentic-awesome-skills-claude/skills 目录下

【免费下载链接】agentic-awesome-skillsAAS 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