Crash & ANR 排查根治
× AI 提效实战

全景与方法论

稳定性问题分类地图

先建立地图,再谈排查。Android 的"闪退/卡死"只有四大类,每类的证据、工具、章节都不同:

为什么必须治:平台的硬红线

Google Play 的 Android Vitals 定义了"坏行为阈值":用户感知崩溃率 ≥1.09% 或 用户感知 ANR 率 ≥0.47%(全设备口径),应用在整个商店的曝光都会被降权;任一单机型上 ≥8%,该机型降权且商店页可能挂警告。稳定性不是技术洁癖,是流量问题。

贯穿全文的五步方法论

1. 现象固定 —— 拿到最原始的证据:完整堆栈/trace/日志,设备、系统版本、App 版本、复现路径。禁止在"二手描述"上开工。
2. 定位 —— 从堆栈找到"第一现场":你的代码在哪一帧?混淆了先还原(retrace)。
3. 归因 —— 回答"为什么会走到这一步":空从哪来?锁被谁持有?内存被谁吃掉?——用工具取证,不靠猜。
4. 根治 —— 修根因而不是包一层 try-catch;修完必须有一条能证明修复的验证路径(复现步骤/回归测试/灰度指标)。
5. 防复发 —— 同类问题的防线:lint 规则、StrictMode、CI 检查、监控告警。修一个 bug,堵一类 bug。

第一次值班：前 30 分钟照表执行

第一课:读懂一次崩溃

堆栈解剖:四个信息一眼定位

FATAL EXCEPTION: main                                    ← ① 崩在哪个线程(main=主线程)
Process: com.example.app, PID: 12345
java.lang.NullPointerException:                          ← ② 异常类型:决定去哪一章查图鉴
    Attempt to invoke virtual method 'int java.lang.String.length()'
    on a null object reference                           ← ③ 异常消息:哪个对象、什么操作
  at com.example.app.OrderDetail.bind(OrderDetail.kt:87) ← ④ 第一现场:自己包名的最上一帧
  at com.example.app.OrderAdapter.onBindViewHolder(OrderAdapter.kt:42)
  at androidx.recyclerview.widget.RecyclerView...        ← 框架帧:通常只是"路过"
Caused by: ...                                           ← 有 Caused by 时,根因在最底下那个!

• 读栈顺序:先看异常类型和消息 → 再从上往下找第一帧属于自己包名的代码 → 有 Caused by 链时,一路追到最底层的那个才是根因;
• 混淆包还原:线上堆栈是 a.b.c(Unknown Source) 时,用 R8 的 mapping.txt 还原:retrace mapping.txt stacktrace.txt(每个发版的 mapping 必须归档!);
• 抓现场三板斧:adb logcat -b crash 只看崩溃缓冲区;adb logcat --pid $(adb shell pidof -s 包名) 只看自己进程;崩溃瞬间没抓到就 adb bugreport 事后取(见 07 章)。

复现:排查价值的一半

拿到堆栈后第一件事不是改代码,是建立稳定复现——能复现的 bug 已经修好一半。三个层级依次尝试:精确步骤复现(用户路径回放)→ 条件复现(特定数据/网络/权限状态)→ 压力复现(monkey / 反复旋转屏幕 / 开发者选项"不保留活动"模拟进程重建)。

# 三个经典压力复现开关
adb shell settings put global always_finish_activities 1   # 不保留活动:暴露进程重建类崩溃
adb shell monkey -p com.example.app --throttle 300 -v 5000 # monkey 随机事件流
# 开发者选项 → 模拟辅助显示/切换语言/切换深色模式:暴露配置变更类崩溃

证据交接单：任何人接手都能继续

问题 ID / 首次时间 / 当前负责人：
影响：版本、轨道、用户数、Crash/ANR 率、核心链路
分类：Java/Kotlin | Native | ANR | 系统退出
已对版：mapping / native Build ID / 源码 commit
分布：App 版本、OS、机型、国家、feature flags
主证据：完整 stack/trace/tombstone 链接（不只贴截图）
确定事实：只写证据直接支持的结论
候选假设：按概率×影响排序；每条附证伪方法
止血状态：回滚/开关/降级/未处理，含时间
下一步：命令或测试、负责人、截止时间

这份交接单也是第 09 章的「崩溃上下文包」雏形。先让人类能无损接手，再把同一份结构化证据交给 AI；否则 AI 只会更快地产生未经验证的猜测。

把上面的 NPE 真正走完

假设第 87 行是 order.title.length，继续向上追到 Java/JSON 边界，发现服务端旧数据缺少 title，Kotlin 把 platform type 当成非空。完整闭环应是：

1. 验证根因：用缺 title 的固定响应复现；确认同样数据进入 mapper 后产生 null，而正常响应不触发；
2. 根治：在 DTO → Domain 边界把字段声明为 String?，按业务规则返回可展示的占位值或明确的 MalformedOrder，UI 只接收非空 Domain；
3. 回归：覆盖缺字段、空字符串、正常值和旧缓存反序列化；运行 release + R8 构建，复跑原路径；
4. 预防：开启严格反序列化/schema 监控，为 Java platform type 边界加 lint/review 规则，并给 Crashlytics key 记录响应 schema 版本。

