这篇文章收集了《从 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
2
3
4
5
开发阶段(我写代码时):
Claude Code + Skills/Hooks → 帮我开发 SmartPerfetto

运行阶段(用户分析 trace 时):
SmartPerfetto Backend + YAML Skills → 帮用户分析性能数据

这是本项目当时的分工,不是标准 Skill 的能力边界。Claude Code Skills 可被用户或模型调用,Agent SDK 也可按配置加载项目 Skills(见官方 SDK Skills 文档);脚本可以参数化并返回 JSON。SmartPerfetto 选择 YAML,是把查询、输出 schema 和组合执行统一交给自己的后端引擎,而让运行时的查询与展示合同集中维护。

即使只看「确定性执行」,YAML Skill 有几个针对性设计

1. 参数化 SQL,不是固定脚本

性能分析的 SQL 不是写死的——同一个 Skill 需要接受不同的参数(进程名、时间范围、帧 ID 列表):

1
2
3
4
5
6
7
8
9
10
11
12
13
steps:
- id: thread_state_distribution
type: atomic
sql: |
WITH clipped AS (
SELECT state,
MIN(ts + dur, ${end_ts}) - MAX(ts, ${start_ts}) AS overlap_ns
FROM thread_state
WHERE utid = ${main_thread_utid} AND dur > 0
AND ts < ${end_ts} AND ts + dur > ${start_ts}
)
SELECT state, SUM(overlap_ns) AS total_dur
FROM clipped GROUP BY state

这是省略输入声明的教学片段。thread_state 直接使用 utid,没有 track_id;按半开窗口裁剪,避免漏掉窗口开始前已进入的状态或累计窗口外时长。排除 dur <= 0 的未完成/无效区间,缺失状态不当作零。调用端先解析并校验 UTID 和纳秒边界,再由引擎替换;YAML 本身不消除注入风险。Python/Node 脚本也可以提供同样的参数与校验合同。

2. 自描述的输出格式(DataEnvelope)

1
2
3
4
5
display:
level: detail
columns:
- { name: state, type: string }
- { name: total_dur, type: duration, unit: ns }

每个 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 SDKExpress 后端 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
2
3
4
5
6
7
8
9
10
**Phase 1.9 — 根因深钻(🔴 强制执行,不可跳过):**

对 `batch_frame_root_cause` 中占比 >15% 的每个 reason_code,
**必须**选最严重的 1 帧执行深钻。
**⛔ 禁止**仅靠 batch_frame_root_cause 的统计分类直接出结论。

| 条件 | 深钻动作 |
| 任何 reason_code Q4>20% | invoke_skill("blocking_chain_analysis", ...) |
| binder_overlap >5ms | invoke_skill("binder_root_cause", ...) |
| ...

软指引(建议但可跳过):

Phase 1.5(架构感知分支)和 Phase 1.7(根因分支)用的是「建议」「改用」等措辞,Claude 可以根据实际数据决定是否执行:

1
2
3
4
5
**Phase 1.5 — 架构感知分支:**

| 架构 | 调整动作 |
| Flutter | 改用 flutter_scrolling_analysis |
| WebView | 注意 CrRendererMain 线程 |

Strategy 文件的全部内容被原文注入 System Prompt,注入时加了一行硬性说明:

1
2
场景策略(必须严格遵循)
对于以下常见场景,已有验证过的分析流水线。必须完整执行所有阶段,不可跳过。

Claude 直接在 System Prompt 中看到这些阶段定义、🔴 标记和「禁止」字样。

“必须”“禁止”和红色标记只表达策略要求,不会自行拦截工具或证明已执行。后续文字启发式可能发现遗漏,也可能漏报;需要强制的前置条件应由运行时明确检查。这里的 Phase、15%/20%/5ms 等是历史策略阈值,不是跨设备有效的因果规则。

第二层:Planning Gate — 强制先计划,但不限制计划内容

启用了 analysisPlan 引用时,execute_sql 与 invoke_skill 的 MCP 入口要求先调用 submit_plan 提交分析计划。没有提交计划就调用 execute_sql 或 invoke_skill 会被直接拒绝:

1
2
3
4
5
function requirePlan(toolName: string): string | null {
if (!analysisPlanRef) return null; // Planning feature disabled
if (analysisPlanRef.current) return null; // 已有计划,放行
return `必须先调用 submit_plan 提交分析计划,然后才能使用 ${toolName}`;
}

关键点在于:Gate 只要求计划存在,不要求计划和 Strategy 的阶段完全对应。 计划仍需满足 submit_plan 的参数 schema;符合结构时可以调整阶段划分——它可以把 Phase 1 和 1.5 合并,可以加入 Strategy 没提到的额外步骤,也可以根据初步数据调整深钻方向。

提交计划时,系统会做场景感知的关键词检查(比如滑动场景检查计划中是否提到了「帧」「jank」等词),但这只是 warning 级别——计划即使不包含这些词也会被接受。

这个设计的目的是:要求 Claude 在调用受保护入口前提交计划(规划纪律),但不限制它怎么想(规划自由)。

这不是所有内部查询的全局锁:预处理、信息查询和工具内子查询不等于上述入口。Quick 未传该引用时不启用 gate。计划存在只证明提交了结构化数据,不证明模型“想清楚”或步骤已执行。

第三层:Verifier — 多维度事后检查

计划和执行之间可能有偏差——Claude 可能提交了计划但实际跳过了某个关键步骤。Verifier 在分析结束后做多维度事后检查,以启发式行为检查为主,同时补充计划/假设/场景完整性校验:

a) 场景完整性检查——分析输出是否覆盖了场景的核心内容:

