blog-cluster

Blog 集群（语义主题集群引擎）

下方捆绑路径使用主机 Markdown 对 ${CLAUDE_SKILL_DIR} 的替换； 它不是导出的 shell 变量。执行前解析这些路径、对路径加引号， 并拒绝非绝对路径的覆盖值。向 Agent 传递从 ${CLAUDE_SKILL_DIR}/../blog/references 解析出的 blog_reference_root、 从 ${CLAUDE_SKILL_DIR}/../blog/templates 解析出的 blog_template_root，以及所需的同级根目录。 加载项目上下文之前，先阅读主参考文档 orchestration-details.md； 只将其由 helper fence 包围的输出传递给下游 Agent。

从单个种子关键词出发，规划并执行完整的互相关联内容生态系统。包含三个层次：语义聚类（大脑）、集群架构（结构）和执行引擎（机器）。

改编自 Lutfiya Miller 提交的 semantic-cluster-engine （获奖作品，AI Marketing Hub Pro Challenge，2026 年 3 月，95/100，优秀）。 原始仓库：截至 2026-10-12 已无法访问 此移植保留了 Plan + Execute 架构和集群上下文创新， 移除了特定品牌（ScienceExperts.ai）的样式和图片提示词，并通过 claude-blog 现有的子技能进行调用。

命令

命令	功能
/blog cluster	交互式。询问是要规划还是执行。
/blog cluster plan <seed-keyword>	基于 SERP 的语义分析。输出集群计划和映射。
/blog cluster plan --from strategy [path]	导入现有的 blog-strategy 集群构建计划，并根据 SERP 数据进行验证。
/blog cluster execute [path-to-plan]	按顺序调用 blog-write，并加入集群上下文及自动互链。

关键参考文档（按需加载）

• ${CLAUDE_SKILL_DIR}/references/semantic-clustering.md（SERP 重叠分析、意图分类、关键词全集扩展）
• ${CLAUDE_SKILL_DIR}/references/cluster-architecture.md（中心辐射式规格、schema 策略、链接密度规则）
• ${CLAUDE_SKILL_DIR}/references/execution-workflow.md（执行顺序、上下文注入、评分卡、故障处理）

与现有 claude-blog 技能的交叉引用

技能	此技能调用时机
/blog strategy	上游规划。plan --from strategy 会使用其 Cluster Build Plan 表格。
/blog write	逐篇执行。每篇分支文章和支柱文章都由 blog-write 生成，并在前面附加集群上下文块。
/blog chart	由 blog-write 在内部调用，用于内联 SVG 图表。此技能不会直接调用。
/blog image	此技能不会调用。每篇文章的主视觉图由 blog-write 根据其交付约定创建一次（通过 generate_hero.py）；参见步骤 4。
/blog seo-check	建议在执行后使用，以验证每篇文章的页面 SEO。
/blog cannibalization	建议在执行后使用，以确认集群内没有关键词重叠。
/blog schema	建议在执行后使用，以添加 BreadcrumbList、ItemList 和 Article schema。

此技能绝不会修改属于其他技能的文件。它通过 Task 工具或作为编排的子技能调用其他技能。

命令路由

1. 解析用户的命令，确定子命令。
2. 如果用户只输入 /blog cluster，询问：“您想要规划一个新集群，还是执行现有计划？”
3. 路由：
   • plan <keyword> 到规划阶段（下文）
   • plan --from strategy [path] 到策略导入流程（下文）
   • execute [path]、build 或 run 到执行阶段（下文）

---

规划阶段：/blog cluster plan <seed-keyword>

参考：${CLAUDE_SKILL_DIR}/references/semantic-clustering.md

步骤 1. 种子关键词扩展

使用 WebSearch 将种子关键词扩展为由 30 到 50 个短语组成的关键词集合：

1. 直接搜索 <seed>，收集相关搜索和“People also ask”。
2. 扩展长尾关键词：<seed> guide、<seed> tips、<seed> tools、<seed> examples、<seed> vs、best <seed>、how to <seed>。
3. 挖掘问题类关键词：what is <seed>、how does <seed> work、why <seed>、<seed> for beginners。
4. 扩展意图变体：添加商业修饰词（best、top、review、comparison、pricing）、信息类修饰词（guide、tutorial、explained、examples）和交易类修饰词（buy、download、tool、software、service）。
5. 确保年份时效性：<seed> <current year>。从系统日期获取当前年份，绝不硬编码年份。

