seo-cluster
热门基于 Google 搜索结果（SERP）重合度的语义主题聚类工具，专为内容架构规划设计。本工具通过实际的 Google 搜索结果重合度（而非单纯的文本字面相似度）对关键词进行精准聚类，设计中心辐射式（Hub-and-Spoke）内容集群与内链矩阵，并生成交互式可视化视图。若安装了 claude-blog，还可直接自动化执行内容创作。当用户提到“topic cluster”（主题聚类）、“content cluster”（内容集群）、“semantic clustering”（语义聚类）、“pillar page”（柱页/核心页）、“hub and spoke”（中心辐射架构）、“content architecture”（内容架构）、“keyword grouping”（关键词分组）或“cluster plan”（集群计划）时使用。
基于 Google 搜索结果（SERP）重合度的语义主题聚类工具，专为内容架构规划设计。本工具通过实际的 Google 搜索结果重合度（而非单纯的文本字面相似度）对关键词进行精准聚类，设计中心辐射式（Hub-and-Spoke）内容集群与内链矩阵，并生成交互式可视化视图。若安装了 claude-blog，还可直接自动化执行内容创作。当用户提到“topic cluster”（主题聚类）、“content cluster”（内容集群）、“semantic clustering”（语义聚类）、“pillar page”（柱页/核心页）、“hub and spoke”（中心辐射架构）、“content architecture”（内容架构）、“keyword grouping”（关键词分组）或“cluster plan”（集群计划）时使用。
语义主题聚类 (Semantic Topic Clustering)
基于 SERP 搜索结果重合度驱动的内容架构关键词聚类工具。按照 Google 实际的排名规律（前 10 搜索结果的重合情况）而非文本字面相似度对关键词进行分组。设计中心辐射式（Hub-and-Spoke）内容集群与内链矩阵，并生成交互式集群地图可视化。
脚本目录： 位于插件根目录下的 scripts/。
快速参考 (Quick Reference)
| 命令 | 功能说明 |
|---|---|
/seo cluster plan <seed-keyword> |
完整规划工作流：扩展、聚类、架构设计、可视化 |
/seo cluster plan --from strategy |
从已有的 /seo plan 输出成果中导入 |
/seo cluster execute |
执行计划：通过 claude-blog 生成内容或输出创作简报（Briefs） |
/seo cluster map |
重新生成交互式集群可视化地图 |
规划工作流 (Planning Workflow)
步骤 1：种子关键词扩展 (Seed Keyword Expansion)
使用 WebSearch 将种子关键词扩展为 30-50 个变体：
- 相关搜索 (Related searches)：搜索种子词，提取“相关搜索”和“其他人也在搜”
- 大家还在问 (People Also Ask / PAA)：提取 SERP 结果中的所有 PAA 问题
- 长尾修饰词 (Long-tail modifiers)：附加常见修饰词：“最佳/best”、“怎么/how to”、“对比/vs”、“新手入门/for beginners”、“工具/tools”、“案例/examples”、“指南/guide”、“模板/template”、“踩坑/mistakes”、“清单/checklist”
- 疑问词挖掘 (Question mining)：生成谁/什么/何时/何地/为什么/怎么做（who/what/when/where/why/how）等疑问词变体
- 意图修饰词 (Intent modifiers)：添加商业意图修饰词：“价格/pricing”、“测评/review”、“替代方案/alternative”、“对比/comparison”、“免费/free”、“Top 榜单/top”
去重处理 (Deduplication)： 规范化变体词（小写化、去除冠词），删除完全重复项。
目标：得到 30-50 个唯一的关键词变体。如果少于 30 个，以热门 PAA 问题作为新种子词进行第二轮扩展。
步骤 2：SERP 重合度聚类 (SERP Overlap Clustering)
这是本工具的核心差异化功能。完整算法请参考 references/serp-overlap-methodology.md。
处理流程：
- 先按初步意图猜测对关键词分组（减少两两对比的计算量）
- 针对组内每一对候选词，使用 WebSearch 分别搜索这两个关键词
- 统计自然搜索前 10 名结果中重合的 URL 数量（忽略广告、精选摘要 / Featured Snippets、PAA）
- 应用以下判定阈值：
| 重合结果数 | 关系 | 处置方案 |
|---|---|---|
| 7-10 | 同一页面 | 合并为单个目标文章页面 |
| 4-6 | 同一集群 | 归入同一个辐射（Spoke）集群中 |
| 2-3 | 相互链接 | 放在相邻集群中，建立跨集群交叉内链 |
| 0-1 | 相互独立 | 分配至不同集群，或直接排除 |
性能优化： 如果有 40 个关键词，全量两两对比需要 780 次检索。优化策略如下：
- 先按意图预分组（4 组 × 约 10 词 = 4 × 45 = 180 次对比）
- 仅对跨组边界词进行交叉检验
- 跳过同属一个核心词的长尾变体组合（默认它们属于同一集群）
DataForSEO 集成： 如果配置了 DataForSEO MCP，可优先使用 serp_organic_live_advanced 替代 WebSearch 获取 SERP 数据。每次批量调用前先运行 claude-seo run dataforseo_costs.py check serp_organic_live_advanced --count N。若返回 "status": "needs_approval"，展示预估费用并询问用户；若返回 "status": "blocked"，则降级退回使用 WebSearch。
步骤 3：搜索意图分类 (Intent Classification)
将每个关键词归类至以下四大意图类别之一：
| 搜索意图 | 特征信号 | 是否纳入集群？ |
|---|---|---|
| 信息型 (Informational) | how（怎么）、what（什么）、why（为什么）、guide（指南）、tutorial（教程）、learn（学习） | 是 |
| 商业型 (Commercial) | best（最佳）、top（前几）、review（测评）、comparison（对比）、vs（PK）、alternative（替代品） | 是 |
| 交易型 (Transactional) | buy（购买）、price（价格）、discount（折扣）、coupon（优惠券）、order（下单）、sign up（注册） | 是 |
| 导航型 (Navigational) | 品牌词、特定产品名、login（登录） | 否（直接排除） |
将导航型关键词排除在聚类之外。对临界模糊案例标记并交由人工复核。对于混合意图关键词（例如“best CRM software”兼具商业与信息属性），按主导意图（Dominant intent）归类。
步骤 4：中心辐射式架构设计 (Hub-and-Spoke Architecture)
完整规范请加载 references/hub-spoke-architecture.md。
设计集群结构：
- 挑选核心柱页关键词 (Pillar keyword)：搜索量最高、意图最广泛、与其他关键词 SERP 重合度最高
- 将辐射页划分至不同子集群：每个子集群对应一个子主题领域（每个柱页配 2-5 个子集群）
- 为子集群分配文章：每个子集群包含 2-4 篇辐射文章 (Spoke posts)
- 根据意图分类匹配页面模板：
| 意图模式 | 可选模板 |
|---|---|
| 信息型 (宽泛) | 终极指南 (ultimate-guide) |
| 信息型 (操作方法) | 步骤教程 (how-to) |
| 信息型 (列表) | 清单干货 (listicle) |
| 信息型 (概念解释) | 深度解析 (explainer) |
| 商业型 (对比) | 对比测评 (comparison) |
| 商业型 (评估) | 产品评测 (review) |
| 商业型 (排名) | 最佳推荐 (best-of) |
| 交易型 | 落地页 (landing-page) |
-
设定字数目标：
- 柱页 (Pillar page)：2500-4000 词
- 辐射页 (Spoke posts)：1200-1800 词
-
关键词自蚕食检查 (Cannibalization check)：确保没有任意两篇文章竞争同一个主关键词。若 SERP 重合度达到 7+，则将这些关键词合并到同一篇文章中统一覆盖。
步骤 5：内链矩阵设计 (Internal Link Matrix)
设计双向内链结构：
| 链接类型 | 指向方向 | 刚性要求 |
|---|---|---|
| 辐射页指柱页 | spoke -> pillar | 必须包含（每篇辐射页都要加） |
| 柱页指辐射页 | pillar -> spoke | 必须包含（覆盖每篇辐射页） |
| 簇内辐射页互链 | spoke <-> spoke | 每篇文章 2-3 个链接 |
| 跨簇辐射页互链 | spoke -> spoke (其它子集群) | 每篇文章 0-1 个链接 |
硬性规则：
- 每篇文章必须至少获得 3 个导入内链（Incoming internal links）
- 严禁孤立页面（Orphan pages，必须保证从柱页点击 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：交互式集群地图 (Interactive Cluster Map)
根据 templates/cluster-map.html 模板生成 cluster-map.html。
- 读取模板文件
- 根据集群计划构建
CLUSTER_DATAJSON 对象：{ 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 } } - 用实际 JSON 替换模板中的
CLUSTER_DATA占位符 - 将生成好的 HTML 文件写入输出目录
- 提示用户：“在浏览器中打开
cluster-map.html即可探索交互式集群地图。”
策略导入 (Strategy Import)
当使用 --from strategy 参数调用时：
- 在当前目录下查找最新的
/seo plan输出文件（搜索匹配*SEO*Plan*、*strategy*、*content-strategy*的文件） - 解析 Markdown 表格，提取：关键词、页面类型、内容支柱 (Content pillars)、URL 结构
- 校验提取的数据：检查是否有重复项、缺失关键词或不完整条目
- 补充 SERP 数据：对提取出的关键词运行 SERP 重合度分析
- 以导入的关键词作为初始集合构建集群计划（跳过步骤 1）
若未找到策略文件，提示用户：“当前目录下未找到现有的 SEO 计划。请先运行 /seo plan，或提供一个种子关键词来重新进行聚类。”
执行工作流 (Execution Workflow)
当调用 /seo cluster execute 时：
检查 claude-blog 是否安装
检测条件：~/.claude/skills/blog/SKILL.md 是否存在？
如果已安装 claude-blog：
- 加载
references/execution-workflow.md获取完整算法 - 从当前目录读取
cluster-plan.json - 检查断点续传状态：扫描输出目录，排查已写好的文章
- 按优先级顺序执行：先写柱页，再按搜索量由高到低依次撰写辐射页
- 针对每篇文章，带上集群上下文调用
blog-writeSkill：- 集群角色（柱页或辐射页）
- 集群内的位置（集群索引、文章索引）
- 目标关键词及次要关键词
- 模板类型与目标字数
- 需插入的内链（含指定锚文本）
- 待后续文章回链的占位标记 (Placeholder markers)
- 每写完一篇文章，扫描已生成的历史文章，寻找反向链接占位符并注入新文章的 URL
- 所有文章撰写完毕后，生成集群计分卡 (Cluster scorecard)
如果未安装 claude-blog：
- 为集群计划中的每篇文章生成详细的内容简报 (Content briefs)
- 每份简报包含：
- 标题与 Meta 描述
- 主关键词与次要关键词
- 模板类型与建议的大纲结构（H2/H3 大纲）
- 目标字数
- 需嵌入的内链（含锚文本）
- 核心覆盖要点
- 需要打出差异化的竞争对手页面
- 将简报作为独立的 Markdown 文件写入
cluster-briefs/目录 - 提示用户：“安装 claude-blog 可实现内容自动生成。目前简报已保存至
cluster-briefs/目录。”
集群计分卡 (Cluster Scorecard)
执行完毕后的质量评估报告。在 /seo cluster execute 完成后自动运行，或对输出目录分析后按需生成。
| 指标 | 目标值 | 测量方式 |
|---|---|---|
| 覆盖率 (Coverage) | 100% | 已撰写文章数 / 计划文章数 |
| 链接密度 (Link Density) | 每篇 3+ | 统计每篇文章的内链数量 |
| 孤立页面 (Orphan Pages) | 0 | 导入链接少于 1 个的文章数 |
| 关键词自蚕食 (Cannibalization) | 0 冲突 | 检查是否存在重复的主关键词 |
| 配图数量 (Image Count) | 每篇 1+ | 至少包含一张配图的文章数 |
| 柱页链接 (Pillar Links) | 100% | 所有辐射页与柱页均实现双向互链 |
| 交叉链接 (Cross-Links) | 80%+ | 推荐的辐射页间交叉内链已落实 |
| 内容缺口 (Content Gaps) | 0 | 计划中被跳过或未完成的文章数 |
地图重新生成 (Map Regeneration)
当调用 /seo cluster map 时：
- 读取当前目录下的
cluster-plan.json - 扫描输出目录并更新文章状态（已计划 vs 已撰写）
- 带有最新状态重新生成
cluster-map.html - 输出报告：已撰写 vs 计划文章数、链接完成百分比
输出文件 (Output Files)
所有产出物均写入当前工作目录：
| 文件 | 描述 |
|---|---|
cluster-plan.json |
机器可读的集群计划（完整数据） |
cluster-plan.md |
适合人类阅读的集群计划摘要 |
cluster-map.html |
交互式 SVG 可视化地图 |
cluster-briefs/ |
内容简报目录（未安装 claude-blog 时生成） |
cluster-scorecard.md |
执行后的质量评估报告 |
跨 Skill 集成 (Cross-Skill Integration)
| Skill | 联动关系 |
|---|---|
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”
错误处理 (Error Handling)
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
| "No seed keyword provided"（未提供种子关键词） | 缺失参数 | 提示用户输入种子关键词或 URL |
| "Insufficient keyword variants"（关键词变体不足） | 扩展后关键词少于 15 个 | 提取 PAA 问题进行第二轮扩展 |
| "SERP data unavailable"（SERP 数据不可用） | WebSearch |
<!-- truncated for translation batch; full body continues in source -->
