这篇文章收集了《从 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 性能优化知识星球 ： 欢迎加入，多谢支持～

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

昨天那篇 OpenClaw 实战复盘发出去之后，后台留言和群里讨论最多的就是这几个方向的问题：Token 消耗、能干什么、本地模型、隐私安全、使用体验。今天挑出被问频率最高的五个，一个一个说清楚。

1. Token 消耗到底多少？贵不贵？

先说结论：没你想的那么贵，但也不是零成本。我前后用了两套方案，一套云端大厂套餐，一套国产性价比路线，感受差异还是挺明显的。

前期：OpenAI Pro 套餐（200 刀/月）

一开始接的是 OpenAI Pro，量大管饱，用着确实省心。不过这个套餐不是只给 OpenClaw 用的——我日常写代码也走这个额度，实际消耗大概一半一半。跑了段时间下来，5 小时速率上限从来没碰过，Weekly 上限也没撞到，说明我这种”重度使用但不是 7×24 不停歇”的用法，200 刀的额度是够用的。

后期：智谱 GLM5 Coding Plan（年费 ¥1608）

Pro 到期后，我切到了智谱 GLM5 Coding Plan，走的是国产模型路线。我买的时候赶上了首购优惠价 ¥980/年，但 **2026 年 2 月智谱调整了套餐价格，取消了首购优惠，整体涨幅约 30%**。

2026 年 3 月最新套餐价格

我用的相当于 Pro 档位，涨价前 ¥980/年，现在 ¥1608/年。实际跑下来体验还行，定时任务、巡检、日报周报、知识库整理这些高频场景都能稳稳撑住，没出现过限额不够用的情况。

GLM-5 API 按量计费（如果不用套餐）

如果你不想买套餐，也可以按量付费。GLM-5 的 API 价格：

算笔账：我 7 天烧了 2.4 亿 Token，如果按量付费光这 7 天就要花大约 ¥2400，而套餐年费才 ¥1608——也就是说一整年的套餐价还不到 7 天按量费用的零头。所以我的建议很直接：重度用户直接上套餐，轻度用户可以先按量试试水深。

国内 Coding Plan 对比（2026 年 3 月）

这三家是对 OpenClaw 支持最好的国内模型：

我的选择是 GLM Coding Pro（¥1608/年），原因是 OpenClaw 对智谱的支持最成熟，API 稳定，中文能力强。性价比之选是 MiniMax Plus（¥1400/年），比 GLM Pro 便宜 200 块，能力接近。

⚠️ 以上价格为 2026 年 3 月查询结果，各家会不定期调整，购买前请以官网为准。

真实数据：7 天烧了 2.4 亿 Token

我查了下智谱后台：过去 7 天，GLM5 消耗了约 2.4 亿 Token。数字看起来挺吓人的，但要注意几点：这 2.4 亿是纯云端 GLM5 的消耗，本地模型处理的那部分并不算在里面；Coding Plan 年费 1608 元，2.4 亿 Token 分摊到 7 天的话平均每天大约 3400 万 Token；如果按量付费 GLM5 大约 0.01 元/千 Token，光这 7 天就要花 2400 元——而 Coding Plan 全年才 1608 元，套餐的性价比不言而喻。所以真实的费用结构是这样：云端干高质量任务，本地干高频脏活，搭配下来成本远没有想象中夸张。 完全不想花钱的话也可以只用本地模型起步，但能力上限和响应质量确实会差一截。如果愿意每月花一杯咖啡的钱接个云端模型，整体体验会好很多，尤其是长文写作和复杂推理的场景。

心态：别太功利

说到费用，我想多聊两句心态。养了这么久 OpenClaw（我家小朋友叫它”虾哥”），我最大的感触是：别一开始就想着变现、ROI 这些功利性的东西。AI 时代才刚刚开始，前期投资是必须的。你现在投入的时间和金钱可能暂时看不到直接收益，但会慢慢转化成你对 AI 能力边界的理解、对 Agent 协作的体感、对”什么场景能用 AI 解决”的直觉判断力。这些东西短期内没法量化，但长期来看价值巨大。

我的态度一直是：养虾就当给自己买了个大玩具，千金难买我开心。每天看它自己跑任务、写文章、整理知识库，这件事本身就已经很有成就感了。以后能变现当然好，但不能用”现在能不能变现”来决定要不要开始。先养起来，比什么都重要。

2. OpenClaw 到底能干什么？给几个实际的例子

上一篇实战复盘写得比较详细，但我知道很多人没耐心从头看到尾。这里直接捞几个我觉得最有价值、最能说明问题的场景出来。

