seo-hreflang

示例输出：examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md

Hreflang 审计

改编自 AgriciDaniel/claude-seo 的 seo-hreflang 技能（MIT）。概念和验证规则源自该项目；本实现基于我们的后端（SE Ranking MCP + Firecrawl + WebFetch + 通过 seo-google 使用 Google APIs）重建。

验证多语言或多地区网站上的 hreflang 实现。展示 SE Ranking 审计级别的 hreflang 问题，解析部分页面，检查其实际输出的 <link rel="alternate" hreflang="…"> 标签，并交叉核对站点地图，最终给出三种结论之一——PASS、NEEDS-FIX 或 BROKEN，并附上一份以客观信号为依据的优先修复项表格。

前提条件

• 已连接 SE Ranking MCP 服务。
• 可使用 Claude 的 WebFetch 工具（Firecrawl 不可用时的备用方案）。
• 用户提供：目标域名（例如 example.com）。可选：要检查的代表性页面列表；如果站点地图不在 /sitemap.xml，则提供明确的站点地图 URL。
• **前置步骤（建议）：**已在该域名上运行 seo-technical-audit 或 seo-sitemap。如果尚无现有审计，此技能会创建一份（成本会显著增加）。

流程

1. **验证目标并进行预检。**参见 skills/seo-firecrawl/references/preflight.md，了解标准的 3 阶段预检（积分余额、Firecrawl 可用性、Google APIs）。技能特定说明：

   • 继续前先规范化域名（去除协议和末尾斜杠）。
   • 此技能的 SE Ranking 预计成本：复用现有审计约需 5–10 个 SE Ranking 积分（每个 URL 的清单最多约需 3 个 Firecrawl 积分）。
   • Firecrawl：可选，可回退到 WebFetch；如果可用，约需 6 个 Firecrawl 积分（硬性上限）。可用时，第 4 步（逐 URL hreflang 清单）会使用 formats: ["rawHtml"] 检查首页和 5 个代表性页面。没有 Firecrawl 时，第 4 步会回退到 WebFetch——覆盖范围会降低，因为 WebFetch 只返回 markdown，并会悄然剥离 <head> 中的 <link rel="alternate"> 标签。即使 Firecrawl 可用，也可传入 --no-firecrawl 强制使用 WebFetch。
   • Google APIs：第 1 层（GSC）可启用第 6 步（通过 GSC 验证 hreflang 指向的备用页面）。完整的补充数据约定请参见 skills/seo-google/references/cross-skill-integration.md。

2. 查找或刷新审计 DATA_listAudits → DATA_getAuditStatus

   • 列出该域名的审计。如果存在近期审计（<30 天），则使用该审计。
   • 如果审计超过 30 天，则运行 DATA_recheckAudit 并等待状态变为 done。
   • 如果不存在审计，则先征求用户同意，再使用 DATA_createStandardAudit 创建审计——这会消耗积分。

3. 提取 SE Ranking 的 hreflang 问题 DATA_getAuditReport + DATA_getAuditPagesByIssue

   • SE Ranking 的审计会直接检测 hreflang 错误——应首先将其作为真实依据展示。
   • 从 DATA_getAuditReport 中提取所有代码或类别匹配 hreflang 的问题（常见代码：hreflang_no_return_tag、hreflang_invalid_lang_code、hreflang_conflict、hreflang_missing_x_default、hreflang_canonical_mismatch、hreflang_no_self_reference）。
   • 对于每个重要的 hreflang 问题（数量 ≥ 1），调用 DATA_getAuditPagesByIssue 列出受影响的 URL。
   • 保存至 01-audit-hreflang-issues.md，并纳入 hreflang-issues.csv。