1
2
3
4
5
6
7
8
9
10
11
// 滑动场景:检查是否有显著掉帧但没做 Phase 1.9 深钻
case 'scrolling': {
const hasSignificantJank = /* 检测文本中是否提到大量掉帧 */;
const hasDeepDrill = /* 匹配结论文字中的工具名或知识术语,不读取执行日志 */;
if (hasSignificantJank && !hasDeepDrill) {
issues.push({
severity: 'error',
message: '滑动分析有掉帧但缺少 Phase 1.9 根因深钻 — reason_code 只是分类标签,不是真正的根因'
});
}
}

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 GateVerifier 检查约束强度
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
2
3
4
5
写死的 Workflow ◄──────────────────────────────────► 完全自主的 Agent
│ │
开发者控制每个分支 LLM 决定一切
│ │
高确定性、低灵活性 低确定性、高灵活性
维度WorkflowAgent
控制流开发者在代码中写死 if/elseLLM 自主选择下一步
工具选择预定义执行顺序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
2
3
4
5
场景识别     → Workflow(确定性逻辑,不需要 LLM 参与)
数据收集 → 半 Workflow(Skill 定义查什么,Agent 决定顺序和参数)
推理归因 → Agent(这是 LLM 的核心价值,结合数据提出待验证的解释)
输出格式 → 程序定义 schema 与校验,模型文本仍可能不合规
质量验证 → Workflow(规则检查)+ Agent(LLM 复核)

表格是工程分工建议,不是对某模型可靠率的测量。单凭提问背景也不能诊断对方系统的唯一根因;还需看失败样本、工具合同与数据覆盖。

SmartPerfetto 的做法:约束强度光谱

SmartPerfetto 没有在 Agent 和 Workflow 之间二选一,而是对不同分析阶段设定了不同的约束强度(详见 Q2)。这里从「能力边界」的角度重新审视这个设计:

Prompt 强要求(Phase 1.9 根因深钻)——针对当时观察到的跳过深钻:

1
2
3
4
5
6
7
# scrolling.strategy.md 中的 Phase 1.9

**Phase 1.9 — 根因深钻(🔴 强制执行,不可跳过):**

对 batch_frame_root_cause 中占比 >15% 的每个 reason_code,
**必须**选最严重的 1 帧执行深钻。
**⛔ 禁止**仅靠 batch_frame_root_cause 的统计分类直接出结论。

为什么强化这条提示?因为我们发现 Agent 有一个系统性偏差:它倾向于在拿到概览数据后就直接出结论,跳过深钻。概览数据已经包含 reason_code,模型可能把分类当作结论;但没有对照实验,不能证明是“认知成本低”或某种内部路径依赖造成。

提示约束较少(Phase 1.5 架构分支)——利用架构信息辅助工具选择:

1
2
3
4
5
6
7
# scrolling.strategy.md 中的 Phase 1.5

**Phase 1.5 — 架构感知分支:**

| 架构 | 调整动作 |
| Flutter | 改用 flutter_scrolling_analysis |
| WebView | 注意 CrRendererMain 线程 |

这里用「改用」「注意」等建议性措辞,不强制。因为架构检测的结果(Flutter/WebView/Standard)已经被确定性代码放进了 system prompt,这提供选路依据,但识别错误、缺失信息或模型误选仍需检查。

没有固定场景步骤(general)——允许通用探索,但保留运行时边界:

1
2
3
4
5
6
7
# general.strategy.md — 只给路由决策树,不给任何必须执行的步骤

场景: general
priority: 99

当前查询未匹配到特定场景策略。请根据用户关注的方向,
使用以下决策树选择合适的分析路径。

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
2
3
Verifier 发现 ERROR → 生成 Correction Prompt → 触发 SDK 重试
↑ ↓
Learned patterns ← 累积历史误判模式

补充:Strategy 文件就是 SOP,这没问题

有人会指出:scrolling.strategy.md 读起来就像一份 SOP(标准作业程序)——有编号的 Phase、条件表、必做项、甚至直接写了 invoke_skill("scrolling_analysis", {...})。这和「在 Skill 里写死决策树」有什么区别?

数据收集部分借用了 Workflow 的组织思路。 Strategy 文件就是 SOP,它把领域专家的分析经验写成了步骤要求;实际调用仍由模型驱动,只有引擎执行的查询/分支才是程序控制。这是故意的。

关键在于理解 SOP 覆盖了什么、没覆盖什么:

SOP 能覆盖的(数据收集)——Strategy 文件干的事:

1
2
3
4
5
scrolling.strategy.md:
Phase 1: "调用 scrolling_analysis" ← 写死了收集什么数据
Phase 1.5: "Flutter 改用 flutter_scrolling_analysis" ← 写死了条件分支
Phase 1.7: 条件表 → 深钻动作 ← 写死了 if/then 表
Phase 1.9: "🔴 占比>15% 的 reason_code 必须深钻" ← 写死了必做项

SOP 未完全覆盖的(推理归因)——Agent 的价值所在:

1
2
3
4
- 47 帧掉帧中,哪些帧是同一根因?(数据聚类)
- 19 帧 workload_heavy 里,哪帧"最严重"值得深钻?(优先级判断)
- 深钻发现 Binder 阻塞 23ms + 热降频同时存在,因果方向是什么?(因果推理)
- 最终结论怎么组织?给 App 开发者 vs 平台工程师的建议如何区分?(表达决策)

不同场景的 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
2
3
4
SDK 查询流 → 应用处理消息/取消/超时 → SSE 事件 → 前端
MCP 工具 → Skill Engine / SQL → 数据与证据引用
策略与计划 → 指导分析;运行时 gate → 检查前置条件
Verifier → 规则/文字复核;不能代替全部数据验真

