用途：分析由 Puffin 插桩应用生成的 .puffin 记录，可用用户提供的记录路径，或在使用 rerun MCP 时用 capture_profile_trace 消息。
环境要求：Rerun CLI（0.38 或更高）、Python 3.10 或更高、jq；Python 辅助脚本仅用标准库。需把 PUFFIN_SKILL_DIR 设为包含 SKILL.md 的绝对目录。
基本流程：先把追踪导出到文件，再查询该 JSON，避免整段读入上下文。命令：rerun dump-puffin <path> > /tmp/puffin.json；jq '.scopes | length' /tmp/puffin.json。若无合适 rerun 二进制但在 Rerun 检出目录内，可用 cargo run --quiet -p rerun-cli --no-default-features -- dump-puffin <path> > /tmp/puffin.json。若 scopes 长度为 0，名称会回退为 scope#<id>，缺源位置，需要新的包含作用域注册的采集，否则只能用动态数据标签并说明限制。
JSON 结构：包含 file、scopes 映射（可为空）、frames 数组（frame_index、range_ns、duration_ns、num_scopes、threads，线程内有 name、num_scopes、depth、range_ns 与 scopes 列表，每个 scope 有 id、name、start_ns、duration_ns、data、children）。name 由 scopes 映射解析，data 是每次调用的动态字符串，如事件类型或网格名。
主要用法：可用 jq 配方查看帧总览、按线程统计、最慢作用域、按名称或 (name,data) 聚合总耗时、查看某作用域的子节点（可按时间排序找并行空档）、单作用域每次调用耗时、某纳秒窗口内各线程活动。使用对象选择时，任何 .. | objects | select(.name? == …) 模式必须同时 select(has("duration_ns"))，否则会命中注册表中无 duration_ns 的条目。按名称或数据前缀查找可用 find_scopes.py（支持 --top、--aggregate、--thread、--frame、--field）。对比前后追踪用 python3 "${PUFFIN_SKILL_DIR}/compare_traces.py" /tmp/puffin.json /tmp/puffin2.json --top 50，可加 --filter、--hide-below；若两追踪一方无作用域注册，名称不匹配会导致大量行显示为新增或消失。
限制与注意：.puffin 可能产生数 MB JSON，务必存文件再查；追踪通常仅覆盖少量帧，需警惕离群帧与单次调用尖峰，不要仅凭平均值报告加速倍数。puffin 只分析被 profile_function!/profile_scope! 包裹的部分，rayon::par_iter 不会自动加等待作用域，只有 re_tracing::profile_wait! 才会，所以主线程可能出现空档，需要跨线程窗口配方排查。dumper 使用 Puffin 0.20，格式版本不兼容的采集可能需要匹配的解析器。对比时应请用户提供对应 git diff，并确认两次采集场景一致。