HTML SEO 审查
概述
为一个或多个静态 HTML 文件生成一份可操作、按严重性排序的发现列表。该技能打包了一个仅使用标准库的 HTML 解析器，可将每个 SEO 相关信号提取到一个 JSON 文档中，并附带一份全面的评分标准和一份发现报告模板——这些组件协同工作，确保每次审计都能产生可预测的输出。
何时使用
当输入是一个或多个静态 .html 文件（或一个包含这些文件的目录），并且用户希望获得可操作的页面内 SEO 发现时使用。触发词包括“SEO 审查”、“SEO 审计”、“检查此 HTML 的 SEO”、“审查此页面的元标签”、“审计页面内 SEO”。
请勿在以下情况下使用：
- 工件是静态站点生成器（Jekyll/Hugo/Astro/Eleventy/Next.js）的源代码。这些需要感知源代码的审查；请留待未来的
ssg-seo-review技能处理。 - 用户需要实时性能指标（LCP、CLS、INP）。仅凭 HTML 无法生成这些指标；建议使用 Lighthouse 或 PageSpeed Insights。
- 用户需要反向链接、域名权威或其他站外分析。这需要第三方工具（如 Ahrefs、SEMrush 等）。
工作流程
1. 提取信号
针对目标运行解析器。它接受单个文件或一个目录（递归扫描 *.html）：
python3 scripts/extract_seo_signals.py <路径> --pretty
输出是一个 JSON 文档，包含以下顶级键：lang、title、meta、links、scripts、headings、images、links_audit、body_word_count。每个元素都包含一个 line 编号，用于在发现中引用。
对于目录，输出为 {"files": [<每个文件的对象>]}。
该脚本仅使用 Python 的标准库——无需 pip install。如果某个特定文件的解析失败，该文件的结果会包含一个 error 字段，审计将继续处理其余文件。
2. 将信号映射到评分标准
加载 references/seo-checklist.md。按顺序浏览每个部分，并检查对应的 JSON 路径。评分标准明确列出了每项检查需要检查的路径（例如，images.missing_alt、meta.description.length、scripts.render_blocking_candidates）。
对于每项失败的检查，记录：
- 评分标准中的严重性（P0/P1/P2/P3）。
- JSON 输出中的行号。
- 文件中确切的引用标记或属性值（重新读取文件，使用行号逐字引用——切勿转述）。
- 修复方法，在更改是机械性的情况下，以具体的 before/after 差异形式写出。
3. 在报告前验证每个发现
在写入发现之前，机械地确认问题：
- 声称某个属性“缺失”必须来自解析器的结构化输出，而不是通过浏览 HTML。
- 声称某个值“太短/太长”必须引用 JSON 中的实际字符数。
- 引用的标记必须精确；如果无法从文件中逐字符复现引用，则丢弃该发现。
这可以防止最常见的审查失败：虚构一个实际上不存在的问题。
4. 生成发现报告
使用 assets/findings-template.md 作为结构。填写：
- 摘要段落，包含总体结论和严重性计数。
- 每个发现一个区块，按严重性排序（P0 → P3），然后按文件顺序排序。
- 当发现数量超过约 10 个时，可选择添加“快速胜利”部分——挑选 3-5 个最具影响力的修复。
- “备注的超出范围项目”部分，列出用户应使用外部工具跟进的事项（如使用 Lighthouse 获取真实 CWV、使用 curl 检查规范化 URL 解析等）。
如果审计涵盖多个文件，则生成一份覆盖所有文件的报告，在每个严重性等级下按文件分组发现——而不是每个文件一份报告。
5. 优雅地跳过
如果某项检查需要解析器无法提供的信息（例如，“此规范化 URL 是否返回 200 状态码？”），切勿猜测。将其记在报告的“备注的超出范围项目”部分，然后继续。
参考
scripts/extract_seo_signals.py— HTML 解析器。仅使用标准库。输出带有行号的结构化 JSON。references/seo-checklist.md— 完整的评分标准，按类别组织，包含每项检查的严重性等级和 JSON 路径。assets/findings-template.md— 审计报告的输出格式。