
SeoMachine 主题集群权威度分析/research-topics 如何把 GSC 关键词变成内容建设路线图【免费下载链接】seomachineA specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. This system helps you research, write, analyze, and optimize content that ranks well and serves your target audience.项目地址: https://gitcode.com/GitHub_Trending/se/seomachine在 SeoMachine 这套基于 Claude Code 的 SEO 内容工作区中/research-topics命令负责一件事主题权威度Topical Authority分析——把站点在 Google Search Console 中排名的全部关键词聚成主题集群逐一打分找出有需求但覆盖薄弱的主题输出可直接执行的 pillar cluster 建设方案。读完本文你将掌握该命令的完整运行机制GSC 数据如何被拉取、关键词如何被 ML 或规则两种策略聚类、0–100 权威度分数的三个权重如何计算以及如何解读报告并衔接后续的 SERP 研究与内容写作流程。命令概览做什么、产出什么该命令的原始定义位于 .claude/commands/research-topics.md使用方式只有一行/research-topics它把所有排名关键词分组为 topic clusters并识别四类主题Strong Authority Topics强权威你已经主导的主题策略是维持并扩张Moderate Authority Topics中等权威部分覆盖需要补强Weak Authority Topics弱权威文档原文用粗体标注为最大机会——应围绕它们构建完整的集群Coverage Gaps覆盖缺口每个主题内部你尚未排名的相关关键词。对每个主题命令会计算权威度分数0–100基于覆盖度、排名位置与搜索需求、排名关键词数量、平均排名、总曝光与点击量以及待填补的覆盖缺口。从执行入口看命令实际驱动的是根目录脚本 research_topic_clusters.py脚本头部 docstring 与命令文档描述一致Analyzes topical authority by clustering keywords into related topics.完整执行流程Process 拆解命令文档列出的 6 步流程在源码中对应一条清晰的调用链以下逐条对照说明。1. 从 GSC 拉取 90 天排名关键词脚本首先初始化两个数据源main()第 44–59 行GSC 为硬性依赖GoogleSearchConsole()初始化失败则直接return整个流程终止DataForSEO 为可选依赖初始化失败时仅打印⚠ DataForSEO not available后续覆盖缺口分析跳过聚类照常进行——即纯聚类是免费的文档中Clustering only 免费、含缺口分析约 $0.50的成本说明正源于此设计。随后调用all_keywords gsc.get_keyword_positions(days90, min_impressions5)关键词少于 10 个时脚本直接退出Not enough keywords for clustering analysis这解释了为什么新站点要积累一定 GSC 数据量后再跑该命令。数据来自 data_sources/modules/google_search_console.py 中的get_keyword_positions()它通过 Search Console API 的searchanalytics().query()以dimensions: [query]拉取起止日期内每行 query 的 clicks / impressions / ctr / position并按曝光量降序返回。一个值得注意的实现细节从源码结构看仓库当前get_keyword_positions()的函数签名为(days30, limit1000)并不包含min_impressions形参而 research_topic_clusters.py 中却以min_impressions5调用。实际运行前建议先核对两者版本是否匹配详见后文运行前提与已知限制。2. 聚类ML 优先规则兜底这是该命令的核心算法层采用双轨制轨道一ML 聚类sklearn 可用且关键词 ≥ 20 时启用cluster_keywords_ml()的处理管道为TF-IDF 向量化TfidfVectorizer(max_features100, ngram_range(1, 2), stop_wordsenglish)——bigram 窗口让 how to x 这类意图组合能作为特征参与聚类K-Means 聚类簇数n_clusters max(5, min(20, len(keywords) // 15))即每 15 个关键词约 1 个簇且被夹在 5–20 之间random_state42, n_init10保证结果可复现主题命名extract_topic_name()统计簇内关键词的高频实词排除内置停用词表只保留长度 3 的词取出现次数 1 的前 2 个高频词拼接成标题如 Podcast Marketing若无高频词则回退为第一个关键词原文。任何一步抛异常都会打印提示并自动回退到规则聚类。轨道二基于模式的规则聚类cluster_keywords_simple()该策略从config/competitors.json读取topic_patterns字段主题名 → 触发词列表的映射若配置文件不存在则使用脚本内置的 8 组通用模式。仓库提供的示例配置 config/competitors.example.json 中topic_patterns字段即对应此用途topic_patterns: { Product Features: [feature, tool, platform, service, software], Pricing: [price, pricing, cost, plan, free, trial], Tutorials: [how to, guide, tutorial, step, setup], Comparisons: [vs, versus, compare, comparison, alternative, best], Marketing: [market, marketing, promote, promotion, grow, audience], Analytics: [analytics, stats, statistics, metrics, data, report] }匹配规则是按顺序短路每个关键词依次与主题列表比对命中第一个主题即归入该主题并停止全部未命中的关键词统一落入Other/General簇。因此主题的排序会影响归类优先级——把更细分的主题写在前面更稳妥。定制建议把示例文件复制为config/competitors.json并改写topic_patterns可以让规则聚类贴合你的行业脚本注释原文即提示 customize these for your industry。3. 计算权威度分数0–100calculate_authority_score()采用三段加权模型与命令文档based on coverage, position, demand的描述完全对应分量权重打分梯度Coverage覆盖度50%关键词数 ≥50 → 100≥30 → 80≥15 → 60≥8 → 40≥4 → 20其余 → 10Position Quality排名质量30%平均位置 ≤5 → 100≤10 → 80≤20 → 60≤30 → 40≤50 → 20其余 → 10Demand需求20%总曝光 ≥10,000 → 100≥5,000 → 80≥2,000 → 60≥1,000 → 40≥500 → 20其余 → 10最终分数为coverage×0.50 position×0.30 demand×0.20后取整。get_authority_level()再把分数映射为四级≥75 → StrongMaintain and expand≥50 → ModerateStrengthen coverage≥25 → WeakBuild comprehensive cluster25 → MinimalMajor opportunity or ignore报告中的 Authority Distribution 表即由这四级计数生成。4. 用 DataForSEO 识别覆盖缺口对每个簇取簇内第一个关键词作为种子词调用find_cluster_gaps()related dfs.get_keyword_ideas(seed_keyword, limit100)该方法在 data_sources/modules/dataforseo.py 中实现底层请求/v3/dataforseo_labs/google/related_keywords/live返回带search_volume/cpc/competition的相关关键词列表默认按搜索量降序。缺口判定逻辑把簇内已排名的关键词小写、去首尾空白放入集合从返回的 related keywords 中剔除已排名的剩下的即缺口附带search_volume与difficulty按搜索量降序取前 20 条limit20最终进入报告的分析对象保留前 10 条coverage_gaps[:10]。单簇的缺口查询失败会被静默吞掉except: pass不影响整体报告生成——这也是API 部分失败仍有产出的容错设计。5. 机会排序弱簇 × 高需求main()中所有簇先按权威度分数升序排列最低分 最大机会再筛出 Weak/Minimal 级别并按total_impressions降序取前 5打印为 TOP 5 TOPIC CLUSTER OPPORTUNITIES (Build These!)。这正对应文档的核心洞察——Weak clusters with high demand Your biggest opportunity.文档给出的示例Content Marketing仅 3 个关键词排名、平均位置 28、5,000 曝光/月、15 个未覆盖的相关词 → 行动是建 10 篇文章的集群就是这个筛选逻辑的典型产物。6. 生成报告报告写入research/topic-clusters-YYYY-MM-DD.mdwrite_markdown_report()以当天日期命名结构上分四段Authority Distribution四级主题的计数与策略对照表Weak Authority Topics最多 15 个按曝光降序每个簇列出分数/级别、排名关键词数、平均位置、曝光、点击、Top 5 当前关键词、最多 8 条带搜索量与难度的覆盖缺口以及按簇规模分档的 Recommended Action5 个关键词的簇建议新建 8–12 篇文章 pillar page否则建议扩写现有内容 补 pillarStrong Authority Topics最多 10 个性能指标、Top 关键词、扩张机会与维护建议保持内容新鲜、拓展进阶主题Strategy Recommendations三级优先级的具体文章数建议——注意其中 Priority 1 的新增文章数由max(8, 15 - cluster[keyword_count])动态计算现有排名词越少建议产出的文章越多。控制台与报告的关键指标示例命令文档中的 Example OutputWeak Authority: Content Marketing (Score: 32/100) - Keywords: 3 - Avg Position: 28.4 - Impressions: 5,240/mo Coverage Gaps: - content marketing strategy (1,200 vol) - content marketing ROI (980 vol) - content calendar template (580 vol) ... Action: Create 10-article cluster to build authority运行前提与已知限制要让python3 research_topic_clusters.py真正跑通需满足以下条件依据 data_sources/README.md 与源码结构依赖安装pip install -r data_sources/requirements.txtML 轨道额外需要scikit-learn不可用时自动降级为规则聚类脚本会打印 Note: sklearn not available.环境变量research_topic_clusters.py通过load_dotenv()加载GSC_SITE_URL与GSC_CREDENTIALS_PATH——缺少站点 URL 或凭证文件不存在时GoogleSearchConsole.__init__会直接抛ValueError流程终止DATAFORSEO_LOGIN/DATAFORSEO_PASSWORD——仅在需要覆盖缺口时用到可缺省。 完整的.env模板可参考 data_sources/README.md 中给出的样例data_sources/config/.env由.env.example复制而来数据量门槛GSC 中排名关键词需 ≥10 个才能启动聚类20 个或无 sklearn 时走规则聚类路径GSC API 限制Search Console API 单次查询上限 1000 行rowLimit关键词极多时实际参与聚类的样本会被该上限截断从 data_sources/modules/google_search_console.py 的默认limit1000参数可以确认这一点版本一致性提示如前文所述脚本调用get_keyword_positions(days90, min_impressions5)而仓库中该方法的当前签名为(days, limit)二者存在出入实际部署时应先本地验证调用兼容性或按目标 GSC 模块版本调整调用参数工作目录报告写入相对路径research/建议从仓库根目录执行若该目录不存在脚本当前未做创建可自行先建目录。时间与成本方面命令文档给出的估计为耗时 2–3 分钟DataForSEO 缺口查询约 $0.50按 data_sources/README.md 中related keyword 数据约 $0.006/词的量级每簇 1 次 live 查询、约 20 个簇即可解释该成本纯聚类完全免费。如何解读报告并落地策略命令文档给出的三级优先级策略与报告结构一一对应Priority 1Build Weak Clusters最高优先选出需求曝光最高的 2–3 个弱簇先建 pillar page文档建议 3000 词再建 8–12 篇 cluster 文章覆盖报告列出的全部 coverage gaps所有 cluster 文章内链指向 pillar。Priority 2Maintain Strong Clusters——保持内容新鲜度、向进阶主题扩张、补足残余缺口。Priority 3Strengthen Moderate Clusters——补 3–5 篇达到强权威门槛同时优化现有内容排名。与其余命令的衔接Integration/research-topics不是孤立工具它是该工作区研究链路的选路器。文档明确给出的下游流程选定要建设的弱簇对每个 gap 关键词跑/research-serp [gap keyword]定义见 .claude/commands/research-serp.md做 SERP 意图分析先创建 pillar page再写 cluster 内容每篇内容用/write [keyword]生成定义见 .claude/commands/write.md。仓库中还有与集群构建主题直接相关的 .claude/commands/cluster.md可与本命令配合使用。什么时候运行When to Run每月一次监控主题权威度增长曲线内容规划前识别下一个要建设的集群进入新细分领域时确定哪些主题值得长期占据。小结/research-topics的设计逻辑可以用一句话概括用 GSC 真实排名数据定位权威洼地用 TF-IDF/K-Means或规则匹配把关键词组织成主题用覆盖度/位置/需求三因子量化每个主题的成熟度再用 DataForSEO 的 related keywords 精确到该写的下一篇粒度。整条链路的数据源、算法参数、评分梯度与报告结构均可在 research_topic_clusters.py、data_sources/modules/google_search_console.py、data_sources/modules/dataforseo.py 中逐行验证配合 config/competitors.example.json 中的topic_patterns完成行业定制后它就能从一次性分析脚本升级为每月可复跑的主题权威度仪表盘。【免费下载链接】seomachineA specialized Claude Code workspace for creating long-form, SEO-optimized blog content for any business. This system helps you research, write, analyze, and optimize content that ranks well and serves your target audience.项目地址: https://gitcode.com/GitHub_Trending/se/seomachine创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考