这篇文章收集了《从 Trace 到洞察：SmartPerfetto AI Agent 的 Harness Engineering 实战》发布后收到的技术问题，以问答形式展开讨论。

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 → 帮用户分析性能数据

Claude Code 的 Skill 运行在开发者的终端里，是 CLI 工具的扩展。SmartPerfetto 的 YAML Skill 运行在 Express 后端的 Skill Engine 中，是 Agent 在运行时通过 MCP 工具 invoke_skill 调用的分析单元。两者的执行环境、调用方式、数据流完全不同。

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

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

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

1
2
3
4
5
6
7
8
9
10

steps:
  - id: thread_state_distribution
    type: atomic
    sql: |
      SELECT state, SUM(dur) as total_dur
      FROM thread_state ts
      JOIN thread_track tt ON ts.track_id = tt.id
      WHERE tt.utid = ${main_thread_utid}
        AND ts.ts BETWEEN ${start_ts} AND ${end_ts}
      GROUP BY state

${main_thread_utid} 和 ${start_ts} 是 Claude 调用 invoke_skill 时传入的参数。YAML Skill Engine 做参数替换后执行 SQL。如果用 scripts/，要么写 shell 脚本接收参数拼 SQL（容易出注入问题），要么写完整的 Python/Node 脚本——复杂度比 YAML 高很多。

2. 自描述的输出格式（DataEnvelope）

1
2
3
4
5

display:
  level: detail
  columns:
    - { name: state, type: string }
    - { name: total_dur, type: duration }

每个 step 声明了输出列的名称和类型。前端根据这个 schema 自动渲染表格——duration 类型自动格式化为 ms，timestamp 类型支持点击跳转到 Perfetto 时间线。scripts/ 方式的输出是自由文本，前端没法自动渲染。

3. 可组合（composite + iterator）

一个 composite Skill 可以引用多个 atomic Skill，iterator 可以遍历数据行逐帧分析。这种组合在 YAML 中是声明式的，Skill Engine 负责编排执行。scripts/ 方式要实现同样的组合需要自己写编排逻辑。

4. 面向性能工程师，不是面向开发者

提问者说对了：YAML Skill 本质上是一个让性能工程师按预定义规则贡献分析逻辑的工具。性能工程师知道该查什么 SQL、该看什么指标，但不一定会写 TypeScript。YAML 格式让他们直接定义 SQL 查询和输出格式，不需要碰后端代码。修改后 DEV 模式刷新浏览器即可生效。

对比总结

两者不是替代关系，而是在不同层面解决不同问题。

Q2：「确定性 + 灵活性混合」具体是怎么实现的？

提问背景： 文章说「已知场景用 Strategy 文件约束必检项，但每个阶段内的具体查询和深钻方向由 Claude 自主决定」。这个约束和自主之间的边界在哪里？具体是怎么做到的？

三层机制配合

这个混合设计靠三层机制配合实现：Strategy 文件定义「必须做什么」，Planning Gate 强制「先计划再执行」，Verifier 事后检查「是否真的做了」。

第一层：Strategy 文件 — 有硬约束也有软指引

以滑动分析的 scrolling.strategy.md 为例，它定义了多个分析阶段，但每个阶段的约束强度不同：

硬约束（必须执行，跳过会触发验证错误）：

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 中看到这些阶段定义、🔴 标记和「禁止」字样。

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

Claude 在执行任何 SQL 查询或 Skill 调用之前，必须先调用 submit_plan 提交分析计划。没有提交计划就调用 execute_sql 或 invoke_skill 会被直接拒绝：

1
2
3
4

function requirePlan(toolName: string): string | null {
  if (analysisPlanRef.current) return null;  // 已有计划，放行
  return `必须先调用 submit_plan 提交分析计划，然后才能使用 ${toolName}`;
}

关键点在于：Gate 只要求计划存在，不要求计划和 Strategy 的阶段完全对应。 Claude 可以提交任何结构的计划——它可以把 Phase 1 和 1.5 合并，可以加入 Strategy 没提到的额外步骤，也可以根据初步数据调整深钻方向。

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

这个设计的目的是：强制 Claude 在动手之前先想清楚要做什么（规划纪律），但不限制它怎么想（规划自由）。

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

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

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

1
2
3
4
5
6
7
8
9
10
11

// 滑动场景：检查是否有显著掉帧但没做 Phase 1.9 深钻
case 'scrolling': {
  const hasSignificantJank = /* 检测文本中是否提到大量掉帧 */;
  const hasDeepDrill = /* 检测是否调用了 blocking_chain / binder_root_cause 等 */;
  if (hasSignificantJank && !hasDeepDrill) {
    issues.push({
      severity: 'error',
      message: '滑动分析有掉帧但缺少 Phase 1.9 根因深钻 — reason_code 只是分类标签，不是真正的根因'
    });
  }
}

b) 假设闭环检查——所有 submit_hypothesis 是否都有对应的 resolve_hypothesis。

c) 因果链深度检查——CRITICAL/HIGH 级别的 findings 是否包含足够的因果连接词和机制性术语（启发式文本匹配）。

d) 可选的 LLM 复核——用独立的 Haiku 模型做证据支撑度验证（可关闭）。

如果检查发现 ERROR 级别问题，会触发 Correction Prompt 让 Claude 补做。

注意 Verifier 不检查 Claude 的计划阶段是否匹配 Strategy 的阶段编号——它检查的是「关键分析动作是否体现在输出中」，不是「计划格式是否正确」。

完整的约束光谱

把三层机制叠在一起，不同阶段的约束强度形成了一个光谱：

而 general.strategy.md（未匹配到场景时的 fallback）则完全是软指引：只给了一个按用户关注方向的路由决策树（CPU → cpu_analysis，内存 → memory_analysis），没有任何必须执行的阶段。Claude 在 general 场景下有完全的自主权。

一句话总结

Strategy 文件告诉 Claude「分析滑动问题至少要做这几件事」，Planning Gate 确保它先想后做，Verifier 事后检查关键步骤有没有真的做。 但在这个框架内，具体查什么数据、用哪个工具、按什么顺序，都是 Claude 根据实际数据自主决定的。

Q3：Agent 和 Workflow 最大的区别在哪里？Agent 的能力边界在哪里、由什么决定？

提问背景： 我们在建设 Agent 的过程中，从最初默认 Agent 有能力理解并决策一切给它的 Skill，到现在几乎在 Skill 中写死了一棵决策树，这中间踩坑的出发点都是：「我们认为 Agent 有 xx 能力，但它没有」，导致其输出偏离我们的预期，于是我们不断地给 Skill 加边界，最后变成了一个写死的 Workflow。

本质区别：决策权在谁手里

Agent 和 Workflow 不是两个工具、两个框架——它们是同一个光谱的两端：

1
2
3
4
5

写死的 Workflow ◄──────────────────────────────────► 完全自主的 Agent
  │                                                        │
  开发者控制每个分支                               LLM 决定一切
  │                                                        │
  高确定性、低灵活性                               低确定性、高灵活性

但工程实践中，几乎没有人处在光谱的任何一端。 纯 Workflow 无法处理未知场景；纯 Agent 在关键步骤上不可靠。实际落地的系统都在光谱的某个中间位置。

你们踩坑的根因：对 Agent 能力做了全局假设

「默认 Agent 有能力理解一切 → 发现它做不到 → 不断加约束 → 变成写死的 Workflow」——这个路径的根本问题在于：对 Agent 的能力做了全局一刀切的判断。

但 Agent 的能力在不同环节差异巨大：

正确的做法不是「全局选 Agent 或全局选 Workflow」，而是按环节分配：

1
2
3
4
5

场景识别     → Workflow（确定性逻辑，不需要 LLM 参与）
数据收集     → 半 Workflow（Skill 定义查什么，Agent 决定顺序和参数）
推理归因     → Agent（这是 LLM 的核心价值，给足数据就能做好）
输出格式     → Workflow（模板化，确定性）
质量验证     → Workflow（规则检查）+ Agent（LLM 复核）

SmartPerfetto 的做法：约束强度光谱

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

高约束（Phase 1.9 根因深钻）——因为 Agent 在「决定是否深钻」这件事上不可靠：

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 有一个系统性偏差：它倾向于在拿到概览数据后就直接出结论，跳过深钻。这不是模型不够聪明——Claude 完全有能力做根因深钻——而是模型存在「路径依赖」：概览数据已经包含了统计分类（reason_code），对模型来说「直接用分类标签出结论」比「花 3 轮工具调用做逐帧深钻」的认知成本低得多。

低约束（Phase 1.5 架构分支）——因为 Agent 在「根据数据选择工具」上足够可靠：

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，Agent 看到这个信息后选择正确 Skill 的概率很高。

零约束（general 场景）——因为 Agent 在「未知场景自主探索」上是唯一选择：

1
2
3
4
5
6
7

# general.strategy.md — 只给路由决策树，不给任何必须执行的步骤

场景: general
priority: 99

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

general 场景没有任何硬约束，因为进入 general 意味着用户的问题超出了预定义场景，Workflow 无法处理。此时只能信任 Agent 的自主探索能力。

Agent 能力边界的决定因素

Agent 的能力边界不取决于模型参数量或 benchmark 分数，而取决于三个工程因素：

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 里写死决策树」有什么区别？

直说：在数据收集阶段，SmartPerfetto 的滑动分析就是一个 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 程度不同：

scrolling.strategy.md 是 SOP 程度最高的，因为滑动分析方法论最成熟。general.strategy.md 几乎没有 SOP，因为用户问题完全不可预测。

所以正确的理解是：SmartPerfetto = 「SOP 驱动的数据收集 + Agent 驱动的推理归因」。

SOP 解决「分析滑动问题至少要看哪些数据」——这个问题有确定性答案，用 SOP 是对的。Agent 解决「拿到数据后怎么推理因果、怎么组织结论」——这个问题每个 trace 不同，写不成 SOP。

回到你们的踩坑：问题不是「Skill 变成了 SOP」——数据收集阶段就应该用 SOP。问题是「SOP 吃掉了推理」——如果 SOP 连结论都写死了（”看到 X 就输出 Y”），Agent 就真的退化成 Workflow 了。关键是让 SOP 止步于数据收集，把推理留给 Agent。

一句话总结

Agent 和 Workflow 的区别不是「智能 vs 写死」，而是「决策权的分配方式」。Agent 的能力边界由「观测能力 × 约束框架 × 反馈质量」共同决定。正确的做法是按环节分配决策权——在 Agent 可靠的环节给自主权，在 Agent 不可靠的环节加约束——而不是全局一刀切。

Q4：Agent 的架构需要从业务视角进行改进吗？

提问背景： Agent 的架构有过不同的设计和演进——从最初的 ReAct 架构，到 LangGraph 的节点式架构，不同的 Agent 架构设计会给它带来怎样的影响？在搭建自己的业务 Agent 时，是否需要考虑架构对 Agent 性能的影响？例如 SmartPerfetto 是在 Claude Agent SDK 的基础上基于业务理解加入了不同的 Skill 加载模式。

三种主流架构的本质差异

它们的核心区别在于「谁来决定下一步做什么」：

• ReAct：LLM 在每一步都做完整决策（想什么、做什么、用什么工具），框架只负责转发
• LangGraph：开发者预定义了所有可能的路径（节点+边），LLM 只在节点内部做局部决策
• SDK 原生：SDK 管理对话循环，LLM 自主选择工具，开发者通过 system prompt 和工具设计来间接约束

SmartPerfetto 选择 SDK 原生 + 自建约束层的原因

SmartPerfetto 的架构是 Claude Agent SDK（SDK 原生）+ 三层约束（Strategy/Planning Gate/Verifier）：

1
2
3
4
5
6
7
8

Claude Agent SDK 提供:                SmartPerfetto 自建:
├─ Turn loop（自动管理多轮对话）      ├─ Scene Classification（场景路由，<1ms）
├─ Tool dispatching（MCP 工具调用）   ├─ Strategy Injection（按场景注入分析策略）
├─ Streaming（SSE 事件流）           ├─ Planning Gate（强制先规划再执行）
├─ Session resume（多轮上下文恢复）   ├─ Verifier（事后验证 + 纠错重试）
└─ Sub-agent orchestration           ├─ ArtifactStore（3 级缓存压缩 token）
                                     ├─ Conditional Tool Loading（按场景注入/隐藏工具）
                                     └─ Cross-Session Memory（模式记忆 + 负面记忆）

为什么不用 LangGraph？

