前端性能优化器

核心原则

本文件只负责流程编排。测量细节、指标口径、分析规则、修复策略和记录模板都放在 references/ 中，执行到对应阶段时再读取。

• 所有结论必须来自真实测量、项目源码或构建配置，不凭经验编造。
• 每轮只保留最值得处理的 Top 3 问题，避免记录膨胀。
• 原始 Lighthouse JSON 保存到 perf-record/artifacts/，Markdown 只写决策摘要。
• Performance 和 Best Practices 同时达标才算完成。
• 若工具不可用，按参考文件中的降级方案继续，并在记录中说明缺失数据。
• 默认采用人工参与的分步确认模式：每个 Step 完成后暂停，展示本步产物、风险和下一步计划，询问用户是否继续；除非用户明确要求全自动连续执行，不要一条指令跑完整个流程。
• 工具权限确认不等于流程确认。即使没有权限弹窗，也必须在每个 Step 结束时等待用户确认下一步。
• 开始正式流程前先执行 PRECHECK：检查 Node/npm、Lighthouse CLI 和 Chrome DevTools MCP 能力。不要默认自动安装工具；需要安装或配置时先向用户说明影响并等待确认。

依赖与脚本

优先使用 Chrome DevTools MCP 做页面导航、交互、trace 和定位；使用 Lighthouse CLI 做 Performance 与 Best Practices 审计。Lighthouse CLI 会启动独立 Chrome 实例，不与 MCP 冲突。

解析 Lighthouse JSON 时使用：

node {skill-path}/scripts/parse-lighthouse.js <lighthouse-report.json>

需要机器可读结果时追加 --json：

node {skill-path}/scripts/parse-lighthouse.js <lighthouse-report.json> --json

Reference 路由

按需读取，不要在开始时一次性加载所有文件。

流程总览

PRECHECK 先执行一次
PROFILE 只执行一次

每轮循环：
  MEASURE -> ANALYZE -> SUGGEST -> EXECUTE -> VERIFY -> RECORD

每个箭头都需要用户确认：
  完成本步 -> 汇报产物/发现/风险 -> 询问是否进入下一步 -> 用户确认后继续

停止条件：
  达标 / 默认 3 轮后无继续价值 / 达到 5 轮硬上限 / 用户选择停止

默认优化轮数为 3，最大硬上限为 5。第 3 轮后仍未达标时，先判断剩余问题是否仍具备“高收益、项目可控、低风险”三个条件；只有满足时才询问用户是否继续第 4/5 轮。达到 5 轮仍未达标时，停止继续小修小补，生成最终报告并列出需要架构或外部协作解决的问题。

达标标准以 references/analysis/lighthouse-metrics.md 为准。通常要求所有已测页面满足 FCP、LCP、TBT、SI、CLS 阈值，且 Best Practices >= 90。

Step 0: PRECHECK

目标：在正式测量前确认必要工具是否可用，并在缺失时给出安装或降级选择。

1. 检查 Node.js 和 npm 是否可用：

node -v
npm -v

2. 检查 Lighthouse CLI 是否可用：

npx lighthouse --version

如果 npx lighthouse 不可用，暂停流程并提示用户先安装或修复 Node/npm/Lighthouse。不要自动安装。可提供以下选项：

检测到 Lighthouse CLI 不可用。它是本 skill 的核心测量工具。

你可以选择：
1. 先在本机修复 Node/npm 或使用 npx lighthouse
2. 全局安装 Lighthouse：npm install -g lighthouse
3. 暂停本次性能测量

处理完成后请回复“继续”。

3. 检查 Chrome DevTools MCP 是否可用。优先确认当前工具列表中是否存在类似能力：

list_pages
navigate_page
performance_start_trace
performance_stop_trace
performance_analyze_insight

如果 MCP 不可用，不阻塞流程，但必须提示降级影响并让用户选择：

未检测到 Chrome DevTools MCP 或等价浏览器控制能力。

你可以选择：
1. 先配置 Chrome DevTools MCP，以获得 trace、network、DOM、截图等定位能力
2. 继续使用 Lighthouse CLI 降级模式
3. 停止本次任务

4. 将工具状态写入 perf-record/summary.md 或当前任务记录：

Node/npm：{可用/不可用}
Lighthouse CLI：{可用/不可用}
Chrome DevTools MCP：{可用/不可用/降级}
降级影响：{无/缺少 trace insight/缺少 browser navigation 等}