Binder、GPU、GC、温控或锁竞争方向可由模型根据数据选择。LangGraph 同样可用“模型节点 → 通用工具节点 → 模型节点”的循环实现,无需为 21 个 reason_code 的每种组合新建节点。原文连续 add_edge 的例子表达的是固定多条边,不是框架强制的条件路由方案,因此不再以它证明路径爆炸。

这里 SDK 返回的是可迭代消息流;SmartPerfetto 自己把消息转换成前端 SSE,不能把这条网站连接归成 SDK 自动完成的全部功能。选型还应比较状态持久化、恢复、工具权限、部署方式、成本与可观测性。

关键业务导向的架构设计

以下是 SmartPerfetto 基于业务理解做的架构改进,每一个都直接对应一个业务问题:

1. 条件化工具加载——减少 Agent 的决策空间

SmartPerfetto 的 MCP 工具总数最多 20 个(9 个 always-on + 11 个条件注入),但一次分析只注入其中的子集:

1
2
3
4
5
6
7
8
9
10
11
// claudeMcpServer.ts — 按模式切换工具集

if (options.lightweight) {
// 事实性查询(如"帧率是多少"):只给 3 个工具
toolEntries = [executeSql, invokeSkill, lookupSqlSchema];
} else {
// 完整分析:9 个 always-on (含 recall_patterns) + 按上下文条件注入
// 比较模式 → 注入 compare_skill, execute_sql_on, get_comparison_context
// 假设管理 → 注入 submit_hypothesis, resolve_hypothesis, flag_uncertainty
// 规划工具 → 注入 submit_plan, update_plan_phase, revise_plan
}

业务原因: 缩小无关工具集可能减少上下文和无效调用,但“工具越多越容易选错”需按任务评测,不能当作普遍规律。

2. Sub-Agent 场景门控——避免不必要的并行开销

1
2
3
4
5
6
7
8
9
10
11
// claudeAgentDefinitions.ts — 只在复杂场景启用 sub-agent

const ORCHESTRATOR_ONLY_TOOLS = new Set([
'submit_plan', 'update_plan_phase', 'revise_plan',
'submit_hypothesis', 'resolve_hypothesis', 'flag_uncertainty',
'recall_patterns',
'compare_skill', 'execute_sql_on', 'get_comparison_context',
]);

// Sub-agent 只拿到数据收集工具,不拿规划/假设工具
// 设计原则:sub-agents collect evidence, orchestrator makes diagnosis
场景Sub-Agent 配置原因
scrollingframe-expert + system-expert帧分析和系统分析适合拆分,由 orchestrator 协调
startupstartup-expert + system-expert启动阶段分析和资源竞争分析适合拆分
anr无 sub-agentANR 是 2-skill 管线,额外 sub-agent 反而增加开销

注:sub-agent 的实际并行性取决于 SDK 内部调度策略,我们按并行采证来设计 prompt,但实际执行可能是串行的。

3. Lightweight vs Full 双模式——快问快答不走完整管线

对于分类为 quick 且没有强制 full 条件的简单问题,可不走完整的 Planning → Skill → Verification 管线。SmartPerfetto 的 ClaudeRuntime 在入口处做复杂度分类:

1
2
3
4
5
6
7
8
9
analyze(query)
↓
queryComplexity === 'quick'
→ analyzeQuick(): 3 个工具,无 Planning Gate,无 Verifier
→ 直接回答事实性问题

queryComplexity === 'full'
→ 完整管线:Planning → Skill → Verification → Correction
→ 系统化分析

业务原因: 用户的提问中有相当比例是事实性查询(「帧率多少」「有没有 ANR」),走完整管线会不必要地增加延迟。

上述为工具配置示意,不是可直接执行的 TypeScript。实际 classifyQueryComplexity 先检查选区、对比 trace、已有 findings、前序 full 分析,以及 scrolling/startup/anr/interaction/scroll-response 场景;命中就强制 full。其余才交 Haiku 分类,失败/超时回退 full。因此“帧率多少”“有没有 ANR”可能先命中场景而走 full,不能只凭句子短就说一定 quick。quick 没有完整 verifier 也不代表答案已证实。

对「是否需要从业务角度改进架构」的回答

先用真实任务定位瓶颈,再决定增加业务约束还是更换编排框架:

  1. 把策略文字与必须执行的条件分开。SQL 参数校验、身份范围、预算和必要依赖继续由程序保证,不能把安全/正确性分支全部移进 Markdown。
  2. Planning Gate 可以要求先提交计划;它的效果仍需失败样本和对照评估,不能用代码短推导可靠性高。
  3. 用工具记录和返回值检查动作确实发生;运行时也应核对数值、来源、实体、时间窗及因果证据。文字痕迹只作补充信号。
  4. 按复杂度选择工具与分析深度,但快速路径也要报告缺失、失败和不确定性。

Q4 小结

架构选型既涉及业务,也涉及运行时的技术约束。ReAct 可由不同框架实现,LangGraph 支持循环与动态路由;本文记录的是 SmartPerfetto 的 SDK 选型及自建约束,不代表另一框架只能处理固定流程。


Q5:性能 AI 智能体应该如何做好场景识别?

提问背景: 想做场景识别、路由到正确的 Skill,在建设这部分的时候应该更多基于「用户原声」还是「日志」,或者有什么更好的方法?场景识别的几条路径各有问题:代码匹配(关键词匹配会导致筛选结果过大或过小)、LLM 理解(LLM 的理解不一定准确)、日志还原(能筛选有无滑动,但不一定是用户关注的问题)。

SmartPerfetto 的做法:三层信号、分工明确

SmartPerfetto 的场景识别依赖三层信号配合,每层解决不同的问题:

1
2
3
Layer 1: 用户原声 — 关键词匹配 → 场景类型(scrolling / startup / anr / ...)
Layer 2: Trace 数据 — 确定性检测 → 架构信息(Flutter / WebView / Standard / Compose)
Layer 3: 数据完整性 — schema + 有限行探测 → 初步可用性(有无 GPU 数据、有无热降频数据)

Layer 1:用户原声(关键词匹配,<1ms)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// sceneClassifier.ts — 46 行代码,完成了全部场景分类

export function classifyScene(query: string): SceneType {
const scenes = getRegisteredScenes(); // 从 12 个 .strategy.md 的 frontmatter 加载
const lower = query.toLowerCase();

const sorted = scenes
.filter(s => s.scene !== 'general')
.sort((a, b) => a.priority - b.priority); // ANR(1) > startup(2) > scrolling(3) > ...

for (const scene of sorted) {
// 先匹配 compound patterns(更具体,如「启动.*慢」)
if (scene.compoundPatterns.some(p => p.test(query))) return scene.scene;
// 再匹配单关键词
if (scene.keywords.some(k => lower.includes(k))) return scene.scene;
}
return 'general'; // 兜底
}

关键词定义在每个 Strategy 文件的 YAML frontmatter 中,不是硬编码在 TypeScript 里:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# scrolling.strategy.md frontmatter
keywords:
- 滑动
- 卡顿
- 掉帧
- jank
- scroll
- fps
- 帧
- frame
- 列表
- 流畅
- fling
- stuttering
- dropped frame
- 不流畅
# ... 共 30+ 关键词

为什么当时选择关键词匹配?

  1. 成本:这一步不调用模型;<1ms 是历史目标/观察,LLM 的延迟与 token 消耗也随模型、网络及提示变化,没有固定 500ms/500 tokens。
  2. 可复查:同样的规则与输入便于重现分类路径,但确定性不等于正确。
  3. 适用范围:明确的场景词可以快速路由;否定句、多意图和追问仍可能误匹配,需要验证与纠正路径。

关键词匹配不够的地方怎么办?

关键词匹配的确有边界——当用户说「这个 app 为什么慢」时,关键词无法确定是启动慢还是滑动慢。SmartPerfetto 的处理方式是:匹配不到就 fallback 到 general 场景,让 Agent 在 general 策略的路由决策树中自主选择方向。

1
2
3
4
5
6
# general.strategy.md — 没有任何硬约束,只给路由建议

| 用户关注方向 | 推荐路径 |
| CPU / 调度 / 线程 | invoke_skill("cpu_analysis") |
| 内存 / OOM / 泄漏 | invoke_skill("memory_analysis") |
| 不确定方向 | invoke_skill("scene_reconstruction") → 按场景路由 |

这个设计的核心思路是:不要试图在入口处 100% 准确分类,而是让准确的情况走快速路径(关键词 → Strategy),不确定的情况走探索路径(general → Agent 自主路由)。

Layer 2:Trace 数据——架构检测(确定性代码)

场景分类只解决了「用户想分析什么」,但同一个场景(如滑动)在不同渲染架构下的分析路径完全不同:

架构渲染管线分析差异
Standard AndroidUI Thread → RenderThread → SurfaceFlinger主线程 + RenderThread 双线分析
Flutter TextureView1.ui → 1.raster → JNISurfaceTexture → RenderThread updateTexImage双出图管线,需要分析 Flutter engine 线程 + 纹理桥接
Flutter SurfaceView1.ui → 1.raster → BufferQueue → SurfaceFlinger单出图管线,不经过 RenderThread
WebViewCrRendererMain → Viz CompositorChromium 渲染管线,线程名不同
ComposeUI Thread (Composition) → RenderThread和 Standard 类似但有 Composition 阶段

架构检测调用 YAML Skill rendering_pipeline_detection 收集、评分和映射特征;TypeScript 中仍有 pipeline ID 到大类的 if/else 映射与 fallback。architectureDetector.ts 在失败/缺失时可回退 STANDARD、0.5 confidence,这不能当作识别成功或校准过的 50% 概率。管线标签是启发式分类,不是设备实际架构的独立真值。

1
2
3
4
rendering_pipeline_detection skill (SQL)
→ 采集线程信号(1.ui / 1.raster / CrRendererMain / RenderThread ...)
→ 管线打分(FLUTTER_TEXTUREVIEW / WEBVIEW_BLINK / ANDROID_VIEW_STANDARD ...)
→ architectureDetector.ts 映射为 ArchitectureInfo 类型

检测结果被注入到 system prompt 中(通过 arch-flutter.template.md 等模板),Agent 看到架构信息后选择对应的分析工具。

Layer 3:数据完整性——能力寄存器

Trace 采集配置不同,可用的数据维度也不同。有的 trace 没有 GPU frequency 数据,有的没有 thermal zone。SmartPerfetto 在分析开始前探测 18 个数据维度的可用性:

1
2
3
4
available:                     primary table has at least 3 rows
insufficient_or_scene_absent: only 1–2 rows observed
missing_config_suspected: table missing/empty, cause not established
not_applicable: historical architecture filter excluded it

这个信息同样注入 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
2
3
4
5
6
7
8
9
10
11
确定性步骤产出数据
↓
Agent 形成假设(自主,但有推理框架约束)
↓
Agent 选择验证工具(自主,但有 Strategy 建议)
↓
验证结果反馈
↓
假设成立 → 深入 / 假设不成立 → 回退换方向
↓
Verifier 事后检查

三个关键机制让 AI 自主探索变得更可靠:

机制 1:假设管理工具——给推理过程加结构

假设工具用于记录可复查的分析声明,不是读取或强制展示模型内部思维。f3206864 的参数与原文示例不同:

1
2
3
4
5
6
7
{
"tool": "submit_hypothesis",
"arguments": {
"statement": "目标 Binder 服务端的调度等待增加了该同步事务时延",
"basis": "已定位事务与对端线程;下一步查询匹配窗口内的 Runnable 区间"
}
}