4. 逐 URL hreflang 标签清单 mcp__firecrawl-mcp__firecrawl_scrape（首选）/ WebFetch（备用）

   • **样本选择：**首页 + 最多 5 个来自 DATA_getDomainPages 的代表性页面（按流量降序排列；如果 URL 结构显示了不同语言路径，则优先选择这些页面，例如 /en/、/fr/、/de/ 等）。
   • Firecrawl 路径（每个 URL 消耗 1 个 credit，总计约 6 个）：调用 firecrawl_scrape(url=..., formats=["rawHtml"])。固定使用 rawHtml——默认的 html 后处理会移除许多网站上的 <link rel="alternate">。从 <head> 中解析每个 <link rel="alternate" hreflang="…" href="…">。记录：源 URL、hreflang 属性、href，以及它是否指向自身。
   • WebFetch 备用方案（无 Firecrawl 时）：尝试获取每个 URL，并从 Markdown 响应中提取 hreflang。WebFetch 经常会返回已移除 <head> 链接标签的 Markdown，因此此路径报告的数量会偏少。在 HREFLANG-REPORT.md 中注明：逐 URL 清单：覆盖不完整——未安装 Firecrawl；可能会遗漏部分 hreflang 标签。
   • 应用验证规则（完整列表请参阅 references/validation-rules.md）：
     • **自引用标签：**页面自身的 URL 必须出现在其 hreflang 集合中。
     • **返回标签：**每个备用链接都必须互相对应。如果页面 A 将页面 B 列为 fr，页面 B 必须将页面 A 列为 en（或相应的语言代码）。
     • **x-default：**每个集合中至少有一个备用链接必须使用 hreflang="x-default"。
     • **语言-地区代码验证：**每个值都必须是有效的 ISO 639-1 语言代码（可选地后接 - 和 ISO 3166-1 Alpha-2 地区代码）。常见错误包括：eng（应使用 en）、jp（应使用 ja）、en-uk（应使用 en-GB）、es-LA（不存在此 ISO 地区代码）。
     • **冲突检测：**同一 hreflang 值（例如 de-DE）出现在多个不同 URL 上，即为冲突——Google 会忽略冲突的集合。
     • **规范链接对齐：**如果页面有 <link rel="canonical">，它必须与页面自身的 URL（或其自引用的 hreflang URL）一致。Google 会静默忽略非规范页面上的 hreflang。
     • **协议一致性：**集合中的所有 URL 必须使用相同的协议（优先使用 HTTPS）。
   • 保存到 02-per-url-hreflang.md，并将发现的问题追加到 hreflang-issues.csv。

5. 站点地图级 hreflang（适当时交由 seo-sitemap 处理）

   • 如果用户的域名使用基于站点地图的 hreflang（站点地图中的 <xhtml:link rel="alternate" …>），此技能只检查结构和一致性。完整的站点地图分析（孤立页面、缺失页面、失效条目）由 seo-sitemap 负责——如果工作范围包含站点地图与审计结果的差异比较，请明确推荐使用它。
   • **获取站点地图。**尝试访问 https://{domain}/sitemap.xml；如果返回 404，则获取 /robots.txt 并查找 Sitemap: 指令。对于站点地图索引文件，递归获取每个子文件。
   • 验证站点地图中的 hreflang：
     • 站点地图是否使用 xmlns:xhtml="http://www.w3.org/1999/xhtml" 命名空间？这是在站点地图中使用 hreflang 的必要条件。
     • 每个包含 hreflang 备用链接的 <url> 条目是否都将自身包含在备用链接集合中（自引用）？
     • 每个 <url> 条目中列出的备用链接，是否都在对应 URL 自身的 <url> 条目中以相同的备用链接集合互相对应（返回标签）？
     • 语言-地区代码是否有效（应用步骤 4 中的相同规则）？
   • **与逐 URL 清单交叉核对（步骤 4）：**如果某个样本 URL 的 HTML 列出了 4 个 hreflang 备用链接，而站点地图中该 URL 的条目列出了 6 个，则这种不匹配属于冲突——Google 可能会选择任一结果，而这种不一致会削弱信号。
   • 保存到 03-sitemap-hreflang.md，并将发现的问题追加到 hreflang-issues.csv。

