# T-AND-012 MediaPipe 初始化崩溃修复

- **状态**: done
- **依赖**: T-AND-003
- **文档**: v1.6 §6.6

## 问题

真机上报 `mediapipe 初始化失败：ExceptionInInitializerError: null`。

`ExceptionInInitializerError` 的 message 为 `null` 时**没有任何信息量** ——
它的真因一定在 `cause` 链里，通常是 `UnsatisfiedLinkError`（native 库加载失败）。

## 诊断结论

按文档 §6.6 的五步逐条核对，本项目实际命中 **三处**：

| # | 项 | 结论 |
|--|--|--|
| 1 | 拿到真因 | ❌ 原实现只把 `t.message` 拼进提示，`null` 就此丢失。**已修**：`PoseDiagnostics.causeChain()` 展开完整因果链，`rootCause()` 取最内层，并把"缺少的具体库"一并显示 |
| 2 | ABI 核对 | ⚠️ release 只打包 `arm64-v8a` / `armeabi-v7a`（正确），但**没有任何机制阻止把 release 装到 x86_64 模拟器**上 —— 那必然缺 native 库。**已加**：`PoseDiagnostics.abiMismatchHint()` 会比较 `Build.SUPPORTED_ABIS` 与 APK 内 `lib/<abi>/` 实际目录，直接给出"APK 只包含 X，而模拟器（x86_64）需要 Y"的结论；构建期另有 `verifyReleaseAbi` 任务核对 |
| 3 | native 解压方式 | ❌ 未设置。AGP 8 的 release 默认 `extractNativeLibs=false`，MediaPipe 的 JNI 加载对它有历史兼容问题。**已修**：`packaging { jniLibs { useLegacyPackaging = true } }` |
| 4 | R8 细化 | ❌ 只有 `-keep class com.google.mediapipe.**`，缺少 **native 方法**的保留规则（R8 仍可能裁剪方法名导致 JNI 注册失败）。**已修**：补 `-keepclasseswithmembernames class com.google.mediapipe.** { native <methods>; }`，并用 `-printseeds` 输出 seeds 供发布前核对（实测保留 **20169** 条 MediaPipe 条目） |
| 5 | 版本与 minSdk | ✅ `minSdk = 29 ≥ 24`，`tasks-vision 0.10.35` 兼容 |

**未换库**：诊断指向的是集成配置（native 解压 + R8 + ABI），不是 MediaPipe 本身不稳定，
因此保留 MediaPipe（33 点契约零成本），备选方案（ML Kit Pose Detection 等）
仅在后续实测仍不稳定时启用。文档 §6.6 的备选 A/B/C/D 已在任务说明中记录取舍。

## 改动清单

| 文件 | 改动 |
|--|--|
| `app/build.gradle.kts` | `jniLibs.useLegacyPackaging = true`；新增 `verifyReleaseAbi` 任务（ABI 集合必须恰为 `[arm64-v8a, armeabi-v7a]`，每个 ABI 下必须有 MediaPipe native 库，模型资源必须存在） |
| `app/proguard-rules.pro` | 补 native 方法保留规则；输出 `seeds.txt` / `usage.txt` 供发布前核对 |
| `pose/PoseDiagnostics.kt` | **新增**：纯函数诊断（cause 链 / 真因 / native 判定 / ABI 比对 / 汇总报告），可在 JVM 单测逐条核对 |
| `pose/PoseDetector.kt` | 读自身 APK 的 `lib/` 目录得到实际 ABI；失败时输出完整诊断并写入 `ConnectionLog`；顺手修复 `lastTimestampMs` 未回写导致 `frame_id` 恒为 0 的缺陷 |
| `util/ConnectionLog.kt` | **新增**：连接与初始化诊断日志（可导出） |
| `AndroidManifest.xml` + `res/xml/file_paths.xml` | FileProvider（导出日志用） |

## 验收（文档 §6.6）

| 验收项 | 结果 |
|--|--|
| release 包在真机（arm64）上初始化成功率 100%，连续 30 分钟无崩溃 | ⚠️ 需真机实测（本环境无设备）。构建期已强制 ABI 与 native 库齐备，R8 保留已用 seeds 核对 |
| 崩溃时 `CrashLogger` 能给出 `Caused by` 真因（含 ABI / 库名） | ✅ `PoseDiagnostics` 输出「真因（cause 链最内层）」「缺少的具体库」「设备 ABI / APK 内 ABI」与判定结论；`PoseDiagnosticsTest` 12 项逐条断言 |
| 若换库：仍输出 MediaPipe 33 点顺序 | ✅ 未换库，33 点契约不变（`KeypointFrameTest` 金标准向量仍通过） |
| 相机权限被拒 / 模型缺失 / 无 Play 服务时给出可读提示，不白屏不崩溃 | ✅ 权限分支已有独立界面与 Robolectric 用例；初始化失败 `catch Throwable` 并显示诊断；`ScreenCompositionTest` 覆盖组合稳定性 |

## 发布前必做（三条命令）

```bash
./gradlew verifyReleaseAbi
#   -> [abi] release APK 包含 ABI：[arm64-v8a, armeabi-v7a]
#   -> [abi] arm64-v8a / armeabi-v7a 下 MediaPipe native 库存在

grep -c "^com.google.mediapipe" app/build/outputs/mapping/release/seeds.txt
#   -> 必须 > 0（实测 20169）；为 0 说明 MediaPipe 被整体裁掉，release 必崩

unzip -p app/build/outputs/apk/release/app-release.apk classes.dex | grep -c poselandmarker/PoseLandmarker
#   -> 必须 > 0，确认关键类仍在 dex 中
```