常见 Crash 图鉴与根治

图鉴不是让你背异常名，而是帮你从「异常消息」跳到下一条取证动作。表中的根治方案都遵循同一原则：修复状态和边界，不吞异常。

生命周期类崩溃：真正的问题是「状态过期」

1. 进程重建：系统杀掉后台进程后会用 savedInstanceState 重建 Activity/Fragment。禁止依赖静态单例仍有数据；以持久 ID 恢复，ViewModel 的 SavedStateHandle 保存最小状态。
2. Fragment View 生命周期：Fragment 还活着不代表 View 还活着。观察 LiveData/Flow 时绑定 viewLifecycleOwner，在 onDestroyView 清 binding。
3. 异步结果过期：网络/定位/支付回调回来时页面可能已销毁。让任务随 lifecycleScope/viewModelScope 取消，或把结果写入状态容器，由当前界面渲染。

来源：Android：保存 UI 状态 · Fragment 生命周期 · Kotlin 协程异常处理

ANR 深入：从主线程快照追到阻塞源

先认清超时类型

八类高频根因

• 主线程 I/O：文件、数据库、DNS、网络、Binder 或大 JSON/Proto 序列化；
• SharedPreferences：commit() 同步落盘；apply() 虽异步写盘，但待完成写入会在 Activity/Service 生命周期切换时由框架等待，仍可能通过 QueuedWork 造成 ANR。新项目优先 DataStore；
• 锁竞争/死锁：main 等后台线程持有的锁，而后台又等 main 或同步 Binder；
• 同步 Binder：你的栈停在 BinderProxy.transactNative，真正慢点可能在 system_server 或另一个进程；
• 广播和服务：onReceive、冷启动初始化、onStartCommand 做重活；goAsync() 忘记 finish()；
• 布局风暴：深层嵌套、反复 requestLayout、Compose 高频无效重组导致 measure/layout 超时；
• GC 抖动：短时间大量分配使 main 频繁停顿；单看一次 GC 不足以定罪，要结合 Perfetto 的分配与调度时间线；
• 系统负载：main 处于 Runnable 却长时间没 CPU、system_server 锁住或 GPU hang，可能不是 App 自身长任务。

读 trace：沿锁链找真正持有者

"main" prio=5 tid=1 Blocked
  | group="main" sCount=1 dsCount=0 flags=1 obj=0x... self=0x...
  | sysTid=18420 nice=-10 cgrp=default sched=0/0 handle=0x...
  | state=S schedstat=(...) utm=82 stm=21 core=4 HZ=100
  | held mutexes=
  at com.example.Cache.read(Cache.kt:48)
  - waiting to lock <0x07c1> (a java.lang.Object)
  at com.example.HomeActivity.onResume(HomeActivity.kt:91)

"sync-worker" prio=5 tid=27 TimedWaiting
  - locked <0x07c1> (a java.lang.Object)
  at android.os.BinderProxy.transactNative(Native method)
  at com.example.remote.ISyncService$Stub$Proxy.refresh(...)

1. 看 main 状态：Runnable 表示可能在算或饿死；Blocked 表示等 monitor；Waiting/TimedWaiting 要看在等谁；Native 需结合顶部 native 方法和 Perfetto。
2. 找等待对象：复制 <0x07c1>，全文搜索 locked 或「held by thread N」，定位持锁线程。
3. 继续追链：持锁线程若又等 Binder/另一把锁，继续追到最终运行者；同时看 system_server 与 Binder 线程栈。
4. 校准快照：trace 可能在超时后才抓到；顶部是 nativePollOnce 且 main 已空闲时，优先看同一 cluster 的其他事件和 Perfetto，而非硬猜。

根治与提前暴露

if (BuildConfig.DEBUG) {
    StrictMode.setThreadPolicy(
        StrictMode.ThreadPolicy.Builder()
            .detectAll()
            .penaltyLog()
            .penaltyDeath()
            .build()
    )
}

• I/O 与序列化下移到有界 dispatcher，并设计取消、超时和结果回主线程的边界；
• 不要持锁执行 I/O/Binder/回调；缩小临界区，以不可变快照或单线程状态机替代共享可变状态；
• 广播只调度工作；需要保证执行时用合适的 WorkManager/JobScheduler，不在 onReceive 里等结果；
• ANR-Watchdog 能在线程长时间不响应时提前抓自有线程栈，但会误报 debugger、系统饿死和长帧，也看不到系统完整 ANR 上下文；它是补充观测，不替代 Vitals、ExitInfo 和 bugreport。

来源：Android：Diagnose and fix ANRs · SharedPreferences API · Android Vitals：ANR

Native Crash：从信号到源码行

先拿到 tombstone：四条路

下面五个区块怎么读之前，读者手上通常还没有 tombstone 文件——这一步经常被跳过。四条获取路径：

tombstone 五个区块怎么读

