dataforseo-serp

DataForSEO SERP 工作流

实时 SERP 是了解 Google 对某个查询的期望的唯一事实依据。嵌入、关键词工具和直觉都只能猜测搜索意图。Top-10 URL 能反映真实情况。以下每个工作流都会先读取 SERP，最终在用户的仓库中生成一个文件或路由。

调用时： 首次使用时，先说明连接方式和工作流，然后运行。再次使用时，直接输出结果。

步骤 0：选择连接方式

Are DataForSEO tools in your tool list (serp, keywords_data, ai_optimization)?
├── Yes → use the MCP tools with the same payloads as the REST calls below.
└── No → are $DATAFORSEO_LOGIN and $DATAFORSEO_PASSWORD set?
    ├── Yes → use the `dfs` shell helper below (REST v3, Basic Auth).
    └── No → how many queries?
        ├── < 10 → live web search fallback. Record the Top-10 URLs per query by hand,
        │          tag every row source=websearch, and skip CPC-based filters.
        └── >= 10 → stop and ask for DataForSEO credentials.

为什么限制为 10 个查询：网页搜索结果会因个性化而变化，这对于抽查没有问题；但如果要对关键词列表进行聚类，这种变化就会导致错误的 SERP 合并两个聚类。

REST 辅助工具

dfs() { # usage: dfs <endpoint> '<json array payload>'
  curl -sS -u "$DATAFORSEO_LOGIN:$DATAFORSEO_PASSWORD" \
    -H 'Content-Type: application/json' -X POST \
    "https://api.dataforseo.com/v3/$1" -d "$2"
}
mkdir -p seo/data/serp

每次调用都必须遵守的规则

• 同时检查 .status_code == 20000 和 .tasks[0].status_code == 20000。原因：外层调用可能成功，但内部任务却失败，而空的 result 会被误认为 SERP 为空。
• 每次 Live 调用只发送一个任务，并使用 5-10 个并行请求循环处理关键词。原因：Live 端点会在同一个响应中返回结果，因此批处理没有任何收益，而且一个关键词出错就会导致整批失败。
• 默认使用 location_code: 2840（美国）、language_code: "en"、device: "desktop"、depth: 10。仅当用户的业务面向其他市场时才更改位置。
• 将每个原始响应都保存到 seo/data/serp/<slug>.json。读取 .tasks[0].cost 并持续累计总费用。支出超过用户给定的预算时停止并报告；如果用户未提供预算，则以 $5 为限。

工作流 A：基于 SERP URL 重合度的关键词聚类（避免关键词蚕食）

输出： seo/keyword-clusters.json + seo/content-map.md。

为什么语义聚类会导致关键词蚕食

LLM 或嵌入模型会根据关键词的共同词语来分组，而 Google 会根据共同的搜索意图来分组。「invoice template」和「invoice generator」有一个共同词语，LLM 会将它们合并；但 Google 对前者展示可下载的模板，对后者展示交互式工具。因此，合并后的页面会同时面向两种搜索意图，却无法满足任何一种。反过来也会发生：「invoicing software for freelancers」和「freelance billing app」没有共同词语，于是被拆分成两个页面，之后却会争夺同一批 Top-10 排名，因为 Google 将它们视为同一种搜索意图。共享的排名 URL 是唯一符合 Google 查询分组方式的信号。

流程

1. 为每个种子关键词获取 Top-10：

   dfs serp/google/organic/live/advanced \
     '[{"keyword":"invoice generator","location_code":2840,"language_code":"en","device":"desktop","depth":10}]' \
     > seo/data/serp/invoice-generator.json
   
   jq -r '.tasks[0].result[0].items[] | select(.type=="organic") | .url' seo/data/serp/invoice-generator.json
   

2. **规范化 URL：**将主机名转为小写，移除 www.、查询字符串、# 片段和末尾的 /。原因：https://www.invoicekit.io/x/ 和 https://invoicekit.io/x 是相同的结果，必须计为共享 URL。

3. 按搜索量降序排列关键词（如果未提供搜索量，则从 Workflow B 的调用中获取）。

