seo-headings-structure

seo-headings-structure (M7c)

清晰且只有一个根节点的标题树，以及恰当的语义地标，能让页面大纲机器可读——AI 引擎正是利用这种结构提取答案块，搜索引擎也用它理解内容范围。Schema/实体上下文：references/schema-tier1.md。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed（包括含有 region 的 headings[] 和 landmarks）；对 pages/<slug>.html 执行 Grep，查找原文证据；站点产物位于 <run_dir>/site/{robots.json,sitemaps.json,discovery.json}。audit.mjs 已输出的确定性发现列在 <run_dir>/findings.deterministic.json 中——不要重新输出这些 id；仅添加由模型判断的发现。如果直接使用 URL/路径调用且不存在快照，请先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"，并使用打印出的快照路径。

审计

基于 PageSnapshot 开展工作（当 render.used 不为 none 时使用 parsed_rendered，否则使用 parsed）：

1. 单个 H1：每页必须恰好有一个 <h1>。没有 H1 或有多个 H1，都属于发现。
2. 层级不可跳过：嵌套每次下降一级（<h2> 后可以跟 <h3>，但不能直接跟 <h4>）。构建大纲并标记所有层级跳跃。
3. 描述性文本：每个标题都应以通俗易懂的方式命名其所在章节——标记空标题、纯粹用于视觉样式的标题，以及通用占位文本（“Section 1”“Welcome”）。
4. 语义地标：检测 <main>、<article>、<section>、<nav>、<header>、<footer>；如果标题位于缺乏语义的 <div> 嵌套中，或存在多个 <main>，则予以标记。
5. 大纲与地标一致性：分节元素应包含自己的标题；孤立的地标以及位于任何地标之外的标题都属于发现。

良好的标题结构有助于 AI 提取答案块：清晰的 H2/H3 边界对应可引用段落的候选范围。

修复

• 重构标题层级 — 调整 H2-H6 层级以消除跳级或正确嵌套（可修复性：proposed）。这会改变视觉层级，因此每项都需要单独接受；输出 fix_preview 差异，绝不自动写入。
• 添加缺失的单个 H1 — 如果页面没有 H1，则根据已填充的 <title>/og:title 或明显的页面标题元素提出一个建议（可修复性：proposed，需逐项接受——添加可见标题属于编辑决策）。绝不要根据内容不足的页面编造 H1 文本；如果来源不明确，请询问用户。
• 使用语义地标包裹内容 — 建议采用 <main>/<article> 属于建议性操作（这属于工具不会执行的结构性重构）。

将每项发现的 fixable 字段设置为与 schema/finding.schema.json 一致（auto / proposed / advisory）。绝不要编造标题文本，也不要根据内容不足的页面臆造 H1——请询问用户，或保留标注清楚的 TODO 占位符。

验证

• 方法：dom_assert。重新解析快照，重建大纲，并断言具体条件（一个 H1、没有层级跳跃、存在地标）。
• 离线复现：node "${CLAUDE_PLUGIN_ROOT}/scripts/parse-html.mjs" --snapshot <pages/<slug>.json>（或使用 --url <u> / --file <path>）——返回 headings 块（各层级的 counts、h1_count 和 skipped_levels），其中会统计 H1 数量，并遍历 H1-H6 标题树以检测层级跳跃。
• 如果需要渲染后的 DOM 层级但该层级不可用（标题由客户端注入，且仅存在 raw_html_path），则状态为 needs_api，绝不能错误地标记为 pass。

发现项

按 schema/finding.schema.json 输出发现项。示例：

• M7c.h1.multiple — 页面上有多个 <h1>（状态 fail，严重性 3，fixable: proposed，维度 search，置信度 established）。evidence.observed 引用每个 H1 的文本和选择器；verification.reproduce 使用上文的 parse-html.mjs 命令（检查 h1_count）。
• M7c.outline.skipped_level — 一个 <h2> 后直接跟着一个 <h4>（状态 fail，严重性 3，fixable: proposed，维度 search，置信度 directional）。evidence.observed 引用这两个相邻标题及其级别。
• M7c.landmark.no_main — 没有 <main> 元素；主要内容位于 <div> 中（状态 warn，严重性 3，fixable: advisory，维度 search，置信度 directional）。

每个发现项都包含引用页面原文的 evidence.observed，以及可运行的 verification.reproduce；expected_impact 采用分级并标注置信度（不使用没有依据的百分比）。

诚实性

• 标题中的关键词堆砌不会提高排名——标题应为读者而写；清晰度才是关键，而非关键词密度。不要建议在 H1/H2 中塞入术语。
• 多个 H1 符合 HTML5 标准，现代解析器和 AI 也能容忍；实际代价是大纲结构变得混乱，因此应将其视为严重性 3、置信度为 directional 的问题，而非关键故障。跳过标题级别主要涉及无障碍性/结构问题——应如实描述其影响（directional），而不是承诺能提升排名。