性能分析的根因推理路径是不可预测的。同样一个「滑动卡顿」，根因可能是：

• Binder 阻塞 → 需要追踪 system_server 端的线程状态
• GPU 渲染慢 → 需要查 GPU frequency 和 fence wait
• GC 暂停 → 需要看 Java heap 和 GC events
• 热降频 → 需要查 thermal zone 和 CPU frequency
• 锁竞争 → 需要查 monitor contention
• 以上多个原因组合

如果用 LangGraph，你需要为每一种根因路径预定义一个 DAG 节点和跳转条件。性能分析有 21 个 reason_code，每个可以组合深钻——排列组合后的路径数量使得 DAG 图变得不可维护。

更根本的问题是：在看到数据之前，你不知道该走哪条路径。LangGraph 的 DAG 图假设开发者能提前预知所有分支条件，但性能分析的分支条件取决于运行时数据。

SDK 原生架构的优势：

LLM 自主选择工具路径，但通过三层约束确保关键步骤不被跳过：

1
2
3
4
5
6
7
8
9

# LangGraph 需要预定义的 DAG:
graph.add_edge("overview", "check_binder")
graph.add_edge("overview", "check_gpu")
graph.add_edge("overview", "check_gc")
# ... 每加一种根因就要改图结构

# SmartPerfetto 的 Strategy 只需要声明:
# "对占比 >15% 的每个 reason_code，必须选最严重的 1 帧执行深钻"
# Agent 自主决定具体调哪个深钻工具

关键业务导向的架构设计

以下是 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
}

业务原因： 工具越多，Agent 选错工具的概率越大。一个只需要快速回答「帧率是多少」的查询，如果看到十几个规划/假设/比较工具，Agent 可能会过度分析。

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

1
2
3
4
5
6
7
8
9
10

// claudeAgentDefinitions.ts — 只在复杂场景启用 sub-agent

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

// Sub-agent 只拿到数据收集工具，不拿规划/假设工具
// 设计原则：sub-agents collect evidence, orchestrator makes diagnosis

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

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

当用户问「这个 trace 的帧率是多少」时，不需要走完整的 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」），走完整管线会不必要地增加延迟。

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

需要，但改进方向不是换底层框架（ReAct → LangGraph），而是在现有框架上加业务约束层。 具体建议：

1. 从你的 Skill 决策树中提取 Strategy 文件：把写死在代码里的 if/else 决策逻辑，改写为自然语言的分析策略（Markdown 文件），按场景注入 system prompt。这样领域专家可以直接修改分析逻辑，不需要碰代码。

2. 加 Planning Gate：requirePlan() 的实现极其简单（不到 10 行代码），但效果显著——强制 Agent 先想后做，经验上能大幅减少跑偏。

3. 加事后 Verifier：不检查 Agent 的中间步骤是否「正确」（这个很难判断），只检查关键步骤是否「发生了」（这个很容易判断）。

4. 按场景/复杂度动态调整工具集和约束强度：不是所有查询都需要同样的分析深度，给简单查询开一条快速通道。

一句话总结

架构选择是业务问题，不是技术问题。ReAct/LangGraph/SDK 只是控制流的不同实现方式——真正影响 Agent 性能的是你在控制流之上搭建的约束层。SmartPerfetto 选择 SDK 原生不是因为它最先进，而是因为性能分析的根因路径不可预测，预定义 DAG 不如让 Agent 在约束框架内自主探索。

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

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

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

SmartPerfetto 的场景识别不是靠单一信号源，而是三层信号配合，每层解决不同的问题：

1
2
3

Layer 1: 用户原声 — 关键词匹配 → 场景类型（scrolling / startup / anr / ...）
Layer 2: Trace 数据 — 确定性检测 → 架构信息（Flutter / WebView / Standard / Compose）
Layer 3: 数据完整性 — 表存在性检查 → 可用分析维度（有无 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+ 关键词

为什么用关键词匹配而不是 LLM？

1. 成本：场景分类在每次分析的入口处执行，关键词匹配 <1ms + 0 tokens；LLM 调用 ~500ms + ~500 tokens
2. 确定性：分类错误的代价非常高（会注入错误的 Strategy 文件），关键词匹配的行为完全可预测
3. 足够准确：在性能分析领域，用户的提问高度格式化——说「滑动卡顿」的就是在问滑动，说「启动慢」的就是在问启动。不需要 LLM 来”理解”

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

关键词匹配的确有边界——当用户说「这个 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 数据——架构检测（确定性代码）

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

架构检测委托给 YAML skill rendering_pipeline_detection——它在 SQL 层做线程/Slice 信号采集、管线打分、子变体判定，支持 24 种细粒度渲染架构。TypeScript 侧（architectureDetector.ts）只负责调用 skill 和映射结果，不做直接的 if/else 判断：

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
5

frame_rendering: ✅ (456 rows)
cpu_scheduling: ✅ (12000 rows)
gpu: ❌ (无 gpu_frequency counter)
thermal_throttling: ✅ (4 zones)
binder_ipc: ✅ (890 transactions)

这个信息同样注入 system prompt，告诉 Agent 哪些维度可以分析、哪些维度数据缺失。避免 Agent 调用没有数据支撑的 Skill 后得到空结果再换方向——这种试错浪费 1-2 个工具调用的 token。

对提问中三条路径的评价

1. 代码匹配（关键词）：可以用，但要设计好兜底

提问者说「关键词匹配会导致筛选结果过大或过小」。SmartPerfetto 的经验是：

• 优先级排序解决「过大」问题：ANR(1) > startup(2) > scrolling(3)，同时命中多个关键词时取优先级最高的
• Compound patterns 解决精度问题：/启动.*慢/ 比单独匹配「启动」更精确
• general 兜底解决「过小」问题：匹配不到就不猜，交给 Agent 自主探索

2. LLM 理解：不建议用在分类入口，可以用在兜底路径

LLM 的分类在 SmartPerfetto 中不是 Layer 1，而是 general 场景中 Agent 的自主路由——这时 Agent 已经拿到了 trace 数据，可以结合数据做更准确的判断。

3. 日志还原：适合做 Layer 2 的补充信号

日志能告诉你「trace 中有什么」（有无滑动事件、有无 ANR），但不能告诉你「用户关心什么」。SmartPerfetto 的数据完整性探测就是这个角色——它不参与场景分类，但为 Agent 提供数据可用性信息。

一句话总结

场景识别不要试图用一个信号源解决所有问题。用关键词匹配做快速路由（准确的情况），用 general 兜底做 Agent 自主探索（不确定的情况），用 trace 数据做架构和完整性补充。关键词匹配 + 优先级排序 + compound patterns + 兜底策略，46 行代码就够了。

Q6：「确定性步骤 + AI 自主探索」，如何更好地发挥 AI 自主探索能力？

提问背景： 目前线上 Skill 运行的时候发现，AI 自主探索、下钻根因容易跑偏，给出不正确的结果。比如 SmartPerfetto 博客中提到的例子——在前期定位到 RenderThread 被 Binder 阻塞后（基于确定性步骤），后面的多个假设形成和验证是纯 AI 发挥吗，还是说针对 Binder 阻塞我们可能给 AI 一些常见的原因作为引导让它自己排查？

先回答核心问题：不是纯 AI 发挥，也不是写死引导

SmartPerfetto 的做法是结构化推理框架 + 按需知识注入：

1
2
3
4
5
6
7
8
9
10
11

确定性步骤产出数据
  ↓
Agent 形成假设（自主，但有推理框架约束）
  ↓
Agent 选择验证工具（自主，但有 Strategy 建议）
  ↓
验证结果反馈
  ↓
假设成立 → 深入 / 假设不成立 → 回退换方向
  ↓
Verifier 事后检查

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

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

SmartPerfetto 提供了 submit_hypothesis 和 resolve_hypothesis 两个 MCP 工具，不是让 Agent 在内心独白中隐式推理，而是强制外显化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Agent 调用:
  submit_hypothesis({
    description: "system_server Binder 响应慢导致 RenderThread 阻塞",
    expected_evidence: "system_server 端对应 Binder 事务的 thread_state 显示长时间 Runnable/Sleeping"
  })

Agent 调用:
  execute_sql("SELECT ... FROM thread_state WHERE utid = ... AND ts BETWEEN ...")

Agent 调用:
  resolve_hypothesis({
    id: "h1",
    outcome: "rejected",
    evidence: "system_server 端 Binder 线程状态正常，响应耗时 <2ms，
              RenderThread 阻塞原因是 dequeueBuffer 等待 SurfaceFlinger"
  })

为什么有效？ 假设管理工具迫使 Agent 在行动之前明确声明「我在验证什么」和「我预期看到什么」。这有两个好处：

1. 防止目标漂移——Agent 不会在收集数据的过程中忘了自己最初想验证什么
2. 可审计——每个假设都有完整记录，Verifier 可以检查是否所有假设都被 resolved

机制 2：知识注入——不是写死引导，是按需加载领域知识

“针对 Binder 阻塞我们可能给 AI 一些常见的原因作为引导吗？”

是的，但不是写死在 Skill 中，而是通过 lookup_knowledge MCP 工具按需加载。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/次，前 4 次共 ~80 tokens），但效果显著。 之所以不是全程附加，是为了在分析后半段控制 token 开销——前几次 nudge 已经建立了「收到数据 → 先反思 → 再行动」的模式。没有这个 nudge，Agent 倾向于连续调用工具而不停下来思考——收集了 5 次数据但没有形成任何中间结论，最后的总结质量很差。

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

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

1. 先看总览 → 发现 47 帧卡顿，P90 = 23.5ms
   [确定性：invoke_skill("scrolling_analysis")]

2. 根据总览决定方向 → 40% 卡在 APP 阶段，优先看 App 侧
   [确定性：数据驱动，Strategy 文件建议]

3. 选代表帧深钻 → Frame #234 RenderThread 被 Binder 阻塞 23ms
   [确定性：invoke_skill("jank_frame_detail")]

--- 以下进入 AI 自主探索 ---

4. Agent 主动加载知识：lookup_knowledge("binder-ipc")
   → 获取 Binder 阻塞常见原因分类表
   [AI 决策 + 知识引导]

5. Agent 形成假设：submit_hypothesis("system_server Binder 响应慢")
   预期证据：server 端 thread_state 长时间 Sleeping/Runnable
   [AI 推理，假设工具强制外显]

6. Agent 验证：execute_sql("查 Binder 对端 thread_state")
   → 发现 system_server CPU 调度延迟，不是 Binder 响应慢
   [AI 自主工具调用]

7. [REFLECT] nudge 触发反思
   Agent: "假设 1 不成立，server 端 thread_state 显示 Runnable 排队，
          真正原因是 CPU 调度延迟"
   → resolve_hypothesis(outcome: "refined",
       evidence: "system_server CPU 调度延迟导致 Binder 线程排队")
   [AI 推理 + 知识模板中的排查路径]

8. Agent 深入：execute_sql("查 CPU frequency + thermal zone")
   → 发现热降频，CPU 大核被限频到 50%
   [AI 自主选择下一步深钻方向]

9. 综合结论：RenderThread Binder 阻塞 ← system_server CPU 调度延迟 ← 热降频
   [AI 归纳，形成 WHY 链]

--- Verifier 事后检查 ---

10. Verifier 启发式检查：
    - 文本模式匹配：结论中是否体现深钻分析（而非仅引用概览数据）
    - 假设闭环：所有 submit_hypothesis 是否都有对应的 resolve_hypothesis
    - 场景完整性：滑动分析是否包含帧/卡顿相关内容
    - 因果链启发式：是否有足够的因果连接词和机制性术语
    [确定性：启发式规则检查，非精确验证]

注意 Step 4-9 全部是 AI 自主探索，但受到三个约束：

• 假设工具迫使推理外显化（Step 5, 7）
• 知识注入提供领域排查路径（Step 4）
• REFLECT nudge在前几次工具返回后触发反思（Step 7）

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

1. 给数据，不给结论

Skill 应该返回结构化数据（帧耗时、线程状态分布、阻塞函数列表），而不是已经得出的结论（「RenderThread 阻塞是因为 Binder」）。让 AI 自己从数据中推理结论，比让它基于别人给的结论做进一步分析更可靠。

2. 给框架，不给路径

Strategy 文件应该定义「必须做什么」（Phase 1.9 必须深钻），而不是「怎么做」（先查 A 再查 B 再查 C）。Agent 在有框架约束的情况下自主选择路径，比在没有任何约束下自由探索要可靠得多，又比写死路径灵活得多。

