feat(feeds): 翻页节流 1s + 连翻 30 页预算，超了 footer 改手动继续

线上遥测：一页只剩一两条可展示（其余被 R-18 / 屏蔽本地过滤掉）时，那一两条
一绑定就落在预取区、立刻再翻——一次搜索 48 秒翻 89 页、一直翻到 pixiv 的
5000 条 offset 上限，没有一个是人在看。

- FeedSource.pagingPolicy() → FeedPagingPolicy（默认全框架生效）：
  相邻两次 loadMore 网络页至少隔 1 s（含空页追载的每一跳）；
  连着翻满 30 页置 appendPaused，footer 变「点击加载更多」，点一下再给一份预算。
- 预算只数「连着翻」的页：两页之间隔 ≥ 5 s 归零，正常人翻多深都不会被拦。
- 刷新整条链路和刷新后的第一次翻页不受限（首屏是用户动作，追载有跳数硬上限）。
- adoptCursor 清 appendPaused，与 reachedEnd 保持互斥。
- 文案 feed_append_paused_tap_to_continue 7 个 locale；docs/feeds-module.md 第 4 节。

:feeds 单测 60/60（新增 12），:app 编译与 feeds 相关单测通过。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vr4LZN5Jpgt4kpqT9pukLd

Author: SoxiaLiSA

docs/feeds-module.md

@@ -56,8 +56,8 @@ ShaftFeedHost.install()
 - **AGP 8 默认 non-transitive R**：`:app` 引用搬走的资源（`@layout/fragment_feed`、
   `@color/feed_skeleton_block` 等）必须写成 `ceui.pixiv.feeds.R.xxx`，光靠资源合并
   只在 XML 里（`@layout/fragment_feed`）自动生效，Kotlin/Java 侧不行。
-- **三条文案随框架搬进了模块**（`empty_list_1` / `list_load_failed_tap_retry` /
-  `feed_error_tap_retry`，7 个 locale 全带）。`scripts/sort_locale_strings.py` 和
+- **文案随框架住在模块里**（`empty_list_1` / `list_load_failed_tap_retry` /
+  `feed_error_tap_retry` / `feed_append_paused_tap_to_continue`，7 个 locale 全带）。`scripts/sort_locale_strings.py` 和
   `scripts/find_missing_used_strings.py` 的默认路径写死在 `app/src/main/res` 下，
   跑这几条要把路径显式指到 `feeds/src/main`，两个脚本参数名不同：
   `find_missing_used_strings.py` 用 `--source-root` / `--source-values` / `--target`，
@@ -66,3 +66,30 @@ ShaftFeedHost.install()
   （`checkDependencies` 默认 false）。改了 `:feeds` 要单独跑 `./gradlew :feeds:lintDebug`。
   没给 `:app` 打开 `checkDependencies`——那会把 `:models` / `:progressmanager` /
   `:flowlayout-lib` 这些老模块的存量问题一起灌进本就是红的 app lint 里。
+
+---
+
+## 4. 翻页的节奏与预算（`FeedPagingPolicy`）
+
+触底预取是零间隔的：`FeedAdapter.onBind` 进尾部 6 条就调 `loadMore()`，页一提交
+`FeedFragment.rearmPaginationIfNearEnd` 再补一次。一页只剩一两条可展示（其余被 R-18 /
+屏蔽等本地过滤掉，过滤发生在 `FeedSource.load` 的 mapper 里，框架只看到「薄页」）时，
+那一两条一绑定就又落在预取区，于是一页接一页零间隔连翻——线上遥测里一次搜索 48 秒翻
+89 页、一直翻到 pixiv 的 5000 条 offset 上限，全是这个形态，没有一个是人在看。
+
+`FeedViewModel` 因此对**首屏之后的每一次网络翻页**（含空页追载的每一跳）过两道闸，
+参数来自 `FeedSource.pagingPolicy()`（默认 `FeedPagingPolicy.Default`，全框架统一）：
+
+- **最小间隔** `minPageIntervalMs`（默认 1 s）：相邻两次 `loadMore` 网络页至少隔这么久，
+  以上一页返回时刻起算。等待发生在 append 已置 Loading 之后（footer 转圈），预取信号不会
+  丢；下拉刷新照常取消它。刷新整条链路（首屏 + 空页追载）和刷新后的第一次翻页都不受限：
+  那是用户的动作，追载又有跳数硬上限跑不飞，节流它只会让重过滤用户（#729）首屏多白等。
+- **连翻预算** `maxAutoPages`（默认 30 页）：跑飞和人的区别不在翻了多少页，而在页与页之间
+  有没有停下来看（线上人类重度翻页 12–20 s/页，跑飞 ≤ 2.4 s/页）。两页之间隔了
+  `burstIdleResetMs`（默认 5 s）以上预算就归零，所以自己账号的收藏、关注动态翻多深都碰不到；
+  连着翻满就置 `FeedUiState.appendPaused`，之后滚动触发一律忽略，footer 变成
+  「点击加载更多」，用户点一下 `continueAppend()` 再给一份预算。预算判定排在空页追载
+  （`MAX_EMPTY_PAGE_HOPS`）之前——薄页和整页滤空烧的是同一份预算。
+
+没有网络代价的数据源（本地库）可覆写 `pagingPolicy()` 返回 `FeedPagingPolicy.Unlimited`。
+与 `refreshAfterCacheHit()` 同一契约：每次现读、纯内存、不抛。