下面是 AOSP 官方文档给出的 tombstone 格式示例（历史机型，字段结构与当前一致，只是十六进制地址位宽因 ABI 而异）：

*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
Build fingerprint: 'Android/aosp_flounder/flounder:5.1.51/AOSP/enh08201009:eng/test-keys'
Revision: '0'
ABI: 'arm'
pid: 1656, tid: 1656, name: crasher  >>> crasher <<<
signal 6 (SIGABRT), code -6 (SI_TKILL), fault addr --------
Abort message: 'some_file.c:123: some_function: assertion "false" failed'
    r0 00000000  r1 00000678  r2 00000006  r3 f70b6dc8
    r4 f70b6dd0  r5 f70b6d80  r6 00000002  r7 0000010c
    r8 ffffffed  r9 00000000  sl 00000000  fp ff96ae1c
    ip 00000006  sp ff96ad18  lr f700ced5  pc f700dc98  cpsr 400b0010
backtrace:
    #00 pc 00042c98  /system/lib/libc.so (tgkill+12)
    #01 pc 00041ed1  /system/lib/libc.so (pthread_kill+32)
    #02 pc 0001bb87  /system/lib/libc.so (raise+10)
    #03 pc 00018cad  /system/lib/libc.so (__libc_android_abort+34)
    #04 pc 000168e8  /system/lib/libc.so (abort+4)
    #05 pc 0001a78f  /system/lib/libc.so (__libc_fatal+16)
    #06 pc 00018d35  /system/lib/libc.so (__assert2+20)
    #07 pc 00000f21  /system/xbin/crasher
    #08 pc 00016795  /system/lib/libc.so (__libc_init+44)
    #09 pc 00000abc  /system/xbin/crasher
Tombstone written to: /data/tombstones/tombstone_06
*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

1. Abort message：主动失败通常已把条件写出来，先处理它——上面这条已经明写了断言文件、行号与条件；
2. signal / code / fault addr：这条示例是 SIGABRT（主动终止，fault addr 为空）；换成 SIGSEGV 时这一行会是 signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x0 这种形式——0x0 或很低地址常是空指针及字段偏移；高位随机地址常见野指针/越界，但必须结合 map 和 sanitizer 证据；靠近 stack guard 要考虑栈溢出；
3. backtrace：每行格式是 #帧号 pc 相对地址 库路径 (符号名+偏移)（如上面的 #00 pc 00042c98 /system/lib/libc.so (tgkill+12)）；找到首个属于自己 so 的 pc offset，不要停在 libc 的 memcpy/free；
4. registers：结合崩溃指令判断哪个寄存器是坏指针；
5. memory map：确认 fault addr 落在已映射区、权限是否匹配，并核对库的 Build ID。符号文件必须与线上 APK 的 ABI 和 Build ID 精确对应。

符号化三件套

# 先列出候选目录；用 readelf -n 比对 tombstone 中 Build ID，禁止静默选旧 hash
find app/build/intermediates/cxx -type d \
  -path '*/RelWithDebInfo/*/obj/arm64-v8a' -print
$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-readelf \
  -n 候选目录/libfoo.so | grep 'Build ID'

# 确认 Build ID 后，把 ACTUAL_HASH 换成匹配目录
SYMBOL_DIR=app/build/intermediates/cxx/RelWithDebInfo/ACTUAL_HASH/obj/arm64-v8a
$ANDROID_NDK_HOME/ndk-stack \
  -sym "$SYMBOL_DIR" \
  -dump tombstone.txt

# 单个 so + 相对 PC；-C 反混淆 C++ 名，-f 显示函数，-e 指定 ELF
$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-addr2line \
  -C -f -e libfoo.so 0x1234

# Crashlytics NDK 符号上传；路径按构建产物调整
firebase crashlytics:symbols:upload \
  --app=1:1234567890:android:abcdef app/build/native-debug-symbols

内存错误工具怎么选

从命中点回到源码根治

• UAF/双重释放：明确对象所有权，优先 RAII 与 std::unique_ptr；跨线程传递共享生命周期时才使用 shared_ptr，并设计停止/回收顺序；
• 越界：所有长度与偏移都在同一处校验，使用带长度的容器/视图；对解析器加入截断、超长、畸形输入的单测与 fuzz；
• JNI 契约：检查 Java 异常、局部/全局引用和线程附着；禁止跨线程保存局部引用，缓存 method/class ID 时处理 ClassLoader 与卸载边界；开 CheckJNI 让这类问题在开发期就报出来，而不是等到线上 native crash（见下方 CheckJNI 小节）；
• 栈溢出：消除无界递归和巨型栈数组，改为迭代/堆分配并对深度设上限；
• 防复发：修复后用同一 sanitizer 重跑原始输入，再加入 release 符号上传校验、ABI 冒烟、native 单测/fuzz 与线上 GWP-ASan 采样。

CheckJNI：把 JNI 契约违反提前到开发期报错

模拟器默认开启（logcat 能看到 CheckJNI is ON）；真机开启方式：

# 无 root，仅对之后启动的进程生效
adb shell setprop debug.checkjni 1