完成后暂停，请用户确认工具状态和是否接受降级；确认后再进入 PROFILE。

分步确认规则

默认不要自动连续执行完整流程。每个 Step 完成后，按以下格式向用户汇报并暂停：

已完成：Step N - {阶段名}

本步产物：
- {写入或更新的文件}
- {关键测量结果/分析结论/建议摘要}

需要你检查：
- {需要用户确认的页面、数据、风险或选择}

下一步计划：
- Step N+1 - {阶段名}：{将要做什么}

是否继续进入下一步？

用户可以回复“继续”“修改”“跳过”“停止”或补充约束。根据用户回复调整后续步骤：

• 继续：进入下一步。
• 修改：按用户反馈修正当前 Step 的产物，不进入下一步。
• 跳过：记录跳过原因，再进入用户指定的后续步骤。
• 停止：保留当前记录并生成阶段性总结。

如果用户在初始指令中明确说“全自动执行”“不需要逐步确认”“跑完整个流程”，才可以连续执行；即便如此，在 SUGGEST 选择优化项、EXECUTE 修改代码、VERIFY 发现明显恶化、进入第 4/5 轮前，仍应暂停请求用户确认。

Step 1: PROFILE

目标：建立性能优化所需的最小项目上下文，并创建记录目录。

1. 读取 references/project-perf-profile.md。
2. 探测并记录只影响性能测量和优化决策的信息：
   - 应用根目录、框架、构建工具、包管理器
   - dev/build 命令和 dev URL/端口
   - 候选测量页面
   - 登录、cookie、token、local state 等前置条件
   - 入口文件、路由文件、构建配置、认证相关文件
   - 微前端状态和证据
3. 在被优化项目根目录创建 perf-record/：

perf-record/
├── summary.md
├── round-1.md
├── round-2.md
├── final-report.md
└── artifacts/

将项目画像摘要写入 perf-record/summary.md。不要把完整项目扫描结果写进记录。

完成后暂停，请用户检查项目画像、测量页面、登录前置条件和记录目录是否符合预期；确认后再进入 MEASURE。

Step 2: MEASURE

目标：在选定页面上采集基线数据。

1. 读取 references/measurement/mcp-tools.md。
2. 如果页面需要登录，读取 references/measurement/login-flow.md。
3. 确认目标页面可访问。优先使用 Chrome DevTools MCP；不可用时使用参考文件中的降级方案。
4. 对每个测量页面运行 Lighthouse CLI，至少输出 Performance 和 Best Practices JSON。
5. 用 scripts/parse-lighthouse.js 解析 JSON。
6. MCP trace 可用时，按问题动态选择 insight；不可用时记录“未采集 MCP trace”。
7. 将核心指标、测量条件和 artifact 路径写入 perf-record/round-N.md。

原始 JSON 命名建议：

perf-record/artifacts/round-N-{page-slug}-baseline-lighthouse.json

完成后暂停，请用户检查测量页面、测量方式、核心指标和 artifacts 是否正确；确认后再进入 ANALYZE。

Step 3: ANALYZE

目标：从真实测量结果中筛出本轮最值得处理的问题。

读取：

• references/analysis/lighthouse-metrics.md
• references/analysis/lighthouse-opportunities.md
• references/analysis/lighthouse-best-practices.md

分析要求：

• 只基于 Step 2 的 Lighthouse JSON、解析结果、MCP trace 洞察和项目源码证据。
• Performance 候选来自未达标指标、Opportunities、Diagnostics 和 trace 洞察。
• Best Practices 候选来自实际扣分项，按安全/兼容/体验风险排序。
• 标注每个问题的影响指标、证据位置、可控性和预估收益。
• 合并 Performance 与 Best Practices 候选，只写入本轮 Top 3。

将结果写入 perf-record/round-N.md 的“Top 问题”章节。

完成后暂停，请用户检查 Top 问题、证据、可控性和优先级是否合理；确认后再进入 SUGGEST。

Step 4: SUGGEST

目标：把 Top 问题转换为用户可选择的优化项。

输出一张建议表，不在此阶段直接改代码：

## 优化建议 - 第 N 轮

当前状态：Performance X 分 | Best Practices X 分
已达标指标：...

| # | 影响指标 | 优先级 | 问题 | 证据/位置 | 可控性 | 优化方向 | 预估收益 |
|---|---------|--------|------|-----------|--------|---------|---------|
| 1 | ... | ... | ... | ... | ... | ... | ... |