3. 给知识，不给答案

知识模板应该包含「可能的原因分类和排查方法」，而不是「如果看到 X 就是 Y」。前者帮助 Agent 建立推理框架，后者把 Agent 变回 Workflow。

4. 验证行为，不验证结论

Verifier 应该用启发式规则检查「分析输出是否体现了关键动作」（结论中是否有深钻分析痕迹、假设是否都已 resolved、因果链是否有足够深度），而不是试图判断「结论是否正确」（这个你在离线评估中用 LLM Judge 做，不应该在运行时做）。注意这是文本模式匹配级别的启发式检查，不是精确的工具调用日志审计。

一句话总结

AI 自主探索的可靠性不是靠「写死引导」来保证的，而是靠三个机制：假设管理工具让推理外显化、按需知识注入提供领域排查框架、ReAct nudge 防止盲目工具调用。关键原则是「给数据不给结论、给框架不给路径、给知识不给答案」。

Q7：每一轮的 Prompt 是怎么拼接的？

提问背景： 大模型 Agent 的输出质量很大程度取决于 system prompt 的设计。SmartPerfetto 在每次分析时是如何构造 prompt 的？不同场景、不同轮次之间 prompt 有什么变化？token 预算怎么控制？

总体设计：四层分层拼接 + 缓存优化

SmartPerfetto 的 system prompt 不是一个静态字符串，而是由 buildSystemPrompt() 函数（claudeSystemPrompt.ts:260）在每次 SDK 查询前动态拼接的。拼接遵循一个核心原则：

按「稳定性」排序——越不容易变化的内容越靠前，越动态的内容越靠后。

这个设计的原因是 Anthropic API 的自动缓存机制：system prompt 超过 1024 tokens 时，API 会自动对 prompt 前缀做缓存。如果把不变的部分放在最前面，多轮对话中大部分 prompt 可以命中缓存，显著降低延迟和成本：

1
2
3

Same trace + same scene:     ~4000 tokens cached (~80% savings)
Same trace + different scene: ~800 tokens cached  (~18% savings)
Different trace:              ~400 tokens cached   (~8% savings)

四层拼接结构

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 轮, 可被丢弃)           │  │
│  │ → 各阶段 ✓/⊘/○ 状态 + 摘要                     │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘

模板加载与变量替换

所有 prompt 内容都在 Markdown 文件中定义（详见 Q1），TypeScript 只做加载和变量替换：

1
2
3
4
5
6
7
8
9
10
11

// strategyLoader.ts — 模板系统

// 1. 加载模板（DEV 模式跳过缓存，刷新浏览器即生效）
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 的内容

模板文件清单：

Token 预算管理

预算上限： 4500 tokens（MAX_PROMPT_TOKENS）。纠错重试时，如果检测到 SDK auto-compact（对话历史被自动压缩），会将预算降到 3000 tokens 以留出空间；否则复用原始 prompt。

Token 估算方法： 混合中英文估算——中文字符按 1.5 tokens/字，ASCII 按 0.3 tokens/字。这是粗略近似，但用于预算管理足够准确。

超预算时的渐进丢弃策略：

当拼接完成后 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 和分析笔记）

上下文构建的完整流程

在 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 缓存，同 trace 只检测一次）
Phase 2.5: 厂商检测（OEM 定制化，LRU 缓存）
Phase 2.8: 比较模式上下文（双 trace 模式）
Phase 2.9: 数据完整性探测（18 个维度，~50ms）
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() 做最终拼接。

Quick vs Full 双模式

不是所有查询都需要完整的 4500-token prompt。当用户问事实性问题（如「帧率是多少」）时，SmartPerfetto 使用精简的 quick prompt：

1
2
3
4

// buildQuickSystemPrompt() — ~1500 tokens
// 加载 prompt-quick.template.md
// 只注入 {{architectureContext}} 和 {{focusAppContext}}
// 无方法论、无场景策略、无对话上下文

多轮对话中 Prompt 的变化

在多轮分析中（用户追问或 drill-down），prompt 的变化取决于 SDK session 是否命中 resume：

第 1 轮： 无对话上下文、无历史计划、无分析笔记

第 2 轮起 — SDK session resume 命中（4 小时内）：

• SDK 内部已持有完整对话历史，不重复注入 previousFindings 和 conversationSummary
• 但仍注入：分析笔记（≤10 条）、实体上下文（drill-down 引用）、历史计划（≤3 轮）
• Tier 1-3 保持不变，命中 ~80% 缓存

第 2 轮起 — SDK session 过期或不可用：

• 手动注入上一轮的 findings 为「之前的分析发现」（≤10 条）
• 手动注入对话摘要（sessionContext.generatePromptContext(2000)，≤2000 tokens）
• 分析笔记、实体上下文、历史计划同上

纠错重试轮： 如果检测到 SDK auto-compact（对话历史被自动压缩），token 预算从 4500 降到 3000，渐进丢弃会更激进地移除非关键 section。如果没有发生 auto-compact，复用原始 system prompt。

一个具体例子：滑动分析的 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 轮相同（命中 ~80% 缓存）
[Tier 4] 对话上下文 (SDK 已持有对话历史，不重复注入 findings):
  - 分析笔记: "⚠️ [假设] 主要 jank 原因是 RenderThread Binder 阻塞"
  - 实体上下文: frame#3 的 ID 和时间范围
  - 历史计划: "✓ Phase 1 概览, ✓ Phase 1.9 深钻, ○ Phase 3 结论"
  (previousFindings 和 conversationSummary 由 SDK session 内部管理，不在 prompt 中重复)

预估: ~3400 tokens, 在预算内

一句话总结

Prompt 按「稳定性」四层排序（Static → Per-Trace → Per-Query → Dynamic），利用 API 前缀缓存实现多轮对话 ~80% token 节省。模板系统让领域专家可以直接编辑分析策略而不碰 TypeScript。超预算时按优先级渐进丢弃，但永远保留角色定义、场景策略和用户选区——这三者决定了分析的方向和范围。

Q8：SmartPerfetto 有哪些 Skill？

提问背景： SmartPerfetto 的分析能力由 YAML Skill 承载。完整的 Skill 清单可以帮助理解系统的分析覆盖范围。

总览

Atomic Skills（87 个）

单步数据提取和检测，是所有高层 Skill 的构建基础。

帧渲染与掉帧：

VSync 与刷新率：

CPU 与调度：

GPU：

主线程分析：

Binder IPC：

锁与同步：

启动专用（19 个）：

内存与 GC：

输入与触摸：

系统与设备：

其他：

Composite Skills（29 个）

组合多个 atomic skill，支持 iterator（逐帧/逐事件深钻）和 conditional（条件分支）。

Deep Skills（2 个）

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

Pipeline Skills（28 个）

渲染管线检测 + 教学。每个 pipeline skill 对应一种渲染架构，包含管线描述、关键线程、性能指标和优化建议。

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

Module Skills（18 个）

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

硬件层（5 个）：

框架层（6 个）：

内核层（4 个）：

应用层（3 个）：

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 深度分析

Agent 的典型调用路径（以滑动分析为例）：

1
2
3
4
5
6

invoke_skill("scrolling_analysis")          ← Composite，内部调用多个 Atomic
  → consumer_jank_detection                 ← Atomic，检测掉帧
  → 逐帧 iterator → jank_frame_detail      ← Composite，每帧深钻
    → main_thread_states_in_range           ← Atomic
    → binder_blocking_in_range              ← Atomic
    → frame_blocking_calls                  ← Atomic

关于我 && 博客

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

1. 博主个人介绍 ：里面有个人的微信和微信群链接。
2. 本博客内容导航 ：个人博客内容的一个导航。
3. 个人整理和搜集的优秀博客文章 - Android 性能优化必知必会 ：欢迎大家自荐和推荐 （微信私聊即可）
4. Android 性能优化知识星球 ： 欢迎加入，多谢支持～

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

这篇文章记录了 SmartPerfetto 从零到可用过程中的关键技术决策——为什么选这个方案而不是那个，哪些地方踩了坑，踩完之后怎么调整的。

为什么做这个工具

我做了多年 Android 性能优化。日常工作中大量时间花在 Perfetto trace 分析上——Perfetto 是 Google 开源的系统级 trace 工具，采集帧渲染、线程调度、CPU 频率、Binder 通信等数据，几乎是 Android 性能分析的标准工具。它的 trace_processor 引擎把 trace 加载到一个嵌入式 SQLite 数据库中，支持用 SQL 查询。

分析 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）： Perfetto 的 frame_timeline track 记录每帧渲染耗时。超过 VSync 周期（120Hz 下为 8.33ms）用户会感知卡顿。jank_type 字段区分掉帧类型：App 侧超时、SurfaceFlinger 合成延迟、Buffer Stuffing（BufferQueue 队列背压）等。

路径 A：手动分析

1
2
3
4
5
6
7
8
9
10

1. 打开 Perfetto UI，拖动时间轴找到滑动区间
2. 展开 frame_timeline track，逐帧检查哪些超过 VSync 周期
3. 18 帧掉帧——逐帧点开，展开 thread_state 切片，查看主线程在做什么
4. 帧 1：Sleeping，手动查 waker_utid → system_server（Android 系统核心进程，托管 AMS/WMS 等系统服务）Binder 回来慢
   帧 2：Running，但在 Choreographer#doFrame 里卡了 → RecyclerView onBind 过重
   帧 3：Sleeping + Running 交替 → dequeueBuffer 等 SurfaceFlinger 合成
   ... (还有 15 帧需要逐一检查)
5. 关联 CPU 频率 track，确认是否有热降频或 governor 升频延迟
6. 检查是否有 GC pause、Lock contention、Binder 超时
7. 汇总证据，组织结论

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

用户输入 "分析滑动性能"，以下是 Agent 实际执行的操作（来自 session log session_agent-1774679540422）：

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

classifyScene("分析滑动性能") → scrolling  (<1ms, 关键词匹配)
buildSystemPrompt() → 4500 tokens (scrolling.strategy.md 注入)

submit_plan({
  phases: ["p0: 架构+时间范围", "p1: 滑动概览+掉帧列表",
           "p1_9: 根因深钻", "p3: 综合结论"],
  successCriteria: "WHY 链 ≥2 级，可操作优化建议"
})

invoke_skill("scrolling_analysis", {process_name: "com.example..."})
  → 18 帧掉帧全部提取，每帧附带:
    - 耗时、jank_type、reason_code (App/SF/GPU)
    - 主线程状态分布 (Running/Sleeping/IO)
    - 阻塞函数 top-3
  → ArtifactStore: art_1 (~440 tokens 引用)

fetch_artifact("art_1", "rows", 0, 18)  → 获取全部 18 帧的结构化数据
invoke_skill("frame_blocking_calls", {frame_ids: [3, 7, 12]})
  → 3 帧代表帧的阻塞链: dequeueBuffer / Binder / GC
lookup_knowledge("rendering-pipeline")  → 加载渲染管线参考资料

输出结论:
  [HIGH] 惯性滑动阶段 18 帧卡顿，3 次 Full 级 ~60ms 掉帧
  [MEDIUM] 14 帧 Buffer Stuffing (App 按时完成渲染，但 BufferQueue 满导致呈现延迟)
  [MEDIUM] Vulkan Shader 首帧编译 + CPU 冷频 (18.66ms, 超预算 2.2×)

Metrics 快照 (来自 logs/metrics/)：16 次工具调用，0 次失败，SQL 平均 652ms。

下图展示了一次完整分析的请求生命周期——从用户输入到最终结论的每一步：

两条路径的分析步骤相同——查帧数据 → 定位 jank → 追踪阻塞链 → 关联系统状态 → 归纳结论。

差异在于：手动分析逐帧串行，每帧需要手动展开和追踪；Agent 通过 scrolling_analysis Skill 用一条 SQL 批量获取全部 18 帧的结构化数据，再选代表帧深钻阻塞链。

Agent 的分析结果同时落地到 Perfetto UI 上：

• Auto-Pin：Agent 提到的关键帧和 Slice 自动标记在时间线上
• 点击跳转：结论中的时间戳和帧 ID 支持点击跳转到 Perfetto 对应位置
• 数据表格：18 帧的完整性能数据以结构化格式渲染为可排序、可筛选的表格

运行截图：以 SmartPerfetto 前端以 Perfetto 插件的形式存在

运行截图：滑动分析的时候详细分析每一个掉帧的地方， 点击最左边那个剪头可以展开

运行截图：滑动分析结论

运行截图：滑动分析结论，代表帧分析