步骤 2. 语义聚类

按照 ${CLAUDE_SKILL_DIR}/references/semantic-clustering.md 中的优先级规则，将扩展后的关键词分组：

1. SERP 重叠分析是主要信号。若两个关键词的前 10 条结果中有 4 条或更多相同，通常说明它们面向相同意图，应考虑合并到同一篇文章。
2. 意图分类：将每个关键词归类为信息型、商业型、交易型或导航型。
3. 实体映射：识别 Google 将哪些人物、产品、框架和组织与该主题关联起来。
4. 分组：合并意图相同且主题接近的关键词。每组成为主题集群中的一个分支。

步骤 3. 集群架构设计

参考：${CLAUDE_SKILL_DIR}/references/cluster-architecture.md

构建中心页与分支页：

• 支柱页（中心页）：针对最宽泛的关键词。字数为 2,500 到 4,000。模板为 pillar-page。链接至每个分支页。
• 分支页：每页针对一个长尾关键词集群。字数为 1,200 到 1,800。根据意图自动选择模板。链接至支柱页和同级页面。

集群构建规则：

• 常规模式：每个支柱页包含 2 到 5 个集群，每个集群包含 2 到 4 个分支页，总计 1 个支柱页加 5 到 15 个分支页。
• 小型集群模式：对于范围较窄的种子关键词，只有在警告用户并征得确认后，才允许创建 1 个支柱页加 2 到 4 个分支页。
• 每个分支页都针对唯一的主要关键词（避免关键词蚕食）。

步骤 4. 内部链接矩阵

对于每个分支页 S：

• S 链接至支柱页（始终如此；锚文本使用支柱页的主要关键词）。
• 支柱页链接至 S（始终如此；锚文本使用 S 的主要关键词）。
• S 链接至同一集群中的其他分支页（每页 2 到 3 个链接，使用上下文相关的锚文本）。
• S 链接至相邻集群中的分支页（0 到 1 个链接，仅在语义相关时添加）。

确认每个分支页至少有 2 个入站链接。统计计划中的内部链接总数。

步骤 5. 生成输出文件

所有计划和执行产物都放入当前工作目录下的同一个子目录。将输出目录规范化，拒绝符号链接，并拒绝写入集群目录之外的位置。Slug 只能包含小写字母、数字和连字符；拒绝绝对路径、..、Slug 中的路径分隔符以及隐藏控制字符。

<cwd>/
└── cluster-<seed-keyword-slug>/
    ├── cluster-plan.json
    ├── cluster-map.html
    ├── pillar-<slug>.md       (Execute Phase)
    ├── <spoke-slug>.md        (Execute Phase, one per spoke)
    └── cluster-scorecard.md   (Execute Phase)

cluster-plan.json 架构

{
  "seed_keyword": "<seed>",
  "generated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "pillar": {
    "id": "P",
    "title": "Title of the pillar",
    "primary_keyword": "broadest keyword",
    "secondary_keywords": ["..."],
    "search_volume_estimate": "high|medium|low",
    "template": "pillar-page",
    "word_count_target": 3000,
    "cluster": "pillar"
  },
  "clusters": [
    {
      "name": "Cluster A: Theme",
      "intent": "informational|commercial|transactional",
      "color": "#2563eb",
      "posts": [
        {
          "id": "A1",
          "title": "Post title",
          "primary_keyword": "long-tail keyword",
          "secondary_keywords": ["..."],
          "search_volume_estimate": "high|medium|low",
          "template": "how-to-guide",
          "word_count_target": 1500,
          "links_to": ["P", "A2"],
          "links_from": ["P", "A2"]
        }
      ]
    }
  ],
  "total_posts": 9,
  "total_interlinks": 23,
  "estimated_total_words": 18000
}

注意：流量估算是根据 SERP 信号得出的相对指标（高、中、低），并非绝对搜索量。若要获取精确数据，用户应查询 Ahrefs、SEMrush 或 DataForSEO（claude-blog 提供配套的同级项目 seo-dataforseo）。

cluster-map.html（可防御 XSS）

一个静态、自包含的 HTML 文件，内嵌 SVG 可视化图表。作者必须遵守以下规则：

