Perfetto Trace 分析

分析 Android Perfetto trace 二进制文件（protobuf 格式），覆盖冷启动耗时、启动阶段分解、掉帧/卡顿等场景。

核心工具

scripts/trace_analyzer.py — 纯 Python 实现，零第三方依赖，直接用任意 Python 3.8+ 运行。

# 1. 先列进程，确认目标应用
python scripts/trace_analyzer.py list <trace文件>

# 2. 冷启动分析（--app 可为包名或 pid；不指定则自动选事件最多的应用进程）
python scripts/trace_analyzer.py cold-start <trace文件> --app <包名|pid> [--out report.html]

# 3. 掉帧/卡顿分析（阈值默认 16.7ms，60Hz；车机/高刷屏可调整）
python scripts/trace_analyzer.py jank <trace文件> --app <包名|pid> [--threshold-ms 16.7] [--top 20]

# 4. 原始切片浏览（按时间排序，带层级）
python scripts/trace_analyzer.py slices <trace文件> --app <包名|pid> [--min-ms 1]

所有模式都会先在终端输出文本摘要；cold-start 和 jank 模式每次运行结束自动生成五段式 Markdown 故障排查报告（文件名为 <应用>_<冷启动|卡顿分析>故障排查报告.md，可用 --md-out 改路径、--no-md 关闭），内容包括：问题概述、完整问题链路、根本原因分析（直接/深层）、影响范围评估、分级修复建议。--out 另可追加生成 HTML 报告（深色主题，含时间轴 SVG）。分析完成后必须用 present_files 把生成的 Markdown 报告展示给用户。

工作流程

识别应用：先跑 list。应用进程名形如 com.xxx.yyy；surfaceflinger/system_server/launcher 是系统进程，不要选成分析目标。用户只给应用中文名时（如"情景模式"），从进程列表中根据包名语义匹配（如 com.wt.scene），拿不准时向用户确认。
按用户问题选模式：冷启动/启动耗时 → cold-start；掉帧/卡顿/流畅度 → jank；其他（如看某个线程在干什么）→ slices 或直接读脚本输出后用 Python 补充查询。
解读并给结论：脚本会自动推导异常点（严重/中等/轻微分级）并生成五段式 Markdown 排查报告；在此之上用对话补充归因解读，不要只贴数据。
报告结构固定为五段：问题概述 → 完整问题链路 → 根本原因分析（直接原因/深层原因 + 证据链）→ 影响范围评估 → 分级修复建议（P0/P1/P2 + 复测验证）。报告由 write_md_report() 自动生成，Agent 在其基础上做人工补充，无需重写。

冷启动分析的关键锚点

起点：AppLaunch_dispatchPtr:Down（system_server，用户点击图标）→ 没有则退化为 startActivity::server → 再退化为应用首个事件。
终点：system_server 的 instant launchingActivity#N:completed*（系统启动完成标记）→ reportFullyDrawn → 首帧 reportDrawFinished。
阶段：AMS startActivity → app activityStart（含 performCreate/资源加载）→ performStart → activityResume → 首帧 doFrame → （若 Splash→主界面两段式）第二次 activityStart → 主界面首帧 → completed。
冷启动真实性判断：trace 中搜 bindApplication/ClassLoader。若完全没有，说明应用进程已存在（进程预热/常驻），本次实为"热/温启动"——向用户说明，系统标记中的 completed-warm 即此含义。

瓶颈归因（按优先级）

超长 doFrame（>3 倍帧周期）：看其子切片——measure/layout/traversal 过长通常由 inflate 或主线程图片解码（Decoding WxH bitmap、ImageDecoder）引起；主线程解码大图是最常见问题，建议异步加载 + inSampleSize 降采样。
monitor contention：锁竞争片段显示 owner 线程，频繁出现说明启动路径上有串行化瓶颈。
GC / JIT：窗口内 GC 与 JIT compiling 次数多说明内存/编译开销大。
启动前耗时（点击 → AMS startActivity）过长是 launcher/系统侧问题，非应用问题。

厂商 trace 布局兼容

脚本自动探测 ftrace 字段布局（见 references/proto-field-notes.md）。已知某车机（MTK Android14，Perfetto v34）使用非标准布局：bundle.event=2, print=3, print.buf=2, ts=1；标准布局为 bundle.event=1, print=22, print.buf=3, ts=8。若遇到新布局解析为 0 切片，用探测输出（list 的 proto 布局探测 行）+ slices 采样排查，并在 detect_layout() 的 candidates 中补充。

局限

只解析 ftrace print（atrace）事件与进程树；不解析 TrackEvent/sched 的深度分析（counter 已提取但仅计数）。
掉帧统计基于应用侧 Choreographer#doFrame 切片，不含 SurfaceFlinger frametimeline 精确判定。
时间均为 CLOCK_BOOTTIME，输出为相对偏移毫秒。