seo-core-web-vitals

seo-core-web-vitals (M15)

Core Web Vitals 是已确认的 Google 排名信号，也是页面质量的代理指标。阈值、真实用户数据与实验室数据的诚实使用规则，以及 LCP 分解：references/cwv-thresholds.md（请严格遵循）。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed（scripts[]、stylesheets[]、images[]），以及 timing.ttfb_ms、body.bytes 和 render — 现场数据仍需使用 PSI 层级；使用 Grep 在 pages/<slug>.html 中查找逐字证据；站点产物位于 <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. p75 现场 CWV — LCP ≤ 2.5 s、INP ≤ 200 ms（INP 已取代 FID）、CLS ≤ 0.1，以上指标均以真实用户数据的第 75 百分位为准。三项都必须通过，才能评为“良好”。使用主动预警阈值（LCP > 2.0 s、INP > 160 ms、CLS > 0.08），在不达标前先发出 warn。
2. 阻塞渲染的资源 — <head> 中的同步 <script>（没有 defer/async/type=module）、阻塞渲染的 <link rel="stylesheet">，以及会延迟首次渲染的 @import 链（存在 LCP/INP 风险）。
3. 未优化的图片 — 缺少 width/height（或 aspect-ratio）、首屏以下未使用 loading="lazy"、没有响应式 srcset/sizes、仍使用可由 AVIF/WebP 替代的旧格式，以及未预加载的 LCP 图片。
4. 布局偏移来源 — 未预留尺寸的图片/iframe/广告/嵌入内容、未设置 font-display/尺寸调整的 Web 字体切换，以及插入到现有内容上方的内容（存在 CLS 风险）。
5. LCP 分解 — 将 LCP 归因于 TTFB、资源加载延迟、加载时长或渲染延迟（参见 references/cwv-thresholds.md），以便每项发现都针对占主导地位的子部分。

修复（可修复：建议性）

仅提供建议。 性能修复会涉及构建配置、服务器、CDN 和运行时 JavaScript — 破坏风险较高 — 因此该工具只诊断并确定优先级，绝不自动修改性能代码。对于每项未达标的指标，指出导致问题的具体资源/元素，并按预期效果排序修复建议（例如预加载 LCP 图片、延迟加载非关键 JS、预留图片尺寸）。如果已知技术栈，请提供框架特定的指导。绝不捏造测量值 — 如果缺少现场数据，请让用户提供 PSI/CrUX 密钥，或留下明确标注的 TODO 占位符，而不是猜测指标。

验证

• Field（Tier 1）：node "${CLAUDE_PLUGIN_ROOT}/scripts/psi-client.mjs" --url <final_url> [--strategy mobile|desktop] [--timeout 60000] 调用 PageSpeed Insights API（loadingExperience，方法 psi_api）。它只接受URL——没有 --snapshot 模式，因为 Field 数据是在实时来源站点上测量的，而不是在已保存的 DOM 上测量的。密钥来自环境变量（CLAUDE_PLUGIN_OPTION_PSI_API_KEY，否则使用 PSI_API_KEY）；有意不提供 --key 标志。没有密钥时，脚本会以退出码 0 返回 status: "needs_api"——应根据 status 分支处理，切勿根据退出码判断。PSI 设置 origin_fallback 时，数据是来源站点级别的，结论必须明确说明这一点。捆绑客户端尚未实现 CrUX 历史数据（crux_api）（references/cwv-thresholds.md）：切勿声称此工具提供了 p75 趋势。
• Tier 0（无密钥）：对于每项 Field-CWV 结论，都输出 status: needs_api，并附上明确标注的实验室启发式指标（阻塞渲染的资源数量、缺少尺寸的图片、捆绑包大小）。将实验室信号标为“实验室数据——非 Google 排名依据”；切勿将启发式指标描述为实测 Field 值。
• 所需数据层级不可用时，状态为 needs_api——绝不能错误地标记为 pass。

结论

按照 schema/finding.schema.json 输出结论。严重性策略：5 仅用于网站／模板级、灾难性且会导致失去资格的事实；4 为重大 · 3 为中等 · 2 为轻微 · 1 为表面问题 · 0 为信息性——且只有活动类别中一个已确认的严重性 5 级 fail 才能限制分数（references/scoring-model.md）。Field CWV 不会达到 5：它是平分时的决胜因素，而非资格门槛。示例：

• M15.lcp.exceeds_p75——Field LCP 在 p75 时 > 2.5 s（状态 fail，严重性 4，fixable: advisory，轴 search，置信度 established）。evidence.observed 引用实测 p75 值和 LCP 元素；verification.reproduce 运行 psi-client 命令。
• M15.cls.unsized_image——缺少 width/height、导致布局偏移的图片（状态 warn，严重性 4，fixable: advisory，轴 search，置信度 directional）。evidence.observed 引用 <img> 标签。
• M15.field.needs_api——没有 PSI/CrUX 密钥，无法验证 Field CWV（状态 needs_api，严重性 4，fixable: advisory，轴 search，置信度 established）。 每项结论都应满足：evidence.observed 引用页面／测量结果；verification.reproduce 是可运行的命令；expected_impact 按范围给出并标注置信度（不得只给出百分比）。

诚实性

• 实验室 ≠ Field。 单次本地 Lighthouse 运行仅用于诊断；Google 根据 Field（CrUX）p75 排名。切勿让实验室数值影响 Search 分数，或将其冒充为 Field 结果。
• CWV 是真实但作用有限的决胜因素，不会凌驾于相关性／内容质量之上。不要承诺绿色分数会带来排名跃升；应将其作为分范围的 expected_impact 报告，而非预测百分比增幅。
• 如果 Field p75 未通过，那么实验室性能分数即使是“100”也不算通过；只有 Field 数据才能最终确定 CWV 结论。