yandex-wordstat

yandex-wordstat

使用 Yandex Wordstat API 分析搜索需求和关键词统计数据。

配置

此技能通过 Yandex Cloud Search API v2 中的 Wordstat API 工作。授权方式可选择通过服务账号授权 JSON 密钥使用 IAM，或使用服务账号 API 密钥。脚本会自动获取并更新 IAM 令牌；API 密钥不会自动更新。

有关配置、从旧版 API 迁移和排查错误的统一说明：config/README.md。

⚠️ dynamics 中的运算符：使用 --period weekly|monthly 时，仅支持运算符 +。减号词、引号、分组和精确形式仅在 --period daily 时有效。此技能会检查短语，并在发送请求前报告错误。详情请参阅 README。

理念

1. 警惕非目标需求 — 数字高不代表流量质量好
2. 创造性地扩展语义 — 像客户一样思考
3. 始终明确地区域 — 分析前询问用户的目标区域
4. 在报告中展示运算符 — 包含 Wordstat 运算符以便核验
5. 通过网络搜索核验意图 — 始终确认人们实际想买什么

关键：核验意图

将任何查询标记为“目标”之前，必须通过 WebSearch 核验意图！

问题所在

查询“каолиновая вата для дымохода”（烟囱用高岭棉）看起来与烟囱卖家相关，但：

• 人们搜索它是为了购买棉，而不是烟囱
• 他们已经有烟囱，需要隔热材料
• 对于烟囱销售来说，这不是目标查询！

核验流程

对于每个有潜力的查询，问自己：

1. 这个人想买什么？（而不只是“他们对什么感兴趣”）
2. 他们会通过这次搜索购买我们的产品吗？
3. 还是他们在寻找相关或配套产品？

必须：使用 WebSearch

始终运行 WebSearch 进行核验：

WebSearch: "каолиновая вата для дымохода" что ищут покупатели

查看搜索结果：

• 显示了哪些产品？
• 人们会提出什么问题？
• 这是信息型意图还是交易型意图？

警示信号（很可能不是目标）

• 查询包含“для [вашего продукта]” — 他们需要的是配件，而不是你的产品
• 查询涉及材料或组件 — 他们要自己动手，而不是购买成品
• 查询包含“своими руками”“как сделать” — 属于信息需求，而非购买需求
• 查询涉及维修或保养 — 他们已经拥有该产品

示例

查询	表面看来	实际上	是否为目标？
каолиновая вата для дымохода	烟囱买家	棉买家	❌ 否
дымоход купить	烟囱买家	烟囱买家	✅ 是
утепление дымохода	烟囱买家	自行做隔热的人	❌ 否
дымоход сэндвич цена	烟囱买家	烟囱买家	✅ 是
потерпевший дтп	律师客户	新闻读者	❌ 否
юрист после дтп	律师客户	律师客户	✅ 是

工作流更新

1. 在 Wordstat 中查找查询
2. 通过 WebSearch 核验每个有潜力查询的意图
3. 仅在意图与销售目标一致时标记为目标
4. 报告目标查询和排除的查询，并说明理由

工作流

停止！开始任何分析之前：

1. 询问用户所在地区并等待回答：

   "Для какого региона анализировать спрос?
   - Вся Россия (по умолчанию)
   - Москва и область
   - Конкретный город (какой?)"
   

   在用户回答之前不要继续！

2. 询问业务目标：

   "Что именно вы продаёте/рекламируете?
   Это важно для фильтрации нецелевых запросов."
   

收到回答后：

3. 检查连接：bash scripts/quota.sh
4. 使用合适的脚本运行分析
5. 通过 WebSearch 核验每个有潜力查询的意图
6. 展示结果，区分目标和非目标查询

脚本

quota.sh

检查 API 连接。

bash scripts/quota.sh

top_requests.sh

获取热门搜索词。最多支持 2000 条结果，并支持导出为 CSV。

bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --regions "213" \
  --devices "all"

# Extended: 500 results exported to CSV
bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --limit 500 \
  --csv report.csv

# Max results with comma separator
bash scripts/top_requests.sh \
  --phrase "юрист дтп" \
  --limit 2000 \
  --csv full_report.csv \
  --sep ","

参数	必填	默认值	值
--phrase	是	-	带运算符的文本
--regions	否	all	逗号分隔的 ID
--devices	否	all	all、desktop、phone、tablet
--limit	否	50（由该技能设置）	1-2000（映射到 API 的 numPhrases）
--csv	否	-	输出 CSV 文件的路径
--sep	否	;	CSV 分隔符（俄罗斯 Excel 使用 ;）

结果类型：热门搜索词与关联词

输出包含两个部分（标准输出和 CSV 中均有）：

• top（topRequests）——包含你输入词语的查询，按频率排序。这些是搜索查询的直接变体。例如：短语“юрист дтп” → “юрист по дтп”、“консультация юриста по дтп”。
• assoc（associations）——含义相近但不一定包含相同词语的查询，按相似度排序。这些是语义相关的搜索。例如：短语“юрист дтп” → “юридическая ответственность”、“адвокат аварии”。