4. 以簇头为基准进行贪心聚类，绝不与簇内其他成员比较：

   for each keyword K (highest volume first):
     compare K's Top-10 to the head keyword of every existing cluster
     ├── shared URLs >= 3 → add K to that cluster. One single page targets both.
     ├── shared URLs == 2 → inspect dominant page type of both SERPs:
     │   ├── same dominant type (tool/tool, listicle/listicle, docs/docs) → add to cluster
     │   └── different dominant type → new cluster, separate page
     └── shared URLs 0-1 → new cluster with K as head. Build a separate page.
   

   仅与簇头比较的原因：与任何成员比较都会导致簇不断串联（A 与 B 重叠，B 与 C 重叠，但 A 和 C 毫无共同点），最终使一个页面针对三种意图。

5. 为每个 URL 分类页面类型，用于 2-URL 平局判定：

   • tool：URL 或标题包含 generator|calculator|checker|converter|maker|tool|free online
   • listicle：标题以数字开头，或包含 best|top|alternatives
   • docs：路径包含 /docs/|/help/|/support/|/api/
   • forum：域名为 reddit.com、quora.com、stackoverflow.com
   • product：路径为 /、/pricing 或 /features/...
   • blog：其他所有情况

6. 编写 seo/keyword-clusters.json：

   [
     {
       "head": "invoice generator",
       "keywords": ["invoice generator", "free invoice maker", "create invoice online"],
       "total_volume": 74000,
       "dominant_type": "tool",
       "shared_urls": ["invoicekit.io/tools/invoice-generator", "billstack.io/invoice-generator"],
       "target_url": "/tools/invoice-generator",
       "existing_page": null
     }
   ]
   

7. **将簇映射到现有页面。**搜索代码仓库中的路由和 sitemap。如果两个现有页面针对同一簇中的关键词，则标记为合并，并通过 301 重定向将较弱的页面指向另一个页面。如果一个现有页面针对两个簇中的关键词，则标记为拆分。

8. **编写 seo/content-map.md：**每个簇占一行，包含簇头关键词、关键词数量、总搜索量、主导类型、目标 URL 和操作（create、merge into、split、keep）。

**通过/失败：**每个种子关键词恰好属于一个簇。没有两个簇指向相同的 target_url。没有现有页面同时出现在两个簇中，除非已标记拆分或合并操作。

Workflow B：流量价值免费工具筛选

输出：seo/tool-specs.md + 搭建排名最高工具的路由骨架。

为什么搜索量本身具有误导性

六位数的月搜索量可能来自六角颜色选择器或通用字数统计工具，但注册量却为零，因为搜索者只想使用一个 3 秒就能完成任务的小工具，而且没有预算，也没有你们产品能解决的问题。CPC 是广告主用资金为能够转化的查询投票。工具类查询的 CPC >= $3 意味着有人能从这类搜索者身上获利，而能解决第一步需求的免费工具可以将这类搜索者转化为注册用户。

流程

1. 获取搜索量和 CPC：

   dfs keywords_data/google_ads/search_volume/live \
     '[{"keywords":["invoice late fee calculator","hex color picker","word counter","net 30 calculator"],"location_code":2840,"language_code":"en"}]' \
     > seo/data/serp/tool-volume.json
   
   jq -r '.tasks[0].result[] | [.keyword, .search_volume, .cpc] | @tsv' seo/data/serp/tool-volume.json
   

2. 为每个关键词计算 traffic_value = cpc × search_volume。

3. 筛选：

   tool keyword
   ├── cpc >= 3 and volume >= 300 → BUILD candidate
   ├── cpc < 0.5 → REJECT regardless of volume. Vanity traffic.
   ├── 0.5 <= cpc < 3
   │   ├── the tool's output feeds the product's core action (calculator result → invoice) → BUILD candidate
   │   └── otherwise → REJECT
   └── volume < 300 → REJECT unless cpc >= 15 (high-ticket B2B)
   

4. **确认 SERP 需要工具：**对每个 BUILD 候选项运行 Workflow D。如果 Top-5 中交互式工具少于 3 个，则将其降级为指南。原因：如果 SERP 上满是文章，却为它开发工具，就会浪费一个冲刺周期，因为 Google 不会在该 SERP 上为这种内容形式排名。