6. GSC 对 hreflang 定向备用页面的验证 （仅当存在 google-api.json 且 tier ≥ 1 时）

   • 对 hreflang 集合中作为 href 目标出现的每个唯一域名（例如 example.com、example.de、example.fr），确认其已通过 GSC 验证： python3 scripts/gsc_query.py --property "{property}" --json（仅检查状态；只需确认该属性有响应，且未出现 PROPERTY_NOT_VERIFIED）。
   • 重要性： Google 明确建议验证参与跨域 hreflang 设置的每个域名。如果 example.de 被列为备用页面，但在此账号中未经验证，hreflang 信号就会减弱，而且你无法了解 Google 如何解读它。
   • 在 HREFLANG-REPORT.md 中以 "## GSC verification of hreflang targets" 为章节标题列出此项，每个目标域名一行：verified / not verified / not configured。
   • 如果目标域名的属性未经验证：将其列为严重性为 Medium 的修复项（"Verify {domain} in Google Search Console — required for cross-domain hreflang trust"）。
   • 有关故障模式约定，请参阅 skills/seo-google/references/cross-skill-integration.md § "Trigger pattern"。

7. 综合判定结果

   • 应用判定启发式（参见 Tips），得出 PASS、NEEDS-FIX 或 BROKEN。
   • 按严重性降序，再按数量降序排列 hreflang-issues.csv。
   • 编写 HREFLANG-REPORT.md，其中包含修复优先级表（前 10 项）和判定结果。

输出格式

创建文件夹 seo-hreflang-{target-slug}-{YYYYMMDD}/，其中包含：

seo-hreflang-{target-slug}-{YYYYMMDD}/
├── 01-audit-hreflang-issues.md   (SE Ranking audit findings filtered to hreflang)
├── 02-per-url-hreflang.md         (per-URL <link rel="alternate"> inventory + validation findings)
├── 03-sitemap-hreflang.md         (sitemap-level hreflang validation; defer details to seo-sitemap)
├── evidence/
│   ├── homepage-rawhtml.html      (raw HTML from Firecrawl, for the homepage sample)
│   ├── sample-{n}-rawhtml.html    (raw HTML for each sampled URL)
│   └── sitemap.xml                (raw fetched sitemap)
├── hreflang-issues.csv            (load-bearing: URL, issue code, severity, fix)
└── HREFLANG-REPORT.md             (PRIMARY: verdict + top fixes table)

HREFLANG-REPORT.md 遵循以下结构：

# Hreflang Audit: {domain}

> Audit date {YYYY-MM-DD} · Sample size: {n} URLs · Languages detected: {comma-separated list}

## Verdict: {PASS | NEEDS-FIX | BROKEN}

Reasoning: {1–2 sentences anchored in concrete numbers from the data}.

## Summary

| Source | Findings | Severity breakdown |
|---|---|---|
| SE Ranking audit | {n} | Critical: {n} · High: {n} · Medium: {n} · Low: {n} |
| Per-URL HTML inventory | {n} | … |
| Sitemap | {n} | … |

## Top fixes (impact-ranked)

| # | URL | Issue | Severity | Fix |
|---|---|---|---|---|
| 1 | {URL} | {issue code} | {severity} | {one-line fix} |
| 2 | … | … | … | … |
| ... up to 10 |

## Languages detected

| Language | URL count | Self-ref OK | Return tags OK | x-default OK |
|---|---|---|---|---|
| en-US | {n} | ✓ / ✗ {count} | ✓ / ✗ | ✓ / ✗ |
| de-DE | {n} | … | … | … |
| ... |

## Per-URL inventory ({n} URLs sampled)

| URL | Alternates | Self-ref | x-default | Notable issues |
|---|---|---|---|---|
| {URL} | {n} | ✓/✗ | ✓/✗ | {short text} |
| ... |