上面用 tool/arguments 包装便于阅读,实际由 MCP 客户端按协议发送。工具返回 hypothesisId。获得反证后,状态更新示例为:

1
2
3
4
5
6
7
8
{
"tool": "resolve_hypothesis",
"arguments": {
"hypothesisId": "h1",
"status": "rejected",
"evidence": "示意:对端没有相应调度等待;另一个等待区间需独立调查"
}
}

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
2
3
4
5
6
7
8
# scrolling.strategy.md Phase 1.9

| 条件 | 深钻动作 |
| 任何 reason_code Q4>20% | invoke_skill("blocking_chain_analysis", ...) |
| binder_overlap >5ms | invoke_skill("binder_root_cause", ...) |
| cpu_runnable_ratio >30% | invoke_skill("cpu_analysis", ...) |
| thermal_throttle detected | invoke_skill("thermal_throttling", ...) |
| gc_pause_total >10ms | invoke_skill("gc_analysis", ...) |

这个表不是写死的决策树——它是给 Agent 的查找表。Agent 看到数据后,根据数据中的指标值决定走哪一行。如果数据不匹配任何一行,Agent 可以自主探索。

机制 3:ReAct Reasoning Nudge——在工具返回时触发反思

在数据工具(execute_sql / invoke_skill)成功返回的前几次调用中,SmartPerfetto 在结果末尾附加一段推理提示:

1
2
3
4
5
6
7
8
// claudeMcpServer.ts

const REASONING_NUDGE = '\n\n[REFLECT] 在执行下一步之前:' +
'这个数据的关键发现是什么?是否支持/反驳你的假设?' +
'如有重要推断,请用 submit_hypothesis 或 write_analysis_note 记录。';

// 只在前 N 次数据工具调用时附加,之后停止(控制 token 成本)
const REASONING_NUDGE_MAX_CALLS = 4;

附加提示可提醒模型记录中间判断,但不能保证形成反思或防止跑偏。原稿的约 20 tokens/次、80 tokens 总量未给 tokenizer/usage 证据,中文与英文也不能按同一常数计费;前 4 次只是代码中的附加次数上限。效果需对照评测。

用图片中的 Binder 例子走一遍完整流程

这是教学假设,不是可由本文图片复现的 trace 结论。原稿“47 帧、Frame #234、23ms、限频 50%”没有配套原始数据,不把这些数字当作事实推导。

1
2
3
4
5
6
7
1. 查询目标进程/时间窗的帧数据,明确计数口径与缺失项。
2. 若发现长同步 Binder 区间,先关联事务、客户端和对端线程。
3. 提出“服务端 Runnable 等待增加响应时延”的假设。
4. 在同一事务窗口裁剪对端 thread_state,区分运行、就绪、睡眠和分发等待。
5. 若证据支持,细化慢响应的机制;若不支持,拒绝该假设并记录反证。
6. 只有采到温控策略、有效限频上限及匹配时序等证据,才继续判断热限制的影响。
7. 结论逐项附可查询证据与不确定性,验证过程不能只看原因词是否出现。

CPU 调度延迟可以是 Binder 慢响应的一部分,不能写成“发现调度延迟,所以不是 Binder 响应慢”。低频加温度高也不足以证明温控造成该帧卡顿。假设 ID/状态更新使用上面的真实 schema,已 rejected 的同一假设不能再改成不存在的 refined。

如何让 AI 自主探索更可靠:四个实操建议

  1. 观察、规则判断和假设分开:保留结构化数据与来源;经过验证的规则诊断也可以输出,但不要伪装成原始观测。
  2. 保留确定性边界:预算、身份范围、数值计算和必要查询依赖由程序执行,开放的问题再允许模型选路。
  3. 知识提供排查线索:版本化知识不是当前 trace 的证据,命中知识条目后仍要查询对应数据。
  4. 运行时也核验结论:检查数值、实体、引用、时间窗和因果链;工具日志证明动作发生,文本启发式提供补充提示。离线可用标注集和 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
┌───────────────────────────────────────────────────────┐
│ Tier 1: STATIC(进程生命周期内不变) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ prompt-role.template.md (~200 tokens) │ │
│ │ → 角色定义:Android 性能分析专家 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ prompt-output-format.template.md (~850 tokens) │ │
│ │ → 输出格式:[CRITICAL]/[HIGH]/[MEDIUM]/[LOW] │ │
│ │ → 根因推理链格式、Mermaid 因果链规则 │ │
│ │ → Slice 嵌套规则、CPU 频率估算指南 │ │
│ └─────────────────────────────────────────────────┘ │
├───────────────────────────────────────────────────────┤
│ Tier 2: PER-TRACE(同一 trace 内稳定) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 架构信息 (~150 tokens) │ │
│ │ → "Flutter TextureView, 置信度 92%" │ │
│ │ → + arch-flutter.template.md 架构指南 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 焦点应用 (~100 tokens) │ │
│ │ → "com.example.app (主焦点), 帧数 456" │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 数据完整性 (~200 tokens, 可被丢弃) │ │
│ │ → 只报告缺失/不足的维度,可用维度不报告 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ SQL 知识库参考 (~300 tokens, 可被丢弃) │ │
│ │ → 从 Perfetto stdlib 索引匹配到的表/视图/函数 │ │
│ └─────────────────────────────────────────────────┘ │
├───────────────────────────────────────────────────────┤
│ Tier 3: PER-QUERY(场景/查询变化时变化) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 方法论 + 场景策略 (~1200 tokens) │ │
│ │ → prompt-methodology.template.md │ │
│ │ → {{sceneStrategy}} = scrolling.strategy.md │ │
│ │ 或 startup/anr/general 等 12 套策略之一 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 子代理协作指南 (~200 tokens, 可被丢弃) │ │
│ │ → 何时委托 vs 直接调用 │ │
│ │ → 滑动场景专用并行证据收集指南 │ │
│ └─────────────────────────────────────────────────┘ │
├───────────────────────────────────────────────────────┤
│ Tier 4: PER-INTERACTION(每次查询都可能变化) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 用户选区上下文 (~300 tokens, 不可丢弃) │ │
│ │ → 时间范围选区 (selection-area.template.md) │ │
│ │ → 或 Slice 选区 (selection-slice.template.md) │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 比较模式上下文 (条件注入) │ │
│ │ → 双 trace 对比方法论 + 工具说明 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 对话上下文 (~500 tokens) │ │
│ │ → 分析笔记 (≤10 条, 按优先级排序) │ │
│ │ → 之前的 findings (≤10 条) │ │
│ │ → 已知实体 (用于 drill-down) │ │
│ │ → 对话摘要 (跨轮压缩, ≤2000 tokens) │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ SQL 踩坑记录 (≤5 条, 可被丢弃) │ │
│ │ → ERROR → BAD SQL → FIX SQL │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 历史分析经验 (跨会话模式记忆, 可被丢弃) │ │
│ │ 历史踩坑记录 (跨会话负面记忆, 可被丢弃) │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ 历史分析计划 (≤3 轮, 可被丢弃) │ │
│ │ → 各阶段 ✓/⊘/○ 状态 + 摘要 │ │
│ └─────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────┘

