seo-cluster

语义主题聚类

基于 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. “用户也在问”（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 数据。每批处理前运行 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run 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” 同时属于商业型和信息型），应按主导意图进行分类。

Step 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 以上，则将这些关键词合并到一篇文章中，同时覆盖这两个关键词。

Step 5：内部链接矩阵

设计双向链接结构：

链接类型	方向	要求
辐射文章到核心页面	spoke -> pillar	必须（每篇辐射文章都要链接）
核心页面到辐射文章	pillar -> spoke	必须（链接到每篇辐射文章）
辐射文章之间（集群内）	spoke <-> spoke	每篇文章 2-3 个链接
跨集群	spoke -> spoke（其他集群）	每篇文章 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" }
  ]
}

Step 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. 使用导入的关键词作为起始集合构建集群计划（跳过 Step 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. 告知用户："安装 claude-blog 即可自动创建内容。简报已保存至 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"

错误处理

错误	原因	解决方案
"No seed keyword provided"	缺少参数	提示用户提供种子关键词或 URL
"Insufficient keyword variants"	扩展后少于 15 个关键词	使用 PAA 问题运行第二轮扩展
"SERP data unavailable"	WebSearch 和 DataForSEO 均无法使用	30 秒后重试；若问题仍然存在，则仅按意图进行聚类并发出警告
"No strategy file found"	使用了 --from strategy，但没有计划	提示用户先运行 /seo plan
"cluster-plan.json not found"	未规划便执行	提示用户先运行 /seo cluster plan
"claude-blog not installed"	未安装博客技能便尝试执行	改为生成内容简报；建议安装
"DataForSEO budget exceeded"	费用检查返回了 "blocked"	改用 WebSearch；告知用户
"Duplicate primary keywords"	检测到关键词蚕食	合并受影响的文章或重新分配关键词
"Orphan page detected"	帖子缺少入站链接	从最近的集群同级页面添加链接
"Resume state corrupted"	计划与输出不匹配	根据输出目录扫描结果重建状态

---

安全性

• 所有 URL 均通过 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run render_page.py <url> --mode auto 获取（通过 url_safety 提供适配 SPA 的 SSRF 防护）
• 不存储或传输凭据
• 输出文件不包含 PII 或 API 密钥
• 每次 API 调用前都会运行 DataForSEO 费用检查

FLOW 框架集成

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