运行截图：滑动分析结论，代表帧分析

运行截图：每一轮分析都有单独的分析 report，内容与前端显示的一致（更详细一些）

分析结论、数据表格和 Perfetto 时间线在同一个界面上。Agent 完成批量数据收集和初步归因后，工程师在 Perfetto UI 上确认关键发现。

需要说明的是，当前 Agent 在复杂边界情况下仍然需要人的判断（后文会具体讨论误诊问题）。这篇文章记录的是构建这个 Agent 背后的工程决策过程。

第一部分：为什么 LLM 不能直接分析 Trace？

在开始讨论架构之前，需要先回答一个根本问题：为什么不能直接把 trace 数据发给 LLM 让它分析？这个问题的答案决定了 SmartPerfetto 整个架构的出发点。

数据规模：trace 文件装不进上下文

一个实际的 Perfetto trace 的数据规模是这样的：

两者差了好几个数量级。即使是一个较小的 50MB trace，里面的 slice（函数调用记录）、counter（CPU 频率采样点）、thread_state（线程调度状态）等数据序列化后也远超 LLM 的上下文容量。

这就意味着 LLM 不可能直接「看到」trace 数据。它必须通过工具按需查询——先用 SQL 找到需要的数据子集（比如某个时间范围内某个线程的状态分布），拿到查询结果后再做分析。这个约束从根本上决定了 SmartPerfetto 必须是一个 工具驱动 的 Agent 架构，而不是把数据喂进 prompt 的简单方案。

精确计算：LLM 不擅长处理数值

性能分析的日常工作围绕精确数值展开：帧耗时的 P50 / P90 / P99 分位数、VSync 周期检测（需要对 VSYNC-sf 间隔取中位数并吸附到标准刷新率）、CPU 利用率的百分比计算、各线程状态的时间占比。

LLM 处理这类数值计算时经常出错。一个实际例子：早期测试中，Claude 把 16.7ms 的帧耗时判断为「正常，未超过 VSync 周期」——它按 60Hz（16.67ms）的帧预算来算了。但这个 trace 采集自一台 120Hz 设备，单帧预算应该是 8.33ms，16.7ms 实际上超预算了一倍。这类错误看起来很小，但在性能分析中会导致完全相反的结论。

数值计算必须由工具完成——SQL 的 AVG()、PERCENTILE() 和 YAML Skill 中预定义的统计逻辑，保证每次计算结果一致且精确。

领域知识：LLM 知道但不会用

Android 的渲染管线复杂度是很多开发者没有预期到的。最常见的三种渲染路径是：标准 HWUI 管线（HWUI 是 Android 默认的硬件加速渲染引擎，应用的 View 绘制指令在主线程生成，由 RenderThread 提交给 GPU，最终经 SurfaceFlinger 合成到屏幕）、Flutter 的双线程模型（1.ui → 1.raster，不走 RenderThread）、以及 WebView 的 Chromium 管线（CrRendererMain 线程负责渲染）。除此之外还有 Jetpack Compose、游戏引擎、相机管线等。SmartPerfetto 的架构检测系统目前识别 24+ 种渲染管线，不同管线的 jank 分析需要查看不同的线程和指标——这也是为什么架构检测是分析的第一步。

卡顿的根因可能跨线程（主线程阻塞 → 原因在 RenderThread）、跨进程（App 等待 → system_server 的 WindowManagerService 响应慢）、甚至跨硬件层（CPU 调度到小核 → 算力不足 → 帧超时）。

LLM 的训练数据中包含这些概念——它「知道」什么是 RenderThread，什么是 Binder，什么是 SurfaceFlinger。但面对一个具体的 trace，它缺乏将这些知识按场景分阶段运用的能力。比如分析滑动卡顿时，需要先检查帧级数据（哪些帧掉了、掉帧类型是什么），再针对占比最高的根因类型选择不同的深钻路径（App 侧阻塞走 blocking_chain_analysis，合成端延迟走 SurfaceFlinger 分析）。这种分步骤、有条件分支的分析流程，需要通过策略注入来引导。

可靠性：错误率在实际运行中偏高

即使解决了数据访问问题，直接让 LLM 产出性能分析结论仍然面临可靠性问题。在 SmartPerfetto 的实际运行中，我观察到几类典型的输出问题：

• 幻觉：生成 trace 中不存在的数据或指标
• 遗漏：漏掉关键检查项（比如分析启动性能时不检查 JIT 编译和类加载的影响）
• 浅层归因：停在「主线程忙」的层面，不继续追踪是忙在 futex（锁竞争）、binder_wait（跨进程等待）还是 GC pause
• 结论不一致：同一份 trace 分析两次，得到不同的严重等级判定

后文第二部分会详细讨论这个问题——agentv3 上线 18 天后的质量审查显示，约 30% 的 Agent 结论包含不同程度的误判。

SmartPerfetto 的分工设计

基于这四个问题，SmartPerfetto 的架构按以下方式分工：

1
2
3
4
5
6
7
8
9
10
11

LLM (Claude) 负责:              工具系统负责:
├─ 理解用户意图                  ├─ SQL 精确查询 (trace_processor)
├─ 制定分析计划                  ├─ 数值计算与统计 (Skill 内置)
├─ 推理因果关系                  ├─ 渲染架构检测 (24+ 管线)
├─ 跨领域关联分析                ├─ 分层数据提取 (L1-L4)
├─ 生成结构化结论                ├─ Perfetto stdlib 查询
└─ 自然语言交互                  └─ 数据摘要与压缩 (Artifact Store)

连接层: MCP Protocol — 最多 20 个工具 (9 常驻 + 11 条件)
策略层: 12 套场景策略 (.strategy.md)
质量层: 3 层验证 + SQL 纠错学习

LLM 做推理和表达，工具做查询和计算。连接两者的是 MCP（Model Context Protocol，Anthropic 提出的工具调用协议）——Claude 通过标准 MCP 接口调用 trace_processor 执行 SQL、调用 YAML Skill 做结构化分析、查询 Perfetto stdlib 模块。分析结果通过 SSE（Server-Sent Events）实时推送到 Perfetto UI 前端。

支撑这个分工的工程基础设施包括：场景路由（根据用户问题注入不同的分析策略）、数据压缩（控制返回给 LLM 的数据量）、质量验证（拦截 LLM 的领域误判）。后面几个部分展开讨论每个部分的设计过程。

下图是完整的系统架构，展示了从用户请求到分析结论的 4 个阶段：

第二部分：从 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
2
3
4
5
6
7

1. 先看总览 → 发现 47 帧卡顿，P90 = 23.5ms
2. 根据总览决定方向 → 40% 卡在 APP 阶段，优先看 APP 侧
3. 选代表帧深钻 → Frame #234 的 RenderThread 被 Binder 阻塞 23ms
4. 形成假设 → "可能是 system_server 的 Binder 响应慢"
5. 验证假设 → 查 Binder 对端的 thread_state，发现 system_server CPU 调度延迟
6. 假设如果不成立 → 回退，换方向（比如改查 GPU 或 GC）
7. 综合所有发现，形成结论

每一步决策都依赖前一步的结果——无法在分析开始前就确定所有步骤。Pipeline 无法处理「这个 trace 的问题可能在 GPU，也可能在 GC，需要根据中间数据动态选择下钻方向」这种需求。

SmartPerfetto 的设计是确定性和灵活性的混合：已知场景（滑动、启动、ANR 等）用 Strategy 文件约束必检项，保证不遗漏；但每个阶段内的具体查询和深钻方向由 Claude 自主决定。未匹配的场景则完全交给 Claude 自主探索。

agentv2：一个典型的 Workflow

agentv2 使用 DeepSeek 作为后端，采用 Governance Pipeline 架构——通过 planner / executor / synthesizer 三阶段编排，本质上是预定义的多步骤工作流（历史 commit 6d80aefb: “Replace the 13-step agentv2 governance pipeline with Claude-as-orchestrator”）。

这个架构在标准 Android 应用的滑动分析上工作得不错，但遇到非标准情况就出问题了。比如 Flutter 应用的 trace 里没有标准的 frame_timeline 数据，管线拿到空结果后继续执行后续步骤，最终输出基于空数据的结论。

agentv3：迁移到 Agent 架构

2026 年 3 月 2 日（commit 6d80aefb），我切换到 Claude Agent SDK。Claude 接收工具定义和策略后，自主决定调用什么工具、按什么顺序、查什么数据。

一个 AI Agent 通常具备以下特征，agentv3 的实现对照如下：

1
2

agentv2 (Workflow): 固定管线 → 每步预定义 → 意外数据 = 错误结论
agentv3 (Agent):    动态计划 → 自主调用工具 → 意外数据 = 调整计划

迁移后的 9 轮审查

从 3 月 2 日到 3 月 20 日，经历了 9 轮架构审查。其中影响最大的几轮：

冷启动 4 层联动 Bug

2026 年 3 月 19 日（commit d5a1d7b3），发现冷启动被错误分类为热启动。追踪后发现这是一个跨 4 层的联动问题：

1
2
3
4

Layer A (Perfetto Stdlib): bindApplication 的 ts 比 launchingActivity 早 ~98ms → 被过滤器排除
Layer B (Skill 逻辑):      startup_events_in_range 的时间过滤与 Layer A 不兼容
Layer C (10 个下游 Skill):  冗余的 startup_type 过滤条件 → 重分类后返回 0 行
Layer D (质量门禁):         startup_analysis 的过滤规则和重分类逻辑不同步

修复规模：重写 10 个下游 Skill，新增 4 个启动分析 Skill。这个问题说明在 Skill 依赖链中，上游的一个字段语义错误会逐层放大。

Ghost MCP Query — 异步生命周期错配

2026 年 4 月 7 日（commit a0ad63ba）抓到的另一类跨层 Bug：分析超时之后，session 已经清理、SSE 流已经收尾，但 trace_processor 的 stderr 仍然在 90 秒后陆续吐出 no such table: cpu_frequency_counters / no such column: ts 这类错误——孤儿日志，没有 owner 可以归因到任何 session，前面错误 4 的两条纠错对就是从这堆 stderr 里反查出来的。

根因在 SDK Query 的异步生命周期：

1
2
3
4
5
6

Layer A (Claude Agent SDK):    SDK 内部的 AsyncIterator 还在生产 message
Layer B (claudeRuntime.ts):    timeout 触发，break 出 for-await 循环
Layer C (MCP 工具队列):         SDK 子进程没收到任何关闭信号，
                                把队列里剩下的 invoke_skill / execute_sql 继续派发
Layer D (trace_processor):     执行这些"幽灵查询"，错误也照常返回——
                                但此时 session 已经清理，没人在听

AsyncGenerator.return() 和 break 只对消费侧生效，不会反向通知生产侧的外部资源（SDK 子进程 + MCP 工具执行队列）。修法是把 sdkQueryWithRetry 的返回类型从单个 AsyncIterable 改成 { stream, close } 二元组，timeout / 异常 / finally 三个路径都显式调一次 close()，让 SDK 主动 abort 子进程：

1
2
3
4
5
6
7
8
9

// claudeRuntime.ts
const { stream, close } = sdkQueryWithRetry({ ... });
const timer = setTimeout(() => { close(); /* abort SDK 子进程 */ }, AGENT_TIMEOUT);
try {
  for await (const message of stream) { ... }
} finally {
  clearTimeout(timer);
  close();   // 即使正常退出也兜底关一次
}

这个 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 套策略同时出现时 LLM 无法区分上下文。

解决方式是做场景分类，每次只注入一套策略：

1
2
3
4
5
6
7
8
9
10
11
12
13

// sceneClassifier.ts — 12 场景, <1ms 执行
export function classifyScene(query: string): SceneType {
  const scenes = getRegisteredScenes(); // 从 .strategy.md frontmatter 加载
  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) {
    if (scene.compound_patterns.some(p => p.test(query))) return scene.scene;
    if (scene.keywords.some(k => lower.includes(k))) return scene.scene;
  }
  return 'general';
}

关键词和优先级声明在每个 .strategy.md 的 YAML frontmatter 中，不硬编码在代码里：

1
2
3
4
5
6
7
8

# scrolling.strategy.md
---
scene: scrolling
priority: 3
keywords: [滑动, 掉帧, jank, scroll, fps, 帧率, 卡顿]
compound_patterns:
  - "(?:分析|看看|检查).*(?:滑动|滚动|列表)"
---

添加新场景只需新建一个 .strategy.md 文件。DEV 模式下支持热加载，修改后刷新浏览器即可生效。