模板加载与变量替换

固定规则主要来自 Markdown 模板;动态选区、findings、notes 和预算裁剪仍由 TypeScript 构造。下面展示模板路径:

1
2
3
4
5
6
7
8
9
10
11
// strategyLoader.ts — 模板系统

// 1. 加载模板(开发模式的缓存策略需按服务端配置确认)
loadPromptTemplate('prompt-methodology') // → strategies/prompt-methodology.template.md

// 2. 加载场景策略(从 YAML frontmatter 中提取 keywords,body 作为策略内容)
getStrategyContent('scrolling') // → strategies/scrolling.strategy.md 的 Markdown body

// 3. 变量替换
renderTemplate(methodologyTemplate, { sceneStrategy })
// 将 {{sceneStrategy}} 替换为 scrolling.strategy.md 的内容

模板文件清单:

类别文件用途
静态模板prompt-role.template.md角色定义
prompt-output-format.template.md输出格式规则(91 行)
prompt-quick.template.md快速模式精简 prompt
方法论prompt-methodology.template.md分析方法论(含 {{sceneStrategy}} 占位符)
架构指南arch-standard.template.mdStandard Android 渲染指导
arch-flutter.template.mdFlutter 引擎指导
arch-compose.template.mdJetpack Compose 指导
arch-webview.template.mdWebView 指导
选区模板selection-area.template.md时间范围选区({{startNs}}, {{endNs}}…)
selection-slice.template.mdSlice 选区({{eventId}}, {{ts}}…)
比较模式comparison-methodology.template.md双 trace 对比方法论
场景策略12 个 *.strategy.mdscrolling/startup/anr/memory/…
知识模板8 个 knowledge-*.template.md按需加载的领域知识(非 prompt 注入)
辅助模板prompt-complexity-classifier.template.mdQuick/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
2
3
4
5
6
7
8
丢弃顺序(最先丢弃 → 最后丢弃):
1. Perfetto SQL 知识库参考 → Agent 可以用 lookup_sql_schema 工具替代
2. Trace 数据完整度 → 有帮助但 Agent 运行时也能发现数据缺失
3. 历史分析经验 → 跨会话模式记忆,非关键
4. 历史踩坑记录 → 跨会话负面记忆,可丢弃
5. SQL 踩坑记录 → 锦上添花
6. 子代理协作 → 只在 sub-agent 启用时有用
7. 历史分析计划 → 补充性上下文

永不丢弃的内容:

  • 角色定义、输出格式(Tier 1 静态)
  • 架构信息、焦点应用(Tier 2 per-trace)
  • 方法论 + 场景策略(Tier 3 核心)
  • 用户选区上下文(用户的显式意图)
  • 对话上下文(之前的 findings 和分析笔记)

f3206864 删除可选 section 后如果仍超预算,只记录 warning 并返回剩余内容。因此 4500/3000 不是硬截断保证,也不包含全部会话历史、工具定义及输出预算。数据完整度提示被裁掉后,工具结果仍应保留缺失/unknown;“未提示缺失”不等于数据完整。

上下文构建的完整流程

在 ClaudeRuntime.analyze() 中,prompt 拼接前需要经过二十多个准备阶段(Phase)来收集所有上下文:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Phase 0:   选区上下文日志
Phase 0.5: 焦点应用检测(3 种方法:battery_stats / oom_adj / frame_timeline)
Phase 1: Skill 执行器初始化
Phase 2: 架构检测(LRU 缓存,缓存有效且存在时复用)
Phase 2.5: 厂商检测(OEM 定制化,LRU 缓存)
Phase 2.8: 比较模式上下文(双 trace 模式)
Phase 2.9: 数据完整性探测(18 个维度,耗时依数据与模块状态)
Phase 3: 会话上下文 + 对话历史
Phase 4: 实体存储(drill-down 引用)
Phase 5: 场景分类(关键词匹配,<1ms)
Phase 5.5: 跨会话模式记忆匹配
Phase 6: ArtifactStore + 分析笔记
Phase 6.5: 分析计划(当前 + 历史)
Phase 6.6: Watchdog 反馈引用
Phase 6.7: 假设状态
Phase 6.8: 不确定性标记
Phase 7: SQL 错误追踪
Phase 8: MCP Server 创建(注入以上所有状态)
Phase 9: (已移除)
Phase 10: SQL 知识库上下文
Phase 11: Sub-agent 定义
Phase 12: SQL error-fix pairs
Phase 13: → buildSystemPrompt(context) → 最终 prompt

