这篇文章收集了《从 Trace 到洞察:SmartPerfetto AI Agent 的 Harness Engineering 实战》发布后收到的技术问题。它不重复正文的大段叙述,而是把最容易追问的设计点单独拆开。如果你已经读过正文,这里更适合作为二次阅读和交叉检索。
版本说明(2026-10 核查):这组问答解释 2026 年 4 月的设计,源码固定 f3206864。Q8 列出当时 164 个分析定义;另有 _base.skill.yaml 模板,文件总数是 165。这里的接口、阈值、缓存设计与耗时不代表最新版本或复测结果。项目现已开源,使用新版请对照 v1.16.1 文档;配套长文已同步标注历史边界。
Q1:为什么不用 Claude Code 的标准 Skill 系统,而要自建 YAML Skill?
提问背景: Claude Code 的 Skill 系统支持 scripts/ 目录放确定性脚本,避免 LLM 泛化。既然可以用 scripts/ 执行固定的 SQL,为什么还要自建一套 YAML Skill 系统?YAML Skill 能不能理解成一个让性能工程师按预定义规则执行 SQL 的工具?
关键区分:两套 Skill 不在同一个层面
Claude Code Skills 和 SmartPerfetto YAML Skills 解决的是不同阶段的问题:
1 | 开发阶段(我写代码时): |
这是本项目当时的分工,不是标准 Skill 的能力边界。Claude Code Skills 可被用户或模型调用,Agent SDK 也可按配置加载项目 Skills(见官方 SDK Skills 文档);脚本可以参数化并返回 JSON。SmartPerfetto 选择 YAML,是把查询、输出 schema 和组合执行统一交给自己的后端引擎,而让运行时的查询与展示合同集中维护。
即使只看「确定性执行」,YAML Skill 有几个针对性设计
1. 参数化 SQL,不是固定脚本
性能分析的 SQL 不是写死的——同一个 Skill 需要接受不同的参数(进程名、时间范围、帧 ID 列表):
1 | steps: |
这是省略输入声明的教学片段。thread_state 直接使用 utid,没有 track_id;按半开窗口裁剪,避免漏掉窗口开始前已进入的状态或累计窗口外时长。排除 dur <= 0 的未完成/无效区间,缺失状态不当作零。调用端先解析并校验 UTID 和纳秒边界,再由引擎替换;YAML 本身不消除注入风险。Python/Node 脚本也可以提供同样的参数与校验合同。
2. 自描述的输出格式(DataEnvelope)
1 | display: |
每个 step 声明输出列名、类型和单位,前端按 DataEnvelope 合同格式化。duration 不一定永远显示为 ms;时间线跳转还需要有效身份、时间单位及相应 clickAction。脚本若返回相同的结构化 JSON,也可以复用渲染,区别在于谁统一维护这个合同。
3. 可组合(composite + iterator)
一个 composite Skill 可以引用多个 atomic Skill,iterator 可以遍历数据行逐帧分析。这种组合在 YAML 中是声明式的,Skill Engine 负责编排执行。scripts/ 方式要实现同样的组合需要自己写编排逻辑。
4. 面向性能工程师,不是面向开发者
提问者说对了:YAML Skill 可以理解成一个让性能工程师按预定义规则贡献分析逻辑的工具。性能工程师知道该查什么 SQL、该看什么指标,但不一定会写 TypeScript。YAML 格式让他们直接定义 SQL 查询和输出格式,不需要碰后端代码。开发热加载需确认服务端已重载定义;新 step、渲染或执行语义仍可能要改代码。
对比总结
| 维度 | 标准 Skill + scripts/ | SmartPerfetto YAML Skill |
|---|---|---|
| 本项目运行位置 | 当时主要用于开发;也可接入 Agent SDK | Express 后端 Skill Engine |
| 调用方式 | 用户或模型调用 Skill,再执行脚本 | Agent 通过 invoke_skill |
| 参数化 | 脚本可定义类型、参数与校验 | 引擎提供模板替换与输入合同 |
| 输出格式 | 可为 JSON、表格或文本 | DataEnvelope |
| 前端渲染 | 接入结构化输出合同后可渲染 | 复用已有 renderer |
| 组合能力 | 脚本/工具编排 | composite、iterator 等引擎能力 |
| 贡献门槛 | 熟悉脚本及合同 | 复用现有能力时写 YAML + SQL |
引擎模板支持 ${param|default};竖线表示模板的默认值分隔符。两种方案可组合,YAML 是本项目维护成本与执行合同的选择。
Q2:「确定性 + 灵活性混合」具体是怎么实现的?
提问背景: 文章说「已知场景用 Strategy 文件约束必检项,但每个阶段内的具体查询和深钻方向由 Claude 自主决定」。这个约束和自主之间的边界在哪里?具体是怎么做到的?
三层机制配合
这个混合设计靠三层机制配合实现:Strategy 文件定义「必须做什么」,启用的 Planning Gate 要求「先提交计划再执行」,Verifier 事后检查文字与状态中的风险信号。
第一层:Strategy 文件 — 有硬约束也有软指引
以滑动分析的 scrolling.strategy.md 为例,它定义了多个分析阶段,但每个阶段的约束强度不同:
Prompt 中的强要求(不是执行层硬约束):
Phase 1.9 根因深钻是最严格的阶段,策略文件里直接用了 🔴 标记和「禁止」字样:
1 | **Phase 1.9 — 根因深钻(🔴 强制执行,不可跳过):** |
软指引(建议但可跳过):
Phase 1.5(架构感知分支)和 Phase 1.7(根因分支)用的是「建议」「改用」等措辞,Claude 可以根据实际数据决定是否执行:
1 | **Phase 1.5 — 架构感知分支:** |
Strategy 文件的全部内容被原文注入 System Prompt,注入时加了一行硬性说明:
1 | 场景策略(必须严格遵循) |
Claude 直接在 System Prompt 中看到这些阶段定义、🔴 标记和「禁止」字样。
“必须”“禁止”和红色标记只表达策略要求,不会自行拦截工具或证明已执行。后续文字启发式可能发现遗漏,也可能漏报;需要强制的前置条件应由运行时明确检查。这里的 Phase、15%/20%/5ms 等是历史策略阈值,不是跨设备有效的因果规则。
第二层:Planning Gate — 强制先计划,但不限制计划内容
启用了 analysisPlan 引用时,execute_sql 与 invoke_skill 的 MCP 入口要求先调用 submit_plan 提交分析计划。没有提交计划就调用 execute_sql 或 invoke_skill 会被直接拒绝:
1 | function requirePlan(toolName: string): string | null { |
关键点在于:Gate 只要求计划存在,不要求计划和 Strategy 的阶段完全对应。 计划仍需满足 submit_plan 的参数 schema;符合结构时可以调整阶段划分——它可以把 Phase 1 和 1.5 合并,可以加入 Strategy 没提到的额外步骤,也可以根据初步数据调整深钻方向。
提交计划时,系统会做场景感知的关键词检查(比如滑动场景检查计划中是否提到了「帧」「jank」等词),但这只是 warning 级别——计划即使不包含这些词也会被接受。
这个设计的目的是:要求 Claude 在调用受保护入口前提交计划(规划纪律),但不限制它怎么想(规划自由)。
这不是所有内部查询的全局锁:预处理、信息查询和工具内子查询不等于上述入口。Quick 未传该引用时不启用 gate。计划存在只证明提交了结构化数据,不证明模型“想清楚”或步骤已执行。
第三层:Verifier — 多维度事后检查
计划和执行之间可能有偏差——Claude 可能提交了计划但实际跳过了某个关键步骤。Verifier 在分析结束后做多维度事后检查,以启发式行为检查为主,同时补充计划/假设/场景完整性校验:
a) 场景完整性检查——分析输出是否覆盖了场景的核心内容:
1 | // 滑动场景:检查是否有显著掉帧但没做 Phase 1.9 深钻 |
b) 假设状态检查——已记录假设是否仍为 formed;状态变更不证明证据充分。
c) 因果链深度检查——CRITICAL/HIGH 级别的 findings 是否包含足够的因果连接词和机制性术语(启发式文本匹配)。
d) 可选的 LLM 复核——用独立的 Haiku 模型做证据支撑度验证(可关闭)。
如果检查发现 ERROR 级别问题,会触发 Correction Prompt 让 Claude 补做。
注意 Verifier 不检查 Claude 的计划阶段是否匹配 Strategy 的阶段编号——它检查的是「关键分析动作是否体现在输出中」,不是「计划格式是否正确」。
快照 verifySceneCompleteness 的输入是 findings 与 conclusion 拼接的 allText。hasDeepDrill 使用 hasAnalysisTool || hasKnowledgeDrill,仅出现 lookup_knowledge 等文字也可能满足条件;注释声称“真实调用”不改变实现。因果连接词、模型写下的 evidence 和 resolved 状态都不足以证明真实采证或因果成立。第三层模型审查也可跳过、超时,最多两次 correction 不保证补齐。
完整的约束光谱
把三层机制叠在一起,不同阶段的约束强度形成了一个光谱:
| 阶段 | Strategy 语气 | Planning Gate | Verifier 检查 | 约束强度 |
|---|---|---|---|---|
| Phase 1(概览) | 建议 | 需要计划 | 不单独检查 | 中 |
| Phase 1.5(架构分支) | 建议 | — | 不检查 | 低 |
| Phase 1.7(根因分支) | 建议+条件 | — | 不检查 | 低 |
| Phase 1.9(根因深钻) | 🔴 必须/禁止 | — | 匹配输出中的深钻相关文字 | 高 |
| Phase 2(补充深钻) | 可选 | — | 不检查 | 无 |
| Phase 3(综合结论) | 必须覆盖分布 | — | 检查结论完整性 | 中 |
而 general.strategy.md(未匹配到场景时的 fallback)则完全是软指引:只给了一个按用户关注方向的路由决策树(CPU → cpu_analysis,内存 → memory_analysis),没有任何必须执行的阶段。general 仍受工具、权限、预算及已启用的 gate/verifier 约束。
Q2 小结
Strategy 表达分析要求,Planning Gate 在启用时检查计划存在,Verifier 提供事后风险提示。具体查询仍可由模型选择,但“描述做过”与“日志证明执行并返回有效数据”必须分开。
Q3:Agent 和 Workflow 最大的区别在哪里?Agent 的能力边界在哪里、由什么决定?
提问背景: 我们在建设 Agent 的过程中,从最初默认 Agent 有能力理解并决策一切给它的 Skill,到现在几乎在 Skill 中写死了一棵决策树,这中间踩坑的出发点都是:「我们认为 Agent 有 xx 能力,但它没有」,导致其输出偏离我们的预期,于是我们不断地给 Skill 加边界,最后变成了一个写死的 Workflow。
本质区别:决策权在谁手里
Agent 和 Workflow 不是两个工具、两个框架——它们是同一个光谱的两端:
1 | 写死的 Workflow ◄──────────────────────────────────► 完全自主的 Agent |
| 维度 | Workflow | Agent |
|---|---|---|
| 控制流 | 开发者在代码中写死 if/else | LLM 自主选择下一步 |
| 工具选择 | 预定义执行顺序 | LLM 根据数据按需选择 |
| 分支条件 | 代码中的条件判断 | LLM 推理判断 |
| 失败处理 | try/catch + 重试逻辑 | LLM 自我反思 + 换方向 |
| 可预测性 | 确定性高 | 不确定性高 |
| 适应新场景 | 需要开发者加分支 | 可以自主探索 |
但工程实践中,几乎没有人处在光谱的任何一端。 Workflow 可提供通用查询、动态路由和拒绝/升级分支;Agent 的可靠性也随任务与约束变化。实际落地的系统都在光谱的某个中间位置。
你们踩坑的根因:对 Agent 能力做了全局假设
「默认 Agent 有能力理解一切 → 发现它做不到 → 不断加约束 → 变成写死的 Workflow」——这个路径的根本问题在于:对 Agent 的能力做了全局一刀切的判断。
但 Agent 的能力在不同环节差异巨大:
| 能力维度 | 本项目的分工考虑 | 该交给谁 |
|---|---|---|
| 意图理解(用户想干什么) | 可辅助识别,歧义需处理 | Agent(但简单场景可以用关键词匹配替代) |
| 计划制定(分几步做、先做什么) | 需任务级验证 | 需要约束框架:Strategy 文件给框架,LLM 填细节 |
| 数据收集(该查什么) | 需任务级验证 | 半自主:Skill 定义了查什么,Agent 决定顺序和参数 |
| 数据推理(看到数据后归因) | 不能由模型自评证明正确 | Agent 提出解释,证据校验约束归因 |
| 精确计算(数值统计) | 使用可复算程序 | 工具系统(SQL / Skill Engine) |
| 自我评估(知道自己对不对) | 不能独立作为验收 | 外部 Verifier,不信任 Agent 自评 |
正确的做法不是「全局选 Agent 或全局选 Workflow」,而是按环节分配:
1 | 场景识别 → Workflow(确定性逻辑,不需要 LLM 参与) |
表格是工程分工建议,不是对某模型可靠率的测量。单凭提问背景也不能诊断对方系统的唯一根因;还需看失败样本、工具合同与数据覆盖。
SmartPerfetto 的做法:约束强度光谱
SmartPerfetto 没有在 Agent 和 Workflow 之间二选一,而是对不同分析阶段设定了不同的约束强度(详见 Q2)。这里从「能力边界」的角度重新审视这个设计:
Prompt 强要求(Phase 1.9 根因深钻)——针对当时观察到的跳过深钻:
1 | # scrolling.strategy.md 中的 Phase 1.9 |
为什么强化这条提示?因为我们发现 Agent 有一个系统性偏差:它倾向于在拿到概览数据后就直接出结论,跳过深钻。概览数据已经包含 reason_code,模型可能把分类当作结论;但没有对照实验,不能证明是“认知成本低”或某种内部路径依赖造成。
提示约束较少(Phase 1.5 架构分支)——利用架构信息辅助工具选择:
1 | # scrolling.strategy.md 中的 Phase 1.5 |
这里用「改用」「注意」等建议性措辞,不强制。因为架构检测的结果(Flutter/WebView/Standard)已经被确定性代码放进了 system prompt,这提供选路依据,但识别错误、缺失信息或模型误选仍需检查。
没有固定场景步骤(general)——允许通用探索,但保留运行时边界:
1 | # general.strategy.md — 只给路由决策树,不给任何必须执行的步骤 |
general 仅表示入口未命中特定策略,不表示问题一定无法程序化,也不表示撤销所有约束。可以先做通用探索、请求更明确的目标,或在证据不足时保留 unknown;并非只能无条件信任模型。
Agent 能力边界的决定因素
模型能力、任务分布和预算会影响结果;下面讨论本项目可以直接改善的三个工程因素,不把它们当作完整的能力公式:
1. 观测能力——Agent 能”看到”什么数据
同一个模型,给它 scrolling_analysis Skill 的 L2 结构化帧数据 vs 让它自己写 SQL 查原始表,分析质量差距非常显著。Agent 可分析的范围受到数据工具的约束。SmartPerfetto 用 164 个 YAML Skill 封装了领域专家的查询逻辑,Agent 通过 invoke_skill 拿到的是处理过的、结构化的分析数据,而不是原始的百万行 trace 事件。
2. 约束框架——Agent 在什么范围内决策
不约束的 Agent 像一个没有任务清单的实习生——知识够但不知道该先做什么。Strategy 文件、Planning Gate、Verifier 多层机制共同定义了 Agent 的决策边界:Strategy 告诉它「至少要做什么」,Planning Gate 强制它「先想后做」,Verifier 事后检查「分析是否充分」(启发式检查 + 假设闭环 + 场景完整性 + 可选的 LLM 复核)。
3. 反馈质量——Agent 做错后能否被纠正
Agent 的 findings 中存在相当比例的问题(浅层归因、假阳性、遗漏关键步骤)。单纯依赖模型自我纠错效果有限。SmartPerfetto 用多层验证 + 外部纠错 prompt 来闭环:
1 | Verifier 发现 ERROR → 生成 Correction Prompt → 触发 SDK 重试 |
补充:Strategy 文件就是 SOP,这没问题
有人会指出:scrolling.strategy.md 读起来就像一份 SOP(标准作业程序)——有编号的 Phase、条件表、必做项、甚至直接写了 invoke_skill("scrolling_analysis", {...})。这和「在 Skill 里写死决策树」有什么区别?
数据收集部分借用了 Workflow 的组织思路。 Strategy 文件就是 SOP,它把领域专家的分析经验写成了步骤要求;实际调用仍由模型驱动,只有引擎执行的查询/分支才是程序控制。这是故意的。
关键在于理解 SOP 覆盖了什么、没覆盖什么:
SOP 能覆盖的(数据收集)——Strategy 文件干的事:
1 | scrolling.strategy.md: |
SOP 未完全覆盖的(推理归因)——Agent 的价值所在:
1 | - 47 帧掉帧中,哪些帧是同一根因?(数据聚类) |
不同场景的 SOP 程度不同:
| Strategy 文件 | SOP 程度 | 原因 |
|---|---|---|
scrolling.strategy.md | 高 — Phase 编号 + 条件表 + 必做项 | 滑动分析方法论最成熟,常见数据收集路径较明确 |
startup.strategy.md | 中高 — 有 Phase 结构,深钻方向更开放 | 启动场景更多样(冷/温/热、不同瓶颈) |
anr.strategy.md | 中 — 2-skill pipeline,但结合规则与进一步归因 | ANR 根因高度多样 |
general.strategy.md | 低 — 只有路由决策树,无必做项 | 未匹配场景,先使用通用探查规则 |
scrolling.strategy.md 是 SOP 程度最高的,因为滑动分析方法论最成熟。general.strategy.md 几乎没有 SOP,因为用户问题完全不可预测。
所以正确的理解是:SmartPerfetto = 「SOP 驱动的数据收集 + Agent 驱动的推理归因」。
SOP 解决「分析滑动问题至少要看哪些数据」——这个问题有确定性答案,用 SOP 是对的。Agent 解决「拿到数据后怎么推理因果、怎么组织结论」——具体实例随 trace 变化,可以结合规则、统计和模型推理。
回到你们担心的“Skill 最后变成了 Workflow”:先看每条规则的适用条件和证据,不必把采用 Workflow 本身视为退化。可以固定可靠的数据收集和诊断规则,在尚未覆盖的问题上开放探索。
这种分工不意味着 SOP 不能处理推理。聚类、严重帧排序、规则诊断和输出格式都可由程序实现,经过验证的确定性诊断也可以是有价值的结果。重点是区分观察、规则判断与假设,并保留来源,而不是为了叫 Agent 就禁止工具产出结论。
Q3 小结
Agent 与 Workflow 的差别主要是决策权如何分配;可靠性要在目标任务上测量。按失败类型决定哪些步骤交给程序、哪些允许模型探索,并保留证据不足时的退出路径。
Q4:Agent 的架构需要从业务视角进行改进吗?
提问背景: Agent 的架构有过不同的设计和演进——从最初的 ReAct 架构,到 LangGraph 的节点式架构,不同的 Agent 架构设计会给它带来怎样的影响?在搭建自己的业务 Agent 时,是否需要考虑架构对 Agent 性能的影响?例如 SmartPerfetto 是在 Claude Agent SDK 的基础上基于业务理解加入了不同的 Skill 加载模式。
三种主流架构的本质差异
这三个名称不处在同一层,也不是互斥路线。ReAct 是推理与行动交替的模式,LangGraph 是有状态图编排框架,Claude Agent SDK 是提供 Agent 循环和工具集成的运行库。
| 名称 | 控制与组合能力 | 需要决定什么 |
|---|---|---|
| ReAct | 交替产生推理/行动并使用观察继续;可在不同框架中实现 | 工具、停止条件和证据检查 |
| LangGraph | 支持循环、条件边、状态、动态路由;节点可调用模型或普通代码 | 状态与执行边界,持久化、重试和人工介入方式 |
| Claude Agent SDK | 提供查询流、工具/权限配置和会话能力;应用仍负责生命周期与业务合同 | 如何接入工具、约束权限、校验结果及处理取消 |
LangGraph 不是只能运行 DAG。其官方 Agent 示例可在模型与工具节点之间循环,让模型根据中间结果选择工具。图中声明节点不等于提前枚举每一种业务根因。
SmartPerfetto 选择 SDK 原生 + 自建约束层的原因
SmartPerfetto 当时选择 Claude Agent SDK,是为了复用现成的 Agent 循环、工具调度和会话功能,再加入自己的 Strategy、Planning Gate、ArtifactStore 和 Verifier。这是工程取舍,不是 LangGraph 无法表达性能分析。
1 | SDK 查询流 → 应用处理消息/取消/超时 → SSE 事件 → 前端 |
Binder、GPU、GC、温控或锁竞争方向可由模型根据数据选择。LangGraph 同样可用“模型节点 → 通用工具节点 → 模型节点”的循环实现,无需为 21 个 reason_code 的每种组合新建节点。原文连续 add_edge 的例子表达的是固定多条边,不是框架强制的条件路由方案,因此不再以它证明路径爆炸。
这里 SDK 返回的是可迭代消息流;SmartPerfetto 自己把消息转换成前端 SSE,不能把这条网站连接归成 SDK 自动完成的全部功能。选型还应比较状态持久化、恢复、工具权限、部署方式、成本与可观测性。
关键业务导向的架构设计
以下是 SmartPerfetto 基于业务理解做的架构改进,每一个都直接对应一个业务问题:
1. 条件化工具加载——减少 Agent 的决策空间
SmartPerfetto 的 MCP 工具总数最多 20 个(9 个 always-on + 11 个条件注入),但一次分析只注入其中的子集:
1 | // claudeMcpServer.ts — 按模式切换工具集 |
业务原因: 缩小无关工具集可能减少上下文和无效调用,但“工具越多越容易选错”需按任务评测,不能当作普遍规律。
2. Sub-Agent 场景门控——避免不必要的并行开销
1 | // claudeAgentDefinitions.ts — 只在复杂场景启用 sub-agent |
| 场景 | Sub-Agent 配置 | 原因 |
|---|---|---|
| scrolling | frame-expert + system-expert | 帧分析和系统分析适合拆分,由 orchestrator 协调 |
| startup | startup-expert + system-expert | 启动阶段分析和资源竞争分析适合拆分 |
| anr | 无 sub-agent | ANR 是 2-skill 管线,额外 sub-agent 反而增加开销 |
注:sub-agent 的实际并行性取决于 SDK 内部调度策略,我们按并行采证来设计 prompt,但实际执行可能是串行的。
3. Lightweight vs Full 双模式——快问快答不走完整管线
对于分类为 quick 且没有强制 full 条件的简单问题,可不走完整的 Planning → Skill → Verification 管线。SmartPerfetto 的 ClaudeRuntime 在入口处做复杂度分类:
1 | analyze(query) |
业务原因: 用户的提问中有相当比例是事实性查询(「帧率多少」「有没有 ANR」),走完整管线会不必要地增加延迟。
上述为工具配置示意,不是可直接执行的 TypeScript。实际 classifyQueryComplexity 先检查选区、对比 trace、已有 findings、前序 full 分析,以及 scrolling/startup/anr/interaction/scroll-response 场景;命中就强制 full。其余才交 Haiku 分类,失败/超时回退 full。因此“帧率多少”“有没有 ANR”可能先命中场景而走 full,不能只凭句子短就说一定 quick。quick 没有完整 verifier 也不代表答案已证实。
对「是否需要从业务角度改进架构」的回答
先用真实任务定位瓶颈,再决定增加业务约束还是更换编排框架:
- 把策略文字与必须执行的条件分开。SQL 参数校验、身份范围、预算和必要依赖继续由程序保证,不能把安全/正确性分支全部移进 Markdown。
- Planning Gate 可以要求先提交计划;它的效果仍需失败样本和对照评估,不能用代码短推导可靠性高。
- 用工具记录和返回值检查动作确实发生;运行时也应核对数值、来源、实体、时间窗及因果证据。文字痕迹只作补充信号。
- 按复杂度选择工具与分析深度,但快速路径也要报告缺失、失败和不确定性。
Q4 小结
架构选型既涉及业务,也涉及运行时的技术约束。ReAct 可由不同框架实现,LangGraph 支持循环与动态路由;本文记录的是 SmartPerfetto 的 SDK 选型及自建约束,不代表另一框架只能处理固定流程。
Q5:性能 AI 智能体应该如何做好场景识别?
提问背景: 想做场景识别、路由到正确的 Skill,在建设这部分的时候应该更多基于「用户原声」还是「日志」,或者有什么更好的方法?场景识别的几条路径各有问题:代码匹配(关键词匹配会导致筛选结果过大或过小)、LLM 理解(LLM 的理解不一定准确)、日志还原(能筛选有无滑动,但不一定是用户关注的问题)。
SmartPerfetto 的做法:三层信号、分工明确
SmartPerfetto 的场景识别依赖三层信号配合,每层解决不同的问题:
1 | Layer 1: 用户原声 — 关键词匹配 → 场景类型(scrolling / startup / anr / ...) |
Layer 1:用户原声(关键词匹配,<1ms)
1 | // sceneClassifier.ts — 46 行代码,完成了全部场景分类 |
关键词定义在每个 Strategy 文件的 YAML frontmatter 中,不是硬编码在 TypeScript 里:
1 | # scrolling.strategy.md frontmatter |
为什么当时选择关键词匹配?
- 成本:这一步不调用模型;
<1ms是历史目标/观察,LLM 的延迟与 token 消耗也随模型、网络及提示变化,没有固定 500ms/500 tokens。 - 可复查:同样的规则与输入便于重现分类路径,但确定性不等于正确。
- 适用范围:明确的场景词可以快速路由;否定句、多意图和追问仍可能误匹配,需要验证与纠正路径。
关键词匹配不够的地方怎么办?
关键词匹配的确有边界——当用户说「这个 app 为什么慢」时,关键词无法确定是启动慢还是滑动慢。SmartPerfetto 的处理方式是:匹配不到就 fallback 到 general 场景,让 Agent 在 general 策略的路由决策树中自主选择方向。
1 | # general.strategy.md — 没有任何硬约束,只给路由建议 |
这个设计的核心思路是:不要试图在入口处 100% 准确分类,而是让准确的情况走快速路径(关键词 → Strategy),不确定的情况走探索路径(general → Agent 自主路由)。
Layer 2:Trace 数据——架构检测(确定性代码)
场景分类只解决了「用户想分析什么」,但同一个场景(如滑动)在不同渲染架构下的分析路径完全不同:
| 架构 | 渲染管线 | 分析差异 |
|---|---|---|
| Standard Android | UI Thread → RenderThread → SurfaceFlinger | 主线程 + RenderThread 双线分析 |
| Flutter TextureView | 1.ui → 1.raster → JNISurfaceTexture → RenderThread updateTexImage | 双出图管线,需要分析 Flutter engine 线程 + 纹理桥接 |
| Flutter SurfaceView | 1.ui → 1.raster → BufferQueue → SurfaceFlinger | 单出图管线,不经过 RenderThread |
| WebView | CrRendererMain → Viz Compositor | Chromium 渲染管线,线程名不同 |
| Compose | UI Thread (Composition) → RenderThread | 和 Standard 类似但有 Composition 阶段 |
架构检测调用 YAML Skill rendering_pipeline_detection 收集、评分和映射特征;TypeScript 中仍有 pipeline ID 到大类的 if/else 映射与 fallback。architectureDetector.ts 在失败/缺失时可回退 STANDARD、0.5 confidence,这不能当作识别成功或校准过的 50% 概率。管线标签是启发式分类,不是设备实际架构的独立真值。
1 | rendering_pipeline_detection skill (SQL) |
检测结果被注入到 system prompt 中(通过 arch-flutter.template.md 等模板),Agent 看到架构信息后选择对应的分析工具。
Layer 3:数据完整性——能力寄存器
Trace 采集配置不同,可用的数据维度也不同。有的 trace 没有 GPU frequency 数据,有的没有 thermal zone。SmartPerfetto 在分析开始前探测 18 个数据维度的可用性:
1 | available: primary table has at least 3 rows |
这个信息同样注入 system prompt,告诉 Agent 哪些维度可以分析、哪些维度数据缺失。这些提示能减少部分盲查,但不是全局完整性证明。
探测器对每张主表只做 LIMIT 3 后计数,rowEstimate=3 表示至少三行,绝不是 456/12000 等完整行数。GPU 主探测表是 gpu_slice,温控项用 android_dvfs_counters,并没有统计四个 thermal zone。表未加载、场景没发生、查询失败与未录制都可能表现为空;旧 fallback 会把个别探测失败写成 0,读者仍应保留未知。探测也未限定目标进程和用户选区,且架构排除规则不证明 Flutter/WebView 没有 FrameTimeline 数据。
上表渲染路径是省略 GPU/HWC 等环节的历史示意。Flutter 1.ui/1.raster 不跨引擎版本固定,TextureView/SurfaceView 与 Skia/Impeller 是不同维度;Compose 不是单独一套显示管线,WebView 也不只 CrRendererMain。
对提问中三条路径的评价
1. 代码匹配(关键词):可以用,但要设计好兜底
提问者说「关键词匹配会导致筛选结果过大或过小」。SmartPerfetto 的经验是:
- 优先级排序为多个命中决定顺序:ANR(1) > startup(2) > scrolling(3),同时命中多个关键词时取优先级最高的
- Compound patterns 补充更具体的匹配模式:
/启动.*慢/比单独匹配「启动」更精确 general兜底处理没有命中的情况:匹配不到就不猜,交给 Agent 自主探索
2. LLM 理解:不建议用在分类入口,可以用在兜底路径
LLM 分类在 SmartPerfetto 中放在 general 场景的自主路由阶段,不放在 Layer 1。此时 Agent 已经拿到了 trace 数据,可以结合数据做更准确的判断。
3. 日志还原:适合做 Layer 2 的补充信号
日志能告诉你「trace 中有什么」(有无滑动事件、有无 ANR),但不能告诉你「用户关心什么」。SmartPerfetto 的数据完整性探测就是这个角色——它不参与场景分类,但为 Agent 提供数据可用性信息。
排序只解决多个命中时“选哪个”,不证明选对;compound pattern 优先仅在同一个 scene 内,较高优先级的宽关键词仍可能抢先。general 只兜住未命中,兜不住误命中。需要区分用户意图与数据中发生的事;是否在入口使用 LLM 应按准确率、延迟和成本评估。场景分类器不用 LLM,不等于相邻的 quick/full 复杂度分类也不用。
Q5 小结
意图路由、架构识别和数据可用性是三个不同问题。关键词分类可复查但会误命中;架构分数和三行表探测也只是线索。保留校正路线,并用目标进程、时间窗和实际数据确认后续分析条件。
Q6:「确定性步骤 + AI 自主探索」,如何更好地发挥 AI 自主探索能力?
提问背景: 目前线上 Skill 运行的时候发现,AI 自主探索、下钻根因容易跑偏,给出不正确的结果。比如 SmartPerfetto 博客中提到的例子——在前期定位到 RenderThread 被 Binder 阻塞后(基于确定性步骤),后面的多个假设形成和验证是纯 AI 发挥吗,还是说针对 Binder 阻塞我们可能给 AI 一些常见的原因作为引导让它自己排查?
先回答核心问题:结构化约束下的自主探索
SmartPerfetto 的做法是结构化推理框架 + 按需知识注入:
1 | 确定性步骤产出数据 |
三个关键机制让 AI 自主探索变得更可靠:
机制 1:假设管理工具——给推理过程加结构
假设工具用于记录可复查的分析声明,不是读取或强制展示模型内部思维。f3206864 的参数与原文示例不同:
1 | { |
上面用 tool/arguments 包装便于阅读,实际由 MCP 客户端按协议发送。工具返回 hypothesisId。获得反证后,状态更新示例为:
1 | { |
h1 必须替换成实际返回 ID;历史 schema 的 status 只有 confirmed/rejected,没有原稿的 outcome: refined,提交字段也不是 description/expected_evidence。证据不足不应为了闭环强填任一结果;保留未解决状态并说明限制,必要时提出新假设。resolve_hypothesis 存储模型提供的 evidence 文本,不会自行执行 SQL 证明它。
机制 2:知识注入——按需加载领域知识
“针对 Binder 阻塞我们可能给 AI 一些常见的原因作为引导吗?”
是的,但这类知识通过 lookup_knowledge MCP 工具按需加载,不写死在 Skill 中。Agent 发现 Binder 阻塞后,可以调用:
1 | invoke lookup_knowledge("binder-ipc") |
返回一份 Binder IPC 的知识模板(knowledge-binder-ipc.template.md),包含:
- Binder 事务的典型阻塞原因分类(server 端忙、进程冻结、CPU 调度延迟、oneway 队列满)
- 每种原因的排查路径和关键指标
- 常见误判场景(如 远程 oneway 不等待服务端完成,但提交/序列化仍有开销或失败)
关键设计:知识是 Agent 主动拉取的,不是系统强制注入的。 目前共有 8 个知识模板(rendering-pipeline、binder-ipc、gc-dynamics、cpu-scheduler、thermal-throttling、lock-contention、startup-root-causes、data-sources),如果在 system prompt 中预先注入全部模板,会消耗大量 token 且大部分不相关。通过 MCP 工具按需加载,Agent 只在需要时才获取对应领域的背景知识。
SmartPerfetto 还在 Strategy 文件中提供了条件化的深钻建议表,这也是一种引导:
1 | # scrolling.strategy.md Phase 1.9 |
这个表不是写死的决策树——它是给 Agent 的查找表。Agent 看到数据后,根据数据中的指标值决定走哪一行。如果数据不匹配任何一行,Agent 可以自主探索。
机制 3:ReAct Reasoning Nudge——在工具返回时触发反思
在数据工具(execute_sql / invoke_skill)成功返回的前几次调用中,SmartPerfetto 在结果末尾附加一段推理提示:
1 | // claudeMcpServer.ts |
附加提示可提醒模型记录中间判断,但不能保证形成反思或防止跑偏。原稿的约 20 tokens/次、80 tokens 总量未给 tokenizer/usage 证据,中文与英文也不能按同一常数计费;前 4 次只是代码中的附加次数上限。效果需对照评测。
用图片中的 Binder 例子走一遍完整流程
这是教学假设,不是可由本文图片复现的 trace 结论。原稿“47 帧、Frame #234、23ms、限频 50%”没有配套原始数据,不把这些数字当作事实推导。
1 | 1. 查询目标进程/时间窗的帧数据,明确计数口径与缺失项。 |
CPU 调度延迟可以是 Binder 慢响应的一部分,不能写成“发现调度延迟,所以不是 Binder 响应慢”。低频加温度高也不足以证明温控造成该帧卡顿。假设 ID/状态更新使用上面的真实 schema,已 rejected 的同一假设不能再改成不存在的 refined。
如何让 AI 自主探索更可靠:四个实操建议
- 观察、规则判断和假设分开:保留结构化数据与来源;经过验证的规则诊断也可以输出,但不要伪装成原始观测。
- 保留确定性边界:预算、身份范围、数值计算和必要查询依赖由程序执行,开放的问题再允许模型选路。
- 知识提供排查线索:版本化知识不是当前 trace 的证据,命中知识条目后仍要查询对应数据。
- 运行时也核验结论:检查数值、实体、引用、时间窗和因果链;工具日志证明动作发生,文本启发式提供补充提示。离线可用标注集和 LLM Judge 辅助评估,但 Judge 也不是独立真值。
Q6 小结
假设记录、知识检索和提示能帮助组织探索,但不保证正确。可靠性仍要落实到真实工具结果、可追溯证据和适当的停止条件;不足以确认时保持未解决。
Q7:每一轮的 Prompt 是怎么拼接的?
提问背景: 大模型 Agent 的输出质量很大程度取决于 system prompt 的设计。SmartPerfetto 在每次分析时是如何构造 prompt 的?不同场景、不同轮次之间 prompt 有什么变化?token 预算怎么控制?
总体设计:四层分层拼接 + 缓存优化
buildSystemPrompt() 在一次分析开始或部分纠错路径中组织上下文;不是每次模型调用工具后都重建整份 system prompt。设计原则是把相对稳定的内容放前面,变化频繁的内容放后面,以增加可复用前缀。
但“超过 1024 tokens 就自动缓存”是旧源码注释中的过度简化,不能当作 API 合同。官方 Prompt caching 文档区分自动缓存配置与显式断点:需要相应请求配置/SDK 行为,满足模型的最小长度及前缀匹配、有效期等条件。当前文档提供默认 5 分钟及可选 1 小时 TTL;不是 SDK 会话的生命周期。
原稿 4000/800/400 cached tokens 与 ~80%/18%/~8% savings 没有 usage 记录支撑,也把缓存比例和价格节省混在一起。缓存不会减少模型要处理的逻辑内容;应分别读 cache_creation_input_tokens、cache_read_input_tokens 和普通 input/output,再按当时模型的价格计算实际成本。下图 token 数仅为结构说明的估算。
四层拼接结构
1 | ┌───────────────────────────────────────────────────────┐ |
模板加载与变量替换
固定规则主要来自 Markdown 模板;动态选区、findings、notes 和预算裁剪仍由 TypeScript 构造。下面展示模板路径:
1 | // strategyLoader.ts — 模板系统 |
模板文件清单:
| 类别 | 文件 | 用途 |
|---|---|---|
| 静态模板 | prompt-role.template.md | 角色定义 |
prompt-output-format.template.md | 输出格式规则(91 行) | |
prompt-quick.template.md | 快速模式精简 prompt | |
| 方法论 | prompt-methodology.template.md | 分析方法论(含 {{sceneStrategy}} 占位符) |
| 架构指南 | arch-standard.template.md | Standard Android 渲染指导 |
arch-flutter.template.md | Flutter 引擎指导 | |
arch-compose.template.md | Jetpack Compose 指导 | |
arch-webview.template.md | WebView 指导 | |
| 选区模板 | selection-area.template.md | 时间范围选区({{startNs}}, {{endNs}}…) |
selection-slice.template.md | Slice 选区({{eventId}}, {{ts}}…) | |
| 比较模式 | comparison-methodology.template.md | 双 trace 对比方法论 |
| 场景策略 | 12 个 *.strategy.md | scrolling/startup/anr/memory/… |
| 知识模板 | 8 个 knowledge-*.template.md | 按需加载的领域知识(非 prompt 注入) |
| 辅助模板 | prompt-complexity-classifier.template.md | Quick/Full 分流判定(不注入 prompt,但决定走哪条路径) |
Token 预算管理
软预算目标: 4500 tokens(MAX_PROMPT_TOKENS)。纠错重试时,如果检测到 SDK auto-compact(对话历史被自动压缩),会将预算降到 3000 tokens 以留出空间;否则复用原始 prompt。
Token 估算方法: 混合中英文估算——中文字符按 1.5 tokens/字,ASCII 按 0.3 tokens/字。这是项目估算,不是 tokenizer 实测或账单数据,误差可能影响预算。
超预算时的渐进丢弃策略:
当拼接完成后 token 数超出预算,按优先级从低到高依次丢弃整个 section:
1 | 丢弃顺序(最先丢弃 → 最后丢弃): |
永不丢弃的内容:
- 角色定义、输出格式(Tier 1 静态)
- 架构信息、焦点应用(Tier 2 per-trace)
- 方法论 + 场景策略(Tier 3 核心)
- 用户选区上下文(用户的显式意图)
- 对话上下文(之前的 findings 和分析笔记)
f3206864 删除可选 section 后如果仍超预算,只记录 warning 并返回剩余内容。因此 4500/3000 不是硬截断保证,也不包含全部会话历史、工具定义及输出预算。数据完整度提示被裁掉后,工具结果仍应保留缺失/unknown;“未提示缺失”不等于数据完整。
上下文构建的完整流程
在 ClaudeRuntime.analyze() 中,prompt 拼接前需要经过二十多个准备阶段(Phase)来收集所有上下文:
1 | Phase 0: 选区上下文日志 |
所有 Phase 的结果汇入 ClaudeAnalysisContext 对象,传给 buildSystemPrompt() 做最终拼接。
Phase 编号是这份源码里的准备步骤,不是必须逐项串行完成的外部协议。LRU 淘汰、会话恢复和失败重试都可能重新探测;已有状态也可能来自恢复,不应把“第1轮”固定等同于空白上下文。
Quick vs Full 双模式
不是所有查询都需要完整的 4500-token prompt。当入口判为 quick 时,SmartPerfetto 使用精简的 quick prompt:
1 | // buildQuickSystemPrompt() — ~1500 tokens |
| 维度 | Quick Mode | Full Mode |
|---|---|---|
| 目标 tokens | ~1500 | ~4500 |
| 场景策略 | 无 | 12 套之一 |
| 方法论 | 无 | prompt-methodology.template.md |
| 对话上下文 | 无 | findings + notes + entity + summary |
| Planning Gate | 无 | 有 |
| Verifier | 无 | 有 |
| 适用场景 | 未命中强制 full 条件且被分类为 quick 的简单查询 | 「分析滑动卡顿」「分析启动性能」 |
这里比较的是显式 system prompt 内容;quick 运行时仍可能传 SDK resume,因此“不注入对话上下文”不等于 SDK 看不到任何历史。实际入口规则见 Q4;quick 不保证适用于所有事实问句。
多轮对话中 Prompt 的变化
项目在准备上下文时检查本地 sessionMap 的 SDK ID 与更新时间。SDK_SESSION_FRESHNESS_MS = 4 * 60 * 60 * 1000 是应用自己的新鲜度判断,不能据此声称 Anthropic 端会话统一四小时过期。
- 项目认为可 resume:省略手动注入的 previousFindings/conversationSummary,仍加入 notes、实体和计划等可用内容。但这个判断不等于 SDK 已成功恢复。
- 项目认为过旧或不可用:手动加入部分 findings 和摘要;摘要/条数限制意味着历史可能丢失细节。
- 纠错轮:检测到 auto-compact 时可将 system prompt 软预算降至 3000;没有时复用原 prompt。自动压缩后的历史不等于原始全量消息。
SDK 会话文档说明会话记录写入磁盘并用 ID 恢复。恢复是否可用还依赖会话文件、工作环境与 SDK 配置;不能用 API 前缀缓存命中替代会话恢复验证。追问也可能改变场景、选区或焦点,Tier 1–3 并非总不变,更没有固定 80% 命中率。
一个具体例子:滑动分析的 Prompt 拼接
用户输入 "分析滑动卡顿",Flutter TextureView 架构,第 1 轮:
1 | [Tier 1] prompt-role.template.md → "你是 Android 性能分析专家..." |
用户追问 "深入分析第 3 帧",第 2 轮(SDK session resume 命中):
1 | [Tier 1-3] 与第 1 轮相同(相同部分具备前缀复用机会,未实测) |
这是教学拼接示例,92% 是示意评分,3200/3400 是估算,不是该用户会话的校准概率或计费记录。占位符、实际策略内容和模型配置变化后,需要重新检查 token 与结果合同。
Q7 小结
按稳定性组织前缀有助于复用,但缓存需要满足模型/API 条件并看实际 usage;会话恢复是另一项机制。4500/3000 是软预算,裁剪和摘要都可能丢信息,必须保留用户范围和缺失证据语义。
Q8:SmartPerfetto 有哪些 Skill?
提问背景: SmartPerfetto 的分析能力由 YAML Skill 承载。完整的 Skill 清单可以帮助理解系统的分析覆盖范围。
总览
以下清单按 f3206864 的定义 name 与目录逐项核对,补齐原稿漏列的 5 个 atomic。定义存在不等于在任意 trace 上都有数据或能成功执行;需满足模块、采集、平台和参数条件。v3.0 等标签为相关 Skill 自身版本,不是 Android 版本。当前清单与安装版本可能不同。
| 分类 | 数量 | 说明 |
|---|---|---|
| Atomic | 87 | 单步检测/统计,一条或几条 SQL 完成 |
| Composite | 29 | 组合多个 atomic skill,支持 iterator/conditional |
| Deep | 2 | 深度剖析(callstack、CPU profiling) |
| Pipeline | 28 | 渲染管线检测 + 教学(24+ 种架构) |
| Module | 18 | 模块化配置:app/framework/hardware/kernel |
| 合计 | 164 |
Atomic Skills(87 个)
单步数据提取和检测,是所有高层 Skill 的构建基础。
帧渲染与掉帧:
| Skill ID | 一句话描述 |
|---|---|
| consumer_jank_detection | 基于帧间隔的历史启发式,非独立的用户感知掉帧真值 |
| frame_blocking_calls | 识别每个掉帧帧期间的阻塞调用(GC、Binder、锁、IO) |
| frame_production_gap | 检测帧生产间隙:连续帧之间的 gap 超过 1.5× VSync |
| frame_pipeline_variance | 检测帧时长抖动与高方差区间 |
| render_pipeline_latency | 分解帧渲染全链路各阶段耗时 |
| render_thread_slices | 分析 RenderThread 的时间片分布 |
| app_frame_production | 分析应用主线程的帧生产情况 |
| sf_frame_consumption | 分析 SurfaceFlinger 消费帧的情况 |
| sf_composition_in_range | 分析 SurfaceFlinger 合成延迟 |
| sf_layer_count_in_range | 统计时间范围内 SF 活跃图层数量 |
| present_fence_timing | 关联已录制present fence时序,需核对端点语义 |
| game_fps_analysis | 针对游戏场景的帧率分析,支持固定帧率模式 |
VSync 与刷新率:
| Skill ID | 一句话描述 |
|---|---|
| vsync_period_detection | 检测 VSync 周期,返回刷新率和置信度 |
| vsync_config | 读取或估计周期;回退默认值需与测量区分 |
| vsync_alignment_in_range | 分析帧与 VSync 信号的对齐情况 |
| vsync_phase_alignment | 分析输入事件与 VSync 的相位关系,定位跟手延迟瓶颈 |
| vrr_detection | 检查刷新节奏变化线索,不据此确认面板LTPO或完整VRR支持 |
CPU 与调度:
| Skill ID | 一句话描述 |
|---|---|
| cpu_topology_detection | 从已录制频率等信息推断核分组,需核对设备拓扑 |
| cpu_topology_view | 创建可复用 SQL VIEW _cpu_topology |
| cpu_slice_analysis | 分析 CPU 时间片分布(动态拓扑检测) |
| cpu_load_in_range | 分析指定时间范围内各 CPU 核心的负载情况 |
| cpu_cluster_load_in_range | 计算大核簇和小核簇的整体 CPU 负载百分比 |
| cpu_freq_timeline | 分析各 CPU 核心的频率变化时间线 |
| cpu_idle_analysis | 统计已录制CPU idle状态与区间,影响需结合唤醒时序 |
| cpu_throttling_in_range | 查限频相关候选信号;低频本身不证明热控 |
| sched_latency_in_range | 分析线程调度等待时间分布,检测 CPU 争抢 |
| scheduling_analysis | 分析线程调度延迟(Runnability) |
| task_migration_in_range | 分析线程在大小核之间的迁移频率 |
| thread_affinity_violation | 统计主线程/RenderThread迁核线索,迁核不等于违反affinity |
| thermal_predictor | 频率趋势启发式提示,非经过校准的热限频预测 |
| util_tracking_analysis | 关联主线程运行与频率的早期窗口,不能单独证WALT/PELT滞后 |
| cache_miss_impact | 统计 cache-miss 计数器并评估波动 |
GPU:
| Skill ID | 一句话描述 |
|---|---|
| gpu_render_in_range | 分析 GPU 渲染耗时和 Fence 等待 |
| gpu_freq_in_range | 分析 GPU 频率变化情况 |
| gpu_metrics | 分析 GPU 频率、利用率和渲染性能 |
| gpu_power_state_analysis | 分析 GPU 频率状态切换,识别降频压力与抖动 |
| gpu_frequency_analysis | 汇总GPU频率采样;单位/采样权重与thermal推断需复核 |
主线程分析:
| Skill ID | 一句话描述 |
|---|---|
| main_thread_states_in_range | 统计区间内主线程状态、阻塞函数与占比 |
| main_thread_slices_in_range | 统计区间内主线程切片耗时分布 |
| main_thread_sched_latency_in_range | 统计主线程 Runnable 等待时间分布 |
| main_thread_file_io_in_range | 统计区间内主线程文件 IO 相关切片耗时 |
Binder IPC:
| Skill ID | 一句话描述 |
|---|---|
| binder_in_range | 分析指定时间范围内的 Binder 事务 |
| binder_blocking_in_range | 分析同步 Binder 调用中对端进程的响应延迟 |
| binder_root_cause | 对慢 Binder 事务进行服务端/客户端阻塞原因归因 |
| binder_storm_detection | 检测 Binder 事务风暴:短时间内过多 IPC 调用 |
锁与同步:
| Skill ID | 一句话描述 |
|---|---|
| lock_contention_in_range | 分析指定时间范围内的锁竞争情况 |
| futex_wait_distribution | 统计futex相关等待;不把所有futex都当mutex争用 |
启动专用(19 个):
| Skill ID | 一句话描述 |
|---|---|
| startup_events_in_range | 查询启动事件及 TTID/TTFD 指标 |
| startup_slow_reasons | 启动慢原因(Google 官方分类 + 自检)v3.0 |
| startup_critical_tasks | 查询启动窗口内已录制的活跃线程,按 CPU 时间排序 |
| startup_thread_blocking_graph | 以waker_utid建立唤醒关联候选,不自动证明锁持有关系 |
| startup_jit_analysis | 分析 JIT 编译线程对启动速度的影响 |
| startup_cpu_placement_timeline | 按时间桶分析主线程核类型变化,检测启动初期被困小核 |
| startup_freq_rampup | 分析冷启动初期 CPU 频率爬升速度,检测升频延迟 |
| startup_binder_pool_analysis | 统计已观测Binder线程/事务,饱和判断需队列与等待证据 |
| startup_hot_slice_states | 分析启动区间内 Top N 热点 Slice 的线程状态分布 |
| startup_main_thread_states_in_range | 统计启动阶段主线程 Running/Runnable/Blocked 占比 |
| startup_main_thread_slices_in_range | 统计启动阶段主线程切片热点 |
| startup_binder_in_range | 统计启动阶段 Binder 调用分布 |
| startup_main_thread_file_io_in_range | 统计启动阶段主线程文件 IO |
| startup_sched_latency_in_range | 统计启动阶段主线程 Runnable 等待时延 |
| startup_main_thread_sync_binder_in_range | 统计启动阶段主线程同步 Binder 耗时 |
| startup_main_thread_binder_blocking_in_range | 分析启动阶段主线程同步 Binder 阻塞明细 |
| startup_breakdown_in_range | 统计启动阶段各归因原因耗时占比 |
| startup_gc_in_range | 统计启动阶段 GC 切片及主线程占比 |
| startup_class_loading_in_range | 统计启动阶段类加载切片耗时 |
内存与 GC:
| Skill ID | 一句话描述 |
|---|---|
| gc_events_in_range | 查询给定进程的 GC 事件和可选时间范围 |
| memory_pressure_in_range | 分析指定时间范围内的内存压力指标 |
| page_fault_in_range | 分析 Page Fault 和内存回收对性能的影响 |
输入与触摸:
| Skill ID | 一句话描述 |
|---|---|
| input_events_in_range | 提取区间内的原始输入事件,分析分发延迟 |
| input_to_frame_latency | 关联已录制输入与帧估计延迟,需确认映射和缺失事件 |
| touch_to_display_latency | 按记录端点估计输入至呈现延迟,不等于光学触屏延迟 |
| scroll_response_latency | 测量滚动手势从输入到首帧渲染的响应延迟 |
系统与设备:
| Skill ID | 一句话描述 |
|---|---|
| system_load_in_range | 分析系统整体 CPU 利用率和进程活跃度 |
| device_state_snapshot | 采集 trace 期间的设备环境信息(屏幕、电量、温度等) |
| device_state_timeline | 追踪设备状态随时间的变化 |
| wakelock_tracking | 统计已录制Wake Lock持有,不能单独换算电量消耗 |
其他:
| Skill ID | 一句话描述 |
|---|---|
| blocking_chain_analysis | 分析主线程阻塞链:谁阻塞了主线程?唤醒者在做什么? |
| anr_main_thread_blocking | 深度分析 ANR 中主线程阻塞原因 |
| anr_context_in_range | 提取第一个 ANR 事件数据用作时间窗口锚点 |
| app_lifecycle_in_range | 追踪 Activity/Fragment 生命周期事件 |
| compose_recomposition_hotspot | 检测 Jetpack Compose 重组热点 |
| webview_v8_analysis | 分析 WebView V8 引擎:GC、脚本编译、执行时间 |
| rendering_pipeline_detection | 识别应用渲染管线类型(24 种细粒度检测) |
| pipeline_key_slices_overlay | 查询管线关键 Slice 的 ts/dur 用于时间线 overlay |
| fpsgo_analysis | 按slice名称汇总FPSGO/FSTB/FBT等候选标记,名称可能误命中 |
| logcat_analysis | 从已录制Logcat中筛选ANR/GC/Binder/StrictMode等警告线索 |
Composite Skills(29 个)
组合多个 atomic skill,支持 iterator(逐帧/逐事件深钻)和 conditional(条件分支)。
| Skill ID | 一句话描述 |
|---|---|
| scrolling_analysis | 滑动分析主入口:概览 → 帧列表 → 根因分类 → 逐帧诊断 |
| flutter_scrolling_analysis | Flutter 特定帧分析,使用 Flutter 线程模型 |
| jank_frame_detail | 分析特定掉帧的详细原因:深钻 jank 原因和根因分类 |
| startup_analysis | 启动分析主入口:Iterator 模式、大小核分析、四象限 |
| startup_detail | 分析单个启动事件:主线程耗时、Binder、CPU 大小核占比 |
| anr_analysis | ANR v3.0 分析:系统问题 vs 应用问题、分类处理 |
| anr_detail | 单个ANR关联线程状态/Binder依赖,死锁需额外证据 |
| cpu_analysis | CPU 分析:时间分布、大小核分析、调度链路 |
| gpu_analysis | GPU 分析:频率分布、内存使用、帧渲染关联 |
| memory_analysis | 内存分析:GC 事件、GC 与帧关联、线程状态 |
| gc_analysis | GC 分析:基于 stdlib android_garbage_collection_events |
| binder_analysis | Binder 深度分析:事务基础、线程状态 |
| binder_detail | 单个 Binder 事务详情:CPU 大小核、四象限、阻塞原因 |
| thermal_throttling | 温度监控、热节流检测、CPU 频率相关性 |
| lock_contention_analysis | 锁竞争多维度分析:基于 android.monitor_contention |
| surfaceflinger_analysis | SF 帧合成性能:GPU/HWC 合成比例、慢合成检测 |
| click_response_analysis | 点击响应分析:基于 stdlib android_input_events |
| click_response_detail | 单个慢输入事件详情:延迟分解、四象限、主线程阻塞 |
| scroll_session_analysis | 单个完整滑动区间:Touch 阶段 vs Fling 阶段 FPS |
| navigation_analysis | Activity/Fragment 跳转性能:生命周期、转场动画 |
| lmk_analysis | LMK 分析:原因分布、时间线、频率 |
| dmabuf_analysis | 统计DMA Buffer事件与未配对候选,不能仅据此判泄漏 |
| block_io_analysis | Block IO 分析:设备级统计、队列深度、长耗时 IO |
| io_pressure | IO 阻塞数据检测、IO Wait 时间、严重度评估 |
| suspend_wakeup_analysis | 休眠/唤醒分析:时间分布、唤醒源排行 |
| network_analysis | 网络分析:流量概览、应用流量、协议分布 |
| irq_analysis | 硬中断和软中断的频率、耗时、嵌套情况 |
| scene_reconstruction | 通过用户输入和屏幕状态还原用户操作场景 |
| state_timeline | 四泳道连续状态时间线:设备/用户/应用/系统 |
引擎支持 conditional 类型,但此快照的定义没有使用该 step;类型支持与已存在的执行路径分开看。查询输出中的分类仍可能是启发式,不能仅凭 Skill 名为 root_cause 就视为因果已证实。
Deep Skills(2 个)
深度剖析,通常需要更长的执行时间。
| Skill ID | 一句话描述 |
|---|---|
| cpu_profiling | CPU 性能剖析:使用热点和调度效率深度分析 |
| callstack_analysis | Running 状态下的调用栈热点分析 |
Pipeline Skills(28 个)
渲染管线检测 + 教学。每个 pipeline skill 对应一种渲染架构,包含管线描述、关键线程、性能指标和优化建议。
| Skill ID | 渲染架构 |
|---|---|
| pipeline_android_view_standard_blast | 常见Android12+ HWUI/BLAST路径;以版本和设备证据确认 |
| pipeline_android_view_standard_legacy | 旧式HWUI/BufferQueue路径,不能只按Android版本二分 |
| pipeline_android_view_software | CPU Skia 软件渲染,无 RenderThread |
| pipeline_android_view_mixed | View + SurfaceView 混合渲染 |
| pipeline_android_view_multi_window | 同进程多窗口(Dialog/PopupWindow) |
| pipeline_android_pip_freeform | 画中画和自由窗口模式 |
| pipeline_compose_standard | Jetpack Compose + HWUI RenderThread |
| pipeline_flutter_textureview | Flutter由TextureView承载的路径,非一律PlatformView降级 |
| pipeline_flutter_surfaceview_skia | Flutter + Skia 引擎(JIT Shader) |
| pipeline_flutter_surfaceview_impeller | Flutter SurfaceView + Impeller;仍需查运行时pipeline/cache工作 |
| pipeline_webview_gl_functor | 传统 WebView,App RenderThread 同步等待 |
| pipeline_webview_surface_control | 现代 WebView + Viz/OOP-R 独立合成 |
| pipeline_webview_textureview_custom | X5/UC 等定制 WebView 内核 |
| pipeline_webview_surfaceview_wrapper | WebView 全屏视频包装模式 |
| pipeline_chrome_browser_viz | Chrome Viz 合成器,多进程架构 |
| pipeline_opengl_es | 直接 OpenGL ES / EGL 渲染 |
| pipeline_vulkan_native | 原生 Vulkan 渲染 |
| pipeline_angle_gles_vulkan | ANGLE: OpenGL ES → Vulkan 翻译层 |
| pipeline_game_engine | Unity/Unreal/Godot 等游戏引擎 |
| pipeline_surfaceview_blast | 独立 SurfaceView + BLAST 同步 |
| pipeline_textureview_standard | SurfaceTexture 纹理采样/合成模式 |
| pipeline_camera_pipeline | Camera2/HAL3 多流相机渲染 |
| pipeline_video_overlay_hwc | HWC 视频层硬件加速叠加 |
| pipeline_hardware_buffer_renderer | Android 14+ HBR API 直接 Buffer 渲染 |
| pipeline_surface_control_api | NDK SurfaceControl 直接事务提交 |
| pipeline_variable_refresh_rate | VRR/ARR + FrameTimeline 动态刷新率 |
| pipeline_imagereader_pipeline | ImageReader API:ML 推理、录屏、自定义相机 |
| pipeline_software_compositing | 软件合成候选教学定义;不证明SF有通用CPU回退路径 |
注:
_base.skill.yaml是 Pipeline Skill 的基础模板文件,不注册为可用 Skill,不计入总数。
Module Skills(18 个)
模块化分析配置,按层级组织。Agent 通过 list_skills 发现并按需调用。
硬件层(5 个):
| Skill ID | 一句话描述 |
|---|---|
| cpu_module | CPU 频率、热节流和电源状态 |
| gpu_module | GPU 渲染、频率和显存使用 |
| memory_module | 内存带宽、LMK、dmabuf、PSI、缺页 |
| thermal_module | 温度传感器、热节流检测、冷却策略 |
| power_module | Wake Lock、CPU idle、电源模式、休眠/唤醒 |
框架层(6 个):
| Skill ID | 一句话描述 |
|---|---|
| surfaceflinger_module | 帧渲染时序、卡顿原因、GPU 合成 |
| choreographer_module | VSync 信号、doFrame 回调、帧生产管线 |
| ams_module | 应用生命周期、进程管理、启动时序 |
| wms_module | 窗口动画、Activity 转场、多窗口 |
| art_module | GC、JIT 编译和内存分配 |
| input_module | 触摸延迟、输入派发和点击响应 |
内核层(4 个):
| Skill ID | 一句话描述 |
|---|---|
| scheduler_module | 线程调度延迟、CPU 利用率、大小核分配 |
| binder_module | 跨进程调用、阻塞事务、调用延迟 |
| lock_contention_module | Mutex/Futex、Java monitor、死锁检测 |
| filesystem_module | Block IO、文件操作、数据库、SharedPreferences |
应用层(3 个):
| Skill ID | 一句话描述 |
|---|---|
| launcher_module | 主屏性能、应用启动、小部件更新 |
| systemui_module | 状态栏、通知栏、快速设置、导航栏 |
| third_party_module | 第三方应用性能、卡顿和资源使用 |
Skill 之间的关系
1 | Module Skills (配置层) |
快照中的滑动分析路径:
1 | invoke_skill("scrolling_analysis") |
scrolling_analysis 在此快照已使用批量 SQL 分类,不是原稿画出的“consumer_jank_detection → iterator → 每帧 jank_frame_detail”。复用某段计算逻辑也不等于调用同名 Skill;读调用边时要区分内联 SQL、skill 引用和 Agent 后续工具调用。
关于我 && 博客
下面是个人的介绍和相关的链接,期望与同行的各位多多交流,三人行,则必有我师!
- 博主个人介绍 :里面有个人的微信和微信群链接。
- 本博客内容导航 :个人博客内容的一个导航。
- 个人整理和搜集的优秀博客文章 - Android 性能优化必知必会 :欢迎大家自荐和推荐 (微信私聊即可)
- Android 性能优化知识星球:付费社群已于 2026 年停止运营,不再招收新成员;此处保留历史介绍。
一个人可以走的更快 , 一群人可以走的更远
旧群二维码保留作历史图片,不保证仍有效;问题反馈可使用 项目 Issues。






