claude-seo 将"Git for SEO"的理念落地为seo-drift子技能与同名分析 Agent（对应 agents/seo-drift.md 与 skills/seo-drift/SKILL.md）：为页面捕获"已知良好"的 SEO 关键元素基线，通过 17 条对比规则检测回归并按时效分级告警。读完本文，你将掌握baseline/compare/history三个核心命令的完整用法、17 条规则的三级严重度语义、SQLite 存储与 URL 规范化机制，以及如何把 drift 结果委托给 schema、technical、content 等子技能做定向处置——可用于发布前后巡检、持续监控与流量下降归因三大场景。

一、为什么 SEO 需要"版本控制"

页面重构、CMS 升级、A/B 实验、CDN 配置变更、第三方脚本接入……线上页面的任何一次改动都可能悄悄破坏 SEO 关键要素：structured data 被删除、canonical 被改错、meta robots 意外出现noindex、H1 被重构掉。这些问题往往要等 Search Console 数据滞后数周才暴露，届时排名和流量损失已经发生。

seo-drift的思路与 Git 完全同构：先提交基线（baseline），再对比当前状态（compare），最后查看变更历史（history）。它捕获的字段覆盖了 on-page SEO 的核心要素（详见 skills/seo-drift/SKILL.md）：

设计理念原封不动地体现在 scripts/drift_baseline.py 中：fetch_page_data()先调用fetch_page.py抓取 HTML，再调用parse_html.py解析结构化元素；hash_content()对 HTML 正文与 JSON-LD 内容（json.dumps(schema, sort_keys=True)）分别计算 SHA-256 哈希；status_code则从fetch_page.py的 stderr 中正则提取（Status:\s*(\d+)）。这意味着 drift 监控复用的是整个项目已验证的抓取与解析管线，而不是另起炉灶。

二、三个核心命令：baseline / compare / history

1. baseline：捕获"已知良好"的快照

python3 scripts/drift_baseline.py <url> python3 scripts/drift_baseline.py <url> --skip-cwv

--skip-cwv用于跳过 PageSpeed 抓取（更快，且不消耗 PageSpeed Insights API 配额）。执行步骤（对应 skills/seo-drift/SKILL.md 的 Command 章节）：

1. 通过google_auth.validate_url()校验 URL（SSRF 防护）；
2. 经scripts/fetch_page.py抓取页面；
3. 经scripts/parse_html.py解析 HTML；
4. 可选：经scripts/pagespeed_check.py抓取 CWV（--skip-cwv跳过）；
5. 计算 HTML 正文与 schema 内容的 SHA-256 哈希；
6. 快照写入 SQLite。

输出为 JSON，包含baseline_id、时间戳、规范化后的 URL，以及各元素的摘要（title、meta 描述前 80 字符、h1、h2/h3/schema/OG 数量、cwv_captured布尔值等），详见 scripts/drift_baseline.py。

注意：即使页面返回 4xx/5xx，也应当照常捕获基线——因为状态码本身就是一个被追踪的字段（见下文 Rule 8）。若 CWV 抓取失败（如未配置 API Key），对应字段存null，对比时相关规则自动跳过。

2. compare：对比当前状态与基线

python3 scripts/drift_compare.py <url> python3 scripts/drift_compare.py <url> --baseline-id 5 python3 scripts/drift_compare.py <url> --skip-cwv

• 默认对比最近一条基线；--baseline-id可指定历史任意一条基线做定向比对；
• 运行全部 17 条对比规则，按严重度分类，结果写入comparisons表；
• 输出 JSON 包含triggered_findings（已触发规则及其 old/new 值）与untriggered_findings（未触发规则），summary汇总三类严重度计数（见 scripts/drift_compare.py）。

命令行在 stderr 上还会输出人类可读的结论，例如*** 2 CRITICAL finding(s) ***或No drift detected. Page matches baseline.（scripts/drift_compare.py）。

对比完成后可以生成 HTML 报告分享给干系人：

python3 scripts/drift_report.py <comparison_json_file> --output drift-report.html # 或从 stdin 读取： echo '{"status":"ok",...}' | python3 scripts/drift_report.py --stdin --output drift-report.html

报告采用 claude-seo 配色，顶部有整体状态横幅（DRIFT DETECTED / CHANGES DETECTED / MINOR CHANGES / NO DRIFT），每张 finding 卡片按严重度着色并展示 Before/After 差异，底部列出全部未触发的通过项（scripts/drift_report.py）。

3. history：查看变更时间线

python3 scripts/drift_history.py <url> python3 scripts/drift_history.py <url> --limit 10

--limit默认 20。输出 JSON 数组：baselines（最新在前，含 id、timestamp、title、canonical、robots、h1、status_code、哈希摘要、是否含 CWV）与 comparisons（含每次对比的 critical/warning/info 计数），见 scripts/drift_history.py。若数据库不存在，会提示先运行drift baseline。

三、17 条对比规则与三级严重度

对比引擎的核心依据是 skills/seo-drift/references/comparison-rules.md，完整实现了 scripts/drift_compare.py 中编号rule_01到rule_17的 17 个函数。

CRITICAL（立即处理，通常数天内造成可测量的流量损失）

WARNING（一周内调查，可能是故意为之）

INFO（仅记录，常为正向或中性变化）