# 有 root，从系统层面常驻开启
adb shell stop && adb shell setprop dalvik.vm.checkjni true && adb shell start

android:debuggable="true" 的 App 同样会自动启用。CheckJNI 会在下面这些场景直接报错阻断，而不是让它悄悄跑出一个 native crash：

局部引用最常见的两个坑：循环里批量创建局部引用不释放（该用 DeleteLocalRef 或 PushLocalFrame/PopLocalFrame 框起来）；用 AttachCurrentThread 附加的原生线程里创建的局部引用不会自动释放，直到线程 detach，必须手动删除。全局引用最常见的坑是用 == 比较两个引用是否指向同一对象——必须用 IsSameObject，官方原文强调"不能假设对象引用是常量或唯一的"。

来源：Android NDK：Debug your project · AOSP：Diagnose native crashes · Memory error debugging and mitigation · JNI Tips（CheckJNI 与引用管理）

工具箱与用法：先问证据在哪

工具给证据，证据决定根治

命令行取证

# 崩溃缓冲区；保存原始时间、PID、TID
adb logcat -b crash -v threadtime -d > crash.log

# 只看当前进程；App 重启后 PID 会变化
adb logcat --pid=$(adb shell pidof -s com.example.app) -v threadtime

# 一次性系统现场包
adb bugreport bugreport.zip

# 20 秒 Perfetto：调度、频率、窗口、绘制、Binder、运行时
adb shell perfetto -o /data/misc/perfetto-traces/anr.perfetto-trace \
  -t 20s sched freq idle am wm gfx view binder_driver hal dalvik input res memory
adb pull /data/misc/perfetto-traces/anr.perfetto-trace .

把 trace 拖进 ui.perfetto.dev，先看 main 的 Thread State：Running 是真在执行，Runnable 长段可能是 CPU 饥饿，Sleeping/Blocked 要沿唤醒者或锁链追。Android 旧版本若直接 pull 无权限，可用 adb shell cat 路径 > 本地文件。

开发期护栏与内存工具

• StrictMode：在 debug 尽早暴露主线程磁盘/网络、泄漏的 Closeable 与注册对象；penaltyDeath 只在开发构建使用；
• LeakCanary：对已销毁对象保留弱引用，触发 GC 后仍不可达预期却未回收时 dump heap，自动找引用链；它定位泄漏，不解释所有 OOM；
• Memory Profiler / MAT：先比较两个时点的存活对象，再在 dominator tree 按 retained heap 找「删掉它能释放最多内存」的支配者；
• CPU / Energy Profiler：复现路径前后录制，关注主线程热点、系统调用和唤醒；采样适合低干扰，方法插桩更细但会改变时序；
• Compose Layout Inspector：看重组次数/跳过次数，确认状态读取范围；计数高只是线索，结合 Perfetto 判断是否真的造成帧预算超支；
• Native sanitizer：测试环境用 ASan/HWASan 提高命中率，线上用 GWP-ASan 抽样，详见 04。

启动时回收上次退出证据

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
    val am = getSystemService(ActivityManager::class.java)
    val exits = am.getHistoricalProcessExitReasons(packageName, 0, 8)
    exits.filter { it.timestamp > lastUploadedAt }.forEach { info ->
        val kind = when (info.reason) {
            ApplicationExitInfo.REASON_ANR -> "ANR"
            ApplicationExitInfo.REASON_CRASH -> "JAVA_CRASH"
            ApplicationExitInfo.REASON_CRASH_NATIVE -> "NATIVE_CRASH"
            ApplicationExitInfo.REASON_LOW_MEMORY -> "LOW_MEMORY"
            else -> "OTHER_${info.reason}"
        }
        uploadExit(kind, info.timestamp, info.importance, info.description)
    }
}

来源：Logcat 命令行 · Perfetto：Recording system traces · ActivityManager 退出历史 API

Play Console 与 Firebase：线上问题的两副镜头

Android Vitals：先看影响，再切维度

「用户感知」不是所有后台异常的总和。指标按每日活跃用户中至少经历 1 次事件的用户占比计算：用户感知 Crash 指 App 正在显示 Activity 或运行前台服务期间的未处理崩溃；当前用户感知 ANR 只计入 Input dispatching timed out。Play 当前核心坏行为阈值为：崩溃率 1.09%、ANR 率 0.47%；单手机型号均为 8%，Wear OS 单手表型号则分别为 Crash 4%、ANR 5%。Play 每日用最近 28 天数据评估质量；超线可能影响可见度并展示商店警告。

1. 先看新增 cluster：同一版本突然出现的新问题，通常比多年存量更有可操作性；
2. 按 App 版本切：确认是新版本引入，还是旧版本用户仍未升级；
3. 按 OS / 机型切：单厂商、单 GPU、单 Android 版本尖峰，优先查兼容性与系统栈；
4. 按国家/轨道切：网络、区域配置、灰度人群可能改变触发条件；
5. 比较 affected users 而非只看次数：一个用户循环崩 100 次与 100 个用户各崩 1 次，治理优先级不同。

Crashlytics：把复现上下文塞进每条事件