所有 Phase 的结果汇入 ClaudeAnalysisContext 对象,传给 buildSystemPrompt() 做最终拼接。

Phase 编号是这份源码里的准备步骤,不是必须逐项串行完成的外部协议。LRU 淘汰、会话恢复和失败重试都可能重新探测;已有状态也可能来自恢复,不应把“第1轮”固定等同于空白上下文。

Quick vs Full 双模式

不是所有查询都需要完整的 4500-token prompt。当入口判为 quick 时,SmartPerfetto 使用精简的 quick prompt:

1
2
3
4
// buildQuickSystemPrompt() — ~1500 tokens
// 加载 prompt-quick.template.md
// 只注入 {{architectureContext}} 和 {{focusAppContext}}
// 无方法论、无场景策略、无对话上下文
维度Quick ModeFull 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
2
3
4
5
6
7
8
9
10
[Tier 1] prompt-role.template.md                    → "你是 Android 性能分析专家..."
[Tier 1] prompt-output-format.template.md → 输出格式规则
[Tier 2] "架构: Flutter TextureView, 置信度 92%" → + arch-flutter.template.md
[Tier 2] "焦点应用: com.example.app (主焦点)" → 帧数 + 检测方法
[Tier 2] "数据完整性: gpu ❌ 疑似未采集" → 只报缺失/不足,可用的不报
[Tier 2] SQL 知识库: android_frames, slice_self_dur → stdlib 匹配结果
[Tier 3] prompt-methodology + scrolling.strategy.md → Phase 1→1.5→1.9→3 完整策略
[Tier 4] (无选区、无对话上下文、无历史计划)

预估: ~3200 tokens, 在 4500 预算内, 无需丢弃

用户追问 "深入分析第 3 帧",第 2 轮(SDK session resume 命中):

1
2
3
4
5
6
7
8
[Tier 1-3] 与第 1 轮相同(相同部分具备前缀复用机会,未实测)
[Tier 4] 对话上下文 (SDK 已持有对话历史,不重复注入 findings):
- 分析笔记: "⚠️ [假设] 主要 jank 原因是 RenderThread Binder 阻塞"
- 实体上下文: frame#3 的 ID 和时间范围
- 历史计划: "✓ Phase 1 概览, ✓ Phase 1.9 深钻, ○ Phase 3 结论"
(previousFindings 和 conversationSummary 由 SDK session 内部管理,不在 prompt 中重复)

预估: ~3400 tokens, 在预算内

这是教学拼接示例,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 版本。当前清单与安装版本可能不同。

分类数量说明
Atomic87单步检测/统计,一条或几条 SQL 完成
Composite29组合多个 atomic skill,支持 iterator/conditional
Deep2深度剖析(callstack、CPU profiling)
Pipeline28渲染管线检测 + 教学(24+ 种架构)
Module18模块化配置: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_analysisFlutter 特定帧分析,使用 Flutter 线程模型
jank_frame_detail分析特定掉帧的详细原因:深钻 jank 原因和根因分类
startup_analysis启动分析主入口:Iterator 模式、大小核分析、四象限
startup_detail分析单个启动事件:主线程耗时、Binder、CPU 大小核占比
anr_analysisANR v3.0 分析:系统问题 vs 应用问题、分类处理
anr_detail单个ANR关联线程状态/Binder依赖,死锁需额外证据
cpu_analysisCPU 分析:时间分布、大小核分析、调度链路
gpu_analysisGPU 分析:频率分布、内存使用、帧渲染关联
memory_analysis内存分析:GC 事件、GC 与帧关联、线程状态
gc_analysisGC 分析:基于 stdlib android_garbage_collection_events
binder_analysisBinder 深度分析:事务基础、线程状态
binder_detail单个 Binder 事务详情:CPU 大小核、四象限、阻塞原因
thermal_throttling温度监控、热节流检测、CPU 频率相关性
lock_contention_analysis锁竞争多维度分析:基于 android.monitor_contention
surfaceflinger_analysisSF 帧合成性能:GPU/HWC 合成比例、慢合成检测
click_response_analysis点击响应分析:基于 stdlib android_input_events
click_response_detail单个慢输入事件详情:延迟分解、四象限、主线程阻塞
scroll_session_analysis单个完整滑动区间:Touch 阶段 vs Fling 阶段 FPS
navigation_analysisActivity/Fragment 跳转性能:生命周期、转场动画
lmk_analysisLMK 分析:原因分布、时间线、频率
dmabuf_analysis统计DMA Buffer事件与未配对候选,不能仅据此判泄漏
block_io_analysisBlock IO 分析:设备级统计、队列深度、长耗时 IO
io_pressureIO 阻塞数据检测、IO Wait 时间、严重度评估
suspend_wakeup_analysis休眠/唤醒分析:时间分布、唤醒源排行
network_analysis网络分析:流量概览、应用流量、协议分布
irq_analysis硬中断和软中断的频率、耗时、嵌套情况
scene_reconstruction通过用户输入和屏幕状态还原用户操作场景
state_timeline四泳道连续状态时间线:设备/用户/应用/系统

引擎支持 conditional 类型,但此快照的定义没有使用该 step;类型支持与已存在的执行路径分开看。查询输出中的分类仍可能是启发式,不能仅凭 Skill 名为 root_cause 就视为因果已证实。

Deep Skills(2 个)

深度剖析,通常需要更长的执行时间。

