keyword-cluster

/digital-marketing-pro:keyword-cluster

脚本位置。 如果你的宿主未设置 ${CLAUDE_PLUGIN_ROOT}，脚本位于此插件的 scripts/ 文件夹中，与 skills/ 同级。请使用 Python 3.10 或更高版本运行：python；如果找不到 python，则使用 python3（macOS 和许多 Linux 系统）。

用途

输入一组种子关键词，生成可直接用于发布的主题集群规划：包含支柱页面及其分支页面，按搜索意图分组，并使用一套明确的评分公式确定优先级，同时提供内链图谱和四道关卡的质量评分卡。输出结构可直接交接给 /digital-marketing-pro:content-brief 或 /digital-marketing-pro:content-engine。

上下文效率

此技能会占用较多上下文。对任何引用的文件，先用 Grep 搜索，再用 Read 仅读取匹配范围，并指定 offset 和 limit。打开文件前，先列出 ${CLAUDE_PLUGIN_DATA}/<brand>/。在会话中途重新调用时，跳过已在上下文中的文件。

适用场景

• 启动新的内容项目——将包含 20 个关键词的简报转化为结构化主题中心
• 审核现有内容库，检查是否存在关键词蚕食（两个页面争夺相同的搜索意图）
• 在开始写作前设计支柱页面与分支页面的架构
• 分阶段为数百个变体实施程序化 SEO（每个主题系列使用一次）
• 重组现有网站的内链图谱

请勿用于仅需要关键词扩展的情况（请使用 /digital-marketing-pro:keyword-research），或需要排名／SERP 功能分析的情况（请使用 /digital-marketing-pro:rank-monitor，并添加 --features 以分析 SERP 功能）。

品牌上下文（自动应用）

1. 读取 ~/.claude-marketing/brands/_active-brand.json 获取当前品牌 slug，然后加载 ~/.claude-marketing/brands/{slug}/profile.json
2. 如果不存在品牌：询问“要先设置品牌吗（/digital-marketing-pro:brand-setup）？”——也可以使用默认值继续
3. 应用 skills/context-engine/industry-profiles.md 中针对行业的指导
4. 应用 skills/context-engine/compliance-rules.md，在聚类前筛除禁用术语

输入

输入	来源	必填？
种子关键词（3–500 个）	含有 keyword 列的 CSV（可选：volume、kd、intent）	是
每个关键词的 SERP 结果	JSON：{keyword: [top result URLs]}，可来自任意排名追踪器／Ahrefs／Semrush 导出	强烈建议——若没有此项，脚本会退回到词汇聚类，置信度较低
目标国家／语言	来自品牌资料	可选覆盖
最低搜索量／最高 KD 筛选条件	CLI 标志	可选
重叠阈值	CLI 标志 --overlap（SERP 模式默认值为 0.4，词汇模式为 0.3）	可选

如果没有 SERP JSON，可以通过品牌已连接的排名追踪器 MCP（Ahrefs／SE Ranking／Semrush）为每个种子运行查询，并保存排名前 10 的 URL，快速生成。如果种子数量过多、API 费用不值得承担，可以跳过此步骤，但须在最终交付物中注明使用了置信度较低的模式。

流程（10 步，按编号文件输出）