我正在用的

核心价值在于，OpenClaw 最值钱的不是”帮你回答一个问题”，而是把那些你明知很重要、但凭意志力很难长期坚持的事情变成系统默认帮你执行的后台任务。

进阶案例 1：批量导入 NotebookLM 进行深度分析

NotebookLM 是 Google 推出的 AI 研究助手，可以把你的各种资料（PDF、网页、文档）变成一个可对话的知识库。它最大的亮点是能自动生成播客式音频概述——两个 AI 主持人用轻松聊天的形式帮你总结资料要点，通勤路上戴着耳机听非常香。但 NotebookLM 有个明显的痛点：手动添加资料很麻烦，需要一个一个上传文件、一条一条粘贴链接，资料一多就让人抓狂。OpenClaw 刚好可以帮你把这个流程自动化掉。

实际操作

1
2
3
4
5

我：帮我研究一下 Android 15 的性能优化特性。
    1. 搜索相关资料（官方文档、博客、论文）
    2. 整理成 10-15 个高质量来源
    3. 批量导入到 NotebookLM
    4. 生成播客概述

OpenClaw 会自动搜集 Android 15 性能优化相关的官方文档、技术博客和论文，筛选掉水文和营销号只保留真正有价值的内容，然后通过 API 或浏览器自动化把资料一键导入 NotebookLM，最后触发播客生成。

为什么这个组合很香？

本质上就是把”信息搜集和筛选”这种费时费力的脏活外包给 OpenClaw，让 NotebookLM 专注于它最擅长的”深度分析和结构化输出”。

进阶案例 2：扔一个链接，自动抓取所有关联内容并落盘

这是我日常用得最多的场景之一，几乎每天都会触发。刷推或者看公众号的时候看到一篇好文章，里面提到了几篇论文、几个 GitHub 仓库、几个相关链接、几本推荐的书籍。以前的做法你一定不陌生：收藏 → 告诉自己回头看 → 忘记 → 再也没看过。现在有了 OpenClaw，做法变了：

1
2
3
4
5
6
7

我：https://example.com/awesome-article
    把这篇文章里提到的所有内容都抓下来：
    - 论文 → 下载 PDF
    - GitHub 仓库 → star + 克隆到本地
    - 相关链接 → 抓取正文
    - 书籍 → 记录到待读清单
    最后整理成一份 Markdown 落盘到 Obsidian

OpenClaw 会读取原文、识别所有链接和引用，然后分类处理：arXiv/论文链接下载 PDF 到 论文/ 目录，GitHub 链接判断是否值得 star、重要的克隆到本地，普通网页抓取正文转成 Markdown，书籍链接提取书名加入待读清单。最后生成一份包含原文摘要、所有关联内容链接和简介、落盘位置的索引 Markdown，自动保存到 Personal-Knowledge/source/ 目录。一个链接，一条指令，全套内容自动归位。 以后想回顾的时候打开 Obsidian 搜一下关键词就行，所有关联资料都已经按类型归好位了。

如果你是 Android 开发者

这是我目前还没做但正在规划中的方向，列出来看看有没有跟你产生共鸣的场景：

这些能力并不是开箱即用的，需要根据你自己的业务场景做定制开发。但 OpenClaw 的架构天然支持这些方向的扩展——关键是先把基础设施养起来，再根据实际需求慢慢迭代。

一句话总结

论文每天读、仓库每天盯、知识每天理、日报每天写。它真正做到的是，把”需要长期坚持”这件反人性的事情变成了”系统在后台默默帮你执行”。

3. 本地模型可以干什么？

本地模型的定位并不是替代云端大模型，而是专门负责那些脏活、累活和高频重复的任务。一句话概括分工：云端”想得深”，本地”跑得勤”。

本地模型承担了多少？

我的实际运行数据：

按任务数量算，本地承担了 60-70%；按 Token 消耗算，本地承担了 80%+。

我的配置

硬件是一台 Mac Studio（M 系列 Apple Silicon），上面部署了多个规格的本地模型：Qwen3.5-2B/4B/9B 使用 MLX 8bit 量化，负责轻量任务和云端故障时的容灾降级；Qwen3.5-27B 通过 Ollama 部署，承担高频结构化任务，是本地的主力干活模型。顺便提一句，Apple Silicon 上用 MLX 框架做推理的效率明显比 Ollama 高，尤其是跑小模型的时候差距更明显。

分工原则

至于成本，硬件本来就是已经购入的设备，电费增加也不多，所以本地模型的边际成本接近零。

烧 Token 的速度

