seo-drift

SEO 漂移监控（2026 年 4 月）

为 SEO 做 Git。记录基线、检测回归、追踪随时间发生的变化。

---

命令

命令	用途
/seo drift baseline <url>	将当前 SEO 状态记录为“已知良好”快照
/seo drift compare <url>	将当前页面状态与存储的基线进行比较
/seo drift history <url>	显示变更历史和以往的比较结果

---

捕获内容

每个基线都会记录以下 SEO 关键元素：

元素	字段	来源
标题标签	title	parse_html.py
Meta 描述	meta_description	parse_html.py
规范 URL	canonical	parse_html.py
Robots 指令	meta_robots	parse_html.py
H1 标题	h1（数组）	parse_html.py
H2 标题	h2（数组）	parse_html.py
H3 标题	h3（数组）	parse_html.py
JSON-LD 架构	schema（数组）	parse_html.py
Open Graph 标签	open_graph（字典）	parse_html.py
Core Web Vitals	cwv（字典）	pagespeed_check.py
HTTP 状态码	status_code	fetch_page.py
HTML 内容哈希	html_hash（SHA-256）	计算得出
架构内容哈希	schema_hash（SHA-256）	计算得出

---

比较方式

比较引擎会应用 3 个严重级别下的 17 条规则。加载 references/comparison-rules.md，查看包含阈值、 建议操作和跨技能参考的完整规则集。

严重级别

级别	含义	响应时间
CRITICAL	可能导致流量损失的 SEO 破坏性变更	立即
WARNING	可能产生影响，需要调查	1 周内
INFO	仅供知悉，可能是有意为之	方便时查看

---

存储

所有数据都存储在本地 SQLite 中：

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

表

• baselines：包含所有 SEO 元素的已捕获快照
• comparisons：包含触发规则和严重级别的差异结果

URL 规范化可确保匹配一致：方案和主机名转为小写，去除默认端口（80/443），对查询参数排序，移除 UTM 参数，去除末尾斜杠。

---

命令：baseline

捕获页面的当前状态并进行存储。

步骤：

1. 验证 URL（通过 google_auth.validate_url() 防护 SSRF）
2. 通过 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run fetch_page.py <URL> 获取页面
3. 通过 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run parse_html.py <URL> 解析 HTML
4. 可选：通过 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run pagespeed_check.py <URL> 获取 CWV（使用 --skip-cwv 跳过）
5. 计算 HTML 正文和架构内容的哈希（SHA-256）
6. 将快照存入 SQLite

执行：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_baseline.py <url>
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_baseline.py <url> --skip-cwv

**输出：**包含基线 ID、时间戳、URL 和已捕获元素摘要的 JSON。

---

命令：compare

获取页面当前状态，并与最近的基线进行差异比较。

步骤：

1. 验证 URL
2. 从 SQLite 加载最近的基线（或指定的 --baseline-id）
3. 获取并解析页面当前状态
4. 运行全部 17 条比较规则
5. 按严重级别对发现进行分类
6. 存储比较结果
7. 输出 JSON 差异报告

执行：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_compare.py <url>
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_compare.py <url> --baseline-id 5
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_compare.py <url> --skip-cwv

**输出：**包含所有触发的规则、新旧值、严重级别和操作建议的 JSON。

比较完成后，提供生成 HTML 报告的选项：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_report.py <comparison_json_file> --output drift-report.html

---

命令：history

显示某个 URL 的所有基线和比较结果。

执行：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_history.py <url>
"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run drift_history.py <url> --limit 10

**输出：**包含各基线（按时间从新到旧排列）的 JSON 数组，其中包含时间戳和比较摘要。

---

跨技能集成

检测到偏移时，推荐使用相应的专业技能：

发现	建议
Schema 已移除或修改	运行 /seo schema <url> 进行完整验证
CWV 出现退化	运行 /seo technical <url> 进行性能审计
标题或 meta description 已更改	运行 /seo page <url> 进行内容分析
Canonical 已更改或移除	运行 /seo technical <url> 检查可索引性
已添加 noindex	运行 /seo technical <url> 进行可抓取性审计
H1/标题结构已更改	运行 /seo content <url> 进行 E-E-A-T 审查
OG 标签已移除	运行 /seo page <url> 进行社交分享分析
状态码已更改为错误码	运行 /seo technical <url> 进行完整诊断

---

错误处理

情况	操作
URL 无法访问	报告 fetch_page.py 返回的错误。不要猜测状态。建议用户验证 URL。
URL 没有基线	告知用户并建议先运行 baseline。
SSRF 拦截（私有 IP）	报告 validate_url() 拒绝请求。绝不绕过。
SQLite 数据库缺失	首次使用时自动创建。不报错。
CWV 获取失败（没有 API 密钥）	将 CWV 字段存储为 null。比较时跳过 CWV 规则。
页面返回 4xx/5xx	仍将其记录为基线（状态码本身就是受跟踪字段）。
存在多个基线	除非指定 --baseline-id，否则使用最新的基线。

---

安全性

• 所有 URL 获取操作都通过 "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run fetch_page.py 执行，该脚本会实施 SSRF 防护 （拦截私有 IP、回环地址、保留地址范围和 GCP 元数据端点）
• 不使用 curl，不调用子进程进行 HTTP 请求——仅使用项目经过验证的获取流程
• 所有 SQLite 查询都使用参数化占位符（?），绝不使用字符串插值
• 始终验证 TLS——流程中任何地方都不会出现 verify=False

---

典型工作流

部署前/后检查

/seo drift baseline https://example.com     # Before deploy
# ... deploy happens ...
/seo drift compare https://example.com      # After deploy

持续监控

/seo drift baseline https://example.com     # Initial capture
# ... weeks later ...
/seo drift compare https://example.com      # Check for drift
/seo drift history https://example.com      # Review all changes

调查流量下降

/seo drift compare https://example.com      # What changed?
/seo drift history https://example.com      # When did it change?