seo-core-web-vitals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

seo-core-web-vitals (M15)

Core Web Vitals are a confirmed Google ranking signal and a proxy for page quality. Thresholds, field-vs-lab honesty rules, and LCP decomposition:

references/cwv-thresholds.md

(follow it exactly).

Core Web Vitals 是 Google 已确认的排名信号，也是衡量页面质量的代理指标。阈值、field 与 lab 之间的诚实性规则以及 LCP 分解：

references/cwv-thresholds.md

（严格遵循）。

Inputs

输入

Work from the PageSnapshot named in your dispatch envelope: read

parsed

from

<run_dir>/pages/<slug>.json

(

scripts[]

stylesheets[]

images[]

) plus

timing.ttfb_ms

body.bytes

, and

render

— field data still needs the PSI tier; Grep

pages/<slug>.html

for verbatim evidence; site artifacts live in

<run_dir>/site/{robots.json,sitemaps.json,discovery.json}

. Deterministic findings already emitted by

audit.mjs

are listed in

<run_dir>/findings.deterministic.json

— do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

and use the printed snapshot path.

以 dispatch envelope 中指定的 PageSnapshot 为基础：从

<run_dir>/pages/<slug>.json

读取

parsed

（

scripts[]

、

stylesheets[]

、

images[]

），以及

timing.ttfb_ms

、

body.bytes

和

render

——field 数据仍需使用 PSI tier；在

pages/<slug>.html

中使用 Grep 查找逐字证据；站点工件位于

<run_dir>/site/{robots.json,sitemaps.json,discovery.json}

。

audit.mjs

已输出的确定性发现列于

<run_dir>/findings.deterministic.json

——不要重复输出这些 id；仅添加模型判断型发现。如果直接使用 URL 或路径调用且不存在 snapshot，请先运行

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

，并使用输出的 snapshot 路径。

Audits

审计

