webperf-core-web-vitals

WebPerf：Core Web Vitals

用于在 Chrome DevTools 中测量网页性能的 JavaScript 代码片段。

运行脚本

1. 使用 mcp__chrome-devtools__evaluate_script 运行脚本，并读取其返回的对象。脚本不会输出到控制台，因此返回的对象就是结果：script、status 和指标数据（value、rating、details、items、issues），具体说明见 references/schema.md。
2. 当 status 为 "tracking" 时，脚本会持续观察页面。完成交互后，使用另一次 mcp__chrome-devtools__evaluate_script 调用 getDataFn 中指定的函数，例如 getINP()，并读取其返回的对象。
3. 当 status 为 "error" 或 "unsupported" 时，请读取 error：页面可能尚未加载，或者浏览器不支持该 API。

如果没有 Chrome DevTools MCP，请使用 webperf-snippets CLI 运行同一代码片段。它会在无头 Chromium 中加载页面，并输出相同的结果对象：npx webperf-snippets <url> --snippet <Name> --json，其中 <Name> 是不带 .js 的脚本名称。它需要 Playwright 和 Chromium（先运行 npm install --save-dev webperf-snippets playwright，然后运行 npx playwright install chromium）；跟踪类代码片段需要使用 --interact-script <file> 来驱动交互。

脚本

• scripts/CLS.js — 累积布局偏移（CLS）
• scripts/INP.js — 下次绘制交互（INP）
• scripts/LCP-Image-Entropy.js — LCP 图像熵
• scripts/LCP-Subparts.js — LCP 子阶段
• scripts/LCP-Trail.js — LCP 候选项变化轨迹
• scripts/LCP-Video-Candidate.js — LCP 视频候选项
• scripts/LCP.js — 最大内容绘制（LCP）

常见工作流

Core Web Vitals 全面审计

当用户要求全面分析 Core Web Vitals，或提出“审计 CWV”时：

1. LCP.js — 测量最大内容绘制
2. CLS.js — 测量累积布局偏移
3. INP.js — 测量下次绘制交互
4. LCP-Subparts.js — 分解 LCP 的计时阶段
5. LCP-Trail.js — 跟踪 LCP 候选项的变化

深入分析 LCP

当 LCP 较慢，或用户提出“调试 LCP”或“为什么 LCP 很慢”时：

1. LCP.js — 确定基准 LCP 值
2. LCP-Subparts.js — 分解 TTFB、资源加载和渲染延迟
3. LCP-Trail.js — 找出所有 LCP 候选项及其变化
4. LCP-Image-Entropy.js — 检查 LCP 图像是否存在视觉复杂度问题
5. LCP-Video-Candidate.js — 检测 LCP 是否为视频（海报图或视频元素）

CLS 调查

检测到布局偏移，或用户提出“调试 CLS”或“布局偏移问题”时：

1. CLS.js — 测量整体 CLS 分数
2. Layout-Shift-Loading-and-Interaction.js (待提供 — 可在 webperf-interaction skill 中使用)
3. 与 webperf-loading skill 交叉核对：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（导致偏移的延迟加载图像）
   • Fonts-Preloaded-Loaded-and-used-above-the-fold.js（导致偏移的字体替换）

INP 调试

交互响应感觉迟缓，或用户提出“调试 INP”或“交互缓慢”时：

1. INP.js — 测量整体 INP 值；交互后调用 getINP()，查看最慢的 15 次交互时调用 getINPDetails()
2. Interactions.js (待提供 — 可在 webperf-interaction skill 中使用)
3. Input-Latency-Breakdown.js (待提供 — 可在 webperf-interaction skill 中使用)
4. Long-Animation-Frames.js (待提供 — 可在 webperf-interaction skill 中使用)
5. Long-Animation-Frames-Script-Attribution.js (待提供 — 可在 webperf-interaction skill 中使用)

视频 LCP 调查

当 LCP 是视频元素时（由 LCP-Video-Candidate.js 检测）：

1. LCP-Video-Candidate.js - 确认视频是 LCP 候选项
2. Video-Element-Audit.js（来自 Media 技能）- 审查视频加载策略
3. LCP-Subparts.js - 分析视频加载阶段
4. 与 webperf-loading 技能交叉参照：
   • Resource-Hints-Validation.js（检查是否预加载视频）
   • Priority-Hints-Audit.js（检查视频是否设置了 fetchpriority）