即使有本地模型分担，云端 Token 还是烧得飞快。我的配置是主模型 GPT-5.4 + 干活主力 GLM5 + 本地苦力 Qwen3.5 系列（27B/9B/4B/2B）。所以我的建议是直接上量大管饱的 Coding Plan 套餐，预算充裕的话可以选 GPT Pro，追求性价比的话 MiniMax 或者 Kimi 都是不错的选择。按量付费的话，以这个消耗速度你一定会心疼的。

备用通道

虾哥前期运行偶尔会出现不稳定的情况，这时候我会用 Claude Code（Remote Control）远程连过去手动排查和救火。这种情况出现的频率不高，但有备用通道在手里心里踏实很多。

分工逻辑

打个比方，本地模型是”勤奋的蓝领工人”，云端模型是”聪明的高级顾问”。OpenClaw 做的事情就是帮你把这套分工协作的逻辑彻底自动化了。

4. 隐私和安全怎么保护？

这个问题被问得非常多，也确实是每个人在决定养虾之前必须认真想清楚的事情。

核心原则

敏感数据不离开本机。 这是我给自己划的底线。具体的做法也很简单直接：

1. 敏感文件不上云端：公司代码、内部文档、个人隐私相关的内容，一律只走本地模型处理
2. 本地优先：能在本地解决的任务，绝不走云端 API
3. 最小权限原则：OpenClaw 只能访问我明确授权过的目录和工具，其他一概不给权限

技术层面的防护

命令执行白名单方面，safeBins 配置严格限制了它能执行的命令范围，只允许 ls、cat、grep、find、git 这些基础只读命令，而像 rm -rf 这样的危险操作会被 deniedFlags 直接拦截。也就是说即使有人尝试通过提示注入诱导它执行恶意操作，命令层面也根本跑不通。

来源校验方面，commands.ownerAllowFrom 和 channels.allowFrom 做了来源白名单，只允许我自己的账号发送系统级指令，即便在群聊里有其他人@它也不会响应任何敏感操作。

另外还有配置文件哈希校验，每天自动对 openclaw.json 生成 SHA256 哈希值并与基线值对比，一旦检测到配置文件被篡改系统会立刻触发告警通知。加上定期巡检，每天自动扫描 workspace 目录下的所有文件，检测是否存在私钥、密码、助记词等敏感信息，一旦发现就立即告警通知绝不静默忽略。

运行层面的隔离

• OpenClaw 跑在独立的 Mac Studio 上，不和我日常开发的机器混用
• 敏感账号（公司邮箱、内部系统）不接入 OpenClaw
• 微信公众号等对外发布渠道，只开放”草稿保存”，不开放”直接发布”

信任边界

我现在的策略是：OpenClaw 能看到的东西，不会比我主动发给云端 AI 的内容更敏感。 你想想看，日常用 ChatGPT、Claude 的时候也会上传文件、发截图，那些数据的暴露面其实更大、更不可控。OpenClaw 反而是相对受控的——它的权限范围、它的行为日志、它的所有操作记录全部都在我本地机器上，随时可以审计。

安全的本质

安全从来不是 AI Agent 自带的默认行为，而是需要你在部署之前主动设计和配置出来的。养虾之前先把笼子扎紧，这个顺序千万不能反。

5. 使用体验：手机随时操控，数据不会丢

这一条其实被问得不算多，但我个人觉得它是 OpenClaw 用起来真正”顺手”的关键所在，值得单独拎出来说说。

Telegram：一个主 bot + 若干群聊

我的用法是这样：主 bot 用私聊做日常对话、发指令、问问题；不同的 daily task 转发到不同的群——Android 群放技术简报、论文精读、GitHub 动态，Daily 群放日报、周报、系统通知，其他群按需分流。为什么要分群？原因有三个：

1. 信息不混杂：技术内容和日常运维日志分开管理，想看哪个类别就进哪个群
2. 通知可控：重要的群打开通知提醒，不重要的直接静音，避免信息轰炸
3. 协作方便：有些群可以拉同事一起加入，共享信息源

数据落盘到 Obsidian

Telegram 在这个体系里只是”前端展示层”，真正重要的内容最终都会落盘到 Obsidian。这种架构设计意味着三件事：

• 不会丢：Telegram 的消息会随着时间被刷掉，但 Obsidian 里的 Markdown 文件会一直留存
• 可检索：Obsidian 的全文搜索能力远比 Telegram 的聊天记录搜索好用
• 可整理：后期可以随时对内容重新组织结构、打标签、建立双向链接

我现在 Obsidian 里的结构：

