seo-drift

SEO 漂移监控（2026 年 4 月）

共享数据缓存

步骤 0 —— 检查共享数据缓存：

开始收集前，检查 .seo-cache/ 中是否有相关 SEO 技能可复用的上下文。 参考 ../seo/references/shared-data-cache.md，了解架构和依赖关系图。

存在时，请检查以下缓存文件：

• .seo-cache/site-meta.json：域名、业务类型、行业和抓取上下文

• .seo-cache/audit-scores.json：之前完整审计的优先级

• .seo-cache/pages/{url-slug}/page-analysis.json：提供 URL 时的页面级上下文

• 如果找到：解析并使用明显有效的字段（注明“正在使用缓存的 [X]（日期：[date]）”）

• 如果缺失、损坏或不相关：继续收集新证据

• 如果用户说“refresh”或“re-run”：忽略缓存读取，并在写入时覆盖

为你的 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/codex-seo/drift/baselines.db

表

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

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

---

命令：baseline

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

步骤：

1. 验证 URL（通过 google_auth.validate_url() 防范 SSRF）
2. 通过 scripts/fetch_page.py 获取页面
3. 通过 scripts/parse_html.py 解析 HTML
4. 可选：通过 scripts/pagespeed_check.py 获取 CWV（使用 --skip-cwv 跳过）
5. 对 HTML 正文和架构内容进行哈希处理（SHA-256）
6. 在 SQLite 中存储快照

执行：

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

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

---

命令：compare

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

步骤：

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

执行：

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

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

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

python scripts/drift_report.py <comparison_json_file> --output drift-report.html

---

命令：history

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

执行：

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

**输出：**按时间戳和比较摘要排列的基线 JSON 数组（最新的在前）。

---

跨技能集成

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

发现	建议
架构已移除或修改	运行 /seo schema <url> 进行完整验证
CWV 回归	运行 /seo technical <url> 进行性能审计
标题或元描述已更改	运行 /seo page <url> 进行内容分析
规范链接已更改或移除	运行 /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 获取操作均通过 scripts/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?

写入共享数据缓存

完成所有工作后，如果工作流产生了可长期保留的发现，则将简洁的 JSON 摘要写入 .seo-cache/。 使用 ../seo/references/shared-data-cache.md 中的架构和命名规则；至少包含 cache_type、analyzed_at、来源 URL/域名、关键发现、问题、建议和工具限制。如果 .gitignore 中缺少 .seo-cache/，请将其添加进去。