Firebase.crashlytics.apply {
    setUserId(hashUserId(accountId))       // 不上传邮箱/手机号等直接标识
    setCustomKey("app_track", buildTrack)
    setCustomKey("feature_flags", flagDigest)
    setCustomKey("screen", currentRoute)
    setCustomKey("order_state", orderState.name)
    log("checkout: confirm tapped")
}

try {
    repository.refresh()
} catch (e: RecoverableDomainException) {
    Firebase.crashlytics.recordException(e) {
        key("endpoint", "orders")
        key("retry_count", retryCount)
    }
    showRecoverableError(e)
}

• Keys：使用稳定、低基数、可聚类的维度。当前 Android SDK 最多保留 64 个 key/value；不要把 timestamp 或随机 ID 塞进异常 message 破坏聚类；
• Logs：记录关键状态转移，不要复制整份网络响应。单 session 日志有大小上限，旧日志会被滚动删除；
• User ID：使用内部匿名/哈希标识，并遵守隐私与删除流程；
• Non-fatal：只记录「已处理但需要统计」的异常。把每次 404/取消都 recordException 会挤掉真正问题、增加成本并污染告警；
• Velocity alert：关注短时间激增，用来触发止血，不替代按受影响用户和版本分布排优先级；
• BigQuery：需要自定义趋势、feature flag 交叉分析或长期留存时导出；用版本采用率与 crash-free/事件率一起判断灰度是否继续。

符号发布链：没上传 mapping，前面几章全部作废

02-04 章的崩溃图鉴、tombstone 解剖、ANR trace 分析，全部建立在"线上堆栈能还原成源码"这个前提上。mapping/符号没上传，Vitals 和 Crashlytics 看到的就是一堆 a.b.c 和裸地址——这一步经常被跳过，直到线上出问题才发现堆栈看不懂。

// build.gradle.kts，release 变体开启 mapping 与 native symbol 自动上传
android {
  buildTypes {
    getByName("release") {
      isMinifyEnabled = true
      configure<com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension> {
        mappingFileUploadEnabled = true   // 默认就是 true，混淆产物才需要它
        nativeSymbolUploadEnabled = true  // 默认 false（避免拖慢构建），有 native 代码务必手动开
      }
    }
  }
}

来源：Firebase：Get deobfuscated crash reports · Firebase：Get and customize NDK reports

Gemini AI insights 与 MCP

Firebase 控制台的 AI insights 可对 issue 生成摘要、潜在根因和调试建议，但它不能读取或修改你的本地代码。官方 Firebase MCP server 可让编码代理读取 issue、事件样本、堆栈、用户/事件数、版本维度与 notes，也能新增/删除 note、更新或关闭 issue；它使用运行环境中 Firebase CLI 的当前凭据。数据交给外部 AI 工具后如何处理取决于该工具条款，因此应使用最小权限账号、限制可用项目，所有写操作要求人工确认并保留审计。截至 2026-07-15，该能力仍为 Experimental，可能发生不兼容变更，接入时固定版本并准备人工回退。

来源：Android Vitals · 自定义 Crashlytics 报告 · Crashlytics MCP · BigQuery 导出

测试机数据导出：把事故现场完整带走

bugreport 是无 root 设备的系统快照

adb bugreport bugreport.zip
unzip -l bugreport.zip | less

# 常用服务快照
adb shell dumpsys meminfo com.example.app
adb shell dumpsys gfxinfo com.example.app framestats
adb shell dumpsys activity activities
adb shell dumpsys dbinfo com.example.app
adb shell dumpsys batterystats --charged com.example.app

# 系统 DropBox 事件索引；具体 tag 因系统版本而异
adb shell dumpsys dropbox --print SYSTEM_TOMBSTONE
adb shell dumpsys dropbox --print data_app_anr

ApplicationExitInfo：启动后回收上一轮 ANR trace

Android 11（API 30）起，可在 App 下次启动时查询历史退出原因；ANR 记录常带系统抓取的 trace。它非常适合补齐「用户设备无法连 adb」的线上证据，但不保证每条记录都有 trace，也不是实时 ANR 回调。

