1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | perfetto-trace-analysis-android-skills |
| 项目自述名称 | perfetto-trace-analysis（SKILL.md frontmatter name 字段） |
| 作者/维护者 | Google LLC（Android 官方团队） |
| 来源链接 | https://github.com/android/skills/tree/main/profilers/perfetto-trace-analysis |
| 许可证 | Apache License 2.0（GitHub API 确认，仓库级；SKILL.md frontmatter 指向仓库根 LICENSE.txt） |
| GitHub Stars / Forks | 6,796 / 411（GitHub API；为 android/skills 整个合集仓库的数据，不代表本子技能单独热度） |
| 最新版本 | SKILL.md frontmatter last-updated：2026-05-14；该子目录最近一次提交：2026-05-15 |
| 安装方式 | Android CLI 一条命令，或手动复制到对应 Agent 的 skills 目录（详见第 10 章） |
2. 功能介绍与亮点
这是 Google Android 官方团队发布的结构化技能，指导 Agent 分析 Perfetto 性能追踪文件（trace），系统化定位 Android 应用卡顿（jank）、内存问题或延迟问题的根本原因。
亮点：
- 强制“证据链”工作方式：要求 Agent 在目标 trace 文件同目录下维护一份调查记录文件，只记录已核实的事实（时间戳、slice 名称、线程状态），不允许写入未经验证的猜测，避免 AI 在分析中过早下结论。
- 假设检验循环：每一轮分析都要求先基于领域提示与用户描述提出假设、说明证据来源，再用宽泛到精确的 SQL 查询收集数据、逐步验证——明确要求区分“线程在运行”与“线程在等待 CPU/被阻塞”，禁止仅凭 slice 耗时长就断定是计算瓶颈。
- 6 份“领域提示”参考文档：分别覆盖 CPU、图形、I/O、进程间通信、内存、功耗六大性能领域，每份文档收录多条经验证的分析技巧，相当于把资深性能工程师的排查经验固化进了技能本身。
- 禁止过早收尾：明确要求即使已找到一个明显瓶颈，也必须继续系统性排查是否存在其他独立问题，并定期做全局复核（如按耗时排序检查全部 slice），避免遗漏。
- 配套 Perfetto SQL 查询参考（约 21 万字节），规定了生成有效查询的执行协议，降低 SQL 编造 schema 的风险。
3. 适用场景
固定分类：工程效率与代码质量。
适用于已经采集到 Perfetto trace 文件、需要排查 Android 应用卡顿、界面掉帧、启动慢、内存增长或跨进程通信延迟等性能问题的工程师，尤其适合面对复杂 trace 数据、缺乏系统化排查经验的中初级 Android 开发者。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。可用 Android CLI
android skills add --skill=perfetto-trace-analysis --agent=claude --project=.安装，也可直接复制到.claude/skills/（依据：官方仓库 README 与第三方综述 androiddevkit.com 均给出针对 Claude Code 的具体安装步骤）。 - Codex：✅ 官方确认支持。Codex 的 CLI、IDE 插件与 App 均原生识别该开放 Agent Skills 格式，可放入
.agents/skills目录，并支持$perfetto-trace-analysis显式调用语法（依据：androiddevkit.com 给出的 Codex 专门设置说明）。 - OpenClaw：⚠️ 未经本技能专门验证。OpenClaw 采用同一开放的 SKILL.md 规范（name + description frontmatter），格式层面理论兼容，但未找到该技能在 OpenClaw 上被实际使用的记录。
- Hermes Agent：⚠️ 未经本技能专门验证，理由同上。
需注意：官方 Android CLI 默认仅为 Gemini 与 Antigravity 自动安装技能，面向 Claude Code / Codex 需手动指定 --agent 参数或手动复制（详见第 10 章）。
5. 推荐理由
Perfetto trace 里往往是几十万行的 slice 和线程状态记录，人工排查费时费力，而 AI 在缺乏方法论约束时容易“看起来在分析、实则在编故事”——把某个耗时长的 slice 直接当成瓶颈、找到第一个异常就草草收工。这份官方技能用强制证据链、假设检验循环与“禁止过早收尾”的规则，把严谨的性能排查方法论固化成了可执行流程，同时用 6 份分领域提示文档把专家经验直接喂给 Agent，能显著降低分析过程中“看似合理但实际错误”的结论出现概率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google LLC（Android 官方团队）出品；仓库 6,796 stars 属整个 android/skills 合集，不代表本子技能独立热度（已在第 1 章注明）；第三方技术博客 androiddevkit.com 对本技能有具体评价与安装指引，但未见 GitHub Issues / Reddit 等平台的独立用户讨论 |
| 可用性 | 8 | 一条 CLI 命令或手动复制即用；SKILL.md 结构清晰，配 6 份领域提示文档 + 1 份约 21 万字节的 SQL 参考文档，文档深度扎实；该子目录最近一次提交为 2026-05-14，约 3 个月前；需要用户预先具备 Perfetto trace 文件与本地 trace_processor 工具作为前置条件，因此未给满分 |
| 安全性 | 9 | 详见下方安全检查清单 |
| 综合 | 8.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令及权限范围 | 指导调用本地 trace_processor 工具对已有 trace 文件执行只读 SQL 查询，范围明确限定在用户主动提供的 trace 文件内，无系统级操作 |
| ② 运行时联网外发 | 无，全程为本地 trace 文件分析与本地记录文件读写 |
| ③ API Key / 凭据 | 不需要 |
| ④ SKILL.md 与脚本可疑指令 | 已通读 SKILL.md 全文及全部参考文档，内容均为性能分析方法论与查询规范，未发现越权指令或夹带与任务无关的推广内容 |
| ⑤ 作者/组织信誉 | Google LLC，Android 官方团队，与 Perfetto 追踪工具同属 Google 生态 |
| ⑥ License | Apache License 2.0，明确（仓库级，GitHub API 确认） |
| ⑦ 最近维护时间 | 该子目录 2026-05-14 有提交，约 3 个月前，非弃置项目 |
7. 跟同类 Skills 相比的优势
| 名称 | 来源 | 定位 | 与本技能的差异 |
|---|---|---|---|
| perfetto-trace-analysis（本推荐） | android/skills | 端到端的 trace 根因分析：假设提出→数据收集→验证→排除其他瓶颈的完整调查协议 | — |
| perfetto-sql | 同合集内 android/skills |
专注把自然语言查询意图翻译为合法的 Perfetto SQL 并执行，是单点查询生成工具 | 只覆盖“怎么写对 SQL”这一步，不含假设检验、跨进程依赖追踪、多瓶颈排查等调查协议；两者可搭配使用，本技能覆盖的调查流程更完整 |
| SmartPerfetto | 独立第三方开源项目（androidperformance.com 团队） | 把 AI 辅助 Perfetto 分析产品化为一套可复用平台，通过 MCP 接口封装 trace_processor 调用与结构化场景策略 |
定位是独立部署的分析平台而非可直接安装的 SKILL.md 技能，需要额外搭建 MCP 服务；本技能是开箱即用、零额外基础设施的轻量方案 |
| camerax | 同合集内 android/skills |
CameraX 相机功能实现与迁移 | 面向功能开发而非性能诊断，与本技能的分析场景不重叠 |
8. 用户评价
- 第三方技术博客 AndroidDevKit（2026-06-29 发布《How to use Android Skills with Cursor, Claude Code, and Codex》）将该技能列入其 Android Skills 推荐清单，评价 Android Skills 类工具“最适合用在给出似是而非错误答案代价很高的场景”（来源：androiddevkit.com/blog/android-skills-cursor-claude-codex）。
- 该技能目前在 GitHub Issues、Reddit 等平台尚无具名用户评价。
9. 其他补充
同仓库 perfetto-sql 与本技能共享同一份约 21 万字节的 Perfetto SQL 标准库参考文档，两者搭配使用可覆盖从查询生成到根因定位的完整链路（详见第 7 章）。
10. 安装使用方式
方式一：Android CLI（官方推荐，一条命令）
android skills add --skill=perfetto-trace-analysis --project=.需先安装 Android CLI；未指定 --agent 时默认为 Gemini 与 Antigravity 自动安装，面向 Claude Code / Codex 需显式使用 --agent 参数指定，具体取值以官方文档为准。
方式二：手动安装（适用于 Claude Code / Codex）
git clone https://github.com/android/skills.git
cp -r skills/profilers/perfetto-trace-analysis <你的项目>/.claude/skills/perfetto-trace-analysis复制时需保留 SKILL.md 与 references/ 目录的完整结构。安装后无需重启，向 Agent 提供一个 Perfetto trace 文件并描述性能问题（如“这个 trace 里应用为什么卡顿”）即可自动触发，也可按各 Agent 自身语法显式调用。
11. 注意事项
- 使用前必须已采集好 Perfetto trace 文件，并在本地安装
trace_processor工具，两者缺一不可，无法脱离它们独立使用。 - 分析过程会在 trace 文件同目录生成调查记录文件（
[trace_filename]_analysis.md），批量分析多个 trace 时注意目录整洁。 - OpenClaw、Hermes Agent 的兼容性未经本技能专门验证，使用前建议先小范围试点。
- 官方 Android CLI 默认只为 Gemini / Antigravity 自动安装，Claude Code / Codex 用户需手动复制或显式指定
--agent参数。