Android 应用内存分析工具

English Version | 中文版本

一套完整的 Android 应用内存分析工具集，支持一键 Dump连接设备的内存数据，并进行多数据源关联分析以深入洞察内存问题。

功能特性

核心能力

功能	说明	是否需要 Root
一键 Dump	从连接的设备一键采集所有内存数据	部分需要（见下表）
全景分析	多数据源关联分析（meminfo + gfxinfo + hprof + smaps）	否
HPROF 分析	Java 堆分析、泄漏检测、大对象追踪	否
SMAPS 分析	Native 内存映射、详细内存分类	是
Meminfo 分析	解析 dumpsys meminfo，包括 Native Allocations	否
Gfxinfo 分析	解析 dumpsys gfxinfo，获取 GPU/图形统计	否

Root 权限需求

数据源	无 Root	有 Root
dumpsys meminfo	✅ 完整数据	✅ 完整数据
dumpsys gfxinfo	✅ 完整数据	✅ 完整数据
hprof dump	⚠️ 仅 debuggable 应用	✅ 所有应用
smaps	❌ 权限拒绝	✅ 完整数据

快速开始

环境要求

• Python 3.8+
• ADB（Android Debug Bridge）在 PATH 中或放在 tools/ 目录
• 已连接的 Android 设备并开启 USB 调试

Android 17 / API 37 兼容性说明

• Demo APK 已升级到 compileSdk = 37、targetSdk = 37，demo 版本为 1.1.0，并继续保留 Android 16 edge-to-edge 与 16 KB page size Native .so 对齐。
• 工具支持 Android 4.0 到 Android 17+ 的输入格式，解析逻辑覆盖 Scudo、GWP-ASan、DMA-BUF、stack/TLS、JIT cache 等较新的分配器与映射命名。
• 全景分析现在以 dumpsys meminfo 原始行序作为主账本，在每个可比较行上附加同类 smaps PSS/SwapPSS 与映射证据；memtrack 行明确标为不可比较。仅输入 smaps 时仍可输出 native allocator、graphics、DMA-BUF、code、stack 和 top mapping。
• Android 17 app memory limits 是 Android 17 设备上的 all-app 运行时行为。Live dump 现在会在依赖 PID 的采集前归档 exit_info.txt、memory_limiter_status.txt、package UID、进程列表、Android release/sdk、build fingerprint 和 page size。
• smaps 采集按以下兜底顺序执行，兼容更多设备：
  1. adb shell cat /proc/<pid>/smaps
  2. adb shell su -c "cat /proc/<pid>/smaps"
  3. adb shell su 0 cat /proc/<pid>/smaps
• PID 获取优先使用 pidof，失败时回退到解析 ps -A。
• Android 17 构建、memory-limiter、运行时和证据清单见 Android 17 / API 37 适配 Review。
• Android 16 与 16 KB page size 基线见 Android 16 / API 36 适配 Review。

安装

git clone https://github.com/Gracker/Android-App-Memory-Analysis.git
cd Android-App-Memory-Analysis

使用方法

一键 Dump 并分析（推荐）

# 列出设备上正在运行的应用
python3 analyze.py live --list

# Dump 并分析指定应用
python3 analyze.py live --package com.example.app

# 快速模式（跳过 hprof 以加快速度）
python3 analyze.py live --package com.example.app --skip-hprof

# 仅 Dump 不分析
python3 analyze.py live --package com.example.app --dump-only -o ./dumps

全景分析（多数据源关联）

# 分析已有的 dump 目录
python3 analyze.py panorama -d ./dumps/com.example.app_20231225_120000

# 分析单独的文件
python3 analyze.py panorama -m meminfo.txt -g gfxinfo.txt -H app.hprof -S smaps.txt

# 只分析特权进程映射
python3 analyze.py panorama -S smaps.txt --json -o smaps_panorama.json

单独文件分析

# 分析 Java 堆（HPROF）
python3 analyze.py hprof demo/hprof_sample/heapdump_latest.hprof.gz

# 分析 Native 内存（smaps）
python3 analyze.py smaps demo/smaps_sample/smaps

# 分析 meminfo
python3 analyze.py meminfo dump/meminfo.txt

# 分析 gfxinfo
python3 analyze.py gfxinfo dump/gfxinfo.txt

# 传统联合分析（HPROF + smaps）
python3 analyze.py combined -H demo/hprof_sample/heapdump_latest.hprof.gz -S demo/smaps_sample/smaps