调整之后 System Prompt 从 ~15000 tokens 降到 ~4500 tokens，策略混淆的问题没有再出现。新增场景也从改代码变成了新建一个 .md 文件。

当多轮对话积累了较多上下文（分析笔记、历史计划、模式记忆等），System Prompt 可能重新超过 4500 token 预算。这时按优先级逐个丢弃低价值段落：SQL 知识库参考（Claude 可以用 lookup_sql_schema 工具按需查询）→ 历史分析经验 → 历史踩坑记录 → SQL 纠错对 → 子代理协作指引 → 历史分析计划。核心段落（角色、方法论、场景策略、输出格式）不会被丢弃。

决策 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
2
3
4
5
6
7

invoke_skill("scrolling_analysis") 执行结果:
  ├── 前端: 全量 DataEnvelope (200 行) → SSE → UI 表格渲染
  │         (DataEnvelope: 自描述的数据合约，包含列名、类型、交互动作，
  │          前端根据 schema 自动渲染表格/图表，不需要针对每个 Skill 写代码)
  └── Claude: 紧凑引用 (~440 tokens)
              "scrolling_analysis 完成. 概要: 347 帧, jank 率 10.6%
               art_1 (详情: fetch_artifact('art_1', 'rows', 0, 20))"

fetch_artifact 的三个粒度：

调整后每个 Skill 的 token 成本从 ~3000 降到 ~440，8 个 Skill 从 ~24000 降到 ~3520 tokens。Claude 的输出从逐行描述变成了模式归纳，前端仍然能拿到完整数据做表格渲染。

决策 3：三层验证 — 从真实误判中学到的

agentv3 上线 18 天后，我做了一次系统性的质量审查（2026 年 3 月 20 日，commit da63eaf9）。统计结果让我意外：约 30% 的 Agent 结论包含不同程度的误判。

以下是实际遇到的误判案例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

[案例 1] Agent 将 VSync 对齐偏移标记为 CRITICAL
实际情况: 现代高刷设备（90Hz/120Hz/144Hz）的 VSync 间隔本身就不是完全固定的，
存在正常的微小偏移（±0.5ms 量级）。Agent 把这种正常偏移当成了异常

[案例 2] Agent 将 Buffer Stuffing 帧计入掉帧统计
实际情况: Buffer Stuffing 表示 App 按时完成了渲染，但 BufferQueue 队列满导致
生产侧背压。这不是 App 逻辑问题，不应直接算作 App 侧掉帧。
SmartPerfetto 通过双信号检测处理：默认排除，但如果实际呈现间隔 > 1.5x VSync
则仍计入感知掉帧

[案例 3] Agent 将单帧耗时异常标记为 CRITICAL
实际情况: 孤立的单帧异常不构成模式，需要确认是否重复出现

[案例 4] Agent 将主线程 Sleeping 占 35% (469ms) 标记为 MEDIUM
实际情况: 在启动总时长中，469ms 的主线程睡眠占比已经很高，应标记为 HIGH

这些误判有一个共同特点：它们不是逻辑错误，而是 领域经验的缺失。高刷设备上 VSync 微小偏移是正常的、Buffer Stuffing 的延迟发生在管线队列层面而非 App 逻辑、单帧异常不构成模式——这些判断依赖对 Android 图形栈的深入理解，Claude 的训练数据对这些细节覆盖不足。

认识到这一点后，我建立了三层递进验证：

1
2
3
4
5
6
7
8

Layer 1: 启发式检查 (无 LLM 调用)
  — 正则匹配已知误判模式（VSync 偏移标 CRITICAL、Buffer Stuffing 算掉帧、单帧标 CRITICAL）

Layer 2: Plan 遵从检查 (无 LLM 调用)
  — 对照 submit_plan 的步骤，检查结论是否覆盖了所有计划阶段

Layer 3: 独立模型审查 (使用 Haiku)
  — 用不同模型检查每个发现是否有数据证据支持，因果链是否完整

验证发现严重问题时，生成 Correction Prompt 让 Claude 修正结论（最多 2 轮）。

跨会话学习： 确认的误判模式被持久化到 logs/learned_misdiagnosis_patterns.json，下次分析时自动注入 System Prompt。例如系统学到了：

1
2
3
4
5
6

{
  "keywords": ["R008", "TTID", "超出", "LOW"],
  "message": "TTID 超出标记为 LOW，但 TTID(1912ms) 超出 dur_ms(1338ms) 43%，
              应标记为 MEDIUM 或更高",
  "occurrences": 1
}

注：学习到的误判模式不会立即生效。代码中要求 occurrences >= 2 才会进入有效模式集——首次记录只是标记，同一模式第二次出现时才会注入到后续分析的 System Prompt 中，避免孤立事件造成过度矫正。

第四部分：为什么不用标准的 Skill 系统？

从 SOP 到 YAML Skill 的设计选择

做性能分析的团队一般都有自己的 SOP（标准操作流程）：滑动卡顿怎么查、启动慢怎么分析、ANR 怎么定位。SOP 通常是一份文档或检查清单，有经验的工程师照着做，新人跟着学。

Anthropic 的 Claude Code 有一套 Skills 系统，本质上是参数化的 Prompt 模板——注入上下文后提交给 Agent 执行。一个自然的想法是把性能分析 SOP 写成这种 Prompt 模板，让 Claude 按 SOP 执行。

我一开始也走了这条路。给 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 采用了不同的思路——不是 Prompt 模板，而是声明式的 SQL 执行单元：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# YAML Skill: SQL 预定义，结果格式固定
steps:
  - id: thread_state_distribution
    type: atomic
    sql: |
      SELECT state, SUM(dur) as total_dur,
             ROUND(SUM(dur) * 100.0 / SUM(SUM(dur)) OVER(), 2) as pct
      FROM thread_state ts
      JOIN thread_track tt ON ts.track_id = tt.id
      WHERE tt.utid = ${main_thread_utid}
        AND ts.ts BETWEEN ${frame_start} AND ${frame_end}
      GROUP BY state ORDER BY total_dur DESC
    display:
      level: detail
      columns:
        - { name: state, type: string }
        - { name: total_dur, type: duration }
        - { name: pct, type: percentage }

两种方式的核心区别在于「谁来写 SQL」。Prompt 模板让 LLM 每次动态生成 SQL，结果格式不可预测，无法做回归测试；YAML Skill 预定义了 SQL 和输出 schema，参数替换后执行，结果格式固定，可以稳定地回归测试和前端渲染。

最终的分工是：Claude 负责理解意图、选择 Skill、推理归因；YAML Skill 负责精确的 SQL 查询和结构化输出。Claude 通过 invoke_skill 调用 Skill，Skill 返回结构化数据，Claude 基于数据做判断。

为什么不把每个 Skill 暴露为独立的 MCP Tool？

一个自然的问题是：为什么不直接把 87 个 atomic 分析能力注册为 87 个 MCP Tool，让 Claude 直接调用？

实际试过会发现一个问题：MCP 的 tool list 会随着工具数量线性增长。87 个工具意味着每次 API 调用都要在请求中附带 87 个工具的描述（名称、参数 schema、使用说明），这个固定开销会占据大量 token。更重要的是，当 Claude 面对 87 个工具时，它的选择准确率会下降——工具太多，它不知道该用哪个。

SmartPerfetto 的设计是 Claude 只看到 2 个和 Skill 相关的 MCP Tool：

• invoke_skill(skillId, params) — 执行指定的 Skill
• list_skills(category?) — 按场景类别查询可用的 Skill 列表

通过 list_skills(category="scrolling") 按需发现能力，再用 invoke_skill 调用。2 个 MCP Tool 封装了 160+ 个分析能力，工具列表的 token 开销是固定的。

另一个好处是 YAML 格式降低了贡献门槛。性能分析专家如果对某个分析场景有经验，可以直接写 YAML Skill 定义 SQL 查询和输出格式，不需要懂 TypeScript 或修改后端代码。修改后在开发模式下刷新浏览器即可生效（热加载），迭代周期在秒级。

Skill 系统的结构

Skill 数量从项目初期的十几个增长到现在的 164 个，增长的驱动力不是「尽可能多」，而是分析实践中不断遇到新的场景需要覆盖——比如最初只有标准 HWUI 的帧分析，后来遇到 Flutter 应用需要专门的 Skill，再遇到厂商差异需要 override，再遇到启动分析中 JIT、class loading、Binder pool 各自需要独立的检测逻辑。

当前的 Skill 按类型分布如下：

另有 skills/vendors/ 下 8 个厂商的 .override.yaml（Pixel / Samsung / Xiaomi / Honor / OPPO / Vivo / Qualcomm / MTK），覆盖通用 Skill 中的厂商特定 SQL。

分层结果

早期 Skill 的输出是平铺的——一个 Skill 返回一张大表，200 行帧数据混在一起，用户打开就看到全量数据，没有层次感。实际使用中发现工程师的阅读习惯是：先看概要（掉帧率多少、P90 多少），再决定要不要展开看详情，再针对具体帧深钻。

现在 Skill 的输出按层级组织，前端渐进式渲染：

1
2
3
4
5
6
7
8
9
10
11

summary  — "47 帧卡顿, P90=23.5ms, SEVERE 占 12%"
  │            聚合指标，快速了解全貌
  ▼
key      — 关键数据（最重要的指标和发现）
  │            高亮展示
  ▼
detail   — 完整的数据列表 (frame_id, duration, jank_type)
  │            可展开的数据表格
  ▼
hidden   — 辅助数据（中间计算结果，默认折叠）
               按需展开查看

Skill 的每个 step 通过 display.level 声明自己的展示层级（实际使用最多的是 detail — 240 处、key — 170 处、summary — 81 处）。前端根据 DataEnvelope 中的列类型（timestamp、duration、percentage、bytes 等）和交互动作（navigate_timeline 跳转到 trace 位置、navigate_range 选中时间范围、copy 复制数据）自动渲染表格和图表——新增一个 Skill，前端不需要写额外的代码。这是 164 个 Skill 而前端代码量仍然可控的关键。

Step 类型

最初所有 Skill 都只有一种 step：执行一条 SQL。后来遇到需要组合多个 Skill 的场景（比如 scrolling_analysis 需要先查帧数据，再对每个 jank 帧做阻塞分析），以及需要遍历数据行的场景（逐帧诊断），逐步扩展了 step 类型：

iterator 是逐帧分析的核心——比如对 18 个 jank 帧中最严重的 8 个，逐一执行 blocking_chain_analysis，每帧独立分析阻塞原因。parallel 和 conditional 在类型系统中已定义，目前还没有 Skill 使用——这是因为当前的分析场景用 skill 引用 + iterator 遍历已经能覆盖，后续引入更复杂的场景（如多路并行数据采集）时会用到。

领域 Skill 举例

以下几个例子说明为什么需要这么多专用 Skill——每个 Skill 背后都有一个「通用方案处理不了」的具体问题。

Consumer Jank Detection — 框架标记 ≠ 用户感知

框架的 jank_type 标记不等于用户感知的掉帧。存在 Hidden Jank——框架标记 jank_type='None' 但用户感知到卡。原因是框架的判定口径和用户的实际感知之间存在差异。

SmartPerfetto 用独立的 consumer_jank_detection Skill 做掉帧判定：通过 VSYNC-sf 间隔的中位数估算实际 VSync 周期，再用 1.5 倍 VSync 周期作为阈值，基于相邻帧的 present_ts 差值（帧实际显示到屏幕的时间戳）判断是否掉帧。不依赖框架标记。

阻塞链分析 — 跨线程、跨进程的根因追踪

一帧掉帧的根因可能涉及多层因果链：

1
2
3
4
5

帧 42 耗时 62ms (预算 8.33ms)
  └→ 主线程被阻塞 35ms
      └→ 阻塞在 futex_wait (锁竞争)
          └→ 锁持有者是 Binder 线程
              └→ Binder 线程在等 system_server 响应

blocking_chain_analysis Skill 用 3 步 SQL 提供这条链的关键线索：主线程状态分布（Running / Sleeping / IO 各占多少）→ 唤醒者追踪（通过 waker_utid 找到是谁唤醒了主线程）→ 阻塞函数汇总（futex / binder_wait / io_schedule 各累计多少时间）。这种跨层分析用通用 Prompt 让 Claude 自己写 SQL 很难稳定实现。

Flutter 架构分支 — 不同渲染模式需要不同分析逻辑

Flutter 的两种渲染模式涉及不同的线程，分析时需要看不同的目标：

