blog-cannibalization

博客关键词蚕食——关键词重叠检测

检测多篇博客文章是否在争夺相同的搜索关键词。提供两种模式： 仅本地分析（默认）和使用 DataForSEO API 获取 SERP 级数据的模式。

两种模式

模式	标志	成本	数据来源
本地	（默认）	免费	通过 Grep/Read 分析文件内容
API	--api	约 $0.01/次调用	DataForSEO Page Intersection + Ranked Keywords

本地模式无需任何 API 密钥即可运行。API 模式需要将 DataForSEO 凭据 设置为环境变量：DATAFORSEO_LOGIN 和 DATAFORSEO_PASSWORD。

本地模式工作流

步骤 1：扫描博客文件

使用 Glob 查找目标目录中的所有内容文件：

• 模式：**/*.md、**/*.mdx、**/*.html
• 跳过 node_modules/、.git/、drafts/ 中的文件

步骤 2：提取主要关键词

对于每个文件，读取并提取以下关键词信号：

• 标题标签或 H1 标题（权重最高）
• H2 标题（中等权重）
• 首段（辅助信号）
• Meta 描述（如果 frontmatter 中存在）

主要关键词提取方法：

1. 将标题和 H1 分词为 1-gram、2-gram 和 3-gram 短语
2. 根据每个短语在标题、H2 和首段中的出现频率评分
3. 选择得分最高的 2-3 词短语作为主要关键词
4. 记录 H2 标题中的次要关键词

步骤 3：按相似度聚类

按照以下匹配规则（按优先级排序）对文章进行分组：

1. 完全匹配——2 篇或更多文章的主要关键词完全相同
2. 词干匹配——词根相同（例如，“optimize”与“optimization”）
3. 语义重叠——Claude 判断两个关键词是否针对相同的 搜索意图（例如，“best CRM software”与“top CRM tools 2026”）
4. 子集匹配——一个关键词包含另一个（例如，“email marketing” 与“email marketing for startups”）

步骤 4：评分并标记

对于包含 2 篇或更多文章的每个聚类，评估严重程度并生成建议。

步骤 5：输出报告

显示结果表格和每个聚类的建议。

API 模式工作流（DataForSEO）

需要使用 --api 标志。通过 WebFetch 调用 DataForSEO 端点。

使用的端点

Page Intersection——查找多个 URL 均获得排名的关键词：

POST https://api.dataforseo.com/v3/dataforseo_labs/google/page_intersection/live
Authorization: Basic <base64(login:password)>

{
  "pages": {
    "1": "https://example.com/post-a",
    "2": "https://example.com/post-b"
  },
  "language_code": "en",
  "location_code": 2840
}

成本：约 $0.01/次调用。返回重叠关键词及其排名、搜索量和 CPC。

Ranked Keywords——获取单个 URL 获得排名的所有关键词：

POST https://api.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live

{
  "target": "https://example.com/post-a",
  "language_code": "en",
  "location_code": 2840
}

API 分析步骤

1. 从用户（或站点地图）处收集所有已发布的 URL
2. 对每个 URL 运行 Ranked Keywords，建立关键词档案
3. 对共享关键词聚类的 URL 配对运行 Page Intersection
4. 使用下方公式计算严重程度
5. 输出包含搜索量和排名数据的增强版报告

严重程度评分

根据重叠信号划分为四个严重程度等级：

等级	标准	处理紧迫性
严重	相同的精确关键词，两个页面均排名前 20	立即处理
高	属于同一关键词聚类，其中一个页面排名高于另一个	本周处理
中	相关关键词，SERP 部分重叠	本月处理
低	语义相似，但已确认的搜索意图不同	监控

严重程度公式（API 模式）

severity_score = overlap_count x avg_search_volume x (1 / position_gap)

其中：

• overlap_count = 共享排名关键词的数量
• avg_search_volume = 共享关键词的月均搜索量
• position_gap = 平均排名位置之差的绝对值（最小为 1）

分数越高，表示关键词蚕食问题越紧急。

严重程度启发式规则（本地模式）

没有 SERP 数据时，使用简化评分：

• 严重：文章之间的主要关键词完全匹配
• 高：主要关键词词干匹配，或共享 3 个或更多 H2 关键词
• 中：主要关键词存在语义重叠
• 低：仅子集匹配，或共享次要关键词

输出格式

汇总表

| Post A | Post B | Shared Keywords | Severity | Recommendation |
|--------|--------|-----------------|----------|----------------|
| /best-crm-tools | /top-crm-software | best crm, crm tools, crm software | Critical | MERGE |
| /email-tips | /email-marketing-guide | email marketing | High | DIFFERENTIATE |
| /seo-basics | /seo-for-beginners | seo basics, beginner seo | Critical | CANONICAL |
| /react-hooks | /react-state-mgmt | react, state | Low | NO ACTION |

每个集群的详细信息

对于每个被标记的集群，请提供：

• 两篇文章的标题和 URL
• 重叠关键词的完整列表（API 模式下附带搜索量）
• 哪篇文章更强（内容更全面、结构更完善）
• 具体建议及理由

建议

每个蚕食集群有四种可能的操作：

MERGE

当两篇页面内容都较单薄，或覆盖相同意图且深度相近时。

• 将两篇文章中最好的内容合并为一篇全面的文章
• 将较弱 URL 通过 301 重定向到合并后的文章
• 保留所有指向任一 URL 的内部链接

DIFFERENTIATE

当页面服务于不同意图，但关键词定位存在重叠时。

• 将较弱文章的主要关键词调整为相关的长尾关键词
• 更新标题、H1 和元描述，以体现新的侧重点
• 在两篇文章之间添加内部链接，以表明它们讨论的是不同主题

CANONICAL

当一篇文章明显更具权威性，另一篇只是质量较低的重复内容时。

• 在较弱页面上添加指向权威页面的 rel="canonical"
• 如果较弱页面没有提供独特价值，可考虑将其设为 noindex
• 从较弱页面链接到权威页面

NO ACTION

当尽管表面上的关键词相似，搜索意图实际上不同的时候。

• 记录原因，供今后的审核参考
• 每季度监控排名，留意排名变化
• 如果任一文章排名下降，则重新评估

错误处理

• 未找到博客文件：如果目录中没有 .md、.mdx 或 .html 文件，请报告 "No blog files found in [directory]"，并建议检查路径
• 缺少 DataForSEO 凭据：在 API 模式下，如果未配置凭据，则自动回退到本地模式并通知用户
• API 速率限制：DataForSEO 有每分钟速率限制。如果收到 429 响应，请等待后重试一次。如果仍然失败，则对剩余 URL 切换到本地模式
• WebFetch 失败：如果无法访问源 URL，请跳过该 URL，并在报告中注明 "Unable to verify - source unavailable"
• 仅有一篇文章的目录：如果目录中只有一篇博客文章，请报告 "Cannibalization analysis requires at least 2 posts"，并正常退出