• OpenClaw定时任务/：所有定时任务的输出
• 论文/：论文精读三件套
• Personal-Knowledge/source/：知识库（1760 篇）
• X 文章/：归档的高价值 X 内容

手机随时访问

这一点的重要性比我最初想象的要大得多。出去玩的时候掏出手机打开 Telegram 就能直接给虾哥发指令，跟在电脑前操作没有区别；想看今天的日报打开 Obsidian 手机端文件已经通过 iCloud 同步过来了；遇到紧急情况需要调整任务也不用专门开电脑，手机上就能完成操作。我现在的日常习惯是早上醒来先刷一下 Telegram，看看昨晚虾哥跑了哪些任务、有没有异常，有问题的直接在手机上回复处理。外出的时候也能随时看一眼运行状态，心里有数。

架构总结

前端是 Telegram，后端是 Obsidian。 Telegram 解决的是”随时随地都能触达”的问题，Obsidian 解决的是”数据永远不会丢”的问题。两者结合在一起，才构成了一个真正好用的 24/7 全天候助手体验。

相关文章

1. 我把 OpenClaw 跑在本地三周后，发现它根本不是聊天机器人

关于我 && 博客

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

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

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

最近这段时间，我一直在本地重度使用 OpenClaw。最开始我也把它当成一个 AI 工具，但真正把它接进 Telegram、Obsidian、定时任务、本地模型和内容工作流之后，我发现自己完全想错了——它最厉害的地方，不是回答问题，而是开始替你持续工作。 它能接消息、调工具、跑定时任务、调用不同模型、沉淀长期记忆、把结果回写 Obsidian，还能把复杂任务分发给别的 Agent。你如果只把它当聊天机器人，那基本等于只用了它 20% 的能力。

对我这种既做 Android 系统性能优化、又要做内容、运营社群、维护知识库、跟进项目、写代码的人来说，OpenClaw 最值钱的地方只有一句话：它让我第一次有了”AI 不只是回答我，而是真的在替我持续推进工作”的感觉。

1. 我是什么时候开始真正用 OpenClaw 的？

按本地环境的初始化痕迹看，我是在 2026 年 2 月 16 日晚上开始把 OpenClaw 真正落到自己机器上的。这不是”装来看看”的那种体验，而是一路接进自己的日常工作流：消息入口、定时任务、Obsidian 知识库、日报周报、GitHub 监控、论文精读、内容素材整理、创作与复盘。所以我现在已经不把它当”一个工具”，而是把它当成一个本地 AI 调度层、一个定时执行系统、一个长期记忆系统、一个内容与知识的自动整理器，以及一个能和 Claude Code 配合工作的 AI 中枢。

2. 对一个 Android 系统工程师来说，OpenClaw 到底有什么用？

如果你本职是 Android 工程、系统优化、性能分析、稳定性治理，OpenClaw 最有价值的，不是”替你答一道题”，而是帮你处理那些持续重复、跨工具、跨时间、跨上下文的工作。我现在主要把它用在四类事情上。

第一类：信息流自动化

每日技术简报、每日信息简报、RSS 抓取、高价值内容筛选、GitHub Issue / PR 监控、每日论文精读——这些事情以前不是不会做，而是太碎了，做着做着就断。OpenClaw 的价值就是把这些动作从”靠意志力”变成”靠系统默认执行”。

第二类：知识库持续整理

我平时会收很多内容：技术文章、公众号、X 长文、RSS、项目资料、自己的思考。以前最大的问题是：收藏了但没整理，整理了但找不到，找到了也很难复用。OpenClaw 接进来之后，会持续做增量整理、结构修复、高价值归档、内容回顾和记忆维护。这件事对工程师特别重要，因为成长靠的不是”看过很多”，而是以后还能拿出来继续用。

第三类：日报、复盘和周检

这是很多人最容易忽略，但最有复利的一部分。我现在让 OpenClaw 长期跑每日早间提醒、今天干了啥日报、日终复盘、周沉淀、项目周审、三层记忆维护、冥想 / evolution log。说白了，OpenClaw 最让我上瘾的一点就是：它把那些”我知道很重要，但人很难长期坚持”的事情，变成了系统自动帮我做。

第四类：工程协作

它也能参与工程工作，比如跟踪 GitHub 仓库变化、巡检 issue / PR、整理代码上下文、调用其他 coding agent 干活。但这里我要先说结论：OpenClaw 不是为了替代 Claude Code，而是为了编排 Claude Code。 Claude Code 更像一个”坐在终端里的顶级程序员”；OpenClaw 更像一个”AI 运营系统”。

3. 为什么我旁边常备 Claude Code？