# 增强联合分析（支持 meminfo 口径，包含 mtrack）
python3 analyze.py combined --modern --hprof demo/hprof_sample/heapdump_latest.hprof.gz --smaps demo/smaps_sample/smaps --meminfo demo/smaps_sample/meminfo.txt --json-output report.json

# 一键运行内置 demo（自动使用 hprof+smaps+meminfo）
python3 analyze.py combined --demo --json-output demo_report.json

说明：

• combined 默认是传统模式（combined_analyzer.py）；当提供 --modern、--meminfo、--pid、--json-output 或 --demo 时，自动切换增强模式。
• 增强模式下使用 -p/--pid 会自动抓取 smaps，并尝试抓取 dumpsys meminfo -d。
• 为规避仓库单文件限制，示例 HPROF 以 heapdump_latest.hprof.gz 提交。统一入口 analyze.py 可直接读取 .hprof.gz；如果旧的 .hprof 示例路径不存在但同目录存在 .hprof.gz，会自动 fallback 到压缩样本。

AI 证据上下文与 Skills

仓库现在提供模型无关的 ai-context 协议：它先校验 artifact、区分内存账本、识别缺失/冲突信息、选择带官方来源的理论条目，再把上下文交给用户选择的 AI。它不会自动上传文件或调用外部模型。

新的 live dump 会同时生成结构化 manifest.json，把用户跳过、设备不支持、权限拒绝、命令失败与真实采集成功分别保留，不再全部折叠成“文件缺失”。

常见的 RD 入口是“目录优先”：把 QA 交付的所有材料下载到同一个目录，只提供这个目录和问题标题/现象即可。上下文会递归盘点每个普通文件，把文件名当提示而不是真相，按内容识别支持的证据，保留多份同类 artifact，并显式报告无法分类的文件和扫描限制，不要求用户先整理材料。识别出的证据也会补充意图路由，因此“内存变多”这类模糊描述仍能评估目录实际支持的 Java、Native、Graphics 或系统压力分支。除了 dump 和报告，它也能识别 Android/logcat 日志（纯文本或 gzip）以及 PNG/JPEG/WebP 截图。

纯文本、gzip 与 bugreport ZIP 日志会被有界扫描 LeakCanary、资源泄漏、OOM、GC、JNI、图形/数据库/Binder、LMKD 与 kernel OOM 信号，但不会嵌入原始日志行或截图像素。日志信号绑定行号/哈希（ZIP 还绑定成员路径）；截图只记录尺寸/哈希，必须由 AI 实际查看后才能作为可见观察使用。

python3 analyze.py ai-context \
  -d ./qa-handoff/ANDROID-1234 \
  --question "退出页面后 Native 内存仍持续增长" \
  --format json \
  -o android-memory-context.json

可导入 AI 项目的 Skills 位于 skills/：

• android-memory-evidence：校验残缺/错误材料并给出精确补证命令；
• android-memory-diagnose：结合理论、artifact 与版本边界给出详细诊断；
• android-memory-remediate：在 owner/机制被证明后修改代码并做同场景验收。

安装完整公开包到当前 AI 项目（需要 Node.js 18+ 与 Python 3.8+）：

npx skills add Gracker/Android-App-Memory-Analysis \
  --skill '*'

全局安装到 Codex 时增加 --agent codex --global。Evidence Skill 已内置校验过的 runtime 和知识目录，安装副本不需要另外 clone 本仓库，也不需要设置 ANDROID_MEMORY_ANALYSIS_ROOT。完整分析器 checkout 只作为 live capture、panorama、diff 和 Perfetto helper 的可选增强层。

需要二次分析时，仍把同一个完整 QA 目录交给 Skill，并说明是质疑旧结论还是在其上补充。Skill 会重新扫描整个目录，识别旧 context/报告，比较新增、变更、缺失和未变证据，并强制把每条重要旧结论标记为确认、修订、撤回或未决。旧材料在目录外时，可用可重复的 --previous-context 与 --previous-analysis 显式传入。

完整架构、上下文 schema、安装/更新、隐私边界与验证入口见 Android 内存 AI 工作流。

分析内容

全景分析报告

全景分析先从大家熟悉的 dumpsys meminfo 表格进入，保留原始顺序中的 每一行，再把 smaps 作为下钻旁证，而不是另起一份替代性的汇总：