• 不得使用内联 <script> 块。文档中任何位置都不得出现 onclick、onmouseover 或任何 on* 事件属性。
• 不得引用外部脚本 <src>。
• 绘制到 SVG 中的所有文本标签（标题、关键词、集群名称）都必须转义：插入前将 & 替换为 &，将 < 替换为 <，将 > 替换为 >，将 " 替换为 "，并将 ' 替换为 '。
• 悬停效果只能使用 CSS :hover。不得使用 JavaScript。
• 在 SVG 节点内使用 <title> 子元素提供可访问的工具提示（浏览器原生，无脚本）。

地图展示：一个中心支柱节点、向外辐射且以颜色区分的集群组、每个集群中的分支节点，以及连接相关节点的连线。

第 6 步：向用户展示计划

显示集群与文章数量、内部链接总数、预估字数和文件路径的汇总表。执行前请用户确认。等待用户明确批准。不得自动执行。

---

策略导入：/blog cluster plan --from strategy [path]

将 blog-strategy 的输出导入集群计划。

1. 查找策略输出。在当前目录（或用户指定的路径）中扫描文件，查找包含 Cluster Build Plan 表格且列为 # | Spoke Topic | Template | Target Keyword | Word Count | Internal Links 的文件（该格式由 /blog strategy 生成）。
2. 解析表格。提取支柱行（标记为 P）、分支行、模板分配、目标关键词和链接关系。
3. 验证并补充信息。对每个关键词执行 SERP 重叠验证（计划阶段第 2 步）。添加搜索量估算，并从语义上验证集群分组。
4. 如果 SERP 数据与策略表格矛盾，请标记冲突；不得默默覆盖用户的策略意图。
5. 使用与标准计划阶段相同的输出，生成 cluster-plan.json 和 cluster-map.html。
6. 展示转换后的计划，并突出显示任何基于 SERP 的调整，然后等待用户确认。

---

执行阶段：/blog cluster execute [path-to-plan]

参考：${CLAUDE_SKILL_DIR}/references/execution-workflow.md

第 1 步：加载计划

从用户指定的路径或工作目录中最新的 cluster-*/cluster-plan.json 读取 cluster-plan.json。验证 JSON 结构。如果不存在计划，返回：“未找到集群计划。请先运行 /blog cluster plan <seed-keyword>。”

读取用户提供的计划路径之前，请将其规范化为相对于当前工作目录的路径。拒绝绝对路径、..、符号链接、文件名不是 cluster-plan.json 的路径，以及位于所选集群目录之外的任何路径。将所有生成的文章、图片、地图和评分卡输出限制在该集群目录内。

第 2 步：确定执行顺序

1. 首先处理支柱页面（这样分支页面就能链接到已知文件名）。
2. 然后处理分支页面，按 (cluster priority, search_volume_estimate desc, post id alphabetical) 排序。集群优先级为该集群内预估搜索量之和（从高到低）。
3. 如果集群数超过 2 个，则在不同集群之间交替处理，以丰富早期内容的分布。

步骤 3：为每篇文章构建集群上下文并调用 blog-write

一次性成本说明（发布第一篇文章前）。 执行过程是批量进行的，且需要付费。只询问一次，并等待明确答复：“此计划包含 N 篇文章。每篇文章都会完整执行一次 blog-write 流程、一次 blog-reviewer 流程（如果某个关卡未通过，则会增加执行次数，最多迭代 3 次），并生成一张主图。使用 Gemini 生成主图时，每篇文章会调用一次付费图片接口（费用约为 N 乘以 https://ai.google.dev/gemini-api/docs/pricing 上当前的单张图片价格）。是否继续使用 Gemini 主图、仅使用免费图库主图，或停止？” 在集群上下文中记录答复为 HERO: gemini 或 HERO: stock-only。如果选择 stock-only，运行 generate_hero.py 时取消设置 Gemini 密钥（env -u GOOGLE_AI_API_KEY）。确认仅涵盖这 N 张主图；绝不循环重新生成。每项回退或跳过（使用图库主图、跳过文章）都要在最终报告的“回退与跳过”下单独列出一行。

构建集群上下文块（完整架构见 ${CLAUDE_SKILL_DIR}/references/execution-workflow.md），并将其添加到传给调用 blog-write 的 Task 工具的主题提示词前面。上下文会告知 blog-write 集群名称、文章的角色（支柱文章或分支文章）、主要和次要关键词、所选模板、目标字数、已写文章列表（附链接）、后续文章列表（使用 [INTERNAL-LINK] 占位符），以及此文章的链接要求。

