seo-rendering

seo-rendering（M4）

仅在 hydration 后才存在的内容，对于任何不会运行 JavaScript 的使用者来说都是不可见的。Google 会渲染 JS（有相关文档）；据报告，大多数第三方 AI 爬虫不会渲染 JS（这只是方向性信息——参见 Honesty），因此，仅 CSR 的空壳主要会造成 AI 可见性和抓取效率问题。依赖 JS 也会延迟首次绘制；有关这对 LCP/INP 的影响，请参见 references/cwv-thresholds.md。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed 和 parsed_rendered，以及 render{needed,signals,used,confidence,hint,delta} 块——脚本已计算原始与渲染结果之间的差异；raw_html_path/rendered_html_path 指向磁盘上的文件；在 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）和脚本计算出的 render.delta 开展工作：

1. 内容差异：对比 raw_html_path 与 rendered_html_path——衡量仅在 JavaScript 运行后才出现的主要文本、内部链接、标题（h1–h3）和 <script type="application/ld+json"> 块所占比例。
2. 策略分类：仅 CSR（原始空壳或近乎空壳，内容由客户端注入）/ SSR / SSG（预渲染静态内容）/ ISR（预渲染并重新验证）。根据原始 HTML 的完整程度和框架信号（__NEXT_DATA__、hydration 标记、data-reactroot、构建清单）进行判断。
3. Hydration 阻塞文本：原始 HTML 中已有主要内容，但在 hydration 前被隐藏或为空，或者仅渲染到客户端专属的岛屿中。
4. 延迟加载的主要内容：需要滚动、交叉检测或交互才能加载的首屏内容或主要内容——不会与页面交互的爬虫无法看到这些内容。
5. AI 爬虫门槛：如果 h1、主要正文或 JSON-LD 仅存在于 rendered_html_path 中，则标记该页面无法被非 JS AI 爬虫可靠读取。

修复（可修复：建议）

渲染策略属于框架/架构决策，且破坏风险较高，因此 M4 仅提供建议——它负责诊断和确定优先级，绝不自动修改构建/服务器代码。

• 提供特定于框架的指导，例如将仅 CSR 的路由改为 SSG/ISR 或 SSR（Next.js App Router 服务端组件 / generateStaticParams + revalidate；Nuxt/Astro/SvelteKit 的对应方案）。
• 建议对主要内容进行预渲染或部分预渲染；仅对确实需要交互的小组件使用客户端专属岛屿。
• 如果正确策略取决于数据新鲜度或快照无法揭示的约束，请明确标记 TODO 留给用户——绝不要编造 revalidate 间隔或断言策略选择。每个问题都带有 fixable: advisory。

验证

• render_diff：计算 raw_html_path 与 rendered_html_path 的内容差异比例（渲染结果中存在、原始 HTML 中不存在的主要文本 / 链接 / 标题 / JSON-LD）。主要内容的差异比例较高，说明存在 JS 依赖。
• 要准确生成 rendered_html_path，需要无头浏览器数据层。该数据层不可用时，状态为 needs_api——绝不能误报为 pass。

发现

按 schema/finding.schema.json 输出发现。严重性策略：5 仅用于网站／模板层面可能导致资格丧失的灾难性事实；4 为重大 · 3 为中等 · 2 为轻微 · 1 为表面 · 0 为信息性——且只有活动类别中已确认的严重性为 5 的 fail 才能限制评分（references/scoring-model.md）。示例：

• M4.render.csr_only_primary_content — H1 和正文仅存在于 rendered_html_path 中；原始 HTML 是空壳（fail，严重性 5，轴为 both，fixable: advisory，置信度为 established）。这是该模块唯一会限制评分的发现，且仅适用于模板／网站层面。
• M4.render.jsonld_js_injected — JSON-LD 区块仅在水合后出现，因此非 JS 消费者看不到结构化数据（warn，严重性 3，轴为 ai，fixable: advisory，置信度为 established）。
• M4.render.lazy_main_content — 主要内容仅在滚动或交互后加载（warn，严重性 3，轴为 both，fixable: advisory，置信度为 directional）。
• M4.render.needs_renderer — 页面显示 CSR 信号，且没有可用的渲染器，因此无法测量差异（needs_api，严重性 3，轴为 both）。 每项发现：evidence.observed 引用页面上原始内容与渲染后内容的差异；verification.reproduce 是可运行的 render_diff 断言；expected_impact 使用分档并标注置信度（不写无依据的百分比）。

如实说明

• Googlebot 会渲染 JavaScript——Google 文档对此有说明（第二波、排队渲染），因此构建良好的 CSR 应用仍可被编入索引并获得排名。这一点属于 established；应将仅 CSR 视为对 AI 消费者 和抓取效率的风险，而不是 Google 一定会失败。
• **“大多数 AI 爬虫不会执行 JavaScript”属于 directional，并非有文档证实。**服务商会公布用户代理标记，而非渲染能力。应表述为“我们无法确认这些爬虫会执行 JS，且其公开行为表明它们不会执行”——绝不要将其说成服务商的声明。
• 不要声称“SSR 比 CSR 排名更高”是排名因素。真正相关的是非 JS 消费者能否获取内容，以及更快的首次绘制，而非渲染模式带来的提升。若页面本质上需要交互，且主要内容仍由服务器交付，就保留 CSR。
• 未使用真实无头浏览器测量的渲染差异不算测量——如果渲染器层级不可用，应说明 needs_api，而不是仅凭框架标记推断差异。