class ExitInfoReporter(
    private val context: Context,
    private val store: ExitCursorStore,
    private val upload: suspend (ExitEnvelope) -> Unit
) {
    private val collectMutex = Mutex()

    suspend fun collect() = collectMutex.withLock {
      withContext(Dispatchers.IO) {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) return@withContext

        val am = context.getSystemService(ActivityManager::class.java)
        val records = am.getHistoricalProcessExitReasons(
            context.packageName, 0, 32
        ).sortedWith(compareBy({ it.timestamp }, { it.processName }, { it.reason }))

        for (info in records) {
            val eventKey = listOf(
                info.timestamp, info.processName, info.reason, info.status
            ).joinToString(":")
            if (!store.shouldAttempt(eventKey, System.currentTimeMillis())) continue

            try {
                val trace = info.traceInputStream?.use { input ->
                    input.readAtMost(512 * 1024)        // API 30 兼容且限制体积
                }
                upload(
                    ExitEnvelope(
                        eventKey = eventKey,
                        timestamp = info.timestamp,
                        processName = info.processName,
                        reason = info.reason,
                        status = info.status,
                        importance = info.importance,
                        description = info.description,
                        pssKb = info.pss,
                        rssKb = info.rss,
                        traceGzip = trace?.let(::gzip)
                    )
                )
                store.markUploaded(eventKey)
            } catch (retryable: RetryableUploadException) {
                store.scheduleRetry(eventKey, retryable) // 有上限的指数退避，不因离线次数直接死信
                continue
            } catch (io: IOException) {
                store.scheduleRetry(eventKey, io)
                continue
            } catch (permanent: PermanentUploadException) {
                store.markDiscarded(eventKey, permanent) // 仅 schema/权限等确定永久错误
                continue                                // Error 与未知异常不吞，继续上抛
            }
        }
      }
    }

    private fun InputStream.readAtMost(limit: Int): ByteArray {
        val output = ByteArrayOutputStream(minOf(limit, 64 * 1024))
        val buffer = ByteArray(16 * 1024)
        var remaining = limit
        while (remaining > 0) {
            val count = read(buffer, 0, minOf(buffer.size, remaining))
            if (count == -1) break
            output.write(buffer, 0, count)
            remaining -= count
        }
        return output.toByteArray()
    }
}

• 在冷启动关键路径之外调用，放到受约束的后台任务；shouldAttempt/scheduleRetry 持久化下次时间并做有上限的指数退避，离线不能只按次数死信；只有明确的 schema/权限等永久错误才丢弃。不要捕获全部 Throwable；
• 本地与服务端都按 eventKey（timestamp + process + reason + status）幂等去重，并保存 App 版本、设备/OS、feature flags；
• 对 REASON_ANR、REASON_CRASH、REASON_CRASH_NATIVE、REASON_LOW_MEMORY 分开治理；REASON_USER_REQUESTED 不是应用崩溃；
• trace 可能在进程后来以其他原因退出时仍随记录保留，必须结合 reason、timestamp 和内容判断。

无法连接 adb 的设备

指导测试/用户在开发者选项选择「提交错误报告/获取错误报告」，说明问题发生时间、App 版本和操作路径；部分厂商另有日志助手或售后拨号码，必须走公司隐私审批与厂商文档，不能让用户盲目上传整机日志。

来源：Capture and read bug reports · dumpsys · ApplicationExitInfo

疑难杂症侦查术：把不可观测变成可验证

# fd 与线程是两条独立预算；/proc 可见性受版本与权限限制
PID=$(adb shell pidof -s com.example.app)
adb shell ls -l /proc/$PID/fd | wc -l
adb shell 'cat /proc/'$PID'/status | grep -E "Threads|VmRSS"'
adb shell cat /proc/$PID/limits

PID=$(adb shell pidof -s com.example.app)
adb shell kill -3 $PID        # 向 ART 进程请求 Java 线程 dump，输出位置依系统而异
adb logcat -d -v threadtime > manual-thread-dump.log

git bisect start
git bisect bad BAD_COMMIT
git bisect good LAST_KNOWN_GOOD
# 每次用同一自动化复现脚本判定，再执行 git bisect good/bad
git bisect reset

侦查结束必须落成防线

来源：Android Vitals · Android 内存管理概览 · AOSP 调试入口 · Git bisect 文档。启动保险丝、feature flag 二分与多次 kill -3 对比属于工程实践；信号输出、/proc 可见性和厂商日志入口随 Android/ROM/权限变化，必须在目标设备验证。

AI 结合：证据质量决定排查上限

AI 排查质量 ≈ 证据完整度 × 问题约束 × 验证反馈。模型擅长跨堆栈、源码、diff 和分布找关联，但看不到你没提供的 mapping、运行时状态和失败样本。先把输入标准化，再谈提示词技巧。

崩溃上下文包：给人和 AI 的统一输入契约

五段式提示词：可直接复制

你是 Android 稳定性负责人。请把证据与假设严格分开；禁止虚构源码、
API 行为或缺失日志。证据不足时先指出缺口，不要直接给补丁。

[主证据]
粘贴完整 retrace stack / ANR trace / tombstone，保留线程、Caused by、Build ID。

[环境与分布]
App 版本与 commit：___；Android/机型/ABI：___；
受影响用户与时间趋势：___；feature flags/业务状态：___；正常对照组：___。

[相关源码与变更]
粘贴第一业务帧、调用方、生命周期/并发相关代码，以及近期 diff。

[任务与输出]
1. 先列「确定事实」，每条引用具体证据行；
2. 给最多 3 个根因假设，按概率×影响排序；
3. 每个假设给证伪条件、最小验证命令/测试和预期结果；
4. 只有验证通过后才给最小修复，并说明生命周期、并发、兼容性边界；
5. 给回归测试、灰度指标、防复发项；
6. 输出：事实表 → 假设表 → 下一步 → 修复候选 → 风险/未知项。

三种高价值任务型提示词

AI 防幻觉验证协议