Skill ID一句话描述
cpu_profilingCPU 性能剖析:使用热点和调度效率深度分析
callstack_analysisRunning 状态下的调用栈热点分析

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_softwareCPU Skia 软件渲染,无 RenderThread
pipeline_android_view_mixedView + SurfaceView 混合渲染
pipeline_android_view_multi_window同进程多窗口(Dialog/PopupWindow)
pipeline_android_pip_freeform画中画和自由窗口模式
pipeline_compose_standardJetpack Compose + HWUI RenderThread
pipeline_flutter_textureviewFlutter由TextureView承载的路径,非一律PlatformView降级
pipeline_flutter_surfaceview_skiaFlutter + Skia 引擎(JIT Shader)
pipeline_flutter_surfaceview_impellerFlutter SurfaceView + Impeller;仍需查运行时pipeline/cache工作
pipeline_webview_gl_functor传统 WebView,App RenderThread 同步等待
pipeline_webview_surface_control现代 WebView + Viz/OOP-R 独立合成
pipeline_webview_textureview_customX5/UC 等定制 WebView 内核
pipeline_webview_surfaceview_wrapperWebView 全屏视频包装模式
pipeline_chrome_browser_vizChrome Viz 合成器,多进程架构
pipeline_opengl_es直接 OpenGL ES / EGL 渲染
pipeline_vulkan_native原生 Vulkan 渲染
pipeline_angle_gles_vulkanANGLE: OpenGL ES → Vulkan 翻译层
pipeline_game_engineUnity/Unreal/Godot 等游戏引擎
pipeline_surfaceview_blast独立 SurfaceView + BLAST 同步
pipeline_textureview_standardSurfaceTexture 纹理采样/合成模式
pipeline_camera_pipelineCamera2/HAL3 多流相机渲染
pipeline_video_overlay_hwcHWC 视频层硬件加速叠加
pipeline_hardware_buffer_rendererAndroid 14+ HBR API 直接 Buffer 渲染
pipeline_surface_control_apiNDK SurfaceControl 直接事务提交
pipeline_variable_refresh_rateVRR/ARR + FrameTimeline 动态刷新率
pipeline_imagereader_pipelineImageReader API:ML 推理、录屏、自定义相机
pipeline_software_compositing软件合成候选教学定义;不证明SF有通用CPU回退路径

注:_base.skill.yaml 是 Pipeline Skill 的基础模板文件,不注册为可用 Skill,不计入总数。


Module Skills(18 个)

模块化分析配置,按层级组织。Agent 通过 list_skills 发现并按需调用。

硬件层(5 个):

Skill ID一句话描述
cpu_moduleCPU 频率、热节流和电源状态
gpu_moduleGPU 渲染、频率和显存使用
memory_module内存带宽、LMK、dmabuf、PSI、缺页
thermal_module温度传感器、热节流检测、冷却策略
power_moduleWake Lock、CPU idle、电源模式、休眠/唤醒

框架层(6 个):

Skill ID一句话描述
surfaceflinger_module帧渲染时序、卡顿原因、GPU 合成
choreographer_moduleVSync 信号、doFrame 回调、帧生产管线
ams_module应用生命周期、进程管理、启动时序
wms_module窗口动画、Activity 转场、多窗口
art_moduleGC、JIT 编译和内存分配
input_module触摸延迟、输入派发和点击响应

内核层(4 个):

Skill ID一句话描述
scheduler_module线程调度延迟、CPU 利用率、大小核分配
binder_module跨进程调用、阻塞事务、调用延迟
lock_contention_moduleMutex/Futex、Java monitor、死锁检测
filesystem_moduleBlock IO、文件操作、数据库、SharedPreferences

应用层(3 个):

Skill ID一句话描述
launcher_module主屏性能、应用启动、小部件更新
systemui_module状态栏、通知栏、快速设置、导航栏
third_party_module第三方应用性能、卡顿和资源使用

Skill 之间的关系

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Module Skills (配置层)
└→ 定义分析范围和关注点

Composite Skills (编排层)
├→ 引用多个 Atomic Skills
├→ Iterator: 逐帧/逐事件遍历深钻
└→ Conditional: 按数据条件分支

Atomic Skills (执行层)
└→ 直接执行 SQL,返回 DataEnvelope

Pipeline Skills (知识层)
└→ 渲染管线教学 + 检测

Deep Skills (剖析层)
└→ Callstack / CPU profiling 深度分析

快照中的滑动分析路径:

1
2
3
4
5
invoke_skill("scrolling_analysis")
→ 引用 cpu_topology_view、frame_pipeline_variance 等
→ 内部 SQL 生成帧概览/列表与 batch_frame_root_cause 分类
Agent 按需要另调 jank_frame_detail(可选深钻)
→ 引用 binder_blocking_in_range、sched_latency_in_range 等

scrolling_analysis 在此快照已使用批量 SQL 分类,不是原稿画出的“consumer_jank_detection → iterator → 每帧 jank_frame_detail”。复用某段计算逻辑也不等于调用同名 Skill;读调用边时要区分内联 SQL、skill 引用和 Agent 后续工具调用。


关于我 && 博客

下面是个人的介绍和相关的链接,期望与同行的各位多多交流,三人行,则必有我师!

  1. 博主个人介绍 :里面有个人的微信和微信群链接。
  2. 本博客内容导航 :个人博客内容的一个导航。
  3. 个人整理和搜集的优秀博客文章 - Android 性能优化必知必会 :欢迎大家自荐和推荐 (微信私聊即可)
  4. Android 性能优化知识星球:付费社群已于 2026 年停止运营,不再招收新成员;此处保留历史介绍。

一个人可以走的更快 , 一群人可以走的更远

旧群二维码保留作历史图片,不保证仍有效;问题反馈可使用 项目 Issues。

SmartPerfetto 交流群