@_nazmiforreal/flutter-ota 0.1.26 → 0.1.28

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/CrashGuard.kt

@@ -0,0 +1,271 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.content.Context
+import android.os.Build
+import android.os.Process
+import android.util.Log
+import java.io.File
+
+/**
+ * 熔断器：防止补丁导致启动崩溃时无限重启。
+ *
+ * 状态机（解耦版）：
+ * 1. Application.attachBaseContext → [markBooting] 写 patch_loading=true（commit 同步）+ pid
+ * 2. Dart 首帧 → [markBootSuccess] 立即清 patch_loading=false + crash_count=0；
+ *    **保留** last_booting_pid 给下次冷启动的 ExitInfo 查询
+ * 3. Dart 首帧 + verifyAfter 秒 → 卸载 Dart 错误钩子（仅 Dart 层动作，不触原生）
+ *
+ * 下次冷启动 [shouldLoadPatch] 综合判定：
+ *
+ * - **API 30+ 且有 pid 记录**：通过 [ActivityManager.getHistoricalProcessExitReasons]
+ *   拿到精确死因。覆盖首帧前后所有崩溃。只有 [ApplicationExitInfo.REASON_CRASH]
+ *   / [ApplicationExitInfo.REASON_CRASH_NATIVE] / [ApplicationExitInfo.REASON_ANR]
+ *   / [ApplicationExitInfo.REASON_INITIALIZATION_FAILURE] 计入 crash_count；
+ *   用户从最近任务划掉、系统 OOM 等不计入。
+ * - **API < 30 或 ExitInfo 无记录**：退回到 patch_loading 兜底——
+ *   patch_loading=true（首帧前死了）→ 视为崩溃；
+ *   patch_loading=false（首帧后死的）→ 不计崩溃。
+ *
+ * API < 30 因此存在已知盲区：补丁加载首帧后才发生的 native crash / ANR 不会被
+ * 检测（Dart 层异常仍由 verifyAfter 窗口内的 Dart 错误钩子捕获）。覆盖率约
+ * 5–10% 的存量长尾设备，业务侧若无法接受可显式调高 `maxCrashCount`。
+ *
+ * 当 crash_count 累计 >= [PatcherConfig.maxCrashCount] 次，自动删除补丁并拒绝加载。
+ */
+internal class CrashGuard(private val context: Context) {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/Guard"
+
+        /**
+         * Pure decision: should a real crash reason be charged against the patch?
+         *
+         * Only crashes within [PatcherConfig.BOOT_CRASH_WINDOW_MS] of boot start
+         * count as patch-boot failures. A crash long after a healthy boot is a
+         * runtime failure and must NOT trip the breaker (that was the bug causing
+         * a working OTA to silently revert hours later).
+         *
+         * When [bootStartedAt] or [crashTimestamp] is unknown (<= 0) we cannot
+         * bound it, so we conservatively charge the patch (preserves the old
+         * fail-fast behavior for that edge).
+         */
+        @JvmStatic
+        fun isWithinBootWindow(
+            bootStartedAt: Long,
+            crashTimestamp: Long,
+            windowMs: Long = PatcherConfig.BOOT_CRASH_WINDOW_MS,
+        ): Boolean {
+            if (bootStartedAt <= 0L || crashTimestamp <= 0L) return true
+            val elapsed = crashTimestamp - bootStartedAt
+            // Negative elapsed (clock skew / stale record) → treat as in-window.
+            if (elapsed < 0L) return true
+            return elapsed <= windowMs
+        }
+    }
+
+    private val sp = PatcherConfig.prefs(context)
+
+    /**
+     * 启动开始时综合判断是否加载补丁。
+     *
+     * @param onTrip 当熔断器**本次**触发并丢弃补丁时调用，参数为触发时的真实
+     *   crash_count（删除前）。供 [BootDiagnosticStore] / [BlacklistStore] 上报使用。
+     */
+    fun shouldLoadPatch(onTrip: ((crashCount: Int) -> Unit)? = null): Boolean {
+        val threshold = PatcherConfig.maxCrashCount(context)
+        val patchLoading = sp.getBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+        val lastPid = sp.getInt(PatcherConfig.KEY_LAST_BOOTING_PID, -1)
+        val bootStartedAt = sp.getLong(PatcherConfig.KEY_BOOT_STARTED_AT, 0L)
+
+        val verdict = classifyPreviousSession(patchLoading, lastPid, bootStartedAt)
+        if (verdict.isCrash) {
+            val count = recordCrashAndMaybeTrip(verdict.reasonName, onTrip)
+            if (count >= threshold) return false
+        } else if (patchLoading || lastPid > 0) {
+            // 非崩溃但状态未清：清掉以免下次冷启动重复处理同一会话
+            sp.edit()
+                .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+                .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+                .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+                .commit()
+            Log.i(TAG, "previous session ended without crash (${verdict.reasonName})")
+        }
+
+        return sp.getInt(PatcherConfig.KEY_CRASH_COUNT, 0) < threshold
+    }
+
+    /**
+     * 由 Dart 侧通过 MethodChannel 调用：上报一次"补丁加载阶段 Dart 层未捕获异常"。
+     *
+     * 这种崩溃不算系统层 [ApplicationExitInfo.REASON_CRASH] —— PlatformDispatcher
+     * 把异常吞了，进程没死，下次冷启动 ExitInfo 看到的是 USER_REQUESTED 之类的非
+     * 崩溃原因。所以需要 Dart 主动汇报，语义等同于一次真崩溃：crash_count += 1，
+     * 达到阈值则熔断 + 删补丁 + 黑名单。
+     *
+     * @param message 异常字符串（透传给日志 / 诊断展示，不做任何业务逻辑判断）
+     * @param onTrip  与 [shouldLoadPatch] 同款：触发熔断时调用，上报黑名单 / 诊断
+     */
+    fun reportDartBootError(message: String?, onTrip: ((crashCount: Int) -> Unit)? = null) {
+        recordCrashAndMaybeTrip(message ?: "no msg", onTrip)
+    }
+
+    /**
+     * 增计 crash_count、清 patch_loading、必要时触发熔断 + 删补丁。供
+     * [shouldLoadPatch] 与 [reportDartBootError] 共用，统一日志格式。
+     *
+     * @param reason  错误原因（ExitInfo reason name / Dart 异常 toString），仅用于日志
+     * @return 累加后的 crash_count（删补丁前的真实值）
+     */
+    private fun recordCrashAndMaybeTrip(
+        reason: String,
+        onTrip: ((crashCount: Int) -> Unit)?,
+    ): Int {
+        val threshold = PatcherConfig.maxCrashCount(context)
+        val count = sp.getInt(PatcherConfig.KEY_CRASH_COUNT, 0) + 1
+        sp.edit()
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, count)
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .commit()
+        Log.w(TAG, "patch boot failure recorded ($reason), crash_count=$count")
+        if (count >= threshold) {
+            Log.w(TAG, "circuit tripped! $count consecutive failures, dropping patch")
+            onTrip?.invoke(count)
+            deletePatchFiles()
+        }
+        return count
+    }
+
+    /** 在 Application.attachBaseContext 内调用。commit 同步写入，确保进程崩溃前状态已持久化。 */
+    fun markBooting() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, true)
+            .putInt(PatcherConfig.KEY_LAST_BOOTING_PID, Process.myPid())
+            .putLong(PatcherConfig.KEY_BOOT_STARTED_AT, System.currentTimeMillis())
+            .commit()
+    }
+
+    /**
+     * Dart 首帧渲染完成：补丁可信，立即清 patch_loading + crash_count。
+     *
+     * 注意：故意 **不清** [PatcherConfig.KEY_LAST_BOOTING_PID] / [PatcherConfig.KEY_BOOT_STARTED_AT]。
+     * 下次冷启动 [shouldLoadPatch] 仍可用这个 pid 查 [ApplicationExitInfo]，从而捕捉首帧
+     * 后短时间内（[PatcherConfig.BOOT_CRASH_WINDOW_MS] 以内）才发生的 native crash / ANR —— 那一刻
+     * patch_loading 已清，不能再作为崩溃信号。pid + 时间戳在 [shouldLoadPatch]
+     * 处理完一次会话后清除。
+     */
+    fun markBootSuccess() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .commit()
+    }
+
+    /** 清零所有熔断状态（配合补丁安装/回滚调用）。 */
+    fun reset() {
+        sp.edit()
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+            .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+            .apply()
+    }
+
+    /**
+     * 综合 [patchLoading] 与 [lastPid] 判定上次会话是否崩溃。
+     *
+     * - API 30+ 且有 pid 记录 → 优先用 [ApplicationExitInfo] 精确分类。**但只把发生在
+     *   启动窗口内（距 [bootStartedAt] 不超过 [PatcherConfig.BOOT_CRASH_WINDOW_MS]）的
+     *   崩溃计入补丁失败**：首帧后长时间运行才发生的 crash/ANR 属于正常运行期故障，
+     *   与补丁无关，不应触发熔断回滚。用户主动关闭 / 系统 OOM 等也不计崩溃。
+     * - API < 30 或 ExitInfo 拿不到记录 → 退回到 [patchLoading] 兜底信号。
+     *   patchLoading=true（首帧前死了）→ 崩溃；patchLoading=false（首帧后死的，
+     *   或本就没启动过）→ 非崩溃。
+     */
+    private fun classifyPreviousSession(
+        patchLoading: Boolean,
+        lastPid: Int,
+        bootStartedAt: Long,
+    ): ExitVerdict {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && lastPid > 0) {
+            val record = queryExitInfo(lastPid)
+            if (record != null) {
+                val isCrashReason = when (record.reason) {
+                    ApplicationExitInfo.REASON_CRASH,
+                    ApplicationExitInfo.REASON_CRASH_NATIVE,
+                    ApplicationExitInfo.REASON_ANR,
+                    ApplicationExitInfo.REASON_INITIALIZATION_FAILURE -> true
+                    else -> false
+                }
+                val reasonName = reasonNameApi30(record.reason)
+                if (!isCrashReason) {
+                    return ExitVerdict(false, reasonName)
+                }
+                // A real crash reason — but only charge it against the patch if it
+                // happened close to boot. A crash hours into a healthy session is a
+                // runtime bug, not a bad patch; counting it would revert a working OTA.
+                if (!isWithinBootWindow(bootStartedAt, record.timestamp)) {
+                    Log.i(
+                        TAG,
+                        "crash ($reasonName) at ts=${record.timestamp} is outside the " +
+                            "${PatcherConfig.BOOT_CRASH_WINDOW_MS}ms boot window " +
+                            "(bootStartedAt=$bootStartedAt); treating as runtime " +
+                            "failure, not charging the patch"
+                    )
+                    return ExitVerdict(false, "${reasonName}_LATE")
+                }
+                return ExitVerdict(true, reasonName)
+            }
+            // ExitInfo 队列已被新进程挤出（罕见）：退回到 patchLoading 兜底
+        }
+
+        return if (patchLoading) {
+            ExitVerdict(true, "NO_FIRST_FRAME")
+        } else {
+            ExitVerdict(false, "NO_RECORD")
+        }
+    }
+
+    private fun queryExitInfo(pid: Int): ApplicationExitInfo? {
+        val am = context.getSystemService(Context.ACTIVITY_SERVICE) as? ActivityManager
+        return try {
+            am?.getHistoricalProcessExitReasons(context.packageName, pid, 1)?.firstOrNull()
+        } catch (e: Throwable) {
+            Log.w(TAG, "getHistoricalProcessExitReasons failed", e)
+            null
+        }
+    }
+
+    private fun deletePatchFiles() {
+        val dir = File(context.filesDir, PatcherConfig.PATCH_DIR)
+        if (dir.exists()) dir.deleteRecursively()
+        sp.edit()
+            .putInt(PatcherConfig.KEY_CRASH_COUNT, 0)
+            .putBoolean(PatcherConfig.KEY_PATCH_LOADING, false)
+            .remove(PatcherConfig.KEY_LAST_BOOTING_PID)
+            .remove(PatcherConfig.KEY_BOOT_STARTED_AT)
+            .commit()
+    }
+
+    private data class ExitVerdict(val isCrash: Boolean, val reasonName: String)
+}
+
+/** 把 [ApplicationExitInfo] reason 整数翻成可读名，仅在 API 30+ 调用。 */
+private fun reasonNameApi30(reason: Int): String = when (reason) {
+    ApplicationExitInfo.REASON_UNKNOWN -> "UNKNOWN"
+    ApplicationExitInfo.REASON_EXIT_SELF -> "EXIT_SELF"
+    ApplicationExitInfo.REASON_SIGNALED -> "SIGNALED"
+    ApplicationExitInfo.REASON_LOW_MEMORY -> "LOW_MEMORY"
+    ApplicationExitInfo.REASON_CRASH -> "CRASH"
+    ApplicationExitInfo.REASON_CRASH_NATIVE -> "CRASH_NATIVE"
+    ApplicationExitInfo.REASON_ANR -> "ANR"
+    ApplicationExitInfo.REASON_INITIALIZATION_FAILURE -> "INITIALIZATION_FAILURE"
+    ApplicationExitInfo.REASON_PERMISSION_CHANGE -> "PERMISSION_CHANGE"
+    ApplicationExitInfo.REASON_EXCESSIVE_RESOURCE_USAGE -> "EXCESSIVE_RESOURCE_USAGE"
+    ApplicationExitInfo.REASON_USER_REQUESTED -> "USER_REQUESTED"
+    ApplicationExitInfo.REASON_USER_STOPPED -> "USER_STOPPED"
+    ApplicationExitInfo.REASON_DEPENDENCY_DIED -> "DEPENDENCY_DIED"
+    ApplicationExitInfo.REASON_OTHER -> "OTHER"
+    else -> "REASON_$reason"
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/FlutterPatcherApplication.kt

@@ -0,0 +1,201 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import io.flutter.app.FlutterApplication
+
+/**
+ * 宿主 App 需在 AndroidManifest.xml 中使用这个 Application（或在自己的 Application
+ * 里调 [attachPatcher]）。
+ *
+ * 启动流程：
+ * 1. attachBaseContext
+ *    → CrashGuard.shouldLoadPatch() 熔断检查（API 30+ 走 ApplicationExitInfo
+ *      精确识别上次进程是真崩溃还是被用户/系统结束；API < 30 走朴素策略：
+ *      patch_loading=true 即视为一次崩溃）
+ *    → PatchManager.getValidPatchPath() 磁盘补丁验签
+ *    → LoaderHook.install() 反射替换 FlutterLoader
+ *    → CrashGuard.markBooting() 标记「启动中」并记录 pid（API 30+ 用于 ExitInfo 查询）
+ * 2. Dart 首帧 → MethodChannel("flutter_ota_kit#reportBootSuccess")
+ *    → CrashGuard.markBootSuccess() 重置计数
+ *
+ * API 30+ 上，用户主动从最近任务划掉 / OOM kill / 强停等「非崩溃退出」不计入
+ * crash_count，只有真崩溃（CRASH / CRASH_NATIVE / ANR / INITIALIZATION_FAILURE）
+ * 才会触发熔断。API < 30 没有这层分类，对长尾设备做 fail-fast 取舍。
+ *
+ * 用户如果已经有自己的 Application 基类，直接把 [attachPatcher] 搬过去即可，
+ * 不需要继承本类。
+ */
+open class FlutterPatcherApplication : FlutterApplication() {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/App"
+
+        @Volatile
+        private var attachAttempted = false
+
+        @Volatile
+        private var attachResult = false
+
+        /**
+         * 在 Application.attachBaseContext(base) 中、super 调用之后调用。
+         * 返回补丁是否成功注入。
+         */
+        @JvmStatic
+        @Synchronized
+        fun attachPatcher(context: Context): Boolean {
+            if (attachAttempted) {
+                Log.d(TAG, "attachPatcher already ran in this process, result=$attachResult")
+                return attachResult
+            }
+            attachAttempted = true
+            attachResult = doAttachPatcher(context)
+            return attachResult
+        }
+
+        private fun doAttachPatcher(context: Context): Boolean {
+            // 本次启动是否已往 BootDiagnosticStore 写过精准 status。
+            // 用于在收尾阶段判断要不要兜底成 NO_PATCH（避免覆盖更精准的 reason）。
+            var diagRecorded = false
+            val appVc = PatcherConfig.currentVersionCode(context)
+
+            return try {
+                // 在熔断/校验丢弃前预读 (version, downloadMd5)，等会儿入黑名单要用。
+                // 即便文件后续被删，这里捕获的字符串仍有效。
+                val patchManager = PatchManager(context)
+                val crashedMeta = patchManager.currentMeta()
+
+                val guard = CrashGuard(context)
+                val canLoad = guard.shouldLoadPatch { crashCount ->
+                    // 熔断触发 ⇒ 这个补丁连续没活到 verified，加入黑名单防止重试。
+                    if (crashedMeta != null) {
+                        BlacklistStore.add(
+                            context,
+                            crashedMeta.first,
+                            crashedMeta.second,
+                            BlacklistStore.REASON_BOOT_CRASH,
+                        )
+                    }
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.DROPPED_CIRCUIT_BREAKER,
+                        patchVersion = crashedMeta?.first,
+                        appVersionCode = appVc,
+                        crashCount = crashCount,
+                        message = if (crashedMeta != null)
+                            "$crashCount boot failure(s); blacklisted (version=${crashedMeta.first})"
+                        else
+                            "$crashCount boot failure(s)",
+                    )
+                    diagRecorded = true
+                }
+                if (!canLoad) {
+                    Log.w(TAG, "circuit breaker tripped, skip patch")
+                    return false
+                }
+
+                val patch = patchManager.getValidPatch { status, version, extras ->
+                    // md5 / signature 失败 = 强烈"补丁有问题"信号，连带入黑名单。
+                    // meta_corrupted / version_code_mismatch 不入黑名单（前者 key 不全，后者
+                    // 属于正常 APK 升级而非补丁本身有问题）。
+                    val blacklistMd5 = extras["blacklistMd5"] as? String
+                    val blacklistReason = when (status) {
+                        BootDiagnosticStore.DROPPED_MD5_MISMATCH ->
+                            BlacklistStore.REASON_MD5_MISMATCH
+                        BootDiagnosticStore.DROPPED_SIGNATURE_INVALID ->
+                            BlacklistStore.REASON_SIGNATURE_INVALID
+                        else -> null
+                    }
+                    if (blacklistReason != null && version != null && !blacklistMd5.isNullOrEmpty()) {
+                        BlacklistStore.add(context, version, blacklistMd5, blacklistReason)
+                    }
+
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = status,
+                        patchVersion = version,
+                        patchTargetVersionCode = extras["patchTargetVersionCode"] as? Long,
+                        appVersionCode = (extras["appVersionCode"] as? Long) ?: appVc,
+                        message = extras["message"] as? String,
+                    )
+                    diagRecorded = true
+                }
+                if (patch == null) {
+                    Log.d(TAG, "no usable patch, boot with built-in libapp.so")
+                    if (!diagRecorded) {
+                        // DROPPED_* 是用户最关心的"上次为啥被丢弃"信息，不应被这次
+                        // 无信息量的 NO_PATCH 覆盖。典型场景：上一次冷启动里 Dart 错误
+                        // 钩子把补丁判崩 + record(DROPPED_CIRCUIT_BREAKER) + 删补丁，
+                        // 但进程没死、UI 没建出来；用户划掉重开后这一次进入本分支，
+                        // 写 NO_PATCH 会让 DiagCard 看不到 trip 信息。
+                        // 后续装上新补丁时，line 127 会写 PATCHED 自然覆盖，sticky 自动解除。
+                        val existing = BootDiagnosticStore.read(context)
+                        val existingStatus = existing?.get("status") as? String
+                        val shouldPreserve = existingStatus != null &&
+                            existingStatus.startsWith("DROPPED_")
+                        if (!shouldPreserve) {
+                            BootDiagnosticStore.record(
+                                context = context,
+                                status = BootDiagnosticStore.NO_PATCH,
+                                appVersionCode = appVc,
+                            )
+                        } else {
+                            Log.d(TAG, "preserved existing $existingStatus over NO_PATCH")
+                        }
+                    }
+                    return false
+                }
+
+                // 走到这里说明补丁已通过校验。预先取版本号，方便后面 record。
+                val patchVersion = patchManager.currentVersion().ifEmpty { null }
+
+                // 标记「启动中」——必须 commit 同步写入，确保进程崩溃前状态已持久化
+                guard.markBooting()
+
+                val attemptedFields = mutableListOf<String>()
+                val ok = LoaderHook.install(
+                    context,
+                    patch.soPath,
+                    patch.assetsBundlePath,
+                    patch.assetsArchivePath,
+                    attemptedFields
+                )
+                if (ok) {
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.PATCHED,
+                        patchVersion = patchVersion,
+                        appVersionCode = appVc,
+                    )
+                } else {
+                    // 注入失败：本次启动根本没换 libapp.so，不视为一次崩溃
+                    guard.reset()
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.HOOK_INSTALL_FAILED,
+                        patchVersion = patchVersion,
+                        appVersionCode = appVc,
+                        attemptedLoaderFields = attemptedFields.toList(),
+                        message = "FlutterLoader reflection failed; patch retained",
+                    )
+                }
+                ok
+            } catch (e: Exception) {
+                Log.e(TAG, "attachPatcher failed, fallback to built-in", e)
+                CrashGuard(context).reset()
+                BootDiagnosticStore.record(
+                    context = context,
+                    status = BootDiagnosticStore.UNKNOWN,
+                    appVersionCode = appVc,
+                    message = e.message ?: e.javaClass.simpleName,
+                )
+                false
+            }
+        }
+    }
+
+    override fun attachBaseContext(base: Context) {
+        super.attachBaseContext(base)
+        attachPatcher(this)
+    }
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/FlutterPatcherAutoInitProvider.kt

