seo-technical-audit

示例输出：examples/seo-technical-audit-linear-app-20260514/TECH-AUDIT.md

技术审计

针对一个域名的一次性技术 SEO 审计。获取 SE Ranking 的审计数据，按领域（可抓取性、可索引性、安全性、移动端、结构化数据等）归类发现，并在各领域内按严重程度排序，最后按影响 × 工作量排名，生成前 10 项修复清单。

前提条件

• 已连接 SE Ranking MCP 服务。
• 可使用 Claude 的 WebFetch 工具（用于核查 robots.txt 和 sitemap 是否存在）。
• 用户提供：目标域名（例如 example.com）。可选：目标国家（默认 us）、审计页面数量上限覆盖值（默认：沿用现有审计的上限）。

流程

1. 验证目标并进行预检。 请参阅 skills/seo-firecrawl/references/preflight.md，了解标准的三阶段预检（点数余额、Firecrawl 可用性、Google API）。本技能的专属说明：

   • 继续操作前，规范化域名（去除协议和末尾斜杠）。
   • 本技能预计消耗的 SE Ranking 点数：重新检查现有审计的成本较低；创建新审计的成本则高得多，并且因页面数量而异。请在决定前说明成本。
   • Firecrawl：可选。可用时，步骤 8（现代信号清单）会检查 5 个示例 URL 和 /robots.txt，约消耗 6 个 Firecrawl 点数（硬性上限）。不可用时，将跳过步骤 8——无法检查 JS 渲染后的 canonical/noindex 差异、X-Robots-Tag 标头和 AI 爬虫 robots 规则分析，但仍会交付完整的技术审计结果。即使 Firecrawl 可用，也可传入 --no-firecrawl 跳过步骤 8（节省点数）。
   • Google API：第 0 层可启用步骤 8b（CrUX 实地数据）；第 1 层还可启用步骤 8c（对流量排名前 5 的页面执行逐 URL GSC 检查）。完整流程及各层级分支，请参阅 skills/seo-google/references/cross-skill-integration.md 中的“seo-technical-audit”部分。

2. 查找或创建审计 DATA_listAudits

   • 列出该域名的审计。
   • 如果存在近期审计（距今不到 30 天），则使用该审计。
   • 如果审计距今超过 30 天，则运行 DATA_recheckAudit 进行更新。
   • 如果不存在审计，在使用 DATA_createStandardAudit 创建新审计前，先询问用户（此操作会消耗点数）。
   • 等待 DATA_getAuditStatus 报告 done 后，再获取报告。

3. 获取审计报告 DATA_getAuditReport

   • 核心指标：抓取页面数、健康度评分、各严重程度的问题总数。
   • 按类别归类的问题（可抓取性、可索引性、移动端、安全性、结构化数据等）。

4. 获取每项问题对应的页面列表 DATA_getAuditPagesByIssue

   • 对每项重要问题（严重程度 ≥ 中等，数量 ≥ 5），获取受影响的 URL。
   • 由此生成可执行的修复清单。

5. 交叉检查关键 URL DATA_getIssuesByUrl

   • 获取流量排名前 5 的页面（来自 DATA_getDomainKeywords 的页面汇总；若没有关键词数据，则使用首页和关键落地页）对应的所有问题。
   • 这有助于发现某个重要页面集中了许多问题的情况。

6. 使用 WebFetch 进行核查

   • 直接获取 /robots.txt 和 /sitemap.xml。
   • 确认审计结果与这些关键文件的实际情况一致（审计结果有时会滞后于当天的部署）。
   • 扩展安全标头。 使用 WebFetch 获取首页和 3 个示例 URL（第 5 步中流量最高的落地页；如果没有关键词数据，则改用首页和关键落地页）；读取响应标头，并标记以下任一问题：
     • csp_missing — 未设置 Content-Security-Policy。
     • xframe_missing — 未设置 X-Frame-Options（仅供参考；CSP 的 frame-ancestors 优先级更高）。
     • xcontent_missing — X-Content-Type-Options 未设为 nosniff。
     • referrer_policy_missing — 未设置 Referrer-Policy。
     • hsts_no_preload — 已设置 Strict-Transport-Security，但缺少 preload 指令，且域名不在 Chromium HSTS 预加载列表中。
   • 根据 references/severity-mapping.md § Security 对问题进行映射，并将结果列入 evidence/02-issues-by-category/security.md（同时内嵌到 TECH-AUDIT.md 的“按类别 → 安全”部分）。

