apify-ai-search-visibility-tracker

AI 搜索可见度追踪器

涵盖 AI 可见度全生命周期的四个工作流：发现哪些提示词很重要 → 寻找引用机会 → 审查你的网站 → 持续追踪。

所有工作流都使用 apify/google-search-scraper 进行 AI 搜索。工作流 C 还会使用 apify/website-content-crawler。

**推荐流程：**运行工作流 A 发现提示词 → 运行工作流 B 寻找引用机会 → 运行工作流 C 审查你的网站 → 运行工作流 D 按计划追踪所有内容。

---

工作流 A — 竞争对手提示词发现

**目标：**找出哪些查询会让竞争对手出现在 AI 搜索答案中，以便了解哪些提示词值得监控。

收集以下输入

#	输入	备注
1	竞争对手域名	例如 brightdata.com、scraperapi.com
2	种子主题关键词	例如“网页抓取”“数据提取 API”
3	AI 来源	默认：全部六种（AI Overviews、AI Mode、ChatGPT、Perplexity、Copilot、Gemini）

工作流

1. 使用以下模板，根据种子关键词生成 15–30 个候选查询：

   • best [topic]、[topic] tools、how to [topic]、[topic] for [use case]
   • [topic] vs [competitor brand]、[competitor brand] alternative
   • [topic] API、[topic] pricing、[topic] tutorial

2. 对每个候选查询运行 apify/google-search-scraper。对每条结果，提取：

   • aiOverview.sources[]、aiMode.sources[]、chatGptAnswer.sources[]、perplexityAnswer.sources[]、copilotAnswer.sources[]、geminiAnswer.sources[]
   • 还要检查 answer_text / aiOverview.text 中是否提及竞争对手品牌名称（按单词边界匹配：\bBrand\b）

3. 对于竞争对手域名或品牌出现在其中的每个（查询，来源）组合，记录一次命中。

4. 输出按查询为主的表格，并按命中总数降序排列：

| Query | ChatGPT | Perplexity | AI Overviews | AI Mode | Copilot | Gemini | Total |
|-------|---------|------------|--------------|---------|---------|--------|-------|
| "best web scraping API" | ✓ | ✓ | — | ✓ | — | ✓ | 4 |
| "how to scrape Google" | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 6 |

5. 将排名靠前的 N 个查询（默认 10 个）整理为可直接粘贴到工作流 D 的 config.json prompts 中的列表。

---

工作流 B — 引用机会查找器

**目标：**针对目标主题，找出 AI 引擎最常引用的域名和内容类型，从而揭示适合发布或推介内容的平台。

收集以下输入

#	输入	备注
1	目标主题 / 行业	例如“网页抓取”“电商自动化”
2	种子查询	5–20 个覆盖主题范围的查询
3	AI 来源	默认：全部六种
4	深度抓取引用次数排名靠前的内容？	可选：使用 website-content-crawler 抓取引用次数排名前三的页面，以分析结构模式

工作流

1. 针对每个种子查询，在所选 AI 来源中运行 apify/google-search-scraper。

2. 收集所有结果中 sources[] 的每个 URL。规范化为可注册域名（blog.example.com → example.com）。

3. 汇总：

   • 按域名：统计引用次数，列出引用该域名的 AI 来源，以及触发该域名的查询
   • 按内容类型：根据 URL 路径模式推断（文档 → /docs/、/reference/；博客 → /blog/；新闻 → 已知新闻域名）

4. 按引用总数排序。输出：

Top-cited domains for "web scraping" (42 queries × 6 sources):
| Domain | Citations | AI Sources | Inferred type |
|--------|-----------|------------|--------------|
| docs.apify.com | 38 | ChatGPT, Perplexity, AI Mode | Documentation |
| scraperapi.com/blog | 21 | AI Overviews, Gemini | Long-form blog |

5. 如果启用了深度抓取：对每个域名下引用次数排名前三的 URL 运行 apify/website-content-crawler。从 Markdown 输出中提取：

   • 直接回答查询的首个标题
   • 前 500 个词中是否包含代码块
   • 字数
   • H2/H3 标题是否包含完整的查询短语

6. 总结模式：“该主题中的 AI 引擎偏好[长篇文档 / 简短的直接回答文章]。典型的引用页面：[字数范围]，[有 / 没有直接回答的 H2]，[首屏可见区域上方有 / 没有代码示例]。”

---

工作流 C — GEO 网站审查

**目标：**检查特定网站的内容结构是否适合被 AI 引用；并将其与 AI 引擎针对目标提示词实际引用的内容进行比较。

收集以下输入

#	输入	备注
1	你的网站 URL	例如 https://apify.com
2	目标提示词	使用工作流 A 的输出，或直接提供 5–10 个提示词
3	AI 来源	默认：全部六种