@@ -0,0 +1,93 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import android.util.Log
+
+/**
+ * 自动初始化 ContentProvider —— 宿主无需改 Application 即可挂上补丁加载。
+ *
+ * # 生命周期
+ * Android `ActivityThread.handleBindApplication` 的固定顺序：
+ *
+ * ```
+ * Application.attachBaseContext()
+ *   ↓
+ * installContentProviders()  ← 本 provider.onCreate 在这里触发
+ *   ↓
+ * Application.onCreate()
+ *   ↓
+ * Activity lifecycle（FlutterActivity.onCreate → 首次 new FlutterEngine）
+ * ```
+ *
+ * 插件反射替换 `FlutterInjector.flutterLoader` 只要求"早于第一次
+ * `FlutterInjector.instance()` 真正被使用"，ContentProvider 这个时机足够。
+ * 这是 Firebase / WorkManager / androidx.startup 都在用的自动初始化模式。
+ *
+ * # 边界：什么时候走不通
+ * 宿主在自己 `Application.attachBaseContext` 里 **预热 FlutterEngine**（罕见，
+ * 主要出现在大厂混合工程的冷启动优化）。此时 provider 还没轮到、Engine 已起来，
+ * 反射来不及。这类工程应在宿主 Manifest 里关掉自动初始化，改为显式调用：
+ *
+ * ```xml
+ * <provider
+ *     android:name="com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider"
+ *     android:authorities="${applicationId}.flutter_patcher.autoinit"
+ *     tools:node="remove" />
+ * ```
+ *
+ * 然后在自己的 Application 里：
+ *
+ * ```kotlin
+ * override fun attachBaseContext(base: Context) {
+ *     super.attachBaseContext(base)
+ *     FlutterPatcherApplication.attachPatcher(base)
+ * }
+ * ```
+ */
+class FlutterPatcherAutoInitProvider : ContentProvider() {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/AutoInit"
+    }
+
+    override fun onCreate(): Boolean {
+        val ctx = context ?: run {
+            Log.w(TAG, "context is null, skip auto init")
+            return false
+        }
+        Log.d(TAG, "auto init via ContentProvider.onCreate()")
+        FlutterPatcherApplication.attachPatcher(ctx)
+        return true
+    }
+
+    // ==================== no-op data surface ====================
+    // 本 provider 不对外暴露任何数据；所有 CRUD 都返回空 / 0 即可。
+
+    override fun query(
+        uri: Uri,
+        projection: Array<out String>?,
+        selection: String?,
+        selectionArgs: Array<out String>?,
+        sortOrder: String?
+    ): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(
+        uri: Uri,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+
+    override fun update(
+        uri: Uri,
+        values: ContentValues?,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+}