所有输出都保存到 ${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{YYYY-MM-DD}/。

1. 00-input.md — 记录种子词、来源、筛选条件、品牌背景和运行时间戳
2. 01-seed-expansion.md — 如果种子词少于 20 个，则通过品牌的关键词研究 MCP（Ahrefs getRelatedKeywords 等）扩展到约 50–200 个；否则跳过。记录扩展来源。
3. 02-filtered.csv — 应用最小搜索量 / 最大 KD / 禁用词筛选条件。将筛选后的集合保存为 CSV（脚本会读取此文件）。
4. 03-serps.json — 通过已连接的排名跟踪工具，获取每个关键词排名前 10 的 SERP URL（如果已提供 SERP，则跳过）。预算保护：如果预估成本超过 500 个积分，则显示成本并在抓取前询问“继续吗？（y/N — 默认 N）”。
5. 04-cluster-run.json — 运行脚本：

   python "${CLAUDE_PLUGIN_ROOT}/scripts/keyword_cluster.py" \
       --keywords "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/02-filtered.csv" \
       --serps "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/03-serps.json" \
       --overlap 0.4 \
       --min-volume {profile.min_volume or 0} \
       --max-kd {profile.max_kd or 100} \
       --out "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/04-cluster-run.json"
   

6. 05-quality-scorecard.md — 从 04-cluster-run.json 中读取 quality_scorecard 块。如果 status: needs_review，则进行诊断：
   • cannibalisation: fail → 两个集群共享支柱页面 + 意图。合并它们，或重新分配优先级较低集群的支柱页面。
   • orphan: fail → 一个包含多个关键词的集群有 0 个支持主题。重新拆分其成员的词元，或调低 --overlap。
   • coverage: fail → 已归入集群的种子词少于 80%。将 --overlap 调低至 0.3，或扩充种子词。
   • anchor_diversity: fail → 支柱页面名称过于相似。改写集群名称，使用不同的同义词。
   • fragmentation_warning: true（仅含支柱页面的集群占比 > 50%）→ 重叠阈值过严。先尝试 --overlap 0.3。
7. 06-pillar-pages.md — 对每个 priority_score >= 0.5 的集群，起草一段支柱页面简报（意图、受众、目标篇幅、需要回答的关键问题）。这些内容将用于 /digital-marketing-pro:content-brief。
8. 07-internal-link-map.md — 以表格形式呈现脚本输出中的 internal_link_targets。针对每个集群，列出要链接到的其他集群及建议的锚文本。这是开发团队或 CMS 模板应使用的文件。
9. 08-build-order.md — 按 priority_score 降序排序。建议的构建节奏：第 1 季度完成前 10%，第 2 季度完成接下来的 30%，其余加入待办列表。
10. PLAN.md — 单页摘要：统计数据 + 评分卡 + 优先级最高的 5 个集群 + 交接给链中的下一个技能。

输出格式

${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/2026-06-04/
├── 00-input.md
├── 01-seed-expansion.md      (only if seeds expanded)
├── 02-filtered.csv
├── 03-serps.json             (if SERP mode)
├── 04-cluster-run.json       (raw script output)
├── 05-quality-scorecard.md
├── 06-pillar-pages.md
├── 07-internal-link-map.md
├── 08-build-order.md
└── PLAN.md                   (the deliverable)

PLAN.md 是交付给品牌方 / 客户 / 下一个技能的文件。其他所有文件都是可审计的中间状态。

质量评分卡（四项关卡）

每次运行都会由 scripts/keyword_cluster.py 生成一份评分卡。要使 status: ready，四项都必须通过：

关卡	检查内容	重要原因
cannibalisation	没有两个集群共享同一 (pillar, primary_intent) 对	防止你撰写两个页面去竞争同一个 SERP
orphan	每个包含多个关键词的集群至少有 1 个支持主题（仅含支柱页面的集群除外，并会添加标签）	找出集群头部没有支持主题的聚类错误
coverage	至少 80% 的输入种子词已分配到至少一个集群	找出“垃圾”种子词和过严的阈值
anchor_diversity	每个包含多个关键词的集群至少建议 2 种锚文本变体	防止内部链接图中的锚文本过度优化

fragmentation_warning: true（仅含支柱页面的集群占比 > 50%）是一个软性信号——本次运行仍然有效，但你应考虑调低 --overlap 并重新运行。

集群完成后

询问：“你希望我：

• 为优先级最高的支柱页面撰写简报吗？（/digital-marketing-pro:content-brief）
• 开始撰写优先级最高的支柱页面吗？（/digital-marketing-pro:content-engine）
• 将内部链接映射应用到你的 CMS 吗？（/digital-marketing-pro:seo-implement）
• 通过 /digital-marketing-pro:seo-drift 安排每季度重新运行吗？”

链式交接

此技能是链中的一个生产者：

1. /digital-marketing-pro:keyword-research — 生成种子词
2. /digital-marketing-pro:keyword-cluster — 此技能
3. /digital-marketing-pro:content-brief — 使用 PLAN.md + 06-pillar-pages.md 为每个支柱页面编写内容简报
4. /digital-marketing-pro:content-engine — 起草内容
5. /digital-marketing-pro:seo-implement — 将内链映射应用到 CMS

提示与注意事项

• SERP 模式明显优于词汇模式。 词汇聚类无法识别“shopify seo”和“ecommerce platform seo”针对的 SERP 相互重叠，而“shopify themes”则不是。
• 重叠阈值的默认值较保守。 如果出现 fragmentation_warning: true，先将阈值降至 0.3。如果出现 cannibalisation: fail 且聚类过少，则将阈值提高到 0.5。
• 优先级分数不是排名，而是初步的构建顺序。某个聚类的 priority_score: 0.3 仍可能是转化率最高的机会，前提是它对应高利润产品线。请根据品牌档案中的 business_goals 灵活调整，不要机械地遵循分数。
• 不要在未先过滤的情况下对原始 GSC 查询导出数据运行此技能。 GSC 导出数据包含数千个同一查询的长尾变体，它们会全部聚在一起，形成单个超大聚类。
• 仅包含支柱页面的聚类也有效——它们代表不同的搜索意图，只是种子集中缺少对应的辐射页面候选项。如果需要辐射页面，请通过步骤 2 扩展种子词。
• 内链映射是建议，不是指令。 应根据品牌调性审核最终的锚文本（结合品牌档案中的调性字段和 skills/context-engine/guidelines-framework.md）。

使用的 Agent

• seo-specialist（主要）——解读结果并提供最终的支柱页面建议
• competitive-intel——当结果出乎意料时，用于分析 SERP 重叠
• brand-guardian——根据禁用词列表审核锚文本

另请参阅

• /digital-marketing-pro:keyword-research — 生成种子词（先使用）
• /digital-marketing-pro:content-brief — 使用聚类计划（接下来使用）
• /digital-marketing-pro:seo-implement — 将内链映射应用到 CMS
• /digital-marketing-pro:seo-drift — 每季度重新运行，以检测聚类漂移
• scripts/keyword_cluster.py — 底层聚类引擎