## Sitemap-level hreflang
- xhtml namespace declared: {✓/✗}
- URLs with hreflang alternates: {n}
- Self-reference within sitemap: {✓ all / ✗ {count} missing}
- Return tags within sitemap: {✓ all / ✗ {count} missing}
- Per-URL HTML vs sitemap consistency: {✓ all match / ✗ {count} mismatched}
- Full sitemap-vs-audit analysis: see `seo-sitemap` (orphans, broken entries, lastmod).

## GSC verification of hreflang targets

| Domain | Verified | Notes |
|---|---|---|
| {domain1} | ✓ / ✗ | {note if unverified} |
| ... |

(Or: `GSC verification: not configured (run bash extensions/google/install.sh)`.)

## Coverage notes

- Per-URL inventory tool: {Firecrawl rawHtml | WebFetch fallback (degraded — some hreflang tags may be missed)}.
- Pages sampled: homepage + {n} representative pages (selection: top traffic from `DATA_getDomainPages`).

## Apply

- Walk `hreflang-issues.csv` row-by-row; each row is one specific change (URL + issue + fix).
- After applying changes, re-run `seo-technical-audit` to refresh SE Ranking's findings, then re-run this skill to verify.

hreflang-issues.csv 列：url,issue_code,severity,fix,source，其中 source 是以下之一：audit | html | sitemap | gsc。

提示

• 遵守 SE Ranking Data API 速率限制：10 req/sec。
• 尽可能复用现有审计——创建新审计是这项技能中成本最高的操作。
• 判定启发式：
  • 通过： 严重问题为零；高优先级问题 ≤ 2 个；所有抽样 URL 均包含自引用、x-default 和互惠返回标签；所有语言-地区代码均有效；canonical 与自引用 hreflang 一致。
  • 需要修复： 存在任何高优先级问题；或中优先级问题 > 5 个；或存在以下任一情况（缺少 x-default、> 25% 的抽样页面缺少返回标签、语言-地区代码错误、站点地图与 HTML 不一致）。
  • 已损坏： 存在任何严重问题；或已尝试实现 hreflang，但首页没有自引用；或某页面的 canonical 指向其他位置，但该页面仍输出 hreflang（Google 会忽略整组标签）；或 > 50% 的抽样 URL 缺少返回标签。
• 在 HREFLANG-REPORT.md 中，所有结论都要对应到 hreflang-issues.csv 中的一行。如果利益相关者质疑判定结果，请带他们逐项查看 CSV。
• 对于每页有 > 50 个语言变体的网站，按 URL 实现的 HTML 会使 <head> 膨胀——建议改用基于站点地图的实现。不要生成代码；交付内容是诊断结果，而非代码生成。
• 这项技能不会评估文化适配、内容一致性或地区格式。这些属于翻译/QA 工作，与 hreflang 本身在技术上是否正确无关。如果用户需要这类评估，请引导他们联系翻译团队——这项技能解答的是“技术上的 hreflang 信号是否有效？”，而不是“本地化内容质量如何？”。
• 对于跨域 hreflang（例如 example.com ↔ example.de），第 6 步的 GSC 检查最有价值——验证两个域名是 Google 的明确建议。
• 常见误报防护： 如果抽样页面确实无需国际化（例如单地区网站），那么没有 hreflang 标签就是正确的，不是问题。这项技能会检查是否有任何抽样页面输出 hreflang；如果都没有，判定结果为通过，并附注“未检测到 hreflang 实现——单语言网站。”
• 搭配 seo-sitemap 使用，可比较站点地图与审计结果的差异；搭配 seo-technical-audit 使用，可检查整体技术健康状况。这项技能的范围较窄：仅检查 hreflang 是否正确。
• 完整的问题规则表（严重程度、检测逻辑、建议修复方案）请参阅 references/validation-rules.md。