一个快速、独立、token 高效的命令行工具，基于 Chrome DevTools Trace Engine 构建。它可以检查 Chromium 性能追踪文件（.json 或 .json.gz），并将其转换为结构化、高信号量的摘要，专为 LLM 上下文窗口、AI 编程代理和开发者性能诊断而优化。

原始 Chromium 性能追踪文件体量巨大（未压缩时通常为 20MB–200MB+），包含数百万条底层 JSON 事件。将原始追踪文件直接喂给 LLM 会迅速耗尽 token 限额、产生高昂成本，并让模型淹没在噪声之中。

从 npm 全局安装 trace-engine-cli，将其添加到 $PATH：

npm install -g trace-engine-cli trace-engine-cli /path/to/trace.json.gz

或使用 npx 直接运行：

npx trace-engine-cli /path/to/trace.json.gz

与 AI 编程代理配合使用

trace-engine-cli 采用渐进式自发现设计，AI 编程代理可以在运行时了解其能力，而无需将完整手册加载到系统提示中。

默认概览 + 内置下钻提示（trace-engine-cli <file>）： 不带子命令调用 trace-engine-cli <file> 会运行 overview，并在输出末尾附加 # Drill-down commands: 参考页脚。首次调用即可让代理获得追踪时间范围、Core Web Vitals、主线程类别细分，以及每个后续子命令的准确语法。

顶层命令发现（trace-engine-cli 或 trace-engine-cli --help）： 不带参数运行 trace-engine-cli 或传入 --help 会打印全部 13 个子命令（overview、insights、tasks、find、profile、diff、scheduling、network、interactions、shifts、events、navigations、scan）以及全局选项。

子命令参数发现（trace-engine-cli <subcommand> --help）： 对任意子命令运行 --help（例如 trace-engine-cli insights --help 或 trace-engine-cli events --help）会打印该命令的参数、可选值和默认值。

方案 1：极简 AGENTS.md / CLAUDE.md 规则 将以下片段添加到项目指令文件（AGENTS.md、CLAUDE.md 或 .cursorrules）中，阻止代理编写临时 JSON 解析脚本，并引导其使用 trace-engine-cli：

性能追踪分析（.json、.json.gz）

• 绝不要用 jq、python、node -e、zcat 或 shell 循环手动解析或搜索追踪文件。请使用 trace-engine-cli，它负责 gzip 解压、DevTools Trace Engine 解析和 token 紧凑的 TOON 格式化。
• 任何单追踪文件调查都从运行 trace-engine-cli <file> 开始。阅读概览和输出末尾附加的 # Drill-down commands: 页脚，以选择后续命令。
• 要跨多个追踪文件或目录搜索，运行 trace-engine-cli scan <dir-or-glob> [options]。
• 运行 trace-engine-cli --help 或 trace-engine-cli <subcommand> --help 查看可用子命令和参数。

方案 2：代理技能模板（SKILL.md） 如果你的代理环境支持按需技能（例如 .gemini/skills/chrome-trace-analysis/SKILL.md 或 .claude/skills/chrome-trace-analysis/SKILL.md），展开下方代码块并复制模板：

---

name: chrome-trace-analysis description: 使用 trace-engine-cli 检查和查询 Chrome/DevTools 性能追踪文件及测试夹具（.json、.json.gz）。在分析追踪事件、洞察或夹具时使用。

Chrome 与 Chromium DevTools 追踪分析

使用 trace-engine-cli 检查、剖析和诊断由 Chrome/Chromium DevTools 性能面板捕获的性能记录（.json、.json.gz）。

---

1. 操作约束

• 绝不要手动解析或搜索追踪文件：不要编写临时的 node -e、python、jq、zcat、gzcat、zgrep、zless 或 shell 循环来检查或搜索追踪文件或夹具。trace-engine-cli 负责 gzip 解压、多文件扫描、追踪引擎解析、模型遍历和格式化。
• 主动查看命令帮助：在尝试自定义变通方案之前，运行 trace-engine-cli --help 或 trace-engine-cli <subcommand> --help 查看可用命令、参数（--time-range、--category、--function、--top）和输出选项。

---

2. 核心原则

• 默认使用相对时间：时间范围（--time-range、--window-a、--window-b）默认相对于追踪开始时间（0ms 原点），与 DevTools 性能面板 UI 一致。
• 时间单位：范围参数接受毫秒或显式单位后缀（3500,4200、3.5s,4.2s、100ms,500ms）。
• 绝对时间戳：查询原始 epoch 时间戳时传入 --absolute-timestamps。
• 输出格式：使用 --format toon（紧凑的类 YAML 输出，默认值）以提升 token 效率，或在生成报告用 Markdown 表格时使用 --format md。

---

3. 命令参考

trace-engine-cli <file> / trace-engine-cli overview <file>

高层级追踪元数据、持续时间、Core Web Vitals（LCP、INP、CLS）以及主线程类别细分（Scripting、Layout、Rendering、GC、System、Idle）。不带 overview 调用 trace-engine-cli <file> 还会打印 # Drill-down commands: 参考页脚。

trace-engine-cli trace.json.gz

trace-engine-cli insights <file>

针对 Core Web Vitals 和性能瓶颈的诊断洞察卡片。

trace-engine-cli insights trace.json.gz
# 按诊断类别过滤：lcp、inp、cls、render-blocking、third-parties
trace-engine-cli insights trace.json.gz --category cls
# 定位特定导航 ID 或 InsightSet ID
trace-engine-cli insights trace.json.gz --navigation NAVIGATION_0

trace-engine-cli shifts <file>

布局偏移聚类、分数和罪魁祸首 DOM 元素。

# 聚类摘要
trace-engine-cli shifts trace.json.gz
# 包含单个偏移事件、导航 ID 和受影响的 DOM 节点
trace-engine-cli shifts trace.json.gz --events

trace-engine-cli events <file>

按名称、类别、阶段、时间范围检查并过滤原始追踪事件，或通过点号表示法提取载荷字段。

# 匹配特定事件名称

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）