feeds/src/main/java/ceui/pixiv/feeds/AppendFooter.kt

@@ -4,17 +4,23 @@ import androidx.core.view.isVisible
 import ceui.pixiv.feeds.databinding.ItemFeedAppendFooterBinding
 
 /**
- * 框架内部的翻页 footer：追加中转菊花，追加失败变「点击重试」。
- * 由 [FeedFragment] 根据 [FeedUiState.append] 拼进展示列表，业务不感知。
+ * 框架内部的翻页 footer：追加中转菊花，追加失败变「点击重试」，自动翻页预算用完变
+ * 「点击加载更多」。由 [FeedFragment] 根据 [FeedUiState.append] / [FeedUiState.appendPaused]
+ * 拼进展示列表，业务不感知。
  */
-internal data class AppendFooterItem(val state: LoadState) : FeedItem {
+internal data class AppendFooterItem(
+    val state: LoadState,
+    /** [FeedUiState.appendPaused]：预算用完等用户点「继续」。与 Loading / Error 互斥。 */
+    val paused: Boolean = false,
+) : FeedItem {
 
     override val feedKey: Any
         get() = "feeds:append_footer"
 }
 
 internal class AppendFooterRenderer(
     private val onRetry: () -> Unit,
+    private val onContinue: () -> Unit,
 ) : FeedRenderer<AppendFooterItem, ItemFeedAppendFooterBinding>(
     AppendFooterItem::class.java,
     ItemFeedAppendFooterBinding::inflate,
@@ -25,15 +31,19 @@ internal class AppendFooterRenderer(
 
     override fun onCreate(cell: FeedCell<AppendFooterItem, ItemFeedAppendFooterBinding>) {
         cell.binding.root.setOnClickListener {
-            if (cell.itemOrNull?.state is LoadState.Error) {
-                onRetry()
+            val item = cell.itemOrNull ?: return@setOnClickListener
+            when {
+                item.paused -> onContinue()
+                item.state is LoadState.Error -> onRetry()
             }
         }
     }
 
     override fun onBind(cell: FeedCell<AppendFooterItem, ItemFeedAppendFooterBinding>) {
         val isError = cell.item.state is LoadState.Error
-        cell.binding.feedFooterProgress.isVisible = !isError
+        val isPaused = cell.item.paused
+        cell.binding.feedFooterProgress.isVisible = !isError && !isPaused
         cell.binding.feedFooterError.isVisible = isError
+        cell.binding.feedFooterPaused.isVisible = isPaused
     }
 }

feeds/src/main/java/ceui/pixiv/feeds/FeedFragment.kt

@@ -195,7 +195,10 @@ abstract class FeedFragment(
         binding.feedSkeleton.removeAllViews()
 
         val adapter = FeedAdapter(
-            renderers = onCreateRenderers() + AppendFooterRenderer { feedViewModel.retryAppend() },
+            renderers = onCreateRenderers() + AppendFooterRenderer(
+                onRetry = { feedViewModel.retryAppend() },
+                onContinue = { feedViewModel.continueAppend() },
+            ),
             onNearEnd = { if (loadMoreEnabled) feedViewModel.loadMore() },
         )
         feedAdapter = adapter
@@ -488,8 +491,11 @@ abstract class FeedFragment(
     /** adapter 现取不缓存：[rebuildList] 换过 adapter 之后，长活的 uiState collector 不能再往旧的提交。 */
     private fun render(state: FeedUiState) {
         val adapter = feedAdapter ?: return
-        val displayList = when (val append = state.append) {
-            is LoadState.Loading, is LoadState.Error -> state.items + AppendFooterItem(append)
+        val displayList = when {
+            state.append is LoadState.Loading || state.append is LoadState.Error ->
+                state.items + AppendFooterItem(state.append)
+            // 自动翻页预算用完：还有下一页，footer 变「点击加载更多」等用户点
+            state.appendPaused -> state.items + AppendFooterItem(state.append, paused = true)
             else -> state.items
         }
         // 整代替换（下拉刷新 / 冷启的缓存→网络）**且新旧两代真的会撕**时才绕开 DiffUtil，

feeds/src/main/java/ceui/pixiv/feeds/FeedSource.kt

@@ -10,6 +10,53 @@ data class FeedPage<Cursor : Any>(
     val nextCursor: Cursor?,
 )
 
+/**
+ * 自动翻页的节奏与预算。
+ *
+ * 触底预取是零间隔的：一页只剩一两条可展示（其余被 R-18 / 屏蔽等本地过滤掉）时，那一两条
+ * 一绑定就落在预取区、立刻再翻一页——线上遥测里一次搜索 48 秒翻 89 页、一直翻到 pixiv 的
+ * 5000 条 offset 上限，全是这个形态，没有一个是人在看。两条闸门把它压回人的节奏：
+ *
+ * - [minPageIntervalMs]：相邻两次 [FeedViewModel.loadMore] 网络翻页之间的最小间隔（含空页
+ *   追载的每一跳），以上一页返回时刻起算。等待期间 footer 照常转圈，预取信号不会丢。
+ *   首屏 / 下拉刷新整条链路不受限，刷新后的第一次翻页也不受限——那是用户的动作，
+ *   而且刷新自带的空页追载有 [FeedViewModel] 的跳数硬上限，跑不飞，节流它只会让重过滤
+ *   用户的首屏多白等。
+ * - [maxAutoPages]：**连着翻**的页数预算。跑飞和人的区别不在翻了多少页，而在页与页之间有
+ *   没有停下来看：线上人类重度翻页 12–20 s/页，跑飞 ≤ 2.4 s/页。所以两页之间隔了
+ *   [burstIdleResetMs] 以上就算「看过了」，预算归零——自己账号的收藏、关注动态翻多深都碰
+ *   不到它；薄页跑飞（节流后 1 s 一页）30 页后停下，footer 变成「点击加载更多」，用户点一下
+ *   再给一份预算（[FeedViewModel.continueAppend]）。
+ *
+ * 默认值 [Default] 全框架生效。个别数据源（本地库、无网络代价的列表）可覆写
+ * [FeedSource.pagingPolicy] 放宽到 [Unlimited]。
+ */
+data class FeedPagingPolicy(
+    val maxAutoPages: Int = DEFAULT_MAX_AUTO_PAGES,
+    val minPageIntervalMs: Long = DEFAULT_MIN_PAGE_INTERVAL_MS,
+    val burstIdleResetMs: Long = DEFAULT_BURST_IDLE_RESET_MS,
+) {
+    init {
+        require(maxAutoPages >= 1) { "maxAutoPages 至少为 1（无上限用 Unlimited）：$maxAutoPages" }
+        require(minPageIntervalMs >= 0) { "minPageIntervalMs 不能为负：$minPageIntervalMs" }
+        require(burstIdleResetMs >= 0) { "burstIdleResetMs 不能为负：$burstIdleResetMs" }
+    }
+
+    companion object {
+        const val DEFAULT_MAX_AUTO_PAGES: Int = 30
+        const val DEFAULT_MIN_PAGE_INTERVAL_MS: Long = 1_000L
+        const val DEFAULT_BURST_IDLE_RESET_MS: Long = 5_000L
+
+        val Default: FeedPagingPolicy = FeedPagingPolicy()
+
+        /** 不节流、不设预算：只给没有网络代价的数据源用。 */
+        val Unlimited: FeedPagingPolicy = FeedPagingPolicy(
+            maxAutoPages = Int.MAX_VALUE,
+            minPageIntervalMs = 0L,
+        )
+    }
+}
+
 /**
  * 数据源契约：一个必做的 suspend [load]，外加一个可选的本地优先能力 [loadFromCache]。
  *
@@ -56,4 +103,12 @@ fun interface FeedSource<Cursor : Any> {
      * 抛出来会经 viewModelScope 直奔线程默认处理器崩掉进程；要读磁盘请改用 [loadFromCache]。
      */
     fun refreshAfterCacheHit(): Boolean = true
+
+    /**
+     * 自动翻页的节奏与预算，默认 [FeedPagingPolicy.Default]（全框架统一的闸门）。
+     *
+     * 每次 [FeedViewModel.refresh] / [FeedViewModel.loadMore] 现读。与 [refreshAfterCacheHit]
+     * 同一契约：必须是廉价的纯内存判断，**不要碰 IO、不要抛**。
+     */
+    fun pagingPolicy(): FeedPagingPolicy = FeedPagingPolicy.Default
 }

feeds/src/main/java/ceui/pixiv/feeds/FeedUiState.kt

@@ -16,6 +16,13 @@ data class FeedUiState(
     val append: LoadState = LoadState.Idle,
     /** 是否已翻到底（没有下一页游标）。 */
     val reachedEnd: Boolean = false,
+    /**
+     * 自动翻页预算（[FeedPagingPolicy.maxAutoPages]）已用完：还有下一页，但不再由滚动触发，
+     * footer 变成「点击加载更多」，等用户点 [FeedViewModel.continueAppend] 再给一份预算。
+     * 与 [reachedEnd] 互斥（到底了就没有「继续」可言）：refresh 整代提交和游标交接
+     * （[FeedViewModel.adoptCursor]）都把它清掉。
+     */
+    val appendPaused: Boolean = false,
     /** 是否成功完成过至少一次刷新，用于区分「首屏加载」和「后续刷新」。 */
     val hasLoadedOnce: Boolean = false,
     /**