分析建议： top 结果是你的主要关键词池。assoc 结果有助于扩展语义，但通常会包含噪声——纳入前务必核实搜索意图。

CSV 导出详情

CSV 格式：带 BOM 的 UTF-8，列为：n;phrase;impressions;type。 设置 --csv 后，标准输出会显示每个部分的前 20 行；完整数据会写入文件。

处理大型 CSV 导出文件

将 --limit 设置为较高值（例如 500-2000）时，请使用 CSV 导出并分块读取文件：

# Export 2000 results
bash scripts/top_requests.sh --phrase "query" --limit 2000 --csv data.csv

# Read first 50 rows (header + data)
head -n 51 data.csv

# Read rows 51-100
tail -n +52 data.csv | head -50

# Count total rows
wc -l < data.csv

# Filter only associations
grep ";assoc$" data.csv

这种方法可以让 Agent 处理大型数据集，而不会让标准输出充斥大量内容。

dynamics.sh

获取随时间变化的搜索量趋势。

bash scripts/dynamics.sh \
  --phrase "юрист дтп" \
  --period "monthly" \
  --from-date "2025-01-01"

参数	必填	默认值	值
--phrase	是	-	文本
--period	否	monthly	daily、weekly、monthly
--from-date	是	-	YYYY-MM-DD
--to-date	否	today	YYYY-MM-DD
--regions	否	all	地区 ID
--devices	否	all	all、desktop、phone、tablet

regions_stats.sh

获取地区分布情况。

bash scripts/regions_stats.sh \
  --phrase "юрист дтп" \
  --region-type "cities"

参数	必填	默认值	值
--phrase	是	-	文本
--region-type	否	all	cities、regions、all
--devices	否	all	all、desktop、phone、tablet

regions_tree.sh

显示常用地区 ID。

bash scripts/regions_tree.sh

search_region.sh

按名称查找地区 ID。

bash scripts/search_region.sh --name "Москва"

Wordstat 运算符

引号 "query"

仅显示该确切短语的需求（不包含其他词语）。

"юрист дтп" → "юрист дтп", "юристы дтп"
             but NOT "юрист по дтп"

感叹号 !word

固定确切的词形。

!юрист → "юрист по дтп", "юрист москва"
         but NOT "юристы", "юриста"

组合 "!word !word"

确切短语 + 确切词形。

"!юрист !по !дтп" → only "юрист по дтп"

减号 -word

排除包含该词的查询。

юрист дтп -бесплатно -консультация

分组 (a|b|c)

在一个查询中包含多个变体。

(юрист|адвокат) дтп → combined demand

停用词

始终使用 ! 固定介词：

юрист !по дтп    ← correct
юрист по дтп     ← "по" ignored!

分析策略

1. 宽泛查询：юрист дтп — 查看总搜索量
2. 用引号缩小范围："юрист дтп" — 仅匹配确切短语
3. 固定词形："!юрист !по !дтп" — 确切匹配
4. 用减号清理：юрист дтп -бесплатно -онлайн
5. 扩展：同义词、相关术语、客户问题

常用地区 ID

地区	ID
俄罗斯	225
莫斯科	213
莫斯科及州	1
圣彼得堡	2
叶卡捷琳堡	54
新西伯利亚	65
喀山	43

运行 bash scripts/regions_tree.sh 查看完整列表。

配额和限制

Wordstat 的当前限制请参阅 Yandex Search API 文档。

示例会话

User: Найди запросы для рекламы дымоходов

Claude: Для какого региона анализировать спрос?
        И уточните — вы продаёте готовые дымоходы или
        материалы для их изготовления/утепления?

User: Москва, продаём готовые сэндвич-дымоходы

Claude: [Запускает анализ для региона 213]

        Нашёл запросы. Проверяю интент через веб-поиск...

        ✅ ЦЕЛЕВЫЕ (покупают дымоходы):
        - "дымоход сэндвич купить" — 450 показов
        - "дымоход для бани цена" — 380 показов

        ❌ НЕ ЦЕЛЕВЫЕ (покупают другое):
        - "каолиновая вата для дымохода" — ищут утеплитель, не дымоход
        - "монтаж дымохода своими руками" — DIY, не покупатели
        - "чистка дымохода" — уже владеют, сервисный запрос

要点

1. 始终询问地区并等待回复
2. 始终确认客户具体销售什么
3. 始终通过 WebSearch 核实搜索意图
4. 将报告分为目标和非目标两类，并说明原因

扩展场景

Поиск упущенного спроса

Анализ рекламной кампании Яндекс Директ для нахождения фраз, не покрытых текущей семантикой. Требования: XLSX-выгрузка из Яндекс Директ (лист «Тексты»). Подробнее: MISSED_DEMAND.md