四、存储与 URL 规范化

所有数据存储在本地 SQLite：

~/.cache/claude-seo/drift/baselines.db

初始化时启用 WAL 模式并建两张表（scripts/drift_baseline.py）：

• baselines：快照，含全部 SEO 元素字段，按url_hash建索引；
• comparisons：对比结果，含results_json与三类严重度计数，外键关联baselines(id)，同样按url_hash建索引。

为了"同一条 URL 稳定匹配"，normalize_url()执行如下规范化（scripts/drift_baseline.py）：

• scheme 与 host 转小写；
• 剥掉默认端口（http:80、https:443）；
• 查询参数排序；
• 移除 UTM 参数（utm_source/utm_medium/utm_campaign/utm_term/utm_content）；
• 去除尾部斜杠（裸域名除外）。

url_hash()取规范化 URL 的 SHA-256 前 16 位十六进制字符作为关联键（scripts/drift_baseline.py）。因此https://example.com/?b=2&a=1&utm_source=x与http://Example.com/a=1&b=2/会被归一到同一条记录，避免因参数顺序、大小写和跟踪参数导致的"幽灵基线"。

五、Agent 工作流与跨技能委托

作为分析 Agent（见 agents/seo-drift.md），seo-drift只在"该 URL 已存在基线"时被唤起，执行三步工作流：

1. Baseline：捕获当前 SEO 状态并以 SHA-256 哈希存入 SQLite；
2. Compare：抓取当前状态，运行 17 条规则 × 3 个严重级，输出全部触发规则的 old/new 值；
3. History：查询该 URL 的全部基线与对比记录，呈现时间线。

检测到 drift 后，Agent 按规则类型推荐对应的子技能做定向处置：

Agent 的最终输出包括：摘要行（CRITICAL / WARNING / INFO 各多少）、所有触发规则的 severity + old + new + action 表格、针对 CRITICAL/WARNING 的跨技能建议，以及可选的 HTML 报告。若审计编排器提供了output_dir，还会持久化output_dir/findings/drift.md与audit-data.json中的 SEO Drift 分类发现（agents/seo-drift.md）。

六、错误处理与安全边界

错误处理矩阵

安全要点

• 所有抓取均经scripts/fetch_page.py，强制 SSRF 防护（拦截私有 IP、loopback、保留地址段、GCP metadata 端点）；Agent 提示词明确禁止使用 curl、wget 或裸 HTTP 请求（agents/seo-drift.md）。
• validate_url是url_safety.validate_url的向后兼容包装，共享模块还提供 DNS-rebinding 安全的validate_url_strict与safe_requests_get，供fetch_page.py在建立 socket 前调用（scripts/google_auth.py）。
• 所有 SQLite 查询使用参数化占位符?，绝不做字符串拼接——这在load_baseline、历史查询、写入语句中处处可见。
• TLS 始终校验，管线中不存在verify=False。

七、典型实战工作流

发布前后巡检（Pre/Post Deployment Check）

/seo drift baseline https://example.com # 发布前 # ... 发布动作 ... /seo drift compare https://example.com # 发布后

在发布窗口前捕获基线、发布后立即对比，任何 CRITICAL（如 schema 丢失、canonical 变更）都能在影响被搜索引擎收录之前定位。

持续监控（Ongoing Monitoring）

/seo drift baseline https://example.com # 首次捕获 # ... 数周后 ... /seo drift compare https://example.com # 检查是否漂移 /seo drift history https://example.com # 回看全部变更

适合对高价值页面（首页、核心落地页、产品详情页）做定期巡检，WARNING 级别的 CWV 回退与性能得分下滑也能在两周观察窗口内被发现。

流量下降归因（Investigating a Traffic Drop）

/seo drift compare https://example.com # 什么变了？ /seo drift history https://example.com # 什么时候变的？

先用 compare 看"变化内容"，再用 history 看"变化时间点"，与 GSC 数据中的流量拐点对齐，即可快速判断流量下滑是否由 on-page 回归导致。

八、源码级的可靠性保证

从源码结构看，seo-drift的可靠性设计贯穿三层：

• 复用已验证管线：drift_baseline/drift_compare直接复用fetch_page.py+parse_html.py+pagespeed_check.py，保证与项目其它 SEO 工具行为一致，避免"两套解析逻辑、两套结果"。
• 可测试性：tests/test_drift_portability.py专门验证fetch_page_data()的跨平台可移植性——断言子进程调用使用临时文件而非/dev/stdout、编码为 UTF-8、错误用replace策略、命令不包含input参数、临时文件用后即清。这类测试守护的是"抓取握手协议"不被无意破坏。
• 容错设计：CWV 缺失时规则跳过而非整体失败；对比结果写库失败仅产生db_warning而不阻断输出；数据库首次使用自动创建。这让 drift 监控在 API 配额耗尽、页面超时等现实干扰下依然能给出可用的比较结论。

结合 skills/seo-drift/SKILL.md 提供的完整规则集（skills/seo-drift/references/comparison-rules.md）与 scripts/drift_report.py 的可分享 HTML 报告，seo-drift可以无缝嵌入 claude-seo 的发布流程与周期性审计中——把"线上页面悄悄变坏"从不可见的事故，变成可量化、可追溯、可立即处置的工程问题。