跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

lighthouse

Lighthouse audit + improvement loop until targets met. Triggers "lighthouse", "page speed", "improve scores", "LCP", "CLS", "INP", "core web vitals". Repo-wide perf audits ("perf audit") go to /audit performance mode instead.

darkroomengineering · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add darkroomengineering/cc-settings --skill lighthouse

技能说明


name: lighthouse description: Lighthouse audit + improvement loop until targets met. Triggers "lighthouse", "page speed", "improve scores", "LCP", "CLS", "INP", "core web vitals". Repo-wide perf audits ("perf audit") go to /audit performance mode instead. context: fork argument-hint: "[url]" allowed-tools:

  • Bash
  • Read
  • Write
  • Edit
  • Grep
  • Glob
  • LS
  • mcp__chrome-devtools__navigate_page
  • mcp__chrome-devtools__take_screenshot
  • mcp__chrome-devtools__take_snapshot
  • mcp__chrome-devtools__lighthouse_audit requires:
  • command: lighthouse install: "npm i -g lighthouse (CLI, used for batched 3x3 averaged audits)"
  • mcp: chrome-devtools install: "chrome-devtools MCP — provides on-demand audits + visual regression screenshots"

Lighthouse Optimization Loop

Set a product-neutral scratch root once:

LIGHTHOUSE_DIR="${TMPDIR:-/tmp}/cc-settings-lighthouse"
mkdir -p "$LIGHTHOUSE_DIR"

Use the Chrome DevTools MCP only when the user configured it. Standalone Codex otherwise uses the Lighthouse CLI plus native/manual screenshots; if no visual capture path exists, stop before changing UI and report that visual regression verification is unavailable. This package does not auto-run unpinned registry MCP packages.

Method: 3 mobile + 3 desktop runs per audit, averaged for reliability. After each code change, re-audit and visually verify the page with the configured MCP or the stated manual fallback.


Setup

  1. Parse URL from $ARGUMENTS. If no URL, ask the user. Default: http://localhost:3000

  2. Verify prerequisites:

    lighthouse --version    # CLI must be installed for the batched 3x3 protocol
    

    If lighthouse is missing: npm install -g lighthouse If runs fail with a chrome-launcher error or every metric comes back NO_LCP/null, no system Chrome exists — find a real Chrome/Chromium binary (Chrome for Testing, Playwright's chromium-* — NOT chrome-headless-shell, which produces NO_LCP) and export CHROME_PATH=<binary> before the loop. Record which binary was used; a before/after comparison is only clean when both sides ran the same binary. Check whether the user configured the chrome-devtools MCP. Do not install or auto-run an unpinned registry MCP on their behalf.

  3. Create results directory:

    mkdir -p "$LIGHTHOUSE_DIR"
    
  4. Take baseline screenshots before any changes:

    • mcp__chrome-devtools__navigate_page (type: "url", url: <url>)
    • mcp__chrome-devtools__take_screenshot

    Describe the current layout, key elements, and visual state. This is your visual baseline — you will compare against it after every change to catch regressions.

  5. Confirm with user: Show the URL, confirm the dev server is running, ask if there are specific pages or routes to audit beyond the main URL.


Audit Protocol

Each audit consists of 3 mobile + 3 desktop runs, averaged per category.

Run the audits

# Mobile runs (Lighthouse default is mobile)
for i in 1 2 3; do
  lighthouse <url> \
    --output=json \
    --output-path="$LIGHTHOUSE_DIR/mobile-$i.json" \
    --chrome-flags="--headless --no-sandbox" \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done

# Desktop runs
for i in 1 2 3; do
  lighthouse <url> \
    --output=json \
    --output-path="$LIGHTHOUSE_DIR/desktop-$i.json" \
    --chrome-flags="--headless --no-sandbox" \
    --preset=desktop \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done

Extract scores

For each JSON result file:

cat "$LIGHTHOUSE_DIR/mobile-1.json" | \
  jq '{
    performance: (.categories.performance.score * 100),
    accessibility: (.categories.accessibility.score * 100),
    bestPractices: (.categories["best-practices"].score * 100),
    seo: (.categories.seo.score * 100)
  }'

Compute averages

Average the 3 runs per category for both mobile and desktop. Report as:

## Audit Results

| Category | Mobile (avg) | Desktop (avg) |
|----------|-------------|---------------|
| Performance | XX | XX |
| Accessibility | XX | XX |
| Best Practices | XX | XX |
| SEO | XX | XX |

Extract failing audits

From the JSON, find specific audits that failed or scored poorly:

cat "$LIGHTHOUSE_DIR/mobile-1.json" | \
  jq '.audits | to_entries[] | select(.value.score != null and .value.score < 0.9) | {id: .key, score: .value.score, title: .value.title, description: .value.displayValue}'

Sort by impact (lowest scores first). These drive the improvement loop.


Diagnose From the JSON, Not From a Narrative

Before planning any fix, re-derive the bottleneck from the report you just ran. Prior session notes, state files, and issue write-ups go stale and get root causes wrong — treat them as hypotheses to check against the JSON, never as the diagnosis.

Classify the perf gap first:

  • TBT high (hundreds of ms) → main-thread problem. Long tasks, hydration, script execution. mainthread-work-breakdown and long-tasks tell you where.
  • TBT low (~tens of ms) but LCP high under throttlingMethod=simulate → bytes-on-critical-path problem, NOT execution. Lantern replays observed traffic over simulated slow 4G, so eager bytes inflate LCP even when the page is actually fast. Fixes that defer execution will not move this; only removing or lazy-loading bytes will.

Do not read mainthread-work-breakdown's total as "blocking work before paint" — it is the whole page load. TBT is the blocking measure.

For bytes-on-critical-path gaps, attribute before fixing:

jq '.audits["resource-summary"].details.items[] | {resourceType, requestCount, transferSize}' "$LIGHTHOUSE_DIR/mobile-1.json"
jq '.audits["bootup-time"].details.items[:5]' "$LIGHTHOUSE_DIR/mobile-1.json"
jq '.audits["network-requests"].details.items | sort_by(-.transferSize)
阅读完整来源 ↗