seo-drift

示例输出：examples/seo-drift-wix-com-20260514/compare/DRIFT-REPORT.md

SEO 漂移

SEO 版 Git。捕获域名或 URL 的 SEO 状态快照（“基线”），之后运行时将当前状态与基线进行差异比较，并呈现退化情况。可发现部署、重新设计或内容清理后悄然恶化的问题。

致谢： 漂移作为 SEO 技能的框架源自 AgriciDaniel 的 claude-seo（原始概念归功于 Dan Colta、Pro Hub Challenge）。双方均采用 MIT 许可；本实现独立开发，但框架构思来自他们。

前提条件

• 已连接 SE Ranking MCP 服务。
• 可使用 Claude 的 WebFetch 工具（用于 URL 模式下的页面指纹识别）。
• 用户提供：目标域名或 URL，以及一个子命令（baseline、compare、history）。

可选标志

标志	模式	效果
--no-firecrawl	baseline, compare	即使已安装 Firecrawl，也跳过基于 Firecrawl 的 <head> + JSON-LD 捕获（节省额度，但会减少 canonical / robots / og:* / JSON-LD 差异覆盖范围）。
--skip-cwv	baseline, compare	即使已配置 google-api.json，也跳过 Google CrUX 捕获（步骤 4b）。适用于只关心内容／结构漂移，或 CrUX 限流顾虑超过 CWV 覆盖需求的情况。与其在 seo-drift/SKILL.md:107, 131 中的设置一致。
--baseline-id <n>	compare	按 ID 指定基线进行比较，而非使用最近的基线。
--limit <n>	history	限制显示的历史条目数量。

子命令

baseline <target>

捕获当前 SEO 状态并将其写入快照文件。不生成差异结果。

compare <target>

加载目标最近的基线。捕获当前状态。进行差异比较。生成 DRIFT-REPORT.md。

history <target>

列出目标的所有已存储基线及其日期和关键指标（DA、流量、关键词数量）。不生成差异结果。

流程

baseline 模式

1. 验证目标。 判断目标是域名还是 URL。域名示例：example.com；URL 是以 http(s):// 开头的任何内容。
   • SSRF 防护（URL 模式）。 如果目标是 URL，请通过 python3 -c "from scripts.google_auth import validate_url; import sys; sys.exit(0 if validate_url('{target}') else 1)" 进行验证（也可以在任意辅助脚本中直接导入 validate_url）。拒绝环回地址（127.0.0.1、::1、localhost）、私有 IP 范围（10/8、172.16/12、192.168/16）、链路本地地址（169.254/16）以及 Google 元数据端点。如果验证失败，则报出明确错误并停止操作，不要继续抓取——将未经验证的 URL 传入 Firecrawl / WebFetch / Google API，可能导致针对内部服务的 SSRF。对应内容见 seo-drift/SKILL.md:97。
2. 预检。 有关规范的三阶段预检（额度余额、Firecrawl 可用性、Google API），请参阅 skills/seo-firecrawl/references/preflight.md。本技能的特定说明：
   • 本技能预计的 SE Ranking 成本：通常基础成本约为 10–20 个 SE Ranking 积分，具体取决于是否包含步骤 4（URL 模式页面快照）。
   • Firecrawl：可选；不可用时回退到 WebFetch。若可用，URL 模式下每个 URL 额外消耗 1 个 Firecrawl 积分。Firecrawl 可用时，快照还会捕获 <head> 和 JSON-LD 内容，因此可通过差异比较检测 canonical / robots / og:* / JSON-LD 的变化。否则快照内容不完整。即使 Firecrawl 可用，也可传入 --no-firecrawl 跳过（节省积分，但差异覆盖范围会缩小）。
   • Google API：第 0 级可捕获 CrUX p75 LCP/INP/CLS（域名模式下为来源级数据，URL 模式下为 URL 级数据）；第 1 级（仅限 URL 模式）还会捕获 URL Inspection 状态（indexStatusVerdict、googleCanonical、lastCrawlTime），以便后续比较时标记字段数据和索引状态的变化。完整操作说明见 skills/seo-google/references/cross-skill-integration.md §「seo-drift」。
3. 域名快照（始终执行）：
   • DATA_getDomainOverviewWorldwide — DA、流量、自然搜索关键词数及付费关键词数。
   • DATA_getDomainKeywords — 排名前 100 的自然搜索关键词及其排名位置。
   • DATA_getBacklinksSummary — 反向链接总数、引荐域名总数。
   • DATA_getBacklinksRefDomains — 权威度最高的前 20 个引荐域名。