因为 OpenClaw 早期真的会挂。我说得更直白一点：升级后会报错、模型配置会出问题、定时任务会异常、某些工具链会失灵、某些路径写入会失败、旧会话和新配置不一定同步。这时候如果你只有 OpenClaw 自己，很多问题会非常烦，但如果旁边有个 Claude Code，事情就简单很多。

我的实际分工很清楚：OpenClaw 负责调度、记忆、定时、归档、消息、工作流；Claude Code 负责修 bug、查日志、看报错、做复杂代码改动、升级后救火。简而言之，Claude Code 像顶级程序员，OpenClaw 像 AI 运营系统。

4. 我的本地配置是什么？

我现在这套机器是 Mac Studio M1 Ultra，64GB 内存，48 核 GPU。这套配置对本地 Agent 工作流非常舒服，因为它允许我同时跑 OpenClaw 常驻服务、Ollama 本地模型、Obsidian、浏览器自动化、以及各种脚本和知识库任务。我现在不是单模型打法，而是云端 + 本地混合分工。

模型搭配思路很简单

高质量任务上云（长文、周报、复杂总结、关键判断），高频脏活本地跑（结构化任务、巡检、批处理、日常 worker）。我本地主要是这套分层：2B 做状态检查，4B 做轻量巡检，9B 是高频主力，27B / 35B 负责更重的本地任务。对我这台机器来说，9B 是最划算的日常工作马。

5. OpenClaw 最重要的，不只是模型，而是那几份核心文件

很多人第一次接触 OpenClaw，会把注意力放在模型、工具、命令行上。但我现在越来越觉得，它真正强大的地方反而是那几份被文件化的规则。我自己最看重的是这几类文件：

• SOUL.md：定义它的性格、风格、做事姿态
• USER.md：定义它到底在帮谁、目标是什么
• AGENTS.md：定义启动流程、记忆规则、安全边界、群聊行为
• MEMORY.md + memory/YYYY-MM-DD.md：一个存长期记忆，一个存每天发生了什么
• TOOLS.md：记录这台机器独有的本地环境信息

所以我现在对 OpenClaw 的理解是：它不是靠一大段系统提示词活着，而是靠一套”文件化人格 + 文件化记忆 + 文件化规则”活着。

6. Skill 机制为什么重要？

很多人把 Skill 理解成”插件”，但我觉得更准确的理解是能力包。一个 Skill 往往不只是多一个按钮，而是把适合什么场景、怎么调用工具、是否依赖脚本、有哪些边界和注意事项、在什么情况下该用或不该用这些东西一起打包了。比如 Obsidian、coding-agent、RSS、技能审计这些能力，一旦装对，OpenClaw 就不再只是聊天，而是真的开始干活。但我的建议也很明确：不要为了炫技乱装 Skill。 先装核心能力，真正跑两天确认稳定再继续扩；涉及高权限或外联的 Skill，先审计再决定要不要上。

7. Telegram 这块，单 Agent 多群聊能用，但后期最好按职责拆

如果你只在私聊里用 OpenClaw，其实还没完全体会到它的架构价值。它真正好玩的地方之一，是同一套系统可以接 Telegram，而且不一定只能对应一种工作方式。

方案 A：单 Agent 多群聊

优点是简单：配置快、起步成本低、前期验证最省事。但缺点也很明显：上下文容易串味，不同群的语气和任务容易混在一起，写作、日报、技术答疑很容易互相污染。

方案 B：按职责拆成多个 Agent

这才是我现在更认可的方式。比如 main 负责私聊主会话，daily 负责定时任务、日报、巡检、知识库类工作，writer 负责写作和内容精修类任务，专题 Agent 负责某个群、某条业务线或某个项目。这样做的好处是上下文隔离更清楚、角色边界更明确、不同群不会互相污染、后期扩展更轻松。我的建议是：前期可以单 Agent 多群聊，后期一定要按职责拆。

8. 安全不是附录，而是前置条件

这件事我非常建议一开始就讲透。因为 OpenClaw 一旦开始接本地文件系统、浏览器、命令执行、外部消息入口、本地和云端模型混合调用，它就不再是一个”无害聊天框”了，而是一个真正有行动能力的系统。这个时候，安全边界一定要先立住。

我现在比较认同的几条原则是：

• 长期记忆要分层：像 MEMORY.md 这种更私人、更稳定的信息，最好只在主会话里使用，不要在群聊上下文里乱读乱用
• 外部发送要谨慎：邮件、公开发帖、社交平台发布，最好默认需要确认，不要自动对外表达半成品
• 群聊不要越权：在群里它是参与者，不是代言人，更不是你本人
• Skill 不要乱装：尤其是涉及联网、执行脚本、读本地路径的能力，先审计再说
• 本地小模型别无脑给大权限：尤其是接网页、执行命令、读写路径时，要清楚工作区边界和工具边界

