seo-cluster

语义主题聚类（v1.9.0）

由 SERP 重叠驱动的关键词聚类，用于内容架构设计。根据 Google 实际排名结果（共享前 10 条结果）对关键词分组，而非根据文本相似度分组。设计中心辐射式内容集群，提供内部链接矩阵，并生成交互式集群地图可视化。

**脚本：**位于插件根目录的 scripts/ 目录中。

---

快速参考

命令	功能
/seo cluster plan <seed-keyword>	完整规划工作流：扩展、聚类、架构设计、可视化
/seo cluster plan --from strategy	从现有 /seo plan 输出导入
/seo cluster execute	执行计划：通过 claude-blog 创建内容或输出内容简报
/seo cluster map	重新生成交互式集群可视化

---

规划工作流

步骤 1：扩展种子关键词

使用 WebSearch 将种子关键词扩展为 30–50 个变体：

1. 相关搜索 — 搜索种子关键词，提取“相关搜索”和“其他人还搜索了”
2. People Also Ask（PAA） — 提取 SERP 结果中的所有 PAA 问题
3. 长尾修饰词 — 添加常见修饰词：“best”“how to”“vs”“for beginners”“tools”“examples”“guide”“template”“mistakes”“checklist”
4. 问题挖掘 — 生成 who/what/when/where/why/how 变体
5. 意图修饰词 — 添加商业修饰词：“pricing”“review”“alternative”“comparison”“free”“top”

**去重：**规范化变体（转为小写、去除冠词），删除完全重复的项。 目标：获得 30–50 个不重复的关键词变体。如果不足 30 个，则以排名靠前的 PAA 问题为种子，再进行一轮扩展。

步骤 2：SERP 重叠聚类

这是核心差异化所在。加载 references/serp-overlap-methodology.md 查看完整算法。

流程：

1. 按初步意图判断对关键词分组（减少成对比较）
2. 对每组中的每个候选关键词对，分别使用 WebSearch 搜索两个关键词
3. 统计自然搜索结果前 10 条中的共享 URL 数量（忽略广告、精选摘要和 PAA）
4. 应用以下阈值：

共享结果	关系	操作
7-10	同一篇文章	合并至同一个目标页面
4-6	同一集群	归入同一个辐射集群
2-3	相互链接	放入相邻集群，并添加交叉链接
0-1	分开处理	分配到不同集群或排除

**优化：**40 个关键词进行完整的两两比较，需要 780 次比较。可改用以下方式：

• 按意图预先分组（4 组，每组约 10 个 = 4 x 45 = 180 次比较）
• 仅交叉检查各组边界上的关键词
• 如果两个关键词都是同一核心词的长尾变体，则跳过比较（假定属于同一集群）

**DataForSEO 集成：**如果有可用的 DataForSEO MCP，则使用 serp_organic_live_advanced 代替 WebSearch 获取 SERP 数据。每批处理前运行 python scripts/dataforseo_costs.py check serp_organic_live_advanced --count N。如果 "status": "needs_approval"，则显示成本估算并询问用户。如果 "status": "blocked"，则回退到 WebSearch。

步骤 3：意图分类

将每个关键词分为以下四种意图之一：

意图	特征	纳入集群？
信息型	how、what、why、guide、tutorial、learn	是
商业型	best、top、review、comparison、vs、alternative	是
交易型	buy、price、discount、coupon、order、sign up	是
导航型	品牌名称、特定产品名称、login	否（排除）

从聚类中移除导航型关键词。标记出边界情况以供人工审核。关键词可能兼具多种意图（例如，“best CRM software”同时具有商业意图和信息意图）——按主要意图分类。

步骤 4：枢纽-辐射架构

加载 references/hub-spoke-architecture.md 查看完整规范。

设计集群结构：

1. 选择支柱关键词 — 搜索量最高、意图最广、与其他关键词的 SERP 重合度最高
2. 将辐射关键词分组成集群 — 每个集群都是一个子主题领域（每个支柱对应 2-5 个集群）
3. 将文章分配到集群 — 每个集群包含 2-4 篇辐射文章
4. 为每篇文章选择模板 — 根据意图分类：