询问用户选择要执行的项。将建议摘要和用户选择写入 perf-record/round-N.md。

本 Step 必须等待用户选择优化项。没有用户选择时，不进入 EXECUTE。

Step 5: EXECUTE

目标：执行用户确认的优化，并完成构建验证。

按问题类型读取对应参考文件：

• 构建配置问题：读取 references/optimization/build-config.md
• 资源加载问题：读取 references/optimization/resource-optimization.md
• 代码层问题：读取 references/optimization/code-level.md
• 微前端问题：读取 references/optimization/microfrontend.md
• Best Practices 问题：读取 references/analysis/lighthouse-best-practices.md

执行规则：

• 修改必须对应 Step 3/4 中的具体问题编号和证据。
• 改动范围保持小而可验证，不做无关重构。
• 如需要用户确认方案，先给出目标文件、修改内容、预期影响和风险。
• 修改后运行项目已有的构建或检查命令；没有明确命令时，根据项目画像选择最合适的验证方式。
• 将改动清单和验证结果写入 perf-record/round-N.md。

完成后暂停，请用户检查改动文件、构建结果和风险说明；确认后再进入 VERIFY。

Step 6: VERIFY

目标：用与基线相同的页面和条件复测。

1. 读取 references/measurement/mcp-tools.md 中的复测和降级规则。
2. 对本轮涉及页面运行同等 Lighthouse 测量。
3. 可用时补充 MCP trace；不可用时记录缺失原因。
4. 对比优化前后 Performance、FCP、LCP、TBT、SI、CLS、Best Practices。
5. 标注达标、未达标或恶化。

原始复测 JSON 命名建议：

perf-record/artifacts/round-N-{page-slug}-verify-lighthouse.json

将对比结果写入 perf-record/round-N.md。

完成后暂停，请用户检查复测是否与基线可比、指标是否改善或恶化；确认后再进入 RECORD。

Step 7: RECORD

目标：让每一步优化清晰可追踪，但不保存冗余明细。

读取 references/record-template.md，更新：

• perf-record/summary.md：项目画像摘要、测量范围、轮次索引、关键 artifacts 索引
• perf-record/round-N.md：步骤日志、基线、Top 问题、建议与选择、改动、复测、结论
• perf-record/final-report.md：最终汇总、总体改善、已完成改动、遗留问题和后续建议

记录原则：

• 每个阶段都更新 round-N.md 的步骤日志。
• Markdown 只保留能解释决策的摘要。
• 原始 Lighthouse JSON 只放 artifacts/，不要复制进 Markdown。
• 每个页面每轮默认只保留 baseline 和 verify 两类正式 JSON。
• 临时试跑、失败测量、重复测量默认不进入正式 artifacts。

完成后暂停，请用户检查本轮结论、遗留问题和下一步建议；确认后再决定停止、进入下一轮或生成最终报告。

继续或停止

每轮 RECORD 后判断：

• 如果所有已测页面达标，生成 final-report.md 并停止。
• 如果未达标且当前轮次小于 3，说明下一轮计划并询问用户是否开始下一轮；用户确认后回到 Step 2。
• 如果第 3 轮后仍未达标，先评估剩余问题：
• 仍有高收益、项目可控、低风险问题时，询问用户是否继续第 4/5 轮。
• 剩余问题主要来自第三方、后端、CDN、架构限制、业务约束或低收益项时，停止并生成 final-report.md。
• 如果已满 5 轮，生成 final-report.md，列出剩余问题、无法继续小步优化的原因和建议方向。
• 如果用户选择停止，保留当前轮次记录并生成阶段性总结。

任务状态维护

开始工作时维护一个步骤状态清单：

PRECHECK
PROFILE
MEASURE
ANALYZE
SUGGEST
EXECUTE
VERIFY
RECORD

如果当前环境有任务管理工具，则用工具同步状态；如果没有，就用对话中的 checklist 和 perf-record/round-N.md 的步骤日志同步状态。

每完成一步，将该步骤标记为 completed。只有在用户确认继续后，才把下一步标记为 in_progress。进入下一轮时，在任务描述和 round-N.md 中更新轮次。

任务状态只表示内部进度，不代表可以自动进入下一步。每个 Step 的状态变为 completed 后，必须先完成用户确认，再推进下一步。