seo-keyword-cluster

示例输出：examples/seo-keyword-cluster-headless-cms-20260514/PLAN.md

关键词集群

将种子关键词转换为按优先级排序的集群计划：每个集群按搜索意图和主题分组，并包含搜索量总计、支柱内容概念、辐射文章，以及每篇辐射文章建议的 H1/H2。

前提条件

• 已连接 SE Ranking MCP 服务。
• 用户提供：(a) 3 到 20 个种子关键词，(b) 目标市场国家（默认值：us），以及可选的 (c) 最低搜索量阈值（默认值：100 次/月），(d) 最高 KD（默认值：60）。

流程

1. 扩展种子关键词 DATA_getRelatedKeywords、DATA_getSimilarKeywords、DATA_getLongTailKeywords

   • 针对每个种子关键词，获取目标国家/地区的相关、相似和长尾变体。
   • 每个种子关键词至少获取 100 个候选关键词；跨种子关键词去重。

2. 基于问题的扩展 DATA_getKeywordQuestions

   • 为排名前 5 的种子关键词获取问题意图关键词。
   • 这些关键词通常会成为具有 PAA/精选摘要潜力的辐射文章。

3. 清理和筛选

   • 移除搜索量低于最低阈值或 KD 高于最高阈值的关键词。
   • 删除目标网站不拥有的品牌词。
   • 为每个关键词标注检测到的意图：信息型、商业型、交易型、导航型。

4. 按 SERP 重叠情况聚类 DATA_getSerpResults（或 DATA_getSerpTaskAdvancedResults）

   • 根据 Google 实际排名情况对关键词分组——即共享的前 10 个自然搜索 URL，而非文本相似度。基于词元重叠的聚类会造成关键词蚕食；完整算法和反模式说明请参阅 references/serp-overlap-methodology.md。
   • 运行前检查预算。 计算 estimated_credits = num_candidate_keywords × per_keyword_cost，其中 per_keyword_cost = 3（SERP-standard，默认值）或 10（SERP-advanced，仅当下游需要 AIO/PAA 时）。SERP-standard 足以完成聚类。如果 estimated_credits > 500，请向用户说明该数值并提供两种方案：(a) 使用 SERP-standard 继续；(b) 在步骤 3 中提高最低搜索量阈值／降低最高 KD 阈值，以缩减候选集后重新运行。如果用户已要求使用 SERP-advanced 且估算值超过 500，还应提供 SERP-standard 作为更经济的备选方案。
   • 获取 SERP（每个唯一候选关键词调用一次，并在会话期间缓存）——参阅 references/serp-overlap-methodology.md §“缓存”。SERP 获取总次数 = 关键词数量，而非关键词对数量。
   • 两两计算重叠分数。 对意图预分组内的每一对关键词（有关避免完整 O(N²) 运算的优化，请参阅 references/serp-overlap-methodology.md §“预分组”），统计前 10 个自然搜索结果中的共享 URL 数量。应用以下阈值：共享 7-10 个 = 同一文章（合并关键词），4-6 个 = 同一集群，2-3 个 = 在不同集群之间互相添加链接，0-1 个 = 分属不同集群或排除。
   • 根据重叠图中 4-6+ 个共享 URL 的连通分量形成集群。目标为 5 到 12 个集群。每个集群包含名称、主要关键词、次要关键词、搜索量总计和加权 KD。
   • 将每个集群分类为适合作为支柱内容（广泛、高搜索量、信息型）或仅适合作为辐射内容（范围较窄、具体）。

5. 支柱内容与辐射内容架构

   • 为每个支柱内容集群指定 3 到 7 篇辐射文章（每篇对应一个子集群或问题）。
   • 为每篇辐射文章拟定一个 H1 和 3 到 5 个 H2。
   • 规划内部链接结构：支柱内容链接到所有辐射文章，辐射文章反向链接到支柱内容，主题相邻的辐射文章之间互相链接。

6. 确定优先级

   • 在步骤 4 中通过 SERP 重叠形成集群之后应用——该公式为已分组的集群评分，不会影响哪些关键词聚在一起。
   • 为每个集群评分：搜索量（40%）+ KD 倒数（30%）+ 商业意图权重（30%）。
   • 输出优先级排序后的构建顺序。