7. 分类并确定优先级，使用 references/severity-mapping.md

   • 将每个问题代码映射到严重性、修复方案和工作量估算。
   • 为每项发现评分：严重性 × 受影响页面数量 / 工作量。
   • 制定前 10 项修复清单。

8. 现代信号检查清单 mcp__firecrawl-mcp__firecrawl_scrape

   • SE Ranking 的审计爬虫不会执行 JS，也不会按页面提供响应头。此步骤可揭示它看不到的信息。
   • 如果 Firecrawl 可用（约 6 个 Firecrawl 点数，硬性上限）：从审计中选取 5 个示例 URL，优先选择流量较高的落地页，以及已标记存在 noindex / canonical 问题的页面。对每个页面：
     • JS 渲染后的 canonical 与初始 HTML 中的 canonical 不一致（js_canonical_mismatch）。 将 metadata.canonical（JS 渲染后）与审计记录的 canonical 进行比较。标记任何差异——根据 Google 于 2025 年 12 月发布的 JavaScript SEO 指南，当原始 HTML 中的 canonical 与 JS 注入的 canonical 不同时，Google 可能会采用其中任意一个，因此 canonical 决策具有不确定性。在 JS 密集型网站上，JS 注入的 canonical 变更会悄无声息地破坏索引。
     • JS 渲染后的 noindex。 渲染后检查 metadata.robots 中是否包含 noindex。捕获审计无法看到的、仅由客户端注入的 noindex。
     • X-Robots-Tag 响应头。 从 metadata 中读取响应头。标记 HTTP 层上的任何 noindex / nofollow / none 指令。
     • 2025 年 12 月 JS-SEO 风险检测（Google 于 2025 年 12 月发布的 JavaScript SEO 指南中提到的静态爬虫无法检测的四项风险）：
       • 风险 1 — 渲染预算耗尽（js_render_budget）。 比较初始 HTML 正文大小与渲染后的 HTML 正文大小。标记 JS 执行后渲染的 HTML 小于初始 HTML 大小 50% 的页面——这表明 Google 可能会在页面的实际内容加载前耗尽渲染预算。
       • 风险 2 — 水合不匹配。 已通过上文的 js_canonical_mismatch 检测；原因是，根据 2025 年 12 月的指南，Google 可能会采用任意一个 canonical，因此任何不一致都是真实的排名风险，而不仅仅是整洁度问题。
       • 风险 3 — CSR 陷阱（js_csr_meta_drift）。 将初始 HTML 的 <title>、<h1> 和 <meta name="description"> 与 JS 渲染 DOM 中的相同字段进行比较。标记任何差异——Google 无法可靠地索引仅在渲染后出现的内容，因此最终被索引的可能是初始 HTML 中的空值或错误值。
       • 风险 4 — JS 错误导致软 404（js_soft_404）。 标记正文文本内容少于 500 个字符、但 HTTP 响应状态为 200 的渲染页面。这种模式表明 JS 渲染失败，Google 会将其视为软 404——页面返回 200（因此“在线”），但不包含实际内容（因此“为空”）。
     • 然后再额外调用一次：对 /robots.txt 执行 firecrawl_scrape（1 个点数）。解析 AI 爬虫的 User-Agent 规则——GPTBot、ClaudeBot、PerplexityBot、Google-Extended、ChatGPT-User、Bytespider、CCBot。展示每个 Agent 的允许 / 禁止范围。
   • 如果 Firecrawl 不可用： 跳过此步骤。在 TECH-AUDIT.md 中注明：现代信号（JS canonical/noindex 不一致、X-Robots-Tag、AI 爬虫 robots.txt 规则、2025 年 12 月 JS-SEO 风险）：已跳过 — 未安装 Firecrawl。

