keyword-clustering

关键词聚类技能

将原始关键词列表整理成结构化、经过验证的聚类映射，并以可下载的 Excel 文件交付。

---

此技能的功能

1. 接收任意格式的关键词
2. 验证每个关键词：通过 DataForSEO 获取搜索量、KD、CPC
3. 筛除搜索量为 0 或 null 的关键词（无效关键词）
4. 聚类经过验证的关键词，依据主题和搜索意图分组
5. 输出格式化、可下载的 Excel 文件

---

第 1 步：输入处理

识别用户提供的输入格式，并提取关键词列表。

粘贴的列表

如果用户直接在聊天中粘贴关键词（每行一个、以逗号分隔或带编号），请提取每个关键词并整理成干净的数组。删除编号、项目符号和多余空格。

CSV 或 Excel 上传文件

文件位于 /mnt/user-data/uploads/。使用 pandas 读取：

import pandas as pd

# CSV
df = pd.read_csv('/mnt/user-data/uploads/filename.csv')

# Excel
df = pd.read_excel('/mnt/user-data/uploads/filename.xlsx')

# Identify keyword column: look for columns named 'keyword', 'keywords', 'query', 'term', 'search term'
# If ambiguous, pick the first text column or ask the user
keyword_candidates = ['keyword', 'keywords', 'query', 'term', 'search term']
keyword_col = next((col for col in df.columns if col.lower() in keyword_candidates), df.columns[0])
keywords = df[keyword_col].dropna().tolist()

Google 表格 URL

使用 web_fetch 将表格作为 CSV 获取（在基础 URL 后追加 /export?format=csv）。使用 pandas 解析。

**每次最多处理 500 个关键词。**如果输入超过 500 个，请告知用户并处理前 500 个，或询问用户要使用哪个子集。

---

第 2 步：DataForSEO 验证

使用 dataforseo_labs_google_keyword_overview 工具验证所有关键词并获取指标。每批处理 100 个，以符合 API 限制。

每个关键词必须提取以下字段：

• search_volume — 月搜索量（Google）
• keyword_difficulty — KD 分数（0–100）

**筛选规则：**删除 search_volume 为 0、null 或缺失的关键词。这些都是无效关键词。

提前告知用户：“正在通过 DataForSEO 验证 [N] 个关键词，请稍候……”

验证完成后，报告：

• 提交的关键词总数
• 通过验证的关键词数（有搜索量）
• 被删除的关键词数（搜索量为零或 null）——列出这些关键词，让用户了解哪些内容被移除了

**如果 DataForSEO 无法使用或返回错误：**告知用户“DataForSEO 验证失败——我会对完整列表进行聚类，但无法验证搜索量或提供 KD/CPC 数据。”然后继续处理完整的未验证列表，并在输出中跳过搜索量、KD 和 CPC 列。

---

第 3 步：聚类

仅使用通过验证的关键词，按以下两个维度进行聚类：

维度 1：主题聚类

按共有的主题进行分组。使用核心概念为聚类命名。

规则：

• 每个聚类应使用一个由 2–5 个词组成的描述性名称（例如，“Email Marketing Tools”“Python Data Analysis”）
• 目标是每个聚类包含 3–8 个关键词。优先增加聚类数量，而非减少；如果某个主题可以合理拆分成两个不同的子主题，就拆分
• 不要过度合并：即使关键词有相同的核心词，针对不同角度、受众或内容类型的关键词也应归入不同聚类
• 如果主题范围很广，始终创建子聚类（使用父级 + 子级命名方式，例如，“SEO – On-Page”“SEO – Technical”）
• 为每个聚类分配一个数字 Cluster ID（1、2、3……）

维度 2：搜索意图

为每个关键词分配以下四种标准意图标签之一：

标签	含义	信号词
Informational	用户想要了解信息	what is、how to、guide、tutorial、definition、examples
Navigational	用户想访问特定网站或品牌	品牌名称 + login/sign in/pricing
Commercial	用户正在比较选项	best、top、vs、review、alternative、comparison
Transactional	用户想要采取行动或购买	buy、download、get、free trial、sign up、hire

如果搜索意图不明确，请根据完整关键词短语选择最可能的意图。不要将意图留空。

聚类逻辑

根据你对关键词语义的理解进行分组。将符合以下条件的关键词归为一组：

• 核心主题或产品领域相同
• 逻辑上会出现在同一篇内容或网站板块中
• 面向相同的受众阶段

不要仅凭共享词语进行分组（例如，不要因为“best email marketing software”和“email marketing statistics”都包含“email marketing”，就把它们放在同一个聚类中——前者属于商业意图，后者属于信息意图，分别对应不同的页面）。

---

第 4 步：构建 Excel 输出

如果有 xlsx SKILL，请先阅读。使用 openpyxl 进行格式设置。

工作表 1：“Keyword Clusters”（主要输出）

列顺序：

列	描述
Cluster ID	数字聚类编号
Cluster Name	描述性主题名称
Keyword	已验证的关键词
Search Volume	DataForSEO 提供的月搜索量
KD	关键词难度（0–100）
Intent	信息 / 导航 / 商业 / 交易

**排序：**先按 Cluster ID 升序，再按每个聚类中的 Search Volume 降序排列。

格式：

• 第 1 行：粗体表头、深色背景（#1F2D40）、白色文本、居中对齐
• 不同聚类组交替使用浅色行底纹，以便区分聚类（每隔一个聚类组使用 #F2F2F2）
• 冻结首行
• 自动调整列宽（最小 15，最大 40）
• Search Volume 的数字格式：#,##0
• KD：普通整数

工作表 2：“Cluster Summary”

每个聚类一行：

列	描述
Cluster ID	编号
Cluster Name	名称
# Keywords	聚类中的关键词数量
Avg Search Volume	聚类内的平均搜索量
Avg KD	平均 KD
Dominant Intent	聚类中最常见的意图标签
Top Keyword	搜索量最高的关键词

按 Avg Search Volume 降序排列——搜索量最高的机会优先。

工作表 3：“Dropped Keywords”

列出验证步骤中移除的所有关键词：

列	描述
Keyword	被移除的关键词
Reason	“零搜索量”或“未返回数据”

如果没有关键词被移除，请添加一行：“没有关键词被移除。”

---

第 5 步：保存并交付

# Save the workbook
output_path = '/mnt/user-data/outputs/keyword_clusters.xlsx'
wb.save(output_path)

然后，如果使用了公式，请运行重新计算：

python scripts/recalc.py /mnt/user-data/outputs/keyword_clusters.xlsx

使用 present_files 将文件交付给用户。

展示文件后，在聊天中简要总结：

• 聚类的关键词总数
• 创建的聚类数量
• 移除的关键词数量
• 按平均搜索量排名前 3 的聚类

---

边缘情况

• **重复关键词：**验证前先去重。如果存在重复项，请说明。
• **非英语关键词：**DataForSEO 支持多语言。按语义进行聚类，并注明语言。
• **所有关键词均被移除：**告知用户所有关键词的搜索量均为零。询问是否要跳过验证并直接进行聚类。
• **仅有一个关键词：**告知用户至少需要 10 个关键词，聚类才有意义。
• **输入内容很大（200 个以上关键词）：**提醒用户 DataForSEO 批处理可能需要 2–3 分钟。自动继续处理。