7. 质量评分卡（综合后验证）

   • 写入 PLAN.md 后，根据生成的计划运行包含 4 项指标的质量评分卡；如果任何指标未通过，则向用户发出警告。此评分卡受到 theirs' 执行后评分卡模型的启发，并针对我们的集群计划输出进行了调整（我们评估的是计划，而非生成的内容，因为 seo-keyword-cluster 止步于架构设计）。
   • 关键词蚕食（零容忍）。 计划中的任意两个集群之间的 SERP 重叠率都不应达到 ≥ 40%（根据步骤 4 中缓存的 SERP 矩阵计算）。如果有两个集群触发此门槛，则重新合并它们，并从步骤 5 开始重新运行后续步骤。
   • 孤立内容（零容忍）。 计划中的每篇辐射文章都必须在步骤 5 生成的内部链接图中链接自其支柱页。任何没有来自其支柱页的入站链接的辐射文章都属于孤立内容。
   • 覆盖率。 每个集群的支柱页必须在其主要关键词 + 次要关键词集合中，或通过步骤 5 拟定的 H2 标题，覆盖该集群 ≥ 70% 的高搜索量关键词（按搜索量排序位于前半部分）。低于 70% 意味着支柱页对于其所属集群来说范围过窄。
   • 锚文本多样性。 在集群内的所有内部链接（支柱页↔辐射页 + 辐射页↔辐射页）中，任何单一锚文本的使用占比都不得超过 40%。占比超过 40% 表明存在过度优化。
   • 输出。 如果四项指标全部通过，则在 PLAN.md 的 "## Quality scorecard" 下追加一行：All gates passed (cannibalisation/orphan/coverage/anchor-diversity). 如果任何指标未通过，则在 PLAN.md 中追加 "## Quality scorecard" 部分，并为每项指标添加红／黄／绿状态行（红色 = 未通过，黄色 = 距阈值不超过 10%，绿色 = 通过）；同时在 PLAN.md 顶部的判定标题处标注 (needs review — N quality-gate failures)。还要将完全相同的评分卡写入输出文件夹中的 06-quality-scorecard.md，以便独立审计。

输出格式

创建文件夹 seo-keyword-cluster-{target-slug}-{YYYYMMDD}/，其中包含：

seo-keyword-cluster-{target-slug}-{YYYYMMDD}/
├── 01-seed-expansion.md
├── 02-filtered-keywords.md
├── 03-cluster-assignment.md      (SERP overlap matrix + cluster groupings)
├── 06-quality-scorecard.md       (evidence) — 4-metric gate result; written every run
├── keywords.csv
└── PLAN.md

PLAN.md 遵循以下结构：

# Cluster Plan: {topic} {(needs review — N quality-gate failures) if step 7 flagged any}
Market: {country}
Seeds: {seed list}

## Summary
- Keywords analysed: {n}
- Clusters formed: {n}
- Estimated combined monthly volume: {n}
- Pillars: {n}, spokes: {n}
- Clustering method: SERP-overlap top-10 (mode: {standard | advanced}, ~{credits} credits)

## Build order

### Cluster 1: {cluster name} [PILLAR]
- Primary keyword: {kw} ({volume}/mo, KD {kd})
- Secondary: {list}
- Total volume: {n}/mo
- Priority score: {n}

#### Pillar page
- H1: {H1}
- H2s: {list}

#### Spoke articles
1. **{spoke title}**
   - H1: {H1}
   - H2s: {list}
   - Target keyword: {kw} ({volume})
2. **{spoke title}** ...

### Cluster 2: {cluster name} [SPOKE-ONLY]
...

## Internal linking map
- Pillar A links to: spokes A1, A2, A3
- Spoke A1 links back to: pillar A, and cross-links to spoke B2 (topical overlap)
...

## Quality scorecard
{If all four gates pass:}
All gates passed (cannibalisation/orphan/coverage/anchor-diversity).

{If any fail, render this table instead:}
| Gate | Status | Detail |
|---|---|---|
| Cannibalisation (no two clusters ≥40% SERP overlap) | RED / YELLOW / GREEN | {detail} |
| Orphan (every spoke linked from its pillar) | RED / YELLOW / GREEN | {detail} |
| Coverage (pillar covers ≥70% of cluster's high-volume keywords) | RED / YELLOW / GREEN | {detail} |
| Anchor diversity (no anchor used >40% of internal links per cluster) | RED / YELLOW / GREEN | {detail} |

## Raw data
- keywords.csv: full enriched keyword list
- 03-cluster-assignment.md: every keyword and its cluster (incl. SERP overlap matrix)
- 06-quality-scorecard.md: standalone copy of the scorecard above (evidence)

keywords.csv 列： keyword,volume,kd,cpc,intent,cluster,role_in_cluster

提示

• 遵守 Data API 速率限制：每秒 10 个请求。使用 20 个种子词和 3 个扩展端点时，约需 60 次调用；请依次发送。
• 运行前调用 DATA_getCreditBalance。当前主要成本来自步骤 4 的 SERP 重叠分析：SERP-standard 模式（默认）下每个候选关键词约需 3 个额度，SERP-advanced 模式下约需 10 个额度。典型的 40 个关键词候选集在 standard 模式下约需 120 个额度，在 advanced 模式下约需 400 个额度。步骤 4 的预算检查会在获取任何 SERP 数据之前，向用户显示此估算；如果估算超过 500 个额度，还会提供更省成本的备用方案。
• 即使关键词在语义上相似，也不要将意图不同的关键词归入同一个集群。“Best X”（商业意图）和 “What is X”（信息意图）应该分属不同内容。
• 如果支柱页尝试对范围过窄的查询进行排名，就会失败。支柱集群的主要关键词月搜索量应 > 1,000，且主题范围要足够广，适合撰写 3,000+ 字的文章。
• 优先级评分只是起点，而非硬性要求。在承诺一整个季度的内容之前，请用户审核排名前 3 的集群。
• 集群合并现在由 SERP 驱动，而非文本驱动。 如果两个集群之间的 SERP 重叠率达到 ≥ 40%，步骤 7 的关键词蚕食检查会将其标记出来；请重新合并这些集群，并从步骤 5 开始重新运行。