这篇文章记录了 SmartPerfetto 从零到可用过程中的关键技术决策。重点放在每次架构取舍背后的约束、失败案例和修正过程,而不是功能清单。如果你也在做 AI Agent 应用,或者在做 Perfetto 这类性能分析工具,这些工程折返点应该能直接参考。
文章按三层展开:先说清楚为什么 LLM 不能直接吃 Trace,包括上下文装不下、数值计算不可靠、领域知识用不上来三个原因;然后是从 Workflow 到 Agent 的迁移过程,附带 9 轮审查里挖出的冷启动 4 层联动 Bug 和 Ghost MCP Query 这类异步生命周期错配的具体案例;最后是 Scene Classification 按需加载、Artifact Store 控制返回数据量、三层验证从误判中迭代这三个关键决策为什么这么定。
版本说明(2026-10 核查):本文保留 2026 年 3—4 月的开发复盘;代码与数量以 4 月 10 日的 f3206864 快照为基线,不代表最新接口。该快照有 165 个 .skill.yaml 文件,其中 _base.skill.yaml 是被加载器跳过的模板,分析定义为 164 个;完整模式最多 20 个 MCP 工具,轻量模式为 3 个。原图、会话摘录和延迟/token 数字是历史材料,未附完整 trace、配置与评测集,不作为本次复测结果。项目现已开源,当前使用入口见文末 v1.16.1 补充。
为什么做这个工具
我做了多年 Android 性能优化。日常工作中大量时间花在 Perfetto trace 分析上——Perfetto 是 Google 开源的系统级 trace 工具,采集帧渲染、线程调度、CPU 频率、Binder 通信等数据,几乎是 Android 性能分析的标准工具。它的 trace_processor 解析 trace 并提供 SQL 查询接口;SQLite 参与 SQL 执行,但 trace 数据并非全部存成普通 SQLite 表。
分析 trace 的过程是高度重复的:找到问题区间、查帧数据、看线程状态、追阻塞链、关联系统指标。每次做的事情类似,但每个 trace 的细节不同。这种「流程固定、细节变化」的工作特点很适合 AI Agent 来处理——把固定流程中的数据收集和初步归因自动化,人来做最后的判断和确认。
SmartPerfetto 就是这个尝试的产物。它在 Perfetto UI 上加了一个 AI 分析面板,用户用自然语言提问(如「分析滑动性能」),背后由 Claude Agent 通过 MCP(Model Context Protocol,Anthropic 提出的工具调用协议)调用 trace_processor 执行 SQL,自主完成多轮数据收集和分析。
写这篇文章的目的,是把构建过程中的工程决策和教训记录下来。从最初的「直接调 API」到现在的最多 20 个 MCP 工具(9 常驻 + 11 条件注入)+ 164 个 YAML Skill + 三层验证体系,中间的每个设计选择都有具体的反例在推动——试过不行才换的方案。这些踩坑记录对做 AI Agent 应用或者做 Android 性能工具的工程师可以直接借鉴。
开篇:同一个 Trace,两条分析路径
一个滑动 trace,120Hz 设备,用户反馈列表滑动偶尔卡顿。打开 Perfetto 看到惯性滑动阶段有 18 帧掉帧,其中 3 帧 Full 级(~60ms,120Hz 设备的单帧预算是 8.33ms)。
Jank 与帧耗时:FrameTimeline 对比 expected/actual 时间线及实际呈现情况。实际 slice 的时长不等于 CPU 渲染耗时;超过一个刷新周期也不能单独证明用户看到了卡顿。120Hz 的周期约 8.33ms,但应用预算、流水线延迟、目标帧率和刷新模式需分别确认。
jank_type是框架分类,Buffer Stuffing 表示缓冲积压相关的额外延迟,不能直接等同于“队列已满”或排除 App 责任。
路径 A:手动分析
1 | 1. 打开 Perfetto UI,拖动时间轴找到滑动区间 |
thread_state 记录线程的调度状态(Running / Runnable / Sleeping / Uninterruptible Sleep 等)。不同状态指向不同的排查方向——Runnable 通常提示 CPU 调度层面的问题,Sleeping 通常提示等待/阻塞层面的问题。
waker_utid字段记录了唤醒线程的源线程 ID,可以辅助追踪跨进程的阻塞链。
第 3-4 步是主要工作量——18 帧掉帧,每帧都需要展开 thread_state、追踪阻塞原因、关联 CPU 调度。分析过程是逐帧串行的:每帧的下钻路径可能不同(Binder? 锁? GC? IO?),全部看完再汇总。
路径 B:SmartPerfetto Agent
用户输入 “分析滑动性能” 后,下面用原会话记录 session_agent-1774679540422 的摘录说明工具编排。参数与输出已压缩为伪代码,不是可直接复制的 MCP 请求;“18 帧”等数值保留为当时记录,不能与下方只显示 7 行的截图混成同一次完整复现。
1 | classifyScene("分析滑动性能") → scrolling (<1ms, 关键词匹配) |
Metrics 快照 (来自 logs/metrics/):16 次工具调用,0 次失败,SQL 平均 652ms。
下图展示了一次完整分析的请求生命周期——从用户输入到最终结论的每一步:

图为历史设计示意:submit_analysis_plan 应读作该快照中的 submit_plan,假设状态更新用 resolve_hypothesis;图中的“验证通过”、耗时和模型置信度不是实测验收。是否启用子 Agent、工具和模型取决于配置。
两条路径的分析步骤相同——查帧数据 → 定位 jank → 追踪阻塞链 → 关联系统状态 → 归纳结论。
差异在于:手动分析逐帧串行,每帧需要手动展开和追踪;Agent 通过 scrolling_analysis 组合 Skill 批量获取全部 18 帧的结构化数据,再选代表帧深钻阻塞链。
Agent 的分析结果同时体现在 Perfetto UI 上:
- Auto-Pin:Agent 提到的关键帧和 Slice 自动标记在时间线上
- 点击跳转:结论中的时间戳和帧 ID 支持点击跳转到 Perfetto 对应位置
- 数据表格:18 帧的完整性能数据以结构化格式渲染为可排序、可筛选的表格
运行截图:以 SmartPerfetto 前端以 Perfetto 插件的形式存在

旧 UI 截图显示 Deepseek 标签及后端连接提示,用来说明插件位置;它不是 Claude agentv3 成功完成分析的证据。
运行截图:滑动分析的时候详细分析每一个掉帧的地方, 点击最左侧的箭头可以展开

截图表头是“7 条”,其中一行责任方为 UNKNOWN;不能据此证明正文 18 帧均已分析、已定因。
运行截图:滑动分析结论,代表帧分析

图中是历史模型输出。95.9% Running 支持该窗口内以运行时间为主,但不能证明“纯计算”或“最快频率仍无解”;那需要采样、关键路径和对照测量。图内频率变化也不能单独证实 governor 或温控原因。
运行截图:滑动分析结论,代表帧分析

cache_miss … makePipeline 是 pipeline/cache 工作的线索,不能仅据名称确认全部是 shader 编译。图中嵌套 slice 耗时不能直接相加;“后续 6 帧”也只说明该样本,不能证明以后永不再发生。
运行截图:每一轮分析都有单独的分析 report,内容完整性需单独核查

