trace-audit

Chrome DevTools Trace 审计

分析 Chrome DevTools Performance 跟踪文件，并生成一份全面的性能审计报告。

用法

/trace-audit <path-to-trace.json>

参数是 Chrome DevTools 跟踪 JSON 文件的绝对路径（从 Performance 面板导出）。

工作流

按顺序执行以下步骤。在注明的地方使用并行工具调用。

步骤 1 — 验证跟踪文件

使用 Read 工具读取文件的前 100 行。通过检查以下内容，确认这是有效的 Chrome DevTools 跟踪文件：

• 顶层包含 traceEvents 数组，或文件以 [ 开头，是一个裸 JSON 数组
• 事件对象包含 name、cat、ph、ts 字段
• 存在 __metadata 或 TracingStartedInBrowser 事件

如果验证失败，告知用户这看起来不是 Chrome DevTools 跟踪文件，然后停止。

步骤 2 — 提取元数据

使用 Grep 从跟踪文件中提取以下内容（并行运行）：

1. 网站 URL — 搜索 TracingStartedInBrowser、navigationStart 或 FrameCommittedInBrowser，并在 args 中查找 URL
2. 进程名称 — 搜索 process_name 或 thread_name，以识别渲染器、浏览器和 GPU 进程
3. 跟踪时间范围 — 搜索第一个和最后一个 "ts": 值，以计算跟踪时长

步骤 3 — 运行检测

参考 detection-heuristics.md 了解完整的模式和阈值。使用 Grep 并行运行所有检测类别。对于每个类别：

• 使用指定的搜索模式搜索跟踪文件
• 收集匹配行；需要时附带周边上下文（-C 1 或 -C 2）
• 统计匹配项，并从匹配的 JSON 中提取时长和数值

检测类别：

1. 长任务（RunTask，dur > 50000）
2. 布局抖动（InvalidateLayout → Layout 配对）
3. 强制回流（带 stackTrace 的 Layout 事件）
4. rAF 定时器循环（RequestAnimationFrame 频率）
5. 样式重计算风暴（dur > 5000 的 UpdateLayoutTree）
6. 绘制风暴（dur > 3000 的 Paint 事件）
7. GC 压力（MajorGC / V8.GC_MARK_COMPACTOR）
8. CLS（LayoutShift 累积分数）
9. INP（EventTiming 最大时长）
10. 网络错误（ResourceReceiveResponse，且 statusCode >= 400）
11. 冗余请求（同一 URL 被多次请求）
12. 脚本求值（dur > 50000 的 EvaluateScript / CompileScript）
13. 长动画帧（LoAF / LongAnimationFrame）

步骤 4 — 汇总发现

对于每个检测类别：

• 计算标记事件总数
• 提取最严重的问题（最大时长或最高分数）
• 根据 detection-heuristics.md 中的阈值划分严重程度：严重（红色）或警告（黄色）
• 跳过没有发现问题的类别

步骤 5 — 识别时间线热点

按时间戳将标记事件归入时间窗口（例如，每 500ms 一个窗口）。找出多个问题类别重叠的窗口——这些是热点范围，代表跟踪文件中问题最严重的部分。

步骤 6 — 生成报告

按照 report-format.md 中定义的结构输出报告。报告应当：

• 可执行——每个问题都关联到具体的修复方案
• 易于浏览——使用表格、严重程度徽章和清晰的标题
• 完整——涵盖所有类别，即使只需说明“未发现问题”