8b. 通过 CrUX 获取 CWV 实测数据 （仅当存在 google-api.json 且 tier ≥ 0 时）

• SE Ranking 的审计报告仅提供实验室环境下的 CWV（Lighthouse 风格的估算值）。CrUX 返回 Chrome 用户的实际 p75 指标——这是 Google 排名所依据的数据。
• 运行 python3 scripts/pagespeed_check.py "https://{domain}" --crux-only --json，获取当前 p75 LCP / INP / CLS / FCP / TTFB。
• 运行 python3 scripts/crux_history.py "https://{domain}" --origin --json，获取每项指标过去 25 周的趋势（改善 / 稳定 / 恶化）。
• 如果 CrUX 没有实测数据（“insufficient data”），请说明并继续——低流量来源很常见。
• 在 TECH-AUDIT.md 中新增 "## Core Web Vitals（实测数据）" 部分，展示每项指标当前的 p75 值和趋势，并将来源标注为 "CrUX 28-day origin"。 8c. 通过 GSC URL Inspection 检查各 URL 的索引状态 （仅当存在 google-api.json 且 tier ≥ 1 时）
• 针对步骤 5 中识别出的流量最高的 5 个页面（如果没有关键词数据，则检查首页和关键落地页），运行： python3 scripts/gsc_inspect.py "{url}" --site-url "{config.default_property}" --json
• 记录每个 URL 的 indexStatusVerdict、coverageState、googleCanonical（与 userCanonical 对比）和 lastCrawlTime。
• **与审计中发现的 noindex / canonical 问题交叉核查。**如果 GSC 报告 INDEXED，但审计标记了 noindex，说明审计结果已过时，或该指令是最近添加的——标记为需要重新审计。如果 GSC 报告某页面为 EXCLUDED，而审计认为该页面状态正常，则表明存在 SE Ranking 审计无法发现的隐藏索引问题。
• **提升为关键问题：**任何流量最高页面出现 userCanonical ≠ googleCanonical 的差异，都应以 Critical 严重级别加入前 10 项修复清单，不受 severity-mapping.md 默认映射影响——Google 已改选其他规范网址，这是实际的排名问题。
• 如果此账号的 GSC 尚未验证该资源，则显示“GSC：{domain} 尚未验证 — 请在 Search Console 中添加”，并仅跳过 8c。
• 在 TECH-AUDIT.md 中新增“## 索引状态实况检查（GSC URL Inspection）”一节，每个流量最高的 5 个 URL 各占一行，列出状态 / 规范网址差异 / 最近抓取时间。
• 完整流程和故障模式见 skills/seo-google/references/cross-skill-integration.md §“seo-technical-audit”。

8d. 检测 IndexNow WebFetch

• 检测逻辑——IndexNow 有 3 种公布密钥的方式。按以下顺序检查：
  1. **robots.txt 提示：**检查已获取的 /robots.txt（步骤 6）中是否有 IndexNow: 指令，或是否有提及密钥文件路径的注释。
  2. **响应头提示：**扫描首页 WebFetch（步骤 6）的响应头，查找 x-indexnow-key、x-indexnow 或 x-indexnow-key-location。
  3. **约定路径探测：**如果在 (1) 或 (2) 中发现密钥提示，则通过 WebFetch 请求 /<key>.txt。如果都没有提示，仅当用户的域名已通过其他方式表明使用 IndexNow 时，才额外探测少量约定位置（例如 robots.txt 中声明已集成 Bing Webmaster）。