如果用标准 HWUI 的分析逻辑去分析 Flutter SurfaceView 应用，会把 1.raster 线程的耗时错误归因到 RenderThread。SmartPerfetto 通过架构检测（24+ 种渲染管线）自动识别 Flutter 应用并切换到专用的 flutter_scrolling_analysis Skill。

但「自动识别 Flutter」本身也踩了坑（commit 355df8ee，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 吸收）上。

修法不是调权重，而是给特化 pipeline 加 exclude_if：TEXTUREVIEW 一旦看到 Flutter 1.ui / 1.raster 信号就直接屏蔽 STANDARD 分类；STANDARD_LEGACY/MIXED/SURFACEVIEW_BLAST 看到 Game Engine 信号就互斥；OPENGL_ES 看到 WebView/Game 信号就互斥。24+ 种 pipeline 不能各打各的分，需要一个「特化 → 通用」的优先级链。 这是「pipeline 多了之后必须做相互排斥」的典型例子——也是为什么 Skill 数量增长到 160+ 之后，光「正确路由到哪个 Skill」本身就成了独立的工程问题。

厂商覆写 — 同一指标在不同平台上的字段名不同

高通、联发科、Google Tensor 的 trace 中，相同指标的字段名不同（比如 GPU 频率在高通叫 gpufreq，联发科可能叫 gpu_freq_khz）。.override.yaml 让同一个 Skill 在不同平台上自动适配 SQL，不需要为每个厂商写独立 Skill。

第五部分：SQL 工程

前面讨论的 Skill 系统最终都落到 SQL 查询上——每个 Skill 的 step 执行的是预定义的 SQL。SQL 是 SmartPerfetto 的核心——所有性能数据的获取最终都通过 SQL 查询 trace_processor 完成。这部分展开讨论 SQL 层面的几个工程问题：查询模式设计、官方 stdlib 复用、Schema 索引、结果压缩和纠错学习。

SQL 查询模式：时间区间 JOIN 和递归分桶

Perfetto trace 的数据本质上是带时间戳和持续时长的事件流。性能分析中最常见的操作是判断两个事件在时间上是否重叠——比如某帧渲染期间，主线程有没有被 Binder 调用阻塞。

YAML Skill 中大量使用的核心 SQL 模式是时间区间 JOIN——判断两个事件是否在时间上重叠。下面这条 SQL 的业务含义是：对于每个掉帧，找出在这帧渲染期间同时发生的阻塞调用（如 GC、Binder、锁），并计算它们重叠了多少毫秒：

1
2
3
4
5
6
7
8
9
10
11

-- 业务含义：掉帧帧和阻塞调用的时间重叠分析
SELECT
  jf.frame_id,
  b.name as blocking_call,
  -- 计算精确的重叠时长（纳秒级）
  ROUND((MIN(b.ts + b.dur, jf.ts + jf.dur) - MAX(b.ts, jf.ts)) / 1e6, 2) as overlap_ms
FROM jank_frames jf
JOIN blocking_calls b
  ON b.ts < jf.ts + jf.dur       -- 阻塞调用的开始 < 帧的结束
  AND b.ts + b.dur > jf.ts       -- 阻塞调用的结束 > 帧的开始
HAVING overlap_ms > 0.5           -- 过滤掉不足 0.5ms 的微小重叠

这里的 MIN(end1, end2) - MAX(start1, start2) 是计算两个区间重叠长度的标准公式。在 Perfetto trace 中，时间戳精度到纳秒，这种区间 JOIN 能精确到 0.001ms 的粒度。

另一个常用模式是递归 CTE 做时间分桶。比如分析启动过程中 CPU 大核/小核的使用分布变化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

-- 递归生成时间桶（最多 30 个，防止递归失控）
WITH RECURSIVE buckets AS (
  SELECT 0 as idx, ${start_ts} as bucket_start,
         MIN(${start_ts} + bucket_ns, ${end_ts}) as bucket_end
  UNION ALL
  SELECT idx + 1, bucket_end, MIN(bucket_end + bucket_ns, ${end_ts})
  FROM buckets WHERE bucket_end < ${end_ts} AND idx < 29
)
-- 每个时间桶内，统计大核 vs 小核的调度时间
SELECT
  ROUND(SUM(CASE WHEN core_type IN ('prime','big','medium')
    THEN overlap_dur ELSE 0 END) / 1e6, 2) as big_core_ms,
  ROUND(SUM(CASE WHEN core_type = 'little'
    THEN overlap_dur ELSE 0 END) / 1e6, 2) as little_core_ms
FROM buckets b
LEFT JOIN main_thread_sched ms ON ms.ts < b.bucket_end AND ms.ts + ms.dur > b.bucket_start
GROUP BY b.idx

_cpu_topology 是 Perfetto stdlib 提供的视图，把 CPU 核心分类为 prime / big / medium / little。递归 CTE 限制最多 30 个桶，防止在极长 trace 上递归失控。

这些 SQL 模式被封装在 YAML Skill 中，通过 ${param|default} 语法接受参数。Claude 不需要自己写这些复杂的时间区间 JOIN——它调用 invoke_skill 传入时间范围和进程名，Skill 负责执行预定义的 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，后续 Skill 查询零开销

• 回退到 lazy 加载 (4/1, commit 0afeb60f)： 22 模块的 eager preload 在生产中翻车了——200MB+ 的大 trace 上，启动时并发 INCLUDE 22 个模块会同时占用 trace_processor_shell 的 RPC 连接，触发 socket hang up。根因是 trace_processor_shell 是单线程的 SQLite 引擎，最不擅长并发 INCLUDE 这种「批量 schema mutation」负载。 最终的修法是把 eager preload 收回，只保留 3 个 Tier-0 模块，且改成首次 query 时 lazy + 串行加载 + 最多 3 次重试：

  1 2 3 4 5 6 7

  // workingTraceProcessor.ts // Tier 0: absolute minimum stdlib modules needed for any analysis to start. const CRITICAL_STDLIB_MODULES = [ 'android.frames.timeline', // 19 个 skill 引用 — frame/jank 基础 'android.startup.startups', // 16 个 skill 引用 — startup 基础 'android.binder', // 22 个 skill 引用 — IPC/blocking 基础 ];

  这 3 个是按「skill 引用次数」筛出来的最高频依赖。其余 stdlib 模块改由 Skill YAML 的 prerequisites 段或 SQL 里显式的 INCLUDE PERFETTO MODULE 在第一次用到时按需声明

• 按需发现： perfettoStdlibScanner.ts 扫描 Perfetto 源码目录自动发现所有可用模块，通过 list_stdlib_modules MCP 工具让 Claude 按需 INCLUDE 非预加载的模块

1
2
3
4
5

// perfettoStdlibScanner.ts — 扫描 perfetto/src/trace_processor/perfetto_sql/stdlib/
function scanDirectory(dir: string, prefix: string): string[] {
  // 递归扫描 .sql 文件，转换为模块路径格式 (如 "android.frames")
  // 排除 prelude 目录（这些是自动加载的，不需要手动 INCLUDE）
}

这次回退的教训和文章前面的「数据越多 Claude 输出反而越差」是同一类的——「在系统启动时把所有可能用到的资源都准备好」是直觉上最优、实际上最差的策略。无论是给 LLM 的上下文还是给 trace_processor 的 stdlib，先 lazy + 按需加载，等真正出现性能瓶颈再考虑预热，几乎总是更稳的选择。

另一个独立的教训是：使用 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 纠错那一节会展开讲。

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

-- 200 行原始结果 (~3000 tokens) 压缩为:
{
  "totalRows": 200,
  "columnStats": [
    { "column": "dur_ms", "type": "numeric",
      "min": 2.1, "max": 67.3, "avg": 12.8,
      "p50": 9.2, "p90": 23.5, "p95": 35.1, "p99": 62.0 },
    { "column": "jank_type", "type": "string",
      "topValues": [
        { "value": "App Deadline Missed", "count": 87 },
        { "value": "Buffer Stuffing", "count": 45 },
        { "value": "None", "count": 68 }
      ] }
  ],
  "sampleRows": [ /* 10 行最严重的帧数据 */ ]
}
// ~500 tokens，压缩率 ~85%

这和前面提到的 Artifact Store 配合使用——Artifact Store 压缩的是 Skill 结果（invoke_skill 返回的数据），SQL Summarizer 压缩的是 Claude 直接执行 SQL 时的结果。两层压缩覆盖了 Agent 获取数据的两条路径。

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
2
3
4
5
6
7
8

-- 错误: no such column: s.utid
SELECT s.ts, s.name FROM slice s
JOIN thread t ON s.utid = t.utid

-- 修正: 通过 thread_track 中间表
SELECT s.ts, s.name FROM slice s
JOIN thread_track tt ON s.track_id = tt.id
JOIN thread t ON tt.utid = t.utid

错误 2：列名歧义

1
2
3
4
5

-- 错误: ambiguous column name: name (slice 和 process 都有 name 列)
SELECT name, ts FROM slice s JOIN process p ON ...

-- 修正: 加表名前缀
SELECT s.name, s.ts FROM slice s JOIN process p ON ...

错误 3：对 counter 表的数据模型理解有误

Perfetto 的 counter 表存储的是采样点（时间戳 + 值），不是区间数据，没有 dur 列。

1
2
3
4
5

-- 错误: no such column: c.dur
SELECT SUM(c.value * c.dur) FROM counter c

-- 修正: 使用简单平均值或 LEAD 窗口函数
SELECT AVG(c.value) FROM counter c WHERE ...

错误 4：stdlib 表名 / 列名陷阱

这两条都是 commit 05922e67 加进去的——发现源是「无主孤儿 stderr」：分析早就结束了，trace_processor 还在喷错误日志，反查回去才定位到 Agent 在 dynamic SQL 里反复踩同样的坑。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

-- 错误 4a: no such table: cpu_frequency_counters
-- 这是 stdlib 表，不在 lazy 预加载的 3 个 Tier-0 模块里
SELECT ts, cpu, freq FROM cpu_frequency_counters WHERE ...

-- 修正: 先 INCLUDE 模块再查
INCLUDE PERFETTO MODULE linux.cpu.frequency;
SELECT ts, cpu, freq FROM cpu_frequency_counters WHERE ...

-- 错误 4b: no such column: ts
-- android_garbage_collection_events 用 gc_ 前缀的列名，不是常规的 ts/dur
SELECT ts/1e6, dur/1e6 FROM android_garbage_collection_events

-- 修正: 用 gc_ts / gc_dur / gc_running_dur / gc_runnable_dur
SELECT gc_ts/1e6, gc_dur/1e6, gc_running_dur/1e6
FROM android_garbage_collection_events

stdlib 视图作者经常会用领域前缀的列名来避开多表 JOIN 时的 ambiguous column 问题，但 Claude 默认假设的是 ts/dur 这种通用约定。这种「stdlib 自己的命名习惯 vs 通用 SQL 习惯」的冲突没法靠 schema introspection 完全自动解决——lookup_sql_schema 工具能告诉 Claude 表存在和有哪些列，但不能预测「这次 Claude 一定会想当然地写 ts」。只能靠纠错对累积来兜底。

这些错误的检测和学习机制是这样的：当 SQL 执行失败时，错误信息和 SQL 被暂存；当后续有 SQL 执行成功时，系统通过 Jaccard 相似度匹配（排除 SQL 结构关键词如 SELECT/FROM/WHERE，以及 Perfetto 通用 token 如 utid/dur/slice）判断是否是同一查询的修正版本。匹配阈值 >30%，时间窗口 60 秒。匹配成功则生成 error→fix 对并持久化到磁盘。

新分析开始时，最近 10 条纠错对加载到 System Prompt，Claude 在写 SQL 之前就能看到这些已知的坑。纠错对设置 30 天 TTL，过期自动清理——Perfetto 的 SQL schema 会随版本更新变化。

第六部分：开发过程本身的 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 先输出结构化实施方案（要改哪些文件、改什么、依赖关系），人审查确认后再执行代码修改
• SuperPower：Claude Code 的第三方插件生态，通过 MCP Server 为 Claude Code 注入额外能力。SmartPerfetto 开发中使用了 Chrome DevTools Protocol 插件（直接操控浏览器截图、调试前端）、Playwright 插件（自动化 UI 测试和截图）等。这些插件让 Claude Code 的能力从代码编辑扩展到了浏览器交互和可视化验证
• Codex + Codex MCP：Codex 是 OpenAI 的代码推理模型。通过 Codex MCP Server 集成到 Claude Code 中后，Claude 可以在对话过程中直接调用 Codex 做独立审查——把实施方案发给 Codex，Codex 以只读方式访问代码库，从架构合理性、边界情况、遗漏风险三个角度给出反馈，整个过程不需要离开 Claude Code 的工作流
• Agent Team：Claude Code 支持启动多个子 Agent 并行工作，每个 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