证据来源追溯传递。 集群上下文必须为每篇分支文章和支柱文章包含以下指令：“确保重要论断可追溯至能为其提供支持的来源。在有助于识别或解读来源时，记录日期、出版方／标题详情、检索备注、方法论和局限性。遵循出版物的引用格式。删除无法核实的统计数据，并替换与事实矛盾的数据。”

这种逐级传递能在批量执行过程中保持证据规范，而不会把固定的来源记录格式变成评分项或关卡。参见 ${CLAUDE_SKILL_DIR}/../blog/references/flow-alignment.md。

上下文还会指示 blog-write 自主运行：跳过主题澄清，跳过大纲审批，不自动检测模板，也不要暂停。

每篇文章都要遵循 blog-write 的完整交付约定（标准流程：起草、处理视觉素材、渲染、初始化 nonce、审核、通过关卡）。集群中的 [INTERNAL-LINK: anchor -> filename.md] 标记仅用于草稿：协调器会在处理视觉素材步骤中、渲染前解析所有标记。目标文章已写完的标记会变成真实链接。目标文章属于计划中的后续文章时，标记会变成指向该文章已规划文件名的真实相对链接（计划会固定每个文件名）；集群全部完成后，该链接即可解析；随后评分卡的链接审计会确认每个目标都存在。没有对应计划目标的标记会被移除。交付的文章中不得残留任何标记。

输出格式：默认使用标准 Markdown（.md），与 blog-write 的默认格式一致。如果用户明确要求 HTML，则相应设置平台目标。不要添加任何品牌专用 CSS 或字标；这应由用户在后续处理中负责。

步骤 4：主图（不单独调用 blog-image）

不要从此技能调用 /blog image。blog-write 的交付约定要求每篇文章都配有主图，并会通过 generate_hero.py 在该文章的草稿文件夹中生成一次主图，因此再次调用会造成双倍开销，并生成一份相互竞争的文件。因此，主图是必需项，而非可选项：如果无法为某篇文章生成主图，该文章即未满足约定，批次会根据步骤 6 停止。遵循步骤 3 中的 HERO: 答复，并在评分卡中逐篇记录来源和模型（取自 hero-credit.txt）。

Step 5. 注入反向链接

较早发布的文章需要链接到较晚发布的文章，但已经通过交付契约的文章不得就地编辑：对其 Markdown、HTML、PDF 或主视觉图进行任何更改，都会使审核 nonce 和各项关卡失效。请明确处理每种情况：

1. 避免大多数编辑。 由于正向标记会解析为计划中的文件名（步骤 3），较早的文章已经链接到计划中指定的所有较晚文章。检查计划中的 links_to 和 links_from。
2. 目标仍是草稿（尚未运行其交付契约，例如它排在刚写完的文章之后）：在契约运行之前，将 Markdown 中匹配的 [INTERNAL-LINK: keyword -> filename.md] 标记替换为 [keyword](filename.md)。无需重新审核。
3. 目标已交付，但仍缺少链接： 不要修改文件。将拟议编辑追加到 cluster-<slug>/cluster-link-patches.md（文件、锚文本、要更改的句子、目标文件名），并在最终报告中列出。如果用户明确选择应用补丁，请编辑 Markdown，然后对该文章重新执行规范流程：重新渲染、重新初始化审核 nonce、重新审核、重新运行预检 --strict（最多 3 轮）。先告知用户额外审核的次数。
4. 集群元数据（cluster:、cluster_role:、cluster_group:、cluster_position:）必须在每篇文章各自的草稿阶段（步骤 3）写入其 frontmatter，不得事后添加。

Step 6. 失败处理

如果 blog-write 对任何文章返回质量关卡失败，立即停止整个批次。保存进度，将失败的文章和所有剩余文章标记为已跳过，并告知用户在继续之前手动检查或重试失败的文章。质量检查失败后，不要继续生成 5 到 15 篇文章，否则可能带来规模化内容滥用风险。

如果 blog-write 在生成内容之前因超时或运行时错误而失败，请在评分卡中记录失败，并停止操作，除非用户明确要求在检查原因后继续执行。

如果用户在执行中途取消，请保存进度并记录已完成的文章。下次运行 /blog cluster execute 时，检测已写入的文件，并从下一篇尚未写入的文章继续。

Step 7. 生成 cluster-scorecard.md

所有已尝试的文章处理完毕后，生成一份 Markdown 评分卡，涵盖以下内容：