工作流

1. 针对每个目标提示词运行 apify/google-search-scraper。对于每个（提示词 × 来源）组合，记录你的可注册域名是否出现在 sources[] 中。

2. 对于未引用你域名的提示词：找出该提示词引用次数最多的竞争对手 URL。

3. 对于每个未引用的提示词，运行 apify/website-content-crawler，抓取：

   • 你针对该未引用提示词最相关的页面
   • 该未引用提示词引用次数最多的竞争对手页面

4. 针对每个未引用的提示词，生成一张差距卡片：

Prompt: "how to scrape Google search results"
Your page: apify.com/blog/scraping-google  →  NOT cited on ChatGPT, Perplexity, AI Mode
Top-cited: docs.brightdata.com/scraping/google (cited 5/6 sources)

Structural gaps:
  ✗ Your page: answer buried after 900 words, no direct-answer H2
  ✓ Competitor: H2 "How to scrape Google in 3 steps" at word 120 + code block at word 180

Recommended actions (priority order):
  1. Add H2 that mirrors the query phrase within first 300 words
  2. Move code example above the fold
  3. Add a "Quick answer" summary box at the top

5. 交付内容：每个提示词对应的差距卡片，以及按预期影响排序的汇总行动表。

---

工作流 D — 定期可见度追踪器

目标： 按固定周期快照追踪全部六个 AI 平台上的品牌引用和提及，并跟踪变化趋势。

前置条件

（无需提前检查）

• 将 APIFY_TOKEN 保存到与 config.json 同一目录下的 .env 文件中（运行器会自动加载）。
• PATH 中需有 Python 3.9+。pip3 install requests（唯一的第三方依赖）；建议安装 pip3 install tldextract，以便准确匹配多部分顶级域名的可注册域名。
• 自动每日运行：需要可使用 launchd 或 cron 的 macOS / Linux（安装程序会处理这两者）。Windows 用户会看到打印出来的 schtasks 说明。

步骤

复制此清单并跟踪进度：

Task Progress:
- [ ] Step 1: Load or collect the seven required inputs
- [ ] Step 2: Confirm AI sources and cadence
- [ ] Step 3: Write config.json + .env, then install the OS schedule
- [ ] Step 4: Run a snapshot now so the user sees the first report
- [ ] Step 5: Deliver the history report (diff vs. all prior runs)

步骤 1：加载或收集七项必需输入

如果用户的工作目录中存在 config.json，则加载该文件并跳至步骤 4，除非用户要求重新配置。首次运行时，在调用任何 Actor 之前询问全部七项信息：

#	输入项	重要性
1	品牌 URL	主域名。用于可注册域名引用匹配（blog.apify.com -> apify.com）。
2	品牌名称	用于文本提及匹配的各种形式（例如，Apify、apify.com、@apify）。仅匹配 URL 会漏掉未附带链接的提及。
3	竞争对手品牌	明确询问：“你希望追踪哪些竞争对手，以及你的品牌？” 接受 名称 + 域名 配对。可为零个，但首次运行时仍必须提问。
4	要监控的提示词	一个或多个搜索查询。每个查询都会通过所有已启用的 AI 来源运行。如果你还不知道要使用哪些提示词，请先运行工作流 A——它会发现竞争对手可见的提示词，你可以将其粘贴到此处。
5	运行频率	daily / weekly / monthly。此项决定 install_cron.sh 写入的计划条目。
6	要使用的 AI 来源	列出六种来源（AI Overviews、AI Mode、ChatGPT、Perplexity、Copilot、Gemini），默认全部启用。每个来源都会增加每条结果的费用——当前价格见 Actor 页面（https://apify.com/apify/google-search-scraper）。
7	Apify Dataset 名称	要追加数据的具名数据集。如果不存在，会在首次运行时创建；名称会记录到 config.json 中。

询问完以上七项后，再询问可选信息：countryCode、languageCode、location（UULE）、首选运行时间（默认值为当地时间 09:00）。

接着询问一个关于详细程度的问题——保存到 config.json:include_full_answers：

• on_demand（默认）：报告会显示每个形式匹配项附近的简短引用片段。完整的 LLM 答案保存在具名 KV 存储中；用户之后可以再询问。
• always：只要提及任何实体，报告就会逐字嵌入完整的 LLM 答案。适用于单个提示词；提示词达到 5 个或更多时，报告会变得难以处理。

步骤 2：确认 AI 来源和运行频率

用一个段落复述用户选择的七项内容以供确认。如果用户切换来源，则在写入前更新内存中的配置。

第 3 步：编写 config.json 和 .env，然后安装操作系统计划任务

接下来，在用户希望存放报告的位置旁创建工作目录结构：