4. 页面快照（目标为 URL 时执行）：WebFetch（始终执行）+ mcp__firecrawl-mcp__firecrawl_scrape（可用时执行）
   • WebFetch（免费）：提取 <title>、所有 <h1..h6>、lang、字数、内部链接数、图片数以及正文 Markdown，以便进行文本层级的差异比较。
   • Firecrawl（每个 URL 消耗 1 个 Firecrawl 积分）——恢复 WebFetch 会剥离的 <head> 和 <script> 内容：
     • 从 metadata 中提取：canonical URL、robots meta、og:title、og:description、og:image、twitter:card。
     • 从返回的 html 中提取：每个 <script type="application/ld+json"> 块。记录检测到的 @type 和完整内容的哈希值（这样差异比较不仅能检测类型列表变化，也能检测任何架构内容变化）。
   • 如果 Firecrawl 不可用（或已传入 --no-firecrawl）： 指纹中只包含 WebFetch 字段。BASELINE.md 中注明：仅通过 WebFetch 恢复快照字段 — 后续比较不会检测 canonical、robots、og:*、twitter:* 和 JSON-LD 的变化。安装 Firecrawl 以获得完整覆盖。
   • 对捕获的字段计算指纹哈希值。
   • 同时捕获页面权威度：DATA_getPageAuthority。 4b. Google 字段数据快照 （仅当存在 google-api.json 且未设置 --skip-cwv 时执行）
   • 第 0 级（配置后始终执行）：URL 模式下运行 python3 scripts/pagespeed_check.py "{target}" --crux-only --json；域名模式下运行 python3 scripts/pagespeed_check.py "https://{domain}" --crux-only --json（来源级 CrUX）。存储得出的 p75 LCP / INP / CLS / FCP / TTFB，以及来源标签（“URL”或“origin”）。
   • 第 0 级（配置后始终执行）：运行 python3 scripts/crux_history.py "{target_or_origin}" --json，获取 25 周趋势窗口快照，并存储为 crux_history_baseline。后续比较可检测其与最近一周数据的变化。
   • 第 1 级（仅限 URL 模式）：运行 python3 scripts/gsc_inspect.py "{target_url}" --site-url "{config.default_property}" --json。存储 indexStatusVerdict、coverageState、googleCanonical、userCanonical、lastCrawlTime。
   • 如果已传入 --skip-cwv，则完全跳过此步骤，并将 cwv / crux_history 字段设为 null。比较模式规则随后会显示“字段数据变化：已跳过 — 基线创建时传入了 --skip-cwv 标志。”
   • 如果 CrUX 返回的数据不足，则将受影响的指标设为 null 并继续。
5. 写入快照文件 seo-drift-{target-slug}-{YYYYMMDD}/snapshot.json。
6. 更新索引 seo-drift-{target-slug}/baselines.json — 追加 {date, snapshot_path} 条目。

对比模式

1. 验证目标并定位最新基线，路径为 seo-drift-{target-slug}/baselines.json。
   • SSRF 防护（URL 模式）。 与基线模式使用相同的 validate_url() 检查。拒绝获取私有地址、环回地址和元数据地址。
   • 如果不存在基线，则转入基线模式，并告知用户稍后再回来。
2. 采集当前状态（数据与基线模式相同）。
3. 使用 references/drift-thresholds.md 对每项指标进行差异比较：
   • 域名权威度：±5 = 黄色，±10 = 红色。
   • 估算自然流量：±20% = 黄色，±50% = 红色。
   • 自然关键词数量：±10% = 黄色，±30% = 红色。
   • Top-3 关键词数量：±15% = 黄色，±40% = 红色。
   • Top-100 关键词变动：任何高流量关键词的流失 = 红色。
   • 引荐域名净变化：-5 至 -20 = 黄色，<-20 = 红色。
   • 页面级（URL 模式）：canonical / robots / lang / H1 任一变化 = 红色；标题或 meta description 变化 = 黄色；schema 类型新增或移除 = 黄色；og:* / twitter:* 变化 = 黄色。
   • 依赖 Firecrawl 的差异比较注意事项： canonical / robots / og:* / twitter:* / JSON-LD 差异比较要求基线和当前快照都使用 Firecrawl 采集。如果其中任一快照仅通过 WebFetch 采集，则这些字段会显示为 not comparable — Firecrawl-only fields missing from {baseline | current} snapshot，而非显示为绿色通过。
   • Google 数据漂移（仅当两个快照都包含 Google 字段时）：
     • LCP p75 增加 ≥20% → 红色。
     • INP p75 增加 ≥20% → 红色。
     • CLS p75 绝对值增加 ≥0.05 → 黄色。
     • FCP / TTFB p75 增加 ≥30% → 黄色。
     • 检查状态从 INDEXED 变为其他状态 → 红色。
     • googleCanonical 变化 → 黄色。
     • lastCrawlTime 距今超过 60 天 → 黄色。
     • 注意： 如果任一快照缺少 Google 字段（某次采集时缺少凭据），则显示 Field-data / indexation drift: not comparable — Google fields missing from {baseline | current} snapshot.