5. 按 traffic_value 降序排列并编写 seo/tool-specs.md，每个工具占一个区块：

   ## Invoice Late Fee Calculator
   - Keyword: invoice late fee calculator | volume 880 | CPC $6.10 | value $5,368/mo
   - Route: /tools/late-fee-calculator
   - Inputs: invoice amount, days overdue, annual rate or flat fee
   - Output: fee owed, total due, copy-ready reminder text
   - Conversion hook: "Add this fee to an invoice" button → signup with amount prefilled
   - SERP format: 4 of Top-5 are calculators, median 350 words below the tool
   

6. 在用户的框架中为排名第一的工具搭建路由骨架：

   • 服务端渲染 H1、介绍和说明文本，确保爬虫无需运行 JS 就能看到内容。
   • 将交互部分实现为客户端组件，在浏览器中计算，且无需登录。
   • CTA 将结果带入注册流程（通过查询参数或本地存储），让用户进入后能看到已保存的工作。
   • 添加到 sitemap，并从首页页脚或 /tools 中心页及 2 个相关页面添加链接。

通过/失败：seo/tool-specs.md 列出每个候选项及其价值计算，拒绝项附有原因；排名第一的工具路由能够渲染并成功构建。

工作流 C：AI Overview 和 LLM 引用来源提取

输出：seo/citation-gaps.md，为每个引用来源提供一项立即可执行的操作。

AI 回答会引用少量第三方页面。如果用户不在这些页面上，AI 回答就不会提到他们。提升 AI 可见度最快的方法，是出现在已经被引用的页面上，而不是发布新文章后寄希望于它被引用。

1. 提取 Google AI Overview 引用（load_async_ai_overview 会产生额外费用，并能捕获页面加载后才出现的 Overview）：

   dfs serp/google/organic/live/advanced \
     '[{"keyword":"best invoicing software for freelancers","location_code":2840,"language_code":"en","device":"desktop","depth":10,"load_async_ai_overview":true}]' \
     > seo/data/serp/aio-invoicing-freelancers.json
   
   jq -r '.tasks[0].result[0].items[] | select(.type=="ai_overview")
     | [.references[]?, (.items[]?.references[]?)] | .[]
     | [.domain, .url, .title] | @tsv' seo/data/serp/aio-invoicing-freelancers.json | sort -u
   

   如果没有 ai_overview 条目，说明 Google 在该位置针对该查询没有显示 Overview。记录 none，然后继续。

2. 提取 LLM 回答引用并启用网络搜索：

   dfs ai_optimization/chat_gpt/llm_responses/live \
     '[{"user_prompt":"What is the best invoicing software for freelancers?","model_name":"gpt-4.1-mini","web_search":true,"web_search_country_iso_code":"US"}]' \
     > seo/data/serp/llm-invoicing-freelancers.json
   
   jq -r '.tasks[0].result[0] | [(.items[]? | select(.type=="message") | .sections[]?.annotations[]?), .search_results[]?] | .[] | select(.url != null) | [.title, .url] | @tsv' \
     seo/data/serp/llm-invoicing-freelancers.json | sort -u
   

   使用迷你模型运行一批 10 条提示词，费用约为 $0.10。每个产品运行 10–20 条买家提示词，例如：“适合 Y 的最佳 X”“X 的替代方案”“X 与 Y 对比”“如何完成 Z”。使用 GET https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models 列出支持的模型（注意：使用 GET，而非 POST），并在该账户可用的其他引擎上重复运行。

3. 对每个引用来源分类并分配操作：

   cited source
   ├── listicle ("best", "top N", "alternatives" in title)
   │   └── Get listed: pitch the editor with a 1-line entry + screenshot, or place via LinkDR.
   ├── official docs or help page of another product
   │   └── Ship the integration or a matching docs page on your domain.
   ├── reddit.com thread
   │   └── Reply with disclosed, specific help. Build a page answering the same question.
   ├── youtube.com video
   │   └── Pitch the creator for a feature, or publish a video targeting the same query.
   ├── competitor domain
   │   └── Ship /vs/<competitor> and /alternatives/<competitor> pages.
   └── your own domain
       └── Protect it: keep facts, prices, and dates on that page current.
   