Working from the PageSnapshot (

parsed_rendered

when

render.used

is not

none

, else

parsed

Field CWV at p75 — LCP ≤ 2.5 s, INP ≤ 200 ms (INP replaced FID), CLS ≤ 0.1, all at the 75th percentile of real-user data. All three must pass for a "good" rating. Use the proactive-warning thresholds (LCP > 2.0 s, INP > 160 ms, CLS > 0.08) to
```
warn
```
before failing.
Render-blocking resources — synchronous
```
<script>
```
in
```
<head>
```
(no
```
defer
```
/
```
async
```
/
```
type=module
```
), blocking
```
<link rel="stylesheet">
```
, and
```
@import
```
chains that delay first render (LCP/INP risk).
Unoptimized images — missing
```
width
```
/
```
height
```
(or
```
aspect-ratio
```
), no
```
loading="lazy"
```
below the fold, no responsive
```
srcset
```
/
```
sizes
```
, legacy formats where AVIF/WebP would serve, and a non-preloaded LCP image.
Layout-shift sources — images/iframes/ads/embeds without reserved dimensions, web-font swap without
```
font-display
```
/size-adjust, and content injected above existing content (CLS risk).
LCP decomposition — attribute LCP to TTFB vs resource load delay vs load duration vs render delay (see
```
references/cwv-thresholds.md
```
) so each finding targets the dominant subpart.

根据 PageSnapshot 开展审计（当

render.used

不为

none

时使用

parsed_rendered

，否则使用

parsed

）：

p75 处的 Field 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
```
，再判定为失败。
阻塞渲染的资源——位于
```
<head>
```
中的同步
```
<script>
```
（没有
```
defer
```
/
```
async
```
/
```
type=module
```
）、阻塞式
```
<link rel="stylesheet">
```
，以及延迟首次渲染的
```
@import
```
链（LCP/INP 风险）。
未优化的图片——缺少
```
width
```
/
```
height
```
（或
```
aspect-ratio
```
）、首屏以下未设置
```
loading="lazy"
```
、缺少响应式
```
srcset
```
/
```
sizes
```
、本可提供 AVIF/WebP 时却使用旧格式，以及 LCP 图片未预加载。
布局偏移来源——未预留尺寸的图片/iframe/广告/嵌入内容、缺少
```
font-display
```
/
```
size-adjust
```
的 web-font swap，以及插入到现有内容上方的内容（CLS 风险）。
LCP 分解——将 LCP 归因于 TTFB、资源加载延迟、加载耗时或渲染延迟（参见
```
references/cwv-thresholds.md
```
），确保每项发现都针对主要问题环节。

Fixes (fixable: advisory)

修复（可修复：仅建议）

Advisory only. Performance fixes touch build config, server, CDN, and runtime JavaScript — high breakage risk — so the tool diagnoses and prioritizes but never auto-edits performance code. For each failing metric, name the specific resource/element causing it and rank fixes by expected leverage (e.g. preload the LCP image, defer non-critical JS, reserve image dimensions). Give framework-specific direction where the stack is known. Never fabricate measured values — if field data is absent, ask the user to supply a PSI/CrUX key or leave a clearly-marked TODO placeholder rather than guessing a metric.

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

Verification

验证

Field (Tier 1):
```
node "${CLAUDE_PLUGIN_ROOT}/scripts/psi-client.mjs" --url <final_url> [--strategy mobile|desktop] [--timeout 60000]
```
calls the PageSpeed Insights API (
```
loadingExperience
```
, method
```
psi_api
```
). It takes a URL only — there is no
```
--snapshot
```
mode, because field data is measured on the live origin, not on a saved DOM. The key comes from the environment (
```
CLAUDE_PLUGIN_OPTION_PSI_API_KEY
```
, else
```
PSI_API_KEY
```
); there is deliberately no
```
--key
```
flag. Without a key the script returns
```
status: "needs_api"
```
at exit 0 — branch on
```
status
```
, never on the exit code. When PSI sets
```
origin_fallback
```
, the numbers are origin-level and the finding must say so. CrUX History (
crux_api
) is not implemented by the bundled client (
```
references/cwv-thresholds.md
```
): never claim a p75 trend from this tool.
Tier 0 (no key): emit
```
status: needs_api
```
for every field-CWV finding, plus clearly-labeled lab heuristics (render-blocking count, missing image dimensions, bundle weight). Label lab signals "lab data — not what Google ranks on"; never present a heuristic as a measured field value.
When the required data tier is unavailable, status is
```
needs_api
```
— never a false
```
pass
```
.

Field（Tier 1）：
```
node "${CLAUDE_PLUGIN_ROOT}/scripts/psi-client.mjs" --url <final_url> [--strategy mobile|desktop] [--timeout 60000]
```
调用 PageSpeed Insights API（
```
loadingExperience
```
，method 为
```
psi_api
```
）。它只接受 URL——不存在
```
--snapshot
```
模式，因为 field 数据是在实时源站上测得，而不是在保存的 DOM 上。key 来自环境变量（
```
CLAUDE_PLUGIN_OPTION_PSI_API_KEY
```
，否则为
```
PSI_API_KEY
```
）；特意不提供
```
--key
```
flag。没有 key 时，脚本会返回
```
status: "needs_api"
```
且退出码为 0——应根据
```
status
```
分支处理，绝不能依据退出码。当 PSI 设置
```
origin_fallback
```
时，数值属于源站级别，对应发现必须明确说明这一点。随附客户端未实现 CrUX History（
```
crux_api
```
）（
```
references/cwv-thresholds.md
```
）：绝不能声称此工具能够提供 p75 趋势。
Tier 0（无 key）：为每个 field-CWV 发现输出
```
status: needs_api
```
，并补充带有明确标签的 lab 启发式结果（阻塞渲染数量、缺失的图片尺寸、bundle 权重）。将 lab 信号标记为“lab data — not what Google ranks on”（lab 数据——并非 Google 用于排名的数据）；绝不能将启发式结果呈现为已测得的 field 值。
当所需的数据 tier 不可用时，状态为
```
needs_api
```
——绝不能标为虚假的
```
pass
```
。

Findings

发现

Emit findings per

schema/finding.schema.json

. Severity policy: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an

established

severity-5

fail

in an active category can cap a score (

references/scoring-model.md

). Field CWV never reaches 5: it is a tie-breaker, not an eligibility gate. Examples:

```
M15.lcp.exceeds_p75
```
— field LCP > 2.5 s at p75 (status
```
fail
```
, severity 4,
```
fixable: advisory
```
, axis
```
search
```
, confidence
```
established
```
).
```
evidence.observed
```
quotes the measured p75 value and the LCP element;
```
verification.reproduce
```
runs the psi-client command.

M15.cls.unsized_image

— image with no

width

height

shifting layout (status

warn

, severity 4,

fixable: advisory

, axis

search

, confidence

directional

evidence.observed

quotes the

<img>

tag.

```
M15.field.needs_api
```
— no PSI/CrUX key, field CWV unverifiable (status
```
needs_api
```
, severity 4,
```
fixable: advisory
```
, axis
```
search
```
, confidence
```
established
```
). Each finding:
```
evidence.observed
```
quotes the page/measurement;
```
verification.reproduce
```
is the runnable command;
```
expected_impact
```
is banded + confidence-tagged (no naked %).

按

schema/finding.schema.json

输出发现。严重性策略：5 专用于站点或模板范围内灾难性且会导致失去资格的事实；4（major）· 3（moderate）· 2（minor）· 1（cosmetic）· 0（informational）——只有当前生效类别中状态为

established

、severity 为 5 且结果为

fail

的发现才能对评分封顶（

references/scoring-model.md

）。Field CWV 的 severity 永远不会达到 5：它只是辅助决胜信号，而不是资格门槛。示例：

```
M15.lcp.exceeds_p75
```
——field LCP 在 p75 处 > 2.5 s（status
```
fail
```
、severity 4、
```
fixable: advisory
```
、axis
```
search
```
、confidence
```
established
```
）。
```
evidence.observed
```
引用测得的 p75 值和 LCP 元素；
```
verification.reproduce
```
给出运行 psi-client 的命令。
```
M15.cls.unsized_image
```
——缺少
```
width
```
/
```
height
```
且导致布局偏移的图片（status
```
warn
```
、severity 4、
```
fixable: advisory
```
、axis
```
search
```
、confidence
```
directional
```
）。
```
evidence.observed
```
引用对应的
```
<img>
```
标签。
```
M15.field.needs_api
```
——没有 PSI/CrUX key，无法验证 field CWV（status
```
needs_api
```
、severity 4、
```
fixable: advisory
```
、axis
```
search
```
、confidence
```
established
```
）。每项发现：
```
evidence.observed
```
引用页面或测量结果；
```
verification.reproduce
```
给出可运行的命令；
```
expected_impact
```
使用分段区间并附带 confidence 标签（不得给出无依据的百分比）。

Honesty

诚实性

Lab ≠ field. A single local Lighthouse run is diagnostic only; Google ranks on field (CrUX) p75. Never let a lab number drive the Search score or masquerade as a field result.
CWV is a real but modest tie-breaker signal — it does not override relevance/content quality. Don't promise ranking jumps from a green score; report it as banded
```
expected_impact
```
, not a predicted percentage gain.
A "100" lab performance score is not a pass if field p75 fails; only field data settles a CWV finding.

**Lab ≠ field。**单次本地 Lighthouse 运行仅用于诊断；Google 的排名依据是 field（CrUX）p75。绝不能让 lab 数值影响 Search 评分，也不要将其冒充为 field 结果。
CWV 确实是一个真实但作用有限的决胜信号——不能凌驾于相关性和内容质量之上。不要承诺评分变绿就会带来排名跃升；应将其作为带区间的
```
expected_impact
```
报告，而不是预测百分比提升。
如果 field p75 未通过，lab 性能评分为“100”也不代表通过；只有 field 数据能够最终判定 CWV 发现。