这是 2026-03-30 的旧报告:页面同时显示“发现问题 0”和两条假设,不能当作零问题或假设已核实的依据。报告与 UI 的数据一致性需按版本单独验证;v1.16.1 后续修复见文末。
分析结论、数据表格和 Perfetto 时间线在同一个界面上。Agent 完成批量数据收集和初步归因后,工程师在 Perfetto UI 上确认关键发现。
需要说明的是,当前 Agent 在复杂边界情况下仍然需要人的判断(后文会具体讨论误诊问题)。这篇文章记录的是构建这个 Agent 背后的工程决策过程。
第一部分:为什么 LLM 不能直接分析 Trace?
在开始讨论架构之前,需要先回答一个根本问题:为什么不能直接把 trace 数据发给 LLM 让它分析?这个问题的答案决定了 SmartPerfetto 整个架构的出发点。
数据规模:trace 文件装不进上下文
真实 trace 的大小和事件数取决于设备、时长与录制配置。原文中的 50–500MB、数百万至千万事件、展开后数 GB,是当时样本的量级示例,不是固定换算关系。二进制 trace 的文件大小也不能直接换算成模型 token。
原文“200K tokens ≈ 150KB”不成立:token 与字节的比例受语言、文本和 tokenizer 影响,模型上下文上限还随型号、版本与接入方式变化。上下文变大后,仍需给工具定义、历史消息和输出留预算。
SmartPerfetto 因此把 trace 留在 Trace Processor 中,按需查询目标进程、时间窗和字段,再把结果送给模型。这既控制上下文开销,也保留查询与原始数据之间的可追溯关系;并不是说模型永远不能直接读取任何小型 trace 摘要。
精确计算:LLM 不擅长处理数值
性能分析的日常工作围绕精确数值展开:帧耗时的 P50 / P90 / P99 分位数、VSync 周期估计(按局部刷新模式和有效采样核对)、CPU 利用率的百分比计算、各线程状态的时间占比。
LLM 处理这类数值计算时经常出错。一个实际例子:早期测试中,Claude 把 16.7ms 的帧耗时判断为「正常,未超过 VSync 周期」——它按 60Hz(16.67ms)的帧预算来算了。但这个 trace 采集自一台 120Hz 设备,单帧预算应该是 8.33ms,16.7ms 超预算了一倍。这类错误看起来很小,但在性能分析中会导致完全相反的结论。
数值交给 SQL 和固定统计逻辑计算,可以复查并减少模型心算错误,但结果正确仍依赖查询口径、数据完整度与函数版本。中位数、分位数参数不能混用 0–1 与 0–100;刷新率变化时也不能把全 trace 的一个周期套到每帧。
领域知识:LLM 知道但不会用
Android 的渲染管线复杂度是很多开发者没有预期到的。最常见的三种渲染路径是:标准 HWUI 管线(HWUI 是 Android 默认的硬件加速渲染引擎,应用的 View 绘制指令在主线程生成,由 RenderThread 提交给 GPU,最终经 SurfaceFlinger 合成到屏幕)、历史 Flutter UI/raster 路径(是否经过宿主 RenderThread 取决于 embedding)、以及 WebView 的 Chromium 多线程渲染路径。除此之外还有 Jetpack Compose、游戏引擎、相机管线等。SmartPerfetto 的架构检测系统目前识别 24+ 种渲染管线,不同管线的 jank 分析需要查看不同的线程和指标——这也是为什么架构检测是分析的第一步。
卡顿的根因可能跨线程(主线程阻塞 → 原因在 RenderThread)、跨进程(App 等待 → system_server 的 WindowManagerService 响应慢)、甚至跨硬件层(CPU 调度到小核 → 算力不足 → 帧超时)。
LLM 的训练数据中包含这些概念——它「知道」什么是 RenderThread,什么是 Binder,什么是 SurfaceFlinger。但面对一个具体的 trace,它缺乏将这些知识按场景分阶段运用的能力。比如分析滑动卡顿时,需要先检查帧级数据(哪些帧掉了、掉帧类型是什么),再针对占比最高的根因类型选择不同的深钻路径(App 侧阻塞走 blocking_chain_analysis,合成端延迟走 SurfaceFlinger 分析)。这种分步骤、有条件分支的分析流程,需要通过策略注入来引导。
这里描述的是当时的观察与路由设计,不是所有模型的能力上限。1.ui/1.raster 是历史 Flutter 线程名,不能跨版本硬编码;较新的引擎有平台/UI 线程合并等变化。WebView 的渲染也跨 renderer、compositor、raster/GPU 等线程/进程,不能只看 CrRendererMain。路由应结合版本、surface/layer 与事件证据;特征缺失不等于架构不存在。
可靠性:错误率在实际运行中偏高
即使解决了数据访问问题,直接让 LLM 产出性能分析结论仍然面临可靠性问题。在 SmartPerfetto 的实际运行中,我观察到几类典型的输出问题:
- 幻觉:生成 trace 中不存在的数据或指标
- 遗漏:漏掉关键检查项(比如分析启动性能时不检查 JIT 编译和类加载的影响)
- 浅层归因:停在「主线程忙」的层面,不继续追踪是忙在 futex(锁竞争)、binder_wait(跨进程等待)还是 GC pause
- 结论不一致:同一份 trace 分析两次,得到不同的严重等级判定
后文“三层验证”讨论当时记录的约 30% 误判观察及其样本限制;它不是可推广的错误率。
SmartPerfetto 的分工设计
基于这四个问题,SmartPerfetto 的架构按以下方式分工:
1 | LLM (Claude) 负责: 工具系统负责: |
LLM 做推理和表达,工具做查询和计算。连接两者的是 MCP(Model Context Protocol,Anthropic 提出的工具调用协议)——Claude 通过标准 MCP 接口调用 trace_processor 执行 SQL、调用 YAML Skill 做结构化分析、查询 Perfetto stdlib 模块。分析结果通过 SSE(Server-Sent Events)实时推送到 Perfetto UI 前端。
支撑这个分工的工程基础设施包括:场景路由(根据用户问题注入不同的分析策略)、数据压缩(控制返回给 LLM 的数据量)、质量验证(拦截 LLM 的领域误判)。后面几个部分展开讨论每个部分的设计过程。
下图是完整的系统架构,展示了从用户请求到分析结论的 4 个阶段:

