名称： seo-dataforseo
描述： "使用 DataForSEO API 进行 SEO 关键词研究。执行关键词分析、YouTube 关键词研究、竞争对手分析、SERP 分析及趋势追踪。适用于用户需要：研究关键词、分析搜索量/CPC/竞争度、获取关键词建议、检查关键词难度、分析竞争对手、获取热门话题、进行 YouTube SEO 研究或优化落地页关键词的场景。需要一个 DataForSEO API 账户，并将凭证配置在 .env 文件中。"

SEO 关键词研究 (DataForSEO)

环境设置

安装依赖：

pip install -r scripts/requirements.txt

在项目根目录创建 .env 文件并配置凭证：

DATAFORSEO_LOGIN=your_email@example.com
DATAFORSEO_PASSWORD=your_api_password

从以下网址获取凭证：https://app.dataforseo.com/api-access

快速开始

通过从 scripts/main.py 导入并执行函数：

import sys
from pathlib import Path
sys.path.insert(0, str(Path("scripts")))
from main import *

result = keyword_research("AI 网站构建工具")

工作流程模式

每项研究任务都遵循以下三个阶段：

1. 研究

运行 API 函数。每次函数调用都会请求 DataForSEO API 并返回结构化数据。

2. 自动保存

所有结果会自动保存为带时间戳的 JSON 文件到 results/{类别}/ 目录。文件命名模式：YYYYMMDD_HHMMSS__操作__关键词__额外信息.json

3. 总结

研究完成后，读取保存的 JSON 文件，并在 results/summary/ 目录下创建一个 Markdown 总结报告，包含数据表格、排序后的机会点以及战略建议。

核心功能函数

这些是 scripts/main.py 中的主要函数。每个函数都协调多个 API 调用，以完成一个完整的研究工作流。

参数说明

所有函数都接受一个可选的 location_name 参数（默认值："United States"）。大多数函数还有布尔标志，用于跳过特定的子分析（例如 include_suggestions=False）。

独立 API 函数

如需更细粒度的控制，可从 API 模块导入特定函数。完整列表（共 25 个 API 函数，包含参数、限制和示例）请参阅 references/api-reference.md。

结果存储

结果自动保存到 results/ 目录，结构如下：

results/
├── keywords_data/    # 搜索量、CPC、竞争度
├── labs/             # 建议、难度、意图
├── serp/             # Google/YouTube 排名
├── trends/           # Google 趋势数据
└── summary/          # 人类可读的 Markdown 总结报告

管理结果

from core.storage import list_results, load_result, get_latest_result

# 列出最近的结果
files = list_results(category="labs", limit=10)

# 加载特定结果
data = load_result(files[0])

# 获取某操作的最新结果
latest = get_latest_result(category="labs", operation="keyword_suggestions")

实用函数

from main import get_recent_results, load_latest

# 列出所有类别中的最近文件
files = get_recent_results(limit=10)

# 加载某个类别的最新结果
data = load_latest("labs", "keyword_suggestions")

创建总结报告

运行研究后，在 results/summary/ 目录下创建一个 Markdown 总结文档。内容应包括：

• 数据表格：包含搜索量、CPC、竞争度、难度等。
• 排序列表：按搜索量或机会分数排序的机会点。
• SERP 分析：展示当前排名情况。
• 建议：针对内容策略、标题、标签等的建议。

请为总结文件起一个描述性的名称（例如 results/summary/ai-tools-keyword-research.md）。

实用建议

1. 具体明确 — "获取 'AI 网站构建工具' 的关键词建议" 比 "研究 AI 相关内容" 效果更好。
2. 请求总结 — 研究完成后，务必创建一个命名具体的总结文档。
3. 批量处理相关关键词 — 一次性传入多个相关关键词进行比较分析。
4. 明确目标 — "用于 YouTube 视频" 和 "用于落地页" 所关注的数据重点不同。
5. 要求竞争分析 — "展示当前排名靠前的视频" 有助于发现内容空白。

默认设置

• 地点：美国 (代码 2840)
• 语言：英语
• API 限制：搜索量/概览 700 个关键词，难度/意图 1000 个，趋势 5 个，关键词创意 200 个。