用途
web-performance 是一个 Web 性能实践技能,用于在编写或修改 Web 应用代码时应用性能默认值,或按需对现有项目进行性能审计。技能性质为建议性,不会在没有所有者同意的情况下搭建架构,审计阶段也不会编辑代码。
主要能力
模式一:默认模式(始终开启,仅限当前任务内)
在编写或修改代码时,无需请求即可应用以下默认值,且不重构当前任务未触及的代码:
- 图片:使用框架图片组件(next/image、Astro <Image>/<Picture>),WebP/AVIF 格式,设置 sizes 与显式尺寸;首屏以下使用 loading="lazy",LCP 图片不使用。
- 加载 UI:布局已知时使用匹配最终布局的骨架屏;仅未知形状或短操作使用旋转指示器。
- 输入:搜索/自动补全防抖;用 AbortController 取消过期请求。
- 数据获取:独立请求并行(Promise.all、Http::pool);共享一个缓存(TanStack Query、fetch 缓存、服务端组件),同一数据不重复调用。
- 列表/API:列表端点分页;渲染数百行的列表使用虚拟化。
- 数据库:预加载关联(with()、include/select),只选择使用的列,在迁移中为过滤/排序的列建立索引。
- 外部调用:每个出站 HTTP/AI 调用设置显式超时。
- AI 输出:面向用户的响应流式传输到 UI。
- 第三方脚本:延迟加载(next/script lazyOnload/afterInteractive、defer/async)。
- 字体:自托管 WOFF2(next/font、Fontsource),仅使用所需字重。
- 渲染:默认服务端或构建时渲染;仅在需要交互处使用客户端代码。
- 变更:结果可预测时使用乐观更新并在出错时回滚。
架构规则(7 任务队列、10 Redis、18 OpenTelemetry、19 同区域、28 负载均衡)默认不引入。若与任务相关,在报告中添加一行:perf proposal: rule N -- 原因。
模式二:审计模式(按请求触发:“audit perf”“为什么慢”)
只读加测量。仅加载存在领域的参考文档。
- 基线:使用 Lighthouse 对运行中的应用测量实验室 Core Web Vitals(bun <fuse-seo plugin>/scripts/check-cwv.ts <url>,依赖在 seo 插件的 package.json 中;或 npx lighthouse <url> --only-categories=performance --output=json);从构建输出获取 JS 大小;从日志获取慢查询/请求计时。无法建立基线时明确说明,排名标记为“估计”。
- 技术栈+领域:检测技术栈(规则 01-project-detection);保留适用领域——前端(references/front.md)、后端+数据库(references/backend-db.md)、基础设施(references/infra.md)。纯静态站点没有后端-数据库领域。
- 审查:审查这些领域的每条规则。状态为 applied / absent / not applicable / not verifiable from code 之一,附证据 file:line 或测量值。absent 时用一句话说明对最终用户的成本。
- 排名:按测量(否则估计)收益与工作量、风险对 absent 规则排名。架构规则标记为 proposal——需要所有者同意。
- 停止:呈现报告并等待所有者验证具体规则编号,之前不编辑。
- 修复:由对应技术栈领域专家逐条修复已验证规则;每条后做真实检查(测试/构建/运行应用)并在同一指标上做前后对比。出现回归则在下一条规则前回滚。
报告格式
表格包含 #、Rule、Status、Evidence、User cost、Rank 列,随后是 absent 规则排名列表:rank. #N rule -- 预期收益(测量|估计)-- 工作量 -- 风险。
负责人使用
收到“audit perf”请求时,负责人可为每个存在领域(前端/后端)运行一个领域专家,各自只加载其参考文档,然后按规则编号合并表格。
参考指南
- front.md:规则 1, 2, 4, 13, 14, 15, 20, 21, 22, 23, 26, 29, 31 —— UI、渲染、资源、客户端 JS。
- backend-db.md:规则 3, 5, 7, 8, 10, 12, 16, 17, 24, 25 —— API、服务端代码、查询、数据库。
- infra.md:规则 6, 9, 11, 18, 19, 27, 28, 30 —— 托管、CDN、响应头、依赖、监控。
禁止事项
- 审计期间或所有者验证规则编号之前编辑代码。
- 未经所有者同意搭建架构规则(7、10、18、19、28)。
- 无证据的状态;将估计收益呈现为测量收益。
- 默认模式下对当前任务之外做全面更改。
适用场景
适用于编写或修改 Web 应用代码时自动应用性能默认值,以及按请求对现有项目进行只读性能审计并逐条修复已验证问题。
限制
技能描述中未提供具体规则全文、安装步骤、收费或价格信息。