growth-report

SEO 性能报告技能

使用实时 DataForSEO 数据生成一份全面的 3 个月 SEO 性能 HTML 报告。 报告涵盖流量趋势、关键词排名、热门内容集群、竞争定位、战略重点和执行摘要—— 全部采用 Infrasity 品牌设计体系。

---

步骤 0 — 开始之前收集所有输入

四项输入均为必填项。 在确认全部四项之前，不要调用任何 API。

请在一条消息中按以下确切格式收集所有信息——一次性询问所有内容，切勿逐项询问：

---

如果用户尚未提供全部四项输入，请询问：

要生成报告，我需要 4 项信息：

1. 目标域名 — 要生成报告的网站，例如 firefly.ai
2. 竞争对手域名 — 最多 5–6 个竞争对手，例如 spacelift.io, env0.com, terraform.io
3. 日期范围 — 3 个月时间段的开始和结束日期 （默认：2026 年 2 月 20 日 → 2026 年 5 月 20 日）
4. 地区 — 搜索数据所用的国家 （默认：United States）

你希望更改哪些默认设置？

---

如果用户已提供目标域名和竞争对手（例如“为 firefly.ai 生成 SEO 报告，对比 spacelift.io、env0.com”），请确认另外两项：

明白了——我将为 firefly.ai 生成报告，对比 spacelift.io、env0.com。

请确认以下默认设置：

• 日期范围： 2026 年 2 月 20 日 → 2026 年 5 月 20 日
• 地区： United States

可以按这些设置继续吗？还是你想更改其中一项？

---

输入解析规则：

输入	规则
TARGET_DOMAIN	去掉 https://、http://、www. 和末尾斜杠。仅保存裸域名（例如 firefly.ai）
COMPETITORS	去掉每个域名的相同前缀。接受逗号分隔或空格分隔的列表。最少 2 个，最多 6 个竞争对手。
START_DATE	将任意人类可读的日期格式解析为 YYYY-MM-DD。默认值：2026-02-20
END_DATE	将任意人类可读的日期格式解析为 YYYY-MM-DD。默认值：2026-05-20
LOCATION	接受国家名称。默认值：United States。必须是有效的 DataForSEO location_name（只能使用完整国家名称，不得使用城市或地区名称）。

确认后，在继续操作前清楚地回显解析后的输入：

✓ 目标： firefly.ai ✓ 竞争对手： spacelift.io, env0.com, controlmonkey.io, scalr.com, terraform.io ✓ 日期范围： 2026 年 2 月 20 日 → 2026 年 5 月 20 日 ✓ 地区： United States

正在获取数据……

---

重要 API 设置

每次调用 DataForSEO 时都必须使用 ignore_synonyms: false。 使用默认值 ignore_synonyms: true 会导致流量和关键词数量低估 30–50%。 这是最重要的参数——绝不能省略。

---

步骤 1 — 基线指标

调用 dataforseo_labs_google_historical_rank_overview，并传入：

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

在返回的月度数组中，查找最接近 START_DATE 的快照（按年份和月份匹配）。 提取并保存：

• baseline_traffic = metrics.organic.etv
• baseline_keywords = metrics.organic.count
• baseline_top3 = metrics.organic.pos_1 + metrics.organic.pos_2_3

⚠️ DataForSEO 中没有 pos_1_3 字段。Top 3 始终要通过 pos_1 + pos_2_3 计算。

同时提取 START_DATE 和 END_DATE 之间的所有月度快照，用于报告中的流量趋势条形图 （通常为 3–4 个数据点）：

• 为每个快照保存：month_label（例如“2026 年 2 月”）、etv、year、month
• 按日期升序排序
• 这些数据将成为 HTML 模板中的 TREND_LABEL_1..4、TREND_ETV_1..4

---

步骤 2 — 当前指标

调用 dataforseo_labs_google_domain_rank_overview，参数如下：

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

从 metrics.organic 中提取：