• 根据 references/severity-mapping.md § IndexNow 对发现结果进行映射：
  • 未公布任何密钥 → indexnow_no_key（Low；仅作参考——仅对 Bing 有益）。
  • 已公布密钥，但 /<key>.txt 的内容 ≠ 公布的密钥 → indexnow_key_mismatch（Medium）。
  • 密钥文件存在且匹配，但未检测到近期提交 → indexnow_not_submitted_recently（Low；仅作参考）。
• 尽可能检测最近一次密钥轮换日期：通过 WebFetch 获取密钥文件并读取 Last-Modified 响应头（若无则读取文件的 Date 响应头）。
• 在 evidence/02-issues-by-category/security.md 中记录（如果发现的问题较重要，也可新建 evidence/02-issues-by-category/indexnow.md；无论如何，都要汇总到 TECH-AUDIT.md 的“按类别”一节中），并在 TECH-AUDIT.md 的 Modern signals 一节中添加一行，显示 IndexNow 状态：是否已配置（Y/N），以及可检测到的最近密钥轮换日期。

9. 综合整理 TECH-AUDIT.md

输出格式

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

seo-technical-audit-{target-slug}-{YYYYMMDD}/
├── TECH-AUDIT.md                       (synthesised top-10 fix list + category summary — primary deliverable; inlines 01-audit-summary header + the six 02-issues-by-category/* tables under "By category")
├── issues.csv                          (every issue: code, severity, count, fix, effort — load-bearing CSV engineering pastes into Jira)
├── 03-key-pages-issues.md              (top 5 traffic pages, all their issues — load-bearing reference engineering / on-call consult per-URL)
└── evidence/
    ├── 02-issues-by-category/          (raw per-category tables — preserved in case a reader wants the unmerged view)
    │   ├── crawlability.md
    │   ├── indexability.md
    │   ├── security.md
    │   ├── mobile.md
    │   ├── structured-data.md
    │   └── content.md
    ├── 04-robots-sitemap-snapshot.md   (raw fetched files — preserved for reproducibility)
    └── 05-modern-signals.md            (JS-render canonical/noindex divergence, X-Robots-Tag, AI-crawler rules — requires Firecrawl)

顶层：TECH-AUDIT.md + issues.csv + 03-key-pages-issues.md。审计摘要标题（01-audit-summary）已位于 TECH-AUDIT.md 的标题部分；六张分类表（02-issues-by-category/*.md）已内嵌在 TECH-AUDIT.md 的“按类别”一节中。原始分类文件、robots/sitemap 快照和 modern-signals 转储文件保存在 evidence/ 下，以便复现。

TECH-AUDIT.md 采用以下结构：

# Technical Audit: {domain}

> Audit date {YYYY-MM-DD} · Pages crawled: {n} · Health score: {n}/100

## Summary

| Severity | Count |
|---|---|
| Critical | {n} |
| High | {n} |
| Medium | {n} |
| Low | {n} |

## Top 10 fixes (impact × effort)

| Rank | Issue | Severity | Pages | Fix | Effort |
|---|---|---|---|---|---|
| 1 | {issue name} | {severity} | {n} | {one-line fix} | {S/M/L} |
| ... |

## By category

### Crawlability ({n} issues)
- {issue name} ({n} pages) — {fix}
- ...

### Indexability ({n} issues)
- ...

### Security ({n} issues)
- ...

### Mobile ({n} issues)
- ...

### Structured data ({n} issues)
- ...

### Content ({n} issues)
- ...

### Modern signals ({n} findings — Firecrawl)
- {URL} — initial-HTML canonical `{X}` differs from JS-rendered canonical `{Y}` (`js_canonical_mismatch`)
- {URL} — JS-rendered `noindex` not visible to static crawler
- {URL} — `X-Robots-Tag: noindex` at HTTP layer
- {URL} — rendered HTML <50% of initial HTML size (`js_render_budget` — Google may stop rendering before content loads)
- {URL} — title / H1 / meta description differ between initial HTML and post-render DOM (`js_csr_meta_drift`)
- {URL} — rendered body <500 chars but HTTP 200 (`js_soft_404` — likely JS render failure, treated as soft-404 by Google)
- robots.txt — `GPTBot`: {allow / disallow `/path`}, `ClaudeBot`: {…}, `Google-Extended`: {…}, ...
- IndexNow — configured: {Y/N} · key-file: `/<key>.txt` {found / missing / mismatch} · last-key-rotation: {YYYY-MM-DD or "unknown"}
- (Or: `Modern signals: skipped — Firecrawl not installed`)

### Security headers (extended — WebFetch)

| Header | Homepage | Sample 1 | Sample 2 | Sample 3 | Issue |
|---|---|---|---|---|---|
| Content-Security-Policy | {present/absent} | … | … | … | `csp_missing` if absent |
| X-Frame-Options | {present/absent} | … | … | … | `xframe_missing` if absent (informational; CSP frame-ancestors supersedes) |
| X-Content-Type-Options | {`nosniff`/absent/other} | … | … | … | `xcontent_missing` if not `nosniff` |
| Referrer-Policy | {present/absent} | … | … | … | `referrer_policy_missing` if absent |
| HSTS preload | {preload directive Y/N · on Chromium preload list Y/N} | … | … | … | `hsts_no_preload` if not on list |

## Core Web Vitals (field data — CrUX)

| Metric | p75 (current) | 25-week trend | Threshold | Status |
|---|---|---|---|---|
| LCP | {n} ms | {improving/stable/degrading} | ≤2500 ms good · ≤4000 ms needs improvement | {pass/warn/fail} |
| INP | {n} ms | … | ≤200 ms good · ≤500 ms needs improvement | … |
| CLS | {n} | … | ≤0.1 good · ≤0.25 needs improvement | … |
| FCP | {n} ms | … | ≤1800 ms good · ≤3000 ms needs improvement | … |
| TTFB | {n} ms | … | ≤800 ms good · ≤1800 ms needs improvement | … |

Source: CrUX 28-day origin. If insufficient field data: "CrUX: insufficient data for {domain} (low-traffic origin)."
(Or: `CWV (field data): not configured — run `bash extensions/google/install.sh` for setup.`)

## Indexation reality check (GSC URL Inspection)

| URL | Status | userCanonical → googleCanonical | Last crawled |
|---|---|---|---|
| {top-traffic URL 1} | {INDEXED|EXCLUDED|...} | {URL} {→ different URL if divergent} | {YYYY-MM-DD} |
| {top-traffic URL 2} | … | … | … |
| ... |

Source: GSC URL Inspection (Tier 1). If property not verified: "GSC: {domain} not verified — add it in Search Console."
(Or: `Indexation reality check: not configured (Tier 1 setup required).`)

## Key-page deep dives

### {URL with most issues}
{n} issues found. Top fixes:
1. ...
2. ...

## Recommended cadence
Re-run this skill monthly to catch regressions, or wire `seo-drift` to baseline + diff between audits.

issues.csv 列：category,issue_code,issue_name,severity,affected_pages,suggested_fix,effort,priority_score

提示

• 遵守速率限制：10 req/sec。
• 尽可能复用现有审计——创建新审计的成本最高。
• 对一个包含 1k 个页面的网站进行全新审计，可能需要 10–30 分钟才能完成。该技能会轮询 DATA_getAuditStatus，直到状态为 done——请耐心等待。
• 严重程度等级来自 SE Ranking 的审计（并非随意设定）。请通过 references/severity-mapping.md 进行映射，以确保每次运行的影响 × 工作量评分保持一致。
• 对于超过 10k 个页面的网站，可考虑分别审计关键部分（在 SE Ranking 中设置审计 URL 筛选条件），而不是每次都抓取整个网站。
• 与 seo-drift 搭配使用以跟踪回归：此技能提供快照，drift 提供差异。
• 与 seo-sitemap 搭配使用以分析孤立页面或缺失页面（它会使用此技能的审计数据）。
• 不要自动应用修复。此技能负责诊断；由人工决定要发布哪些修复，以及按什么顺序发布。