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，输出为相对偏移毫秒。