原图的 17 工具对应未启用对比能力的组合;快照完整模式为 9 常驻 + 最多 11 条件工具。图中的端口、模型、缓存命中率和运行耗时属于旧配置/示意,不是当前默认值或性能保证。
第二部分:从 Workflow 到 Agent
Workflow 和 Agent 的区别
Anthropic 在 2024 年 12 月发表的《Building Effective Agents》(作者 Erik Schluntz、Barry Zhang)中,将 AI 系统分为两类:
- Workflow(工作流):LLM 和工具通过预定义的代码路径进行编排。每一步做什么、下一步走哪里,都由开发者事先定义好。
- Agent(智能体):LLM 动态主导自身流程和工具使用,自主决定如何完成任务。
这个区分的实际意义在于灵活性和可控性的权衡。Workflow 提供可预测性,适合步骤固定的任务;Agent 提供灵活性,适合需要根据中间数据调整方向的开放式问题。Andrew Ng 的描述很准确:判断一个系统时,不必二元区分它是不是 Agent,可以把它看作不同程度的 Agent 化。SmartPerfetto 的 agentv2 和 agentv3 分别对应这个光谱的两端。
为什么性能分析需要 Agent 而不是 Pipeline
性能分析不是一个「给输入得输出」的固定流程,它是一个探索性的推理过程。以一个实际的滑动分析为例:
1 | 1. 先看总览 → 发现 47 帧卡顿,P90 = 23.5ms |
每一步决策都依赖前一步的结果——无法在分析开始前就确定所有步骤。Pipeline 也能用分支、循环和状态机处理动态路径;这里选择 Agent,是把部分开放式选路交给模型,而不是说固定程序做不到。
SmartPerfetto 的设计是确定性和灵活性的混合:已知场景(滑动、启动、ANR 等)用 Strategy 文件列出必检项,再验证是否遗漏;但每个阶段内的具体查询和深钻方向由 Claude 自主决定。未匹配的场景由 Claude 在可用工具、预算和权限内探索。
agentv2:一个典型的 Workflow
agentv2 使用 DeepSeek 作为后端,采用 Governance Pipeline 架构——通过 planner / executor / synthesizer 三阶段编排,可以把它理解成预定义的多步骤工作流(历史 commit 367f61ee5: “Replace the 13-step agentv2 governance pipeline with Claude-as-orchestrator”)。
这个架构在标准 Android 应用的滑动分析上工作得不错,但遇到非标准情况就出问题了。比如部分 Flutter trace 因录制配置、系统版本或 surface 关联缺失而没有可用的标准 frame_timeline 结果,管线拿到空结果后继续执行后续步骤,最终输出基于空数据的结论。
agentv3:迁移到 Agent 架构
2026 年 3 月 2 日(commit 367f61ee5),我切换到 Claude Agent SDK。Claude 接收工具定义和策略后,自主决定调用什么工具、按什么顺序、查什么数据。
本项目按以下职责组织 Agent,agentv3 的实现对照如下:
| 特征 | SmartPerfetto 中的实现 | 代码位置 |
|---|---|---|
| 自主性 | Agent 自主决定调用哪个工具、按什么顺序 | claudeRuntime.ts |
| 推理能力 | 前 4 次相关数据工具调用可追加 REASONING_NUDGE 提醒复核 | claudeMcpServer.ts |
| 工具使用 | 最多 20 个 MCP 工具调用 trace_processor | 9 常驻 + 11 条件 |
| 规划能力 | submit_plan + requirePlan() 门控 | 轻量模式关闭 |
| 反思能力 | 3 层 Verifier + Correction Prompt (max 2 轮) | claudeVerifier.ts |
| 错误恢复 | SQL 纠错学习 + 跨会话误判模式学习 | 跨文件 |
| 记忆 | 短期: Analysis Notes / Artifact Store;长期: Pattern Memory / SQL Fix Pairs | 多种存储机制,非固定层数 |
1 | agentv2 (Workflow): 固定管线 → 当时缺少空结果分支 → 可能错误归纳 |
迁移后的 9 轮审查
从 3 月 2 日到 3 月 20 日,经历了 9 轮架构审查。其中影响最大的几轮:
| 轮次 | 日期 | 主要发现 |
|---|---|---|
| Round 1 | 3/2 | 初始 SDK 集成后 12 个修复——SQL 知识库没接入 System Prompt,jank_frame_detail 中 CPU 核数硬编码为 4 |
| Round 3 | 3/12 | 架构接线审计——12 处「实现了但没接上」的断连,比如验证管线在 0 findings 时被跳过 |
| Round 7 | 3/15 | Perfetto Stdlib 集成——预加载模块 4→22,Schema Index 708→761 |
| Round 9 | 3/20 | 18 天真实 trace 后的生产质量审查——3 P0 + 4 P1 + 5 P2,催生了三层验证系统 |
这些轮次与问题数量来自我当时的开发记录;提交内容能核对修复范围,但不能单独证明每一轮测试或所有实际 trace 已通过。本文旧 commit 编号已按提交内容替换为当前仓库可解析的编号。
冷启动 4 层联动 Bug
2026 年 3 月 19 日(commit b184547a1),发现冷启动被错误分类为热启动。追踪后发现这是一个跨 4 层的联动问题:
1 | Layer A (Perfetto Stdlib): bindApplication 的 ts 比 launchingActivity 早 ~98ms → 被过滤器排除 |
修复规模:重写 10 个下游 Skill,新增 4 个启动分析 Skill。这个问题说明在 Skill 依赖链中,上游的一个字段语义错误会逐层放大。这个修复针对当时的启动识别逻辑,不意味着所有 Android 版本的冷/温启动定义都可据单个 slice 重写。
Ghost MCP Query — 异步生命周期错配
2026 年 4 月 7 日(commit e8aa4dc65)抓到的另一类跨层 Bug:分析超时之后,session 已经清理、SSE 流已经收尾,但 trace_processor 的 stderr 仍然在 90 秒后陆续吐出 no such table: cpu_frequency_counters / no such column: ts 这类错误——孤儿日志,没有 owner 可以归因到任何 session,后文错误 4 的两个 SQL 陷阱就是从这堆 stderr 里反查出来的。
根因在 SDK Query 的异步生命周期:
1 | Layer A (Claude Agent SDK): SDK 内部的 AsyncIterator 还在生产 message |
for await 提前退出通常会调用迭代器的 return()(见 AsyncIteratorClose),生成器的 finally 也可以清理资源。因此,“break 只能影响消费侧”不是语言层面的通则。本次缺陷在包装器没有把关闭动作可靠传递到 SDK Query;修复给 sdkQueryWithRetry 增加 { stream, close } 对象,让超时及 finally 显式关闭底层查询。关闭还需幂等;已经派发到其他进程的工作是否停止,要看各层取消合同。下面是省略了配置和异常处理的生命周期示意:
1 | // claudeRuntime.ts |
这个 Bug 之所以隐蔽,是因为表面症状(孤儿 SQL 错误日志)和真实根因(异步资源生命周期错配)相隔很远——错误信息长得像「Agent 写错 SQL」,但其实是「Agent 早就停了,是 SDK 子进程没停」。在 Agent 应用中,”break 一个循环” 经常没有想象中那么干净;任何长生命周期的异步资源都需要显式的 close 通道,而不是依赖 for-await 的自动析构。
第三部分:三个关键的工程决策
决策 1:Scene Classification — 从全量注入到按需加载
一开始我把 12 个场景(scrolling / startup / ANR / interaction / pipeline / game / memory 等)的分析策略全部塞进 System Prompt,总计 15000+ tokens。逻辑是:Claude 应该知道所有场景的分析方法,这样不管用户问什么都能应对。
实际运行后发现 Claude 会混淆不同场景的术语——在分析滑动时引用了启动阶段的指标,把 VSync 间隔(帧间时序)和 bindApplication(进程初始化)搞混。一个可能原因是不同场景的术语存在大量重叠,「帧」在滑动场景里是渲染帧,在启动场景里是首帧显示,同时提供 12 套策略增加了选错上下文的机会。
解决方式是做场景分类,每次只注入一套策略:
1 | // sceneClassifier.ts — 12 场景, <1ms 执行 |
关键词和优先级声明在每个 .strategy.md 的 YAML frontmatter 中,不硬编码在代码里:
1 | # scrolling.strategy.md |
场景的声明入口是 .strategy.md;开发环境支持相应加载机制,新增后应确认服务端注册结果。
当时记录中,按需加载把 System Prompt 从约 15000 tokens 降到约 4500,场景混淆有所减少。该数字来自项目自己的 token 估算,不能当作实际账单或所有会话的硬上限。新增声明式场景可从 .strategy.md 开始;是否还需 Skill、输出与验证改动取决于功能。
当多轮对话积累了较多上下文(分析笔记、历史计划、模式记忆等),System Prompt 可能重新超过 4500 token 预算。这时按优先级逐个丢弃低价值段落:SQL 知识库参考(可按需查询)→ trace 数据完整度提示 → 历史分析经验 → 历史踩坑记录 → SQL 纠错对 → 子代理协作指引 → 历史分析计划。核心段落(角色、方法论、场景策略、输出格式)不会被丢弃。
如果删除这些可选段后仍超预算,快照代码只记录 warning,并不继续裁掉核心段落。因此 4500 是软预算;完整度提示被删后,查询层仍须保留 unknown 与缺失证据。开发热加载也取决于服务端缓存/文件监听策略,不是浏览器刷新本身重新执行所有配置。
决策 2:Artifact Store — 控制返回给 LLM 的数据量
决策 1 解决了 System Prompt 的膨胀问题。但即使场景策略只注入了一套,Agent 在执行过程中每次调用 Skill 仍然会产生大量数据(200+ 行帧数据),这些数据全部放进上下文带来新的问题。
早期版本把 Skill 执行结果(比如 200 行帧数据、487 行阻塞分析)完整返回给 Claude。每个 Skill 结果约 3000 tokens,一次分析调用 5-8 个 Skill,仅 Skill 数据就占 15000-24000 tokens。
token 成本是一方面,更意外的发现是:数据越多,Claude 的输出质量反而越差。面对 200 行帧数据时,它倾向于逐行描述(「帧 1 耗时 12.3ms,帧 2 耗时 15.7ms…」)而不是做模式归纳。我猜测原因是上下文中充斥大量数字后,LLM 的注意力被分散了。
解决方式是把 Skill 结果存入 ArtifactStore,返回给 Claude 的只有紧凑引用(~440 tokens)——行数、列名和摘要信息。需要详情时,Claude 通过 fetch_artifact 按需分页获取。结构化结果通过 SSE(Server-Sent Events)的数据事件发送给前端渲染,不经过 LLM。
1 | invoke_skill("scrolling_analysis") 执行结果: |
fetch_artifact 的三个粒度:
| 级别 | 返回内容 | 约 tokens |
|---|---|---|
summary | 行数 + 列名 + 首行样本 | ~50 |
rows | 分页数据 (offset/limit) | ~200-500 |
full | 原结构,快照最多返回 500 行,超出标记 truncated | 随内容变化 |
调整后每个 Skill 的 token 成本从 ~3000 降到 ~440,8 个 Skill 从 ~24000 降到 ~3520 tokens。Claude 的输出从逐行描述变成了模式归纳,前端仍然能拿到完整数据做表格渲染。
这里的“全量”指执行结果合同允许返回的数据,不是整份 trace。full 也有 500 行上限;更多行要读取 truncated/totalRows 并分页,不能因拿到摘要就认定已经审查全部数据。约 440/3000 tokens 是样本估算,内容、分页次数与缓存都会改变总消耗。SSE 是同一分析流内的独立数据事件,不必是另一条网络连接。
决策 3:三层验证 — 从真实误判中学到的
agentv3 上线约 18 天后,我在 2026 年 3 月 20 日做了质量审查,对应修复提交 1c64fd8fb。当时记下的“约 30% 结论含误判”让我挺意外,但我没有附样本数量、抽样方式、标注规则和逐条结果;这个数字只能保留为当时观察,不能当作模型错误率基准或验证器拦截率。
几个当时促成验证规则的例子,也需要区别经验规则与确定事实:
| 原输出/规则 | 核查时应确认的边界 |
|---|---|
| 把 VSync 对齐偏移标 CRITICAL | 先确认刷新模式、时间源和呈现影响;±0.5ms 不是所有设备通用的正常阈值 |
| 把 Buffer Stuffing 都算作 App 掉帧,或全部排除 | 它与生产节奏、缓冲积压和额外延迟相关;应分别报告框架标记、呈现间隔与 App deadline,不能直接免除 App 责任 |
| 单帧异常不能是 CRITICAL | 单帧也可能造成明显冻结;严重程度需看绝对延迟、交互及影响,不能只看是否重复 |
| 主线程 Sleeping 35%(469ms)必须从 MEDIUM 升 HIGH | Sleeping 可能是正常等待或关键路径阻塞;先确定窗口、等待原因与对 TTID/TTFD 的影响,占比不足以定级 |
这些案例涉及规则、数据口径和推理链,不能只归因于“训练数据缺少领域知识”。当时的验证框架大致分三类:
1 | 1. 启发式检查:匹配已知问题模式 |
在 f3206864 的 claudeVerifier.ts 中,第 3 类可按启发式条件跳过,也可能超时或返回无法解析的结果。它没有独立重新查询整个 trace;另一个模型复核文字不等于独立事实验证。历史 passed 主要表示收集到的问题中没有 error,不能把 skipped/unknown 自动当作完整验收。
发现严重问题时可生成 Correction Prompt,最多两次修正;第二次受是否出现新错误等条件约束。预算耗尽、超时、证据不足和修正完成应分别报告,不能只因为生成了结论就宣告通过。
跨会话模式记录到 logs/learned_misdiagnosis_patterns.json。快照要求 occurrences >= 2 且未过期才加载,但重复出现不证明规则正确。例如原稿“TTID 1912ms 比 dur_ms 1338ms 多 43% 就应升级”必须先确认两个时长的开始点和定义;否则可能把不同口径之差错误学成规则。
第四部分:为什么不用标准的 Skill 系统?
从 SOP 到 YAML Skill 的设计选择
做性能分析的团队一般都有自己的 SOP(标准操作流程):滑动卡顿怎么查、启动慢怎么分析、ANR 怎么定位。SOP 通常是一份文档或检查清单,有经验的工程师照着做,新人跟着学。
Claude Code 的 Skills 以 SKILL.md 提供指令,也能携带脚本、模板和参考资料;不能简单等同于参数化 Prompt。这里比较的是当时只给模型 SOP 文本的做法,与项目自定义的 YAML 查询引擎。标准 Skill 同样可以调用确定性脚本或 SQL。
我一开始也走了这条路。给 Claude 的 Prompt 是:「查询 frame_timeline 表,找出 jank 帧,分析主线程在 jank 帧期间的状态分布。」
Claude 理解意图没问题,但每次生成的 SQL 不一样。有时候 JOIN 路径写对了(slice → thread_track → thread),有时候直接写 slice.utid——这个列不存在。查出来的结果格式也不固定,有时候 3 列有时候 5 列,前端渲染没法做。
原因很简单:SOP 是给人看的,工程师看到「查 frame_timeline」知道具体该写什么 SQL。LLM 对 Perfetto 的 SQL schema 理解不完整(这些 schema 在训练数据中覆盖有限),每次从 SOP 文本到 SQL 的翻译过程都会引入方差。
SmartPerfetto 的 YAML Skill 采用了另一条路线:声明式的 SQL 执行单元。
1 | # YAML Skill: SQL 预定义,结果格式固定 |
这段是省略 Skill 输入声明的教学片段。thread_state 直接用 utid,没有 track_id;查询按半开窗口裁剪每段状态,排除未知/未结束的 dur <= 0。百分比的分母是窗口内已观测状态时长,不把缺失时间填成零。UTID 和纳秒边界应由调用端解析、校验,不能把任意文本拼入 SQL。
这里比较的是“每次自由生成 SQL”和“调用预定义查询”两种执行合同。前者也能做评测、约束输出和组合执行;后者更容易固定数据集、参数与输出 schema,做确定性回归。YAML 本身不保证查询正确,仍需核对时间窗、单位、身份和缺失数据。
| 维度 | Prompt 模板 (SOP 式) | YAML Skill (声明式执行) |
|---|---|---|
| SQL 来源 | LLM 每次动态生成 | YAML 预定义,参数替换 |
| 结果格式 | 每次可能不同 | 固定的列名和类型 |
| 可回归测试 | 可评测,但需控制生成方差 | 可固定查询;6 条 trace 是当时记录的样本集 |
| 前端渲染 | 需要解析自由文本 | Schema-driven 表格/图表 |
| 可组合 | 可由 Agent/脚本编排 | composite skill 调用 atomic skill |
| 厂商适配 | 需要写不同 Prompt | .override.yaml 覆写 SQL |
最终的分工是:Claude 负责理解意图、选择 Skill、推理归因;YAML Skill 负责精确的 SQL 查询和结构化输出。Claude 通过 invoke_skill 调用 Skill,Skill 返回结构化数据,Claude 基于数据做判断。
为什么不把每个 Skill 暴露为独立的 MCP Tool?
一个自然的问题是:为什么不直接把 87 个 atomic 分析能力注册为 87 个 MCP Tool,让 Claude 直接调用?
实际试过会发现一个问题:MCP 的 tool list 会随着工具数量线性增长。如果把 87 个工具的描述、schema 和说明全部提前放入模型上下文,会占据可观预算;当时还观察到选工具困难,但没有足够评测据此推导工具数量与准确率的普遍关系。
SmartPerfetto 的设计是 Claude 只看到 2 个和 Skill 相关的 MCP Tool:
invoke_skill(skillId, params)— 执行指定的 Skilllist_skills(category?)— 按场景类别查询可用的 Skill 列表
通过 list_skills(category="scrolling") 按需发现能力,再用 invoke_skill 调用。2 个 MCP Tool 封装了 160+ 个分析能力,顶层工具 schema 的数量保持固定。
另一个好处是 YAML 格式降低了贡献门槛。性能分析专家如果对某个分析场景有经验,可以直接写 YAML Skill 定义 SQL 查询和输出格式,不需要懂 TypeScript 或修改后端代码。复用现有执行能力时可通过开发环境的热加载迭代,仍需确认服务端已加载新定义并验证输出。
上述开销指把全部 schema 提前装入上下文的实现方式,不是 MCP 协议强制每轮重发所有工具。工具搜索、延迟加载和 prompt caching 都会改变成本;工具多也不必然降低准确率。两个入口稳定的是顶层 schema,list_skills 返回的目录和后续结果仍占 token。新增 YAML 只有复用现有 step、输出类型和动作时才通常不必改 TypeScript;新能力仍需引擎实现与验证。
Skill 系统的结构
Skill 数量从项目初期的十几个增长到当时的 164 个,增长驱动力来自分析实践中不断出现的新场景,而不是「尽可能多」本身:比如最初只有标准 HWUI 的帧分析,后来遇到 Flutter 应用需要专门的 Skill,再遇到厂商差异需要 override,再遇到启动分析中 JIT、class loading、Binder pool 各自需要独立的检测逻辑。
f3206864 中分析定义按目录统计如下(排除 _base.skill.yaml 模板,定义数不等于独立场景数):
| 类型 | 数量 | 位置 | 说明 |
|---|---|---|---|
| Atomic | 87 | skills/atomic/ | 单一检测能力(VSync 周期、CPU 拓扑、GPU 频率、GC 事件等) |
| Composite | 29 | skills/composite/ | 多步组合分析(如 scrolling_analysis 编排多个 atomic Skill) |
| Pipeline | 28 | skills/pipelines/ | 渲染管线检测 + 教学(24+ 种 Android 渲染架构识别) |
| Module | 18 | skills/modules/ | 按模块分类的分析(app / framework / hardware / kernel) |
| Deep | 2 | skills/deep/ | 深度分析(CPU profiling、callstack 分析) |
另有 skills/vendors/ 下 8 个厂商的 .override.yaml(Pixel / Samsung / Xiaomi / Honor / OPPO / Vivo / Qualcomm / MTK),覆盖通用 Skill 中的厂商特定 SQL。
分层结果
早期 Skill 的输出是平铺的——一个 Skill 返回一张大表,200 行帧数据混在一起,用户打开就看到全量数据,没有层次感。实际使用中发现工程师的阅读习惯是:先看概要(掉帧率多少、P90 多少),再决定要不要展开看详情,再针对具体帧深钻。
现在 Skill 的输出按层级组织,前端渐进式渲染:
1 | summary — "47 帧卡顿, P90=23.5ms, SEVERE 占 12%" |
Skill 的每个 step 通过 display.level 声明自己的展示层级(具体取值与数量随快照变化,不作为稳定接口)。前端根据 DataEnvelope 中的列类型(timestamp、duration、percentage、bytes 等)和交互动作(navigate_timeline 跳转到 trace 位置、navigate_range 选中时间范围、copy 复制数据)自动渲染表格和图表——复用已有列类型与交互的 Skill 通常不需要额外前端代码。这是 164 个 Skill 而前端代码量仍然可控的关键。
Step 类型
最初所有 Skill 都只有一种 step:执行一条 SQL。后来遇到需要组合多个 Skill 的场景(比如 scrolling_analysis 需要先查帧数据,再对每个 jank 帧做阻塞分析),以及需要遍历数据行的场景(逐帧诊断),逐步扩展了 step 类型:
| Step 类型 | 说明 | 使用频次 |
|---|---|---|
atomic | 单条 SQL 查询,最基础的 step 类型 | 最常用 |
skill | 引用另一个 Skill 的结果,用于组合分析中复用已有能力 | 56 处 |
iterator | 遍历数据行,对每行执行子查询 | 5 个 composite Skill 中使用 |
diagnostic | 诊断步骤,生成结构化的诊断结论 | 38 处 |
parallel | 并行执行多个 step(代码已支持,尚未在 Skill 中使用) | 0 |
conditional | 根据条件选择分支(代码已支持,尚未在 Skill 中使用) | 0 |
iterator 是逐帧分析的核心——比如对 18 个 jank 帧中最严重的 8 个,逐一执行 blocking_chain_analysis,每帧独立分析阻塞原因。parallel 和 conditional 在类型系统中已定义,目前还没有 Skill 使用——这是因为当前的分析场景用 skill 引用 + iterator 遍历已经能覆盖,后续引入更复杂的场景(如多路并行数据采集)时会用到。
领域 Skill 举例
以下几个例子说明为什么需要这么多专用 Skill——每个 Skill 背后都有一个「通用方案处理不了」的具体问题。
Consumer Jank Detection — 框架标记 ≠ 用户感知
jank_type、相邻帧的呈现节奏和主观流畅感是不同口径。框架没有标记某类 jank,不代表交互一定流畅;呈现间隔变长也可能是目标低帧率、静止画面或动画结束,不能都算掉帧。
历史 consumer_jank_detection 的意图是用 VSync 周期与 1.5 倍间隔阈值补充框架标记,并把大于 6 个周期的间隔视为会话断点。但核查实现时有几个限制不能省略:
vsync_config会吸附到若干固定刷新率,另一段间隔查询却另算未吸附周期;没有 VSYNC-sf/expected 数据时回退 60Hz。回退不是设备测量值,也不覆盖可变刷新率。- 查询中把
PERCENTILE(..., 0.5)当中位数;Perfetto 的 PERCENTILE 参数范围是 0–100,中位数应使用 50。不能只凭变量名vsync_median宣称得到了中位数。 present_ts是从actual_frame_timeline_slice.ts + dur构造的代理值,LAG 按upid分区,去重按进程和 token;并非无条件保证“同 layer 的实际扫描显示时间”。多 layer、重复 token 和丢弃/未结束帧都要继续检查。
因此,这里展示的是当时启发式及其已知边界,不能称为独立的用户感知真值或所有刷新模式下的正确掉帧计数。本次修订文章,没有修改 SmartPerfetto 仓库或复跑这一算法。
阻塞链分析 — 跨线程、跨进程的根因追踪
一帧掉帧的根因可能涉及多层因果链:
1 | 帧 42 耗时 62ms (预算 8.33ms) |
blocking_chain_analysis Skill 用 3 步 SQL 提供这条链的关键线索:主线程状态分布(Running / Sleeping / IO 各占多少)→ 唤醒者追踪(通过 waker_utid 找到是谁唤醒了主线程)→ 阻塞函数汇总(futex / binder_wait / io_schedule 各累计多少时间)。这种跨层分析用通用 Prompt 让 Claude 自己写 SQL 很难稳定实现。
上面是待验证的链路示例。waker_utid 是观测到的唤醒者,不自动等于锁持有者或 Binder 服务端;futex 等待也不必然是互斥锁竞争。还需锁事件/调用栈、Binder 事务关联、对端状态和时间顺序逐边建立因果关系。
Flutter 架构分支 — 不同渲染模式需要不同分析逻辑
这里比较历史 Android embedding 的两种承载 surface,不是 Flutter 渲染后端的全部分类;Skia/Impeller 与 SurfaceView/TextureView 是不同维度。表中线程名属于旧样本:
| 模式 | Jank 分析目标线程 | 是否经过宿主 RenderThread |
|---|---|---|
| TextureView (双管线) | 1.ui + 1.raster + RenderThread | 是 |
| SurfaceView (单管线) | 1.ui + 1.raster | 否 |
如果用标准 HWUI 的分析逻辑去分析 Flutter SurfaceView 应用,会把 1.raster 线程的耗时错误归因到 RenderThread。SmartPerfetto 通过架构检测(24+ 种渲染管线)自动识别 Flutter 应用并切换到专用的 flutter_scrolling_analysis Skill。
但「自动识别 Flutter」本身也踩了坑(commit efb464acf,4/6)。早期的 pipeline 检测器是给每种架构单独打分,分数最高的胜出——结果 Flutter TextureView 的 trace 经常被误判为 STANDARD。原因是 Flutter TextureView 的宿主侧仍然走 HWUI 管线(Choreographer#doFrame / DrawFrame / RenderThread),这些信号同时被 STANDARD 和 TEXTUREVIEW 两个分类吸收。STANDARD 的信号覆盖面更广(trace 里几乎一定有 Choreographer 帧),总分常常压过专属的 TEXTUREVIEW,把 Flutter 应用误分到 STANDARD。同样的问题也出在 WeChat Skyline(被 WEBVIEW 吸收)和游戏引擎(被 STANDARD/MIXED 吸收)上。
修复在相关通用候选的 YAML 中补 exclude_if:例如 TEXTUREVIEW_STANDARD 看到 Flutter/WebView 信号时退出竞争;STANDARD_LEGACY/MIXED/SURFACEVIEW_BLAST 排除 Game Engine 信号;OPENGL_ES 排除 WebView/Game,WebView 候选排除 Flutter。它不是某个 TEXTUREVIEW 对象主动关闭所有 STANDARD。24+ 种 pipeline 不能各打各的分,需要一个「特化 → 通用」的优先级链。 这是「pipeline 多了之后必须做相互排斥」的典型例子——也是为什么 Skill 数量增长到 160+ 之后,光「正确路由到哪个 Skill」本身就成了独立的工程问题。
新版本应核对 Flutter 架构说明及具体 engine 配置。Android/iOS 的平台/UI 线程合并已使“必须存在独立 1.ui”失效;Platform Views 组合模式也会改变路径。宿主有 RenderThread 不证明 Flutter 所有帧都经过它,SurfaceView 也不意味着整个页面只剩一条管线。
厂商覆写 — 同一指标在不同平台上的字段名不同
高通、联发科、Google Tensor 的 trace 中,相同指标的字段名不同(比如 GPU 频率在高通叫 gpufreq,联发科可能叫 gpu_freq_khz)。.override.yaml 让同一个 Skill 在不同平台上自动适配 SQL,不需要为每个厂商写独立 Skill。
gpufreq/gpu_freq_khz 只是需核查的 track/event 命名示例,不是高通或联发科的统一字段合同。还要核单位、采样保持方式、设备与内核版本。快照中的 8 份 override 都是 startup.override.yaml;不能据此声称所有厂商 GPU 频率已自动适配。
第五部分:SQL 工程
前面讨论的 Skill 系统最终都落到 SQL 查询上——每个 Skill 的 step 执行的是预定义的 SQL。SQL 是 SmartPerfetto 的核心——所有性能数据的获取最终都通过 SQL 查询 trace_processor 完成。这部分展开讨论 SQL 层面的几个工程问题:查询模式设计、官方 stdlib 复用、Schema 索引、结果压缩和纠错学习。
SQL 查询模式:时间区间 JOIN 和递归分桶
trace 中的 slice、sched 和 thread_state 常以开始时间及持续时长表示区间。关联帧与阻塞候选时,要计算交集,不能只筛“开始时间落在帧内”的事件,否则会漏掉跨帧边界的等待。
下面是教学查询:jank_frames 与 blocking_calls 是调用方预先构造、已限定同一目标进程/线程及分析范围的关系,不是 Perfetto 内置表。时间重叠提供关联线索,本身不证明某调用阻塞了该帧。
1 | WITH overlaps AS ( |
先在纳秒值上过滤大于 0.5ms 的交集,最后显示为两位小数;不是先四舍五入再过滤。原稿在非聚合查询末尾使用 HAVING 不正确,现改为 CTE 外层 WHERE。时间以纳秒表示也不等于采集具有纳秒测量准确度。多个候选区间可能嵌套,不能直接把它们的 overlap 相加当作总阻塞时间。
递归分桶的原稿还引用了未定义的 bucket_ns、overlap_dur,并可能在第 30 桶截断窗口。下面按 Perfetto v58.3 的 sched.utid/ucpu/ts/dur 展示完整的已观测运行时长分桶;正整数窗口宽度向上取整,最多 30 桶覆盖整个窗口:
1 | WITH RECURSIVE |
${...} 是需由调用端替换的已校验整数,不是原生 Perfetto SQL 参数语法。返回的是各桶、各 ucpu 的已观测 Running 时间;没有 sched 行的桶不输出,不擅自当作空闲或采集完整。若要分大核/小核,还需已验证的 CPU capacity/拓扑映射,把未知类保留为 unknown。原稿的 _cpu_topology 由项目 cpu_topology_view Skill 创建,不是稳定公共 stdlib 合同,不能跨设备默认推导 prime/big/medium/little。
Skill Engine 支持自己的 ${param|default} 模板语法,缺省值和校验由引擎合同决定;它不替代输入类型、范围和 SQL 注入边界检查。
Perfetto Stdlib 复用
Perfetto 官方维护了一套 SQL 标准库(stdlib),提供了大量预定义的视图和函数。比如 android_frames 视图封装了帧渲染数据的多表关联逻辑,_android_critical_blocking_calls 内部表汇总了关键阻塞调用。直接使用这些官方抽象,比手写 SQL 从底层表关联要稳定得多。
SmartPerfetto 对 stdlib 的集成经历了几轮迭代——其中一次回退还把「优化的方向」整个翻了过来:
- 初始阶段: 只预加载了 4 个 stdlib 模块(android.frames.timeline、android.binder、android.startup.startups、android.input),大部分 Skill 的 SQL 直接查底层表。优点是启动快,缺点是 Skill 里到处自己手写多表 JOIN
- Round 7 (3/15): 把预加载集扩展到 22 个模块,包括
linux.cpu.utilization、android.garbage_collection、android.oom_adjuster、slices.with_context,覆盖 CPU/GC/OOM/slice 等常用维度。当时的逻辑是:trace 加载时一次性把所有常用 stdlib 模块批量INCLUDE,后续查询无需重复初始化这些模块,但执行查询仍有开销 - 回退到 lazy 加载(4/1,commit
9d313df5a):当时记录的大 trace 加载中出现socket hang up,修复把 eager preload 收缩为 3 个 Tier-0 模块,在首个查询前按需串行加载,并限制失败重试。这个提交支持“减少并发初始化压力”的设计选择,但单凭断连错误不能把原因证明为 SQLite 的 schema mutation,也不能把 Trace Processor 整体等同于一个普通 SQLite 数据库:
1 | // workingTraceProcessor.ts |
这 3 个是按「skill 引用次数」筛出来的最高频依赖。其余 stdlib 模块改由 Skill YAML 的 prerequisites 段或 SQL 里显式的 INCLUDE PERFETTO MODULE 在第一次用到时按需声明
- 按需发现:
perfettoStdlibScanner.ts扫描 Perfetto 源码目录自动发现所有可用模块,通过list_stdlib_modulesMCP 工具让 Claude 按需INCLUDE非预加载的模块
1 | // perfettoStdlibScanner.ts — 扫描 perfetto/src/trace_processor/perfetto_sql/stdlib/ |
这次调整适合当时的加载瓶颈。Lazy 加载降低初始化工作量,也把部分延迟推到首次查询;稳定的高频模块仍可能适合预热,应按连接模型、trace 规模和测量结果选择。
另一个独立的教训是:使用 stdlib 的 android_garbage_collection_events 视图比自己 JOIN slice + thread + process 表查 GC 事件要稳定得多——因为 GC 事件的 slice name 在不同 Android 版本中有变化(concurrent mark sweep vs young concurrent copying vs HeapTaskDaemon),stdlib 已经处理了这些兼容性问题。但 stdlib 视图自己也有坑(列名前缀、模块未自动加载),后面 SQL 纠错那一节会展开讲。
stdlib 复用可以减少重复逻辑,但不能保证跨版本稳定。_android_critical_blocking_calls 这类下划线内部对象尤其不应当作公开稳定 API;源码目录扫描得到的模块也必须与实际运行的 Trace Processor 版本一致。
SQL Schema Index:让 Claude 知道有什么表可以查
Perfetto trace_processor 包含数百个表和视图,加上 stdlib 的模块,Claude 不可能全部记住。lookup_sql_schema MCP 工具提供了一个搜索接口,让 Claude 按关键词查找相关的表、视图和函数定义。
底层是一个从 Perfetto 源码自动生成的索引文件(perfettoSqlIndex.light.json),包含 761 个模板,每个模板记录了名称、类别、类型(table/view/function)、列定义和参数。
查询时使用分词匹配 + 评分排序:
- 名称/类别/描述中包含完整搜索词 → 高分
- 多词查询按 token 分别匹配 → 匹配 ≥50% 的 token 才算相关
- 表名的下划线分段支持前缀匹配(”frame_time” 匹配 “frame_timeline_slice”)
- 返回 top 30 结果
配合 sqlKnowledgeBase.ts 的意图映射,还支持双语查询:用户输入「卡顿」会映射到 ['jank', 'frame', 'dropped'] 等搜索词,输入「启动」会映射到 ['android_startups', 'launch', 'time_to_display']。多个意图同时命中时,分数叠加——比如查询「启动帧卡顿」同时触发 startup 和 jank 两个意图,匹配到两者交集的模板分数最高。
SQL 结果压缩
当 Claude 使用 execute_sql 直接查询时,可以传入 summary=true 参数触发结果压缩。压缩逻辑在 sqlSummarizer.ts 中实现:
数值列: 计算 min、max、avg 和分位数(P50 / P90 / P95 / P99),让 Claude 了解数据分布,不需要看原始行。
字符串列: 统计 top 5 值及其出现次数,了解数据的类别分布。
样本行选择: 从完整结果中选 10 行有代表性的样本。选择策略是:如果数据中有 dur、latency、jank、count 等和性能相关的列,按该列降序排列取 top 10(最严重的数据通常最有分析价值);如果没有明确的性能指标列,等间距采样。
1 | -- 200 行原始结果 (~3000 tokens) 压缩为: |
这和前面提到的 Artifact Store 配合使用——Artifact Store 压缩的是 Skill 结果(invoke_skill 返回的数据),SQL Summarizer 压缩的是 Claude 直接执行 SQL 时的结果。两层压缩覆盖了 Agent 获取数据的两条路径。
统计范围是传入 summarizer 的结果行,不自动等于整份 trace;查询 LIMIT、前置过滤、缺失值和截断需随结果解释。按性能列取最差 10 行是极值样本,不是总体的无偏代表;分位数插值和数值精度也应与 SQL 口径核对。JSON 图例省略字段且含注释,不能直接解析执行。
SQL 纠错学习
Claude 对 Perfetto 的 SQL schema 不完全熟悉,会写出有错误的查询。以下是实际记录的典型错误(来自 logs/sql_learning/error_fix_pairs.json):
错误 1:JOIN 了不存在的列
Perfetto 的 slice 表没有直接的 utid 列。要关联 slice 和 thread,需要经过 thread_track 中间表:slice.track_id → thread_track.id → thread_track.utid → thread.utid。
1 | -- 错误: no such column: s.utid |
错误 2:列名歧义
1 | -- 错误: ambiguous column name: name (slice 和 process 都有 name 列) |
错误 3:把 counter 采样点当作区间
counter 保存时间戳和值,没有 dur。AVG(value) 是样本均值,采样不均匀时不等于时间加权均值,不能作为同义修复。
若目标是某窗口的时间平均频率,需要按 track 分区,以 LEAD(ts) 构造分段,带入窗口开始前最后一个有效样本,裁剪边界,再算 SUM(value * overlap_ns) / SUM(overlap_ns)。末段是否延续到窗口终点必须有明示的采样保持假设;没有覆盖的时间保持未知。CPU 频率还可使用下方 linux.cpu.frequency 的区间结果,并核对 kHz 单位。
错误 4:stdlib 表名 / 列名陷阱
这两类错误在 commit a262dadf1 中被加入方法论 Prompt 的 SQL 陷阱说明;这个提交修改的是模板,不能把它当作运行时自动学习了两个纠错对的证据。这次排查的线索就是超时后的孤儿 stderr:分析早就结束了,trace_processor 还在喷错误日志,顺着日志才找回这些 SQL 问题。
1 | -- 错误 4a: no such table: cpu_frequency_counters |
上面省略了筛选条件;GC 查询还要先 INCLUDE PERFETTO MODULE android.garbage_collection;。gc_dur 是 GC 区间,不能当作主线程 Stop-the-world 暂停;不同线程/阶段的 Running、Runnable 与暂停需分别关联。表和列按 Perfetto v58.3 的 frequency 与 garbage_collection 核对。
stdlib 视图作者经常会用领域前缀的列名来避开多表 JOIN 时的 ambiguous column 问题,但 Claude 默认假设的是 ts/dur 这种通用约定。这种「stdlib 自己的命名习惯 vs 通用 SQL 习惯」的冲突没法靠 schema introspection 完全自动解决——lookup_sql_schema 工具能告诉 Claude 表存在和有哪些列,但不能预测「这次 Claude 一定会想当然地写 ts」。还可在生成前提供实际 schema、限制可用列并对结果语义做校验;纠错对只是辅助。
这些错误的检测和学习机制是这样的:当 SQL 执行失败时,错误信息和 SQL 被暂存;当后续有 SQL 执行成功时,系统通过 Jaccard 相似度匹配(排除 SQL 结构关键词如 SELECT/FROM/WHERE,以及 Perfetto 通用 token 如 utid/dur/slice)判断是否是同一查询的修正版本。匹配阈值 >30%,时间窗口 60 秒。匹配成功则生成 error→fix 对并持久化到磁盘。
新分析开始时,读取最多 10 条纠错对,再将其中最多 5 条呈现在 System Prompt,Claude 在写 SQL 之前就能看到这些已知的坑。纠错对设置 30 天 TTL,过期自动清理——Perfetto 的 SQL schema 会随版本更新变化。
执行成功只表示 SQL 被接受,不证明修复保留了原意或数值正确。相似度和时间窗口匹配可能误配;30 天 TTL 也不等于 schema 版本绑定,旧经验仍需在目标 trace 与引擎上复查。
第六部分:开发过程本身的 Harness 演进
最后一个部分稍微跳出产品本身,聊一下开发过程。SmartPerfetto 是用 AI 辅助开发的——从第一行代码到现在,Claude Code 是主要的编程工具。回顾这三个月,我使用 AI 辅助开发的方式本身也经历了几次迭代,和 SmartPerfetto 从 agentv2 到 agentv3 的演进有相似的逻辑。
AI 辅助开发的几个阶段
先简要说明涉及的工具和概念:
- Claude Code:Anthropic 的 CLI 工具,可以在终端中与 Claude 对话,Claude 能直接读写文件、执行命令。我在开发中一直开启
--dangerously-skip-permissions(危险模式)和 bypass permissions,让 Claude 无需逐次确认即可自主执行文件编辑、命令运行、Git 操作等。这大幅提升了迭代速度——Claude 可以连续执行「改代码 → 跑测试 → 看结果 → 修复 → 再跑」的完整循环而不被权限弹窗打断,代价是需要开发者对 Claude 的操作有足够信任和事后审查 - Claude Agent SDK:Anthropic 提供的 Agent 开发框架,SmartPerfetto 的 agentv3 后端基于它构建。SDK 封装了多轮对话管理、MCP 工具调用循环、上下文自动压缩(auto-compact)等能力,开发者定义工具集和 System Prompt,SDK 驱动 Claude 自主完成多轮分析
- Plan Mode:Claude Code 的规划模式,AI 先输出结构化实施方案(要改哪些文件、改什么、依赖关系),人审查确认后再执行代码修改
- Superpowers:第三方开发工作流/Skill 集合,不是 Claude Code 插件生态的统称,也不等于 Chrome DevTools 或 Playwright MCP。这里保留原文“SuperPower”作为当时使用习惯的称呼;Plan Mode 是 Claude Code 自身的功能。
- Codex + Codex MCP:Codex 是 OpenAI 的编程 Agent 产品/工具系列,不是一个固定模型名称。历史流程通过本地 MCP 集成让另一个 Agent 审查;
codex mcp-server是 CLI 提供的集成入口,是否只读由工具和沙箱配置决定,不是“用了 MCP”就自动只读。参见 CLI reference。 - Agent Team / Subagent:子 Agent 可以有独立上下文与角色;当前 Agent teams 与 subagents 是不同机制,不能把“并行启动子 Agent”直接称为完整团队功能。
- Skills / Hooks:Claude Code 的扩展机制,Skills 是可复用的任务模板(如
/commit、/simplify),Hooks 是在特定事件(如工具调用前后)自动执行的脚本
我的实际演进过程
阶段 1:直接对话
最早期的开发方式是在 Claude Code 中直接描述需求,让 AI 修改代码。类似于结对编程中一个人说、一个人写。这个阶段人需要逐行审查每次修改,因为 AI 对项目上下文的理解有限,经常做出不符合整体架构的局部修改。
阶段 2:Plan Mode(SuperPower)
开始使用 Plan Mode 后,工作流变成:我描述需求 → AI 输出结构化的实施方案(要改哪些文件、每个文件改什么、改动顺序和依赖关系)→ 我审查方案 → 确认后 AI 执行。这把 review 的重心从「逐行看代码」转移到了「审查架构方案」,效率明显提升。
阶段 3:Plan Mode(SuperPower) + 引入同行 Review(Codex)
单靠一个 AI 生成方案,容易出现盲区。我开始在 Plan Mode 的方案确定后,把方案发给 Codex 做独立审查。Codex 以只读方式访问代码库,从架构合理性、边界情况、遗漏风险三个角度给反馈。这相当于在 AI 开发流程中引入了 code review 环节。
文章前面提到的 9 轮架构审查,大部分都经过了这个流程。以 Perfetto Stdlib 集成为例(Round 7,3 月 15 日),Codex 审查了 3 轮,累计提出 36 条反馈,其中涉及 stdlib 模块预加载策略、Schema Index 的缓存失效机制等我在方案中遗漏的问题。
阶段 4:Harness 化的工程流水线
到后期,开发流程变成了:
1 | 1. 我确定需求和架构方向 |
这个流程中,人的介入集中在第 1 步(需求和架构决策)和第 4 步(评估 review 反馈)。代码细节、测试执行、格式整理由工程流水线完成。
上面保留的是当时 SmartPerfetto 的开发流程,不是读者当前 checkout 的统一验证命令。原文未提供这次运行的完整终端结果;脚本存在、SSE 结束或产出报告,都不能单独证明根因判断正确。复现时应固定 commit、trace、模型/配置、预期证据与终态,并分别记录 deterministic 检查、真实模型 E2E 与失败/跳过结果。
和 SmartPerfetto 架构的对应关系
回过头看,我的 AI 辅助开发流程和 SmartPerfetto 的 Agent 分析流程在结构上是相似的:
| 维度 | SmartPerfetto Agent 分析 | 我的 AI 辅助开发 |
|---|---|---|
| 意图理解 | Scene Classifier 识别场景 | 我确定需求方向 |
| 策略注入 | .strategy.md 注入分析方法论 | Plan Mode 输出实施方案 |
| 执行 | MCP 工具调用 SQL/Skill | Claude Code 执行代码修改 |
| 质量验证 | 三层 Verifier (启发式+Plan+Haiku) | 回归测试 + Codex review |
| 纠正循环 | Correction Prompt 让 Claude 修正 | 测试失败 → 分析 → 修复 → 重跑 |
| 跨会话学习 | Pattern Memory + SQL 纠错 | CLAUDE.md 规则积累 + memory 系统 |
两个系统的演进方向也一致:人的介入从执行层逐步上移到决策层。 SmartPerfetto 从固定管线(人定义每一步)到自主推理(人定义目标和约束);我的开发方式从逐行 review 到审查架构方案。
这不是偶然——Harness Engineering 的核心就是构建足够的工程基础设施(测试、验证、review),使得人可以信任 AI 的执行结果,把注意力放在更高层的决策上。
下图汇总了 SmartPerfetto 的 Harness Engineering 全景——从输入路由到跨会话学习:

原图保留作结构示意。其“拦截约 30% 误诊”没有检测率评测支持,不能由原文的约 30% 观察误判率推导;80% 缓存命中率、85% 节省和“越用越准”也不是已验证保证。快照正向/负向模式 TTL 分别为 60/90 天,不能统一读成 90 天。
结语
回顾这三个月的迭代,从 agentv2 的 13 步固定管线到 agentv3 的自主推理,从记录中的误判问题到三层验证,从 15000 tokens 的 System Prompt 到 4500 tokens 的按需加载——每一步变化都有具体的失败经历在推动。
做完这个项目之后,我对 AI Agent 应用开发有两个体会。
第一个是:主要工作量不在 LLM API 调用本身,而在围绕 LLM 的工程基础设施:
- System Prompt 怎么组织,才能让 LLM 不混淆上下文?→ 场景分类 + 按需加载 + Token 预算
- 怎么控制 LLM 的执行顺序,让它先想再做?→ Planning Gate + Hypothesis 提交
- 返回多少数据给 LLM 合适?→ Artifact Store,给摘要而不是全量
- 怎么发现和拦截 LLM 的领域误判?→ 三层验证 + Correction 循环
- 怎么保证数据查询的精度?→ YAML Skill (声明式 SQL) + SQL 纠错学习
- 怎么适配不同渲染架构和芯片平台?→ 架构检测 + 厂商覆写
第二个体会是:Agent 的「环境」比 prompt 的措辞重要得多。 agentv3 初期我花了不少时间调整 System Prompt 的用词和格式,后来发现影响 Agent 输出质量的主要因素是工具、数据返回方式和约束,而不是 prompt 措辞。三个具体的例子:
- 加了
submit_plan门控后,Claude 不再没有方向地查 SQL(之前会出现连续SELECT * FROM slice→SELECT * FROM thread的无目的查询),分析路径变得有组织 - 加了 ArtifactStore 后,Claude 接收到的数据从 200 行降到摘要引用,推理的聚焦度明显提升
- 加了
lookup_knowledge工具后,根因分析的深度从「主线程阻塞」推进到「Binder 对端 system_server 因 CPU 被调度到小核导致响应延迟」
这些改进都来自 Agent 工具集和数据环境的变化,不来自 prompt 文字微调。如果我要给做 AI Agent 应用的工程师一个建议,就是把精力放在工具设计和数据控制上,少把问题压到 prompt engineering 上。
后续方向
以下为 2026 年 4 月的历史规划,原“目前闭源、尚未发布”的状态已过期。 当时由我个人开发,主要方向包括:
- 厂商深度接入 — 当时 8 个厂商目录中的
.override.yaml只覆盖了核心 Skill。更多厂商专属指标(高通 Snapdragon Profiler 数据、联发科 MAGT 信号、三星 GameOptimizing 服务)需要逐一对接 - CI 集成 + 批处理 — 从交互式分析到 CI Pipeline 中自动分析每次构建的性能回归。包括无人值守模式、结果对比基线、自动标记 regression
- E2E 验证框架 — 当前的 6 条 trace 回归测试验证 Skill 产出数据的正确性,但不验证 Agent 的结论质量。需要建立 E2E 验证:给定 trace + 已知根因 → 检查 Agent 是否正确定位
- 代码库接入 — 将 trace 中的 slice/function 映射回源码位置,结合 git blame 定位变更引入点
2026-10 更新(v1.16.1):项目现已开源,提供 Web UI、CLI、报告与 portable runtime。以 v1.16.1 README 和发布记录为当前使用参考;不能沿用本复盘中的旧工具清单、模型与启动配置。
该版本发布说明明确修复 HTML 报告的数据行、时间线、嵌套内容及对比/批量数据保留,以及离线交互。这也说明“生成报告”和“报告完整呈现所有证据”是两项不同的验收。源码、文档和 release 可核查,并不等于本次文章审查已经重新验证全部设备、模型或 trace 场景。
历史开发源码入口:MCP 注册、Artifact Store、System Prompt。这些固定链接解释本文四月的设计;新版行为应查对应 tag。
关于我 && 博客
下面是个人的介绍和相关的链接,期望与同行的各位多多交流,三人行,则必有我师!
- 博主个人介绍 :里面有个人的微信和微信群链接。
- 本博客内容导航 :个人博客内容的一个导航。
- 个人整理和搜集的优秀博客文章 - Android 性能优化必知必会 :欢迎大家自荐和推荐 (微信私聊即可)
- Android 性能优化知识星球:付费社群已于 2026 年停止运营,不再招收新成员;此处保留历史介绍。
一个人可以走的更快 , 一群人可以走的更远
旧群二维码保留作历史图片,不保证仍有效;当前问题反馈可使用 项目 Issues。