如果你后面还要接更多外部能力、浏览器自动化或者海外模型，通常还需要稳定的科学上网环境，但能力越多越要先把边界设计好。

9. 还有一个特别关键的问题：它到底留下了什么成果？

如果文章只写”它能做什么”，读者还是容易觉得这是一套概念系统。真正有说服力的，其实是这套系统已经在 Obsidian 里沉淀出了什么成果物。截至我写这篇文章时，我的 Obsidian 里已经能直接看到这些成果：

• OpenClaw定时任务/ 下有 214 篇 Markdown，说明日报、周检、归档、巡检已经不是口号，而是持续产出
• Personal-Knowlodge/source/ 下有 1760 篇 Markdown，知识库已经不是空目录，而是真在增长
• X 文章/ 下有 115 篇 Markdown，高价值外部内容已经沉淀成长期素材库
• 论文/ 下有 4 个标准化论文目录，每个目录都按”原 PDF + 翻译 + 精读”来组织
• 小说工坊/夜航之上（分章）/ 下有 58 个章节相关文件，它已经进入长期创作工作流，而不只是技术任务
• Ebook/ 里已经有实际 EPUB 成果，不只是笔记，还有可交付格式

如果你看几个具体例子，会更有感觉：OpenClaw定时任务/每日论文精读（Android+AI）/2026-03-08-每日论文精读（Android+AI）.md、Personal-Knowlodge/source/2026-03-08_wechat_Android_JNI原理分析.md、论文/AI-2026-03-08-Agentic-Reasoning-Framework/01-paper.pdf + 02-翻译.md + 03-精读.md、小说工坊/夜航之上（分章）/第018章-光标闪烁.md。这也是我现在最看重 OpenClaw 的地方：它不是做完就没了，而是在不断把工作变成资产。

10. 我踩过哪些坑？

这部分非常重要，因为它决定你会不会半路放弃。

坑 1：它初期真的没那么稳

你要接受一个现实：OpenClaw 很强，但并不等于”零维护”。我踩过的坑包括升级后报错、模型 allowlist 没配对、模型切换后旧会话不生效、定时任务能跑但落盘失败、外部路径权限问题、浏览器策略问题等等。

坑 2：Node 环境不要混

我后面把运行环境统一切到了 Homebrew Node，不再混用 nvm。这个动作非常有必要，不然后面升级、重启、路径都容易乱。

坑 3：Obsidian 外部路径别乱写

这是我踩得很深的一个坑。后来我收敛成非常明确的规则：

• 必须绝对路径
• 最稳是 exec + python/pathlib 落盘
• 不要想当然地直接 write/edit
• 同日内容尽量追加，不要覆盖

坑 4：自动化不是越多越好

一开始很容易上头，这个也想自动化、那个也想自动化。但最后你会发现任务太多就会带来重复、冲突、噪音、token 成本上升，结果反而没人真正看。所以更好的策略不是”全自动化”，而是先抓最有复利的几条主线。

11. 什么样的人适合用 OpenClaw？

我觉得最适合的是三类人。第一类是有持续输入和输出需求的人，比如工程师、独立开发者、技术博主、社群运营者、研究型创作者。第二类是愿意折腾工作流的人，如果你对”自动化、系统化、结构化”天然感兴趣，OpenClaw 会越用越顺手。第三类是想把 AI 真正接进工作流的人，如果你不是只想问几个问题，而是真的想做持续监控、自动整理、主动提醒、定时产出、长期记忆、跨平台内容协同，那 OpenClaw 会很有用。

12. 什么样的人不太适合？

也要说实话。只想把它当 ChatGPT 替代品的人、不想维护环境不想看日志的人、没有持续工作流的人，这三类人不一定用不好，但大概率感受不到它真正的价值。

13. 硬件怎么推荐？

如果你问我推荐什么机器，我会分三档说：

• 入门档：16GB 内存，主要跑云端模型，本地只做少量辅助
• 实用档：32GB 内存，能跑一部分本地模型，可以承接中轻量任务
• 舒服档：64GB 及以上，Mac Studio 或高配工作站级机器，云端 + 本地混合长期常驻

如果你真想把 OpenClaw 跑成”长期常驻、云端+本地混合、多任务并行”的系统，64GB 这一档体验会明显更稳。

14. 我现在对 OpenClaw 的最终判断