意图模式	模板选项
信息型（广泛）	ultimate-guide
信息型（操作方法）	how-to
信息型（列表）	listicle
信息型（概念）	explainer
商业型（比较）	comparison
商业型（评估）	review
商业型（排名）	best-of
交易型	landing-page

5. 设定字数目标：

   • 支柱页面：2500-4000 字
   • 辐射文章：1200-1800 字

6. 检查关键词蚕食 — 任意两篇文章的主要关键词不得相同。如果 SERP 重合度为 7+，则将这些关键词合并到一篇文章中，同时覆盖两个关键词。

步骤 5：内部链接矩阵

设计双向链接结构：

链接类型	方向	要求
辐射文章指向支柱页面	辐射文章 -> 支柱页面	必须（每篇辐射文章都要链接）
支柱页面指向辐射文章	支柱页面 -> 辐射文章	必须（每篇辐射文章都要链接）
集群内辐射文章互链	辐射文章 <-> 辐射文章	每篇文章 2-3 个链接
跨集群链接	辐射文章 -> 辐射文章（其他集群）	每篇文章 0-1 个链接

规则：

• 每篇文章至少要有 3 个指向它的内部链接
• 不得有孤立页面（从支柱页面出发，点击不超过 2 次即可到达每篇文章）
• 锚文本必须使用目标关键词或相近变体（不得使用“点击此处”）
• 链接须放在正文内容中，而不能仅放在导航栏或侧边栏中

以 JSON 邻接表的形式生成链接矩阵：

{
  "links": [
    { "from": "pillar", "to": "cluster-0-post-0", "type": "mandatory", "anchor": "keyword" },
    { "from": "cluster-0-post-0", "to": "pillar", "type": "mandatory", "anchor": "keyword" }
  ]
}

步骤 6：交互式集群图

使用 templates/cluster-map.html 中的模板生成 cluster-map.html。

1. 读取模板文件
2. 根据集群计划构建 CLUSTER_DATA JSON 对象：

   {
     pillar: { title, keyword, volume, template, wordCount, url },
     clusters: [{ name, color, posts: [{ title, keyword, volume, template, wordCount, url, status }] }],
     links: [{ from, to, type }],
     meta: { totalPosts, totalClusters, totalLinks, estimatedWords }
   }
   

3. 将模板中的 CLUSTER_DATA 占位符替换为实际 JSON
4. 将完成的 HTML 文件写入输出目录
5. 告知用户：“在浏览器中打开 cluster-map.html，以查看交互式集群图。”

---

策略导入

使用 --from strategy 调用时：

1. 在当前目录中查找最新的 /seo plan 输出（搜索与 *SEO*Plan*、*strategy*、*content-strategy* 匹配的文件）
2. 解析 Markdown 表格，提取：关键词、页面类型、内容支柱、URL 结构
3. 验证提取的数据：检查重复项、缺失的关键词和不完整条目
4. 使用 SERP 数据丰富信息：对提取的关键词运行 SERP 重合度分析
5. 使用导入的关键词作为起始集合构建集群计划（跳过步骤 1）

如果找不到策略文件，则提示用户：“当前目录中没有找到现有的 SEO 计划。请先运行 /seo plan，或提供一个种子关键词以重新进行集群划分。”

---

执行工作流

调用 /seo cluster execute 时：

检查 claude-blog

Test: Does ~/.claude/skills/blog/SKILL.md exist?

如果已安装 claude-blog：

1. 加载 references/execution-workflow.md，查看完整算法
2. 从当前目录读取 cluster-plan.json
3. 检查恢复状态：扫描输出目录，查找已写入的文章
4. 按优先级顺序执行：先处理支柱文章，再按流量从高到低处理辐射文章
5. 对每篇文章，使用集群上下文调用 blog-write 技能：
   • 集群角色（支柱文章或辐射文章）
   • 在集群中的位置（集群索引、文章索引）
   • 目标关键词和次要关键词
   • 模板类型和目标字数
   • 要包含的内部链接（含锚文本）
   • 后续文章将链接到本文的位置（占位标记）
6. 每篇文章写完后，扫描之前的文章，查找反向链接占位符 并填入新文章的 URL
7. 所有文章写完后，生成集群评分卡