4. 汇总 DRIFT-REPORT.md：先列出红色发现，再列出黄色发现，然后列出绿色 / 正向变化。最后给出“优先调查事项”建议。

历史模式

1. 加载 baselines.json。
2. 为每个条目生成一行摘要：日期、DA、流量、关键词数量、Top-3 数量。
3. 将表格写入 HISTORY.md。

输出格式

基线模式

seo-drift-{target-slug}-{YYYYMMDD}/：

seo-drift-{target-slug}-{YYYYMMDD}/
├── snapshot.json            (the captured state)
└── BASELINE.md              (one-page human summary of what was captured)

对比模式

seo-drift-{target-slug}-{YYYYMMDD}/：

seo-drift-{target-slug}-{YYYYMMDD}/
├── DRIFT-REPORT.md              (synthesised: red/yellow/green changes — primary deliverable; inlines 01-domain-deltas, 02-keyword-churn, 03-backlink-deltas, 04-page-deltas as sections)
└── evidence/
    ├── baseline-snapshot.json   (the prior reference — kept for replay)
    ├── current-snapshot.json    (today's state — kept for replay)
    ├── 01-domain-deltas.md      (DA, traffic, keyword count changes — raw step output)
    ├── 02-keyword-churn.md      (top-100 entries/exits)
    ├── 03-backlink-deltas.md    (new + lost backlinks/domains)
    └── 04-page-deltas.md        (URL mode only: HTML fingerprint diff)

顶层仅包含 DRIFT-REPORT.md。四个差异步骤文件会内联到 DRIFT-REPORT.md 的命名章节中；evidence/ 保留原始差异转储和两个快照 JSON，以便未来重新比较或审计时可据此重现。

DRIFT-REPORT.md 结构：

# Drift Report: {target}
> Baseline: {baseline date} · Current: {today's date}

## RED — investigate today
- {finding} ({severity rationale})
- ...

## YELLOW — investigate this week
- {finding}
- ...

## GREEN — positive deltas
- {finding}
- ...

## Field-data drift (CrUX + URL Inspection)
- LCP p75: {baseline} → {current} ms ({Δ%}) {↑ red / ↑ yellow / stable / ↓ green}
- INP p75: {baseline} → {current} ms ({Δ%}) {…}
- CLS p75: {baseline} → {current} ({Δ absolute}) {…}
- Indexation status: {baseline INDEXED → current EXCLUDED} (URL mode)
- googleCanonical: {baseline → current} (if changed)
- (Or: `Field-data / indexation drift: not configured` / `not comparable — missing from {snapshot}`)

## What to investigate first
1. {prioritised action with reasoning}
2. ...

历史模式

seo-drift-{target-slug}-{YYYYMMDD}/HISTORY.md：

# History: {target}

| Date | DA | Traffic | Keywords | Top-3 |
|---|---|---|---|---|
| 2026-04-27 | 42 | 18,500/mo | 1,247 | 89 |
| 2026-03-15 | 41 | 17,200/mo | 1,213 | 85 |
| ...

提示

• 遵守速率限制：10 req/sec。基线检查会依次进行 4–6 次调用，节奏宽松。
• 运行前调用 DATA_getCreditBalance。域名基线约需 10–15 个 SE Ranking 积分；URL 基线约需 15–20 个 SE Ranking 积分 + 1 个 Firecrawl 积分；对比约需 20–30 个 SE Ranking 积分 + 1 个 Firecrawl 积分（捕获当前状态）。
• 在 v0.4.0 中，快照仅存储在本地。如果团队需要共享基线，请让所有人使用共享文件系统中的同一个 seo-drift-{target-slug}/ 目录，或将其提交到私有代码仓库。基线为 JSON 格式，适合使用 git 管理。
• 基线检查频率：每月一次是理想节奏，因为 SE Ranking 的历史数据端点按月提供数据。每周检查对于反向链接数据来说噪声太大。请在交接给团队时说明建议的检查频率。
• 对于部署时“过去一小时内是否出过问题”这类场景，URL 模式下的页面指纹部分是主要工具——它不依赖月度数据。
• 不要根据漂移发现自动拒绝或自动修复任何内容。该技能负责诊断；由人工决策。
• **权威度历史全为零的注意事项：**如果 DATA_getPageAuthorityHistory（URL 模式）或 DATA_getDomainAuthorityHistory 在整个时间范围内都返回全零值，请将其视为“历史数据不足”——不要计算差值，也不要根据缺失数据指出回归。请交叉检查当前值端点（DATA_getPageAuthority / DATA_getDomainOverviewWorldwide）——如果当前值有意义但历史值全为零，请在 DRIFT-REPORT.md 中将其标记为数据质量问题，而不是虚构趋势。
• 什么都不做的代价：悄无声息的回归。每月运行的成本：约 15 个积分。请按月运行。