seo-cluster

语义主题聚类（v1.9.0）

共享数据缓存

步骤 0 -- 检查共享数据缓存：

开始收集前，检查 .seo-cache/ 中是否有可复用的相关 SEO 技能上下文。 参考 ../seo/references/shared-data-cache.md，了解架构和依赖关系图。

如果存在，请检查以下缓存文件：

• .seo-cache/site-meta.json，获取域名、业务类型、行业和爬取上下文

• .seo-cache/audit-scores.json，获取之前完整审计的优先事项

• .seo-cache/pages/{url-slug}/page-analysis.json，如果提供了 URL，则获取页面级上下文

• 如果找到：解析并使用明确有效的字段（注明“正在使用来自 [date] 的缓存 [X]”）

• 如果缺失、损坏或不相关：使用新证据继续

• 如果用户说“refresh”或“re-run”：忽略缓存读取，并在写入时覆盖

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

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

---

快速参考

命令	功能
/seo cluster plan <seed-keyword>	完整规划工作流：扩展、聚类、架构设计、可视化
/seo cluster plan --from strategy	从现有 /seo plan 输出导入
/seo cluster execute	执行计划：通过 codex-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 数据。每批次运行前先执行 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）	how-to
信息型（列表）	listicle
信息型（概念）	explainer
商业型（比较）	comparison
商业型（评估）	review
商业型（排名）	best-of
交易型	landing-page

5. 设定字数目标：

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

6. 检查关键词蚕食 — 任意两篇文章都不能使用相同的主要关键词。如果 SERP 重叠度达到 7+，将这些关键词合并到一篇同时针对它们的文章中。

第 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" }
  ]
}

第 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 时：

检查是否安装了 codex-blog

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

如果已安装 codex-blog：

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

如果未安装 codex-blog：

1. 为集群计划中的每篇文章生成详细的内容简报
2. 每份简报包括：
   • 标题和元描述
   • 主要关键词和次要关键词
   • 模板类型和建议结构（H2/H3 大纲）
   • 目标字数
   • 要包含的内部链接（带锚文本）
   • 要涵盖的要点
   • 需要与之形成差异化的竞争页面
3. 将简报作为单独的 Markdown 文件写入 cluster-briefs/ 目录
4. 告知用户：“安装 codex-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/	内容简报（未安装 codex-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
"未安装 codex-blog"	未安装博客技能就尝试执行	改为生成内容简报；建议安装
"超出 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 重叠的聚类方法。

写入共享数据缓存

完成所有工作后，如果工作流产生了可长期保留的发现，请将简洁的 JSON 摘要写入 .seo-cache/。 请遵循 ../seo/references/shared-data-cache.md 中的架构和命名规则；至少包含 cache_type、analyzed_at、源 URL/域名、关键发现、问题、建议和工具限制。如果 .gitignore 中缺少 .seo-cache/，请将其添加进去。