图片 LCP 调查

当 LCP 是图片时（最常见的情况）：

1. LCP.js - 测量 LCP 时间
2. LCP-Subparts.js - 拆解各个计时阶段
3. LCP-Image-Entropy.js - 分析图片复杂度
4. 与 webperf-media 技能交叉参照：
   • Image-Element-Audit.js（检查格式、尺寸和延迟加载）
5. 与 webperf-loading 技能交叉参照：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（检查是否错误地设置了延迟加载）
   • Priority-Hints-Audit.js（检查是否设置了 fetchpriority="high"）
   • Resource-Hints-Validation.js（检查是否预加载）

决策树

使用此决策树，根据结果自动运行后续代码片段：

执行 LCP.js 后

• 如果 LCP > 2.5s → 运行 LCP-Subparts.js，诊断哪个阶段较慢
• 如果 LCP > 4.0s（较差） → 运行完整的 LCP 深度调查工作流（5 个代码片段）
• 如果 LCP 候选项是图片 → 运行 LCP-Image-Entropy.js 和 webperf-media:Image-Element-Audit.js
• 如果 LCP 候选项是视频 → 运行 LCP-Video-Candidate.js 和 webperf-media:Video-Element-Audit.js
• 始终运行 → LCP-Trail.js，了解候选项的变化情况

执行 LCP-Subparts.js 后

• 如果 TTFB 阶段 > 600ms → 切换到 webperf-loading 技能并运行 TTFB-Sub-Parts.js
• 如果资源加载时间 > 1500ms → 运行：
  1. webperf-loading:Resource-Hints-Validation.js（检查是否预加载／预连接）
  2. webperf-loading:Priority-Hints-Audit.js（检查 fetchpriority）
  3. webperf-loading:Find-render-blocking-resources.js（检查竞争资源）
• 如果渲染延迟 > 200ms → 运行：
  1. webperf-loading:Find-render-blocking-resources.js（检查阻塞渲染的 CSS／JS）
  2. webperf-loading:Script-Loading.js（检查阻塞解析器的脚本）
  3. webperf-interaction:Long-Animation-Frames.js（检查主线程阻塞）

执行 LCP-Trail.js 后

• 如果 LCP 候选项变化很多次（>3） → 这会导致视觉不稳定，请调查：
  1. webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js（检查延迟加载的图片）
  2. webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js（检查字体切换）
  3. CLS.js（检查导致 LCP 变化的布局偏移）
• 如果最终的 LCP 候选项出现较晚 → 运行 webperf-loading:Resource-Hints-Validation.js
• 如果早期候选项被替换 → 查明初始内容被向下推移的原因（可能是 CLS 问题）

执行 LCP-Image-Entropy.js 后

• 如果熵非常高 → 图片视觉复杂度较高，建议：
  • 使用现代格式（WebP、AVIF）
  • 采用适当的压缩
  • 考虑使用占位图策略
• 如果熵较低 → 图片可能过度优化，或类似占位图
• 如果检测到文件较大 → 运行 webperf-media:Image-Element-Audit.js，分析格式和尺寸

执行 LCP-Video-Candidate.js 后

• 如果 LCP 是视频 → 运行：
  1. webperf-media:Video-Element-Audit.js（检查封面图、预加载和格式）
  2. webperf-loading:Priority-Hints-Audit.js（检查封面图上的 fetchpriority）
  3. LCP-Subparts.js（分析视频加载阶段）
• 如果 LCP 是封面图片 → 按图片 LCP 处理（运行图片工作流）

CLS.js 之后

• 如果 CLS > 0.1 → 运行 webperf-interaction:Layout-Shift-Loading-and-Interaction.js (待提供 — 可在 webperf-interaction 技能中使用)
• 如果 CLS > 0.25（较差） → 运行全面的布局偏移调查：
  1. webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js（缺少尺寸的图像）
  2. webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js（字体加载策略）
  3. webperf-loading:Critical-CSS-Detection.js（延迟加载的样式）
  4. webperf-media:Image-Element-Audit.js（缺少 width/height）
• 如果 CLS = 0 → 通过多次加载页面确认（可能受时序影响）

INP.js 之后