[ meminfo 主账本 + smaps 逐行旁证 ]
分类              Mem PSS  PrivDirty  SwapPss  smaps PSS  差值  状态
Native Heap          80860      80824        25      80860    +0  aligned
Dalvik Heap          59439      59420        69      59439    +0  aligned
EGL mtrack           54432      54432         0          -     -  not-comparable
...
TOTAL               337790     293788       162          -     -  see-total

逐行解释：
- Native Heap：smaps 补充 Scudo primary/secondary 映射，但不覆盖 meminfo 值。
- EGL mtrack：保留驱动/HAL 归因，不与 `/proc/<pid>/smaps` 强行相减。

🖼️ Bitmap 深度分析:
------------------------------
  Bitmap (malloced):     27 个    6.78 MB
  Bitmap (nonmalloced):   8 个   11.59 MB
  GPU Cache:             15.34 MB
  GraphicBuffer:         12.45 MB

📈 Native 内存追踪:
------------------------------
  可追踪 Native:        28.45 MB (83.2%)
  未追踪 Native:         5.76 MB (16.8%)

  ⚠️ 警告: 存在较大的未追踪 Native 内存

🎨 UI 资源统计:
------------------------------
  Views: 1,234
  ViewRootImpl: 3
  Activities: 5
  WebViews: 0

核心分析特性

1. meminfo 逐行主账本：保留熟悉的每个 meminfo 分类和字段
2. smaps 行级旁证：补充分类 PSS/SwapPSS、allocator subtype、映射与显式对账
3. Bitmap 关联分析：将 Java Bitmap 对象与 Native 像素内存关联
4. Native 内存追踪：识别可追踪 vs 未追踪的 Native 分配
5. GPU 内存分析：GraphicBuffer 和 GPU 缓存使用情况
6. UI 资源统计：View 层级和 Activity 泄漏检测
7. 异常检测：自动检测潜在问题并发出警告

项目结构

Android-App-Memory-Analysis/
├── analyze.py              # 主入口
├── tools/
│   ├── hprof_parser.py     # HPROF 文件解析器
│   ├── smaps_parser.py     # smaps 文件解析器
│   ├── meminfo_parser.py   # dumpsys meminfo 解析器
│   ├── gfxinfo_parser.py   # dumpsys gfxinfo 解析器
│   ├── panorama_analyzer.py # 多数据源关联分析器
│   ├── combined_analyzer.py # HPROF + smaps 联合分析器
│   ├── memory_analyzer.py  # 增强联合分析器（meminfo/mtrack 关联）
│   ├── live_dumper.py      # 设备实时 Dump
│   ├── hprof_dumper.py     # HPROF Dump 工具
│   └── adb                 # ADB 二进制文件（可选）
├── demo/
│   ├── hprof_sample/       # 最新示例 HPROF 与分析结果
│   ├── smaps_sample/       # 最新示例 smaps/meminfo/showmap/gfxinfo 与报告
│   └── memory-lab/         # 用于回灌最新样本数据的 Demo APK 工程
├── docs/
│   ├── en/                 # 英文文档
│   └── zh/                 # 中文文档
└── pic/                    # 文档图片

文档

详细的分析结果解读指南：

• 中文学习路径

  • 分析结果解读指南
  • meminfo 解读
  • smaps 解读
  • Android 17 / API 37 适配 Review
  • Android 16 / API 36 适配 Review
  • 教学实践手册
  • Demo APK 实战案例

• 英文学习路径

  • Analysis Results Guide
  • Meminfo Interpretation
  • SMAPS Interpretation
  • Android 17 / API 37 Adaptation Review
  • Teaching Playbook

数据源说明

数据源	命令	提供的信息
smaps	cat /proc/<pid>/smaps	详细内存映射
hprof	am dumpheap <pkg> <path>	Java 堆对象和引用链
meminfo	dumpsys meminfo <pkg>	汇总 + Native Allocations（Bitmap 精确统计）
gfxinfo	dumpsys gfxinfo <pkg>	GPU 缓存、GraphicBuffer、帧率统计

相关工具

本工具集可与以下 Android 内存分析工具配合使用：

• Android Studio Profiler: 实时内存监控
• LeakCanary: 自动内存泄漏检测
• MAT (Memory Analyzer Tool): 深度 HPROF 分析
• Perfetto: 系统级追踪

贡献

欢迎贡献代码！请随时提交 Pull Request 或开启 Issue。

许可证

本项目采用 Apache License 2.0。三个可独立安装的 Skill 都包含同一份许可证文本。