• current_traffic = etv
• current_keywords = count
• current_top3 = pos_1 + pos_2_3
• current_pos_1 = pos_1
• current_pos_2_3 = pos_2_3
• current_pos_4_10 = pos_4_10
• current_pos_11_20 = pos_11_20
• current_pos_21_100 = pos_21_30 + pos_31_40 + pos_41_50 + pos_51_60 + pos_61_70 + pos_71_80 + pos_81_90 + pos_91_100 的总和

计算所有增减值：

traffic_growth_pct  = ((current_traffic - baseline_traffic) / baseline_traffic) * 100
keywords_change     = current_keywords - baseline_keywords
keywords_change_pct = (keywords_change / baseline_keywords) * 100
top3_growth_pct     = ((current_top3 - baseline_top3) / baseline_top3) * 100

格式规则：

• 正值前加 +，负值会自动显示 -
• 所有百分比四舍五入至 1 位小数
• 正向增减值添加 pos CSS 类，负向增减值添加 neg

---

步骤 3 — 竞争格局

3a — 当前流量概览

调用 dataforseo_labs_bulk_traffic_estimation，参数如下：

targets:         [TARGET_DOMAIN, ...COMPETITORS]   ← all domains in a single API call
location_name:   LOCATION
language_code:   en
item_types:      ["organic"]
ignore_synonyms: false

对于返回的每个域名，提取：etv、count。

按 etv 降序排列所有域名。将流量最高的域名排为第 1 名。 确定：

• competitive_rank = TARGET_DOMAIN 的排名（1 = 第 1 名）
• total_domains = 表格中所有域名的总数
• domain_above = 排名比 TARGET_DOMAIN 高一位的域名（如果有）
• domain_below = 排名比 TARGET_DOMAIN 低一位的域名（如果有）
• gap_to_next_above = domain_above 的 etv − current_traffic（如果 TARGET_DOMAIN 排名第 1，则为 0）
• lead_over_next_below = current_traffic − domain_below 的 etv（如果 TARGET_DOMAIN 排名最后，则为 0）

3b — 竞争对手趋势信号（历史数据，选项 1）

对于每个竞争对手（不包括目标域名），调用 dataforseo_labs_google_historical_rank_overview：

target:          COMPETITOR_DOMAIN
location_name:   LOCATION
language_code:   en
ignore_synonyms: false

从返回的月度数组中：

• 找出最接近 START_DATE 的快照 → 提取 comp_baseline_etv
• 找出最接近 END_DATE 的快照 → 提取 comp_current_etv
• 计算：comp_trend_pct = ((comp_current_etv - comp_baseline_etv) / comp_baseline_etv) * 100

趋势徽标分配规则（±5% 稳定阈值）：

条件	徽标	CSS 类
comp_trend_pct > +5%	↑ +X.X%	trend-up（绿色）
comp_trend_pct < -5%	↓ -X.X%	trend-down（红色）
-5% ≤ comp_trend_pct ≤ +5%	→ Stable (X.X%)	trend-stable（灰色）

竞争对比表中 TARGET_DOMAIN 的趋势也必须使用相同的 START_DATE → END_DATE 时间范围，以确保一致性。步骤 1 中获取的历史数据已包含这些信息：

• target_table_trend_pct = ((end_date_snapshot_etv - baseline_traffic) / baseline_traffic) * 100

其中，end_date_snapshot_etv 是步骤 1 历史数组中最接近 END_DATE 的快照所对应的 ETV（不是步骤 2 中的实时数值 current_traffic）。

应用相同的 ±5% 阈值规则，确定目标域名的趋势徽标。

⚠️ 步骤 2 中的 traffic_growth_pct（基线 → 实时）用于时间线卡片、增减徽标和执行摘要，但不用于竞争对比表的趋势列。 竞争对比表的趋势列对所有域名（包括目标域名）使用 target_table_trend_pct（START_DATE → END_DATE），以确保比较一致、公平。

⚠️ 未运行此计算前，绝不能将任何竞争对手的趋势默认设为“Stable”。 竞争对比表中的每个趋势徽标都必须根据真实的历史 ETV 数据得出。

