检测博客文章关键词自相残杀（关键词重叠）并给出合并或差异化建…

当多篇博客文章可能争夺同一搜索关键词时，用本地文件分析或 DataForSEO API 检测关键词重叠并输出严重度报告。

适用场景

解决思路

1. 本地模式（默认，免费）：用 Glob 按 `**/*.md`、`**/*.mdx`、`**/*.html` 扫描目标目录，跳过 `node_modules/`、`.git/`、`drafts/` 中的文件。
2. 对每个文件从 title 标签或 H1（最高权重）、H2（中等权重）、首段（辅助信号）、frontmatter 中的 meta description 提取关键词信号。
3. 主关键词提取：将 title、H1、H2、meta description、首段分词为 1-gram、2-gram、3-gram 短语；确定性归一化（转小写、去除停用词、统一词干化、保留产品名、保留 best/pricing/vs/review/template 及年份等意图修饰词）；按区块分别打分（title/H1 最高，meta description 与 H2 中等，首段辅助）；选得分最高的 2-3 词短语作为主关键词，并从 H2 记录次要关键词。
4. 按相似度聚类，匹配规则优先级：1) 精确匹配（2 篇以上主关键词完全相同）；2) 词干匹配（如 optimize 与 optimization）；3) 语义重叠（标注 informational、commercial、transactional、comparison、troubleshooting 等意图标签，附置信度与一句话理由，或用带明确阈值的 embeddings 流程）；4) 子集匹配（一个关键词包含另一个，如 email marketing 与 email marketing for startups）。
5. 对每个含 2 篇以上文章的聚类评估严重度并生成建议。
6. 输出结果表格与每个聚类的建议。
7. API 模式（需 `--api` 标志）：需有本地 CLI 包装器从环境变量读取 `DATAFORSEO_LOGIN` 和 `DATAFORSEO_PASSWORD` 并输出 JSON；不要用 WebFetch 发 DataForSEO POST 请求，不要在提示或报告中暴露 Basic auth 头、登录名、密码或编码凭证；若项目无包装器，报告 `SKIPPED: DataForSEO wrapper unavailable` 并改用本地模式。
8. API 模式调用 Page Intersection 端点 `POST https://api.dataforseo.com/v3/dataforseo_labs/google/page_intersection/live`，请求体含 pages、language_code、location_code，约 $0.01/次，返回重叠关键词及 position、volume、CPC。
9. API 模式调用 Ranked Keywords 端点 `POST https://api.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live`，请求体含 target、language_code、location_code，获取单个 URL 排名的全部关键词。
10. API 分析步骤：1) 从用户或 sitemap 收集所有已发布 URL；2) 对每个 URL 运行 Ranked Keywords 建立关键词画像；3) 对共享关键词聚类的 URL 对运行 Page Intersection；4) 用公式计算严重度；5) 输出含搜索量与排名数据的增强报告。
11. 严重度分级：Critical（完全相同关键词且两页均在前 20，立即处理）；High（同一关键词聚类且一页排名高于另一页，本周处理）；Medium（相关关键词且 SERP 部分重叠，本月处理）；Low（语义相似但意图不同，持续监控）。
12. API 模式严重度公式：`severity_score = overlap_count x avg_search_volume x (1 / position_gap)`，其中 overlap_count 为共享排名关键词数，avg_search_volume 为共享关键词月均搜索量，position_gap 为平均排名位置差的绝对值（最小为 1），分数越高越紧急。
13. 本地模式严重度启发式：Critical 为文章间主关键词精确匹配；High 为主关键词词干匹配或共享 3 个以上 H2 关键词；Medium 为主关键词语义重叠；Low 仅为子集匹配或共享次要关键词。
14. 输出汇总表，列为 Post A、Post B、Shared Keywords、Severity、Recommendation。
15. 对每个被标记聚类提供：两篇文章标题与 URL、完整重叠关键词列表（API 模式含搜索量）、哪篇更强（更全面、结构更好）、带理由的具体建议。
16. 建议动作 MERGE：当两页都较单薄或意图与深度相似时，合并两篇最佳内容为一篇综合文章，将较弱 URL 301 重定向到合并后文章，保留指向任一 URL 的所有内链。
17. 建议动作 DIFFERENTIATE：当页面服务不同意图但关键词定位重叠时，将较弱文章的主关键词转向相关长尾词，更新 title、H1 和 meta description 以反映新焦点，并在两篇文章间加内链以表明主题不同。
18. 建议动作 CANONICAL：当一篇明显是权威、另一篇是较弱的重复时，在较弱页面加 `rel="canonical"` 指向权威页；不要随意组合 canonical 与 noindex，仅在确实要从搜索中移除时用 noindex；从较弱页链接到权威页。
19. 建议动作 NOINDEX：当页面需从搜索结果移除但仍对用户存在时，确认该页无独特搜索需求或商业价值，在 noindex 指令被观察到前保持可抓取，不要将其作为重复内容的默认修复手段。
20. 建议动作 NO ACTION：当表面关键词相似但意图确实不同时，记录理由供未来审计，每季度监控排名变化，若任一文章排名下降则重新评估。
21. 错误处理：目录中无 .md、.mdx、.html 文件时报告 "No blog files found in [directory]" 并建议检查路径；API 模式凭证未配置时自动回退本地模式并通知用户；收到 429 时等待并重试一次，仍失败则对剩余 URL 改用本地模式；API 返回错误时在速率限制内重试一次，仍失败则对剩余 URL 改用本地模式并报告失败端点（不含凭证）；仅一篇文章时报告 "Cannibalization analysis requires at least 2 posts" 并优雅退出。

适用边界 · 注意事项

• 只有一篇文章时无法进行自相残杀分析。
• API 模式需要 DataForSEO 凭证与本地 CLI 包装器，缺失时应回退本地模式。
• 不要用 WebFetch 发 DataForSEO POST 请求，也不要在提示或报告中暴露凭证。