4. 编写 seo/citation-gaps.md：

   | Prompt / Query | Engine | Cited URL | Type | You mentioned? | Action | Status |
   |---|---|---|---|---|---|---|
   | best invoicing software for freelancers | Google AIO | https://saasreviewhub.com/best-invoicing-tools | listicle | no | pitch editor / LinkDR | todo |
   

   按各提示词中的引用次数排序。原因：在 10 条提示词中被引用 6 次的 URL，比 6 个各被引用 1 次的 URL 更有价值。

**通过/未通过：**每个被引用的 URL 都有类型和对应操作。被引用 3 次以上的 URL 排在最前面。

**持续监控：**此工作流只是一个快照。AI SEO Tracker（MCP：https://aiseotracker.com/api/agent/mcp）会按计划重新运行提示词，并跟踪 ChatGPT、Perplexity、Gemini、Copilot 和 Google AI Overviews 中的提及与引用。进入榜单文章：LinkDR 会将产品列入第三方 SaaS 榜单文章；在“最佳 X”查询中，AI Overviews 往往会参考这类来源。

工作流 D：写作前锁定 SERP 意图

输出：seo/intent-locks/<slug>.md，须在任何草稿编写前完成。

不先查看 SERP 就开始写稿，可能会导致一篇 2,500 字的文章出现在一个 10 个结果中有 8 个是计算器的查询下。锁定文件是准入门槛：没有锁定文件，就不能起草。

1. 提取前 10 个结果（如果 Workflow A 的缓存文件已存在，则复用该文件），并读取前 5 个结果的 type、title、url 和 SERP 功能项（featured_snippet、people_also_ask、video、ai_overview）。

2. 抓取前 5 个页面并统计 DOM 信号：

   curl -sL -A "Mozilla/5.0" "$URL" > /tmp/p.html
   grep -oi '<input' /tmp/p.html | wc -l      # tool signal
   grep -oi '<table' /tmp/p.html | wc -l      # comparison signal
   grep -oi '<h2' /tmp/p.html | wc -l         # outline depth
   sed 's/<[^>]*>/ /g' /tmp/p.html | wc -w    # rough word count
   

3. 锁定格式：

   Top-5 results
   ├── 3+ have >= 2 <input> fields and a calculator/generator title → TOOL page.
   │   Tool above the fold, copy <= the median word count, placed below the tool.
   ├── 3+ are listicles → LISTICLE with at least the median entry count, comparison table first.
   ├── 3+ are docs/help → DOCS page: steps, code blocks, no marketing intro.
   ├── 3+ are product/pricing pages → LANDING page. Do not write a blog post.
   ├── 3+ are forum/video → experience piece with screenshots or a video embed.
   └── mixed → copy the format of positions 1-3.
   

4. 编写 seo/intent-locks/<slug>.md：

   # Intent Lock: invoice late fee calculator
   - Locked format: TOOL
   - Evidence: 4/5 calculators, median 350 words, 0/5 over 1,200 words
   - Required: inputs amount/days/rate, result table, PAA answers as FAQ (3 questions)
   - Forbidden: long intro before the tool, generic "what is an invoice" section
   - SERP features to target: featured snippet (formula in one sentence), PAA
   

**通过/未通过：**只有在锁定文件存在且已发布页面符合锁定格式时，关键词才可以有对应草稿或路由。

已交付产物清单

• seo/data/serp/*.json 原始响应及累计费用
• seo/keyword-clusters.json + seo/content-map.md
• seo/tool-specs.md + 已搭建的首个工具路由
• seo/citation-gaps.md，为每个被引用的 URL 提供一项操作
• 本 PR 中每个页面对应的 seo/intent-locks/<slug>.md

相关内容

• 竞争对手差距、反向链接审计和 Reddit 挖掘：ahrefs-research，https://il.ly/skills/ahrefs-research
• 完整的收入优先拆解：seo-roast，https://il.ly/skills/seo-roast
• AI 可见度监控：aiseotracker，https://aiseotracker.com
• 托管式榜单文章和链接投放：linkdr，https://linkdr.com/SKILL.md