---

步骤 4 — 顶级内容集群

调用 dataforseo_labs_google_relevant_pages，参数如下：

target:          TARGET_DOMAIN
location_name:   LOCATION
language_code:   en
order_by:        ["metrics.organic.etv,desc"]
limit:           3
ignore_synonyms: false

对于排名前 3 的页面，提取：

• page_address — 缩短显示 URL：移除 https://www. 前缀，保留路径
• metrics.organic.etv → page_etv（使用逗号分隔，四舍五入至最接近的整数）
• metrics.organic.count → page_keywords

首页集中度检查： 如果 page_1_etv / current_traffic > 0.80，则将 homepage_concentration = true。 这会触发执行摘要中的特定段落。

---

步骤 5 — 推导报告目标（Q2 卡片）

IF traffic_growth_pct >= 0:
  traffic_goal   = round(current_traffic * (1 + traffic_growth_pct/100))
ELSE:
  traffic_goal   = round(baseline_traffic * 0.9)   ← recovery target

keywords_goal    = max(round(current_keywords * 1.2), round(baseline_keywords * 0.95))
top3_goal        = round(current_top3 * 1.3)

IF competitive_rank == 1:
  target_badge = "Maintain #1"
ELSE:
  target_badge = "Challenge #" + str(competitive_rank - 1)

traffic_goal 的格式示例：62,000+。四舍五入至最接近的千位，以便清晰呈现。

---

步骤 6 — 推导战略优先级卡片

始终生成恰好 6 张卡片。每张卡片的描述都必须使用实际数据值，不得使用泛泛的文本。 在相关情况下，引用步骤 3b 中的竞争对手趋势数据，以丰富卡片描述。

#	卡片标题公式	内容规则
1	"缩小与 #[rank_above] 的差距"	写出 domain_above，说明 gap_to_next_above 的 ETV 及其趋势标记（增长/下降）。如果趋势下降，则将其描述为窗口期正在收窄的机会。
2	"防范 / 关注 [domain_below 或增长最快的竞争对手]"	如果排名较低的竞争对手增长迅速（>+20%），则将其标记为新兴威胁。否则，写出 domain_below，并说明 lead_over_next_below。
3	流量恢复或规模增长	如果流量下降："扭转 [X]% 的跌幅"，并将 pos_4_10 数量作为潜在增长来源。如果流量增长："保持 [X]% 的增长势头"，并说明市场背景（例如，大多数竞争对手都在下降）。
4	"扩大头部内容集群"	引用 page_1 URL 及其 ETV；如果首页流量集中度为 true，则予以标记
5	"恢复/扩大关键词覆盖范围"	使用 keywords_change 作为需要恢复的具体数量或扩大的具体数量
6	"将排名第 4–10 位的关键词推入前 3 名"	使用当前的 current_pos_4_10 数量；说明转化其中 20% 可新增约 N 个排名前 3 的关键词

---

步骤 7 — 编写执行摘要（4 段）

自然行文；段落内不要使用项目符号。所有数字都必须来自实际 API 值。

• 第 1 段： 总体结果。说明 traffic_growth_pct，以及所有 total_domains 中的 competitive_rank。说明竞争对手的趋势分布（根据步骤 3b 得出增长、持平或下降的数量），并指出目标域名是否增长最快。写出排名紧邻其上方和下方的域名、各自的 ETV 及趋势方向。

• 第 2 段： 如果 homepage_concentration = true：指出 X% 的流量来自单个页面， 并将其描述为风险，同时也是实现流量来源多元化的机会。 否则：描述内容广度优势——关键词数量与竞争对手相比如何。

• 第 3 段： 排名前 3 的关键词趋势（top3_growth_pct）。指出 keywords_change——如果为负数， 说明具体损失数量，并强调应尽快夺回这些关键词。如果为正数，则称其为增长势头。