1. 引用证据：所有事实必须指向堆栈帧、源码行、分布或官方文档；无法引用则标为假设。
2. 反例检查：主动问「什么证据会推翻这个结论？正常对照为何没触发？」。
3. 工具验证：让 AI 给命令，但由受控环境执行；命令输出回填后再更新概率。
4. 最小补丁：只改根因路径，附失败测试；不接受大范围“顺手重构”。
5. 独立复核：第二代理只找错误归因、未覆盖边界和回归风险，不看第一代理的“信心”。
6. 线上闭环：测试通过仍不是结案；灰度观察新增 cluster、用户率和副作用，达到窗口后再关闭 issue。

来源：Firebase：Crashlytics AI assistance · Claude Code Best Practices · Codex Best Practices

AI 工作流与原创 crash-triage Skill

工作流一：官方 Crashlytics MCP × 编码代理

# 方案 A（交互式官方推荐）：安装 Firebase 插件；与方案 B 二选一
claude plugin marketplace add firebase/firebase-tools
claude plugin install firebase@firebase
claude plugin marketplace list

# 方案 B（生产固定版）：不安装上述插件，手动只接 Crashlytics
# 首次解析当前版本后，把具体版本号写入配置与变更记录
FIREBASE_TOOLS_VERSION=$(npm view firebase-tools version)
claude mcp add firebase-crashlytics npx -- \
  -y firebase-tools@$FIREBASE_TOOLS_VERSION mcp \
  --dir "$(pwd)" --only crashlytics
claude mcp list

# 查看并审查该固定版本实际暴露的工具；后续不要自动跟随 latest
npx -y firebase-tools@$FIREBASE_TOOLS_VERSION mcp \
  --only crashlytics --generate-tool-list

1. 先让代理「列出本版本新增的 Top 5 issue，按 affected users 与增长率排序，暂不改代码」；
2. 对第 1 个 issue 拉取多个事件样本、版本/设备分布与 notes，生成第 09 章的证据包；支持 MCP prompt 的客户端可运行 crashlytics:connect；
3. 让代理定位相关源码与 diff，只输出事实/假设/验证；验证后再写失败测试与最小补丁；
4. 由人审核后，代理可把调查摘要和 PR 链接写回 note；关闭 issue 是写操作，必须人工确认。

工作流二：告警 → CI 自动分诊，默认只读

triage-schema.json（Claude 与 Codex 共用同一输出契约）

{
  "type": "object",
  "properties": {
    "facts": {"type": "array", "items": {"type": "string"}},
    "hypotheses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cause": {"type": "string"},
          "verification": {"type": "string"}
        },
        "required": ["cause", "verification"],
        "additionalProperties": false
      }
    },
    "risk": {"type": "string"}
  },
  "required": ["facts", "hypotheses", "risk"],
  "additionalProperties": false
}

#!/usr/bin/env bash
set -euo pipefail

ISSUE_JSON="$1"                         # webhook worker 生成的脱敏证据包，不接受任意 URL
test -f "$ISSUE_JSON"
test "$(wc -c < "$ISSUE_JSON")" -lt 10485760
test -f triage-schema.json

OUTPUT_DIR=${OUTPUT_DIR:-"$(pwd)/triage-output"}
mkdir -p "$OUTPUT_DIR"
RUN_DIR=$(mktemp -d)
trap 'rm -rf "$RUN_DIR"' EXIT
cp "$ISSUE_JSON" "$RUN_DIR/issue.json"
cp triage-schema.json "$RUN_DIR/triage-schema.json"
cd "$RUN_DIR"                            # 空目录：不挂载源码、凭据、用户配置
SCHEMA=$(jq -c . triage-schema.json)

AI_PROVIDER=${AI_PROVIDER:-claude}       # claude 或 codex，只运行一个
case "$AI_PROVIDER" in
  claude)
    cat issue.json | claude --bare -p \
      "只做只读分诊。区分事实与假设；输出根因候选、验证步骤、回归风险；禁止改代码。" \
      --permission-mode plan --tools "" \
      --output-format json --json-schema "$SCHEMA" \
      | jq -e '.structured_output' > "$OUTPUT_DIR/triage-result.json"
    ;;
  codex)
    cat issue.json | codex exec --ephemeral --ignore-user-config --ignore-rules \
      --skip-git-repo-check --sandbox read-only \
      --output-schema triage-schema.json \
      "分析 stdin 中的脱敏证据包；只做分诊，不修改文件" \
      -o "$OUTPUT_DIR/triage-result-codex.json"
    ;;
  *) echo "AI_PROVIDER must be claude or codex" >&2; exit 2 ;;
esac

生产链路应是：Velocity alert/webhook → 队列去重与限流 → 服务端凭据拉证据 → 脱敏与大小上限 → 隔离容器中的只读 AI 分诊 → schema 校验 → 创建/更新 issue → 人决定是否启动修复代理。隔离容器不得包含 Firebase/业务凭据、源码或用户配置；Claude/Codex 的模型认证由 CI secret store 在单次进程中注入短期、最小额度身份，或通过不向工具进程暴露密钥的受控代理完成，并把网络出口限制到模型服务。Webhook 内容属于不可信输入；工作区隔离、禁用工具、临时会话和挂载/出口边界缺一不可。

