feat: implement retention policy for background apps

- Introduced RetentionPolicy interface and RetentionManager class to manage background app retention.
- Updated JSCore to ensure proper handling of lifecycle and termination APIs.
- Enhanced AppManager to configure and observe memory pressure for retained apps.
- Implemented background scheduler to manage timer callbacks during app suspension.
- Added tests for background lifecycle and retention behavior.
- Updated iOS DMPApp and DMPAppManager to support retention functionality.

Author: dos1in

android/dimina/src/main/kotlin/com/didi/dimina/Dimina.kt

@@ -94,6 +94,14 @@ class Dimina private constructor(context: Context) {
         return BuildConfig.DEBUG && config.debugMode
     }
 
+    @MainThread
+    fun configureRetention(policy: com.didi.dimina.core.RetentionPolicy) {
+        MiniApp.getInstance().configureRetention(policy)
+    }
+
+    /** Hosts may forward their own pressure source here as well. */
+    fun notifyMemoryPressure() { MiniApp.getInstance().notifyMemoryPressure() }
+
     fun getApiNamespaces(): List<String> = config.apiNamespaces
 
     private val appContext: Context = context
@@ -108,6 +116,17 @@ class Dimina private constructor(context: Context) {
     // 初始化核心组件
     private fun setupCoreComponents() {
         StoreUtils.initialize(context = appContext)
+        appContext.registerComponentCallbacks(object : android.content.ComponentCallbacks2 {
+            override fun onConfigurationChanged(newConfig: android.content.res.Configuration) {}
+            override fun onLowMemory() { notifyMemoryPressure() }
+            override fun onTrimMemory(level: Int) {
+                if (level == android.content.ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW ||
+                    level == android.content.ComponentCallbacks2.TRIM_MEMORY_RUNNING_CRITICAL ||
+                    level >= android.content.ComponentCallbacks2.TRIM_MEMORY_BACKGROUND) {
+                    notifyMemoryPressure()
+                }
+            }
+        })
     }
 
     // 应用配置

android/dimina/src/main/kotlin/com/didi/dimina/core/MiniApp.kt

@@ -56,6 +56,49 @@ import java.io.File
  */
 class MiniApp private constructor() {
     private val tag = "MiniApp"
+    private val retention = BackgroundRetention()
+    private val retentionHandler by lazy { android.os.Handler(android.os.Looper.getMainLooper()) }
+    private var retentionPressure = false
+    private val retentionTask = Runnable { collectRetainedApps() }
+
+    @androidx.annotation.MainThread
+    fun configureRetention(policy: RetentionPolicy) {
+        retention.policy = policy
+        scheduleRetention()
+    }
+
+    fun notifyMemoryPressure() {
+        retentionHandler.post {
+            retentionPressure = true
+            scheduleRetention()
+        }
+    }
+
+    internal fun retentionVisibility(appId: String, visible: Boolean) {
+        if (visible) retention.forget(appId)
+        else retention.hide(appId, android.os.SystemClock.elapsedRealtime())
+        scheduleRetention()
+    }
+
+    private fun scheduleRetention() {
+        retentionHandler.removeCallbacks(retentionTask)
+        retentionHandler.post(retentionTask)
+    }
+
+    private fun collectRetainedApps() {
+        retentionHandler.removeCallbacks(retentionTask)
+        val now = android.os.SystemClock.elapsedRealtime()
+        val canEvict: (String) -> Boolean = { DiminaActivity.canEvictRetainedApp(it) }
+        val victims = retention.collect(now, retentionPressure, canEvict)
+        retentionPressure = false
+        victims.forEach { appId ->
+            // No opener restoration or foreground task movement during cache eviction.
+            DiminaActivity.closeForUninstall(appId)
+            clear(appId)
+        }
+        retention.nextDelay(now, canEvict)?.let { retentionHandler.postDelayed(retentionTask, it) }
+    }
+
 
     private val apiRegistry = ApiRegistry()
     private val bluetoothApi = BluetoothApi()
@@ -93,6 +136,7 @@ class MiniApp private constructor() {
      * @param miniProgram The MiniProgram to open
      */
     fun openApp(context: Activity, miniProgram: MiniProgram) {
+        collectRetainedApps()
         // Initialize or get JsCore for this MiniProgram
         val alreadyRunning = isRunning(miniProgram.appId)
         getOrCreateJsCore(miniProgram.appId, context)
@@ -467,6 +511,7 @@ class MiniApp private constructor() {
      */
     @androidx.annotation.MainThread
     fun clear(appId: String) {
+        retention.forget(appId)
         updateCheckRegistry.reset(appId)
         synchronized(this) {
             pendingAppShowOptions.remove(appId)
@@ -503,6 +548,8 @@ class MiniApp private constructor() {
      */
     @androidx.annotation.MainThread
     fun clearAll() {
+        retention.clear()
+        retentionHandler.removeCallbacks(retentionTask)
         updateCheckRegistry.resetAll()
         synchronized(this) {
             pendingAppShowOptions.clear()

android/dimina/src/main/kotlin/com/didi/dimina/core/RetentionPolicy.kt

@@ -0,0 +1,38 @@
+package com.didi.dimina.core
+
+/** SDK defaults, not a promise about another client's cache capacity. */
+data class RetentionPolicy(
+    val maxBackgroundApps: Int = 3,
+    val backgroundTimeoutMs: Long = 300_000,
+) {
+    init {
+        require(maxBackgroundApps >= 0) { "maxBackgroundApps must be non-negative" }
+        require(backgroundTimeoutMs >= 0) { "backgroundTimeoutMs must be non-negative" }
+    }
+}
+
+/** Pure policy: timestamps are monotonic, duplicate hide never extends the lease. */
+internal class BackgroundRetention {
+    var policy = RetentionPolicy()
+    private val hidden = linkedMapOf<String, Long>()
+    fun hide(id: String, now: Long) { hidden.putIfAbsent(id, now) }
+    fun forget(id: String) { hidden.remove(id) }
+    fun clear() { hidden.clear() }
+    fun collect(now: Long, pressure: Boolean, canEvict: (String) -> Boolean): List<String> {
+        val candidates = hidden.entries.filter { canEvict(it.key) }.sortedBy { it.value }
+        val victims = mutableListOf<String>()
+        for ((id, since) in candidates) {
+            if (pressure || candidates.size - victims.size > policy.maxBackgroundApps ||
+                (policy.backgroundTimeoutMs > 0 && now - since >= policy.backgroundTimeoutMs)) {
+                victims.add(id)
+                hidden.remove(id)
+            }
+        }
+        return victims
+    }
+    fun nextDelay(now: Long, canEvict: (String) -> Boolean): Long? {
+        if (policy.backgroundTimeoutMs == 0L) return null
+        val since = hidden.filterKeys(canEvict).values.minOrNull() ?: return null
+        return (policy.backgroundTimeoutMs - (now - since)).coerceAtLeast(1)
+    }
+}

android/dimina/src/main/kotlin/com/didi/dimina/ui/container/DiminaActivity.kt

@@ -1906,6 +1906,7 @@ class DiminaActivity : ComponentActivity() {
 
     fun hideMiniProgram() {
         if (!isMiniProgramForeground() || isFinishing) return
+        activityRegistry.snapshot(miniProgram.appId).forEach { it.retainedByHost = true }
         window.decorView.clearFocus()
         // Queue options before another task can receive onStart.
         queueOpenerReturn(null)
@@ -1981,7 +1982,11 @@ class DiminaActivity : ComponentActivity() {
      * bootstrap lands - the pending intent is not lost, it is left for
      * [reconcileAppVisibilityWithCore] to replay once a real JsCore exists.
      */
+    private var retainedByHost = false
+
     private fun dispatchMiniProgramShow() {
+        retainedByHost = false
+        miniApp.retentionVisibility(miniProgram.appId, true)
         val jsCore = miniApp.peekJsCore(miniProgram.appId)
         if (jsCore != null) {
             val showOptions = miniApp.consumePendingAppShowOptions(miniProgram.appId)?.apply {
@@ -1996,6 +2001,7 @@ class DiminaActivity : ComponentActivity() {
     }
 
     private fun dispatchMiniProgramHide() {
+        miniApp.retentionVisibility(miniProgram.appId, false)
         miniApp.peekJsCore(miniProgram.appId)?.appHide()
         com.didi.dimina.api.network.WebSocketManager.shared.setBackgrounded(miniProgram.appId, true)
     }
@@ -2590,6 +2596,11 @@ class DiminaActivity : ComponentActivity() {
             return true
         }
 
+        internal fun canEvictRetainedApp(appId: String): Boolean {
+            val activity = activityRegistry.lastRegistered(appId) ?: return true
+            return activity.retainedByHost && !visibilityTracker.isForeground(appId)
+        }
+
         internal fun closeForUninstall(appId: String) {
             activityRegistry.closeAll(appId) { activity ->
                 activity.prepareForColdRestart()

android/dimina/src/test/java/com/didi/dimina/core/BackgroundRetentionTest.kt

@@ -0,0 +1,37 @@
+package com.didi.dimina.core
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class BackgroundRetentionTest {
+    @Test fun capacityUsesHideRecencyAndDoesNotRefreshDuplicateHide() {
+        val state = BackgroundRetention()
+        state.policy = RetentionPolicy(2, 0)
+        state.hide("a", 0); state.hide("b", 1); state.hide("a", 2); state.hide("c", 3)
+        assertEquals(listOf("a"), state.collect(3, false) { true })
+        state.forget("b"); state.hide("b", 4); state.hide("d", 5)
+        assertEquals(listOf("c"), state.collect(5, false) { true })
+    }
+
+    @Test fun expiresAtDeadlineAndCancelsLastLease() {
+        val state = BackgroundRetention()
+        state.policy = RetentionPolicy(3, 100)
+        state.hide("a", 0); state.hide("b", 50)
+        assertEquals(1L, state.nextDelay(99) { true })
+        assertEquals(emptyList<String>(), state.collect(99, false) { true })
+        assertEquals(listOf("a"), state.collect(100, false) { true })
+        state.forget("b")
+        assertNull(state.nextDelay(100) { true })
+    }
+
+    @Test fun pressureProtectsPinnedAppsAndZeroCapacityDisablesRetention() {
+        val state = BackgroundRetention()
+        state.hide("pinned", 0); state.hide("a", 1); state.hide("b", 2)
+        assertEquals(listOf("a", "b"), state.collect(2, true) { it != "pinned" })
+        state.policy = RetentionPolicy(0, 0)
+        assertEquals(listOf("pinned"), state.collect(2, false) { true })
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun rejectsNegativeCapacity() { RetentionPolicy(-1) }
+}

docs/MiniProgram-Retention.md

@@ -1,6 +1,6 @@
 # 小程序多实例与后台留存
 
-不同 appId 可以同时保留运行状态；同一个 appId 从宿主入口再次打开时复用已有实例，恢复当前页面栈，不重新执行 `App.onLaunch`、`Page.onLoad`。
+不同 appId 可以同时保留运行状态；同一个 appId 从宿主入口再次打开时优先复用仍在缓存中的实例，恢复当前页面栈。实例已被回收时走冷启动，重新执行 `App.onLaunch`、`Page.onLoad`。
 
 ## 关闭界面与销毁实例
 
@@ -40,7 +40,73 @@ Android、iOS 和 Harmony 的后台实例不能操作前台导航栈。销毁后
 
 每个保留实例仍占用 JS 和 WebView 内存，宿主可通过主动销毁入口释放不再需要的实例。Harmony 隐藏期间的 TabBar 更新在恢复时应用；待处理更新最多 128 条，超过上限会失败，避免无限积压。
 
-当前没有统一的运行时挂起、留存超时或按内存压力自动淘汰策略。宿主保持前台、某个小程序处于后台时，其 JS 仍可能继续执行；需要控制实例数量时，应通过宿主销毁接口释放实例。
+四端共用逻辑层的协作式挂起：`App.onHide` 执行后暂停 `setTimeout`、`setInterval` 和普通业务消息回调，包括网络、扩展事件与 Canvas 动画回调。`App.onShow` 时恢复，定时器继续剩余等待时间，周期定时器不补跑隐藏期间错过的次数。业务消息按接收顺序分批处理，每批最多 64 条，避免为每条积压消息创建原生定时器。
+
+资源初始化、页面生命周期、销毁屏障和跨小程序导航的成功/失败/完成回调继续分发，避免隐藏后的退出或重启操作互相等待。挂起不抢占正在执行的 JS 或微任务，不冻结整个 Worker、WebView、原生网络或媒体任务；已到达但尚未分发的业务消息仍占用内存。原生能力继续遵循各自的隐藏与销毁规则。
+
+原生宿主需要同步更新共享 JSSDK 中的 `service.js`，才能启用上述挂起逻辑；只升级原生 SDK、继续使用旧 JSSDK 时，只会生效原生实例回收策略。
+
+## 宿主留存策略
+
+| 配置 | 默认值 | 含义 |
+| --- | --- | --- |
+| `maxBackgroundApps` | `3` | 可回收后台缓存实例的数量上限；`0` 表示界面关闭后不留存 |
+| `backgroundTimeoutMs` | `300000` | 自最近一次隐藏起的超时，单位毫秒；`0` 关闭超时回收 |
+
+配置必须是非负整数。这些默认值属于 Dimina，不是微信客户端固定数量或时长的承诺。配置更新后会重新检查已有缓存。
+
+超限时按最近使用顺序回收：最早隐藏且此后未重新显示的实例最先释放。重复隐藏不会延长超时；显示后再次隐藏才开始新的留存周期。每个管理器只维护最近一个到期计时器，不轮询、不为每个实例创建回收计时器。宿主进程被系统挂起期间不能保证准点执行；启动入口会在复用前再次检查期限。
+
+当前展示的实例，以及跨小程序导航中尚未解除的来源链，属于受保护的展示关系，不计入可回收缓存上限。宿主整体进入系统后台也不会立即解除该关系。因此总运行实例数可以大于 `maxBackgroundApps`，该配置不是进程总实例数的硬上限。实例脱离展示关系后才允许自动销毁，避免破坏返回页面与来源关系。
+
+内存压力会释放所有可回收后台实例，保留受保护的展示关系；之后再次打开被回收实例走冷启动。回收释放运行时、页面和实例资源，不清除 Storage 或用户文件，也不自动打开其他小程序。
+
+### Android
+
+在主线程配置；调用 `Dimina.init` 后即可设置：
+
+```kotlin
+import com.didi.dimina.core.RetentionPolicy
+
+dimina.configureRetention(RetentionPolicy(maxBackgroundApps = 3, backgroundTimeoutMs = 300_000))
+```
+
+SDK 自动监听应用的 `onLowMemory` 及低内存级别的 `onTrimMemory`，单纯的 `TRIM_MEMORY_UI_HIDDEN` 不当作内存告警。宿主也可主动调用 `dimina.notifyMemoryPressure()`。
+
+### iOS
+
+在主线程配置：
+
+```swift
+DMPAppManager.sharedInstance().configureRetention(
+    DMPRetentionPolicy(maxBackgroundApps: 3, backgroundTimeoutMs: 300_000)
+)
+```
+
+SDK 自动监听 `UIApplication.didReceiveMemoryWarningNotification`。宿主可在主线程主动调用 `DMPAppManager.sharedInstance().notifyMemoryPressure()`。
+
+### Harmony
+
+```typescript
+import { DMPAppManager, DMPRetentionPolicy } from 'dimina'
+
+DMPAppManager.sharedInstance().configureRetention(new DMPRetentionPolicy(3, 300000))
+```
+
+启动时 SDK 向应用上下文注册一次环境监听，在 `onMemoryLevel` 中发起回收。宿主也可主动调用 `DMPAppManager.sharedInstance().notifyMemoryPressure()`。
+
+### Web
+
+```typescript
+const container = createContainer({
+  mount,
+  retention: { maxBackgroundApps: 3, backgroundTimeoutMs: 300000 },
+})
+container.configureRetention({ maxBackgroundApps: 1, backgroundTimeoutMs: 60000 })
+container.notifyMemoryPressure()
+```
+
+配置和实例池按容器隔离。浏览器没有通用且可靠的内存告警事件，因此 Web 内存压力入口由宿主触发，不依据不可靠的堆大小估算主动淘汰。
 
 Harmony 的 `customLaunchPageCallBack` 自定义挂载页面没有框架路由入口，由宿主负责隐藏和恢复，不适用默认路由隐藏方法。
 
@@ -54,9 +120,15 @@ Harmony 的 `customLaunchPageCallBack` 自定义挂载页面没有框架路由
 6. TabBar 场景重复上述操作，检查选中项、已加载 Tab、徽标及页面状态。
 7. 从不同场景重新打开同一实例，检查进入参数更新、旧来源关系清除，以及系统前后台切换后参数不回退。
 
+8. 把后台上限设为 1，依次关闭 A、B：A 应被回收；重新打开 A 应冷启动。
+9. 缩短超时，检查到期回收、显示后取消旧期限，以及回收时其他前台小程序不受影响。
+10. 主动发起内存压力，检查后台缓存释放；当前展示实例与返回来源链仍可使用。
+11. 隐藏期间检查业务定时器和回调不执行，恢复后顺序正确；隐藏后的退出/重启回调与销毁屏障仍能完成。
+
 回归入口：
 
-- Android：`:dimina:testDebugUnitTest`，以及示例应用中的任务栈切换。
+- Android：`:dimina:testDebugUnitTest`，其中 `BackgroundRetentionTest` 覆盖容量、期限与内存压力；界面仍需示例应用中的任务栈切换验证。
 - iOS：`DMPRetainedMiniProgramTests` 和 `DMPNavigatorCapsuleTests`。
-- Web：`retained-mini-program.spec.ts` 与容器 SDK 现有生命周期、并发打开测试。
+- Web：`retention-policy.spec.ts`、`retained-mini-program.spec.ts` 与容器 SDK 现有生命周期、并发打开测试。
+- 共享逻辑层：`background-scheduler.spec.js`、`background-lifecycle.spec.js`，验证挂起、恢复、定时器剩余时间和终止性回调的顺序。
 - Harmony：安装前端依赖后执行 `node --test harmony/scripts/retained-pages.test.mjs`；ArkUI 编译通过 `dimina:assembleHar` 验证，实际界面复用仍需设备验证。

docs/Multi-Mini-Program.md

@@ -34,7 +34,7 @@ B 调用 `navigateBackMiniProgram` 或 `exitMiniProgram` 后：
 3. 恢复的仍是原来的 A 实例，不重新触发 `App.onLaunch`。
 4. A 以场景值 `1038` 触发 App Show 和当前 Page Show；`navigateBackMiniProgram` 的 `extraData` 放在 `referrerInfo.extraData` 中返回。
 
-这条“隐藏不等于销毁”的边界也适用于宿主直接缓存的 Web `MiniApp`：`closeApp()` 只从呈现栈摘除实例，后续再次 `openApp()` 同一 `appId` 会前置缓存实例；传入 `destroy: true` 才会销毁其它实例。
+这条“隐藏不等于销毁”的边界也适用于宿主直接缓存的 Web `MiniApp`：`closeApp()` 只从呈现栈摘除实例，后续再次 `openApp()` 同一 `appId` 会前置缓存实例；传入 `destroy: true` 会主动销毁其它实例；已脱离呈现栈的缓存还会按宿主留存策略自动回收。
 
 ## 平台实现
 
@@ -52,7 +52,7 @@ B 调用 `navigateBackMiniProgram` 或 `exitMiniProgram` 后：
 - `restartMiniProgram` 会替换当前实例的完整运行时，不属于后台恢复。
 - `exitMiniProgram` 会销毁当前目标实例；它不会销毁仍在呈现栈中的来源实例。
 - 后台保留是进程内能力，不是系统级持久化。宿主进程被系统终止后，需要按冷启动或宿主保存的恢复数据重新创建。
-- JavaScript 定时器、WebSocket、蓝牙和局域网等能力仍受各能力自身的后台限制及操作系统策略约束；例如 WebSocket 会按既有后台宽限策略中断。框架尚未实现统一的 JS 挂起或实例自动淘汰，详见[资源边界](./MiniProgram-Retention.md#生命周期与资源边界)。
+- JavaScript 定时器、WebSocket、蓝牙和局域网等能力仍受各能力自身的后台限制及操作系统策略约束；例如 WebSocket 会按既有后台宽限策略中断。框架在逻辑层协作式暂停定时器与普通业务回调，并为脱离展示链的后台缓存提供数量、超时和内存压力回收，详见[资源边界](./MiniProgram-Retention.md#生命周期与资源边界)及[宿主留存策略](./MiniProgram-Retention.md#宿主留存策略)。
 
 ## 验证建议
 

fe/packages/common/src/core/callback.js

@@ -19,6 +19,15 @@ class Callback {
 		return evtId
 	}
 
+	/** Lifecycle transactions must finish even after their initiating app hides. */
+	allowInBackground(evtId) {
+		if (this.callbacks[evtId]) this.callbacks[evtId].backgroundControl = true
+	}
+
+	isAllowedInBackground(evtId) {
+		return this.callbacks[evtId]?.backgroundControl === true
+	}
+
 	/**
 	 * [Container] triggerCallback -> [Service] invoke
 	 * @param {*} evtId

fe/packages/container-sdk/__tests__/retained-mini-program.spec.ts

@@ -66,3 +66,22 @@ it('refreshes host entry options without reviving an old mini-program opener', a
 		mount.remove()
 	}
 })
+
+
+it('reclaims a hidden runtime after capacity reduction and rebuilds it on next entry', async () => {
+	const mount = document.createElement('div')
+	document.body.appendChild(mount)
+	const container = createContainer({ mount, retention: { maxBackgroundApps: 1, backgroundTimeoutMs: 0 } })
+	const first = await container.openApp({ appId: 'evict-a' })
+	await container.application.dismissView(first, { destroy: false })
+	const second = await container.openApp({ appId: 'evict-b' })
+	container.configureRetention({ maxBackgroundApps: 0, backgroundTimeoutMs: 0 })
+	await vi.waitFor(() => expect(container.application.appManager.getAppById(first.appId)).toBeNull())
+	expect(FakeWorker.instances[0].terminate).toHaveBeenCalledTimes(1)
+	expect(container.application.views.at(-1)).toBe(second)
+	const restored = await container.openApp({ appId: 'evict-a' })
+	expect(restored).not.toBe(first)
+	await container.application.destroyRootView(restored)
+	await container.application.destroyRootView(second)
+	mount.remove()
+})