• 第 4 段： Q2 策略。指出需要弥合的具体差距（gap_to_next_above）、需要追赶的竞争对手（domain_above），以及该竞争对手的趋势是增长还是下降。如果 domain_above 正在下降，则将这一机会描述为窗口期正在收窄。根据数据，指出最具影响力的恢复或规模增长行动。

判断增长最快的对象 — 将 target_table_trend_pct 与步骤 3b 中所有竞争对手的 comp_trend_pct 值进行比较。如果 TARGET_DOMAIN 的趋势百分比在整个集合中最高，则设置 is_fastest_growing = true。在第 1 段和摘要徽章中使用此结果。

摘要徽章格式： 排名 #[competitive_rank] | [current_traffic_K]K 流量 | [traffic_growth_pct]% 增长 | [current_top3] 个排名前 3 的关键词 | [增长最快 / 下降 / 持平]

最后一个标签的取值规则：

• 如果 is_fastest_growing = true，则为“增长最快”
• 如果 traffic_growth_pct > 5% 且并非增长最快，则为“增长”
• 如果 traffic_growth_pct < -5% 且并非增长最快，则为“下降”
• 如果 -5% <= traffic_growth_pct <= +5% 且并非增长最快，则为“持平”

---

步骤 8 — 生成 HTML 报告

阅读 references/html-template.md，了解完整的 HTML 结构、CSS 和变量映射。

模板仅使用 Infrasity 品牌设计系统：

• 背景：#0D0A1A（黑紫色）——不得使用白色或其他深色
• 主强调色：#8157F2——唯一的强调色；不得替换为蓝色或绿色
• 字体：所有标题 / KPI 数值 / 章节编号使用 Instrument Sans， 所有正文 / 标签 / UI 文本使用 DM Sans，路径 / 代码 / 数据值使用 DM Mono
• 状态颜色：#5DCEA6（正向变化）、#F07070（负向变化）

不得更改、覆盖或混用其他任何配色方案或字体栈。 使用真实数据填充每个 {{VARIABLE}}。将文件输出至：

/mnt/user-data/outputs/{TARGET_DOMAIN}_seo_report.html

然后调用 present_files 将其交付给用户。

---

错误处理

情况	操作
域名通过 bulk_traffic_estimation 返回无数据	在竞争对比表中省略该域名；添加脚注
START_DATE 或 END_DATE 所在月份缺少历史快照	使用最近的可用月份；在报告页脚注明实际使用的日期
baseline_traffic 为 0（除以零）	将 traffic_growth_pct 设为 "N/A"，跳过所有依赖此值的变化徽标，并在报告页脚注明 START_DATE 的基线数据不可用
baseline_top3 为 0（除以零）	将 top3_growth_pct 设为 "N/A"，并跳过变化徽标
comp_baseline_etv 为 0（竞争对手趋势除以零）	在趋势列中将该竞争对手标记为 "N/A"
backlinks_bulk_ranks 返回 40204 错误	不要调用此端点——它需要单独订阅。完全跳过。
ai_opt_llm_ment_agg_metrics 返回 40204 错误	不要包含 AI 引用部分。此功能不在本技能范围内。

---

不要包含的内容

• ❌ 不包含 AI/LLM 引用部分——按设计排除（需要付费的 DataForSEO 附加服务）
• ❌ 不包含 DFS Rank（0–1000）列——按设计排除（需要单独订阅）
• ❌ 不使用 ignore_synonyms: true——始终设为 false，没有例外
• ❌ 不使用占位文本——HTML 中的每个数字都必须来自真实的 API 响应
• ❌ 不逐项询问输入——始终在一条消息中收集所有缺失的输入
• ❌ 不将竞争对手的趋势默认设为 "Stable"——始终根据历史 ETV 对比得出趋势

---

参考文件

• references/html-template.md — 完整的 Infrasity 品牌 HTML 模板，包含 CSS 设计系统、 所有章节标记、竞争对比表行模式，以及完整的变量替换映射。 编写任何 HTML 之前，请务必先阅读此文件。Infrasity 设计是唯一允许的 输出设计——不得使用其他任何配色方案、字体栈或布局。