如果只让我用一句话总结，我会这么说：OpenClaw 最迷人的地方，不是它更会回答问题，而是它开始替你持续推进工作。 对 Android 系统工程师来说，它最有价值的地方不是取代你写代码，而是帮你把输入、整理、归档、跟进、输出、复盘、记忆这些本来散落在各处的事情串起来。它不是零门槛工具，它会挂、会报错、会踩坑，但一旦你把它跑顺，你会很明显地感受到：以前是你在推着工作流走，后来是系统在推着你往前走。 这就是我觉得它最值得折腾的地方。

结尾

如果你本身就是工程师、创作者，或者正在尝试把 AI 接进真实工作流，而不是只把它当聊天窗口，那 OpenClaw 值得你认真折腾一次。它不一定适合所有人，但一旦跑顺，带来的不是”对话效率提升”，而是工作流层面的复利。

相关文章

1. OpenClaw 常见问题解答：Token 消耗、能干什么、本地模型、隐私安全、使用体验

关于我 && 博客

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

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

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

本文是 Perfetto 系列的第十篇文章，聚焦 Binder 这一 Android 跨进程通信的核心机制。Binder 承载着大部分系统服务与应用的交互，也常常是性能瓶颈的源头。本文站在系统开发与性能调优的视角，结合 linux.ftrace（binder tracepoints + sched）、thread_state 轨道，以及 ART 的 Java Monitor Contention（通过 atrace 的 dalvik 类别采集）等信号，给出一套可直接落地的诊断流程，帮助初学者和进阶开发者定位耗时、线程池压力与锁竞争等问题。

本系列的目标，就是通过 Perfetto 这个工具，从一个全新的图形化视角，来审视 Android 系统的整体运行，同时也提供一个学习 Framework 的新途径。或许你已经读过很多源码分析的文章，但总是对繁杂的调用链感到困惑，或者记不住具体的执行流程。那么通过 Perfetto，将这些流程可视化，你可能会对系统有更深入、更直观的理解。

本文目录

• Perfetto 系列文章
• Binder 基础与案例
• Perfetto 观测准备
  • 其他 Binder 分析工具
• Binder 分析工作流
  • 步骤一：定位事务耗时
  • 步骤二：评估线程池与 Oneway 队列
  • 步骤三：排查锁竞争
• 最新平台特性与优化建议
• 总结
• 参考
• 关于我 && 博客

Perfetto 系列文章

1. Android Perfetto 系列目录
2. Android Perfetto 系列 1：Perfetto 工具简介
3. Android Perfetto 系列 2：Perfetto Trace 抓取
4. Android Perfetto 系列 3：熟悉 Perfetto View
5. Android Perfetto 系列 4：使用命令行在本地打开超大 Trace
6. Android Perfetto 系列 5：Android App 基于 Choreographer 的渲染流程
7. Android Perfetto 系列 6：为什么是 120Hz？高刷新率的优势与挑战
8. Android Perfetto 系列 7 - MainThread 和 RenderThread 解读
9. Android Perfetto 系列 8：深入理解 Vsync 机制与性能分析
10. Android Perfetto 系列 9 - CPU 信息解读
11. Android Perfetto 系列 10 - Binder 调度与锁竞争
12. 视频(B站) - Android Perfetto 基础和案例分享
13. 视频(B站) - Android Perfetto 分享 - 出图类型分享：AOSP、WebView、Flutter + OEM 系统优化分享

Binder 基础与案例

对于首次接触 Binder 的读者，理解它的角色和参与者至关重要。可以先把 Binder 粗暴地理解成“跨进程的函数调用”：你在一个进程里像调用本地接口一样写代码，真正的调用和数据传输则由 Binder 帮你完成。整体上它是 Android 的主力跨进程通信（IPC）机制，核心包含四个组件：

1. Client：应用线程通过 IBinder.transact() 发起调用，将 Parcel 序列化的数据写入内核。
2. Service（Server）：通常运行在 SystemServer 或其他进程中，通过 Binder.onTransact() 读取 Parcel 并执行业务逻辑。
3. Binder Driver：内核模块 /dev/binder 负责线程池调度、缓冲区管理、优先级继承等，是连接双方的“信使”。
4. Thread Pool：服务端通常维护一组 Binder 线程。需要注意的是，线程池并不是一开始就创建满的，而是按需创建。Java 层默认最大线程数约为 15 个 Binder 工作线程（不含主线程），Native 层通过 ProcessState 也可以配置最大线程数（默认值通常也是 15）。当所有 Binder 线程都忙碌时，新的请求就会在驱动层排队等待空闲线程。