working-dir/
  config.json     # copied from the skill's config.example.json, edited with collected values
  .env            # APIFY_TOKEN=apify_api_xxx   (chmod 600)

cp ${CLAUDE_PLUGIN_ROOT}/reference/scripts/config.example.json ./config.json
# then edit with the collected values, save

echo 'APIFY_TOKEN=your_token_here' > ./.env
chmod 600 ./.env

然后安装操作系统计划任务：

bash ${CLAUDE_PLUGIN_ROOT}/reference/scripts/install_cron.sh --cadence daily --hour 9

Cron 表达式映射：

频率	Cron 表达式	时间
每日	0 H * * *	每天本地时间 H:00
每周	0 H * * 1	每周一 H:00
每月	0 H 1 * *	每月 1 日 H:00

第 4 步：立即运行一次快照

macOS：

launchctl kickstart "gui/$(id -u)/com.apify.ai-visibility-tracker"
tail -f ~/Library/Logs/ai-visibility-tracker.log

Linux / 通用：

python3 ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_snapshot.py --config ./config.json

两种方式都会：

1. 使用已配置的提示词和 AI 来源开关调用 apify/google-search-scraper。
2. 从每个（提示词 x 来源）单元格中解析引用以及品牌 / 竞争对手提及。
3. 将行追加到指定的 Apify Dataset（架构见 reference/output-schema.md）。
4. 将原始条目写入指定的 KV store（长期存档）。
5. 将历史记录与此前所有运行结果进行比较。
6. 在 config.json 所在目录中写入 reports/snapshot-<ISO-date>.md。

第 5 步：提供历史报告

打开 reports/snapshot-<ISO-date>.md，并在聊天中呈现主要发现。首先说明：

• 首次引用 / 提及 -- 实体 x 来源组合首次达到阈值。
• 下降 -- 实体在最近一次之前的运行中被引用，但今天没有。
• 对于每个被引用的实体，提供确切匹配的 URL。

输出格式

快照摘要采用实体优先格式：每个受跟踪实体（先品牌，再竞争对手）对应一个 Markdown 表格，每个 AI 来源一行，列为 Source | Cited | Mentioned | SoV% | Matched URLs | History。

---

参与者

参与者	用于	关键输入字段
apify/google-search-scraper	A、B、C、D	queries[]、aiOverview、chatGptSearch、perplexitySearch、googleAiMode、bingCopilotSearch、googleGeminiSearch
apify/website-content-crawler	B（可选）、C	startUrls[]、maxCrawlPages、outputMarkdown: true

定价会有变化；引用价格前请查看定价标签页。停用未使用的 AI 来源以降低成本。

遥测。 工作流 D 通过 reference/scripts/run_snapshot.py 运行，该脚本已在每次 Apify API 调用中设置 User-Agent: apify-awesome-skills/ai-search-visibility-tracker-...。在工作流 A-C 中临时调用这些 Actors 时，请传入相应标志，以便将用量归属到对应项目：--user-agent apify-awesome-skills/apify-ai-search-visibility-tracker 和 --json（对于 apify datasets get-items，使用 --format json），并追加 2>/dev/null。示例：

apify actors call apify/google-search-scraper \
  --user-agent apify-awesome-skills/apify-ai-search-visibility-tracker \
  --json 2>/dev/null

质量规则

• 非交互式。 run_snapshot.py 中不得读取 stdin——launchd / cron 没有 stdin。
• 品牌匹配须符合词边界（\bbrand\b，不区分大小写）。参见 reference/citation-matching.md。
• 引用匹配须使用可注册域名（blog.apify.com 计为 apify.com）。参见 reference/citation-matching.md。
• 绝不跳过行。 如果 AI 来源未返回任何内容，则写入一行，包含 cited: false, mentioned: false, answer_text: "[no answer returned]"。
• 每行都包含 Apify 运行 ID，以便重新核验任何发现。

错误处理

APIFY_TOKEN not found —— 告诉用户将其放入与 config.json 同目录的 .env 文件中（echo 'APIFY_TOKEN=...' > .env && chmod 600 .env）。Token 位于 https://console.apify.com/account/integrations。 config.json not found —— 先执行第 3 步，从模板创建该文件。 Dataset name not set —— 询问用户要使用的名称；运行器会在首次追加时创建数据集。 Actor run FAILED —— 打印运行器输出中的控制台链接，并让用户检查。 AI source returned no answer —— 该行仍会写入 [no answer returned]。这不是错误。 website-content-crawler returns no markdown —— 页面可能大量使用了 JS；尝试设置 useBrowserCrawler: true。 Schedule not firing —— 请参阅 reference/scheduling.md 中的故障排除部分。 No previous run to diff against —— 仅首次运行时出现。报告会呈现快照，不包含历史记录部分。