1. 我确定需求和架构方向
2. Claude Code 在 Plan Mode 下输出实施方案
3. Codex 以只读模式审查方案，提出反馈
4. 我评估 Codex 的反馈（不盲从，约 20% 的建议会被驳回并说明理由）
5. Claude Code 按修正后的方案执行代码修改
6. 自动运行完整测试：
   - npx tsc --noEmit (类型检查)
   - npm run test:scene-trace-regression (6 条 trace 回归，验证 Skill 数据产出)
   - npm run validate:skills + validate:strategies (Skill/策略合约校验)
   - 对于启动/滑动/Flutter 相关的改动，还会跑真实 Trace 的 E2E Agent 分析：
     用 verifyAgentSseScrolling.ts 脚本加载真实 trace 文件，
     发起完整的 Agent 分析会话，检查 SSE 事件流、工具调用序列、
     最终结论是否覆盖策略中定义的必检项。
     比如滑动场景会检查 Agent 是否执行了 Phase 1.9 根因深钻，
     Flutter 场景会检查 Agent 是否正确识别了 TextureView/SurfaceView 架构
     并调用了 flutter_scrolling_analysis 而不是标准的 scrolling_analysis。
     这一步验证的不是 Skill 能不能跑通，而是 Agent 在面对真实数据时
     的推理路径和结论质量是否符合预期。
     <!-- TODO: 贴真实截图 -->
     <!-- 截图 6: E2E 测试输出 — verifyAgentSseScrolling.ts 的终端输出，展示 SSE 事件统计和通过/失败状态 -->
7. 测试不通过 → 分析失败原因（读 session log + metrics）→ 修复 → 重新测试
8. 测试通过 → /simplify (代码整理)
9. 最终 Codex review 确认

这个流程中，人的介入集中在第 1 步（需求和架构决策）和第 4 步（评估 review 反馈）。代码细节、测试执行、格式整理由工程流水线完成。

和 SmartPerfetto 架构的对应关系

回过头看，我的 AI 辅助开发流程和 SmartPerfetto 的 Agent 分析流程在结构上是相似的：

两个系统的演进方向也一致：人的介入从执行层逐步上移到决策层。 SmartPerfetto 从固定管线（人定义每一步）到自主推理（人定义目标和约束）；我的开发方式从逐行 review 到审查架构方案。

这不是偶然——Harness Engineering 的核心就是构建足够的工程基础设施（测试、验证、review），使得人可以信任 AI 的执行结果，把注意力放在更高层的决策上。

下图汇总了 SmartPerfetto 的 Harness Engineering 全景——从输入路由到跨会话学习：

结语

回顾这三个月的迭代，从 agentv2 的 13 步固定管线到 agentv3 的自主推理，从约 30% 误判率到三层验证，从 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 被调度到小核导致响应延迟」

这些改进都不是通过调整 prompt 文字实现的，而是通过改变 Agent 的工具集和数据环境实现的。如果我要给做 AI Agent 应用的工程师一个建议，就是把精力放在工具设计和数据控制上，而不是 prompt engineering 上。

后续方向

当前的 SmartPerfetto 是一个交互式分析工具，还远远没有达到可以发布的程度，所以目前还是闭源的，由我个人在负责开发。后续的工程方向包括：

• 厂商深度接入 — 当前 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 定位变更引入点

在合适的时候本工具会开源处理（因为各个大厂内部都在做了，所以开源出来大家集思广益，共同开发），对进度感兴的同学可以加我微信进群聊或者私聊。

关于我 && 博客

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

1. 博主个人介绍 ：里面有个人的微信和微信群链接。
2. 本博客内容导航 ：个人博客内容的一个导航。
3. 个人整理和搜集的优秀博客文章 - Android 性能优化必知必会 ：欢迎大家自荐和推荐 （微信私聊即可）
4. Android 性能优化知识星球 ： 欢迎加入，多谢支持～

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

16 KB 内存页面大小的支持，是Google Play 新提出的要求。要在2026年5月31日之前，满足这一条件：

https://play.google.com/console/u/0/developers/9060101706093336387/app/4974577679306649072/policy-center/issues/4988764664083295045/details

Android 15 的 16KB page 检测主要看三件事：

1. PT_LOAD >= 16 KB
2. RELRO 必须在 segment 末尾（suffix）
3. RELRO end 必须 16KB 对齐

对于aab 来说，上面的三个要求，一般只用关注PT_LOAD。因为aab 有压缩率，所以关于压缩的两项检验直接计算是不准确的。Google Play 在分发时会自动处理。

官方文档：

https://developer.android.com/guide/practices/page-sizes?utm_source=chatgpt.com&hl=zh-cn

检测方式

关于so 文件是否合规的检测，主要有以下几种方法：

方法一

可以解压出so文件，然后使用ndk 工具检测（一定使用PowerShell，cmd无法运行）：

1

llvm-objdump.exe -p E:\Test\so\arm64-v8a\libanogs.so | Select-String -Pattern "LOAD"

运行结果可以看LOAD off 类型行尾是不是带有212、213。
低于2**14的so文件都不符合。

工具的路径在：

1

{YourNDKPath}\toolchains\llvm\prebuilt\windows-x86_64\bin

但是这里只检查了PT_LOAD。

方法二

Google 官方提供了检测工具：

https://cs.android.com/android/platform/superproject/main/+/main:system/extras/tools/check_elf_alignment.sh?hl=zh-cn

可以直接使用这个脚本进行检测。

1

check_elf_alignment.sh APK_NAME.apk

方法三

最后，如果将Android Studio 更到最新版本，即可使用Apk Analyze 功能进行检测。

前者报错为：

1

4 KB LOAD section alignment, but 16 KB is required

后者报错为：

1

RELRO is not a suffix and its end is not 16 KB aligned

适配方法

Unity 相关so

Unity相关的so，需要通过提升Unity 编辑器版本号的方式进行解决。

第三方SDK

第三方SDK 相关的so，需要联系相关提供商进行SDK 升级。

如果无法完成合规，应该考虑取消对该插件的接入。

自己编译的so

如果是自己使用NDK 编译的so，需要升级NDK工具并在编译中指定相关参数。

1
2
3
4
5
6
7

({NDK Path}/ndk-build ^
NDK_PROJECT_PATH=. ^
APP_BUILD_SCRIPT=Android.mk ^
NDK_APPLICATION_MK=Application.mk ^
APP_ABI="armeabi-v7a x86 arm64-v8a x86_64" ^
APP_LDFLAGS="-Wl,-z,max-page-size=16384 -Wl,-z,common-page-size=16384" ^ // 新增
|| pause) && pause

对于Android.mk 文件和Application.mk 文件也有内容需要修改：

如果旧内容涉及cmd-strip，在打包时会报错。这是因为NDK r23+中，strip 工具路径变成 LLVM 版本。最简单的解决方式是删掉这一行，新版本不需要手动调用strip，会自动调用。

如果文件中存在：APP_STL := gnustl_static，也需要进行修改。
修改为：APP_STL := c++_static

为了兼容RELRO 必须在 segment 末尾（suffix）和 RELRO end 必须 16KB 对齐，需要在Android.mk 中增加：

1
2

LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384
LOCAL_LDFLAGS += -Wl,-z,common-page-size=16384

最后，在旧的代码中，如果使用了PAGE_SIZE / PAGE_MASK 宏，这会报错，在新版本中，NDK 不再提供。
需要增加以下内容：

1
2
3
4
5
6
7

#ifndef PAGE_SIZE
#define PAGE_SIZE 4096
#endif

#ifndef PAGE_MASK
#define PAGE_MASK (~(PAGE_SIZE - 1))
#endif

3. il2cpp处理方式

升级到新版Unity之后，如果不修改代码，可能不会让C++代码重新导出。

也可以删除Library目录下的Bee目录和所有的il2cpp_*目录的缓存，强制生成。

对于经历过 2007-2017 年移动操作系统大洗牌时代的用户，Android 曾是一面旗帜。

在 BBOS、塞班、Windows Mobile「百家争鸣」之后，由谷歌牵头的 Android 成为仅存的硕果。这个开源操作系统，曾经是包容、多样与打破陈规的象征，与隔壁精致、有板有眼，却封闭的 iOS 形成了鲜明对比。

▲ 图｜WIRED

然而多年以后，谷歌变了，Android 也变了。

2026 年 4 月 1 日，本来是个大家都开心的日子，谷歌突然宣布：

Android 开发者验证功能自近日起全面推出，所有开发者必须向谷歌注册自己的应用。未来如果系统检测到安装包没有注册信息，将会强制启动 7 天的「安装冷静期」，或者要求用户必须接上电脑用 ADB 授权安装。

这套名为「高级侧载」（advanced sideload）的功能预计在今年 8 月向所有安卓用户推出，「冷静期」功能则计划 2027 年在全球范围施行。

本质上，谷歌封锁了「侧载」应用，即直接通过 .apk 文件直装应用的路子。

▲ 图｜Aurich Lawson

从不断收紧的第三方应用侧载限制，到针对全球开发者的强制认证要求，再到令人难绷的「七天安装冷静期」，叠加前面转向闭源的新闻——无不在释放一个令人心寒的信号：

谷歌正在亲手杀掉曾经由它开启的开放 OS 时代。

毕竟如果我们回看 Android 诞生初期，它之所以能够击溃塞班、抗衡 iOS，靠的绝不是单纯「免费」，同时还有那份近乎野蛮的开放性。

▲ 图｜TechRadar

正是对于「开放性」的包容，让 Android 成功突围，得以在全球移动 OS 市场上和苹果抗衡，以后来居上的姿势告诉全世界：

手机操作系统，何必是被严密限制的黑盒？它完全可以是一张白纸，由厂商、开发者、用户共同书写——

如果你不喜欢厂商预装的桌面，就直接换一个启动器；Play Store 也不是唯一的下载渠道，各种第三方应用市场百花齐放。

当然，如果你想要的应用没有上架应用商城，完全可以通过侧载的方式安装。

▲ 知名第三方应用市场 F-Droid｜Android Authority

这种高自由度和可定制化，就是 Android 森林能够如此茂盛的根基，也是它相比坚持「封闭花园」策略的 iOS 的最大竞争优势。

但今天的谷歌，似乎早已忘记了当年「不作恶」（Don’t be evil）的口号，同时患上了某种「权力焦虑症」——它要控制系统里每一条 ADB 指令的流向，质询每个安装包的来源。

这完全就是「屠龙勇士终成恶龙」的现实版本。

谷歌正在用一种温水煮青蛙的方式，将 Android 变成一个披着「开源」的皮、实则高度集权的私家领地。

▲ 图｜How-to-geek

在谈到这些限制时，谷歌永远都只会抛出「安全」和「用户体验」的理由。

诚然，移动安全至关重要，在如今这个手机承载了我们 95% 日常生活的时代来说更是如此，但我们已经经历了太多太多血淋淋的教训——

所有拿「安全」做挡箭牌的商业决策，最后都变成了攫取用户信息获利的手段。

更何况，谷歌在不管不顾地推进这种封闭化进程时，反而让自己露出了一个极其尴尬的姿势。

「没有苹果命，得了苹果病。」这句话以前是形容盲目抄袭苹果产品形态、却忽视了苹果设计逻辑的手机厂商用的，现在用来形容谷歌倒是再贴切不过——

没有人能够否认，iPhone + iOS 软硬件结合的「围墙花园」（walled garden）模式在商业上的成功，iPhone 用户也乐于留在其中。

▲ 图｜Apple

但我们必须清楚：苹果能够跑通这一套逻辑的前提，是它真的做到了「为用户提供一个完整的闭环生态」。

iPhone 只能从 App Store 获取应用不假，但 App Store 里的应用不仅会经过苹果严苛的技术审核，更重要的是：苹果的服务足够便捷、稳定，且能够在全球范围提供相对统一的高质量内容。

▲ 图｜Apple

反观谷歌 Play Store，光是 Play Store 本身的 Bug 频出和应用质量的良莠不齐，就足以让谷歌梦里的「围墙花园」地基垮掉。

虽然 App Store 里面也有不少粗制滥造的东西，但相比 Play Store 的生态还是小巫见大巫了。