• 每篇文章的状态（已写入、失败、已跳过）、文件路径和字数。
• 每篇文章的质量分数（通过 Task 并行调用每篇文章的 /blog analyze），以及集群平均分。
• 集群凝聚度评分：根据链接互惠性、意图多样性、模板多样性和关键词覆盖率计算的 0 到 100 综合分（公式见 ${CLAUDE_SKILL_DIR}/references/execution-workflow.md）。
• 内部链接审计：每篇文章的出链和入链数量、孤立标记、未解析的 [INTERNAL-LINK] 标记。
• 关键词蚕食检查：是否有两篇文章的主关键词相同，或任意文章对的关键词重合度超过 70%。建议运行 /blog cannibalization 进行深入检查。
• 主视觉图摘要：根据 hero-credit.txt 列出每篇文章的主视觉图来源和模型，以及任何图库备用图片。
• 链接补丁：列出 cluster-link-patches.md 的内容（如有）。
• 建议的后续操作：生成结构化数据（/blog schema）、逐篇进行 SEO 验证（/blog seo-check）、内容再利用（/blog repurpose）。

Step 8. 最终报告

向用户返回简明摘要，包含总数、评分卡路径和后续操作命令。

输出产物（摘要）

文件	阶段	格式
cluster-plan.json	规划	JSON
cluster-map.html	规划	静态 HTML + 内嵌 SVG，无 JavaScript
pillar-<slug>.md	执行	Markdown（或平台检测到的格式）
<spoke-slug>.md	执行	Markdown（或平台检测到的格式）
cluster-link-patches.md	执行（仅当已交付的文章缺少计划中的链接时）	Markdown 补丁列表
cluster-scorecard.md	执行	Markdown

---

质量门槛

门槛	检查项	未通过时的操作
集群最低要求	至少包含 2 个集群，每个集群至少有 2 篇文章	规划期间发出警告；建议扩展
关键词蚕食	没有两篇文章共用同一个主关键词	阻止执行；要求调整规划
链接完整性	每篇文章至少有 2 个指向它的内部链接	在评分卡中发出警告
长度估算	支柱文章通常需要比辐射文章更深入	作为可选规划上下文传递给 blog-write；绝不强制最低字数
搜索意图多样性	集群中至少包含 2 种不同的搜索意图	在评分卡中发出警告
模板多样性	集群中至少包含 3 种不同的模板	在评分卡中发出警告

---

错误处理

情况	操作
种子关键词过于宽泛（关键词变体超过 50 个）	建议在聚类前缩小主题范围。
种子关键词过于狭窄（关键词变体少于 5 个）	提供更小的集群（支柱文章加 2 到 3 篇辐射文章），或建议扩大范围。
WebSearch 不可用	仅生成草拟计划，并要求用户在执行前确认、导入关键词数据或 SERP 数据。
blog-write 未通过质量门槛或内容生成失败	停止批量处理，保存进度，将其余文章标记为已跳过，并要求手动检查或明确恢复执行。
未安装 blog-write	返回：“blog-cluster requires claude-blog. Install it before running this skill.”
cluster-plan.json 格式错误	验证 JSON，并报告带行号的解析错误。
用户取消执行	保存进度；下次调用时恢复执行，并自动检测已写好的文章。
无法为某篇文章制作主视觉图	交付约定要求必须提供主视觉图：该文章失败，批量处理停止（步骤 6）。提供仅使用图库图片的主视觉图。

---

与相关 claude-blog 技能的区别

技能	职责	blog-cluster 的新增功能
blog-strategy	规划 3 到 5 个内容支柱，并将中心辐射图作为战略练习绘制出来	根据 SERP 进行语义聚类，然后执行计划，生成相互链接的真实文章。
blog-calendar	围绕主题集群安排发布日期	不构建集群或撰写文章；本技能两者兼顾。
blog-cannibalization	检测现有内容中的关键词重叠	仅用于诊断。blog-cluster 在规划阶段防止关键词蚕食。
blog-write	一次撰写一篇文章	blog-cluster 在共享集群上下文和双向链接的基础上，协调多次 blog-write 调用。
blog-outline	生成单篇受 SERP 信息启发的大纲	blog-cluster 为整个集群生成相当于大纲的内容，然后撰写这些文章。

blog-cluster 是总承包方：它分析主题、绘制数据驱动的计划，并从一个种子关键词构建完整结构。