为什么需要 Binder？

Android 采用多进程架构来隔离应用、提升安全性与稳定性。每个 APK 运行在独立的用户空间，当需要访问系统能力（相机、位置、通知等）时，必须跨进程调用 Framework 或 SystemServer。

传统 IPC 方案的局限：

Binder 在内核层解决了这些问题，提供了三个关键能力：一是身份与权限（基于 UID/PID 校验，确保调用方合法）；二是同步与异步调用（同步模式下 Client 等待 Server 返回，这是最常见的模式，而异步模式下 Client 发送后立即返回，适用于通知、状态上报等场景）；三是优先级继承（当高优先级 Client 调用低优先级 Server 时，Server 会临时提升优先级，避免优先级反转问题）。

因此，当应用进程在启动阶段通过 IActivityManager#attachApplication() 把自己“挂到” SystemServer 时，底层必然借助 Binder 把调用安全、可靠地传递给 system_server。

从 App 开发者视角的案例

假设我们在 Trace 里关注到 AIDL::java::IActivityManager::attachApplication::server。它对应的是应用进程通过 IActivityManager#attachApplication(...) 发起的一次同步 Binder 调用，服务端实现位于 system_server 的 ActivityManagerService。调用路径可以概括为：首先，在 Proxy 侧，应用进程通过 ActivityManager.getService() 拿到一个 IActivityManager 的代理对象（BinderProxy）；然后进行序列化，调用 attachApplication(...) 时，代理会把参数写入 Parcel，执行 transact()；接着是内核传输，Binder 驱动将该事务排入 system_server 的 Binder 线程队列，并唤醒一个空闲线程（例如 Binder:1460_5）；随后在 Stub 侧，ActivityManagerService（Stub）所在的线程被唤醒，读取参数并进入 attachApplication 的处理流程；最后是返回阶段，Service 处理完毕，将结果写入 Parcel，驱动唤醒原 App 线程，App 线程从 waitForResponse() 返回继续执行。

在 Perfetto 中，这条链路会显示为：Android Binder / Transactions 轨道上的一次事务（如果 trace 中能解析到 AIDL 信息，Slice 名称会类似 AIDL::java::IActivityManager::attachApplication::client/server，或在 SQL 中体现为 aidl_name=IActivityManager、method_name=attachApplication）；App 线程在 thread_state 里处于 S (Sleeping) 状态（同步调用时常见），且 blocked_function 通常涉及 binder_thread_read / epoll_wait / ioctl(BINDER_WRITE_READ)；SystemServer 的 Binder 线程出现 Running 切片；以及 Flow 箭头（Perfetto 会用箭头把 Client 的 transact 和 Server 的处理线程连接起来）。

Perfetto 观测准备

要在 Perfetto 中诊断 Binder，需要提前准备好数据源与 Trace 配置。

数据源与轨道总览

Binder 分析需要把「事务事件」和「线程调度/阻塞/锁」串起来。录制侧主要依赖 linux.ftrace（包含 Binder tracepoints、调度事件以及可选的 atrace 类别），再配合少量元数据源（进程/线程命名映射）。

linux.ftrace（内核层 + atrace） 是最通用、最基础的数据源，兼容所有 Android 版本。它直接读取内核的 ftrace 事件，包括 binder_transaction（事务开始）、binder_transaction_received（服务端收到事务）、binder_transaction_alloc_buf（缓冲区分配，诊断 TransactionTooLarge）等；再配合调度相关事件（sched_switch、sched_waking）即可还原出 “Client 发起调用 → 内核唤醒 Server 线程 → Server 处理 → 返回” 的链路。
另外，linux.ftrace 里还可以开启 atrace 类别来补充用户态 Slice：binder_driver/am/wm 等有助于解释系统服务语义；dalvik 则用于采集 ART 的 monitor contention（Java synchronized 竞争），从而在 UI 里出现 Thread / Lock contention 相关轨道。

linux.process_stats（元数据） 用于把 PID/TID 映射成进程名/线程名，方便在 UI 和 SQL 中阅读与过滤。开销极低，建议常开。

说明：Perfetto UI 中的 Android Binder / Transactions、Android Binder / Oneway Calls 轨道，以及 PerfettoSQL 标准库中的 android.binder / android.monitor_contention 模块，都是在 trace processor 侧基于上述原始事件解析/聚合出来的，并不是需要额外开启的“录制数据源”。

Trace Config 推荐

以下配置兼顾了兼容性与新特性，建议作为标准的 Binder 分析模板。将配置保存为 binder_config.pbtx 即可使用：

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
66
67