▲ Play Store 付费榜

哪怕谷歌已经扯着嗓子喊了几年的 Play Protect 机制和强制 API 规定，我们依然能在 Play Store 的推荐页乃至首页，看到大量粗制滥造的马甲包。

甚至在 2026 年的今天，Play Store 免费区里面依然潜伏着太多字面意义上的「毒瘤」应用。

▲ 麦卡菲安全通报的数个 Play Store 毒瘤应用｜McAfee

而在这种官方渠道无法做到尽善尽美的情况下，谷歌却还要斩断用户寻找第三方替代方案的后路，好一个又当又立的典范。

别忘了，Play Store 同样是锁区的，并且锁区机制相比 App Store 简直有过之而无不及。

对于很多地区的用户来说，侧载 APK 其实跟所谓的极客精神八杆子打不着——而是为了在官方商店堵死的情况下，维持手机的基本功能。

▲ 图｜Reddit

而谷歌紧赶慢赶想要关上侧载这扇门，本质上就是在强迫用户接受一个德不配位的商店服务。

谷歌对 Android 核心资产的态度转变，更是让人加深对这个操作系统的不信任。

从去年开始，谷歌就开始宣布 Android 的部分核心功能不再向 AOSP 开放，而是整合进其私有的 GMS 服务中。

换言之，以前「原生」和「类原生」的区别，已经被谷歌自己切割成「Pixel OS」和「其它」。

同时，AOSP 源代码的公开频率和深度也在大幅削减，直至谷歌最后宣布：仅会向部分生产 Android 手机的企业伙伴提供 AOSP 源码。小型硬件品牌、第三方 ROM 和个人开发者，哪凉快哪歇着去吧。

▲ 图｜Android Authority

这就是 Android 从开源转向闭源的标志。

那个曾经属于全球开发者的 Android、那个曾经用「农村包围城市」战术赶超 iOS 的 Android，其开放与自由的属性，正在被谷歌从内部一点点掏空。

自从 Pixel 手机的业务站稳脚跟，谷歌就开始试图通过控制底层代码和基础 API，把 Android 从一个公共资源池，转型为纯粹的、为谷歌搜索、广告、应用生态业务服务的赚钱工具。

▲ 图｜Google Ads

这种商业上的贪婪，正是最近几代 Android 大版本在审美和质量上表现得极其分裂的原因——

它既想要苹果那样对软硬件生态的话语权，又舍不得放下它那套依靠大规模数据采集和广谱分发的商业逻辑。

这其中最典型的例子，就是谷歌对 UI 设计规范的反复无常。

你或许还记得 Material Design，那个谷歌曾经提出的介于拟物化和扁平化之间的、以「折纸」为哲学的设计语言：

▲ 图｜Tech & ALL

从 Material Design 1.0 到现在的 Material You、Material 3 Expressive，且不说安卓本身的设计语言有多割裂，谷歌做了这么多年设计先锋，到头来却连自家全家桶的设计都没办法统一跟上最新标准。

自家房间都扫不干净，谷歌又有什么颜面指挥全世界 Android 开发者呢？

▲ Material 3 Expressive 效果图｜Google Design

理念的混乱、审美的平庸，正是谷歌无法建立起类似苹果那样的品牌信仰和生态凝聚力的原因。

然而在这种软实力缺失的前提下，谷歌却试图通过强硬的硬性限制——比如可能在 2027 年全球上线的「七天安装冷静期」——来建立防御壁垒。

这种做法不仅是逃避责任，更是一种技术上无能的表现。

▲ 图｜Interesting Engineering

如果一个系统需要通过人为制造障碍、折磨用户耐心的方式，来规劝用户应该做什么，维持所谓的安全，那只能说明这个系统的底层架构已经混乱到了无法通过正常技术手段解决问题的地步。

苹果之所以是苹果，因为它从卖 iPhone 的第一天就设计好了如何运转这样一个封闭的生态系统。

谷歌想要变成苹果，用的方法却是「头疼砍头、脚痛砍脚」。

从 18 年前的 Android 1.0 走到今天，谷歌似乎忘记了 Android 之所以能有如今的地位，正因为它是一个「和 iOS 不一样的选择」。

▲ 图｜Android Police

然而当谷歌把 Android 变得越来越像一个廉价、粗糙且充满限制的 iOS 仿制品时，它就失去了自己最核心的竞争优势——

既然非得从两个封闭系统里选一个，那我凭什么选尾大不掉的 Android，而不去买更完善、更安全、封闭得井井有条的 iPhone 呢？

「开放」与「封闭」的矛盾中心，就是谷歌没有办法拿出一个真正能够在封闭系统内运行的足够好的 Android 产品，来为自己的策略撑腰。

它既没有苹果那样端到端的生产研发实力，又没有苹果的品位和审美，更是至今保留着 Android 里面抠都抠不掉的牛皮癣——年代断层的 UI、无法统一的 API、以及封闭又稀碎的软件生态。

苹果给用户喂饭，虽然不一定合每个人的胃口，但好歹是饭。

而谷歌喂的，就很难说是什么东西了。

▲ 图｜9to5Google

直白地说，谷歌对于 Android 开放性动手动脚，本质就是缺乏远见且充满傲慢的体现，在自己的地位稳固后，开始逐渐剥离曾经赋予它权力的「草根」生态，转而渴望独裁的横征暴敛。

如果谷歌继续在封闭之路上狂奔，那它最终收获的不会是一个稳定的赚钱机器，而只会是一个死气沉沉的荒芜花园。

因为谷歌在 18 年之后，已经彻底忘记了：

人们选择 Android，难道是因为它像 iOS？

#欢迎关注爱范儿官方微信公众号：爱范儿（微信号：ifanr），更多精彩内容第一时间为您奉上。

去年在接入安卓SDK时，会有部分渠道有要求手写闪屏的情况，下面是当时的笔记，这只是最简单的一种方法。

参考资料：

很好的例子：

https://www.jianshu.com/p/a609f510b19a

https://blog.csdn.net/l799069596/article/details/47094731

安卓动画：https://blog.csdn.net/IO_Field/article/details/53101499

背景：

除去游戏本身的闪屏之外，有的渠道会要求，有额外的渠道闪屏。为了使用一套资源出不同渠道包，我们可以对接渠道的AS工程进行处理，单独设置闪屏。

首先，创建一个闪屏Activity，为你的主Activity，这样在游戏的一开始你就可以看到闪屏了。

这里需要注意的是，你原先的Activit也需要在Manifest中注册打开日志，否则在打包的时候会找不到，报错：

https://blog.csdn.net/qq_28301007/article/details/52265775

1

<activity android:name="...Activity"/>

下面是主Activity，也就是闪屏Activity的代码，需要根据AS的提示import缺少的部分。

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

import android.animation.ObjectAnimator;
import android.animation.ValueAnimator;
import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.os.Handler;
import android.view.WindowManager;
import android.widget.ImageView;

public class SplashActivity extends Activity {
    private final int TimeAnimDurning = 2000;
    private int displayDeviceWidth;
    ImageView iv_splash;
    private ObjectAnimator objAnim;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        displayDeviceWidth = getResources().getDisplayMetrics().widthPixels;
        setContentView(R.layout.activity_splash);
        iv_splash = (ImageView) findViewById(R.id.splash);
        objAnim = ObjectAnimator.ofFloat(iv_splash,"alpha",1,0);
        objAnim.setDuration(TimeAnimDurning);

        new Handler().postDelayed(new Runnable() {
            @Override
            public void run() {
                objAnim.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {
                    @Override
                    public void onAnimationUpdate(ValueAnimator animation) {
                        if((int)animation.getAnimatedFraction() == 1){
                            getWindow().clearFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN);
                            startActivity(new Intent(SplashActivity.this , .YouActivity.class));
                            finish();
                            return ;
                        }
                    }
                });
                objAnim.start();
            }

        }, 2000);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@color/white"
    tools:context="com.unity3d.player.SplashActivity">

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:visibility="visible">

    <ImageView
        android:id="@+id/splash"
        android:layout_width="0dp"
        android:layout_height="match_parent"
        android:layout_weight="1"
        android:scaleType="fitXY"
        android:src="@drawable/splash" />

</LinearLayout>
</RelativeLayout>

在上面控制闪屏格式的style.xml中，可以看到闪屏的背景色设置为了白色。这里有一些常用的颜色xml：https://blog.csdn.net/sundaysunshine/article/details/53509854

除了这两处之外，还需要根据style.xml中的配置，放好闪屏图片，设置闪屏背景。

整个闪屏的原理就是创建一个动画，在动画播放完成之后，去执行一个新的activity。在补全报错的部分之后，还是有一些细节部分需要注意的。

首先是结束时间的判定。判定时机总共有两种，一种是获取动画的进度，就像这里的例子，使用(int)animation.getAnimatedFraction()进行获取一个从0~1的数，来表示目前的动画的播放进度。除此之外还可以获取播放的时间，这个函数是：getAnimatedValue()，它可以获取属性的当前值。使用这两个函数可以很方便地控制动画的时间和动作。

除此之外，在调起另一个Activity之后，我结束了这个Activity。这是因为如果使用默认的LaunchMode，在重新唤醒应用时，闪屏会再次启动，然后走完动画，应用重启。这就造成了应用无法关闭的状况，只能后台强制杀掉。解决办法就是让闪屏只执行一次。

去年的这个时候，我在忙于接入各种SDK。接渠道SDK，是一件十分薛定谔的事情。你觉得很容易，的确很容易，但是，也很容易遇到问题。然后我就陷入了长期的自闭状态，再加上偷懒，然后博客就断更了一年。现在回头来回忆一下，去年的这个时候，接入SDK时的那些体验。

1.酷派

充值之后，服务器收不到消息，对接也没有人。

现在看来很明显，已然黄了。

2.应用宝

传说中的5000人大群只有2个技术的大渠道。每天上午问问题会施舍你两句，下午是肯定不会回答问题的，团建能团建半个月。这个渠道我是使用聚合sdk接入的。需要注意的是，接入时有测试阶段，和正式阶段之分，游戏货币名不能修改，同时还必须接入腾讯的信鸽推送SDK，否则无法过审，手动接入成本极高。

3.金立

高版本会造成初次进入闪退，主动获取权限也不行，必须低版本编译。
华为手机会出现渲染错误，游戏变成紫红色。
需要安装支付插件。
现在也应该没有接入的必要了。

4.华为

相当棒的渠道，文档详细，对接起来体验也很不错。充值错误的时候，每一步骤，原因都会有显示。
但是不支持第三方工具接入。
需要安装支付插件。

5.魅族

商品id配置不明，会出现莫名的变动，很不靠谱。
支付回调生效需要1天的时间，需要对商品进行映射，对接很麻烦的渠道。
需要安装支付插件。

6.360

包体最大，足足有50多k的方法数，不分包就是死。

7.百度

方法数排名第二，仅次于360。
高版本编译会无法使用闪屏。
提审体验极差。说好的SDK不强用更，但是等到提审后告诉你不合格。

8.联想

商品id为自动生成，需要做好映射。
AnySDK接入需要注意参数顺序。

9.UC

无法使用第三方工具进行接入。
闪屏比较蛋疼，在sdk初始化时自动播放。首次运行时无法正常显示，时机不一定，容易和应用闪屏覆盖。

10.OPPO、VIVO

无法使用第三方工具进行接入。
需要安装支付插件。

11.小七

文档描述不明确，注意对登陆回调的处理方式，注重切换账号的测试。
SDK的Manifest中，最高宽高比设置为2.2。如果游戏中有对这个参数进行修改，需要进行统一。

12.拇指玩

sdk默认背景为透明，会造成有些版本的手机唤起sdk时会显示桌面为背景。或者是切换到主屏后，再回来，只有单独的sdk页面。
解决方式是把style.xml中的windowIsTranslucent值置为为false。
回调处理方式与其他sdk略有不同,Log与执行功能部分的代码进行了分离。
目前版本，无法使用qq登陆等方式，在登陆界面仍没有去掉该入口。

其他:

在运营过程中，小米、UC、应用宝和魅族会不同频率出现无法登录的问题，属正常现象，是他们的SDK服务器抽风了，会报一些很可怕的错误，比如应用不存在，应用id无效之类的。这时候只需要稳定好用户的心态即可，没有任何解决办法。

Haven 是一款免费、开源的安卓一站式 SSH、VNC、RDP 和 SFTP 客户端。@Appinn

Haven 功能还挺多的：

SSH

网络

远程桌面

文件管理（SFTP）

安全