• 如果 INP > 200ms → 运行 webperf-interaction:Interactions.js，找出响应较慢的交互
• 如果 INP > 500ms（较差） → 运行完整的 INP 调试工作流：
  1. webperf-interaction:Interactions.js（列出所有交互）
  2. webperf-interaction:Input-Latency-Breakdown.js（分阶段分析）
  3. webperf-interaction:Long-Animation-Frames.js（阻塞帧）
  4. webperf-interaction:Long-Animation-Frames-Script-Attribution.js（问题脚本）
• 如果特定类型的交互较慢（例如键盘交互） → 将分析重点放在该类型的交互上
• 收集 INP 数据后 → 调用 getINPDetails()，按耗时从长到短获取最慢的 15 个交互（有助于识别多个慢速交互中的规律）

错误恢复

• 如果任何脚本返回 status: "error" → 检查页面是否已完成加载：
  • 如果页面刚开始加载：等待后重新运行脚本
  • 如果页面是 SPA：用户可能需要先导航到目标路由
• 如果 LCP.js / LCP-Subparts.js 返回 status: "error" → 告知用户：“LCP 数据暂不可用。请确保页面已完全加载，然后重新运行分析。”
• 如果 INP.js 的 getINP() 返回 status: "error" → getDataFn: "getINP" 字段表明 Agent 可以在用户交互后重试。提示用户点击、输入或滚动，然后再次调用 getINP()。

跨技能触发条件

上下文分叉说明： 此技能以 context: fork 运行。下面的跨技能触发条件是建议反馈给父 Agent 的操作，而不是此子 Agent 可以直接执行的调用。触发跨技能条件时，请告知用户接下来要运行的技能和脚本。标记为 (待提供) 的脚本尚不可用——请跳过并注明此限制。

这些触发条件建议使用其他技能中的代码片段：

从 LCP 到 Loading 技能

• 如果 LCP > 2.5s 且 TTFB 阶段占主导 → 使用 webperf-loading 技能：

  • TTFB.js、TTFB-Sub-Parts.js、Service-Worker-Analysis.js

• 如果 LCP 图像采用了延迟加载 → 使用 webperf-loading 技能：

  • Find-Above-The-Fold-Lazy-Loaded-Images.js

• 如果 LCP 没有 fetchpriority → 使用 webperf-loading 技能：

  • Priority-Hints-Audit.js

从 CLS 到 Loading 技能

• 如果 CLS 是由字体导致的 → 使用 webperf-loading 技能：

  • Fonts-Preloaded-Loaded-and-used-above-the-fold.js
  • Resource-Hints-Validation.js（用于字体预加载）

• 如果 CLS 是由图像导致的 → 使用 webperf-media 技能：

  • Image-Element-Audit.js（检查是否有 width/height 属性）

从 INP 到 Interaction 技能

• 如果 INP > 200ms → 使用 webperf-interaction 技能进行完整调试：
  • Interactions.js、Input-Latency-Breakdown.js
  • Long-Animation-Frames.js、Long-Animation-Frames-Script-Attribution.js
  • LongTask.js（如果怀疑交互前存在阻塞）

从 LCP/INP 到 Interaction 技能

• 如果渲染延迟或交互延迟较高 → 使用 webperf-interaction 技能：
  • Long-Animation-Frames.js（主线程阻塞）
  • LongTask.js（延迟渲染的长任务）

多指标相关性

当多个 CWV 指标较差时，应优先进行调查：

• 如果 LCP > 2.5s 且 CLS > 0.1 → 可能存在共同的根本原因：

  1. 检查是否有延迟加载的内容推挤 LCP 元素
  2. 运行 LCP-Trail.js，查看 LCP 候选项的变化
  3. 运行 Layout-Shift-Loading-and-Interaction.js，关联时间点

• 如果 LCP > 2.5s 且 INP > 200ms → 主线程拥塞：

  1. 运行 Long-Animation-Frames.js
  2. 运行 webperf-loading:Script-Loading.js
  3. 运行 webperf-loading:JS-Execution-Time-Breakdown.js

• 如果 CLS > 0.1 且 INP > 200ms → 布局抖动或由交互触发的偏移：

  1. 运行 Layout-Shift-Loading-and-Interaction.js
  2. 运行 Interactions.js
  3. 检查偏移是否发生在交互期间或之后

参考资料

• references/snippets.md — 各脚本的说明和阈值
• references/schema.md — 用于解读脚本输出的返回值架构