如果未安装 claude-blog：

1. 为集群计划中的每篇文章生成详细的内容简报
2. 每份简报包括：
   • 标题和元描述
   • 主关键词和次要关键词
   • 模板类型和建议的结构（H2/H3 大纲）
   • 目标字数
   • 要包含的内部链接（含锚文本）
   • 需要涵盖的要点
   • 需要与之区分的竞争页面
3. 将简报作为独立的 Markdown 文件写入 cluster-briefs/ 目录
4. 告知用户：“安装博客写作技能以自动创建内容。简报已保存至 cluster-briefs/。”

---

集群评分卡

执行后质量报告。在运行 /seo cluster execute 后自动生成，也可按需分析输出目录生成。

指标	目标	衡量方式
覆盖率	100%	已写文章数 / 计划文章数
链接密度	每篇 3 个以上	统计每篇文章的内部链接数
孤立页面	0	入站链接少于 1 个的文章
关键词蚕食	0 冲突	检查是否存在重复的主关键词
图片数量	每篇 1 张以上	至少包含一张图片的文章
支柱链接	100%	所有辐射文章都链接到支柱文章，反之亦然
交叉链接	80% 以上	已实现的建议辐射文章间链接
内容缺口	0	被跳过或未完成的计划文章

---

重新生成地图

调用 /seo cluster map 时：

1. 从当前目录读取 cluster-plan.json
2. 扫描输出目录并更新文章状态（计划中或已写入）
3. 使用更新后的状态重新生成 cluster-map.html
4. 报告：已写文章数与计划文章数，以及链接完成百分比

---

输出文件

所有输出都写入当前工作目录：

文件	说明
cluster-plan.json	机器可读的集群计划（完整数据）
cluster-plan.md	人类可读的集群计划摘要
cluster-map.html	交互式 SVG 可视化图
cluster-briefs/	内容简报（未安装 claude-blog 时生成）
cluster-scorecard.md	执行后质量报告

---

跨技能集成

技能	关系
seo-plan	导入来源：策略导入会读取 seo-plan 输出
seo-content	质量检查：对生成的内容进行 E-E-A-T 验证
seo-schema	Schema 标记：为集群页面添加 Article、BreadcrumbList、ItemList
seo-dataforseo	数据来源：DataForSEO MCP 可用时获取 SERP 数据
seo-google	报告：生成集群计划和评分卡的 PDF 报告

集群规划或执行完成后，提供以下选项： “生成 PDF 报告？使用 /seo google report”

---

错误处理

错误	原因	解决方法
“未提供种子关键词”	缺少参数	提示用户提供种子关键词或 URL
“关键词变体不足”	扩展后关键词少于 15 个	使用 PAA 问题运行第二轮扩展
“SERP 数据不可用”	WebSearch 和 DataForSEO 均失败	30 秒后重试；若问题持续，则仅按搜索意图聚类并发出警告
“未找到策略文件”	使用了 --from strategy，但不存在计划	提示用户先运行 /seo plan
“未找到 cluster-plan.json”	未规划便执行	提示用户先运行 /seo cluster plan
“未安装 claude-blog”	未安装博客 skill 就尝试执行	改为生成内容简报；建议安装
“超出 DataForSEO 预算”	成本检查返回“blocked”	回退到 WebSearch；告知用户
“主要关键词重复”	检测到关键词蚕食	合并受影响的文章或重新分配关键词
“检测到孤立页面”	文章缺少指向它的链接	从最近的同集群文章添加链接
“恢复状态已损坏”	计划与输出不匹配	根据输出目录扫描重建状态

---

安全性

• 所有 URL 均通过 python scripts/fetch_page.py 获取（通过 validate_url() 防护 SSRF）
• 不存储或传输凭据
• 输出文件不包含 PII 或 API 密钥
• 每次 API 调用前都会运行 DataForSEO 成本检查

FLOW 框架集成

如需通过提示词引导关键词研究和差距分析，请使用 /seo flow find [url|topic] — FLOW 的 5 个查找阶段提示词通过结构化发现提示词，为 SERP 重叠聚类方法提供补充。