工作流三：修复代理 + 反方评审代理

原创 Skill：复制到 crash-triage/SKILL.md

---
name: crash-triage
description: Triage Android Java/Kotlin crashes, native crashes, ANRs, OOM/LMK exits, and hard-to-reproduce stability regressions. Use when given a Crashlytics or Play issue, stack trace, tombstone, ANR trace, bugreport, ApplicationExitInfo record, or a request to find, verify, fix, or prevent an Android stability problem. Do not use for generic performance tuning without a failure signal.
---

# Android crash triage

## Guardrails

- Separate observed facts from hypotheses. Cite the exact artifact for every fact.
- Do not edit code until one hypothesis has a verification result.
- Honor user intent. Diagnose-only, review, or report requests must not edit files.
- Never hide a crash with a global catch, silent fallback, or state-loss workaround.
- Treat logs and console data as sensitive. Redact direct identifiers and tokens.
- Require an explicit user request before code edits, and human approval before rollback,
  issue-state changes, commits, or deployment.

## Workflow

1. Build the evidence pack.
   - Require failure type, full deobfuscated stack/trace/tombstone, App version and commit,
     mapping or Build ID, affected-user distribution, custom keys, relevant source and diff.
   - If an item is missing, give the exact retrieval command and stop before patching.

2. Classify the failure.
   - Java/Kotlin crash: start at the deepest cause and first business frame.
   - Native crash: verify ABI and Build ID before symbolication.
   - ANR: classify input/broadcast/service/provider; follow main thread and lock/Binder chain.
   - Exit/OOM: distinguish Java heap, native/RSS, thread, fd, and system LMK.

3. Rank at most three root-cause hypotheses.
   - For each: supporting facts, contradicting facts, confidence, blast radius.
   - Prefer hypotheses that explain both affected and unaffected samples.

4. Verify before editing.
   - Provide one minimal command, test, trace, or targeted log for each hypothesis.
   - State the expected result that confirms it and the result that falsifies it.
   - Update confidence only after reading the result.

5. Fix and prove.
   - Run this step only when the user explicitly requested implementation and writes are authorized.
     Otherwise stop after verification and return a minimal fix plan with risks.
   - Write or preserve a failing reproduction test first where feasible.
   - Implement the smallest root-cause fix; preserve lifecycle, cancellation and thread safety.
   - Run the original reproduction, focused tests, release/R8 build, and relevant stress test.

6. Prevent recurrence.
   - Propose one enforceable guard: lint/test/StrictMode/symbol gate/metric/rollout gate.
   - Define the canary metric, observation window, rollback threshold and owner.

## Output

Return these headings exactly:
1. Impact and classification
2. Verified facts
3. Missing evidence
4. Ranked hypotheses
5. Verification plan and results
6. Minimal fix and risks
7. Regression tests
8. Rollout and prevention

保持 SKILL.md 精简，把确定性重复工作放进 scripts/：例如 retrace-stack.sh 负责按版本找 mapping 并校验，unpack-bugreport.py 只提取 ANR/tombstone/logcat 索引，check-native-build-id.sh 比对 tombstone 与 so。脚本必须对缺失/多候选版本失败退出，禁止“猜一个最像的”。团队 schema、严重级别和隐私规则放 references/，按需加载，不把所有背景塞进 Skill 主体。

如何判断 AI 真的提效，而不是多产文档

来源：Firebase Crashlytics MCP · Claude Code 非交互模式 · Codex 非交互模式 · Codex Skills

治理体系：从救火到稳定性复利

四道防线

SLO 与错误预算：远低于平台红线

Play 坏行为阈值是商店惩罚线，不是质量目标。团队应按业务关键度、历史基线和用户规模设更严格 SLO，并把新增问题与存量债务分开。下面只是示例起点，不是 Android 官方目标：

值班 SOP：定级 → 止血 → 根治

1. 定级：按用户影响、增长速度、核心链路与可恢复性，而不是异常名字；启动风暴/数据损坏优先级最高。
2. 止血：暂停灰度、回滚、关开关、服务端降级或恢复模式；记录每个操作时间与效果。
3. 根治：建立证据包、验证假设、最小修复、回归与灰度；止血补丁不能代替永久修复。
4. 复盘：回答「为何产生、为何测试没挡住、为何监控没更早发现、什么自动机制能防同类」。

一页式结案清单

• 影响与版本范围已量化；Play 与 Crashlytics 口径已注明；
• 主证据已对版，根因有可复现/可证伪结果，不是仅凭 AI/聚类推断；
• 止血与永久修复分别记录，补丁有原始复现和边界回归；
• 灰度观察窗、成功指标、回滚阈值与 owner 已明确；
• 同类防线已进入 lint/test/StrictMode/发布门禁/监控之一；
• Crashlytics/工单 note 链接 PR、验证证据和 RCA，方便下一位值班者追溯。

官方资源索引

来源：Android Vitals · Google Play 技术质量 · Firebase Crashlytics