Merge branch 'feat/w80-voice-failed-status-judgment' into android

后端 M57-M59 预告（devdocs/02 第 1255/1260 行我们的答复）：`voice` 键在不再等于
「这是一段能播的声音」。合成降级 / 入站转写失败的行 `status = "failed"`，正文是一句话，
`fallbackReason` 里给出降级原因——按老判据会被画成一个点下去必然播不了的语音气泡。

判据拆成两问，各自落在一处（domain/chat/VoiceMessage.kt）：
- `hasVoice` = `voice` 键存在 —— 「这条**来自**一段声音」；
- `isPlayableVoice` = `status != "failed"` —— 认不出的 status 一律当可播（fail-open：
  多画一枚语音形态最坏是点了播不出来，有既有失败文案兜着；反方向会把真有副本的语音
  静默吞成纯文字，用户再也点不到）；
- `isVoiceMessage` = 两者相与 —— 「画不画语音形态」。

failed 行改画「正文 + 一行灰色小标」：`voiceFallbackNote` 给固定前半句 + 服务端
`fallbackReason` **原样**（不猜闭集、不做映射——取值集合后端尚未定稿；缺席/空白时退化成
固定那一句，不白屏）。新组件 `VoiceFallbackNote` 用 footnote2 +
onSurfaceVariantSummary，与语音形态旁边那几句脚注同一档。

`isContentlessUserMessage` 挂 `hasVoice` 而**不**是 `isVoiceMessage`：failed 行虽没有语音
形态，但有正文和那行小标，同样不是「什么都没有」——判错了屏幕上会多一句假的
「内容没有被传过来」。`messageTimeCarrier` 同理按 `hasVoice` 挑落脚点。

DTO 上补第八个键 `fallbackReason`（只在 failed 时有，`explicitNulls = false` 时不写出），
所以转写成功的行键集仍是原来七个。

验证：`assembleDebug` + `testDebugUnitTest` 全绿，142 个测试文件 / 1766 个用例 / 0 失败
（基线 1755，新增 11 条；VoiceMessageTest 20、VoiceDtoTest 13、WsEventPersistedVoiceTest 7）。

.gitignore

@@ -12,3 +12,7 @@ captures/
 .cxx/
 # 主人从手机丢进仓库根当素材用的图（例如换图标用的原图）——只用不存，绝不进仓库
 /IMG_*.png
+# 开发文档 —— **主人 2026-10-07 明确指令：整个文件夹禁止进入远程仓库**。
+# 它只在本机磁盘上（前后端协同留言板、进度交接、设计拆解都在里面），靠磁盘本身交接。
+# 凭据同样绝不写进去（那类东西在 dev-secrets.local.md）。
+devdocs/

app/src/main/AndroidManifest.xml

@@ -1,6 +1,40 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
+    <!--
+        「后台保持连接」用到的三个权限（设置页那个开关，默认关）：
+
+        - FOREGROUND_SERVICE：起前台服务本身。
+        - FOREGROUND_SERVICE_DATA_SYNC：前台服务的类型权限（API 34+ 与 android:foregroundServiceType
+          配合）。选 dataSync 是因为这条服务保的是一条**长连接**——保持与后端的实时同步，
+          既不是 mediaPlayback 也不是 location，声明成别的类型才是说谎。
+        - POST_NOTIFICATIONS：前台服务必须有一条通知，而 minSdk 33 ⇒ 它恒是运行时权限。
+          用户拒绝时开关**打不开**（判据见 core.keepalive.shouldKeepAliveRun），本端不偷偷跑。
+    -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <!--
+        「用户按住麦克风说话」用的麦克风权限（契约 v0.96 §3.15 ①）。
+
+        它是**运行时权限**（minSdk 33 ⇒ 恒是）：本端只在用户**第一次点麦克风**时申请，
+        被拒之后不再重复申请（Android 不会二次弹框，重复申请等于点了没反应），
+        改由真机设置页授权——文案见 `ui.chat.VOICE_PERMISSION_DENIED_MESSAGE`。
+        没有这个权限时录音机直接起不来，本端如实说一句，绝不假装在录。
+    -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+
+    <!--
+        联网权限**显式**声明，不靠任何传递依赖。
+
+        事实（W52K 跑 `:app:processReleaseMainManifest` 核过）：本端一直能联网，是靠
+        `com.squareup.okhttp3:okhttp-android:5.5.0` 的清单把 `INTERNET` 合并进来的；而 debug 那边
+        AGP 也注入同一份 ⇒ **本地怎么试都看不出来**。一旦换掉/排除那个依赖，release 会**静默失去**
+        网络权限（不报错、只是所有请求都失败）。显式写在这里，从此与第三方清单无关。
+    -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
     <application
         android:name=".app.CyreneApplication"
         android:allowBackup="false"
@@ -65,6 +99,21 @@
                 android:resource="@xml/file_paths" />
         </provider>
 
+        <!--
+            「后台保持连接」的前台服务（设置页开关控制，默认关）。
+
+            exported="false"：它没有任何对外接口（onBind 返回 null），只由本进程 start/stop。
+
+            foregroundServiceType="dataSync"：这条服务的职责是让进程活着，从而让那条**进程级共享**
+            的实时连接（AppContainer.chatSocket）不被 Android 12+ 的 cached 进程冻结掐断——
+            语义上就是「后台数据同步」。它不自己去建立 / 关闭任何连接，连接的主人是
+            SessionsViewModel（见 KeepAliveService 的类注释）。
+        -->
+        <service
+            android:name=".core.keepalive.KeepAliveService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+
     </application>
 
 </manifest>

app/src/main/kotlin/top/yeij/cyrene/app/AppContainer.kt

@@ -3,21 +3,28 @@ package top.yeij.cyrene.app
 import android.content.Context
 import top.yeij.cyrene.core.auth.AuthManager
 import top.yeij.cyrene.core.auth.SessionStore
+import top.yeij.cyrene.core.notify.AppPresence
+import top.yeij.cyrene.core.notify.ProactiveNotifier
+import top.yeij.cyrene.core.notify.postProactiveNotification
 import top.yeij.cyrene.core.prefs.AppSettings
 import top.yeij.cyrene.core.prefs.EnumPreferences
 import top.yeij.cyrene.core.prefs.SessionPreferences
+import top.yeij.cyrene.core.session.ChatSessionSlots
 import top.yeij.cyrene.core.session.GoneSessions
 import top.yeij.cyrene.data.api.AdminApi
 import top.yeij.cyrene.data.api.ApiClientFactory
 import top.yeij.cyrene.data.api.ChatApi
 import top.yeij.cyrene.data.api.DocumentsApi
+import top.yeij.cyrene.data.api.MediaApi
 import top.yeij.cyrene.data.api.MetaApi
 import top.yeij.cyrene.data.api.PersonaApi
 import top.yeij.cyrene.data.api.SessionsApi
 import top.yeij.cyrene.data.api.UploadApi
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
 import top.yeij.cyrene.data.repository.AdminRepository
 import top.yeij.cyrene.data.repository.ChatRepository
 import top.yeij.cyrene.data.repository.DocumentRepository
+import top.yeij.cyrene.data.repository.MediaRepository
 import top.yeij.cyrene.data.repository.MessageRepository
 import top.yeij.cyrene.data.repository.MetaRepository
 import top.yeij.cyrene.data.repository.PersonaRepository
@@ -41,11 +48,56 @@ class AppContainer(context: Context) {
      * 本端已知「服务端没有这个会话」的那几个 id（**进程级**，与 [chatSocket] 同一层）。
      *
      * 跨两个 VM 的唯一共享面：写它的是 `SessionsViewModel`（本端唯一的删除入口），读它的是
-     * **每一个** `ChatViewModel`（它们各留一个常驻 VM，删会话不回收）。它拦下的是那一轮注定
-     * `404 session_not_found` 的补拉 —— 理由与「为什么不持久化」见 [GoneSessions] 的类注释。
+     * **每一个还活着的** `ChatViewModel`（它们在 [chatSessionSlots] 没回收之前都活着、都订阅着
+     * 那条共享连接）。它拦下的是那一轮注定 `404 session_not_found` 的补拉 —— 理由与
+     * 「为什么不持久化」见 [GoneSessions] 的类注释。
      */
     val goneSessions: GoneSessions = GoneSessions()
 
+    /**
+     * 「App 在不在前台」「聊天页显示着哪个会话」（**进程级**，与 [chatSocket] / [goneSessions]
+     * 同一层）：写它的是 `MainActivity`（`onStart` / `onStop`）与 `ChatScreen`（组合进出），
+     * 读它的是 [proactiveNotifier]。为什么不引 `ProcessLifecycleOwner` 见 [AppPresence] 的类注释。
+     */
+    val appPresence: AppPresence = AppPresence()
+
+    /** 「点通知进来要看主会话」那笔待落地的意图（写：`MainActivity`，消费：`ChatHomeScreen`）。 */
+    val proactiveTapIntake: ProactiveTapIntake = ProactiveTapIntake()
+
+    /**
+     * 「她主动说的话」的通知通路（W53N）：判据、去重与落地都在里面，Android 那一步从这里注入。
+     *
+     * 它**不订阅任何东西**（帧由 [proactiveFrameIntake] 喂进来），因此与连接的所有权完全无关
+     * ——本端那条共享连接的生死仍然只在登录态那一处表达。
+     */
+    val proactiveNotifier: ProactiveNotifier = ProactiveNotifier(
+        presence = appPresence,
+        post = { text, notificationId ->
+            // 「免打扰」**每次现读**（`AppSettings.current` 是那份热副本）：开关一改，下一条通知就
+            // 换一条渠道，不必重启 App。为什么不能在这里挂起读一次、以及那个毫秒级窗口是怎么回事，
+            // 都写在 `AppSettings.current` 的 KDoc 里。
+            postProactiveNotification(
+                context = appContext,
+                text = text,
+                notificationId = notificationId,
+                quiet = appSettings.current.value.proactiveQuiet,
+            )
+        },
+    )
+
+    /**
+     * 会话槽位账本（**进程级**）：本端为一个账号留着的聊天状态，一格一份 `ViewModelStore`。
+     *
+     * 它把 S4 那笔技术债收在一处：`ChatViewModel` 是按会话建的，此前访问过多少个会话就有多少份
+     * 常驻内存（消息列表含内联 base64 图片）与多少份对共享连接的订阅；现在最多留
+     * [top.yeij.cyrene.core.session.CHAT_SESSION_SLOT_KEEP] 格，超出的按「最后一次成为当前会话」
+     * 从旧到新交出去（判据是纯函数 `core.session.chatSessionEvictions`）。
+     *
+     * 与 [goneSessions] 同一层、同一批读者（写它的是 `ChatScreen` 与 `SessionsViewModel`）。
+     * 主会话 id 在这里注入，是为了让 `core.session` 那两层不认识 `ui.chat` 的那个常量。
+     */
+    val chatSessionSlots: ChatSessionSlots = ChatSessionSlots(SessionSummaryDto.MAIN_SESSION_ID)
+
     private var cachedBaseUrl: String? = null
     private var cachedSessionsApi: SessionsApi? = null
 
@@ -146,6 +198,34 @@ class AppContainer(context: Context) {
 
     val documentRepository: DocumentRepository get() = DocumentRepository(documentsApi)
 
+    private var cachedMediaApi: MediaApi? = null
+    private var cachedMediaBaseUrl: String? = null
+
+    /**
+     * 语音副本端点（`GET /api/v1/media/{name}`，契约 §1.2 **U19**）；与 [documentsApi] **同一套门**：
+     * `owner|admin` **必须 Bearer**（与图片读侧「名字即凭据」刻意相反 —— 语音是私密内容）。
+     *
+     * 同样与 [chatApi] 同源（同一 baseUrl、同一 token/401 处理）：`voice.url` 是**服务端相对路径**，
+     * 只有落在**同一台后端**上才取得到那份副本。
+     */
+    val mediaApi: MediaApi
+        get() {
+            val baseUrl = authManager.currentBaseUrl
+            val cached = cachedMediaApi
+            if (cached != null && cachedMediaBaseUrl == baseUrl) return cached
+            val created = ApiClientFactory.create(
+                baseUrl = baseUrl,
+                service = MediaApi::class.java,
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
+            )
+            cachedMediaBaseUrl = baseUrl
+            cachedMediaApi = created
+            return created
+        }
+
+    val mediaRepository: MediaRepository get() = MediaRepository(mediaApi)
+
     private var cachedAdminApi: AdminApi? = null
     private var cachedAdminBaseUrl: String? = null
 
@@ -226,9 +306,12 @@ class AppContainer(context: Context) {
      * 每个 `ChatSocket` 都自带一个 `OkHttpClient`（各自的连接池 / ping / 重连循环）。改前
      * `ChatViewModel`（**每个会话一个 VM**）、[top.yeij.cyrene.ui.sessions.SessionsViewModel]、
      * [top.yeij.cyrene.ui.admin.AdminViewModel] 各自建了一条（`ChatViewModel.start()`、
-     * 两个 VM 的 init）⇒ 访问 N 个会话 = N+2 条连接、N+2 个 `OkHttpClient`；而 VM 活在 Activity 级
-     * `ViewModelStore` 里，**切走 / 删会话都不回收**。现在这里就是唯一的持有者（`by lazy`，只此一份），
-     * 调用方只订阅 [ChatSocket.events] / [ChatSocket.state]。
+     * 两个 VM 的 init）⇒ 访问 N 个会话 = N+2 条连接、N+2 个 `OkHttpClient`。现在这里就是唯一的
+     * 持有者（`by lazy`，只此一份），调用方只订阅 [ChatSocket.events] / [ChatSocket.state]。
+     *
+     * **每个会话那个 VM 常驻的那一半**（S4）由 [chatSessionSlots] 收：本端最多留
+     * [top.yeij.cyrene.core.session.CHAT_SESSION_SLOT_KEEP] 格，多出来的整格交出去。这一条与
+     * 本段说的是**两件事**：连接只有一条，而订阅它的 VM 有几格 —— 前者与本类同一层，后者在账本里。
      *
      * ## 开与关只有一个主人
      * [top.yeij.cyrene.ui.sessions.SessionsViewModel] 的登录态订阅：`LoggedIn → connect()`、
@@ -244,4 +327,22 @@ class AppContainer(context: Context) {
             onAuthFailed = authManager::onSessionExpired,
         )
     }
+
+    /**
+     * 「她主动说的话 ⇒ 弹通知」那条通路在**帧这一层的消费点**（W57，**进程级**）：把 [chatSocket]
+     * 上那两种帧交给 [proactiveNotifier]。构造即订阅，此后与进程同寿（没有 start / stop 的理由
+     * 见 [ProactiveFrameIntake] 的类注释）。
+     *
+     * 改前这份订阅挂在 `SessionsViewModel` 的 `viewModelScope` 上（它随 Activity 一起结束），于是
+     * 「从最近任务划掉 App、进程还被 `KeepAliveService` 撑着」那一档：帧到了 [chatSocket]、
+     * 一个订阅者都没有，而 `events` 是 `replay = 0` 的 `SharedFlow` ⇒ 当场丢掉，通知永远不弹。
+     *
+     * 声明在这里（类的末尾）有一个顺序上的理由：它要同时用到 [proactiveNotifier] 与 [chatSocket]，
+     * 而 [chatSocket] 是本类最后声明的那个（Kotlin 按声明顺序初始化）。读 [ChatSocket.events] 会把
+     * 那条连接对象提前建出来——本容器与它同时诞生、同时活着，这一步没有任何代价。
+     */
+    val proactiveFrameIntake: ProactiveFrameIntake = ProactiveFrameIntake(
+        events = chatSocket.events,
+        notifier = proactiveNotifier,
+    )
 }

app/src/main/kotlin/top/yeij/cyrene/app/CyreneApp.kt

@@ -5,8 +5,14 @@ import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.platform.LocalContext
 import kotlinx.coroutines.launch
 import top.yeij.cyrene.core.auth.SessionState
+import top.yeij.cyrene.core.keepalive.KeepAliveAction
+import top.yeij.cyrene.core.keepalive.KeepAliveService
+import top.yeij.cyrene.core.keepalive.keepAliveAction
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+import top.yeij.cyrene.core.prefs.LocalAppPrefs
 import top.yeij.cyrene.ui.chat.ChatHomeScreen
 import top.yeij.cyrene.ui.common.LoadingScreen
 import top.yeij.cyrene.ui.login.LoginScreen
@@ -14,12 +20,44 @@ import top.yeij.cyrene.ui.login.LoginScreen
 @Composable
 fun CyreneApp(container: AppContainer) {
     val state by container.authManager.state.collectAsState()
+    val prefs = LocalAppPrefs.current
+    val context = LocalContext.current
     val scope = rememberCoroutineScope()
 
     LaunchedEffect(Unit) {
         container.authManager.bootstrap()
     }
 
+    /*
+     * 后台保持连接：**全 App 唯一一处**决定那条前台服务的起停。
+     *
+     * 这里是合适的位置，因为它是「开关（App 偏好）与登录态碰头」的最小汇合点：偏好由
+     * CyreneRoot 读出来经 LocalAppPrefs 下发，登录态本来就订阅在本函数里。判据本身是纯函数
+     * （core.keepalive.keepAliveAction），两种状态各自变化都会把这一次重跑一遍，于是
+     * 「启动时开关开着且已登录 ⇒ 服务在跑」「登出 ⇒ 停」「开关关掉 ⇒ 停」都不用另外写路径。
+     *
+     * 权限每次**现读**（不缓存在 remember 里）：会话自举完成那一刻读到的就是当下的真实授权，
+     * 而授权变化只有两条路——本端刚申请完（设置页那次写入会连带把这里重跑一遍）、或用户在系统
+     * 设置里改过（下次启动必然重跑）。
+     */
+    // ⚠️ key 里必须有「回到前台」这一位（W53S 登记的那一格）：通知权限是**现读**的，而用户在系统
+    // 设置里授权后回到 App 时，只有这个状态会变 —— 少了它，UI 会说「已开」而服务其实没起。
+    val appInForeground by container.appPresence.appInForegroundFlow.collectAsState()
+    LaunchedEffect(prefs.keepAliveEnabled, state, appInForeground) {
+        when (
+            keepAliveAction(
+                enabled = prefs.keepAliveEnabled,
+                sessionKnown = state !is SessionState.Unknown,
+                loggedIn = state is SessionState.LoggedIn,
+                notificationsAllowed = context.notificationsAllowed(),
+            )
+        ) {
+            KeepAliveAction.Start -> KeepAliveService.start(context)
+            KeepAliveAction.Stop -> KeepAliveService.stop(context)
+            KeepAliveAction.Leave -> Unit
+        }
+    }
+
     when (state) {
         SessionState.Unknown -> LoadingScreen()
         SessionState.LoggedOut -> LoginScreen(container)

app/src/main/kotlin/top/yeij/cyrene/app/MainActivity.kt

@@ -7,6 +7,9 @@ import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 
 class MainActivity : ComponentActivity() {
+
+    private val container: AppContainer get() = (application as CyreneApplication).container
+
     override fun onCreate(savedInstanceState: Bundle?) {
         enableEdgeToEdge()
         super.onCreate(savedInstanceState)
@@ -17,22 +20,47 @@ class MainActivity : ComponentActivity() {
         // intent 再送一遍，照单全收就会把同一条分享发第二次。重建带 savedInstanceState，
         // 冷启动不带——这就是判据。
         if (savedInstanceState == null) {
-            intent?.let { ShareIntake.accept(this, it) }
+            intent?.let {
+                ShareIntake.accept(this, it)
+                // 点她那条通知冷启动进来：记一笔「要看主会话」（见 ProactiveTapIntake）。
+                // 与分享同一个判据：重建时系统会把同一个 intent 再送一遍，那时不能重复记账
+                // （重复没有害处，但「冷启动才接」这条纪律只有一处，别在两处各写一半）。
+                container.proactiveTapIntake.accept(it)
+            }
         }
-        val container = (application as CyreneApplication).container
         setContent {
             CyreneRoot(container)
         }
     }
 
+    /**
+     * 本 App 只有**一个** Activity（`singleTop`），所以它的 start / stop 就是「App 有没有在被看」
+     * ——这是「她主动说的话该不该弹通知」的两半之一（见 `core.notify.shouldNotifyProactive`）。
+     *
+     * 报的是**实例**而不是一个布尔量：旋转 / 系统深浅色切换会让新实例的 `onStart` 先于旧实例的
+     * `onStop`，布尔量在那一刻必然被记成「后台」，于是用户正看着聊天页她却弹一条通知出来。
+     * 集合由 [AppPresence] 自己持有，这里只报自己。
+     */
+    override fun onStart() {
+        super.onStart()
+        container.appPresence.onActivityStarted(this)
+    }
+
+    override fun onStop() {
+        container.appPresence.onActivityStopped(this)
+        super.onStop()
+    }
+
     /**
      * 热启动（`launchMode="singleTop"`）：App 已经开着时系统不再新建实例，只回调这里。
-     * 不接这一路的话，「从浏览器分享 → 回到已经开着的 Cyrene」会一点反应都没有。
+     * 不接这一路的话，「从浏览器分享 → 回到已经开着的 Cyrene」会一点反应都没有，而
+     * 「点她的通知 → 回到已经开着的 Cyrene（可能停在设置页）」同理。
      */
     override fun onNewIntent(intent: Intent) {
         super.onNewIntent(intent)
         // 让 getIntent() 与新到的 intent 一致（系统不会自己更新它），否则后续读到的还是旧的那个。
         setIntent(intent)
         ShareIntake.accept(this, intent)
+        container.proactiveTapIntake.accept(intent)
     }
 }

app/src/main/kotlin/top/yeij/cyrene/app/ProactiveFrameIntake.kt

@@ -0,0 +1,136 @@
+package top.yeij.cyrene.app
+
+import android.util.Log
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.BuildConfig
+import top.yeij.cyrene.core.notify.ProactiveNotifier
+import top.yeij.cyrene.data.ws.WsEvent
+
+private const val LOG_TAG = "ProactiveFrameIntake"
+
+/** 一帧「她主动说的话」剥出来的东西：[ProactiveNotifier.onProactiveFrame] 的四个入参 + 会话归属。 */
+internal data class ProactiveFrame(
+    val sessionId: String?,
+    val id: String?,
+    val messageId: String?,
+    val timestamp: String?,
+    val content: String,
+)
+
+/**
+ * 这一帧算不算「她主动说的话」，以及那四个入参各取帧上的哪个键——**纯函数**（离线可穷举）。
+ *
+ * 只有两种帧是她主动说的话，它们对应服务端两条路（见 [ProactiveNotifier]）：
+ * 1. [WsEvent.ProactiveMessage]（实时帧 `proactive_message`）——`id` 取落库行键 `data.id`，`messageId`
+ *    取 IM 侧消息号，两者**不是同一个 id**（见那个事件的 KDoc）；
+ * 2. [WsEvent.MessagePersisted] **且** `proactive == true`（IM 桥那条路补发的落库帧）——这一档只有
+ *    落库行的键（`message.id`），另外两个键帧上就没有，所以恒给 `null`，一个字都不许编。
+ *
+ * 其余帧一律 `null`：普通落库广播、流式增量、别的事件都不是「她主动找我说话」。判据错在这一层的
+ * 两个方向都很难在真机上发现——要么她开口了却什么都不弹（要等下一次主动消息才看得见），要么普通
+ * 消息也弹（每一次她正常回话都响）。
+ */
+internal fun proactiveFrameOf(event: WsEvent): ProactiveFrame? = when (event) {
+    is WsEvent.ProactiveMessage -> ProactiveFrame(
+        sessionId = event.sessionId,
+        id = event.id,
+        messageId = event.messageId,
+        timestamp = event.timestamp,
+        content = event.content,
+    )
+
+    is WsEvent.MessagePersisted -> {
+        if (!event.proactive) {
+            // 普通落库广播（她回话、别的端发的消息都走这一帧）：主人只批了 proactive 这一档。
+            null
+        } else {
+            ProactiveFrame(
+                sessionId = event.sessionId,
+                id = event.message?.id,
+                messageId = null,
+                timestamp = null,
+                content = event.message?.content.orEmpty(),
+            )
+        }
+    }
+
+    else -> null
+}
+
+/**
+ * 「她主动说的话 ⇒ 弹系统通知」那条通路的**帧消费点**（W57，**进程级**）。
+ *
+ * ## 为什么必须提到这一层（改前那一档是坏的）
+ * 这条通路的判据与去重一直是对的，错的是**订阅挂在哪**。改前它是 `SessionsViewModel` 里那句
+ * `viewModelScope.launch { socket.events.collect(::onEvent) }`。连接倒是进程级的——划掉 Activity
+ * 之后它照样连着、照样在收帧——但 `viewModelScope` 随 Activity 一起结束，而 `ChatSocket.events`
+ * 是 `replay = 0` 的 `SharedFlow`：**没有订阅者的 `tryEmit` 就是当场丢掉**（它不替将来的订阅者
+ * 留任何东西）。于是「从最近任务把 App 划掉、进程还被前台服务撑着」那一档，她的话进了连接、
+ * 然后没了。
+ *
+ * 本类因此只做一件事：**在进程级订那份帧流**，把 [proactiveFrameOf] 认出的帧交给 [ProactiveNotifier]。
+ * 它不建连接、不关连接、不认识登录态——连接的所有权一个字节都没动，仍然只在登录态那一处表达
+ * （`SessionsViewModel` 的 `LoggedIn → connect()` / `LoggedOut → close()`）。
+ *
+ * ## 为什么没有 start() / stop()
+ * 它的生命周期**就是进程**：`AppContainer` 在 `Application.onCreate` 里构造它，此后一直活着。
+ * 刻意不提供 `stop()` 正是这次要修的那个 bug——**唯一会想到去调 stop 的调用方（某个 ViewModel）
+ * 会随 Activity 一起死**，那等于把这条通路又绑回 Activity 上；留一个可以被忘掉调用的 `start()`
+ * 也只是多一种坏法（忘调 = 通知整个哑掉，且没有任何报错）。
+ *
+ * 它不需要停：帧只有连接活着才可能到，而连接在登出（含令牌失效那条经 `onAuthFailed` 的路径）时
+ * 由登录态关掉。「登出期间收不到帧」这件事由**连接**保证，不靠这里取消订阅。去重账本也**刻意不**
+ * 在这里清：它是 `ProactiveNotifier` 里的进程级账本，而换了账号之后同一条消息再推一次，仍是
+ * 同一个人的同一句话，不该弹第二遍。
+ *
+ * ## 它现在是这条通路上唯一的帧消费点
+ * 改前 `SessionsViewModel` 里那两处转交已经删掉（留两处就等于靠去重去替一次重复消费擦屁股，
+ * 而且「谁在喂通知」会有两个答案）。所以这条订阅一旦死掉，通知就**整个**哑掉——兜底见 [deliver]。
+ *
+ * @param events 进程内唯一那条连接的帧流（`ChatSocket.events`）。
+ * @param notifier 判据 + 去重 + 落地那一处。本类只喂帧，不替它判断任何事（那两个入参是它自己的
+ *   事实与动作，见它的 KDoc）。
+ * @param dispatcher 收集用的调度器；单测传 `Dispatchers.Unconfined`，让帧在同一次 `emit` 里走完。
+ */
+class ProactiveFrameIntake(
+    events: SharedFlow<WsEvent>,
+    private val notifier: ProactiveNotifier,
+    dispatcher: CoroutineDispatcher = Dispatchers.Default,
+) {
+
+    /**
+     * 订阅本身那个 scope：私有，没有第二个人拿得到它，也就没有人能取消这条订阅——本类的全部意义
+     * 就在这里。`SupervisorJob` 只为 [deliver] 那条兜底留余地。
+     */
+    private val scope = CoroutineScope(SupervisorJob() + dispatcher)
+
+    /** 构造即订阅（理由见类注释：启动时刻只有一个，留个能忘调的 `start()` 只会多一种坏法）。 */
+    init {
+        scope.launch { events.collect { event -> proactiveFrameOf(event)?.let(::deliver) } }
+    }
+
+    private fun deliver(frame: ProactiveFrame) {
+        try {
+            notifier.onProactiveFrame(
+                sessionId = frame.sessionId,
+                id = frame.id,
+                messageId = frame.messageId,
+                timestamp = frame.timestamp,
+                content = frame.content,
+            )
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Throwable) {
+            // 落地那一步（建渠道 / notify）万一抛，**这条订阅必须活下来**：它是进程级那唯一一处、
+            // 不会再被重建，而不接住的话异常会打到线程的未捕获处理器（Android 上就是进程当场挂）。
+            // 代价封顶在「这一条通知没弹」——去重账本已经把它记下了，不会为了补它再弹一次。
+            if (BuildConfig.DEBUG) Log.d(LOG_TAG, "这条主动消息的通知没能落地", e)
+        }
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/app/ProactiveTapIntake.kt

@@ -0,0 +1,56 @@
+package top.yeij.cyrene.app
+
+import android.content.Intent
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import top.yeij.cyrene.core.notify.EXTRA_PROACTIVE_OPEN_MAIN_SESSION
+
+/**
+ * 「点她那条通知进来 ⇒ 要看主会话」这条**待落地的意图**（W53N）。
+ *
+ * ## 为什么它必须活在进程里，而不是直接在那次 Intent 里做完
+ * 通知可能在**任何**时刻被点：App 还没起来（冷启动）、已经开着但停在设置页、甚至还没登录。
+ * 而真正能「切到主会话」的只有一处——`ChatHomeScreen` 里那个 `SessionsViewModel`（`select()`），
+ * 它要被组合出来才存在，登录态没定时**根本没有**。所以这里只记一笔「用户要求看主会话」，
+ * 由 `ChatHomeScreen` 在能落地的那一刻取走（与 `ShareIntake` 同一种做法：待落地的意图活在
+ * Compose 与 ViewModel 之外，消费方自己挑时机认领）。
+ *
+ * ## 为什么是 StateFlow 而不是一个布尔
+ * 消费方（`ChatHomeScreen`）在 App 已经开着的时候**已经在组合里**：一个普通布尔量被改成 true
+ * 不会叫醒它，那一次点击就会静默丢掉（用户点了通知，进来还停在设置页）。`StateFlow` 一改值就能
+ * 让订着它的那段组合重跑判据。
+ *
+ * ## 不清理会怎样
+ * 没人消费时它一直是 true（例如点了通知但登录失败）——代价是「重登之后落在主会话」。
+ * 主会话本来就是默认落点（`resolveActiveSession` 在会话没了时也收敛到它），所以这里**刻意不**
+ * 在登出时清掉：留一个不会做错事的意图，好过为了干净而多一条「谁负责清它」的路径。
+ */
+class ProactiveTapIntake {
+
+    private val _openMainSession = MutableStateFlow(false)
+
+    /** 是否有一笔待落地的「切到主会话」。消费方拿到 true 后必须调 [consume]。 */
+    val openMainSession: StateFlow<Boolean> = _openMainSession.asStateFlow()
+
+    /**
+     * 从一次启动 / 热启动的 Intent 里认领这条意图（`MainActivity` 的两条入口都走这里）。
+     *
+     * 判据是这个 extra 的**字面量 true**：别的 Intent（分享、桌面图标）里它缺席，什么都不做。
+     */
+    fun accept(intent: Intent?) {
+        if (intent?.getBooleanExtra(EXTRA_PROACTIVE_OPEN_MAIN_SESSION, false) == true) {
+            requestMainSession()
+        }
+    }
+
+    /** 记下「用户要求看主会话」（与 `accept` 分开，是为了这一半能脱离 Android 单测）。 */
+    fun requestMainSession() {
+        _openMainSession.value = true
+    }
+
+    /** 取走这笔意图（只有真正落地了「切到主会话 + 回到聊天页」的那一次才调）。 */
+    fun consume() {
+        _openMainSession.value = false
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/app/ShareIntake.kt

@@ -48,6 +48,17 @@ import java.util.UUID
  * 猜错等于替用户把一个合规文件变成一次失败；代价是「图片但 provider 没报 MIME」会落到文档路、
  * 被服务端按 `415` 拒（有如实文案）。画廊 / 相机 / MediaStore 都会报图片那一类，风险面很小。
  *
+ * ## 四个 extra 为什么都读「原始值」
+ * `EXTRA_TEXT` / `EXTRA_SUBJECT` / `EXTRA_TITLE` / `EXTRA_STREAM` 一律用 [Intent.rawExtra] 取原始值，
+ * 再由本文件按**形态**分派（[shareStreamExtrasOf] / [shareTextExtrasOf]）。两个理由：逐类型的
+ * `getXxxExtra` 遇到别的形态只会往 logcat 打一句 `ClassCastException` 再把值扔掉（那正是「分享点下去
+ * 什么都没发生」的来处），而本端还要知道「这个 extra 里**到底有没有躺着值**」——那件事纯函数看不到，
+ * 只能由这里如实报进去（两个 `present` 参数）。
+ *
+ * ⚠️ **正文的回落链起点也在这里**：`EXTRA_TEXT` 读不出东西时，`EXTRA_SUBJECT` → `EXTRA_TITLE` 依次
+ * 顶上（[ShareRules.extract]），来源记进 `SharedContent.textSource`。三个都空 / 都读不出来时，这一次
+ * 分享照样要往下走（走「读不进来」那条如实告知），**绝不静默**。
+ *
  * ## 清理
  * 缓存副本只对**产生它的那个进程**有意义（持有者在内存里，进程没了就没人认领），所以
  * 进程启动时整目录删一次（[reset]）。运行期间不做细粒度回收：那些文件在发送失败被回滚到
@@ -90,14 +101,24 @@ object ShareIntake {
      */
     fun accept(context: Context, intent: Intent) {
         val appContext = context.applicationContext
-        // EXTRA_STREAM 一次读原始值、按**形态**分派（规范形态 + 字符串兼容形态），见 [shareStreamExtrasOf]：
-        // 挨个 getParcelableExtra / getParcelableArrayListExtra 去问的话，遇到字符串形态只会拿到两行
-        // `ClassCastException` 加一个 `null`——那正是「分享进来什么都没发生」的来处。
-        val rawStream = intent.streamExtraValue()
+        // 四个 extra 一律读**原始值**、按**形态**分派（见 [shareStreamExtrasOf] / [shareTextExtrasOf]）：
+        // 挨个 getXxxExtra 去问的话，遇到别的形态只会拿到一行 `ClassCastException` 加一个 `null`
+        // ——那正是「分享进来什么都没发生」的来处。读不出形态时本端既不猜、也不闭嘴（见下面两个
+        // `present`）：那照样是一次「带着内容迹象却什么都没读进来」。
+        val rawStream = intent.rawExtra(Intent.EXTRA_STREAM)
         val streamExtras = shareStreamExtrasOf(rawStream)
+        val textExtras = shareTextExtrasOf(
+            text = intent.rawExtra(Intent.EXTRA_TEXT),
+            subject = intent.rawExtra(Intent.EXTRA_SUBJECT),
+            title = intent.rawExtra(Intent.EXTRA_TITLE),
+        )
         val extracted = ShareRules.extract(
             action = intent.action,
-            text = intent.getCharSequenceExtra(Intent.EXTRA_TEXT),
+            // 正文走回落链：EXTRA_TEXT → EXTRA_SUBJECT → EXTRA_TITLE（有些发送方不填 EXTRA_TEXT，
+            // 内容只在后两个里；只读第一个会让那次分享整条静默）。来源记在 `textSource` 里。
+            text = textExtras.text,
+            subject = textExtras.subject,
+            title = textExtras.title,
             // 单值 / 列表两个字段都喂进去（本端不再按 action 猜该读哪个，见 [ShareRules.extract]）。
             stream = streamExtras.uriForms.firstOrNull(),
             streams = streamExtras.uriForms,
@@ -105,6 +126,7 @@ object ShareIntake {
             // 「里面躺着值」这件事只有这里知道（纯函数看不到原始值）：形态认不出的那种也算带着内容，
             // 否则「分享点下去什么都没发生」会从那条缝里回来。
             streamPresent = rawStream != null,
+            textPresent = textExtras.present,
             clipUris = intent.clipUris(),
             // 分流就发生在这一处：读不到类型（null）也按文档路走，见类 KDoc。
             mimeOf = { uri ->
@@ -139,8 +161,12 @@ object ShareIntake {
     /**
      * 取走一条待落地内容（原子出队，只有取到它的那个调用方会去发）；队列为空回 `null`。
      *
-     * 出队是**唯一的认领方式**：消费它的地方会被重建（重组 / 切会话 / Activity 重建），
-     * 所以「已经发过了」这件事不能记在消费方身上（见 [PendingShareHolder]）。
+     * 出队是**唯一的认领方式**，而它在这里是原子的：两个消费者同时来也只会各拿各的一条
+     * （判据见 [PendingShareHolder.take]）。而「**已经认领过了**」这件事此后记在认领它的那一格上
+     * ——`ChatViewModel` 的 [top.yeij.cyrene.ui.chat.ChatUiState.shareConfirm]。那一格活在
+     * `AppContainer` 那一层（`core.session.ChatSessionSlots` 的 `ViewModelStore`），比组合与
+     * Activity 都活得久，所以转屏 / 深浅色切换重建之后**不会再取第二遍**，也不会把队列里下一条顶掉：
+     * 认领的闸门在 `ChatViewModel.claimSharedContent` 里，且在调用本函数**之前**。
      */
     fun take(): SharedContent? = holder.take()
 
@@ -276,14 +302,27 @@ object ShareIntake {
     }
 
     /**
-     * `EXTRA_STREAM` 的原始值（**故意读原始值**，理由见 [ShareStreamExtras]）。
+     * 一个 extra 的**原始值**（四个 extra 共用），取不到回 `null`。
      *
+     * ## 为什么读原始值而不是 `getXxxExtra`
      * `Bundle.get` 在 API 33 起被打上废弃：它绕过类型安全。这里要的正是「绕过类型安全」——要判的
      * 就是「这个值到底是什么形态」。逐类型的 `getXxxExtra` 遇到别的形态只会往 logcat 打一句
-     * `ClassCastException` 再把值扔掉，那正是本次要修的那个静默。
+     * `ClassCastException` 再把值扔掉（`String[]` 形态的 `EXTRA_STREAM` 就是这么静默丢掉的），而那
+     * 正是「分享点下去什么都没发生」的来处。形态分派见 [shareStreamExtrasOf] / [shareTextExtrasOf]。
+     *
+     * ## 为什么要 `runCatching`
+     * `Bundle.get` 第一件事是 `unparcel()`，它会解析别的进程给的字节：里面有个解析不出来的
+     * `Parcelable` 时它抛 `BadParcelableException`（核对过 AOSP 的 `android/os/BaseBundle.java`：
+     * defuse 关着时**直接抛出**，开着时也还要看 `Flags.deprecateBundleDefuse()` 那个 flag）。那是
+     * `RuntimeException`，从 `accept` 冒出去就是 `onCreate` 里的一次崩溃。
+     *
+     * ⚠️ 与它相对的是「类型不符」那种：`Bundle.getCharSequence` 自己 `catch` 了 `ClassCastException`
+     * 并回 `null`（同一个 AOSP 文件），所以那一档**不会**抛异常——但也**读不到值**，于是它只能靠
+     * 本函数给出的原始值被记成「里面躺着值」（见 [ShareTextExtras.present]），不会被静默当成
+     * 「什么都没分享」。两件事一起挡住：畸形 bundle 不当崩，读不出来的值不当没发生。
      */
     @Suppress("DEPRECATION")
-    private fun Intent.streamExtraValue(): Any? = extras?.get(Intent.EXTRA_STREAM)
+    private fun Intent.rawExtra(key: String): Any? = runCatching { extras?.get(key) }.getOrNull()
 
     /**
      * `ClipData` 各条目的 URI（部分 App 只填它）；纯文本条目的 URI 是 `null`。
@@ -344,3 +383,54 @@ internal fun shareStreamExtrasOf(raw: Any?): ShareStreamExtras {
 
     return ShareStreamExtras(uriForms = uriForms, stringForms = stringForms)
 }
+
+/**
+ * `EXTRA_TEXT` / `EXTRA_SUBJECT` / `EXTRA_TITLE` 三个**原始值** ⇒ 能当正文用的那几段。
+ *
+ * ## 为什么也读原始值（而不是 `getCharSequenceExtra` 挨个问）
+ * 两个理由，第一个是「读得回来」，第二个是「读不回来也要知道有东西」：
+ *
+ * 1. `getCharSequenceExtra` 只回「读到 / 没读到」，而本端要按**形态**分派：值可能是 `String`、
+ *    `Spanned`（富文本分享的常态）、`SpannedString`……它们都是 `CharSequence`，但按 `String` 读就
+ *    直接是 `null`（那正是「分享进来什么都没发生」的来处之一）。这里用 `as?` 一次判完：是
+ *    `CharSequence` 就收下，不是就当没有——**不猜、也不抛**。
+ * 2. 「三个里**有没有躺着值**」这件事纯函数看不到（它只收到几个 `CharSequence?`），而
+ *    「有值、只是本端一段都读不出来」与「用户什么都没分享」是**两件事**：前者必须能说出口，
+ *    否则那三种 extra 一起落空就是一次静默。所以 [present] 由这里如实报进去
+ *    （见 [ShareRules.extract] 的 `textPresent`）。
+ *
+ * ## 它抛不抛异常（核对过 AOSP 源码，`sources/android-36.1/android/os/BaseBundle.java`）
+ * - **类型不符不抛**：`Bundle.getCharSequence` 自己 `catch` 了 `ClassCastException`（`unparcel()` 之后
+ *   直接 `(CharSequence) o`，失败就 `typeWarning` 记一句 log 再回 `null`）⇒ 所以
+ *   `intent.getCharSequenceExtra(...)` 不会因为「值不是 CharSequence」把 App 打崩，它只是**读不到**。
+ *   那一档在这里落成 [present] 为真、[text] 为 `null`：既不崩、也不再静默。
+ * - **畸形 bundle 会抛**：它内部的 `unparcel()` 在别的进程给的 bundle 解析不出来时抛
+ *   `BadParcelableException`（`RuntimeException`）。那一路由 [Intent.rawExtra] 的 `runCatching` 挡住
+ *   ——读不到就当没有，**绝不让异常从 `accept` 冒出去**（那会是 `onCreate` 里的一次崩溃）。
+ */
+internal data class ShareTextExtras(
+    /** `EXTRA_TEXT` 读出来的那一段（读不回来是 `null`；空白**原样留着**，由纯函数判它算不算正文）。 */
+    val text: String?,
+    /** `EXTRA_SUBJECT` 读出来的那一段。 */
+    val subject: String?,
+    /** `EXTRA_TITLE` 读出来的那一段。 */
+    val title: String?,
+    /**
+     * 三个 extra 里**至少一个躺着原始值**——含**读不出类型**的那一种，也含**只是一段空白**的那一种。
+     *
+     * 空白也算，是刻意的：它说的是「对方**给了**这个字段」，与「这个字段里有没有可用的正文」是两件
+     * 事。而 `EXTRA_STREAM` 那边早就是这个口径（原始值只要非 null 就算 `streamPresent`），两个 extra
+     * 用同一条判据，才不会出现「流的空值会说话、文本的空值却闭嘴」这种要靠运气才发现的差别。
+     */
+    val present: Boolean,
+)
+
+/** 见 [ShareTextExtras]：把三个文本 extra 的原始值读成能当正文用的那几段（纯逻辑，可单测）。 */
+internal fun shareTextExtrasOf(text: Any?, subject: Any?, title: Any?): ShareTextExtras = ShareTextExtras(
+    text = (text as? CharSequence)?.toString(),
+    subject = (subject as? CharSequence)?.toString(),
+    title = (title as? CharSequence)?.toString(),
+    // 读不出类型（`42`、别种 `Parcelable`……）也算「里面躺着值」：本端不猜它是什么意思，但不该因此
+    // 把整次分享当成「什么都没发生」。`null`（连值都没有）才是真的没有。
+    present = text != null || subject != null || title != null,
+)

app/src/main/kotlin/top/yeij/cyrene/core/keepalive/KeepAlivePolicy.kt

@@ -0,0 +1,82 @@
+package top.yeij.cyrene.core.keepalive
+
+/**
+ * 「后台保持连接」该不该跑（**纯函数**，UI 与测试共用）。
+ *
+ * 判据单独拎出来的理由与先例一致（`ui.sessions.silentRefreshStep`、`ui.chat.reconnectPull`）：
+ * 起服务那半边要 `Context`、要系统 API，在 JVM 单测里起不来；而「什么时候该跑」只有几个布尔，
+ * 能穷举、能断言。糊进 UI 之后就再也说不清「登出之后到底还会不会留着一条前台服务」——
+ * 那恰恰是这个功能最容易被写错的一半。
+ *
+ * 三个条件缺一不可，每一个都有自己的理由：
+ * - [enabled]：用户的选择，**默认关**。没打开就什么都不该常驻。
+ * - [loggedIn]：实时连接是登录态的产物（`SessionsViewModel` 在登出时关掉那条共享连接）。
+ *   没有连接还留一条前台服务，就只剩「白占一条通知 + 一点电」。
+ * - [notificationsAllowed]：`POST_NOTIFICATIONS` 被拒时前台服务**照样能跑**（系统不再拦它），
+ *   但那就等于**背着用户常驻一个不可见的进程**。本功能卖的就是「我明说我在跑」，
+ *   偷偷跑比不跑更糟——所以权限被拒判「不该跑」，由设置页那行字如实说出来。
+ *
+ * minSdk 33 ⇒ `POST_NOTIFICATIONS` 恒是运行时权限，不存在「低版本不用问」的那一档。
+ */
+internal fun shouldKeepAliveRun(
+    enabled: Boolean,
+    loggedIn: Boolean,
+    notificationsAllowed: Boolean,
+): Boolean = enabled && loggedIn && notificationsAllowed
+
+/** 这一刻该对那条前台服务做什么（[keepAliveAction] 的取值）。 */
+internal enum class KeepAliveAction {
+    /** 该在跑：起服务。重复起是安全的，见 [keepAliveAction]。 */
+    Start,
+
+    /** 不该在跑：停服务。对一条没在跑的服务喊停同样是安全的。 */
+    Stop,
+
+    /** 什么都不做：**此刻还不该有主张**（登录态未定，见 [keepAliveAction]）。 */
+    Leave,
+}
+
+/**
+ * 这一刻该对那条前台服务做什么（**纯函数**，判据本体是 [shouldKeepAliveRun]）。
+ *
+ * ## 为什么不只回一个布尔
+ * 只回「该不该跑」的话，调用方每次都得转成一次 `start` 或 `stop`，而**启动自举那一段**
+ * （`SessionState.Unknown`）两种都不该做：冷启动时进程里根本没有服务，但**热启动**（Activity
+ * 重建、进程还活着）时上一次那条还好端端跑着，此时若按「还没登录 ⇒ 停」收掉它，用户会看到
+ * 「通知消失 → 自举完成 → 通知又回来」这一闪，而中间那段（App 刚被切到后台时）进程正好没有任何
+ * 保护。所以那一档是 [KeepAliveAction.Leave]。
+ *
+ * ## 为什么**不**看一眼「现在跑着没有」
+ * 那样能省掉几回重复调用，但代价是引入一份会漂移的进程内状态：系统完全可能**在进程还活着的前提下**
+ * 把服务收掉而不走 `onDestroy`（比如用户在系统的「正在运行的应用」里按停），于是那份「跑着」的记忆
+ * 停在 true，下一轮判据就会「Leave」——**该起的时候一声不响地没起**，而这正是本功能最不能出的错。
+ * 重复调用则没有任何代价：`startForegroundService` 打到一条已经在跑的服务上只是刷新同一条
+ * （同 id、静默渠道的）通知，`stopService` 打到没在跑的服务上是空操作。
+ *
+ * @param enabled 设置页那个开关（持久化在 `AppPrefs.keepAliveEnabled`）。
+ * @param sessionKnown 登录态**已经定了**（`Unknown` 之外的一切）。
+ * @param loggedIn 现在处于登录态。
+ * @param notificationsAllowed `POST_NOTIFICATIONS` 已授权。
+ */
+internal fun keepAliveAction(
+    enabled: Boolean,
+    sessionKnown: Boolean,
+    loggedIn: Boolean,
+    notificationsAllowed: Boolean,
+): KeepAliveAction = when {
+    // 开关关着：没有第二种解释，收掉。**不等登录态**——用户刚表达过「不要」，用不着等自举。
+    !enabled -> KeepAliveAction.Stop
+
+    // 登录态未定（启动自举的那一段）：这时谁都说不准该不该跑，别动。
+    !sessionKnown -> KeepAliveAction.Leave
+
+    // 明确登出：连接都没了，留着没意义。开关本身不动（`AppSettings` 是 App 级的、不随登出清空，
+    // 下次登录仍按用户当初的选择来）。这里读的是**登录态**而不是「用没用上连接」——本服务不碰连接
+    // （见 [KeepAliveService]），它对连接的了解就只有「现在有没有一个登录着的用户」这一件事。
+    !loggedIn -> KeepAliveAction.Stop
+
+    // 到这儿只剩「开关开着 + 已登录」这一种情形，跑不跑由通知权限说话。
+    shouldKeepAliveRun(enabled, loggedIn, notificationsAllowed) -> KeepAliveAction.Start
+
+    else -> KeepAliveAction.Stop
+}

app/src/main/kotlin/top/yeij/cyrene/core/keepalive/KeepAliveService.kt

@@ -0,0 +1,162 @@
+package top.yeij.cyrene.core.keepalive
+
+import android.Manifest
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.content.pm.ServiceInfo
+import android.os.IBinder
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import androidx.core.app.ServiceCompat
+import androidx.core.content.ContextCompat
+import top.yeij.cyrene.BuildConfig
+import top.yeij.cyrene.app.MainActivity
+
+/** 通知渠道 id。恒定不变：改了它等于换一条渠道，用户对旧渠道做的静音设置会失效。 */
+internal const val KEEP_ALIVE_CHANNEL_ID = "keep_alive"
+
+/**
+ * 渠道重要级。**只许是 LOW / MIN**（[NotificationManager.IMPORTANCE_LOW] = 不响铃、不震动、
+ * 不弹横幅）：这是「保活」不是「提醒」，用户没要求被叫住。
+ *
+ * 注意重要级是**渠道创建时定死的**：应用后改不了（只有用户能改），所以这个值必须是最终值。
+ */
+internal const val KEEP_ALIVE_CHANNEL_IMPORTANCE = NotificationManager.IMPORTANCE_LOW
+
+/** 通知 id。常驻的那一条始终用它，重复起服务只更新不叠加。 */
+internal const val KEEP_ALIVE_NOTIFICATION_ID = 1
+
+private const val LOG_TAG = "KeepAliveService"
+
+/**
+ * `POST_NOTIFICATIONS` 授没授（minSdk 33 ⇒ 它恒是运行时权限）。
+ *
+ * 它既是 [shouldKeepAliveRun] 的入参，也是设置页那行字要说的事，所以两边共用这一处口径。
+ */
+internal fun Context.notificationsAllowed(): Boolean =
+    ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
+        PackageManager.PERMISSION_GRANTED
+
+/**
+ * 「后台保持连接」的前台服务。
+ *
+ * ## 它的职责只有一条：让进程活着
+ * 实时连接是**进程级共享**的那一条（`AppContainer.chatSocket`），所有权在 `SessionsViewModel`
+ * ——登录连、登出关。所以本服务**绝不**去 `connect()` / `close()` 它，也**不订阅任何帧**：
+ * 换了它的死活不等于换了连接的死活，两者各有各的主人。
+ *
+ * 它要挡的是 Android 12+ 对 cached 进程的冻结：进程一旦被冻，那条连接的读写就不再被调度，
+ * 久了连接就断（消息不丢，服务端会落库，回前台靠 history + `after` 补洞恢复，但那就不是
+ * 「保持连接」了）。前台服务把本进程从 cached 那一档里抬出来，这件事就到此为止。
+ *
+ * ## 起停只有一个主人
+ * [keepAliveAction] 判、`CyreneApp` 那个 `LaunchedEffect` 执行（全 App 唯一一处）：
+ * 谁都不许自己在别处 start / stop 它，否则「登出后还留着一条服务」这类不一致没有一处说得清。
+ *
+ * ## 它被系统杀掉怎么办
+ * [onStartCommand] 回 `START_STICKY`：被内存压力回收后系统会重建它。用户主动关开关走的是
+ * [stop]，那是显式停止，粘性不会把它拉回来。
+ */
+class KeepAliveService : Service() {
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        createChannel()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        ServiceCompat.startForeground(
+            this,
+            KEEP_ALIVE_NOTIFICATION_ID,
+            buildNotification(),
+            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+        )
+        return START_STICKY
+    }
+
+    /**
+     * Android 15（API 35）起，`dataSync` 型前台服务在 24 小时内累计跑满 6 小时，系统会回调这里，
+     * 并给几秒钟让应用自己收手——**不接管就会 ANR 崩掉整个 App**（本端 targetSdk 37，躲不掉）。
+     *
+     * 所以这里照办：`stopSelf` 收掉自己，进程回到普通后台状态。刻意**不绕**这条限制
+     * （绕它要么换前台服务类型、要么加心跳，都超出这个功能的边界）。代价如实说：同一台设备
+     * 24 小时内累计只能保活 6 小时；额度用完之后能不能再起、什么时候能再起由系统说了算，
+     * 本端不替它猜（这条限制的真机表现留给验收）。
+     */
+    override fun onTimeout(startId: Int, fgsType: Int) {
+        stopSelf(startId)
+    }
+
+    /**
+     * 常驻通知。文案**刻意克制**：它只是为了让「我在后台跑着」这件事在系统里是可见的
+     * （前台服务必须有一条通知，这是本功能对用户的代价，设置页那行字把它写明了）。
+     *
+     * `setSilent` + `setOngoing` + `setOnlyAlertOnce` + 渠道 LOW：不响、不震、不亮屏、划不掉。
+     * `setOnlyAlertOnce` 是给**重复起服务**留的（判据不看「现在跑着没有」，见 [keepAliveAction]）：
+     * 第二次 `startForegroundService` 打到同一条通知上时，用户那边必须**一点动静都没有**。
+     */
+    private fun buildNotification(): Notification {
+        // 点一下回到 App：一条点不动的常驻通知会让人以为卡住了。
+        val open = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, MainActivity::class.java),
+            PendingIntent.FLAG_IMMUTABLE,
+        )
+        return NotificationCompat.Builder(this, KEEP_ALIVE_CHANNEL_ID)
+            .setSmallIcon(android.R.drawable.stat_notify_sync)
+            .setContentTitle("保持与昔涟的连接")
+            .setContentText("Cyrene 正在后台维持与昔涟的连接")
+            .setContentIntent(open)
+            .setOngoing(true)
+            .setSilent(true)
+            .setOnlyAlertOnce(true)
+            .setShowWhen(false)
+            .setCategory(NotificationCompat.CATEGORY_SERVICE)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .build()
+    }
+
+    private fun createChannel() {
+        val channel = NotificationChannel(
+            KEEP_ALIVE_CHANNEL_ID,
+            "后台保持连接",
+            KEEP_ALIVE_CHANNEL_IMPORTANCE,
+        ).apply {
+            description = "开启「后台保持连接」期间常驻的通知：让系统不要冻结 Cyrene 的进程"
+            setShowBadge(false)
+            setSound(null, null)
+            enableVibration(false)
+        }
+        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
+    }
+
+    companion object {
+
+        fun start(context: Context) {
+            // Android 12+ 对「从后台起前台服务」是受限的，系统直接抛异常；这里吞掉它，理由有两条：
+            // ① 这个失败用户既看不懂也无从处置，而把异常放出去就是一次崩溃——崩溃比「这次没起成」
+            //    严重得多；
+            // ② 状态是自愈的：下一个判据触发点（开关 / 登录态变化、下次启动）会再试一次，
+            //    而这次没起成除了「进程暂时少一层保护」之外不留任何后遗症。
+            runCatching { ContextCompat.startForegroundService(context, intent(context)) }
+                .onFailure {
+                    if (BuildConfig.DEBUG) Log.d(LOG_TAG, "系统拒绝了这次前台服务启动", it)
+                }
+        }
+
+        fun stop(context: Context) {
+            context.stopService(intent(context))
+        }
+
+        private fun intent(context: Context): Intent = Intent(context, KeepAliveService::class.java)
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/core/notify/AppPresence.kt

@@ -0,0 +1,92 @@
+package top.yeij.cyrene.core.notify
+
+import java.util.Collections
+import java.util.concurrent.ConcurrentHashMap
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * 进程级的两个「我此刻在哪儿」的事实（W53N）：**App 在不在前台**、**聊天页正显示哪个会话**。
+ *
+ * ## 为什么是这一层，而不是 ProcessLifecycleOwner
+ * 本仓没有 `lifecycle-process` 依赖，而为一个「要不要弹通知」的判断新增依赖不值当（主人明令不加）。
+ * 既有的 `MainActivity` 生命周期已经足够说清第一件事——本应用只有**一个** Activity
+ * （`singleTop`），它的 `onStart` / `onStop` 就是「App 有没有在被看」。第二件事由 `ChatScreen`
+ * 的组合报告（组合在 = 那一页在屏幕上，见 [onChatSurface]）。两条都在手写 DI 容器
+ * （`app.AppContainer`）那一层汇合——与那条共享连接、`goneSessions` 那几件进程级事实同一层。
+ *
+ * ## 为什么前台用「活着的 Activity 集合」而不是一个布尔
+ * 配置变更（旋转 / 系统深浅色切换）时，**新实例的 `onStart` 会先于旧实例的 `onStop`**：
+ * 一个布尔量在那里必然被旧实例的 `onStop` 记成「后台」，于是用户正看着聊天页，她一句话却弹出
+ * 通知来。按实例登记就没有这个方向性问题——新实例先加进来、旧实例后移出去，集合始终非空。
+ * 集合按 `ConcurrentHashMap` 语义（`Activity` 不重写 `equals` ⇒ 就是**同一实例**），
+ * 且读写可能不在同一线程上（她的话那条通路是在**进程级订阅自己的调度器**上读它的，见
+ * `ProactiveFrameIntake`），所以用并发容器而不是普通 `MutableSet`。
+ *
+ * ## 它**不是**「App 有没有活着」
+ * 后台保活（前台服务）让进程活着、连接继续收帧，而本类在这里恒报「不在前台」——那正是通知要
+ * 出现的那一档。两者是两件事，别把它们揉在一起。
+ */
+class AppPresence {
+
+    private val startedActivities: MutableSet<Any> =
+        Collections.newSetFromMap(ConcurrentHashMap<Any, Boolean>())
+
+    /**
+     * 聊天页此刻显示着的会话 id；`null` = 聊天页不在屏幕上（设置页 / 管理页 / 未登录 / 已销毁）。
+     *
+     * 由 [onChatSurface] 写、通知判据读。**刻意不带「前台」的含义**：App 退到后台时这段组合在
+     * Android 上并不会被销毁，这个值会原样留着——前台那一半由 [appInForeground] 单独表达，
+     * 两个事实的合取才是「这条消息此刻会不会正好被用户看到」（见 [shouldNotifyProactive]）。
+     */
+    @Volatile
+    var chatSurfaceSessionId: String? = null
+        private set
+
+    /** App 是否正在被看（有任何一个 Activity 处在 started 之后、stopped 之前）。 */
+    val appInForeground: Boolean
+        get() = startedActivities.isNotEmpty()
+
+    private val _appInForeground = MutableStateFlow(false)
+
+    /**
+     * [appInForeground] 的**可订阅**形态（W53S 登记的那一格要它）。
+     *
+     * 为什么需要第二条出口：`CyreneApp` 那个「起 / 停前台服务」的 `LaunchedEffect` 的 key 里没有
+     * 通知权限，于是**用户在系统设置里授权后回到 App** 时它不会重跑 —— UI 已经显示「已开」，
+     * 服务却没起。权限本身必须**现读**（不该缓存成状态），能当 key 的是「刚好会在这件事发生时变化」
+     * 的信号：**回到前台**（从系统设置返回必经 `onStart`）。所以这里把「在不在前台」补成一条流。
+     * 判据本身仍然只读 [appInForeground] 那个布尔——两条出口算的是**同一份事实**（同一个集合）。
+     */
+    val appInForegroundFlow: StateFlow<Boolean> = _appInForeground.asStateFlow()
+
+    /** 一个 Activity 进入「可见」这一档（`onStart`）。 */
+    fun onActivityStarted(owner: Any) {
+        startedActivities.add(owner)
+        _appInForeground.value = appInForeground
+    }
+
+    /**
+     * 一个 Activity 离开「可见」这一档（`onStop`）。
+     *
+     * 只移除**报上来的那一个实例**：照抄成「一停就整集合清空」会把正在起的新实例一起算掉
+     * （那条路径见类注释里的配置变更）。
+     */
+    fun onActivityStopped(owner: Any) {
+        startedActivities.remove(owner)
+        _appInForeground.value = appInForeground
+    }
+
+    /** 聊天页刚显示（或刚换成）[sessionId]；`null` = 它离开了屏幕。 */
+    fun onChatSurface(sessionId: String?) {
+        chatSurfaceSessionId = sessionId
+    }
+
+    /**
+     * 聊天页此刻显示的是不是 [sessionId] 这个会话（等值比较，不是前缀：`web` ≠ `web:xxx`）。
+     * `sessionId` 为空白时恒假——「没显示任何会话」不等于「显示了一个空 id 的会话」。
+     */
+    fun isShowingChatSurface(sessionId: String): Boolean =
+        sessionId.isNotBlank() && chatSurfaceSessionId == sessionId
+}

app/src/main/kotlin/top/yeij/cyrene/core/notify/ProactiveNotification.kt

@@ -0,0 +1,277 @@
+package top.yeij.cyrene.core.notify
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import top.yeij.cyrene.app.MainActivity
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+
+/**
+ * 「她主动说的话」那条通知的渠道 id —— **弹横幅**的那一条（[PROACTIVE_IMPORTANCE]）。
+ *
+ * ⚠️ **这里是 `proactive_v2`，不是最初的 `proactive`**：渠道的**重要级一旦创建就改不了**
+ * （Android 的设计 —— 只有用户能改，App 改不动）。2026-10-07 主人明确要求「要横幅」，而把重要级
+ * 从 DEFAULT 提到 HIGH **对已经建过旧渠道的设备不生效** ⇒ 只能换一个新 id，让系统按新重要级
+ * 重新建一条。旧渠道由 [ensureProactiveChannel] 顺手删掉（它的重要级改不动，留着只会让系统设置里
+ * 多一条永远不再出现的条目）。
+ *
+ * **刻意与保活那条分成两个渠道**：保活那条是 LOW（不响不震、用户没要求被叫住），这一条是
+ * [PROACTIVE_IMPORTANCE]。两者混在一条渠道里，就只能在「保活开始响铃」与「她的话不响铃」之间
+ * 二选一——那正是「一个渠道只能是其中一件事」的由来。
+ *
+ * 与 [QUIET_PROACTIVE_CHANNEL_ID] **也是两条**，理由与上面那条一模一样：横幅由渠道重要级决定，
+ * 而重要级建完就改不了 ⇒ 设置页那个「免打扰」开关**不可能**靠运行时改设置实现，只能按开关选一条
+ * 渠道发（见 [proactiveChannelId]）。
+ */
+internal const val PROACTIVE_CHANNEL_ID = "proactive_v2"
+
+/**
+ * 「她主动说的话」在**免打扰**下走的那条渠道 id：重要级是 [QUIET_PROACTIVE_IMPORTANCE]
+ * （有提示音、通知栏有条目、**不弹横幅**）。
+ *
+ * 为「免打扰」单独建**第二条**渠道，是因为**重要级建完就改不了**（理由见 [PROACTIVE_CHANNEL_ID]）
+ * ——想「只关横幅」就只有换渠道这一条路。
+ *
+ * ⚠️ 刻意**不用** `setSilent(true)`：那是**完全静音**（连提示音都没），而用户要的语义是
+ * 「只在通知栏提示，别在屏幕顶部弹横幅」——两者之间差着一个提示音，不是同一件事。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_ID = "proactive_quiet"
+
+/**
+ * 上一个渠道 id（[PROACTIVE_CHANNEL_ID] 的前身）。**只在建渠道时用于删除**：它的重要级是
+ * DEFAULT 且改不动，留着毫无用处。
+ */
+internal const val LEGACY_PROACTIVE_CHANNEL_ID = "proactive"
+
+/**
+ * 弹横幅那条渠道的重要级：**`HIGH`**（屏幕顶部弹横幅 + 提示音）。
+ *
+ * 这一条**是**来提醒人的 —— 她主动找我说话的那一刻，我显然不在跟她聊天（App 不在前台），
+ * 正是最需要在屏幕顶部弹一下的场景。DEFAULT 只会响一声、安静躺在通知栏里，很容易错过
+ * （主人 2026-10-07 的原话：「我在其他 APP 时没看到横幅」）。
+ *
+ * 想安静的用户可以在系统设置里单独把这条渠道调低、或关掉它的横幅 —— 那是用户的权利，
+ * 不是我们对他的默认；应用内的那条捷径是设置页的「免打扰」，它把通知改发到
+ * [QUIET_PROACTIVE_CHANNEL_ID]。
+ *
+ * ⚠️ 与保活那条同理：重要级在**建渠道**时定死，应用之后改不了（只有用户能改）⇒ **改这个常量
+ * 对已建过渠道的设备不生效**，必须同时换 [PROACTIVE_CHANNEL_ID]。`ProactiveNotificationShapeTest`
+ * 把这两个值钉住。
+ */
+internal const val PROACTIVE_IMPORTANCE = NotificationManager.IMPORTANCE_HIGH
+
+/**
+ * 免打扰那条渠道的重要级：**`DEFAULT`**（提示音 + 通知栏条目，**没有横幅**）。
+ *
+ * `HIGH`(4) 才是屏幕顶部弹横幅的门槛，所以 DEFAULT 正是「她的话照旧说、只是不盖住我正在做的事」
+ * 那一档。
+ *
+ * ⚠️ 与上面那条同理：**改这个常量必须同时换 [QUIET_PROACTIVE_CHANNEL_ID]**，否则对已经建过它的
+ * 设备一个字节都不生效。这个方向（往安静改）出错时用户的感受只是「开关按了没反应」——不会有任何
+ * 报错，所以这条纪律只能靠常量与测试钉住。
+ */
+internal const val QUIET_PROACTIVE_IMPORTANCE = NotificationManager.IMPORTANCE_DEFAULT
+
+/** 通知标题：**是谁在说话**。正文是她的原话（见 [ProactiveNotifier]）。 */
+internal const val PROACTIVE_NOTIFICATION_TITLE = "昔涟"
+
+/**
+ * 渠道名（系统设置的渠道列表里那一行）。与通知标题分开是为了让它说清**这条渠道是什么**，
+ * 而不是重复一遍说话人的名字。
+ */
+internal const val PROACTIVE_CHANNEL_NAME = "她主动说的话"
+
+/**
+ * 免打扰那条渠道的渠道名。**必须一眼看出与 [PROACTIVE_CHANNEL_NAME] 的区别**：系统设置的渠道列表
+ * 里这两行会并排出现，用户就是靠这一行判断「哪条会弹横幅」的——同名的话两条渠道就白分了
+ * （他只能点进去、一条条试着看）。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_NAME = "她主动说的话（免打扰：只在通知栏）"
+
+/** 弹横幅那条渠道的描述（点进渠道详情才看得到）。 */
+internal const val PROACTIVE_CHANNEL_DESCRIPTION = "她主动找你说话时的通知"
+
+/**
+ * 免打扰那条渠道的描述。把「不弹横幅」与「还有提示音」都说清：用户点进来想知道的是**它到底静到
+ * 什么程度**，而「免打扰」四个字很容易被读成「完全没有声音」——那是另一件事（也正是用户会去系统
+ * 设置里翻、翻完还是不确定的那一件事）。
+ */
+internal const val QUIET_PROACTIVE_CHANNEL_DESCRIPTION =
+    "她主动找你说话时的通知（只在通知栏提示、不弹横幅；仍有提示音）"
+
+/**
+ * 一条 proactive 渠道的完整定义：**id / 渠道名 / 重要级 / 描述一次给全**。
+ *
+ * 为什么要打包成一个值：这四样必须**成对地**跟着「免打扰」这个布尔走（换了 id 却没换重要级 =
+ * 开关没生效；换了重要级却没换 id = 对老设备没生效）。散成四个各自 `if (quiet)` 就是四份口径，
+ * 而它们分叉时的症状全都是「用户按了开关，什么都没变」——最难被发现的那种坏法。
+ */
+internal data class ProactiveChannelSpec(
+    val id: String,
+    val name: String,
+    val importance: Int,
+    val description: String,
+)
+
+/**
+ * 「免打扰」→ 这一次该用哪条渠道 —— **纯函数**（不含任何 Android 调用，两档可穷举）。
+ *
+ * @param quiet 设置页那个「免打扰」开关**当下的值**（`false` = 都弹，也是默认）。
+ */
+internal fun proactiveChannelSpec(quiet: Boolean): ProactiveChannelSpec = if (quiet) {
+    ProactiveChannelSpec(
+        id = QUIET_PROACTIVE_CHANNEL_ID,
+        name = QUIET_PROACTIVE_CHANNEL_NAME,
+        importance = QUIET_PROACTIVE_IMPORTANCE,
+        description = QUIET_PROACTIVE_CHANNEL_DESCRIPTION,
+    )
+} else {
+    ProactiveChannelSpec(
+        id = PROACTIVE_CHANNEL_ID,
+        name = PROACTIVE_CHANNEL_NAME,
+        importance = PROACTIVE_IMPORTANCE,
+        description = PROACTIVE_CHANNEL_DESCRIPTION,
+    )
+}
+
+/**
+ * 发通知那一刻用哪条渠道 id —— **纯函数**，就是「同一个开关、两条渠道」这件事的全部落地形状。
+ *
+ * 单独再露一层是因为调用方要的正好只是这个 id（`NotificationCompat.Builder(context, ???)`），
+ * 而测试要问的也只是这一个问题：「开关两档各发去哪条」。
+ */
+internal fun proactiveChannelId(quiet: Boolean): String = proactiveChannelSpec(quiet).id
+
+/**
+ * 点通知进来时那个「切到主会话」的 Intent extra。
+ *
+ * 它是本端**手写布尔路由**里的一次「带意图的冷启动 / 热启动」：`MainActivity` 读它 →
+ * `ProactiveTapIntake` 记一笔 → `ChatHomeScreen` 落成一次 `select(主会话)`。刻意**不引导航库**
+ * （本项目没有导航库，路由就是 `ChatHomeScreen` 里那几个布尔量）。
+ */
+internal const val EXTRA_PROACTIVE_OPEN_MAIN_SESSION = "top.yeij.cyrene.extra.PROACTIVE_OPEN_MAIN_SESSION"
+
+/**
+ * 弹一条「她主动说的话」的通知。
+ *
+ * 只做四件事：按 [quiet] 选渠道、建渠道（惰性，第一次真要用时才建）、拼通知、`notify`。**判据、
+ * 去重与 id 的派生都不在这里**（那是 [ProactiveNotifier] 与 [proactiveNotificationId] 的事）
+ * ——本函数被调用就意味着「这一次确实该弹，且这条消息的号已经定好了」，它只负责把号用在通知上。
+ *
+ * ## 为什么 id 是入参而不是这里恒定一个
+ * 同 id 的 `notify` 是**替换**：恒用一个号就等于「后来的覆盖先来的」——她连说几句，用户只看到
+ * 最后一句。入参那个号由 [proactiveNotificationId] 按消息派生（输入就是去重键），于是同一句
+ * 无论到几次都落在同一条通知上，而不同的句子各占一条。
+ *
+ * ## 免打扰只换渠道，别的一个字节都不动
+ * [quiet] 为真时整条通知除了「发去哪条渠道 / 7.x 的优先级」以外**逐字节不变**：同一个标题、同一
+ * 段正文、同一个通知号、同一次点击行为。用户要的是「别在我正做事的时候盖住屏幕」，不是「别让我
+ * 知道」——所以什么都不该少，只是她的话安静地躺在通知栏里。
+ *
+ * ## 没授通知权限时什么都不做
+ * `minSdk 33` ⇒ `POST_NOTIFICATIONS` 恒是运行时权限，而系统在未授权时**静默丢弃**通知。与其发一条
+ * 必然无声无息的东西，不如在这里就收手（判据复用保活那处 [notificationsAllowed]，全 App 只有
+ * 一份「授没授」的口径）。用户之后在设置页授权、或直接开通了保活那个开关，下一句话就能弹出来
+ * ——本函数每次都**现读**权限，不缓存。
+ *
+ * ## 小图标用的是平台资源
+ * 工程里没有为通知准备单色小图标（`@mipmap/ic_launcher` 是彩色的，拿它当通知小图标在通知栏上
+ * 会显示成一块白斑）。所以用平台自带的 `stat_notify_chat`——与保活那条用 `stat_notify_sync` 是
+ * 同一个做法。要换成本应用的图标时，只需换下面这一行。
+ *
+ * @param notificationId 这条消息的通知 id，同时也是它点击用的 request code（两者必须一起动：
+ *   只换 id 不换 request code，点后到的那条通知会串到先到那条的 `PendingIntent` 上）。
+ * @param quiet 「免打扰」开关**当下的值**：`true` ⇒ 发到 [QUIET_PROACTIVE_CHANNEL_ID]（有提示音、
+ *   不弹横幅）；`false` ⇒ 发到 [PROACTIVE_CHANNEL_ID]（弹横幅）。**刻意不给默认值**：调用方忘写
+ *   这一位时症状是「开关按了没反应」，那种坏法没有任何报错——让编译器拦住它。
+ *   值由调用方每次**现读**（见 `AppContainer` 里 `post` 那个 lambda），所以开关一改不必重启 App，
+ *   下一条通知就走新渠道。
+ */
+internal fun postProactiveNotification(
+    context: Context,
+    text: String,
+    notificationId: Int,
+    quiet: Boolean,
+) {
+    if (!context.notificationsAllowed()) return
+
+    // 选渠道与建渠道用的是**同一个** spec：两处各自 `if (quiet)` 就会有一条渠道永远建不出来，
+    // 而它的症状是「开了免打扰之后她再也不通知我了」（Android 8+ 对不存在的渠道是静默丢弃）。
+    val channel = proactiveChannelSpec(quiet)
+    ensureProactiveChannel(context, channel)
+
+    // request code 随消息走（`proactiveNotificationId` 的下界远高于保活那条用的 `0`，所以不会
+    // 撞上它）：两个 Intent 都是「启动 MainActivity」、没有 action / data / categories ⇒
+    // `Intent.filterEquals` 判它们**相等**，而 `PendingIntent` 的相等判据里**不含 extras**。
+    // 同 request code 时系统直接复用**先建的那一个**，后建这枚的 extra 会被悄悄丢掉。
+    val openApp = PendingIntent.getActivity(
+        context,
+        notificationId,
+        Intent(context, MainActivity::class.java).putExtra(EXTRA_PROACTIVE_OPEN_MAIN_SESSION, true),
+        PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+    )
+
+    val notification = NotificationCompat.Builder(context, channel.id)
+        .setSmallIcon(android.R.drawable.stat_notify_chat)
+        .setContentTitle(PROACTIVE_NOTIFICATION_TITLE)
+        .setContentText(text)
+        // 展开态显示完整正文（`setContentText` 那一行放不下 120 字，而截断只解决「过长」，
+        // 解决不了「一行的宽度」）。
+        .setStyle(NotificationCompat.BigTextStyle().bigText(text))
+        .setContentIntent(openApp)
+        // 点掉即消失：这条通知说的是一次刚发生的事，用户点开就等于看到了。
+        .setAutoCancel(true)
+        .setCategory(NotificationCompat.CATEGORY_MESSAGE)
+        // 横幅：Android 8+ 由**渠道重要级**决定（上面那条 spec 选出来的那条渠道），这一句管的是
+        // 7.x 及更早（那边还没有渠道，优先级就是全部）。两处必须同向——免打扰那一档在这里也得
+        // 降回 DEFAULT，否则老设备上「开着免打扰却照样弹横幅」。
+        .setPriority(if (quiet) NotificationCompat.PRIORITY_DEFAULT else NotificationCompat.PRIORITY_HIGH)
+        .build()
+
+    // 一事一条：号随消息走。撞号会发生，代价与改前一样是「后来的把先来的替换掉」，
+    // 理由与概率写在 `proactiveNotificationId` 的 KDoc 里。
+    NotificationManagerCompat.from(context).notify(notificationId, notification)
+}
+
+/**
+ * 建（或更新）**这一次要用的那一条**渠道。惰性创建：一个从没收到过她主动消息的用户，系统设置的
+ * 渠道列表里不会平白多出一条「她的话」。
+ *
+ * ## 为什么只建「这一次要用的那一条」，而不是两条都建
+ * 「免打扰」决定的是**下一条**通知发去哪条渠道，而渠道只需要在 `notify` 之前存在。两条都建的话，
+ * 一个从没开过免打扰、将来也不打算开的用户，系统设置里会平白多出一条他从没见过的「她主动说的话
+ * （免打扰：只在通知栏）」——那是我们替他做的选择，也算脏数据。所以这里只 ensure 被选中的那一条。
+ *
+ * ⚠️ 但**必须在 `notify` 之前** ensure：Android 8+ 上目标渠道不存在时，那条通知是被系统**静默
+ * 丢弃**的（不报错、不打日志、只是什么都没有）。这正是「只建一条」这个省法的代价 —— 它靠
+ * [postProactiveNotification] 里「选渠道」与「建渠道」用的是**同一个** [ProactiveChannelSpec]
+ * 兜住（两处各自 `if (quiet)` 就会有一条渠道永远建不出来，而症状是「开了免打扰之后她再也不
+ * 通知我了」——用户只会以为是她不说话了）。
+ *
+ * ## 另一条渠道**不删**
+ * 它是「这一次没选」，不是「以后不再用」：用户来回切开关时，他在系统设置里对另一条调过的横幅 /
+ * 静音设置得留着（删掉 = 把他的选择一起删掉，还得重新建一条空白的）。唯一会删的是
+ * [LEGACY_PROACTIVE_CHANNEL_ID] —— 那条 id 本端**再也不会发**，而它的重要级又改不动，留着只会
+ * 在系统设置里多一条永远不再出现的条目（用户可能在那儿调半天、却发现怎么调都没变化）。
+ *
+ * 重复调用是幂等的（同 id ⇒ 更新那条渠道，不会建出第二条）。**注意重要级只在第一次创建时生效**
+ * ——它已经在 [PROACTIVE_IMPORTANCE] / [QUIET_PROACTIVE_IMPORTANCE] 上定死（渠道名与描述此后仍
+ * 可以改，重要级改不了）。
+ *
+ * @param spec 这一次要用的那条渠道（由 [proactiveChannelSpec] 按「免打扰」开关选出来）。
+ */
+private fun ensureProactiveChannel(context: Context, spec: ProactiveChannelSpec) {
+    val channel = NotificationChannel(spec.id, spec.name, spec.importance).apply {
+        description = spec.description
+        setShowBadge(true)
+    }
+    val manager = context.getSystemService(NotificationManager::class.java)
+    manager.createNotificationChannel(channel)
+    // 旧的 DEFAULT 渠道删掉：重要级改不动，留着只会在系统设置里多一条永远不再出现的条目
+    // （用户可能在那儿调半天、却发现怎么调都没变化）。删一条不存在的渠道是幂等的。
+    manager.deleteNotificationChannel(LEGACY_PROACTIVE_CHANNEL_ID)
+}

app/src/main/kotlin/top/yeij/cyrene/core/notify/ProactiveNotifier.kt

@@ -0,0 +1,107 @@
+package top.yeij.cyrene.core.notify
+
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
+
+/**
+ * 一帧「她主动说的话」进到本类之后**发生了什么**（纯判定的结果，可单测）。
+ *
+ * 分成五档而不是一个布尔，是为了让「为什么这次没弹」在日志与测试里都能一眼看穿：这五条各自
+ * 对应一个完全不同的理由，而在通知这一档上，「没弹」与「弹了」一样需要说得清。
+ */
+enum class ProactiveNotifyOutcome {
+
+    /** 弹了。 */
+    Posted,
+
+    /** 用户正看着主会话（前台 ∧ 聊天页显示主会话）：她的话就出现在他眼前，不打扰。 */
+    SeenOnScreen,
+
+    /** 同一条已经到达过（实时帧与落库帧两条路，或服务端重推）。 */
+    Duplicate,
+
+    /** 帧里没有可显示的正文（坏帧 / 落库失败的空帧）。 */
+    NothingToSay,
+
+    /**
+     * 不属主会话。她主动说的话落的是主会话（服务端 `history.MainSessionID`）；帧上若明说了别的
+     * 会话，那不是这件事，绝不弹（宁可漏，也不要把别处的消息说成是她在找我说话）。
+     */
+    OtherSession,
+}
+
+/**
+ * 「她主动说的话」的通路（W53N）：**判据 + 去重 + 落地**收在一处，Android 那一步由 [post] 注入。
+ *
+ * ## 谁把帧喂进来（W57 起）
+ * 后端两条路（实时帧 `proactive_message`、落库帧 `message_persisted{proactive:true}`）在客户端
+ * 汇于一处：**进程级**的帧消费点 `app.ProactiveFrameIntake` 订着那条共享连接，把这两种帧折成下面
+ * [onProactiveFrame] 的四个入参喂过来（同一条消息无论走哪条路、到几次，都只经过这一处）。
+ * 本类因此只是一个**纯逻辑 + 一个回调**，不订阅任何东西、不碰连接、不认识 Android——测试里传个
+ * 假的 [post] 就能把它整条驱动起来。
+ *
+ * ## 它绝不碰连接
+ * 连接的所有权在登录态（`SessionsViewModel` 那处 `LoggedIn → connect()`）。本类只在帧**已经到达
+ * 之后**做判断——帧没到就没有任何事发生，它不会去重连、不会去补拉、不会去订阅。
+ *
+ * ## 一次帧到这里的顺序（每一步的顺序都有理由）
+ * 1. [ProactiveNotifyOutcome.OtherSession]：不是主会话，连账本都不必碰；
+ * 2. [ProactiveNotifyOutcome.NothingToSay]：先看有没有可显示的字。**这一步不记账**——同一句话的
+ *    另一条路上正文可能是齐的（实时帧空、落库帧有字的形状漂移），记了就会把那条能弹的挡成重复；
+ * 3. [ProactiveNotifyOutcome.Duplicate]：记账与查重。**先记账再判「会不会被看到」**，因为「用户
+ *    正看着」那一次也算这条已经到达：他当场看过了，另一条路再补一帧时不该为一句**看过的话**弹
+ *    通知（他这会儿可能已经切走了）；
+ * 4. [ProactiveNotifyOutcome.SeenOnScreen] / [ProactiveNotifyOutcome.Posted]：最后才问时机。
+ *
+ * @param presence 「App 在不在前台 / 聊天页显示着谁」，由 `MainActivity` 与 `ChatScreen` 报告。
+ * @param post 真正的落地动作（Android 那边是建渠道 + `notify`）。第二个入参是**这条消息派生出来的
+ *   通知 id**（见 [proactiveNotificationId]）：落地侧必须用它，别再恒用一个号——恒用一个号时
+ *   `notify` 是替换，她连说几句就只剩最后一句。测试传一个记录用的假实现即可。
+ * @param mainSessionId 主会话 id。默认取 [SessionSummaryDto.MAIN_SESSION_ID]，测试可换。
+ */
+class ProactiveNotifier(
+    private val presence: AppPresence,
+    private val post: (text: String, notificationId: Int) -> Unit,
+    private val mainSessionId: String = SessionSummaryDto.MAIN_SESSION_ID,
+    private val recent: RecentProactiveNotices = RecentProactiveNotices(),
+) {
+
+    /**
+     * 一帧到了（实时帧与落库帧**共用**这一处，所以同一条消息无论到几次都只弹一次）。
+     *
+     * @param sessionId 帧上的会话归属；`null` / 空白 = 帧壳没给（实时帧就是这样：服务端构造它时
+     *   不设 `sessionId`）⇒ 按「无法判定」放行，由 [mainSessionId] 那条事实兜住归属。
+     * @param id 落库行 id（实时帧的 `data.id` / 落库帧的 `message.id`）——两条路的公共键。
+     * @param messageId IM 侧消息号（实时帧才有；落库失败那一档它是最后的服务端键）。
+     * @param timestamp 服务端给的时间**字面量**（只作去重兜底，排序与本类无关）。
+     * @param content 她的原话（原始文本，标记由 [proactiveNotificationText] 剥）。
+     */
+    fun onProactiveFrame(
+        sessionId: String?,
+        id: String?,
+        messageId: String?,
+        timestamp: String?,
+        content: String,
+    ): ProactiveNotifyOutcome {
+        if (!sessionId.isNullOrBlank() && sessionId != mainSessionId) {
+            return ProactiveNotifyOutcome.OtherSession
+        }
+
+        val text = proactiveNotificationText(content) ?: return ProactiveNotifyOutcome.NothingToSay
+
+        val key = proactiveNotifyKey(id, messageId, timestamp, text)
+        val firstArrival = recent.markIfNew(key)
+        if (!firstArrival) return ProactiveNotifyOutcome.Duplicate
+
+        // 判据只回答「弹不弹」，「用户会不会正好看到」是它的反面——别在接线层另写一遍这个取反
+        // （两份口径早晚会分叉，而这里分叉的代价是「她的话在用户眼前弹出来」）。
+        val seenOnScreen = !shouldNotifyProactive(
+            appInForeground = presence.appInForeground,
+            viewingTargetSession = presence.isShowingChatSurface(mainSessionId),
+        )
+        if (seenOnScreen) return ProactiveNotifyOutcome.SeenOnScreen
+
+        // id 与去重键同源，正是为了让「同一条 ⇒ 同一个号」与「同一条 ⇒ 只弹一次」永远不会分叉。
+        post(text, proactiveNotificationId(key))
+        return ProactiveNotifyOutcome.Posted
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/core/notify/ProactiveNotify.kt

@@ -0,0 +1,192 @@
+package top.yeij.cyrene.core.notify
+
+import kotlin.math.absoluteValue
+import top.yeij.cyrene.domain.parse.parse
+
+/**
+ * 「她主动说的话」该不该弹一条系统通知 —— 纯函数（W53N）。
+ *
+ * 主人对时机的原话是「**App 不在前台，或者不在聊天页**」。写成一个判据（而不是直接写成
+ * `!viewing`）是为了让两个事实**各自**可见、可穷举、可测试：它们是两个方向完全不同的东西，
+ * 合成一行以后「为什么这一档不弹」就再也说不清了。
+ *
+ * 语义（**判断标准只有一条：这条消息此刻会不会正好被用户看到**）：
+ *
+ * | [appInForeground] | [viewingTargetSession] | 结论 | 场景 |
+ * |---|---|---|---|
+ * | true | true | **不弹** | 用户正看着主会话，她的话就出现在他眼前 |
+ * | true | false | 弹 | 用户在看设置页 / 别的会话（甚至另一个会话的聊天页） |
+ * | false | false | 弹 | App 退到后台 / 熄屏（进程被保活着，帧还在到） |
+ * | false | true | 弹 | **Android 上真实存在**：Activity `onStop` 之后组合并没有销毁，
+ * 聊天页仍「显示」着主会话。此时的用户根本看不见它，所以照弹 |
+ *
+ * 最后一行是「两个事实不许互相顶替」的那一半：只看聊天页显示着谁，就会在 App 退到后台以后
+ * 静默漏掉**所有**她的话。
+ *
+ * @param appInForeground 此刻有没有 Activity 在「可见」这一档（见 [AppPresence.appInForeground]）。
+ * @param viewingTargetSession 聊天页此刻显示的是不是**她说这句话的那个会话**。注意它**不含**
+ *   「前台」的含义（见 [AppPresence.chatSurfaceSessionId]）——它只说「屏幕上摆着哪一页」。
+ */
+fun shouldNotifyProactive(
+    appInForeground: Boolean,
+    viewingTargetSession: Boolean,
+): Boolean = !(appInForeground && viewingTargetSession)
+
+/**
+ * 通知正文的长度上限（字符）。超出的部分截断加 `…`。
+ *
+ * 取值理由：通知在折叠态只显示一行（约 20~30 字），展开态（`BigTextStyle`）能显示四五行。
+ * 这个上限是**展开态**的预算——正文不砍到一行那么短（那样会看不出她在说什么），但也不许整屏
+ * 铺开。真正的长文在聊天页里一字不少。
+ */
+const val PROACTIVE_NOTIFICATION_MAX_CHARS = 120
+
+/**
+ * 去重账本的容量。同一条她的话最多两条路会到（实时帧 + 落库帧），容量只需要覆盖「最近一小段」；
+ * 取 64 是给「她连说几句 + 两条路交错」留的余量，同时**有界**——进程活一整天也不会涨。
+ */
+const val RECENT_PROACTIVE_CAPACITY = 64
+
+/**
+ * 最近**已经到达过**的 proactive 消息的键（进程级、容量有限、先进先出淘汰）。
+ *
+ * ## 为什么必须有它
+ * 同一条消息会走**两条**路到本端：实时帧 `proactive_message`（带**落库行** `id`）与落库帧
+ * `message_persisted{proactive:true}`（带 `message.id`，同一个值）。不去重就是同一条消息弹两次。
+ *
+ * ## 为什么记的是「到达过」而不是「弹过」
+ * 因为「用户正看着主会话」那一次也要记：他当场看过这条了，随后另一条路再补一帧时**不该**为一句
+ * 已经看过的话弹通知（他这会儿可能已经切到别的会话了）。两个方向都要求同一件事：**先到的那一次
+ * 说了算**。判据见 [ProactiveNotifier.onProactiveFrame]。
+ *
+ * 有界：超过容量按插入顺序丢掉最老的（`LinkedHashSet` 的迭代顺序就是插入顺序）。
+ * 只活在本进程里，不持久化——重启之后最多重复弹一条「刚刚到达过、还没被看过」的话，那比
+ * 为一个通知判据在磁盘上留一份状态诚实得多。
+ */
+class RecentProactiveNotices(private val capacity: Int = RECENT_PROACTIVE_CAPACITY) {
+
+    private val seen = LinkedHashSet<String>()
+
+    /**
+     * 记下这个键，并回「它是不是**第一次**来」。返回 false = 这条已经到达过，调用方必须闭嘴。
+     *
+     * 空键恒回 false（「没有键」不是一个可去重的身份，绝不把它当成一条新消息的凭据）。
+     */
+    @Synchronized
+    fun markIfNew(key: String): Boolean {
+        if (key.isBlank()) return false
+        if (!seen.add(key)) return false
+        while (seen.size > capacity.coerceAtLeast(1)) {
+            val oldest = seen.firstOrNull() ?: break
+            seen.remove(oldest)
+        }
+        return true
+    }
+
+    /** 账本里现有多少个键（测试与诊断用）。 */
+    @Synchronized
+    fun size(): Int = seen.size
+}
+
+/**
+ * 一条 proactive 消息的去重键（纯函数）。
+ *
+ * 按**服务端给的 id 优先级**取，最后才退到正文：
+ * 1. 落库行 id（实时帧的 `data.id` / 落库帧的 `message.id`）——两条路**唯一的公共键**，
+ *    也是服务端唯一保证「同一条消息同一个值」的键；
+ * 2. IM 侧消息号（只有实时帧有：落库失败那一档它仍然在，`id` 缺席）；
+ * 3. 时间字面量（同上，最后的服务端键）；
+ * 4. [fallback]（调用方传**正文**）——服务端一个键都没给时的兜底。
+ *
+ * 第 4 条是刻意的取舍：它会让「没有 id、正文又一个字不差」的两条消息被并成一条（少弹一次），
+ * 而反过来（不兜底 ⇒ 无键可查 ⇒ 每来一帧都弹）会把服务端重推的同一条话弹成两条。**少弹**
+ * 是这两边更轻的那一侧——通知只是提醒，话本身在聊天页里一条都不少。
+ */
+fun proactiveNotifyKey(
+    id: String?,
+    messageId: String?,
+    timestamp: String?,
+    fallback: String,
+): String = listOf(id, messageId, timestamp)
+    .firstOrNull { !it.isNullOrBlank() }
+    ?: fallback
+
+/**
+ * 派生 id 的取值**下界**（见 [proactiveNotificationId]）。
+ *
+ * 通知 id 与 `PendingIntent` 的 request code 都是**全 App 共用**的命名空间，而它们现有的占用者
+ * （保活那条常驻通知 `KEEP_ALIVE_NOTIFICATION_ID` = 1、它点击用的 request code = 0）全在低位。
+ * 从远高于它们的地方起步，「派生 id 不撞既有 id」就是**结构性**成立的，不是靠「碰巧没撞上」。
+ */
+private const val PROACTIVE_NOTIFICATION_ID_FLOOR = 1_000
+
+/**
+ * 派生 id 的取值**宽度**（见 [proactiveNotificationId]）。
+ *
+ * 取这么宽是为了让 id 空间尽量大（撞号的概率随宽度下降），同时**贴着 `Int.MAX_VALUE` 留出下界的
+ * 位置**：「下界 + 宽度」一旦越过 `Int.MAX_VALUE`，末尾的 `.toInt()` 就会折回负数。
+ */
+private const val PROACTIVE_NOTIFICATION_ID_SPAN = 2_000_000_000
+
+/**
+ * 一条 proactive 消息对应的**通知 id（同时也是它点击用的 request code）**——纯函数，由去重键
+ * [proactiveNotifyKey] 的输出派生。这就是「一事一条」的全部落地形状（W54A）。
+ *
+ * ## 为什么必须与去重键同源
+ * 改前所有她的话共用一个固定 id，而 `notify` 遇同 id 是**替换**：她连说几句，用户只看到最后
+ * 一句，前面那几句在他拿起手机之前就已经没了。按消息派生要回答的第一个问题是「凭什么是同一条」
+ * ——那正是 [proactiveNotifyKey] 已经回答过的（实时帧与落库帧共用它）。**两处口径必须永远同源**：
+ * 去重说「这是同一条」、派生说「这是同一条 ⇒ 同一个号」；分成两套，就会出现「认得出是同一条、
+ * 却排出两条 id」的形状漂移。
+ *
+ * ## 它会撞号，后果如实说
+ * `String.hashCode()` 只有 32 位，再折进 [PROACTIVE_NOTIFICATION_ID_SPAN] 这一段 ⇒ **不同消息
+ * 派生出同一个 id 是会发生的**（约 2×10⁹ 的空间，按生日问题算，通知栏里装几十条时概率可忽略）。
+ * 撞上的后果与改前**一模一样**：后来那条替换先来那条，用户少看见一条提醒。这是刻意接受的那一侧
+ * ——通知只是「她找你了」这一下，她的话本身在主会话里一条不少；反过来要绝对不撞，就得在服务端
+ * 唯一号之外再维护一套映射并持久化它，代价比「极少数情况下少一条提醒」大得多。
+ *
+ * ## 两个坑都在这里堵上
+ * 1. **号必须为正**：通知 id 是一个有符号 `int`，而这个命名空间里正数是纪律（本仓保活那条常驻通知
+ *    是 1；平台对前台服务的 id 更直接写明「must not be 0」）。而 `hashCode()` 可以是负的、甚至
+ *    正好是 `Int.MIN_VALUE`——后者连 `abs` 都兜不住（在 int 域里 `abs(Int.MIN_VALUE)` 仍是它自己）。
+ *    所以这里**先展宽到 `Long` 再取绝对值**：`Int.MIN_VALUE.toLong()` = 2147483648，取绝对值是安全
+ *    的，再折进 [PROACTIVE_NOTIFICATION_ID_SPAN] 后落在正区间。
+ * 2. **不撞既有 id**：见 [PROACTIVE_NOTIFICATION_ID_FLOOR]。
+ */
+internal fun proactiveNotificationId(key: String): Int {
+    val magnitude = key.hashCode().toLong().absoluteValue
+    return (PROACTIVE_NOTIFICATION_ID_FLOOR + magnitude % PROACTIVE_NOTIFICATION_ID_SPAN).toInt()
+}
+
+/**
+ * 通知正文：她的原话，**剥掉标记、折成一行、过长截断**；没有可显示的字时回 `null`。
+ *
+ * ## 为什么不直接发原始 `content`
+ * 她的内容里带 `<p>` / `<action>` / `<narration>` 标记（服务端原样落库），直接放进通知会把标签
+ * 露给用户（本仓在会话列表那一行上早就踩过同一件事，见 `ui.sessions.toPreviewText`）。
+ * 这里**复用权威解析器** [parse] 而不是再写一份剥标签的正则：同一件事有两份口径早晚会分叉，
+ * 而分叉的那一侧就是通知里露标签的那一侧。解析出的全部片段按原顺序拼回（旁白/动作也留着——
+ * 那也是她说的话），片段之间补空格，免得「正文紧贴旁白」时两侧的字粘成一个词。
+ *
+ * 截断按 UTF-16 码元走，但**不劈开代理对**（emoji 这类字符由两个码元组成，劈开会显示成半个
+ * 乱码方块）：末尾正好落在高代理项上时整体后退一位。
+ */
+fun proactiveNotificationText(
+    content: String,
+    maxChars: Int = PROACTIVE_NOTIFICATION_MAX_CHARS,
+): String? {
+    val flat = parse(content)
+        .joinToString(" ") { bubble -> bubble.parts.joinToString(" ") { part -> part.text } }
+        .replace(WHITESPACE_RE, " ")
+        .trim()
+    if (flat.isEmpty()) return null
+    // maxChars <= 0 = 「不截断」（调用方明确要全文）；其余情况只在真的超长时才动手。
+    if (maxChars <= 0 || flat.length <= maxChars) return flat
+
+    var end = maxChars
+    if (Character.isHighSurrogate(flat[end - 1])) end -= 1
+    return flat.substring(0, end).trimEnd() + "…"
+}
+
+private val WHITESPACE_RE = Regex("\\s+")

app/src/main/kotlin/top/yeij/cyrene/core/prefs/AppSettings.kt

@@ -8,8 +8,14 @@ import androidx.datastore.preferences.core.booleanPreferencesKey
 import androidx.datastore.preferences.core.edit
 import androidx.datastore.preferences.core.stringPreferencesKey
 import androidx.datastore.preferences.preferencesDataStore
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
 
 private val Context.appDataStore: DataStore<Preferences> by preferencesDataStore("cyrene_app")
 
@@ -72,6 +78,23 @@ fun String?.toInterruptMode(): InterruptMode = when (this) {
     else -> InterruptMode.AppendQueue
 }
 
+/**
+ * 「免打扰」（[AppPrefs.proactiveQuiet]）没有落盘值时的取值 —— **`false` = 都弹**（横幅 + 提示音
+ * + 通知栏条目）。老安装、或从没碰过这个开关的用户走的都是它。
+ *
+ * 两条路必须落在**同一个**值上：[AppPrefs] 那个数据类的默认参数（进程刚起来、还没读到盘时用），
+ * 与 [toProactiveQuiet]（盘上没有这个键时用）。分叉的症状是「开关显示关着、行为却是安静的」
+ * ——一个默认就安静的 App 会让人以为通知坏了。
+ */
+internal const val PROACTIVE_QUIET_DEFAULT = false
+
+/**
+ * 落盘布尔 → 免打扰开关（`AppSettings` 的 `proactive_quiet` 键读取口；抽成顶层函数是为了能单测
+ * ——`AppSettings` 本体要 Android + DataStore，单测里起不来）。缺省 / 盘上没有这个键
+ * ⇒ [PROACTIVE_QUIET_DEFAULT]。
+ */
+internal fun Boolean?.toProactiveQuiet(): Boolean = this ?: PROACTIVE_QUIET_DEFAULT
+
 /**
  * App 级偏好（非机密）。
  *
@@ -79,12 +102,20 @@ fun String?.toInterruptMode(): InterruptMode = when (this) {
  * @param showNarration 是否显示 `<action>` / `<narration>` 旁白
  * @param thinkingExpanded 思维链卡片默认是否展开
  * @param interruptMode 她正忙时按发送的行为（默认追加队列）
+ * @param keepAliveEnabled 后台保持连接（常驻一条前台服务，**默认关**；判据见
+ *   `core.keepalive.shouldKeepAliveRun`）
+ * @param proactiveQuiet 免打扰：她主动找你说话**只在通知栏提示，不在屏幕顶部弹横幅**（**默认
+ *   `false` = 都弹**）。⚠️ 它的语义**不是静音**：提示音与通知栏条目照旧，只是不盖住用户正在做的
+ *   事。落地形状是**换一条渠道**（见 `core.notify.proactiveChannelId`）——横幅由渠道重要级决定，
+ *   而重要级建完就改不了，所以只能两条渠道切着用
  */
 data class AppPrefs(
     val themeMode: ThemeMode = ThemeMode.System,
     val showNarration: Boolean = true,
     val thinkingExpanded: Boolean = true,
     val interruptMode: InterruptMode = InterruptMode.AppendQueue,
+    val keepAliveEnabled: Boolean = false,
+    val proactiveQuiet: Boolean = false,
 )
 
 /** 全局注入 App 偏好，供聊天渲染等深层组件读取。 */
@@ -94,15 +125,45 @@ class AppSettings(context: Context) {
 
     private val store: DataStore<Preferences> = context.applicationContext.appDataStore
 
+    /**
+     * 与 `AppSettings` 同寿的收集 scope —— 也就是**与进程同寿**（`AppContainer` 在
+     * `Application.onCreate` 里建它）。刻意**不取消**：[current] 的下一个读者可以是任何时刻的
+     * 任何一次通知落地，没有比进程结束更晚的时刻需要它。
+     */
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+
     val data: Flow<AppPrefs> = store.data.map { prefs ->
         AppPrefs(
             themeMode = prefs[KEY_THEME_MODE].toThemeMode(),
             showNarration = prefs[KEY_SHOW_NARRATION] ?: true,
             thinkingExpanded = prefs[KEY_THINKING_EXPANDED] ?: true,
             interruptMode = prefs[KEY_INTERRUPT_MODE].toInterruptMode(),
+            keepAliveEnabled = prefs[KEY_KEEP_ALIVE] ?: false,
+            proactiveQuiet = prefs[KEY_PROACTIVE_QUIET].toProactiveQuiet(),
         )
     }
 
+    /**
+     * [data] 的**热副本**：进程里任何地方都读得到「当下是什么偏好」。
+     *
+     * ## 为什么需要它
+     * 发通知那一刻**没有挂起上下文**：帧的落地是一次同步回调（`ProactiveNotifier.post` 不是
+     * `suspend`，也不该是——它是连接那条已建立的流水线上的最后一跳），而 DataStore 的读取是挂起
+     * 的。所以只能由这里常驻订阅、把最近一次读数摆在一个同步读得到的地方（`StateFlow.value`）。
+     *
+     * ## 为什么是 `Eagerly`
+     * 它的读者（发通知那条路）随时可能来，而「等有人订阅了再开始读」意味着第一次落地时读到的是
+     * 初始值。`Eagerly` 让这一次读盘在设置对象构造时就发生 —— 与 UI 那边（`CyreneRoot` /
+     * `SettingsScreen` 各自 `collectAsState`）读的是同一份上游数据，没有多出一次磁盘 IO 的量级。
+     *
+     * ⚠️ 它有一个**毫秒级**的不准确窗口：进程刚起来、第一次读盘还没回来时，[StateFlow.value] 是
+     * [AppPrefs] 的默认值（免打扰 = false ⇒ 弹横幅）。要撞上它，得在「本对象构造完 → DataStore
+     * 第一次读完」之间就有一条她的主动消息走完建连、认证、收帧（`ProactiveFrameIntake`）——
+     * 实际上到不了那么快。**代价封顶是「开了免打扰的用户在冷启动瞬间多看到一次横幅」**，
+     * 而不是丢通知。
+     */
+    val current: StateFlow<AppPrefs> = data.stateIn(scope, SharingStarted.Eagerly, AppPrefs())
+
     suspend fun setThemeMode(mode: ThemeMode) {
         store.edit { it[KEY_THEME_MODE] = mode.name }
     }
@@ -119,6 +180,19 @@ class AppSettings(context: Context) {
         store.edit { it[KEY_INTERRUPT_MODE] = mode.name }
     }
 
+    suspend fun setKeepAliveEnabled(enabled: Boolean) {
+        store.edit { it[KEY_KEEP_ALIVE] = enabled }
+    }
+
+    /**
+     * 写「免打扰」。**写这一处就够了**：发通知那条路每次现读 [current]（见它的 KDoc），所以这里
+     * 一落盘、DataStore 一发出新值，**下一条**通知就走新渠道——不必重启 App，也不必在这里再去
+     * 通知谁。
+     */
+    suspend fun setProactiveQuiet(enabled: Boolean) {
+        store.edit { it[KEY_PROACTIVE_QUIET] = enabled }
+    }
+
     private fun String?.toThemeMode(): ThemeMode = when (this) {
         ThemeMode.Light.name -> ThemeMode.Light
         ThemeMode.Dark.name -> ThemeMode.Dark
@@ -130,5 +204,7 @@ class AppSettings(context: Context) {
         val KEY_SHOW_NARRATION = booleanPreferencesKey("show_narration")
         val KEY_THINKING_EXPANDED = booleanPreferencesKey("thinking_expanded")
         val KEY_INTERRUPT_MODE = stringPreferencesKey("interrupt_mode")
+        val KEY_KEEP_ALIVE = booleanPreferencesKey("keep_alive_enabled")
+        val KEY_PROACTIVE_QUIET = booleanPreferencesKey("proactive_quiet")
     }
 }

app/src/main/kotlin/top/yeij/cyrene/core/session/ChatSessionEviction.kt

@@ -0,0 +1,100 @@
+package top.yeij.cyrene.core.session
+
+/**
+ * 本端**同时**为一个账号留几个会话槽位（N=3，[chatSessionEvictions] 的默认 `keep`）。
+ *
+ * 为什么是 3（**主人拍板的口径**）：它要在「切回去时那几屏东西还在」与「不留着一堆没人再看的
+ * 消息列表」之间取一个数。驱动这个数的是**内存**——每个槽位留着一整页已落库消息（次级会话里可能
+ * 是内联 base64 图片），而 S4 登记的正是「访问过的会话一个都不回收」。不跟着会话数走的理由也在
+ * 这里：它是内存上限，不是「用户可能有多少会话」。
+ */
+const val CHAT_SESSION_SLOT_KEEP = 3
+
+/**
+ * 一格槽位在**被判定那一刻**的样子（[chatSessionEvictions] 的入参，**纯值**）。
+ *
+ * 三项都由调用方现读现喂，判据自己不看 VM、不读表、不碰时钟（先例：`ui.sessions.silentRefreshStep`
+ * 只回结论，账本与时钟都由调用方喂）——所以它在 JVM 上可以穷举。
+ *
+ * @param key 槽位的稳定标识（`账号指纹|会话 id`）。它就是**结论的载体**：判据只把它原样列出来，
+ *   「拿这个 key 去哪里找槽位」是调用方的事。
+ * @param sessionId 会话 id。**它和 [key] 不是同一件事**：key 里还带着账号指纹（换账号之后同一个
+ *   会话 id 是另一格），而这一位只回答一个问题——**它是不是主会话**（主会话永不回收，见
+ *   [chatSessionEvictions] 第 1 条）。两样都留着是刻意的：把「主会话」这件事换个说法搬出判据，
+ *   它就再也钉不住了（那是本任务的红线之一）。
+ * @param lastUsedAt **最后一次成为当前会话**的时刻（毫秒）。「最近」的口径就是它，理由见
+ *   [chatSessionEvictions]。`0` = 建出来还没打开过（组合被丢弃时留下的空槽位）。
+ * @param holdsUnsentWork 这一格里还有**本端唯一一份**的内容（没发出去的草稿 / 没上路的发送）。
+ *   它必须一路传到这里，是因为「回收」是一条**回不来**的动作：判据要在动手之前就能拦下
+ *   「把用户还没发出去的字一起收掉」——那比「多留一格」严重得多（红线：不许静默丢内容）。
+ */
+internal data class ChatSessionUsage(
+    val key: String,
+    val sessionId: String,
+    val lastUsedAt: Long,
+    val holdsUnsentWork: Boolean,
+)
+
+/**
+ * 这一刻该交出去哪几格（**纯函数**，[ChatSessionSlots] 与测试共用）。返回**要回收的槽位 key**，
+ * 最该走的在最前（最旧的最先）；没有要回收的就返回空表。
+ *
+ * ## 「最近」的口径：最后一次**成为当前会话**的时刻
+ * 三选一里选的它，理由是另外两个都答不对这个问题：
+ * - 「最后一次收到这个会话的帧」**不是用户的活动**：共享连接上别的会话的帧一直在来（服务端不按
+ *   会话订阅），一条后台广播就能把一个用户根本没再打开过的会话顶成「最近」。
+ * - 「最后一次有新消息」同理，而且是**别人**的活动（她在次级会话里说一句，本端就要为它留一格）。
+ * - 「最后一次成为当前会话」才是「用户切回去时希望看到什么」这件事本身：槽位存在的意义就是
+ *   那一屏不用重新加载，而**用户看得见哪个会话**只有这一个时刻能表达。
+ *
+ * 它由 `ChatScreen` 在**组合到某个会话时**写入（那正是「它成了当前会话」这一刻），所以判据这边
+ * 只需要比大小，不需要任何时钟：谁的时刻新，谁就留下。同一毫秒并列时按**账本里的先后**退回
+ * （[usages] 的顺序 = 槽位被建出来的顺序，见 [ChatSessionSlots]），也就是「谁先建谁先走」。
+ *
+ * ## 判据与优先级（自上而下，先命中先返回）
+ * 1. **主会话永不回收**：它是抽屉与主流程的锚——用户随时会退回它，而它那一格正是「一进 App
+ *    就有东西看」的来处。这一条**不看** `keep`，也不占「最近」的名额：主会话就是主会话，
+ *    不看它多久没被打开过。
+ * 2. **屏幕上那一格永不回收**（`key == [currentKey]`）：它的 VM 一死，屏幕上那一段就再也不会更新
+ *    （帧收不到、`viewModelScope` 已经取消 ⇒ 连发送都会静默不发），要等下一次重组才会自己修回来
+ *    —— 那是「回收」绝不能带来的一种状态。这一条与主会话同属「按身份豁免」，与时刻无关
+ *    （[currentKey] 那一格通常本来就是最新的，但不靠这件事成立）。
+ * 3. **还有没交代完的事的槽位不回收**（[ChatSessionUsage.holdsUnsentWork]）：那些内容只在本端
+ *    这一份（草稿、排队等连接的发送），回收掉就**回不来**了。这一条压过 `keep` 的语义——
+ *    它宁可让本端多留一格，也不做一件不可逆的事。
+ * 4. 其余按 [ChatSessionUsage.lastUsedAt] 从新到旧留 `keep` 格，**连上面三条占住的一起算**：
+ *    `keep` 是「本端同时保留几格」这个内存目标，所以被豁免的那些**占名额**——不然「最多 3 格」
+ *    在豁免生效时会变成 3 + 豁免数，那个数就没有上限了。（真实使用里豁免的那些几乎总是
+ *    「刚刚还在用的」，本来就在最近 3 个里，这条只在极端情况下才真的挤掉谁。）
+ *
+ * 判据里除了这些入参什么都不看，才能穷举、才能在 JVM 上单测（先例：`ui.chat.reconnectPull`、
+ * `ui.sessions.silentRefreshStep`）。
+ *
+ * ## ⚠️ 它**只**回答「交出去哪几格」
+ * 「交出去」具体是什么动作（清掉那份 `ViewModelStore`、于是这一格的 VM 随 `onCleared` 一起走）
+ * 是调用方的事，而且**必须**是那份 store 自己的 `clear()`：连接是全 App 共享的那一条，它的生死
+ * 只由登录态表达（主人是 `SessionsViewModel`），回收一格**绝不能**碰它——回收一格的状态与
+ * 「别人的流、别人的未读」是两件事，这条判据里连一个字节的连接概念都没有。
+ *
+ * @param usages 账本里的全部槽位（顺序有意义，见「同一毫秒并列」那一句）。
+ * @param mainSessionId 主会话的 id（由装配处注入，判据不认识那个常量本身）。
+ * @param currentKey **此刻屏幕上**那一格的 key（[ChatSessionSlots] 刚记完账的那一格）。
+ * @param keep 本端**同时**保留几格（含主会话、屏幕上那一格与「还有没交代完的事」的那些），
+ *   默认 [CHAT_SESSION_SLOT_KEEP]。
+ */
+internal fun chatSessionEvictions(
+    usages: List<ChatSessionUsage>,
+    mainSessionId: String,
+    currentKey: String,
+    keep: Int = CHAT_SESSION_SLOT_KEEP,
+): List<String> {
+    val reclaimable = usages
+        .filter {
+            it.sessionId != mainSessionId && it.key != currentKey && !it.holdsUnsentWork
+        }
+        .sortedBy { it.lastUsedAt }
+    val budget = keep - (usages.size - reclaimable.size)
+    val surplus = reclaimable.size - budget
+    if (surplus <= 0) return emptyList()
+    return reclaimable.take(surplus).map { it.key }
+}

app/src/main/kotlin/top/yeij/cyrene/core/session/ChatSessionSlots.kt

@@ -0,0 +1,184 @@
+package top.yeij.cyrene.core.session
+
+import androidx.lifecycle.ViewModelStore
+import androidx.lifecycle.ViewModelStoreOwner
+
+/**
+ * 本端留着的**会话槽位**（`账号指纹|会话 id` → 那一格的聊天状态）。S4 的解药。
+ *
+ * ## 它回答的是哪一个问题
+ * `ChatViewModel` 是**按会话**建的（`sessionId` 是构造参数），于是「切走 / 删会话都不回收」意味着
+ * 访问过 N 个会话就常驻 N 份消息列表（含内联 base64 图片）、N 份对共享连接的订阅、以及**每次重连
+ * 各自一轮** `after` 补拉。这里就是那个「N」的闸门：**一格一个 `ViewModelStore`**，超出的按
+ * [chatSessionEvictions] 的结论交出整格。
+ *
+ * ## 为什么一格一个 `ViewModelStore`（而不是给 key 加一代号）
+ * 回收的本体动作是「让那一格的 VM 真正死掉」：`ViewModelStore.clear()` 会走 `ViewModel.onCleared()`
+ * 并取消 `viewModelScope`——于是**订阅、补拉、正在飞的那些请求一起停下**。此前每一格都塞在
+ * Activity 级那个 store 里，而它**只有整体 `clear()`**，没有「按 key 交出一格」的入口：那种情况下
+ * 只能让 key 换一代、把旧实例**留在 store 里**（它照样活着、照样收帧——那正是 S4 的另一半没修掉
+ * 的样子）。一格一份 store 之后，`clear()` 的粒度就正好是「这一格」。
+ *
+ * ## 回收**不碰**共享连接
+ * 连接是全 App 唯一的那一条（`AppContainer.chatSocket`），它的生死只由登录态表达
+ * （主人是 `SessionsViewModel`）。本类碰的只有「自己那一格的 store」：掐掉的是这一格的订阅，
+ * 别的会话的流、别的会话的未读、以及那条连接本身一个字节都不动。
+ *
+ * ## 谁碰它、什么时候（全部在主线程上）
+ * - **`ChatScreen`**：组合到某个会话时 [slotFor] 取（或建）槽位——VM 必须有地方建，而槽位就是
+ *   那一格的存放处，所以这一步没法挪到组合之后；组合完成之后 [onOpened] 记账 + 回收。
+ * - **`SessionsViewModel`**：本端**唯一**的删除入口，删成功后 [reclaim]（那一格跟着会话一起走）；
+ *   登出 / 换账号时 [clear]（与快照 / 已读游标 / [GoneSessions] 同一档：换代之后本端什么都不知道）。
+ * - 三者都在主线程上（组合、`viewModelScope` 的默认派发器），所以账本本身不加锁——它的每一个
+ *   读写点都在同一个线程上。
+ *
+ * ## 为什么不持久化
+ * 槽位里装的是**进程内存里的状态**（消息列表、草稿、流式缓冲），它没有可以落盘的形式，而它的
+ * 内容全部另有来源（服务端的 `GET /messages` 那一页 + 服务端的幂等键）。重启之后本端重新拉，
+ * 与 [GoneSessions] 「不持久化」是同一个理由。
+ */
+class ChatSessionSlots(private val mainSessionId: String) {
+
+    /**
+     * 账本。用 `LinkedHashMap` 只为一件事：**同一毫秒并列**时 [chatSessionEvictions] 的稳定排序会
+     * 退回这个插入顺序（先建出来的先走）。除此之外顺序不表达任何东西——「谁最近」一律看
+     * [ChatSessionSlot] 里的 `lastUsedAt`。
+     */
+    private val slots = linkedMapOf<String, ChatSessionSlot>()
+
+    /**
+     * 取这个会话的槽位（没有就建一个）。**组合期间**调用。
+     *
+     * 它**不记账**：谁最近用过由 [onOpened] 写。所以就算这一段组合被丢弃（组合没走完），留下的也
+     * 只是一个 `lastUsedAt` 还是 `0` 的空槽位，下一次回收就会把它扫掉（它必然是最旧的那一格）。
+     */
+    fun slotFor(account: String, sessionId: String): ChatSessionSlot =
+        slots.getOrPut(keyOf(account, sessionId)) { ChatSessionSlot(sessionId) }
+
+    /**
+     * 这个会话**刚刚成为当前会话**：记下它是「最近」的那一格，然后按 [chatSessionEvictions] 回收。
+     *
+     * 记账与回收在同一处，是因为回收的判据就是这份账本本身（先例：`ui.sessions.silentRefreshStep`
+     * 把「该做什么」与「账本走成什么样」一起回）：拆开就会给出「判了却忘了推进账本」的机会，
+     * 而那正好会让最该留下的那一格被当成最旧的收掉。同一处也才拿得到那个 key —— 判据要
+     * **按身份**豁免的就是刚记完账这一格（`chatSessionEvictions` 的 `currentKey`）。
+     *
+     * @param holdsUnsentWork 现读的一格真相（见 [ChatSessionUsage.holdsUnsentWork]）。收的是一个
+     *   **探针**而不是一个布尔快照，是因为回收发生在**别的**会话被打开的那一刻 —— 而那一刻正是
+     *   用户可能刚在前一个会话里打了草稿、还没切走的时候。快照会把它读成「干净」，把没发出去的
+     *   字一起回收掉（那是一条回不来的动作）。
+     */
+    fun onOpened(
+        account: String,
+        sessionId: String,
+        holdsUnsentWork: () -> Boolean,
+        nowMillis: Long,
+    ) {
+        val key = keyOf(account, sessionId)
+        slotFor(account, sessionId).opened(holdsUnsentWork, nowMillis)
+        sweep(currentKey = key)
+    }
+
+    /**
+     * 定点回收一格（删会话）：把那份 store 交出去，那个 VM 随 `onCleared` 一起走，本类不再引用它。
+     *
+     * 与 [GoneSessions] 的关系：那是「本端已知它没了」这件事的**第一半**（让还活着的 VM 别再去发
+     * 注定 404 的补拉），这里是**第二半**（那一格本来就该跟着会话一起消失）。两半分开写在两处，
+     * 是因为它们回答的问题不同——一个答「还值不值得发请求」，一个答「还留不留这一格状态」，
+     * 而后者要动 VM 的生命周期，不该被前者拽住（`ui.chat.reconnectPull` 只读前者）。
+     */
+    fun reclaim(account: String, sessionId: String) {
+        slots.remove(keyOf(account, sessionId))?.clear()
+    }
+
+    /**
+     * 换账号 / 登出：本端**一格都不留**。
+     *
+     * 与快照 / 已读游标 / [GoneSessions] 是同一档纪律（`SessionsViewModel` 的登出分支一处清完）：
+     * 槽位里的东西全部属于**上一个环境**，留着只会在下一次登录后变成一份没人认领的常驻内存
+     * （而它带着的那个 VM 还在订阅连接、还会在重连时补拉）。这一条也顺带把 [ChatSessionSlot] 的
+     * 那条「主会话永不回收」的例外收干净：换账号时连主会话那一格也不留。
+     *
+     * 代价说清楚：登出（含令牌失效那条路径）之后**本端未发出的草稿会跟着没了**。这与既有口径一致
+     * ——登出时快照、已读游标、已删会话的结论都是当场清掉的（那些也都没落盘）。
+     */
+    fun clear() {
+        slots.values.forEach { it.clear() }
+        slots.clear()
+    }
+
+    /**
+     * 按 [chatSessionEvictions] 的结论交出超出的那几格（「最近」的口径见那个函数的 KDoc）。
+     *
+     * @param currentKey 刚记完账、此刻在屏幕上那一格的 key（它按身份豁免，见判据第 2 条）。
+     */
+    private fun sweep(currentKey: String) {
+        val usages = slots.map { (key, slot) -> slot.usage(key) }
+        chatSessionEvictions(usages, mainSessionId, currentKey)
+            .forEach { key -> slots.remove(key)?.clear() }
+    }
+
+    /** 与聊天页的 VM key 无关：这是**槽位**的身份，账号指纹在里面是为了换账号时天然分格。 */
+    private fun keyOf(account: String, sessionId: String): String = "$account|$sessionId"
+}
+
+/**
+ * 一个会话的槽位：**它自己的那份 `ViewModelStore`**，外加这项回收策略要的两个记账位。
+ *
+ * 装在这里的 VM 由 `ChatScreen` 经它取出（`viewModel(viewModelStoreOwner = 槽位, key = <账号指纹|会话 id>)`）：
+ * key 仍然是 `chatViewModelKey` 那一份口径，只是现在**配着一份按会话分的 store** 用。
+ *
+ * 它**不持有** VM 的类型：本类只知道「怎么把这一格交出去」（[clear]）与「它还有没有没交代完的事」
+ * （[opened] 收下的那个探针）。这样 `core.session` 不必认识 `ui.chat` 的任何类型，而两件事
+ * ——「槽位怎么算最近」与「VM 里哪一位算没交代完」——各自待在自己那一层。
+ */
+class ChatSessionSlot internal constructor(
+    /** 本槽位的会话 id（槽位身份的一半：账号指纹在 [ChatSessionSlots] 的账本 key 里）。 */
+    val sessionId: String,
+) : ViewModelStoreOwner {
+
+    private val store = ViewModelStore()
+
+    override val viewModelStore: ViewModelStore
+        get() = store
+
+    /**
+     * 最后一次成为当前会话的时刻（毫秒）；`0` = 建出来还没打开过。**只增不改**。
+     *
+     * 由 `ChatSessionSlots.onOpened` 写（那里是「它成了当前会话」的唯一表达处），本类不自己读时钟。
+     * 不进 [usage] 以外的任何地方——「最近」的判据只认它，而判据只吃 [ChatSessionUsage]。
+     */
+    private var lastUsedAt: Long = 0L
+
+    /**
+     * 这一格里「还有没有没交代完的事」的**现读**探针（见 [ChatSessionSlot.opened] 的说明）。
+     * 默认恒 `false`：还没打开过的一格当然没有。
+     */
+    private var holdsUnsentWork: () -> Boolean = { false }
+
+    /** 这一格成了当前会话：记下该问谁「还有没有没交代完的事」，并更新「最近」这一位。 */
+    internal fun opened(holdsUnsentWork: () -> Boolean, nowMillis: Long) {
+        this.holdsUnsentWork = holdsUnsentWork
+        lastUsedAt = nowMillis
+    }
+
+    /** 交给判据的样子（判据不认识本类，见 [ChatSessionUsage]）。 */
+    internal fun usage(key: String): ChatSessionUsage = ChatSessionUsage(
+        key = key,
+        sessionId = sessionId,
+        lastUsedAt = lastUsedAt,
+        holdsUnsentWork = holdsUnsentWork(),
+    )
+
+    /**
+     * 交出这一格：`ViewModelStore.clear()` ⇒ 那一格的 `ViewModel.onCleared()` + `viewModelScope`
+     * 取消（订阅、补拉、在飞的请求一起停），随后**松开探针**。
+     *
+     * 松开探针不能省：它捕获着那个 VM（否则就成了一份「已经交出去、却还被人拎着」的引用，
+     * 那一格的消息列表会跟着这条引用活到进程结束——正是本类要断掉的那根线）。
+     */
+    internal fun clear() {
+        store.clear()
+        holdsUnsentWork = { false }
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/core/session/GoneSessions.kt

@@ -7,16 +7,21 @@ import kotlinx.coroutines.flow.update
  * 本端**已经知道服务端没有这个会话**的那几个会话 id（进程级、只在内存里、只增不减）。
  *
  * ## 它回答的是哪一个问题
- * 「这个 id 还值不值得我发一次请求」。`ChatViewModel` 每个访问过的会话各留一个常驻 VM
- * （切走 / 删会话都不回收），而它们都订阅同一条共享连接 ⇒ **每次重连各自会去补拉一轮**。会话
- * 在本端被删掉之后，那个 VM 并不知道（它没有别的渠道知道），于是**每一个**重连都发一次注定
- * `404 session_not_found` 的补拉，404 被静默吞掉（S7 登记的那一条）。
+ * 「这个 id 还值不值得我发一次请求」。`ChatViewModel` 是按会话建的，本端**同时**留着其中几格
+ * （W52A 起是 `ChatSessionSlots` 的 N 格），它们都订阅同一条共享连接 ⇒ **每次重连各自会去补拉
+ * 一轮**。会话在本端被删掉之后，那个 VM 自己并不知道（它没有别的渠道知道），于是**每一个**重连
+ * 都发一次注定 `404 session_not_found` 的补拉，404 被静默吞掉（S7 登记的那一条）。
  *
  * 补拉**事前**就能判掉它，靠的就是这里：删除是**本端自己做的**，那一刻就已经知道结果了，
  * 没有任何理由等下一条请求回来才「发现」。于是这一位把「已知不存在」从「一次注定失败的往返」
  * 提前成「一次本地查询」——**不是**「重连时少拉一点」的省流量优化，而是不让一个注定失败的请求
  * 上路（它会占一条连接、写一行日志、并把 `sessionGone` 变成一个只能靠 404 才置得起来的位）。
  *
+ * W52A 又给这件事加了一半：删会话时那一格**当场就被回收**（`ChatSessionSlots.reclaim`），所以
+ * 大多数情况下这里拦的已经是一个不会再发生的补拉。它仍然留着，因为两件事回答的不是一个问题
+ * ——这一位答「还值不值得发请求」，槽位答「还留不留这一格状态」，而**本端删掉一个会话**与
+ * **那个会话在别处被删掉**（只能靠 404 发现）是两条不同的路，后者压根不经过这里。
+ *
  * ## 为什么是进程级、为什么**不**持久化
  * - 进程级（挂在 `AppContainer` 上，与那条共享连接同一层）：写它的是 `SessionsViewModel`
  *   （本端唯一的删除入口），读它的是**别的** VM —— 两个 VM 之间没有别的共享面。
@@ -25,7 +30,8 @@ import kotlinx.coroutines.flow.update
  *   以那一次服务端答复为准；把 id 落盘只会让一份陈旧记忆挡掉重启后的第一次拉取。
  * - **换账号要清**（[clear]）：id 是服务端铸的，理论上不会跨账号撞车，但这一位说的是「本端
  *   已经知道」，而换账号之后本端**什么都不知道** —— 留着上个环境的结论，是那种「差一个分隔符
- *   就漏过去」的同一类错误（先例：`accountFingerprint` 的注释）。
+ *   就漏过去」的同一类错误（先例：`accountFingerprint` 的注释）。同一处也清聊天页的槽位
+ *   （`ChatSessionSlots.clear`），两件事属同一档纪律。
  */
 class GoneSessions {
 

app/src/main/kotlin/top/yeij/cyrene/data/api/MediaApi.kt

@@ -0,0 +1,41 @@
+package top.yeij.cyrene.data.api
+
+import okhttp3.ResponseBody
+import retrofit2.Response
+import retrofit2.http.GET
+import retrofit2.http.Streaming
+import retrofit2.http.Url
+
+/**
+ * 语音副本的字节读取（契约 **v0.79 已实现**，api-client.md §1.2 **U19**
+ * `GET /api/v1/media/{name}`）。
+ *
+ * ## 鉴权：**必须** Bearer `owner|admin`
+ * 与 `GET /api/v1/documents/{name}` 同一套门，与图片读侧「128-bit 名即凭据」**刻意相反**
+ * ——语音是私密内容，那个 URL 不能直接贴进 `<audio src>`。Bearer 不在本接口上做任何事：
+ * [ApiClientFactory.create] 按 **OkHttpClient** 挂 `AuthInterceptor`，只要本接口的实例是从
+ * 那里建的（`AppContainer.mediaApi` 的写法），请求就自带令牌、并享受 401 单飞续期。
+ *
+ * ## 为什么参数是一整条 URL 而不是 `@Path name`
+ * 契约把相对路径 `/api/v1/media/<name>` 定成**服务端唯一的派生字段**（`voice.url`），并明写
+ * 客户端**绝不自己拼路径**。所以调用方把**服务端给的那条路径接到当前服务器地址上**
+ * （纯函数 `domain.chat.voiceMediaUrl`）再传进来——本接口一个字都不拼，只发出去。
+ *
+ * @see MediaRepository
+ */
+interface MediaApi {
+
+    /**
+     * 取一条语音副本的字节。
+     *
+     * 响应**不是信封**（就是音频本身），所以返回 [ResponseBody] 由仓库层读字节并负责关闭。
+     * [Streaming] 让 Retrofit 不把响应体一次性读进内存。
+     *
+     * ⚠️ 服务端的 `416`（`Range` 不可满足）是**标准库直写**的 `text/plain` + `Content-Range`，
+     * **不套** `{"error":{…}}`（契约 §0.3 / §4.5）——本端不发 `Range`、也不拿 `error.code`
+     * 去解析它，`ApiErrorMapper` 对这种非信封响应的处理是「说不出就不编」。
+     */
+    @Streaming
+    @GET
+    suspend fun download(@Url url: String): Response<ResponseBody>
+}

app/src/main/kotlin/top/yeij/cyrene/data/api/SpeechApi.kt

@@ -0,0 +1,67 @@
+package top.yeij.cyrene.data.api
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import okhttp3.ResponseBody
+import retrofit2.Response
+import retrofit2.http.Body
+import retrofit2.http.POST
+import retrofit2.http.Streaming
+
+/**
+ * 一段待朗读的文本（`POST /api/v1/audio/speech` 的请求体，api-client.md §1.2 U6 / 行 126）。
+ *
+ * ## 只有两个字段，是**刻意的**
+ * 契约给了五个键 `{text, voice?, format?, instruction?, sessionId?}`，但其中三个在本端**不生效**：
+ * - `voice`：接受但不生效 —— 发音人**不由它决定**；
+ * - `format`：不生效 —— 产物恒为 WAV（响应也明说「别照抄 `Content-Type`」，见 [SpeechApi]）；
+ * - `instruction`：只影响表达方式，本端当前的产品口径里没有「怎么说」这一档输入。
+ *
+ * 发一个服务端会忽略的键，只会让排查时多一条**看起来有含义、实际没有**的字段。所以这里只发
+ * 真正起作用的那两个 —— 尤其是 [sessionId]：发音人由它**那条会话的生效人格**解析
+ * （会话绑定人格 → 全局默认人格 → 都没有就取服务端配置的 default），**省略它不等于没有角色**。
+ *
+ * [sessionId] 为 `null` 时字段**整个缺席**（`ApiClientFactory.json` 的 `explicitNulls = false`），
+ * 而不是发一个 `"sessionId": null`。
+ */
+@Serializable
+data class SpeechRequestDto(
+    @SerialName("text") val text: String,
+    @SerialName("sessionId") val sessionId: String? = null,
+)
+
+/**
+ * 语音合成（契约 **v0.96 增量 / v0.97 补写**，api-client.md §1.2 **U6** `POST /api/v1/audio/speech`）。
+ *
+ * ## 鉴权：owner-only，双凭据门
+ * `Authorization: Bearer <owner JWT>` **或** `X-API-Key`，两个分支在服务端落到同一个
+ * `authorize(RoleOwner)`。本端只走前者（主人 2026-10-26 拍板：不设 API Key 输入框），令牌由
+ * [ApiClientFactory.create] 挂在 OkHttpClient 上的 `AuthInterceptor` 自动注入，本接口不碰它。
+ * 无 / 无效凭据 → `401`，错误体是 §4.1 那个 `{error:{code,message}}` 信封。
+ *
+ * ## 响应**不是信封**
+ * 成功是 `200` + **原始音频字节**（与 [MediaApi] 同一个形状），所以返回 [ResponseBody] 由上层
+ * 读字节并负责关闭，[Streaming] 让它不一次性读进内存。
+ *
+ * ⚠️ **产物恒为 WAV，按字节嗅探判定，不要照抄 `Content-Type`** —— 那条头的实际值不在契约里
+ * 承诺（§4.1 行 561 的同句旁注就是这个意思）。嗅探在 [top.yeij.cyrene.data.voice.SpeechClient]。
+ *
+ * 失败时的错误码（全部是 `{error:{code}}` 信封）：
+ * `400`（空 text）、`500 voice_unavailable`（未接语音）、`500 tts_failed`、
+ * `500 tts_persona_unmapped`（人格没有发音人映射）、`500 tts_no_character`（连生效人格都没有）、
+ * `500 tts_empty`（拿到的是静默空音频，同时响应头带 `X-Voice-Provider: silent`）。
+ *
+ * @see top.yeij.cyrene.data.voice.SpeechClient
+ */
+interface SpeechApi {
+
+    /**
+     * 把 [body] 合成为一段 WAV 字节。
+     *
+     * 路径**不带前导 `/`**（与 [ChatApi] 一致）：Retrofit 的 `baseUrl` 已含 `/` 结尾，
+     * 带前导 `/` 会把它当成根路径、把部署在子路径下的服务端地址整段丢掉。
+     */
+    @Streaming
+    @POST("api/v1/audio/speech")
+    suspend fun speech(@Body body: SpeechRequestDto): Response<ResponseBody>
+}

app/src/main/kotlin/top/yeij/cyrene/data/api/dto/MessageDto.kt

@@ -8,6 +8,10 @@ import kotlinx.serialization.Serializable
  *
  * 它同时是 WS 握手 `history` 回放与 `message_persisted` 的载荷消息类型
  * （服务端三处共用同一个 `historyMessage`），所以 [documents] 的解析一处覆盖三条路。
+ *
+ * [voice] 从契约 v0.97（后端 M44 `fb55769`）起也**不再是例外**：REST 四路、握手 `history` 回放、
+ * `message_persisted` / `channel_persisted` 落库帧**都填它**，第一条帧就带
+ * （前提与理由写在 [voice] 的 KDoc 里）。
  */
 @Serializable
 data class HistoryMessageDto(
@@ -59,6 +63,38 @@ data class HistoryMessageDto(
      * 回放 / `channel_persisted`（本端不消费最后一条）。
      */
     val turnId: String? = null,
+    /**
+     * 这条消息的语音元数据（契约 v0.67 登记、**v0.79 已实现**，形状见 [VoiceDto]）；
+     * **非语音消息整键缺席** —— 所以缺席与 `null` 是同一件事。
+     *
+     * ## 判据是**两个**问题，别再合成一个
+     * - 「这条**来自**一段声音吗」= 这个键在不在（`domain.chat.hasVoice`）；
+     * - 「要不要画语音形态」= 键在 **且** `status != "failed"`（`domain.chat.isVoiceMessage`）。
+     *   后端 M57-M59 的出站合成降级行（`{source:"tts", status:"failed", fallbackReason}`）与入站的
+     *   转写失败行都是**键在、但没有可播的语音**：正文照常按文字渲染，另加一行灰色小标
+     *   （`domain.chat.voiceFallbackNote`），**不画**语音形态。按旧的单条判据（键在即语音）它们会
+     *   被画成一个点下去必然播不了的气泡。
+     *
+     * ## 覆盖率（契约 v0.97）：**全部读面都带**，第一条帧就带
+     * `GET /sessions/{id}/messages`、`GET /admin/channels/messages`、
+     * `GET /admin/channels/{platform}/messages`、`PATCH /messages/{id}` 的响应与
+     * `message_edited` 广播帧，**外加** WS 握手 `history` 回放与 `message_persisted` /
+     * `channel_persisted` 落库帧——后三处由后端 M44（`fb55769`）修好：落库顺序改为
+     * **INSERT → 写 `voice` 列 → notify**，于是语音消息的**第一条**落库帧就带 `voice`
+     * （v0.79 时期「落库那一刻还拿不到、等下一次拉取自动升级」的说法**已作废**）。
+     *
+     * 所以本端**没有任何**「实时帧先按普通文本显示、稍后升级成语音气泡」的兜底：
+     * `voice` 在就按 `status` 分流，不在就不是语音。**不要为它加重试 / 轮询 / 延迟判定**。
+     *
+     * ⚠️ 两条实现前提（服务端口径，未来改动**别破坏它**）：① `voice` 列写入必须先于 notify；
+     * ② 帧内 `voice` 是**发出那一刻的即时列读**（每帧多一次查询，亚毫秒）。任一被改回
+     * 「先 notify 再写列」，本端判据立刻退回 v0.79 的行为——而本端**刻意不再为它留兼容分支**。
+     *
+     * ⚠️ 列被外部改坏（非法 JSON / 越出闭集）时服务端**让字段缺席**（记一条不带正文的 WARN），
+     * 于是这种情况在本端与「不是语音」同形——契约的 `voice` 没有「读不出」这一态，缺席是唯一
+     * 诚实的表达（与 [documents] 回一条 `unreadable` 不同）。
+     */
+    val voice: VoiceDto? = null,
 )
 
 /**

app/src/main/kotlin/top/yeij/cyrene/data/api/dto/VoiceDto.kt

@@ -0,0 +1,86 @@
+package top.yeij.cyrene.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * 一条消息的**语音元数据**（契约 **v0.67 登记、v0.79 已实现（切片 L45）**，
+ * `Cyrene_v2/Docs/api-client.md` §4.4「`voice` 语义」与 §1.2 U19）。
+ *
+ * ## 🎤 判据 = 本键存在 **且** `status != "failed"`
+ * `voice` 是 [HistoryMessageDto] 上的**指针**：非语音消息**整键缺席**（不是 `{}`，也不是 `null`）。
+ * 客户端**只认这个键**，**绝不**从 `content` 正文里认媒体类型——QQ 语音正文里那个 `[语音]`
+ * 占位标记自 v0.67 起**不再下发**，而正文里**也可能**出现用户自己打出的 `[语音]` 字样。
+ *
+ * 键在只说明「这条来自一段声音」；要不要画语音形态还看 `status`（见下）。
+ * 判据落在一处：`domain.chat.isVoiceMessage`（`domain.chat.hasVoice` 答的是前半个问题）。
+ *
+ * ## 三态 `status`（闭集）
+ * `transcribed`（正文即转写文本；出站方向 = 合成成功）/ `empty`（转写成功但没识别出文字）/
+ * `failed`（**没有可播的语音**——入站没拿到转写文本，出站是合成降级回文字）。客户端**按 `status`
+ * 分支，绝不按正文文案分支**；设计上刻意不下发 `failed` 的机器可读细分（未配置 / 鉴权 / 欠费 /
+ * 限流 / 超时 / 格式不支持 / 无字节一律只进服务端日志），所以本端**不猜**细分。
+ *
+ * ## `fallbackReason` 只在 `failed` 时有
+ * 出站方向（`source = "tts"`）合成降级时，服务端在这个键里给出降级原因；本端**原样**小字展示
+ * （`domain.chat.voiceFallbackNote`），**不猜闭集**——取值集合后端尚未定稿，见那个函数的 KDoc。
+ *
+ * ## `name` / `mime` / `size` / `url` 四者同生共死
+ * 有音频副本时四个键全在，**无副本时全缺席**（服务端保证不会出现 `url` 指着一个不存在的 `name`）。
+ * 反过来说：**四个键没凑齐就不要画播放控件**——不能给一个点下去必然失败的按钮。
+ * 判据落在一处：`domain.chat.voiceAudio`。一个真实的无副本例子是微信（`weixin-ilink`）：
+ * 平台自带转写就**不白下载那份音频**，于是 `source` 是 `platform` 而四个键全缺席
+ * （**只有 🎤 标记**，不可回放）。
+ *
+ * ## `durationMs` 只有渠道如实给出时才有
+ * 服务端「读不出来就省略键，**绝不估算**」。本端同理：**缺席就不显示时长**
+ * （不拿 size / 码率反算，也不显示 `0:00` 冒充）。所以它是可空的，且 `<= 0` 一并当缺席
+ * （见 `domain.chat.voiceDurationLabel`）。
+ *
+ * ## `url` 是**服务端相对路径**，客户端绝不自己拼
+ * 取值形如 `/api/v1/media/<name>`，由服务端一处拼出（**唯一派生字段**）。
+ * 客户端要取字节时把它接到**当前服务器地址**后面（`domain.chat.voiceMediaUrl`）——
+ * 与图片那条「保留 path、替换 host」同一取向，但这里服务端给的就是相对路径，不需要换 host。
+ */
+@Serializable
+data class VoiceDto(
+    /**
+     * `"asr"`（服务端语音识别所得，含云端）/ `"platform"`（渠道平台自带转写，微信 iLink 的
+     * `voice_item.text`）/ `"tts"`（我们自己合成的出站语音，后端 M57-M59）。
+     * 见 `domain.chat.VoiceSource`。**开放取值**：认不出的原样保留。
+     *
+     * 接收侧**不按 `source` 分支**：合成成功的那条与入站语音同形（`status = transcribed` +
+     * 四键副本），走同一条渲染路径。
+     */
+    val source: String = "",
+    /**
+     * `"transcribed"` / `"empty"` / `"failed"`（闭集三态，见 `domain.chat.VoiceStatus`）。
+     *
+     * 默认空串而非某个态，是因为**认不出就不要装认识**：显示层对「不是 `empty`」的所有取值
+     * （含服务端将来新增的态）一视同仁地不额外说话（见 `domain.chat.voiceNote`）。
+     *
+     * ⚠️ 只有 `"failed"` 是**没有可播的语音**的那一态（`domain.chat.isPlayableVoice`）；认不出的
+     * 取值一律当可播（fail-open，理由写在那个函数的 KDoc 里）。
+     */
+    val status: String = "",
+    /** 音频副本的存储名（内容寻址，`<32hex>.<ext>`）；**无副本 ⇒ 键缺席**。 */
+    val name: String? = null,
+    /** 副本的 MIME（按存储名扩展名映射）。与 [name] / [size] / [url] 同生共死。 */
+    val mime: String? = null,
+    /** 副本的字节数。与 [name] / [mime] / [url] 同生共死；**不用它反算时长**。 */
+    val size: Long? = null,
+    /** 时长（毫秒）。**只有渠道如实给出时才有**；缺席 = 本端不显示时长。 */
+    val durationMs: Int? = null,
+    /**
+     * 合成降级的原因（后端 M57-M59 预告，`devdocs/02` 已登记；契约 **v0.98 的正式回执尚未到**）。
+     *
+     * 只在 `status == "failed"` 时有意义，其余状态下服务端不会下发（`omitempty`）；入站转写失败
+     * 也不带它——入站的失败原因由正文那行诚实提示承载。
+     *
+     * 本端**原样**小字展示（`domain.chat.voiceFallbackNote`），**不猜闭集、不做映射**：取值集合
+     * 后端还没定（`tts_timeout` 之类是我们看到的预告示例，不是契约）。缺席 / 空白时那一行小标
+     * 退化成固定的一句（`VOICE_FALLBACK_NOTE`），不白屏。
+     */
+    val fallbackReason: String? = null,
+    /** 副本的服务端相对路径（`/api/v1/media/<name>`）。**不要自己拼这条路**，也不要当绝对地址用。 */
+    val url: String? = null,
+)

app/src/main/kotlin/top/yeij/cyrene/data/repository/MessageRepository.kt

@@ -16,7 +16,8 @@ import kotlinx.coroutines.withContext
  * 三条读取出口共用同一个端点，只是给的查询参数不同：
  * - [loadPage] / [loadLatest]：`before` 往回翻（服务端**倒序**返回）；
  * - [search]：`q` 会话内搜索（也是倒序）；
- * - [loadAfter]：`after` 往前追（服务端**升序**返回，契约 §1 行 6）。
+ * - [loadAfter]：`after` 往前追（服务端**升序**返回，契约 §1 行 6）；[loadIncrement] 是它在
+ *   `after` 方向上的翻页版（一直追到尾巴，追不到就如实说 `complete = false`）。
  *
  * 三者都统一转成**升序**的 [PagedMessages] 再交出去。去重 / 合并请用 [mergeMessages]。
  */
@@ -87,7 +88,9 @@ class MessageRepository(
      * `createdAt`（[PagedMessages.newestCreatedAt]），不是最旧的。
      *
      * 同毫秒并列且条数超过 `limit` 时，纯 `createdAt` 游标推不动（契约 §A5 明说的已知边界）——
-     * 调用方按 `id` 去重、并在游标没前进时停下来，不在这里兜。
+     * 落在页边界上的那一毫秒里剩下的行**再也追不回来**，因为服务端只给严格 `>`。调用方按 `id`
+     * 去重，并且**不能把满页之后的一页（空页、不满页都一样）当作追到了尾巴**：要翻页又要把边界
+     * 说清楚，用 [loadIncrement]，不要自己拿这一页凑。
      */
     suspend fun loadAfter(
         sessionId: String,
@@ -100,6 +103,87 @@ class MessageRepository(
             .map { raw -> toPagedMessages(raw, pageSize) }
     }
 
+    /**
+     * **增量追尾**（W77）：从 [after] 起把某会话的新消息一直翻到尾巴，最多 [maxPages] 页。
+     *
+     * 与裸的 [loadAfter] 的差别只有一件：**它负责把「还没翻完」这件事如实说出来**。
+     *
+     * ## 什么时候只能说 `complete = false`
+     * 游标是本页**最新**一条的 `createdAt`，而服务端只给 `created_at > after`（**严格**大于：
+     * `list_after.go` 的 `ListAfter` 与 `devtools/fake-backend` 两处一致）。于是**落在页边界上被
+     * 劈开的那一毫秒**里的行永远追不回来——它们的 `createdAt` 恰好等于游标，再问一次也问不到
+     * （契约 §A5 的已知边界：纯 `createdAt` 游标没有毫秒内的次序）。
+     *
+     * 要紧的是**切点**：只有当服务端的 `LIMIT` 在某一毫秒中间切过一刀，才会留下追不回来的尾巴。
+     * 客户端看不见那一刀落在哪儿，只知道自己**拿过满页**就等于「发生过一次切点」。所以这里只有一条
+     * 不变式，下面几档都是它的推论：
+     *
+     * > `complete = true` **当且仅当整个追尾从未拿过满页**。
+     *
+     * - **第一页就是空页 ⇒ `true`**：一条新消息都没有，没有可少给的；
+     * - **第一页就不满 ⇒ `true`**：`LIMIT` 没切到任何东西，`> cursor` 的行全在这一页里；
+     * - **拿过整页之后，下一页是空页 ⇒ `false`**：那次空页分不出「干净的尾巴」与「空页底下还压着
+     *   同一毫秒的几条」；
+     * - **拿过整页之后，下一页不满 ⇒ 也是 `false`**：不满只说明「`> cursor` 的行就这么多了」，对
+     *   切点那一毫秒还有没有行**一无所知**。例如积压 `m1@500 m2@500 m3@500 m4@600`、页宽 2：
+     *   第一页给 `m1 m2`（切点正好劈开 500 那一毫秒），第二页 `after=500` 只给 `m4@600`、不满页，
+     *   而 `m3@500` 既不 `> 500`、也就永远拿不到；
+     * - **翻满 [maxPages] ⇒ `false`**。
+     *
+     * 代价：积压一到页宽（默认 50 条）就回落整表。这与「翻满 [maxPages] ⇒ 回落」同类——那时增量
+     * 已经取回 ≥50 行，多问一次整表是边际成本，也正合 [MAX_INCREMENT_PAGES] 那句「积压多到增量不再
+     * 便宜」。主路径（几条新消息、第一页就不满）不受影响。
+     *
+     * 这里**不猜**、也不悄悄少给几条：说不完整，调用方还能去问唯一权威。
+     *
+     * 不传 `platform`：未读面上的口径是服务端 `count(created_at > read_at)`（`unreadCountQuery`，
+     * 不带平台过滤），按平台过滤会让本地数出来的条数**与服务端的 `unreadCount` 不同源**。
+     *
+     * @param after 本端**已见**的最大 `createdAt`（毫秒）；服务端返回严格新于它的消息，升序。
+     * @param maxPages 最多翻几页（默认 [MAX_INCREMENT_PAGES]）。用尽即 `complete = false`：
+     *   一次静默刷新不该为了补一个角标翻十几页。
+     */
+    suspend fun loadIncrement(
+        sessionId: String,
+        after: Long,
+        pageSize: Int = DEFAULT_PAGE_SIZE,
+        maxPages: Int = MAX_INCREMENT_PAGES,
+        platform: String? = null,
+    ): Result<MessageIncrement> = withContext(dispatcher) {
+        val size = pageSize.coerceIn(1, MAX_PAGE_SIZE)
+        val byId = LinkedHashMap<String, HistoryMessageDto>()
+        var cursor = after
+        // 只要翻到过一整页，就说明服务端的 LIMIT 切过一刀，那一刀可能劈开了一毫秒（见 KDoc）。
+        // 此后无论下一页是空页还是不满页，都说不出「追到了尾巴」。
+        var chasedFullPage = false
+
+        fun done(at: Long, complete: Boolean) = Result.success(
+            MessageIncrement(messages = byId.values.sortedWith(MessageOrder), cursor = at, complete = complete),
+        )
+
+        var page = 0
+        while (page < maxPages.coerceAtLeast(1)) {
+            page++
+            val raw = apiCall { api.listMessages(sessionId, size, before = null, platform = platform, after = cursor) }
+                .getOrElse { return@withContext Result.failure(it) }
+            val paged = toPagedMessages(raw, size)
+            // 空页有两种含义，客户端分不出来：第一页就空 = 真的没有新的；拿过一整页之后空 = 可能还有
+            // 同一毫秒的几条卡在游标上（服务端只给严格大于）。后者只能说「没追完」。
+            if (paged.messages.isEmpty()) {
+                return@withContext done(cursor, complete = !chasedFullPage)
+            }
+            // 去重只是防御：严格 `>` 下相邻两页不可能重叠（下一页只要 > 本页最新那条）。
+            paged.messages.forEach { byId[it.id] = it }
+            val newest = paged.newestCreatedAt ?: return@withContext done(cursor, complete = false)
+            // 不满页只说明「> cursor 的行就这么多了」，对切点那一毫秒一无所知 —— 与空页档同一个洞，
+            // 同样是拿过整页之后就不作数。
+            if (!paged.hasMore) return@withContext done(newest, complete = !chasedFullPage)
+            cursor = newest
+            chasedFullPage = true
+        }
+        done(cursor, complete = false)
+    }
+
     /**
      * 编辑单条消息（D3，契约 §1 行 6a）：`PATCH /api/v1/messages/{id}`，成功返回**服务端更新后的
      * 完整消息 DTO**。
@@ -152,6 +236,15 @@ class MessageRepository(
         /** 搜索结果一页的条数：命中项要一条条读，比历史分页小一些更好翻。 */
         const val DEFAULT_SEARCH_PAGE_SIZE = 30
 
+        /**
+         * [loadIncrement] 一次最多翻几页（500 条）。
+         *
+         * 这个上限只为一件事存在：一次**后台**的顺手对齐不该翻十几页。越过它就说明积压已经多到
+         * 「增量」不再便宜，那时整表（`GET /sessions` 一次拿回权威的 `unreadCount` 与预览）
+         * 反而更划算——调用方据此回落，见 `SessionsViewModel.flushPendingIncrements`。
+         */
+        const val MAX_INCREMENT_PAGES = 10
+
         private val EMPTY_PAGE = PagedMessages(
             messages = emptyList(),
             hasMore = false,
@@ -190,3 +283,18 @@ private fun toPagedMessages(
         newestCreatedAt = ascending.lastOrNull()?.createdAt,
     )
 }
+
+/**
+ * [MessageRepository.loadIncrement] 的结论：升序增量消息 + 推进后的游标 + 有没有真的追到尾巴。
+ *
+ * [complete] 为 `false` 时 [messages] 仍是**已拿到的全部**（不丢），但调用方不能把它当成
+ * 「这之后就没有了」——未读面上那种情况要回落到整表，见 `SessionsViewModel.flushPendingIncrements`。
+ *
+ * 放在这里而不是 `PagedMessages.kt`：`PagedMessages` 是纯分页形状（一页的元数据），
+ * 这个类型是 [MessageRepository] 翻页循环的产物，跟着它的生产者走。
+ */
+data class MessageIncrement(
+    val messages: List<HistoryMessageDto>,
+    val cursor: Long,
+    val complete: Boolean,
+)

app/src/main/kotlin/top/yeij/cyrene/data/repository/VoiceStore.kt

@@ -0,0 +1,164 @@
+package top.yeij.cyrene.data.repository
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiErrorMapper
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.MediaApi
+import top.yeij.cyrene.domain.chat.DocumentAttachments
+import top.yeij.cyrene.domain.chat.VoiceAudio
+import top.yeij.cyrene.domain.chat.readBounded
+import top.yeij.cyrene.domain.chat.voiceMediaUrl
+import java.io.File
+
+/** 本端一次读得下、也放得动的语音副本上限，超过就如实说「放不了」（见 [VoiceTooLargeException]）。 */
+class VoiceTooLargeException : Exception("voice copy too large")
+
+/** 服务端只给了相对路径，而本端目前拿不到一个能接上去的服务器地址（未登录 / 地址为空）。 */
+class VoiceUrlUnavailableException : Exception("voice media url unavailable")
+
+/**
+ * 语音副本的取字节层（`GET /api/v1/media/{name}` 的第一个调用方）。
+ *
+ * 与 [DocumentRepository] 同一个形状：响应不是信封（就是音频本身），所以不用 `apiCall`——
+ * 成功即读字节，失败才走 [ApiErrorMapper]（`404 media_not_found` / `401`）。
+ * `@Streaming` 的响应体必须由调用方关闭，[okhttp3.ResponseBody.use] 在这里收口。
+ *
+ * [url] 由调用方拼好（服务端给的**相对路径** + 当前服务器地址，纯函数
+ * [voiceMediaUrl]）：本层**不自己拼路径**——契约把那条路径定成服务端唯一的派生字段。
+ * 因此这里也不做形态校验：拼不出可信地址的调用方根本不会走到这里（[VoiceStore] 先判）。
+ */
+class MediaRepository(
+    private val api: MediaApi,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    /**
+     * 取回一条语音副本的字节。
+     *
+     * 读到超过 [MAX_VOICE_BYTES] 就判 [VoiceTooLargeException]：语音副本本就不该大，
+     * 而「一次读进内存」这条路上必须有一把尺子（与文档 / 图片同一个做法）。
+     * **0 字节不算成功**——那会让下一次播放「读缓存命中」一份什么都没有的文件。
+     */
+    suspend fun download(url: String): Result<ByteArray> = withContext(dispatcher) {
+        try {
+            val response = api.download(url)
+            val body = response.body()
+            when {
+                response.isSuccessful && body != null -> body.use { stream ->
+                    val bytes = readBounded(stream.byteStream(), MAX_VOICE_BYTES)
+                    when {
+                        bytes == null -> Result.failure(VoiceTooLargeException())
+                        bytes.isEmpty() -> Result.failure(
+                            CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                        )
+
+                        else -> Result.success(bytes)
+                    }
+                }
+
+                // 2xx 却没有响应体：与 apiCall 同一口径，判解析失败而不是「拿到了空文件」。
+                response.isSuccessful -> Result.failure(
+                    CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                )
+
+                else -> Result.failure(
+                    CyreneException(ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string())),
+                )
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
+        }
+    }
+
+    private companion object {
+        /**
+         * 上限取附件那一把尺子（20 MB）：语音副本远小于它，而这里要防的只是「一次读进内存」
+         * 这条路上没有上界。**不新造一个数字**——多一个自定义上限就多一处会漂移的口径。
+         */
+        val MAX_VOICE_BYTES: Long = DocumentAttachments.MAX_FILE_BYTES
+    }
+}
+
+/**
+ * 语音副本的「取字节 + 落盘缓存」层（播放前那一步的**唯一**取数入口）。
+ *
+ * ## 缓存：`<cacheDir>/media/`，复用 [DocumentCache] 的三条规则
+ * - **名字规则 / 命中判定 / 原子落盘**全部复用 [DocumentCache]（同一条 `isSafeName`、
+ *   `isHit`（非空才算命中）、`write`（先写 `.part` 再改名））——只在缓存根下换一个目录名。
+ * - **特意不落进 `documents/`**：那个目录是 `FileProvider`（`res/xml/file_paths.xml`）**唯一**
+ *   暴露出去的根，「用其它应用打开 / 保存到下载目录」两条出口都从它取文件。语音本片只做
+ *   收 / 放，不提供「交给别的 App」这条出口，所以**不把暴露面扩大一个字节**。
+ * - 目录名是 `media`，与 `voice.url` 里的 `/api/v1/media/` 同源，便于排查时对得上号。
+ *
+ * ## 为什么缓存（而不是每次现下）
+ * 服务端副本是**内容寻址**的（名字由内容决定）+ `Cache-Control: private, max-age=86400,
+ * immutable` ⇒ 同一个名字的字节永不改变，「文件在且非空」就是永远有效的命中。重复播放因此
+ * **一个请求都不发**，离线也能重听刚听过的那条。代价是缓存目录里多占几十 KB~几百 KB 一份，
+ * 而它在 `cacheDir` 下：系统需要空间时可以回收，本端被回收之后下次播放重新下载（**不是**错误）。
+ *
+ * ## 它不做什么
+ * 不拼路径（[voiceMediaUrl] 在调用前判，拿不到可信地址就直接失败）、不做形态校验、不猜 MIME、
+ * **不拿 `size` 反算时长**（时长只认服务端给的 `durationMs`）。
+ */
+class VoiceStore(
+    /**
+     * 取一条副本的字节（未命中缓存时调一次）。
+     *
+     * 收成一个 lambda 而不是直接收 [MediaRepository]：本类因此可以在单测里用临时目录 + 假下载器
+     * 跑完，不必造一个 HTTP 替身（与 [ImageCacheStore] 的 `download` 参数同一手法）。
+     * 生产路径上它就是 `container.mediaRepository::download`。
+     */
+    private val download: suspend (String) -> Result<ByteArray>,
+    private val cacheDir: File,
+    private val baseUrlProvider: () -> String,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    /**
+     * 取这条语音的字节并确保它已落进缓存；返回**可直接交给 `MediaPlayer` 的那份文件**。
+     *
+     * 顺序是刻意的：**先拼地址、再查缓存**。地址拼不出来（未登录 / 地址为空）就如实失败，
+     * 绝不因为「本地碰巧缓存过」而放行——那会让一条本端根本没有服务器归属的语音照旧能放，
+     * 而调用方拿不到任何异常信号。
+     */
+    suspend fun load(audio: VoiceAudio): Result<File> = withContext(dispatcher) {
+        val url = voiceMediaUrl(audio.url, baseUrlProvider())
+            ?: return@withContext Result.failure(VoiceUrlUnavailableException())
+        // ⚠️ 刻意**不用** `DocumentCache.fileFor`：那个函数的缓存根写死成 `documents/`
+        // （FileProvider 那一层），传别的目录进去会拼成 `<cacheDir>/media/documents/<name>`。
+        // 这里只用它的**名字判据**，路径自己拼。
+        if (!DocumentCache.isSafeName(audio.name)) {
+            // 名字不安全 = 服务端给了一个本端不敢拼路径的名字；判解析失败，绝不退回别的名字。
+            return@withContext Result.failure(
+                CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+            )
+        }
+        val file = File(directory(cacheDir), audio.name)
+        if (DocumentCache.isHit(file)) return@withContext Result.success(file)
+
+        val bytes = download(url).getOrElse { return@withContext Result.failure(it) }
+        try {
+            DocumentCache.write(file, bytes)
+            Result.success(file)
+        } catch (_: Exception) {
+            // 写不进去时把可能的残留清掉，再如实报「缓存不可用」——**绝不**退回「把字节直接喂给
+            // 播放器」那条路：那需要另一条落盘位置，而缓存目录写不进去时多半写得进的地方也没有。
+            file.delete()
+            Result.failure(DocumentCacheUnavailableException())
+        }
+    }
+
+    companion object {
+        /** 缓存根下的目录名（与 `voice.url` 里的 `/api/v1/media/` 同源，便于对号）。 */
+        const val DIRECTORY_NAME: String = "media"
+
+        /** 语音副本的缓存目录：`<cacheDir>/media`。 */
+        fun directory(cacheDir: File): File = File(cacheDir, DIRECTORY_NAME)
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/data/voice/SpeechClient.kt

@@ -0,0 +1,219 @@
+package top.yeij.cyrene.data.voice
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import top.yeij.cyrene.core.auth.NoUnauthorizedPolicy
+import top.yeij.cyrene.core.auth.UnauthorizedPolicy
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.data.api.ApiErrorMapper
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.SpeechApi
+import top.yeij.cyrene.data.api.SpeechRequestDto
+import top.yeij.cyrene.data.repository.DocumentCache
+import top.yeij.cyrene.data.repository.DocumentCacheUnavailableException
+import top.yeij.cyrene.data.repository.VoiceStore
+import top.yeij.cyrene.domain.chat.DocumentAttachments
+import top.yeij.cyrene.domain.chat.readBounded
+import java.io.File
+import java.security.MessageDigest
+
+/** 服务端回的字节**不是**一段 WAV（200 却回了 JSON 信封 / HTML 错误页 / 别的东西）。 */
+class SpeechNotAudioException : Exception("speech response is not wav")
+
+/**
+ * 一次 TTS 请求的**字节嗅探**：真的是 RIFF/WAVE 吗？
+ *
+ * 契约（api-client.md §4.1 行 561 的旁注、§1.2 U6）只说「产物恒为 WAV」，**没有**承诺
+ * `Content-Type` 是什么，并明写「不要照抄 `Content-Type`」。所以判据只能落在字节上：
+ * 头 4 字节 `RIFF` + 偏移 8 起的 4 字节 `WAVE`（RIFF 容器里夹一段 `fmt ` 那种标准布局）。
+ *
+ * 为什么要判：`MediaPlayer` 拿到非音频字节时抛的是它自己那套 `setDataSource` 异常，
+ * 与本端「取字节失败」的语义完全不同；而 200 回 JSON 信封恰恰是**最可能**的一种
+ * 「网关/反代把错误包了一层」的形态 —— 提前拦在这里，失败就被如实归到「解析失败」那一档，
+ * 而不是在播放器里炸成一个没人认识的东西。
+ */
+fun isWavBytes(bytes: ByteArray): Boolean =
+    bytes.size >= WAV_HEADER_BYTES &&
+        bytes[0] == 'R'.code.toByte() &&
+        bytes[1] == 'I'.code.toByte() &&
+        bytes[2] == 'F'.code.toByte() &&
+        bytes[3] == 'F'.code.toByte() &&
+        bytes[8] == 'W'.code.toByte() &&
+        bytes[9] == 'A'.code.toByte() &&
+        bytes[10] == 'V'.code.toByte() &&
+        bytes[11] == 'E'.code.toByte()
+
+/** RIFF 头里本端要看的那几个字节都在前 12 个之内。 */
+private const val WAV_HEADER_BYTES = 12
+
+/** 本端一次读得下、也放得动的合成音频上限（与语音副本同一把尺子：附件上限 20 MB）。 */
+private val MAX_SPEECH_BYTES: Long = DocumentAttachments.MAX_FILE_BYTES
+
+/**
+ * 「把一段文字念出来」的取字节层（`POST /api/v1/audio/speech` 的唯一调用方，契约 api-client.md
+ * §1.2 **U6**，v0.96 增量 + v0.97 补写）。
+ *
+ * ## 凭据：只走 Bearer，不设 API Key
+ * 服务端是 owner-only 的**双凭据门**（Bearer owner JWT **或** `X-API-Key`，两个分支落到同一个
+ * `authorize(RoleOwner)`）。本端只走前者：令牌由 [ApiClientFactory.create] 挂在 OkHttpClient 上的
+ * `AuthInterceptor` 注入，并顺带享受「带令牌仍 401 ⇒ 单飞续期并重试一次」。
+ * 主人 2026-10-26 拍板**不加 API Key 输入框** —— 那会多一份要保管、要轮换、要泄漏的凭据，
+ * 而本端本来就已经有 owner 会话。
+ *
+ * ## 发音人从哪来：`sessionId`，不是 `voice`
+ * 契约里 `voice` **接受但不生效**、`format` **不生效**。真正决定发音人的是 `sessionId` 那条会话的
+ * **生效人格**（会话绑定 → 全局默认 → 服务端配置的 default）。所以 [speak] 一定要拿到当前会话 id
+ * ——**省略它不等于没有角色**，只是让服务端退到全局默认。
+ *
+ * ## 缓存：`<cacheDir>/media/tts_<hash>.wav`，同一段文字一个请求都不发第二次
+ * 名字按 **(baseUrl, sessionId, text)** 内容寻址（sha256 前 32 位十六进制），复用 [DocumentCache] 的
+ * 三条规则（`isSafeName` / `isHit` / 原子 `write`），目录复用 [VoiceStore.directory]（`media/`，
+ * 与 `voice.url` 的 `/api/v1/media/` 同源，排查时对得上号；且它**不在** FileProvider 暴露的
+ * `documents/` 根下，不扩大暴露面一个字节）。
+ *
+ * `baseUrl` 进哈希是 P2-2 的修法：换一台服务器后，同一个 `(sessionId, text)` 在那边可能是**另一个
+ * 声音**（人格映射 / 发音人 / 合成实现都是那台服务器的），命中上一台合成的那份 WAV 就是念错人。
+ *
+ * ⚠️ 与语音副本的缓存**有一处关键差别**：副本的名字由服务端按内容决定 ⇒ 命中永不失效；而这里的
+ * 名字由**请求参数**决定，服务端换了发音人 / 换了合成实现之后，同一段文字应该能念出不一样的声音。
+ * 因此这里把 `tts_` 前缀留成「本端合成缓存」的标记，命中判定仍用 [DocumentCache.isHit]
+ * （非空才算）——它是 `cacheDir` 下的东西，系统随时可回收，被回收之后下次朗读重新请求，
+ * **不是**错误。
+ *
+ * ## 错误怎么分类
+ * 非 2xx 一律走 [ApiErrorMapper]（`401` ⇒ [CyreneError.Unauthorized]，其余 ⇒
+ * [CyreneError.Server] 且**保留服务端那句 `code`**——`tts_persona_unmapped` /
+ * `tts_no_character` 这两档的文案完全不同，折成一句话就说不清了）。
+ * 分类成「柔和提示」还是「明确降级」是纯函数的事，在
+ * [top.yeij.cyrene.domain.chat.ttsFailureOf] 里，本类不做产品判断。
+ *
+ * @param baseUrlProvider 每次现读服务器地址（换服务器 ⇒ 客户端重建，与 `AppContainer` 同一纪律）。
+ * @param apiFactory 按 baseUrl 造 [SpeechApi]；收成 lambda 是为了单测能塞一个直连本地 HTTP 替身的
+ *   实例，而不必造一整套依赖注入。
+ */
+class SpeechClient(
+    private val baseUrlProvider: () -> String,
+    private val tokenProvider: () -> String? = { null },
+    private val unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
+    private val cacheDir: File,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+    private val apiFactory: (String) -> SpeechApi = { baseUrl ->
+        ApiClientFactory.create(
+            baseUrl,
+            SpeechApi::class.java,
+            tokenProvider,
+            unauthorizedPolicy,
+        )
+    },
+) {
+
+    /** 按 baseUrl 缓存 Retrofit 实例（换地址才重建），与 `AppContainer.mediaApi` 同一手法。 */
+    private var cachedApi: SpeechApi? = null
+    private var cachedBaseUrl: String? = null
+
+    private fun api(): SpeechApi {
+        val baseUrl = baseUrlProvider()
+        val cached = cachedApi
+        if (cached != null && cachedBaseUrl == baseUrl) return cached
+        return apiFactory(baseUrl).also {
+            cachedApi = it
+            cachedBaseUrl = baseUrl
+        }
+    }
+
+    /**
+     * 把 [text] 合成成一段 WAV 并落盘，返回**可直接交给 `MediaPlayer`** 的那份文件。
+     *
+     * [sessionId] 是当前会话 id：它决定发音人（见类 KDoc）。传 `null` 表示「本端不知道是哪个会话」，
+     * 服务端会退到全局默认人格 —— 调用方**不要**为了让字段好看而编一个 id 出来。
+     */
+    suspend fun speak(text: String, sessionId: String?): Result<File> = withContext(dispatcher) {
+        val trimmed = text.trim()
+        if (trimmed.isEmpty()) {
+            // 服务端对空 text 回 `400`；本端连请求都不发（省一次往返，也省一次无意义的失败）。
+            return@withContext Result.failure(
+                CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+            )
+        }
+        val file = File(VoiceStore.directory(cacheDir), cacheName(trimmed, sessionId, baseUrlProvider()))
+        if (DocumentCache.isHit(file)) return@withContext Result.success(file)
+
+        try {
+            val response = api().speech(SpeechRequestDto(text = trimmed, sessionId = sessionId))
+            val body = response.body()
+            when {
+                response.isSuccessful && body != null -> body.use { stream ->
+                    val bytes = readBounded(stream.byteStream(), MAX_SPEECH_BYTES)
+                    when {
+                        // 超过上限：本端一次读不下（合成音频远小于它，走到这里说明对面不对劲）。
+                        bytes == null -> Result.failure(SpeechNotAudioException())
+                        // 0 字节：与 MediaRepository 同一口径，判解析失败而不是「拿到一段静音」。
+                        bytes.isEmpty() -> Result.failure(
+                            CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                        )
+                        // 200 却不是 WAV：**绝不**把 JSON / HTML 喂给 MediaPlayer（见 isWavBytes）。
+                        !isWavBytes(bytes) -> Result.failure(SpeechNotAudioException())
+                        else -> cache(file, bytes)
+                    }
+                }
+
+                // 2xx 却没有响应体：与 apiCall 同一口径。
+                response.isSuccessful -> Result.failure(
+                    CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)),
+                )
+
+                else -> Result.failure(
+                    CyreneException(
+                        ApiErrorMapper.fromHttp(response.code(), response.errorBody()?.string()),
+                    ),
+                )
+            }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Result.failure(CyreneException(ApiErrorMapper.fromThrowable(e)))
+        }
+    }
+
+    private fun cache(file: File, bytes: ByteArray): Result<File> = try {
+        DocumentCache.write(file, bytes)
+        Result.success(file)
+    } catch (_: Exception) {
+        // 写不进去时把可能的残留清掉，再如实报「缓存不可用」——绝不退回「把字节留在内存里等播放器
+        // 读」那条路：MediaPlayer 只吃路径，而缓存目录写不进去时多半写得进的地方也没有。
+        file.delete()
+        Result.failure(DocumentCacheUnavailableException())
+    }
+
+    private companion object {
+        /** 合成缓存的名字前缀：与语音副本（服务端内容寻址名）在同一目录里区分开。 */
+        const val NAME_PREFIX = "tts_"
+
+        /** sha256 前 32 位十六进制，与服务端存储名 / [DocumentCache.localName] 同一长度。 */
+        const val NAME_HEX_LENGTH = 32
+
+        /**
+         * 缓存名 = `tts_<sha256(baseUrl \n sessionId \n text)[:32]>.wav`。
+         *
+         * 带上 `sessionId` 是**必须的**：发音人由会话的生效人格决定，不同会话的同一段文字
+         * 可能是两个声音。带上 `baseUrl` 同样是必须的：换一台服务器（同一个会话 id、同一段文字）
+         * 命中的会是**上一台服务器**合成的那份 WAV —— 那一台上的人格映射 / 发音人 / 合成实现
+         * 可能完全不同，播出来是别人的声音。缓存是 `cacheDir` 下的东西、系统随时可回收，
+         * 换地址后重新请求一次的代价远小于「念错了声音却看不出为什么」。
+         *
+         * 地址先 `trimEnd('/')` 归一：`http://a/` 与 `http://a` 是同一台服务器，不该分成两份缓存。
+         * `\n` 做分隔符，免得 `(a, "bc")` 与 `(ab, "c")` 撞成同一个名字。
+         */
+        fun cacheName(text: String, sessionId: String?, baseUrl: String): String {
+            val digest = MessageDigest.getInstance("SHA-256")
+                .digest(
+                    "${baseUrl.trimEnd('/')}\n${sessionId.orEmpty()}\n$text".toByteArray(Charsets.UTF_8),
+                )
+            val hex = digest.joinToString("") { "%02x".format(it) }.take(NAME_HEX_LENGTH)
+            return NAME_PREFIX + hex + ".wav"
+        }
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/data/voice/VoiceRecorder.kt

@@ -0,0 +1,219 @@
+package top.yeij.cyrene.data.voice
+
+import android.annotation.SuppressLint
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import java.io.ByteArrayOutputStream
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.domain.chat.VoiceClip
+
+/** 录音机的两个可见态（界面只认这两个）。 */
+sealed interface VoiceRecorderState {
+
+    /** 没在录。 */
+    data object Idle : VoiceRecorderState
+
+    /**
+     * 正在录。
+     *
+     * [elapsedMs] 由**已收到的字节数**反算（[VoiceClip.durationMillisOf]），不是另起一个计时器——
+     * 两个时钟一定会漂，而屏幕上那个数字必须与最终发出去的音频长度一致。
+     *
+     * [reachedLimit] = 已经录满 [VoiceClip.MAX_RECORDING_MILLIS]，此后的字节被**丢弃**（不是
+     * 悄悄截断已经收到的部分）。UI 看到它应当立刻收尾发送，见本类注释。
+     */
+    data class Recording(val elapsedMs: Int, val reachedLimit: Boolean) : VoiceRecorderState
+}
+
+/**
+ * 麦克风录音机：`AudioRecord` 收 PCM → 交给 [VoiceClip] 封 WAV（本类不碰封装，见那里的 KDoc）。
+ *
+ * ## 为什么自己持有一个作用域，而不复用调用方的 `rememberCoroutineScope`
+ * 读循环必须活到 [stop] 真的收尾：调用方的组合一旦被丢弃（转屏 / 退到后台那一刻重建），
+ * 挂在它上面的协程会被取消，而 USB/内置麦克风已经交给系统的那一块缓冲就再也取不回来——
+ * 用户按下停止却拿到一个缺尾的片段。所以读循环跑在这个类自己的 `SupervisorJob + IO` 上，
+ * 由 [release] 明确收掉。
+ *
+ * ## 满了不自动发送，只置位
+ * 到 [VoiceClip.MAX_RECORDING_MILLIS] 时把 [VoiceRecorderState.Recording.reachedLimit] 置真、
+ * 继续把多余的字节丢掉。**发送时机由 UI 决定**（它要先把「正在录」那一行换回输入栏，再交给
+ * VM）：本类不知道 VM 也不发帧，这条边界让它在单测里不必造一个 VM。
+ *
+ * ## 权限
+ * 调用方必须先拿到 `RECORD_AUDIO`（运行时权限）。本类**不申请**也不检查：`AudioRecord`
+ * 在没权限时会抛 `SecurityException`，[start] 把它连同「设备不支持 / 初始化失败」一起收敛成
+ * `false`，由 UI 按「这台设备现在开不了麦克风」说一句，**绝不静默**。
+ */
+class VoiceRecorder(
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    private val scope = CoroutineScope(SupervisorJob() + dispatcher)
+
+    private val _state = MutableStateFlow<VoiceRecorderState>(VoiceRecorderState.Idle)
+
+    /** 当前录音状态（界面据此显示「录音中 0:07」）。 */
+    val state: StateFlow<VoiceRecorderState> = _state.asStateFlow()
+
+    private var record: AudioRecord? = null
+
+    /** 收集到的 PCM；只有 [start] 建、[stop]/[cancel] 取走或丢掉。 */
+    private var collected: ByteArrayOutputStream? = null
+
+    private var reader: Job? = null
+
+    /**
+     * 录音代次：每次 [start] 自增。
+     *
+     * 只服务一件事：读循环的 `finally` 里**只在还属于这一代**时才把状态收回 [VoiceRecorderState.Idle]。
+     * 少了它，「取消 → 立刻重录」的窄窗口里，上一轮的收尾会把新那一轮的「录音中」抹成「没在录」，
+     * 而麦克风其实还在收字节——界面上什么都不显示，用户以为自己没在录。
+     */
+    private var generation = 0
+
+    @Volatile
+    private var collecting = false
+
+    /**
+     * 开始录音。
+     *
+     * @return `false` = 这台设备现在起不了麦克风（没有权限 / 设备被占用 / 不支持的采样参数）。
+     *   调用方必须**如实告知**（不得假装在录）。
+     */
+    @SuppressLint("MissingPermission")
+    fun start(): Boolean {
+        if (collecting) return false
+        val minBuffer = AudioRecord.getMinBufferSize(SAMPLE_RATE_HZ, CHANNEL_MASK, ENCODING)
+        if (minBuffer <= 0) return false
+        val recorder = runCatching {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(
+                    AudioFormat.Builder()
+                        .setEncoding(ENCODING)
+                        .setSampleRate(SAMPLE_RATE_HZ)
+                        .setChannelMask(CHANNEL_MASK)
+                        .build(),
+                )
+                // 缓冲给到最小值的两倍：读循环偶尔晚一拍时不至于立刻丢帧。
+                .setBufferSizeInBytes(minBuffer * 2)
+                .build()
+        }.getOrNull() ?: return false
+        if (recorder.state != AudioRecord.STATE_INITIALIZED) {
+            runCatching { recorder.release() }
+            return false
+        }
+        val started = runCatching { recorder.startRecording() }.isSuccess
+        if (!started) {
+            runCatching { recorder.release() }
+            return false
+        }
+        record = recorder
+        val sink = ByteArrayOutputStream(INITIAL_PCM_BYTES)
+        collected = sink
+        collecting = true
+        val current = ++generation
+        _state.value = VoiceRecorderState.Recording(elapsedMs = 0, reachedLimit = false)
+        reader = scope.launch { readLoop(recorder, sink, current) }
+        return true
+    }
+
+    /**
+     * 停止并交出这一段 PCM；`null` = 没有可发的字节（没在录 / 读失败 / 全被丢弃）。
+     *
+     * `suspend` 是刻意的：必须等读循环真的收尾（[reader] 的 `join`）才去读那份缓冲，
+     * 否则最后一块还没写进去就被取走——用户会听到句尾少一截。
+     */
+    suspend fun stop(): ByteArray? {
+        if (!collecting) return null
+        collecting = false
+        reader?.join()
+        reader = null
+        releaseRecorder()
+        _state.value = VoiceRecorderState.Idle
+        val sink = collected ?: return null
+        collected = null
+        return sink.toByteArray().takeIf { it.isNotEmpty() }
+    }
+
+    /** 取消：丢掉已经收到的字节，一个都不发（用户点了「取消」）。 */
+    fun cancel() {
+        collecting = false
+        reader?.cancel()
+        reader = null
+        releaseRecorder()
+        collected = null
+        _state.value = VoiceRecorderState.Idle
+    }
+
+    /** 组合被丢弃时调（等价于 [cancel]：一段没发出去的录音不该在后台继续占着麦克风）。 */
+    fun release() = cancel()
+
+    /**
+     * 读循环：一块一块收进 [sink]，顺手更新已录时长；满了之后**丢字节但不打断录音**
+     * （见类注释「满了不自动发送」）。
+     *
+     * 读出错（`read < 0`）就结束这一次录音：硬件被抢走、设备被拔出都会走到这里，此时
+     * 已经收到的部分仍然有效（[stop] 照常交出它们）。
+     *
+     * @param generation 启动时那一代的编号：收尾只在自己还是「当前这一代」时才改状态。
+     */
+    private suspend fun readLoop(recorder: AudioRecord, sink: ByteArrayOutputStream, generation: Int) {
+        val buffer = ByteArray(READ_BYTES)
+        try {
+            while (collecting) {
+                val read = recorder.read(buffer, 0, buffer.size)
+                if (read < 0) break
+                if (read == 0) continue
+                val used = sink.size()
+                if (used < VoiceClip.MAX_PCM_BYTES) {
+                    sink.write(buffer, 0, minOf(read, VoiceClip.MAX_PCM_BYTES - used))
+                }
+                val elapsed = VoiceClip.durationMillisOf(minOf(sink.size(), VoiceClip.MAX_PCM_BYTES))
+                _state.value = VoiceRecorderState.Recording(
+                    elapsedMs = elapsed,
+                    reachedLimit = elapsed >= VoiceClip.MAX_RECORDING_MILLIS,
+                )
+            }
+        } finally {
+            // 读循环自己结束（出错 / 被取消）时也要把状态收回 Idle，否则界面会永远停在「录音中」。
+            // 只在自己还是当前这一代时才收：否则「取消 → 立刻重录」的窄窗口里，上一轮的收尾
+            // 会把新一轮的「录音中」擦掉。
+            if (generation == this.generation && _state.value is VoiceRecorderState.Recording) {
+                _state.value = VoiceRecorderState.Idle
+            }
+        }
+    }
+
+    /** 把 `AudioRecord` 拆干净（`stop` 在没起录时抛 `IllegalStateException`，所以都包在 `runCatching` 里）。 */
+    private fun releaseRecorder() {
+        val current = record ?: return
+        record = null
+        runCatching { current.stop() }
+        runCatching { current.release() }
+    }
+
+    private companion object {
+        val SAMPLE_RATE_HZ: Int = VoiceClip.SAMPLE_RATE_HZ
+        const val ENCODING: Int = AudioFormat.ENCODING_PCM_16BIT
+        const val CHANNEL_MASK: Int = AudioFormat.CHANNEL_IN_MONO
+
+        /**
+         * 一次读多少字节：`2048` = 16 kHz 下单声道 16-bit 的 64 ms（1024 帧）。
+         * 比这更小则更新频率过高（每秒几十次状态写），更大则「停止」那一刻的延迟可感。
+         */
+        const val READ_BYTES: Int = 2048
+
+        /** 初始缓冲按 10 秒预分配（够大多数语音，长的那条会自己扩容）。 */
+        val INITIAL_PCM_BYTES: Int = VoiceClip.pcmBytesFor(10_000)
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/data/ws/ChatSocket.kt

@@ -209,15 +209,51 @@ class ChatSocket(
      *   与加入 `scope` 之前**逐字节相同**）；`"current"` = 只取消在跑回合、保留待处理队列。
      *   其它取值原样发出，服务端**定向**回 `error{bad_request}` 且不打断任何会话（本层不预判取值域）。
      *
-     * **调用方只有一处**：`ChatViewModel.interruptRunningTurn()`——它在一条消息真的要走上去**之前**
-     * 按 App 偏好（`InterruptMode`）决定要不要先打断，且**只在会话正忙时**发（判据是纯函数
-     * `interruptScopeForSend`）。默认档「追加队列」与「并行」这一档都恒不发（后者的 `wireScope`
-     * 就是 `null`：并行与打断互斥），所以本方法只服务「打断」这一档。
-     * 返回 false 只有一种原因（WS 未连接）：调用方**静默**并不阻断本次发送，理由见那里的 KDoc。
+     * **调用方有两处，两处都只发 `"current"`**（本端从不发 `all`，见 `devdocs/02` 的 A2 补记）：
+     * 1. `ChatViewModel.interruptRunningTurn()`——它在一条消息真的要走上去**之前**按 App 偏好
+     *    （`InterruptMode`）决定要不要先打断，且**只在会话正忙时**发（判据是纯函数
+     *    `interruptScopeForSend`）。默认档「追加队列」与「并行」这一档都恒不发（后者的 `wireScope`
+     *    就是 `null`：并行与打断互斥），所以本方法只服务「打断」这一档。
+     * 2. `SessionsViewModel.stopGenerating(sessionId)`——抽屉里那一行的「停止」（W52B）：它是一个
+     *    **独立的动作**（不读偏好），停的是**指定会话**正在跑的那一轮。`WsOutbound.Interrupt`
+     *    本来就带 `sessionId`，所以「停某一个会话」这条既有出口表达得了，不需要新帧。
+     *
+     * 返回 false 只有一种原因（WS 未连接）：两处调用方都**静默**，理由见各自的 KDoc。
      */
     fun sendInterrupt(sessionId: String, scope: String? = null): Boolean =
         send(WsOutbound.Interrupt(sessionId = sessionId, scope = scope))
 
+    /**
+     * 发送 `voice_input`（契约 v0.96 §3.15）：一段 base64 音频 + 格式，走与 `chat` 同一条出站通道。
+     *
+     * ## 为什么没有「离线队列」
+     * 文本那条有补发队列（内容只是一小段字符串，留着不贵）；语音的 audio 是**几 MB 的 base64**
+     * 内联在帧里，队列化它等于把这段内存钉在待发状态里，而重连之后服务端到底要不要它、要哪一段
+     * 又都是用户该重新决定的事。所以本层与 [sendChat] 一样：**发不出去就回 `false`**，由
+     * `ChatViewModel` 把这段留在内存里、让用户按「重发」（复用同一个 `clientMsgId`）。
+     *
+     * @param audio base64（单行，`Base64.NO_WRAP`）。
+     * @param format 契约白名单 `wav|mp3|ogg` 之一；本端恒 `"wav"`。
+     * @param deviceId 与 `chat` 帧同一份来源标识。
+     * @param clientMsgId 幂等键：同一段语音重发**必须复用**（否则服务端会把同一句话说两遍）。
+     * @return 未连接 / 写失败返回 `false`。
+     */
+    fun sendVoiceInput(
+        sessionId: String?,
+        audio: String,
+        format: String,
+        deviceId: String?,
+        clientMsgId: String?,
+    ): Boolean = send(
+        WsOutbound.VoiceInput(
+            audio = audio,
+            format = format,
+            sessionId = sessionId,
+            deviceId = deviceId,
+            clientMsgId = clientMsgId,
+        ),
+    )
+
     private fun send(outbound: WsOutbound): Boolean {
         if (_state.value != WsState.Connected) return false
         val socket = webSocket ?: return false

app/src/main/kotlin/top/yeij/cyrene/data/ws/WsEvent.kt

@@ -190,10 +190,19 @@ sealed class WsEvent {
         override val type: String get() = "tool_execution.update"
     }
 
-    /** 工具执行**完成或失败**（契约 v0.50）：`phase:"error"` 即失败。 */
+    /**
+     * 工具执行**完成或失败**（契约 v0.50）：`phase:"error"` 即失败。
+     *
+     * [resultSummary] 是**执行结果摘要**（新契约切片，与回看面 `toolCalls[].resultSummary` 同一份预算：
+     * 已经脱敏、已经截断 ≤500 字符的成品，本端只展示）。它的语义是**缺席即「不知道」**：
+     * 只有这一轮的执行结果**真的拿到了**才在场，失败 / 取消 / 超时 / 未落图时后端**整个键省略**
+     * （且承诺不用空串顶位）。所以 `null` 与 `""` 在本端都读作**不知道**——绝不解成「没有输出」，
+     * 因为那是替服务端下一个它没下的结论。当前服务端**尚未部署**该键 ⇒ 真机上它恒缺席。
+     */
     data class ToolExecutionEnd(
         val tool: String,
         val phase: String,
+        val resultSummary: String? = null,
         val id: String? = null,
         override val turnId: String? = null,
         override val seq: Long? = null,
@@ -459,9 +468,21 @@ sealed class WsEvent {
         override val type: String get() = "session_read"
     }
 
-    /** 主会话（`web` / `web:<uuid>`）消息落库后广播。 */
+    /**
+     * 主会话（`web` / `web:<uuid>`）消息落库后广播。
+     *
+     * [proactive] = **这句话是她主动说的**（v0.72 起，服务端走 IM 桥那条路由时会补发这一帧，
+     * 并在帧上打这个判据）。它此前被本端**丢掉**了：`data` 只解 `message`，而生产 `Json` 是
+     * `ignoreUnknownKeys = true` ⇒ 这个键既没被解、也不会报错，于是「她主动说的话走了落库这条路」
+     * 这件事在客户端**完全不可见**（W53N 的通知判据正是靠它）。
+     *
+     * 判据的两种落点都接受（见 [parse]）：`data.proactive` 与帧壳顶层的 `proactive` 取**或**。
+     * 契约只说「帧顶带它」，没说清是帧壳还是载荷，而**猜错就是整个功能静默失效**——所以两处都读。
+     * 缺席（`false`）= 普通消息，绝不弹通知（主人只批了 proactive 这一档）。
+     */
     data class MessagePersisted(
         val message: HistoryMessageDto?,
+        val proactive: Boolean = false,
         override val turnId: String? = null,
         override val seq: Long? = null,
         override val sessionId: String? = null,
@@ -579,12 +600,30 @@ sealed class WsEvent {
         override val type: String get() = "observability_log"
     }
 
-    /** 语音合成回复（定向回请求连接）。 */
+    /**
+     * 语音合成回复（契约 v0.96 §3.15）：`{audio, format, text, reply, sessionId, deviceId?, provider?}`。
+     *
+     * ## 会话归属**只在 `data` 里**
+     * 契约明写这帧的帧壳**没有** `sessionId`（与其它结构化流帧不同），会话 id 在载荷上。
+     * 所以解析层用既有口径 [`resolveSessionId`] 把它提到 [sessionId] 上：帧壳有就用帧壳，
+     * 否则用 `data` 里那一份。少了这一步，`isForSession` 会把帧**放行给每一个会话的 VM**
+     * （空值 = 无法判定），于是切到别的会话时也会响一段本属于别的会话的语音。
+     *
+     * ## 只定向回发起 `voice_input` 的那条连接、断线不补投
+     * 这是契约的明确边界，不是缺口：本端**不**为它做任何「重连后拉取」的补救（历史靠 REST，
+     * 音频只在这一次连接里存在）。所以这一帧只有「当场播放 / 当场显示」这一种用途。
+     *
+     * [text] 是**转写**（那段音频被识别成什么），[reply] 是**她说的话**——两者的取舍见
+     * `domain.chat.voiceReplyText`。[provider] 是降级信号（`silent` = 这一轮没有真音频），
+     * 判据见 `domain.chat.voiceOutputHasAudio`。
+     */
     data class VoiceOutput(
         val audio: String?,
         val format: String?,
         val text: String?,
         val reply: String?,
+        val deviceId: String? = null,
+        val provider: String? = null,
         override val turnId: String? = null,
         override val seq: Long? = null,
         override val sessionId: String? = null,
@@ -667,7 +706,16 @@ sealed class WsEvent {
             val seq = root["seq"].asStringOrNull()?.toLongOrNull()
             val sessionId = root["sessionId"].asStringOrNull()
             val data = root["data"]?.takeIf { it !is JsonNull }
-            return runCatching { dispatch(type, turnId, seq, sessionId, data) }.getOrNull()
+            val event = runCatching { dispatch(type, turnId, seq, sessionId, data) }.getOrNull()
+                ?: return null
+            // 帧顶那一位 `proactive`（见 [MessagePersisted]）。这一层只对落库帧有意义，载荷里的那一份
+            // 由 [PersistedData] 解出来，两边**取或**：契约写的是「帧顶带它」而没说是帧壳还是载荷，
+            // 而猜错的方向是「功能静默失效」，所以两处都认。
+            return if (event is MessagePersisted && root.frameProactive()) {
+                event.copy(proactive = true)
+            } else {
+                event
+            }
         }
 
         private fun dispatch(
@@ -739,7 +787,7 @@ sealed class WsEvent {
             "tool_execution.update" -> decode<ToolExecutionData>(data)
                 .let { ToolExecutionUpdate(it.tool, it.phase, it.delta, it.id, turnId, seq, sessionId) }
             "tool_execution.end" -> decode<ToolExecutionData>(data)
-                .let { ToolExecutionEnd(it.tool, it.phase, it.id, turnId, seq, sessionId) }
+                .let { ToolExecutionEnd(it.tool, it.phase, it.resultSummary, it.id, turnId, seq, sessionId) }
             "stream_chunk" -> StreamChunk(decode<StreamChunkData>(data).delta, turnId, seq, sessionId)
             "stream_end" -> decode<StreamEndData>(data)
                 .let { StreamEnd(it.stopReason, it.steps, it.error, turnId, seq, sessionId) }
@@ -840,8 +888,15 @@ sealed class WsEvent {
             // 已读游标（D4 §3.9）：会话归属只在帧壳上（data 只有 readAt）。
             "session_read" -> decode<SessionReadData>(data)
                 .let { SessionRead(resolveSessionId(sessionId, ""), it.readAt, turnId, seq) }
-            "message_persisted" -> decode<PersistedData>(data)
-                .let { MessagePersisted(it.message, turnId, seq, sessionId ?: it.message?.sessionId) }
+            "message_persisted" -> decode<PersistedData>(data).let {
+                MessagePersisted(
+                    message = it.message,
+                    proactive = it.proactive.asTrue(),
+                    turnId = turnId,
+                    seq = seq,
+                    sessionId = sessionId ?: it.message?.sessionId,
+                )
+            }
             "channel_persisted" -> decode<PersistedData>(data)
                 .let { ChannelPersisted(it.message, turnId, seq, sessionId ?: it.message?.sessionId) }
             // 消息编辑（D3 §3.8）：`data` **就是**编辑后的完整消息 DTO——**没有** `message`
@@ -853,8 +908,20 @@ sealed class WsEvent {
             // 消息删除（D3 §3.8）：载荷只有 id，会话归属**只在帧壳**上（缺席时上层按全局唯一 id 兜底）。
             "message_deleted" -> decode<DeletedData>(data)
                 .let { MessageDeleted(it.id, turnId, seq, sessionId) }
-            "voice_output" -> decode<VoiceOutputData>(data)
-                .let { VoiceOutput(it.audio, it.format, it.text, it.reply, turnId, seq, sessionId) }
+            "voice_output" -> decode<VoiceOutputData>(data).let {
+                VoiceOutput(
+                    audio = it.audio,
+                    format = it.format,
+                    text = it.text,
+                    reply = it.reply,
+                    deviceId = it.deviceId,
+                    provider = it.provider,
+                    turnId = turnId,
+                    seq = seq,
+                    // 帧壳**没有** sessionId（契约 v0.96），归属在 data 里 ⇒ 走既有口径提到帧上。
+                    sessionId = resolveSessionId(sessionId, it.sessionId),
+                )
+            }
             // 她主动说的话（v0.72）。帧壳**没有** `sessionId`（服务端不设），与会话归属有关的一切
             // 都在载荷里（落库行 id / 时间戳）+ 消费方自己钉「主会话」这条事实，见 [ProactiveMessage]。
             "proactive_message" -> decode<ProactiveData>(data).let {
@@ -922,6 +989,22 @@ private fun JsonElement?.asStringOrNull(): String? {
     return primitive.content
 }
 
+/**
+ * 帧壳顶层的 `proactive` 是否为真。
+ *
+ * 只认**字面量** `true`（布尔或字符串 `"true"`），其余（键缺席、`false`、`JsonNull`、数字、对象）
+ * 一律按假——这个键的方向必须偏「不打扰」：判错成真会给一条普通消息弹出通知，而主人只批了
+ * proactive 那一档；判错成假的最多是她主动说的话没弹通知（不打扰人，也不撒谎）。
+ */
+private fun JsonObject.frameProactive(): Boolean = this["proactive"].asTrue()
+
+/**
+ * `proactive` 那个键的**宽容**读法（只认字面 `true`；`JsonNull` / 别的形状一律假）。
+ * 帧壳与载荷两处共用这一份口径，免得同一个键在两处各判一次、各自漂移。
+ */
+private fun JsonElement?.asTrue(): Boolean =
+    (this as? JsonPrimitive)?.content?.toBooleanStrictOrNull() == true
+
 @Serializable
 private data class IndexData(val index: Int = 0)
 
@@ -939,6 +1022,10 @@ private data class ToolCallData(val id: String = "", val index: Int = 0, val del
  * `id` 在 provider 未给时**整个键省略**，`delta` 只在 `update` 且非空时出现。
  * 刻意**不复用** [ToolCallData]：那是 `tool_call.*` 的形状，真的有 `index`；这三帧没有，
  * 也没有 `streamId`（它们不属于某一次模型流）。
+ *
+ * [resultSummary] 只由 `.end` 携带（后端在新契约切片里只补了 `.end`）。它放在这份共用载荷上
+ * 是因为三帧形状同源、共用一个 DTO；`.start` / `.update` 即便被塞了这个键也**不读**
+ * （它们的领域事件上根本没有这个字段），所以契约没变宽——变宽的只是「多一个键不再算坏帧」。
  */
 @Serializable
 private data class ToolExecutionData(
@@ -946,6 +1033,7 @@ private data class ToolExecutionData(
     val phase: String = "",
     val id: String? = null,
     val delta: String = "",
+    val resultSummary: String? = null,
 )
 
 @Serializable
@@ -1037,8 +1125,24 @@ private data class ChatDuplicateData(
 @Serializable
 private data class SessionReadData(val readAt: Long = 0L)
 
+/**
+ * `message_persisted` / `channel_persisted` 载荷：`{message:{…}}`。
+ *
+ * [proactive] 是「这句话是她主动说的」（见 [WsEvent.MessagePersisted]）。它此前**不在**这里，
+ * 于是被 `ignoreUnknownKeys = true` 静静吃掉——这正是 W53N 要修的那一条：判据键读不回来，
+ * 「她主动说的话」在客户端就只剩 `proactive_message` 那一条路可见。
+ *
+ * ⚠️ 声明成 [JsonElement] 而不是 `Boolean` 是**修一类能把整帧弄没的解码缺陷**（同
+ * [ProactiveData.timestamp] 那条教训）：契约没说这个键的类型，而线上只要给的是 `"true"` 这种
+ * 字符串形状，`Boolean` 解码就会抛、被 `parse` 的 `runCatching` 吞成 `null` ⇒ **整帧消失**，
+ * 连普通消息的落库广播都跟着受影响。收成元素之后按字面量读（见 [asTrue]），一个判据键从此
+ * 不可能让一整类帧消失。
+ */
 @Serializable
-private data class PersistedData(val message: HistoryMessageDto? = null)
+private data class PersistedData(
+    val message: HistoryMessageDto? = null,
+    val proactive: JsonElement? = null,
+)
 
 /**
  * `message_deleted` 载荷（§3.8）：`{id}`。缺键 / 空串解成空 `id`，上层据此整帧跳过
@@ -1055,12 +1159,22 @@ private data class TracePushData(val spans: List<AdminTraceSpanDto> = emptyList(
 @Serializable
 private data class LogPushData(val entries: List<AdminLogEntryDto> = emptyList())
 
+/**
+ * `voice_output` 载荷（契约 v0.96 §3.15）：`{audio, format, text, reply, sessionId, deviceId?, provider?}`。
+ *
+ * `sessionId` 在这里**不是可选的**（契约「帧壳没有 sessionId（在 data 里）」），但解成缺省空串
+ * 并交给 [WsEvent.resolveSessionId]：坏帧（真没给）时宁可退化成「无法判定」（放行、由消费方
+ * 兜底），也不把整帧按坏帧丢掉——丢了就是「她回了语音但屏幕上什么都没有」。
+ */
 @Serializable
 private data class VoiceOutputData(
     val audio: String? = null,
     val format: String? = null,
     val text: String? = null,
     val reply: String? = null,
+    val sessionId: String = "",
+    val deviceId: String? = null,
+    val provider: String? = null,
 )
 
 /**

app/src/main/kotlin/top/yeij/cyrene/data/ws/WsOutbound.kt

@@ -105,12 +105,26 @@ sealed interface WsOutbound {
         }
     }
 
-    /** `voice_input`：`{audio?, format?, text?, sessionId?}`。 */
+    /**
+     * `voice_input`：`{audio?, format?, text?, sessionId?, deviceId?, clientMsgId?}`（契约 v0.96 §3.15）。
+     *
+     * 五个键里 [audio] / [format] 是我们**总要给**的（一段 WAV 的 base64 + `"wav"`，见
+     * `domain.chat.VoiceClip`）；[text] 只有本端**自己做过转写**时才给（给了服务端就跳过 STT），
+     * 本端不做本地转写 ⇒ 恒省略。
+     *
+     * [clientMsgId] 与 `chat` 帧**同形同语义**：同一个非空值服务端只承认第一条，重复到达回
+     * `chat_duplicate`、不再落库不再起回合。所以「这一段没发出去、用户点重发」必须**复用**
+     * 同一个键（见 `domain.chat.voiceClientMsgIdFor`），换新键就是让服务端把同一句话再答一遍。
+     *
+     * [deviceId] 的取值与 `chat` 帧同一份（`ChatViewModel.DEVICE_ID`）：服务端据此标记来源。
+     */
     data class VoiceInput(
         val audio: String? = null,
         val format: String? = null,
         val text: String? = null,
         val sessionId: String? = null,
+        val deviceId: String? = null,
+        val clientMsgId: String? = null,
         override val reqId: String? = null,
     ) : WsOutbound {
         override val type: String get() = "voice_input"
@@ -120,6 +134,8 @@ sealed interface WsOutbound {
             format?.let { put("format", it) }
             text?.let { put("text", it) }
             sessionId?.let { put("sessionId", it) }
+            deviceId?.let { put("deviceId", it) }
+            clientMsgId?.let { put("clientMsgId", it) }
         }
     }
 

app/src/main/kotlin/top/yeij/cyrene/domain/admin/AdminFormat.kt

@@ -130,7 +130,8 @@ data class ConclusionParagraph(val parts: List<ContentPart>)
  *
  * 该字段承载的是**与聊天消息同一套 Web 端 markup**（真实样本里有连写的空 `<p></p>`、
  * `<action>` 等），所以这里**不新增任何 markup 规则**，一律委托 [parse]：
- * 一个 `<p>` 块 = 一段，旁白/动作块依聊天页的归属规则挂在该段内，畸形标签按普通文本回落。
+ * 一个 `<p>` 块 = 一段，旁白/动作块依聊天页的归属规则挂在该段内，畸形标签由 [parse] 兜底
+ * （落单的段落标签剥掉，其余按普通文本回落）。
  * 空段（`<p></p>` 连写产生的空白）不产出模型项——否则界面上会出现成片空行。
  * 段内片段顺序取**渲染顺序**：`head` → 正文 → `tail`（与聊天页气泡上/下方旁白的排布一致）。
  * `null` / 纯空白输入返回空列表。

app/src/main/kotlin/top/yeij/cyrene/domain/chat/MessageEditText.kt

@@ -40,12 +40,21 @@ data class EditableMessage(
 )
 
 /**
- * 已知标签的容差，与 [parse] 逐字对齐（只认解析器真正认识的那几个标签）：
- * `<p>`（可带属性）/ `</p>` / `<action>` / `</action>` / `<narration>` / `</narration>`。
+ * 已知标签的容差，与 [parse] 逐字对齐（只认解析器会**改掉**的那几个标签——行内标签不在其中，
+ * 见下）：`<p>`（可带属性）/ `</p>` / `<action>` / `</action>` / `<narration>` / `</narration>`。
  *
  * 绝不能「见到一个 `<` 就当标记」：用户打的 `1 < 2`、`<div>`、`<3`、`a<b` 都是普通文本，
  * 判成标记就会顺手把它们当标签吃掉——那才是真正的静默丢东西。大小写同样照解析器来：
  * `parse` 只认小写的 `<p>` / `<action>` / `<narration>`，所以 `<P>` 在这里也是普通文本。
+ *
+ * **行内标签（`<b>` / `<code>` …）故意不在**这份容差里：它们是渲染用的标记，但编辑框
+ * 编辑的是**源码本身**，而 `parts`（这一份的来源）是**逐字原文**——所以 `日落 <b>18:35</b>` 在
+ * 编辑框里连 `<b>` 一起显示、也一起保存，这里一个字符都不动它。
+ *
+ * **`<br>` 同理**（契约 v0.89 更正后它是**气泡分隔符**、不是行内标签）：只含 `<br>` 的消息在这份
+ * 容差里仍是纯文本 ⇒ 编辑框里逐字恒等（`<br>` 原样显示、原样保存）；只有原文**另有**已知标记时
+ * 才走剥标记那条路，那时 `<br>` 与 `<p>` / `</p>` 一样被换成它本来就在表示的**空行分隔**
+ * （保存后渲染结果不变，且弹层已经明说标记会被替换）。
  */
 private val KNOWN_TAG_RE = Regex(
     "<p(\\s[^>]*)?>|</p>|<\\s*(action|narration)\\s*>|</\\s*(action|narration)\\s*>",

app/src/main/kotlin/top/yeij/cyrene/domain/chat/PreviewMetadata.kt

@@ -0,0 +1,207 @@
+package top.yeij.cyrene.domain.chat
+
+import java.util.Locale
+
+/**
+ * 预览内容**下方**那一行灰色小字的组装（纯函数，逐档穷举单测在 `PreviewMetadataTest`）。
+ *
+ * ## 这一行是什么，不是什么
+ * 它只放**关于这份文件本身**的格式事实：有多少行、按什么口径解码、多大、多少像素、什么时候拍的。
+ * 它**不是**状态栏、也不是错误提示——「读不到 / 打开失败 / 保存失败」各有自己的去处（芯片行、
+ * 正文区那句人话、弹层下方那行告知），混进来会让这一行读起来像出了什么事。
+ *
+ * ## 纪律：拿不到的项就不出现
+ * 每一项都在**有证据时才产出**，没有证据就整项缺席——**不留占位符、不写「未知」、不写 `--`**。
+ * 一屏小字里堆三个「未知」换不来任何信息，却会让人以为本端查过了。三档证据强度各自成条：
+ * - **字节**（本端真的持有那一份）：行数、像素、EXIF 拍摄日期、文件体积；
+ * - **服务端结论**（DTO 里的字段）：注入字符数、注入是否被截断、嗅探所得的 mime；
+ * - **本端口径**（本端自己做了什么）：`UTF-8` 只是**本端解码口径**，不是文件的真实编码（见下）。
+ *
+ * ## 「编码」为什么敢写 UTF-8（且只敢这么写）
+ * 客户端**拿不到文件的真实编码**：磁盘上那份字节是按什么字符集写的，没有任何字段说过，本端也没有
+ * 可靠的方式判定（猜 GBK / Shift-JIS 就是在编）。能确定的只有一件事：正文区那段文字是
+ * [DocumentPreview.slice] 用 `String(bytes, Charsets.UTF_8)` 解出来的——所以这一项写的是
+ * **「本端解码口径」**，即「你正在读的这段文字是怎么来的」。**表述里必须带这个限定语**：
+ * 裸写一个「UTF-8」会被读成「这份文件是 UTF-8 编码的」，那是本端不知道的事。
+ *
+ * ## 与芯片行重合的两处：一处保留、一处省略
+ * 预览弹层顶部那枚芯片已经写着「类型 · 体积 · 字数 · 状态 · 注入已截断」（[DocumentChipModel.detail]），
+ * 因此这一行刻意**不重复**：
+ * - **省略**「体积」与「服务端状态」：[DocumentChips.sizeLabel] / [DocumentChips.statusLabel] 那两个
+ *   数字/词与芯片行**逐字相同**、且没有口径可补，再写一遍只是噪音（图片那一路没有芯片行，所以
+ *   体积在 [imageItems] 里是要显示的）；
+ * - **保留**「字符数」并补上口径：芯片只写「8,000 字」，读者无法知道那是**服务端注入上下文**的
+ *   字数还是这份文件的字数——这正是一句会把人带偏的话，补上「（服务端注入口径）」才算说清。
+ *
+ * ## 本端的截断为什么不在这里再说一遍
+ * [PreviewSlice.truncated]（本端只预览了前 256 KB / 5,000 行）已经让 [PreviewSlice.notice] 在**正文
+ * 上方**明说了，本行不再重复同一件事；而**服务端**的「注入被预算截断」是另一件事（[DocumentRefDto.truncated]，
+ * 正文照样进了上下文），它没有别的去处，所以在 [textItems] 里单列一条。
+ */
+object PreviewMetadata {
+
+    /** 这一行各项之间的分隔符。 */
+    const val ITEM_SEPARATOR: String = " · "
+
+    /** 把各项拼成能直接交给 `Text` 的那一行；空列表拼成空串（调用方据此不画这一行）。 */
+    fun join(items: List<String>): String = items.joinToString(ITEM_SEPARATOR)
+
+    /**
+     * 文本类预览的那几项：行数 · 字符数（带口径）· 解码口径 · 服务端的截断标记。
+     *
+     * @param slice 正文区的切段结果（[DocumentPreview.slice] 的产物）。
+     * @param serverCharsLabel 服务端下发的注入字符数**已格式化**的那一份
+     *   （`documents[].chars` → [DocumentChips.charsLabel]，如 `"8,000 字"`）；`null` = 服务端没报
+     *   （`chars` 整键缺席，契约 v0.59 §1.2），此时改报本端预览内容的字数。
+     * @param contextTruncated 服务端是否报告了「注入被预算截断」（`documents[].truncated`）。
+     *   ⚠️ 与 [PreviewSlice.truncated]（**本端**预览截断）是两件事，见本对象 KDoc。
+     */
+    fun textItems(
+        slice: PreviewSlice,
+        serverCharsLabel: String?,
+        contextTruncated: Boolean,
+    ): List<String> = buildList {
+        add(linesItem(slice))
+        add(charsItem(slice.text, serverCharsLabel))
+        // 本端解码口径：正文就是 String(bytes, UTF_8) 的产物，说得出、也只在说这一件事。
+        add(DECODED_AS_UTF8)
+        if (contextTruncated) add(TRUNCATED_FOR_CONTEXT)
+    }
+
+    /**
+     * 非文本类（PDF 这类二进制）的那几项：只有服务端**字节嗅探**所得的 mime。
+     *
+     * 体积与状态刻意不在这里（芯片行已经写着，见本对象 KDoc）；服务端说「读不到」时下发的
+     * **原因原话**也不在这里——它已经被 [DocumentPreviewGate.plan] 送进正文区那句人话里**原样显示**，
+     * 这里是同一屏的第二个位置，重复一遍只会让那句话看着像两条不同的消息。
+     *
+     * @param serverMime DTO 的 `mime`（服务端嗅探所得基类型）；本地待发附件**没有**这个结论
+     *   （还没上传过），传 `null` —— 这一项因此缺席，**不由本端按扩展名补一个**。
+     */
+    fun fileItems(serverMime: String?): List<String> =
+        listOfNotNull(serverMime?.trim()?.takeIf { it.isNotEmpty() })
+
+    /**
+     * 图片的那几项：格式（mime）· 分辨率 · 体积 · 拍摄日期。
+     *
+     * 图片这一路没有附件芯片行，所以体积在这里是要显示的。每一项都可能在拿不到时缺席：
+     * 格式（嗅探与平台声明都判不出来时）、分辨率（本端解不出边界时）、拍摄日期（EXIF 里没有
+     * `DateTimeOriginal`，或那个值不是能认的日期时）——见各自的参数说明。
+     *
+     * @param mime 交给别的应用的类型（[ImageOpenTypes.openType] 的产物）。⚠️ 退化到「图片通配」
+     *   时**必须传 `null`**：`image/` 通配（[ImageOpenTypes.ANY_IMAGE]）不是格式，写出来等于给了一个什么都没说的答案。
+     * @param width / @param height 本端按 `inJustDecodeBounds` 读到的像素；任一侧 ≤ 0 / 缺席即整项不出现。
+     * @param sizeBytes 本端实际持有的字节数；[UNKNOWN_BYTES] 即整项不出现。
+     * @param capturedAt EXIF `DateTimeOriginal` 的**原始字符串**（`yyyy:MM:dd HH:mm:ss`，
+     *   没有时区、按本地墙钟读，见 [formatExifDateTime]）。
+     */
+    fun imageItems(
+        mime: String?,
+        width: Int? = null,
+        height: Int? = null,
+        sizeBytes: Long = UNKNOWN_BYTES,
+        capturedAt: String? = null,
+    ): List<String> = buildList {
+        mime?.trim()?.takeIf { it.isNotEmpty() }?.let { add(it) }
+        if (width != null && height != null && width > 0 && height > 0) add("$width × $height")
+        DocumentChips.sizeLabel(sizeBytes).takeIf { it.isNotEmpty() }?.let { add(it) }
+        formatExifDateTime(capturedAt)?.let { add(CAPTURED_AT_PREFIX + it) }
+    }
+
+    /**
+     * EXIF 的拍摄时间 → 人能读的样子（`"2019:07:04 20:31:05"` → `"拍摄于 2019年7月4日 20:31"`）；
+     * 认不出就回 `null`（宁可不显示，也不显示一个错的日期）。
+     *
+     * ## 两个必须说清的取舍
+     * 1. **没有时区**。EXIF 的 `DateTimeOriginal` 是纯墙钟字符串（`yyyy:MM:dd HH:mm:ss`），规范里
+     *    根本没有偏移量字段。所以这里**不做任何时区换算**，按字面数字当日历时间读——把它当 UTC
+     *    再转本地，只会让一个原本正确的日期凭空错几个小时。
+     * 2. **严格到不近人情**。只有逐位对上 `yyyy:MM:dd HH:mm:ss`（19 个字符、分隔符固定）且各段落在
+     *    合法范围内才认。相机的「值未写入」占位符 `"0000:00:00 00:00:00"` 因此落在月份 0 上被判非法
+     *    ——这是对的，它本来就表示「不知道」。宽松解析（补零、猜分隔符）换来的是**看起来正常的错日期**，
+     *    比不显示糟得多。
+     *
+     * 秒刻意丢掉：这一行是给人看的摘要，分钟已经足够定位（同秒的两张图对用户没有区别）。
+     */
+    fun formatExifDateTime(raw: String?): String? {
+        val value = raw?.trim().orEmpty()
+        val groups = EXIF_DATE_TIME.matchEntire(value) ?: return null
+        // 正则已保证每段都是纯数字，`toInt()` 在这里不会抛。
+        val (year, month, day, hour, minute, second) = groups.destructured
+        val y = year.toInt()
+        val mo = month.toInt()
+        val d = day.toInt()
+        val h = hour.toInt()
+        val mi = minute.toInt()
+        val s = second.toInt()
+        if (y < MIN_YEAR) return null
+        if (mo !in 1..12) return null
+        if (d !in 1..31) return null
+        if (h !in 0..23) return null
+        if (mi !in 0..59) return null
+        // 60 是闰秒，相机会写出来，不该判成坏日期。
+        if (s !in 0..60) return null
+        return String.format(Locale.ROOT, "%d年%d月%d日 %02d:%02d", y, mo, d, h, mi)
+    }
+
+    /**
+     * 行数那一项。
+     *
+     * 显示量按 [DocumentPreview.lineCount] **从正文本身重算**（不是取 [PreviewSlice.shownLines]）：
+     * 这一行的标题就是「你看到的这段有多少行」，重算让它与正文永远自洽。被本端截断时补上全文行数
+     * （[PreviewSlice.totalLines] 是按整份字节数出来的，本端确实持有那份字节）——只说「显示 N 行」
+     * 会让人以为文件就这么长。
+     */
+    private fun linesItem(slice: PreviewSlice): String {
+        val shown = grouped(DocumentPreview.lineCount(slice.text))
+        return if (slice.truncated) {
+            "显示 $shown 行 / 共 ${grouped(slice.totalLines)} 行"
+        } else {
+            "$shown 行"
+        }
+    }
+
+    /** 字符数一项：服务端报了就报它那句（补口径），没报才用本端的计数（另一句口径）。 */
+    private fun charsItem(text: String, serverCharsLabel: String?): String =
+        if (serverCharsLabel != null) {
+            serverCharsLabel + SERVER_CHARS_SCOPE
+        } else {
+            grouped(codePointCount(text)) + " 字" + LOCAL_CHARS_SCOPE
+        }
+
+    /**
+     * 「字」数按 **Unicode 码点**算（`codePointCount`）：一个 emoji / 一个汉字都算一个字。
+     * 直接取 `String.length` 会把 BMP 之外的字符算成两个（UTF-16 代理对），与「字数」这个说法不符。
+     */
+    private fun codePointCount(text: String): Int =
+        text.codePointCount(0, text.length)
+
+    /** 千分位分组（只用于计数，纯展示）。 */
+    private fun grouped(value: Int): String = String.format(Locale.ROOT, "%,d", value)
+
+    // —— 每一项的措辞都收在这里，测试锚的也是这几句 ——
+
+    /** 本端解码口径。**限定语不许省**：省了就成了对文件真实编码的断言（见本对象 KDoc）。 */
+    const val DECODED_AS_UTF8: String = "UTF-8（本端解码口径）"
+
+    /** 服务端 `chars` 的口径：那是**注入上下文**的字数，不是这份文件的字数。 */
+    const val SERVER_CHARS_SCOPE: String = "（服务端注入口径）"
+
+    /** 本端自己数出来的字数口径：只数了预览内容（截断时就不是全文）。 */
+    const val LOCAL_CHARS_SCOPE: String = "（本端预览内容）"
+
+    /** 服务端的 `truncated`：注入被预算截断，**正文照样进了上下文**（与「读不到」是两件事）。 */
+    const val TRUNCATED_FOR_CONTEXT: String = "正文被截断（进上下文的部分）"
+
+    /** 拍摄日期前缀：一个光秃秃的日期在这一行里会被当成「文件修改时间」之类的东西。 */
+    const val CAPTURED_AT_PREFIX: String = "拍摄于 "
+
+    /** 字节数拿不到时的占位：交给 [DocumentChips.sizeLabel]，它会回空串（于是整项不出现）。 */
+    const val UNKNOWN_BYTES: Long = -1L
+
+    private const val MIN_YEAR = 1
+
+    /** EXIF 规范里的日期时间形状；只认这一种，见 [formatExifDateTime]。 */
+    private val EXIF_DATE_TIME =
+        Regex("""(\d{4}):(\d{2}):(\d{2}) (\d{2}):(\d{2}):(\d{2})""")
+}

app/src/main/kotlin/top/yeij/cyrene/domain/chat/VoiceClip.kt

@@ -0,0 +1,238 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 一段**要发出去的语音**：录音参数、WAV 封装、体积闸门与幂等键（纯函数，可穷举单测）。
+ *
+ * ## 为什么自己封 WAV，而不是用 `MediaRecorder`
+ * 契约 v0.96 给 `voice_input.format` 的白名单是 **`wav|mp3|ogg`**，而 Android `MediaRecorder`
+ * 的默认产物是 **`m4a/aac`**——**不在白名单里**。要用它就得另接一个编码器把 aac 转成 mp3/ogg，
+ * 那是新依赖（项目纪律：加依赖先问）。而 `AudioRecord` 给的 PCM + 一个 44 字节的 RIFF 头
+ * 就是 WAV：**零依赖、零转码、逐字节可预期**，也能在单测里把头的每个字段钉死。
+ *
+ * ## 采样参数：16 kHz / 单声道 / 16-bit
+ * - **采样率 16 kHz**：语音识别的行业口径就是 16 kHz（电话带宽 8 kHz 会把擦音削掉，44.1 kHz
+ *   对 STT 没有任何增益）。同一句话的字节数因此只有 44.1 kHz 的 **36%**——这一条在本端格外重要，
+ *   因为 `voice_input.audio` 是**内联 base64**（4/3 膨胀）走一条 WS 文本帧。
+ * - **单声道**：麦克风阵列的立体声对 STT 只有副作用（两路几乎相同，白背一倍体积）。
+ * - **16-bit**：`AudioRecord` 的原生 PCM 编码（`ENCODING_PCM_16BIT`），不做压缩——压缩要依赖。
+ *
+ * 由此得出一个**只有一条**的换算：`1 ms = 32 字节`，`1 s = 32 000 字节`。
+ *
+ * ## 体积闸门（为什么是 5 MiB）
+ * 契约 v0.96 的 `voice_input` **没写** `audio` 的体积上限（`chat.image` 写了：解码后 5 MiB /
+ * 字符串 6990572 字符）。本端按**已知最严的那一档**设计，也就是 [MAX_AUDIO_BYTES] =
+ * `ChatImageBudget.SERVER_MAX_DECODED_BYTES`（5 MiB，解码后）——同一个部署对「内联 base64 字段」
+ * 已经明确接受的量级，voice 没有理由比它更宽。超限**明确拒绝**（[VOICE_TOO_LARGE_MESSAGE]），
+ * 绝不静默截断：截断后的音频在服务端听来就是「话说到一半断了」。
+ *
+ * 60 秒的录满长度（[MAX_RECORDING_MILLIS]）只用到这条闸门的 **36%**（1 920 044 字节），所以
+ * 正常路径永远撞不到它——它是**第二道**闸（硬件偶尔会多给几块缓冲，谁也说不准），不是主判据。
+ *
+ * ## 时长下限
+ * 按下就松手的误触会得到几十毫秒的音频：那不是「说话」，送给服务端只会换来一次空转写。
+ * 不足 [MIN_RECORDING_MILLIS] 的录音在**本端**就被挡下并说明（[VOICE_TOO_SHORT_MESSAGE]）。
+ */
+object VoiceClip {
+
+    /** 采样率（Hz）。16 kHz = STT 的行业口径，见类注释。 */
+    const val SAMPLE_RATE_HZ: Int = 16_000
+
+    /** 声道数：单声道（立体声对 STT 无益，只翻倍体积）。 */
+    const val CHANNEL_COUNT: Int = 1
+
+    /** 位深：`AudioRecord` 的原生 16-bit PCM。 */
+    const val BITS_PER_SAMPLE: Int = 16
+
+    /** 每采样的字节数。 */
+    const val BYTES_PER_SAMPLE: Int = BITS_PER_SAMPLE / 8
+
+    /** RIFF/WAVE 的 PCM 头长度：`RIFF`(4) + size(4) + `WAVE`(4) + `fmt `(16+8) + `data`(8)。 */
+    const val HEADER_BYTES: Int = 44
+
+    /** 上行 `format` 的取值。契约白名单 `wav|mp3|ogg` 里我们**只产出**这一个。 */
+    const val FORMAT: String = "wav"
+
+    /** 每秒的 PCM 字节数（= [SAMPLE_RATE_HZ] × [CHANNEL_COUNT] × [BYTES_PER_SAMPLE]）。 */
+    val BYTES_PER_SECOND: Int = SAMPLE_RATE_HZ * CHANNEL_COUNT * BYTES_PER_SAMPLE
+
+    /**
+     * 一段语音（**含头**）的字节上限：与 `chat.image` 解码后同一条线，见类注释。
+     * 刻意**引用**那个常量而不是再写一遍 `5 * 1024 * 1024`：上限只留一处，改的时候不会漂。
+     */
+    const val MAX_AUDIO_BYTES: Int = ChatImageBudget.SERVER_MAX_DECODED_BYTES
+
+    /**
+     * 一次录音的**最长**时长（毫秒）。60 秒取自 IM 的通行口径（微信 / QQ 都是这个量级），
+     * 也对得上服务端 STT 的现实：再长的语音转写质量与等待都不划算。
+     *
+     * 到点由录音机自己置「满了」标记（见 `VoiceRecorder`），UI 随即收尾发送——
+     * 不是悄悄截断，用户看到的是「到 60 秒了，这段发出去」。
+     */
+    const val MAX_RECORDING_MILLIS: Int = 60_000
+
+    /** 短于这个时长的录音**不送**（按下就松手的误触），见类注释。 */
+    const val MIN_RECORDING_MILLIS: Int = 1_000
+
+    /** 60 秒对应的 PCM 字节数（录音机据此封顶，不在读循环里另算一遍公式）。 */
+    val MAX_PCM_BYTES: Int = pcmBytesFor(MAX_RECORDING_MILLIS)
+
+    /** 这段 PCM 加上 WAV 头之后的**总**字节数。 */
+    fun totalBytesFor(pcmBytes: Int): Int = if (pcmBytes <= 0) 0 else HEADER_BYTES + pcmBytes
+
+    /** 时长 → PCM 字节数（向下取整；`<= 0` 的时长回 0）。 */
+    fun pcmBytesFor(durationMillis: Int): Int =
+        if (durationMillis <= 0) 0 else (durationMillis.toLong() * BYTES_PER_SECOND / 1000L).toInt()
+
+    /** PCM 字节数 → 时长（毫秒，向下取整）。 */
+    fun durationMillisOf(pcmBytes: Int): Int =
+        if (pcmBytes <= 0) 0 else (pcmBytes.toLong() * 1000L / BYTES_PER_SECOND).toInt()
+
+    /** 总字节数是否在 [MAX_AUDIO_BYTES] 以内（**等于**算通过：`<=`，与 `withinServerLimit` 同口径）。 */
+    fun withinLimit(totalBytes: Int): Boolean = totalBytes <= MAX_AUDIO_BYTES
+
+    /**
+     * WAV 头（44 字节，PCM / 单块 / 无扩展）。
+     *
+     * 逐字段按 RIFF 规范写：`RIFF` + 文件长 - 8 + `WAVE` + `fmt `(16 字节，PCM=1) + 声道 /
+     * 采样率 / 字节率 / 块对齐 / 位深 + `data` + 数据长。全部**小端**。
+     */
+    fun wavHeader(pcmBytes: Int): ByteArray {
+        val data = ByteArray(HEADER_BYTES)
+        putAscii(data, 0, "RIFF")
+        putIntLe(data, 4, HEADER_BYTES - 8 + pcmBytes)
+        putAscii(data, 8, "WAVE")
+        putAscii(data, 12, "fmt ")
+        putIntLe(data, 16, 16)
+        putShortLe(data, 20, AUDIO_FORMAT_PCM)
+        putShortLe(data, 22, CHANNEL_COUNT)
+        putIntLe(data, 24, SAMPLE_RATE_HZ)
+        putIntLe(data, 28, BYTES_PER_SECOND)
+        putShortLe(data, 32, CHANNEL_COUNT * BYTES_PER_SAMPLE)
+        putShortLe(data, 34, BITS_PER_SAMPLE)
+        putAscii(data, 36, "data")
+        putIntLe(data, 40, pcmBytes)
+        return data
+    }
+
+    /** 头 + PCM = 一个可直接交给任何 `WAV` 解码器的字节数组。 */
+    fun toWav(pcm: ByteArray): ByteArray {
+        val header = wavHeader(pcm.size)
+        val out = ByteArray(HEADER_BYTES + pcm.size)
+        header.copyInto(out, 0)
+        pcm.copyInto(out, HEADER_BYTES)
+        return out
+    }
+
+    /**
+     * 这段 PCM 该不该发、发出去长什么样（**唯一**的准入判据，录音机与 VM 共用）。
+     *
+     * 判序是刻意的：**空 → 超限 → 太短 → 可发**。
+     * - 空：一个字节都没有（设备没给 / 权限刚被撤），连「太短」都谈不上；
+     * - 超限：长度或字节数已经越线，绝不能发（哪怕时长看起来正常——硬件也可能给出异常长的一块）；
+     * - 太短：见 [MIN_RECORDING_MILLIS]。
+     */
+    fun plan(pcm: ByteArray): VoiceClipPlan {
+        if (pcm.isEmpty()) return VoiceClipPlan.Empty
+        val total = totalBytesFor(pcm.size)
+        if (!withinLimit(total)) return VoiceClipPlan.TooLarge(total)
+        val duration = durationMillisOf(pcm.size)
+        if (duration < MIN_RECORDING_MILLIS) return VoiceClipPlan.TooShort(duration)
+        return VoiceClipPlan.Ready(toWav(pcm), duration)
+    }
+
+    /** RIFF 的 `audioFormat`：1 = PCM（整数）。 */
+    private const val AUDIO_FORMAT_PCM: Int = 1
+
+    private fun putAscii(target: ByteArray, offset: Int, text: String) {
+        for (index in text.indices) target[offset + index] = text[index].code.toByte()
+    }
+
+    private fun putIntLe(target: ByteArray, offset: Int, value: Int) {
+        target[offset] = (value and 0xFF).toByte()
+        target[offset + 1] = ((value ushr 8) and 0xFF).toByte()
+        target[offset + 2] = ((value ushr 16) and 0xFF).toByte()
+        target[offset + 3] = ((value ushr 24) and 0xFF).toByte()
+    }
+
+    private fun putShortLe(target: ByteArray, offset: Int, value: Int) {
+        target[offset] = (value and 0xFF).toByte()
+        target[offset + 1] = ((value ushr 8) and 0xFF).toByte()
+    }
+}
+
+/** [VoiceClip.plan] 的四档结论。 */
+sealed interface VoiceClipPlan {
+
+    /** 一段**可以发**的语音：已经封好 WAV，[durationMs] 是它的实际时长。 */
+    class Ready(val wav: ByteArray, val durationMs: Int) : VoiceClipPlan
+
+    /** 一个字节都没录到。 */
+    data object Empty : VoiceClipPlan
+
+    /** 短于 [VoiceClip.MIN_RECORDING_MILLIS]（按下就松手那种误触）。 */
+    data class TooShort(val durationMs: Int) : VoiceClipPlan
+
+    /** 总字节数超过 [VoiceClip.MAX_AUDIO_BYTES]。 */
+    data class TooLarge(val totalBytes: Int) : VoiceClipPlan
+}
+
+/** 空录音的如实告知（**不是错误**：什么都没发生，用户重来一次即可）。 */
+const val VOICE_EMPTY_MESSAGE: String = "没有录到声音，再按一次试试"
+
+/** 太短的如实告知。 */
+const val VOICE_TOO_SHORT_MESSAGE: String = "录得太短了，说满一秒再发"
+
+/**
+ * 超限的如实告知。刻意说「没发出去」：那句话必须与事实上一致（这条一个字节都没上行），
+ * 也不能把责任推给用户（他确实就说了那么久，是本端的闸门挡下的）。
+ */
+const val VOICE_TOO_LARGE_MESSAGE: String = "这段语音太长，本机没有发出去"
+
+/** 这一条被本端挡下时该说的那句话；`null` = 可以发（纯函数）。 */
+fun voiceClipRejection(plan: VoiceClipPlan): String? = when (plan) {
+    is VoiceClipPlan.Ready -> null
+    VoiceClipPlan.Empty -> VOICE_EMPTY_MESSAGE
+    is VoiceClipPlan.TooShort -> VOICE_TOO_SHORT_MESSAGE
+    is VoiceClipPlan.TooLarge -> VOICE_TOO_LARGE_MESSAGE
+}
+
+/**
+ * 录音中 / 待重发那一段的时长文案（纯函数）：`m:ss`，**从 0:00 起就有值**。
+ *
+ * 与接收侧的 [voiceDurationLabel] 差一条：那个对「不足一秒」回 `null`（服务端没给准数时宁可
+ * 不显示），而这里显示的是**本端自己正在数的时间**——0:00 是事实，不是冒充。
+ * 负数按 0 处理（时钟回拨 / 调用方算错时也不出现 `-1:-1`）。
+ */
+fun voiceElapsedLabel(elapsedMs: Int): String {
+    val totalSeconds = elapsedMs.coerceAtLeast(0) / 1000
+    return "${totalSeconds / 60}:${(totalSeconds % 60).toString().padStart(2, '0')}"
+}
+
+/** 语音消息的幂等键前缀：与文本那条（`local-`）/ 分享那条（`share-`）同一手法，见 [voiceClientMsgIdFor]。 */
+const val VOICE_CLIENT_MSG_ID_PREFIX: String = "voice-"
+
+/**
+ * 一条**录好、还没发出去**的语音在本端的记账（只有小字段，audio 不在这里）。
+ *
+ * `clientMsgId` 是契约 v0.96 §3.15 的幂等键：同一个非空值服务端**只承认第一条**，重复到达回
+ * `chat_duplicate`、不落库不起回合。所以「重发这一段」必须**复用**它（[voiceClientMsgIdFor]），
+ * 换了新键就是让服务端把同一句话再答一遍。
+ *
+ * `audio`（base64）刻意**不进** [top.yeij.cyrene.ui.chat.ChatUiState]：那是一格会被反复 `copy`
+ * 并逐字段比较的状态（流式期间每秒几十次），几 MB 的字符串放进去等于每次比较都扫一遍它。
+ * 字节留在 VM 自己那个字段上（生命周期与 VM 相同，转屏不丢）。
+ */
+data class VoiceDraftInfo(
+    val clientMsgId: String,
+    val durationMs: Int,
+    val totalBytes: Int,
+)
+
+/**
+ * 这一段该用哪个幂等键（纯函数）：
+ * - [draft] 非空 = **重发刚才没发出去的那一段** ⇒ 原样复用它当时的键（契约要求）；
+ * - [draft] 为空 = 一段**新**录音 ⇒ 现铸一个：前缀 + [mint] 给的随机串（随机而不是自增，
+ *   理由与文本那条相同：服务端的判重窗口是整个会话历史）。
+ */
+fun voiceClientMsgIdFor(draft: VoiceDraftInfo?, mint: () -> String): String =
+    draft?.clientMsgId ?: "$VOICE_CLIENT_MSG_ID_PREFIX${mint()}"

app/src/main/kotlin/top/yeij/cyrene/domain/chat/VoiceMessage.kt

@@ -0,0 +1,311 @@
+package top.yeij.cyrene.domain.chat
+
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.data.repository.DocumentCacheUnavailableException
+import top.yeij.cyrene.data.repository.VoiceTooLargeException
+import top.yeij.cyrene.data.repository.VoiceUrlUnavailableException
+
+/**
+ * `voice.source` 的闭集（契约 §4.4）：`asr` = 服务端（含云端）语音识别所得；
+ * `platform` = 渠道平台自带转写（微信 iLink 的 `voice_item.text`）；
+ * `tts` = **我们自己合成的出站语音**（她的 `speak` 工具产出的那一段，后端 M57-M59 新增）。
+ *
+ * 三个取值在**接收侧**没有分叉：合成成功的那条与入站语音同形（`status = transcribed` + 四键
+ * 副本齐全），照同一条路渲染；合成降级的那条是 `status = failed`（见 [VoiceStatus.FAILED]）。
+ */
+object VoiceSource {
+
+    const val ASR: String = "asr"
+
+    const val PLATFORM: String = "platform"
+
+    const val TTS: String = "tts"
+}
+
+/**
+ * `voice.status` 的闭集（契约 §4.4，**三态**）。
+ *
+ * 与 [DocumentStatus] 同一条纪律：**只认闭集里的取值，认不出的不猜**——但两者收尾的方式不同。
+ * 文档的未知 `status` 要**原样显示**（那是给用户看的结论），语音的未知 `status` 只是
+ * 「本端不多说一句话」（正文由服务端给，见 [voiceNote]）。
+ */
+object VoiceStatus {
+
+    /** 正文**就是**转写文本（出站方向 = 合成成功、有副本可播）。 */
+    const val TRANSCRIBED: String = "transcribed"
+
+    /** 转写成功但**没识别出文字** ⇒ 正文多半是空的，本端补一句（[VOICE_EMPTY_NOTE]）。 */
+    const val EMPTY: String = "empty"
+
+    /**
+     * 这一条**没有可播的语音**，正文是一句话（见 [isPlayableVoice]）。
+     *
+     * 两个方向同形、语义统一（后端 M57-M59 预告，契约 v0.98 待正式回执）：
+     * - **入站**：没拿到转写文本 ⇒ 正文是服务端给的那行中文诚实提示；
+     * - **出站**：她本想用语音、合成降级回文字 ⇒ 正文是普通文字，另带 `fallbackReason`
+     *   （见 [voiceFallbackNote]）。
+     *
+     * 入站方向设计上**刻意不下发**失败细分（未配置 / 鉴权 / 欠费 / 限流 / 超时 / 格式不支持 /
+     * 无字节一律只进服务端日志），所以本端**一个细分都不许猜**，也不替服务端改写那句话。
+     */
+    const val FAILED: String = "failed"
+}
+
+/**
+ * 「转写成功但没识别出文字」时本端补的那一句。
+ *
+ * 为什么这句是**本端的**而不是服务端的原话：这一态的语义由契约定义（§4.4 的三态之一），而
+ * `empty` 的正文按定义就是空的——不补一句的话，一条「微信语音、没有音频副本、也没转出文字」
+ * 的消息在屏幕上**只剩一个「语音」标签**，看的人无从知道发生了什么。这不是替服务端改文案
+ * （那句话说的是**这一态的语义**，不是失败原因），也**不覆盖**任何正文。
+ */
+const val VOICE_EMPTY_NOTE: String = "没有识别出文字"
+
+/**
+ * `status == "failed"` 的那一行**灰色小标**的固定前半句（后面可能跟服务端给的 `fallbackReason`）。
+ *
+ * 为什么要有这一行：这一态的消息 `voice` 键**在**、但**没有可播的语音**（见 [isPlayableVoice]），
+ * 所以屏幕上不会有语音形态。少了这一行，一条「她本想发语音、合成降级成文字」的消息与一条普通文字
+ * 消息**逐像素相同**——看的人无从知道这条本来是一段声音。它只说本端能确定的那件事（这条没有可播的
+ * 声音），**不解释原因**（原因归服务端，见 [voiceFallbackNote] 里那段原话）。
+ *
+ * ⚠️ 措辞要同时站得住两个方向（入站转写失败 / 出站合成降级），所以**不写**「转写失败」也**不写**
+ * 「合成失败」：本端分不清，也不该替服务端选一个说法。
+ */
+const val VOICE_FALLBACK_NOTE: String = "这条语音没有可播放的声音"
+
+/**
+ * 解码 / 播放阶段失败（`MediaPlayer` 报错或起播抛异常）时的文案。
+ *
+ * 与取字节失败（[voicePlaybackFailureMessage]）分开：两者要用户做的事不一样——字节没拿到是
+ * 「网络 / 过期 / 服务端没有这份副本」，可以再点一次；这一段是「字节在手上，本机解不开」
+ * （格式不支持、文件损坏），再点一次多半还是同样的结果。
+ */
+const val VOICE_UNPLAYABLE_MESSAGE: String = "这段语音本机播不了"
+
+/**
+ * 一条语音的**可播放副本**：四个键（`name` / `mime` / `size` / `url`）齐全时才构造得出来。
+ *
+ * 存在的理由是把「能不能播」这件事**收成一个类型**，而不是让 UI / 播放器各自去测四个 `!= null`：
+ * 拿到 [VoiceAudio] 就等于「有副本、可以画播放控件、可以发请求」；拿不到就**一个播放控件都不画**
+ * （不能给一个点下去必然失败的按钮）。
+ *
+ * @property durationMs 从 [VoiceDto] 原样带过来；`null` = 服务端没给，**不显示时长**。
+ */
+data class VoiceAudio(
+    val name: String,
+    val mime: String,
+    val size: Long,
+    val url: String,
+    val durationMs: Int? = null,
+)
+
+/**
+ * `voice` 键在不在（纯函数）—— 「这条消息**来自**一条语音」。
+ *
+ * 这是契约 §4.4 给的**唯一**来源判据：非语音消息整键缺席（不是 `{}` 也不是 `null`），
+ * `content` 里有没有 `[语音]` 这类字样与本判据无关（QQ 的占位标记自 v0.67 起不再下发，
+ * 别人也可以自己打出一模一样的字）。
+ *
+ * ⚠️ 它与「要不要画语音气泡」**不是同一件事**了：合成降级 / 转写失败的那些行 `voice` 键照样在，
+ * 但**没有可播的语音**（见 [isPlayableVoice]）。判「是不是语音消息」用本函数，判「画不画语音
+ * 形态」用 [isVoiceMessage]——两个问题分开问，混用会让降级行被画成一个必然播不了的气泡。
+ */
+fun hasVoice(message: HistoryMessageDto): Boolean = message.voice != null
+
+/**
+ * 这条语音**有没有可播的语音形态**（纯函数）：除了 `voice` 键要在，`status` 还不能是 `failed`。
+ *
+ * ## 为什么判据是「不是 `failed`」而不是「是 `transcribed` / `empty`」
+ * 后端 M57-M59 预告（契约 v0.98 待正式回执）只点名了 `failed` 这一态**明确没有可播的语音**：
+ * 入站是没拿到转写文本、出站是合成降级回文字，两个方向的正文都是一句话而不是一段语音。
+ *
+ * 反过来，认不出的 `status` **一律当可播**（fail-open）。理由是这个方向错得便宜、另一个方向错得
+ * 贵：后端将来若新增一个成功态（比如 `transcribed` 之外的 `truncated`），fail-open 只是多画一枚
+ * 语音形态（最坏是点了播不出来，有既有的失败文案兜着）；fail-closed 则会把一条**真的有副本**的
+ * 语音静默吞成纯文字，用户再也点不到那段声音——而且没有任何界面提示说明为什么。所以这里只把
+ * 契约明确说过「没有语音」的那一态排除掉，其余交给「四键齐全才画播放控件」（[voiceAudio]）。
+ */
+fun isPlayableVoice(voice: VoiceDto): Boolean = voice.status != VoiceStatus.FAILED
+
+/**
+ * 🎤 **要不要画语音形态的判据** = `voice` 键存在 **且** `status != "failed"`（契约 §4.4 +
+ * 后端 M57-M59 预告）。
+ *
+ * 只有这两个条件，而且**永远只有这两个**：
+ * - `voice` 键缺席 ⇒ 不是语音消息（[hasVoice]）；
+ * - `status == "failed"` ⇒ 这条**没有可播的语音**（入站转写失败 / 出站合成降级），正文照常按文字
+ *   渲染，另加一行灰色小标（[voiceFallbackNote]）——**不**画语音形态，因为画出来就是一个必然
+ *   播不了的控件。
+ *
+ * 入站语音（`asr` / `platform`）与合成成功的出站语音（`tts`）走的是**同一条**路：判据只看
+ * `status`，不看 `source`。
+ */
+fun isVoiceMessage(message: HistoryMessageDto): Boolean {
+    val voice = message.voice ?: return false
+    return isPlayableVoice(voice)
+}
+
+/**
+ * 这条语音的**可播放副本**；四个键没凑齐（或名字 / MIME / URL 是空白）就回 `null`。
+ *
+ * 服务端保证「四者同生共死」，本端仍然逐项检查：**这条判据的下游是「给不给播放控件」**，
+ * 而契约里那份保证一旦被某个部署打破，唯一的后果就是用户点到一个必然失败的按钮
+ * ——宁可少画一个控件，也不要画一个假的。
+ *
+ * `size` 只要求在（**不要求 > 0**）：契约说它恒在，本端也不拿它推导别的任何东西
+ * （尤其**不反算时长**，见 [voiceDurationLabel]）。
+ */
+fun voiceAudio(voice: VoiceDto?): VoiceAudio? {
+    if (voice == null) return null
+    val name = voice.name?.takeIf { it.isNotBlank() } ?: return null
+    val mime = voice.mime?.takeIf { it.isNotBlank() } ?: return null
+    val url = voice.url?.takeIf { it.isNotBlank() } ?: return null
+    val size = voice.size ?: return null
+    return VoiceAudio(name = name, mime = mime, size = size, url = url, durationMs = voice.durationMs)
+}
+
+/**
+ * 时长文案（纯函数）：`m:ss`（如 `0:03` / `1:05`）。
+ *
+ * **缺席就不显示**是契约的硬要求（服务端「读不出来就省略键，绝不估算」，本端同理）：
+ * - `null` ⇒ 回 `null`（调用方因此**一个字符都不画**，更不会出现 `0:00` 那种冒充）；
+ * - `<= 0` ⇒ 也回 `null`：`0` 毫秒的语音不存在，把服务端的一个异常取值显示成 `0:00`
+ *   就是拿一个编出来的数字冒充事实；
+ * - **不足一秒**（`1..999`）⇒ 也回 `null`：`m:ss` 只能把它显示成 `0:00`，而 `0:00` 与
+ *   「没有时长」在屏幕上是同一个样子——与其显示一个看起来像没读到的时间，不如什么都不显示
+ *   （渠道也不会真的发这种语音）；
+ * - 不设上限：语音消息不会长到需要小时制，超过 99 分钟就照实显示 `124:03`（**不折算**成
+ *   「2:04:03」——那是另一种自己发明的表达）。
+ */
+fun voiceDurationLabel(durationMs: Int?): String? {
+    if (durationMs == null || durationMs < 1_000) return null
+    val totalSeconds = durationMs / 1000
+    val minutes = totalSeconds / 60
+    val seconds = totalSeconds % 60
+    return "$minutes:${seconds.toString().padStart(2, '0')}"
+}
+
+/**
+ * 语音形态**之外**还要多说的一句话；不需要多说就回 `null`（纯函数）。
+ *
+ * 只对 `status == "empty"` 且**正文为空**时成立：
+ * - `transcribed`：正文**就是**转写文本，多说一句都是噪声（所以什么都不补）；
+ * - `empty` 而正文非空：正文本身就是要说的话，此时再说「没有识别出文字」会**自相矛盾**
+ *   （这一形状按契约不该出现，但真出现了也不该让屏幕上出现两句互相顶嘴的话）；
+ * - 未知 `status`（含空串）：**不猜**，只显示正文。
+ *
+ * ⚠️ `failed` 那一态**不走这里**（它连语音形态都不画）：正文由服务端给，本端另加一行小标
+ * （[voiceFallbackNote]）。本函数仍对 `failed` 回 `null`，因为「语音形态旁边多说一句」这个位置
+ * 对那一态根本不存在。
+ */
+fun voiceNote(status: String, content: String): String? =
+    if (status == VoiceStatus.EMPTY && content.isBlank()) VOICE_EMPTY_NOTE else null
+
+/**
+ * `status == "failed"` 时那行灰色小标该写什么；别的状态回 `null`（纯函数）。
+ *
+ * 两段拼成一句话：**固定前半句**（[VOICE_FALLBACK_NOTE]，说的是本端能确定的事实）+ 服务端给的
+ * `fallbackReason`（**一个字符都不改**，原样放进括号里）。
+ *
+ * ## 为什么原样放、不做映射
+ * `fallbackReason` 的取值集合**后端还没定**（`devdocs/02` 里我们已经问了「是闭集还是自由文本」，
+ * 尚未答复；契约 v0.98 的正式回执也还没到）。在有答案之前，本端**不猜**它是不是闭集、更不替它
+ * 编一套友好文案：认不出的取值被映射成一句话，比原样显示更难排查——用户报「显示成『语音超时』」
+ * 时，我们连服务端到底给了什么都不知道。原样显示，最坏是屏幕上出现一个 `tts_timeout` 这样的词，
+ * 而它**正是**我们和后端对账时要的那个字符串。
+ *
+ * ## `fallbackReason` 缺席时
+ * 只有固定前半句。这一档同时是**空正文 + `failed`** 的兜底：这一态的消息正文按契约应当非空
+ * （服务端那行诚实提示 / 降级后的原文本），但本端**不靠**这条保证——真收到一条空正文的 `failed`
+ * 行时，屏幕上至少还有这行小标，而不是一个**什么都没有**的空白（那正是空气泡那种最糟的呈现）。
+ */
+fun voiceFallbackNote(voice: VoiceDto?): String? {
+    if (voice == null || voice.status != VoiceStatus.FAILED) return null
+    val reason = voice.fallbackReason?.takeIf { it.isNotBlank() } ?: return VOICE_FALLBACK_NOTE
+    return "$VOICE_FALLBACK_NOTE（$reason）"
+}
+
+/**
+ * 把服务端给的**相对路径** [url] 接到当前服务器地址 [baseUrl] 上（纯函数）。
+ *
+ * 契约明写 `url` 是唯一的派生字段（`/api/v1/media/<name>`），**客户端绝不自己拼路径**——所以
+ * 本函数只做「保留 path、换成当前 host」这一件事，与 [ImageHostRebase] 同一取向
+ * （图片那条要换的是**别人给过的绝对地址**里的 host，这里要接的是**服务端给的相对路径**）。
+ *
+ * 判据取最小容忍度，任何一条不满足就回 `null`（调用方据此如实报「暂时播不了」，**绝不**
+ * 退回「自己拼一条 `/api/v1/media/<name>`」——那正是契约禁止的那件事）：
+ * - [url] 必须以 `/api/v1/media/` 开头，且后面**恰好**是一段名字：非空、不是 `.` / `..`、
+ *   不含 `/` `\` `%` `?` `#` 与 NUL；
+ * - [baseUrl] 必须能解出 `scheme://authority`（空串 / 没有 host 都解不出）。
+ *
+ * 用的是 [baseUrl] 的 scheme + authority（所以 `http → https`、端口变更都跟着走），**不用**
+ * baseUrl 里的路径：这条地址挂在根路径上，部署形态本来就没有路径前缀这一说。
+ */
+fun voiceMediaUrl(url: String, baseUrl: String): String? {
+    val name = url.removePrefix(MEDIA_PREFIX)
+    if (!url.startsWith(MEDIA_PREFIX) || !isSafeMediaName(name)) return null
+    val origin = originOf(baseUrl) ?: return null
+    return origin + url
+}
+
+/**
+ * 取字节失败时的文案（纯函数，可单测）。
+ *
+ * 与 `documentLoadFailureMessage` / `imageLoadFailureMessage` 同一纪律：服务端能说清的用它的
+ * 原话，本端能分类的分开说，**绝不把失败渲染成「静音」**——一条点了没反应的语音消息在用户眼里
+ * 与「坏了」没有区别。
+ *
+ * 三档本地失败分开写，因为它们要用户做的事不一样：地址拼不出来 = 本端环境不对（重新登录 / 换
+ * 服务器）；太大 = 这条本端处理不了；缓存写不进去 = 本端的问题，重试多半还是这样。
+ */
+fun voicePlaybackFailureMessage(e: Throwable): String = when (e) {
+    is VoiceUrlUnavailableException -> "当前服务器地址不可用，暂时播不了这条语音"
+    is VoiceTooLargeException -> "这条语音太大，本机放不了"
+    is DocumentCacheUnavailableException -> "本地缓存不可用，暂时播不了这条语音"
+    is CyreneException -> when {
+        // ⚠️ 刻意**不**走 `toDocumentFailure()`：那个映射只认文档那四个码（`document_not_found`），
+        // `media_not_found` 在它眼里是「未知码」⇒ 会把「服务端上已经没有这条语音了」说成
+        // 「语音加载失败，media not found」。这一档本端说得准，就说得准一点。
+        e.error.isMediaNotFound() -> "服务端上已经没有这条语音了"
+        else -> "语音加载失败，" + e.error.userMessage
+    }
+
+    else -> "语音加载失败，请稍后重试"
+}
+
+/** 服务端对「名字非法 / 穿越 / 不存在」统一回这一个码（U19：**不区分**，不给探测面）。 */
+private const val MEDIA_NOT_FOUND_CODE = "media_not_found"
+
+private fun CyreneError.isMediaNotFound(): Boolean =
+    this is CyreneError.Server && code == MEDIA_NOT_FOUND_CODE
+
+/** 服务端相对路径的前缀（契约 §1.2 U19）。 */
+private const val MEDIA_PREFIX = "/api/v1/media/"
+
+/**
+ * 媒体名是不是「恰好一段」：不许有分隔符、百分号编码、查询串，也不许是 `.` / `..`。
+ *
+ * 与 `ImageHostRebase` 的同名判据同一条理由：这个字符串来自**别人给的**数据，
+ * 看不懂的形态就不该被我们拼进一条请求地址。
+ */
+private fun isSafeMediaName(name: String): Boolean {
+    if (name.isEmpty() || name == "." || name == "..") return false
+    return name.none { it == '/' || it == '\\' || it == '%' || it == '?' || it == '#' || it == '\u0000' }
+}
+
+/** `scheme://authority`；解不出来回 `null`（空串 / 没有 host / 不是 http(s) 都是解不出来）。 */
+private fun originOf(baseUrl: String): String? {
+    val rest = when {
+        baseUrl.startsWith("http://", ignoreCase = true) -> baseUrl.substring("http://".length)
+        baseUrl.startsWith("https://", ignoreCase = true) -> baseUrl.substring("https://".length)
+        else -> return null
+    }
+    val end = rest.indexOfFirst { it == '/' || it == '?' || it == '#' }.let { if (it < 0) rest.length else it }
+    val authority = rest.substring(0, end)
+    if (authority.isBlank()) return null
+    return baseUrl.take(baseUrl.length - rest.length) + authority
+}

app/src/main/kotlin/top/yeij/cyrene/domain/chat/VoiceOutput.kt

@@ -0,0 +1,93 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * `voice_output` 的**判据**（纯函数，可穷举单测）：契约 v0.96 §3.15 下行帧。
+ *
+ * 帧形状（后端 `回执三十六`）：
+ * ```json
+ * { "type": "voice_output",
+ *   "data": { "audio": "<base64>", "format": "wav", "text": "...", "reply": "她的话",
+ *             "sessionId": "web", "deviceId?": "...", "provider?": "silent|emotiontts|..." } }
+ * ```
+ *
+ * ## `text` 与 `reply` 是两个东西（本端怎么用）
+ * - **[text]**：这一轮**转写出来的话**——也就是我们那段音频被识别成什么。它与
+ *   `voice_input.text`（「已自行转写则跳过 STT」）同一个键名、同一个语义，只是方向相反。
+ * - **[reply]**：**她说的话**（音频念的就是它），也就是用户真正要听/要看的那一句。
+ *
+ * 于是「屏幕上该显示哪一句」的答案是 [voiceReplyText]：**`reply` 优先**，它缺席时才退到 `text`
+ * （宁可显示转写也不显示空白），两者都缺席就什么都不显示（绝不编一句）。
+ *
+ * ## `provider` 是**降级信号**，不是装饰
+ * `provider == "silent"` = 这一轮**没有真音频**（`audio` 空，但 `text` / `reply` 有）。
+ * 契约明写「UI 别把它画成播放器」——画了就是一个点下去必然失败的按钮（与接收侧
+ * `voiceAudio` 的「四个键不齐就不画播放控件」同一条纪律）。
+ *
+ * 除此之外 `audio` 空白也按「没有音频」处理（[voiceOutputHasAudio]）：契约说 silent 时
+ * `audio` 为空，反过来「空 audio + 没给 provider」也绝不能画出一个播放器。
+ *
+ * ## 它与 `voice` 键那条（接收侧放别人发来的语音）**互不相干**
+ * 见 [isVoiceMessage]/[voiceAudio]：那是消息 DTO 的历史副本，这里是**本端刚发出去的那一段**的
+ * 实时应答——两者不共用判据，共用只会把两套字段口径搅在一起。
+ */
+
+/** `provider` 里那个**降级档**的取值（契约 v0.96）。 */
+object VoiceProvider {
+
+    /** 这一轮**没有真音频**（`audio` 空、`text`/`reply` 有）。 */
+    const val SILENT: String = "silent"
+}
+
+/**
+ * 这一帧是不是「没有真音频」那一档（纯函数）。
+ *
+ * 只认字面 `silent`（忽略首尾空白与大小写：它是机器可读码，不是文案）。未知取值一律**不当**
+ * silent——那是另一个 provider，`audio` 在不在由 [voiceOutputHasAudio] 按字节判，不靠猜。
+ */
+fun isSilentVoiceProvider(provider: String?): Boolean =
+    provider?.trim().equals(VoiceProvider.SILENT, ignoreCase = true)
+
+/**
+ * 这一轮**有没有真音频**（纯函数）：`provider != silent` **且** `audio` 非空白。
+ *
+ * 两个条件都不许省：silent 档的 `audio` 契约上就是空的（万一真给了也不算数，因为服务端已经
+ * 明说这一轮没发音），而非 silent 档的 `audio` 也可能因为编码失败缺席。
+ */
+fun voiceOutputHasAudio(audio: String?, provider: String?): Boolean =
+    !isSilentVoiceProvider(provider) && !audio.isNullOrBlank()
+
+/**
+ * 屏幕上该显示的那一句（纯函数，见文件头「`text` 与 `reply` 是两个东西」）。
+ * `reply` 非空白 ⇒ 它；否则 `text` 非空白 ⇒ 它；都没有 ⇒ `null`（一个字符都不显示）。
+ */
+fun voiceReplyText(reply: String?, text: String?): String? =
+    reply?.takeIf { it.isNotBlank() } ?: text?.takeIf { it.isNotBlank() }
+
+/**
+ * 这张卡片下面要补的那一句（纯函数：不需要补时回 `null`）。
+ *
+ * 两档**都要解释，但说的不是同一件事**：
+ * - [silent]：**服务端**这一轮没有真音频（`provider == "silent"`）⇒「她只回了文字」。不解释的话，
+ *   用户按着麦克风说话、回来的却是一段文字，分不清「她选择只回文字」与「播放器坏了」。
+ * - 有音频却没落地（[hasAudioFile] 为假）：那是**本端**解码 / 写缓存失败 ⇒ 说「这段语音本机没
+ *   准备好」，绝不把本机的故障说成「她只回了文字」（那是替服务端下了一个它没下的结论）。
+ */
+fun voiceReplyNote(silent: Boolean, hasAudioFile: Boolean): String? = when {
+    silent -> VOICE_SILENT_NOTE
+    !hasAudioFile -> VOICE_REPLY_LOCAL_UNAVAILABLE_NOTE
+    else -> null
+}
+
+/**
+ * 「这一轮没有音频」的说明。刻意说清是**服务端**这一轮没给音频（`provider` 的降级信号），
+ * 而不是「本机播不了」——后者会把人引向「换个播放器」这种无用的动作。
+ */
+const val VOICE_SILENT_NOTE: String = "这一轮她只回了文字，没有语音"
+
+/**
+ * 「音频有、但本机没准备好」的说明（解码 / 写缓存失败）。
+ *
+ * 与 [VOICE_SILENT_NOTE] 分开是必须的：这一档的真相是**本端**的问题，而文字照样在
+ * （[voiceReplyText] 已经把它取出来了），所以用户至少还能读到她说的话。
+ */
+const val VOICE_REPLY_LOCAL_UNAVAILABLE_NOTE: String = "这段语音本机没能准备好，先看文字"

app/src/main/kotlin/top/yeij/cyrene/domain/chat/VoicePlayback.kt

@@ -0,0 +1,121 @@
+package top.yeij.cyrene.domain.chat
+
+/**
+ * 语音播放的**状态**（纯数据，可单测）。
+ *
+ * ## 为什么要有它，而不是让每个气泡各自 `remember { mutableStateOf(false) }`
+ * 同一时刻**只能有一条语音在响**（一台设备一个喇叭，两条语音叠着放一定是 bug），而
+ * 「哪一条在响」是**跨气泡**的事实：用户点了另一条，前一条必须停下来并释放解码器。
+ * 于是这份状态由**一条播放通道**持有，气泡只是它的视图。四个态刻意只有四个：
+ *
+ * - [Idle]：什么都没在放（也是「停下来之后」唯一的终点）；
+ * - [Loading]：字节在取（首次播放要先下载；第二次起走本地缓存，一闪而过）；
+ * - [Playing]：真的在响（`MediaPlayer` 已经 `start()` 过，还没走完 / 还没被停）；
+ * - [Failed]：**这一次尝试**没成功，[Failed.message] 是给用户看的那句话。
+ *
+ * [Failed] 携带的是**这条消息**的失败（不是全局横幅）：用户点的是这一条，出问题的是这一条。
+ * 它**不粘**：再点一次就从 [Loading] 重新开始（见 [pressed]）。
+ *
+ * ## 每条转换都带 `messageId`，因为回调会迟到
+ * `MediaPlayer` 的回调（prepared / completion / error）与取字节的协程都可能**在用户已经改主意
+ * 之后**才到达。所以每一次转换都要**比对目标**：过期的回调**一个都不许**改状态
+ * （[prepared] / [failed] / [finished] 的同一条纪律）。这不是防御性编程的洁癖——
+ * 少了它就会出现「播放器已经换了、界面还显示上一条在响」。
+ */
+sealed interface VoicePlaybackState {
+
+    /** 没有被这条通道占着的消息（初始态，也是停 / 出错 / 放完之后的终点）。 */
+    data object Idle : VoicePlaybackState
+
+    /** 正在取这一条的字节（下载 / 读缓存）。 */
+    data class Loading(val messageId: String) : VoicePlaybackState
+
+    /** 这一条正在响。 */
+    data class Playing(val messageId: String) : VoicePlaybackState
+
+    /** 这一条的上一次尝试没成；[message] 是给用户看的那句话（见 `voicePlaybackFailureMessage`）。 */
+    data class Failed(val messageId: String, val message: String) : VoicePlaybackState
+}
+
+/**
+ * 这条消息此刻正被这条播放通道占着吗（[VoicePlaybackState.Loading] 或
+ * [VoicePlaybackState.Playing]）。
+ *
+ * [VoicePlaybackState.Failed]**不算**：它表示这条已经不在放，用户再点一下就是「重试」。
+ */
+fun VoicePlaybackState.isActiveFor(messageId: String): Boolean = when (this) {
+    is VoicePlaybackState.Loading -> this.messageId == messageId
+    is VoicePlaybackState.Playing -> this.messageId == messageId
+    else -> false
+}
+
+/** 这条消息**正在响**吗（只认 [VoicePlaybackState.Playing]，加载中不算）。 */
+fun VoicePlaybackState.isPlayingFor(messageId: String): Boolean =
+    this is VoicePlaybackState.Playing && messageId == this.messageId
+
+/**
+ * 这条消息**正在取字节**吗（只认 [VoicePlaybackState.Loading]）。
+ *
+ * 与 [isPlayingFor] 分开是必须的：「正在加载」与「正在响」对用户是两件事，界面上那句
+ * 「加载中…」只能在**真的在加载**时出现——混着用会让一条 30 秒的语音在整段播放期间都写着
+ * 「加载中…」。
+ */
+fun VoicePlaybackState.isLoadingFor(messageId: String): Boolean =
+    this is VoicePlaybackState.Loading && messageId == this.messageId
+
+/**
+ * 这条消息上一次尝试失败时那句提示；不是它 / 没失败过就回 `null`（气泡据此决定画不画那一行）。
+ */
+fun VoicePlaybackState.failureOf(messageId: String): String? =
+    (this as? VoicePlaybackState.Failed)?.takeIf { it.messageId == messageId }?.message
+
+/**
+ * 用户点了这条消息的播放 / 暂停。
+ *
+ * - 点的是**正在放 / 正在加载的那一条** ⇒ 回 [VoicePlaybackState.Idle]（= 停，调用方据此停下
+ *   并释放；「再点一下取消」对加载中同样成立——用户不该被一个慢下载困住）；
+ * - 点的是别的（或上一次失败的）那一条 ⇒ 换成它的 [VoicePlaybackState.Loading]。
+ *
+ * 有一条**调用方职责**不在状态里：进入 [VoicePlaybackState.Loading] 之前必须把上一条真的停掉
+ * （见 `ui.chat.VoicePlayer.toggle`）。纯函数只说「状态应该变成什么」。
+ */
+fun VoicePlaybackState.pressed(messageId: String): VoicePlaybackState =
+    if (isActiveFor(messageId)) VoicePlaybackState.Idle else VoicePlaybackState.Loading(messageId)
+
+/**
+ * 字节到手、`MediaPlayer` 已经 `start()` 过：`Loading(同一条)` ⇒ `Playing(同一条)`。
+ *
+ * 目标不对（用户已经点了别的 / 点了停）或当前不是 `Loading` 时**原样返回**——迟到的回调不许
+ * 把界面从「另一条在响」拽回来。
+ */
+fun VoicePlaybackState.prepared(messageId: String): VoicePlaybackState =
+    if (this is VoicePlaybackState.Loading && this.messageId == messageId) {
+        VoicePlaybackState.Playing(messageId)
+    } else {
+        this
+    }
+
+/**
+ * 取字节 / 起播失败：`Loading(同一条)` ⇒ `Failed(同一条, message)`；其余情况原样返回。
+ *
+ * 只从 [VoicePlaybackState.Loading] 出发是刻意的：**正在响的那一条**不会被一个迟到的失败
+ * 回调说成失败（`Playing` 阶段的解码错误走 [finished] 那条路，由播放器自己先停下再报）。
+ */
+fun VoicePlaybackState.failed(messageId: String, message: String): VoicePlaybackState =
+    if (this is VoicePlaybackState.Loading && this.messageId == messageId) {
+        VoicePlaybackState.Failed(messageId, message)
+    } else {
+        this
+    }
+
+/** 放完了：`Playing(同一条)` ⇒ [VoicePlaybackState.Idle]（播完就回初始外观，不留痕迹）。 */
+fun VoicePlaybackState.finished(messageId: String): VoicePlaybackState =
+    if (isPlayingFor(messageId)) VoicePlaybackState.Idle else this
+
+/**
+ * 停下来（用户点了停 / 换了另一条 / 离开会话 / 组件销毁）⇒ [VoicePlaybackState.Idle]。
+ *
+ * **任何态都收**，包括 [VoicePlaybackState.Failed]：失败那句话的生命周期与这一次尝试绑定，
+ * 换了目标或页面重进就不该再挂着。
+ */
+val VoicePlaybackState.silenced: VoicePlaybackState get() = VoicePlaybackState.Idle

app/src/main/kotlin/top/yeij/cyrene/domain/chat/VoiceSpeak.kt

@@ -0,0 +1,167 @@
+package top.yeij.cyrene.domain.chat
+
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.parse.ParsedBubble
+import top.yeij.cyrene.domain.parse.parse
+
+/**
+ * 「把这条消息念出来」这条路上，**本端要说的那几句话**，以及失败该分到哪一档。
+ *
+ * 这个文件里全是纯函数 / 常量，没有 Android、没有网络、没有状态：单测直接调（见
+ * `VoiceSpeakTest`）。真正的取字节在 `data.voice.SpeechClient`，播放复用 `ui.chat.VoicePlayer`。
+ */
+
+/**
+ * 从一条消息解析出来的气泡里抽出**要念的那段纯文本**。
+ *
+ * ## 为什么只念 `body`
+ * [ParsedBubble] 把一条气泡拆成三段：`head`（说话人抬头）、`body`（正文）、`tail`（旁白 / 动作）。
+ * 念出来时**只念正文**：
+ * - `head` 是「昔涟：」这种抬头，念出来像在念字幕；
+ * - `tail` 里的旁白（`*她笑了笑*`）与动作（`[动作]`）是**舞台指示**，语音合成念它只会变成一串
+ *   莫名其妙的字面量。
+ *
+ * ## 为什么按 `\n` 拼、且空就回 `null`
+ * 一条消息可能被切成多个气泡（连续说两段）；`\n` 让合成的停顿落在段落之间，比空格自然。
+ * 全都为空（纯附件消息、纯旁白消息、或者解析完什么都不剩）时回 `null` —— 调用方据此**不显示**
+ * 朗读入口，而不是让用户点一个必然拿到 `400` 的按钮。
+ *
+ * 取完 `trim`：首尾空白会变成合成音频开头 / 结尾的静音，没有任何用处。
+ */
+fun ttsTextOf(bubbles: List<ParsedBubble>): String? =
+    bubbles.asSequence()
+        .map { it.body }
+        .filter { it.isNotBlank() }
+        .joinToString("\n")
+        .trim()
+        .takeIf { it.isNotEmpty() }
+
+/**
+ * 一条消息（`content` + `mode`）里**要念的那段文本**；`null` = 没有可念的正文。
+ *
+ * 这是「这条消息能不能朗读」的**唯一判据**：`ChatViewModel.speak` 用它决定发不发请求，
+ * `MessageBubble` 用它决定画不画那枚图标。两处必须是同一个答案 —— 画了却发不出去、或者能发
+ * 却不给入口，都是 bug。
+ *
+ * ## 为什么要看 `mode`
+ * `chat`（或缺席）是「按 markup 切气泡的聊天式渲染」；其余 mode 下气泡里放的是**原文**，
+ * 一条 markup 都不解析（`MessageBubble` 就是这么画的）。朗读要念的显然也是**用户看到的那段字**：
+ * - 聊天式 ⇒ 走 [ttsTextOf] 剥掉抬头 / 旁白；
+ * - 其余 ⇒ 原文原样，只 `trim`。
+ *
+ * 判据本身与 `MessageBubble` 里那句 `isChat` 一字不差，刻意留在这里一份：多写一份就会出现
+ * 「界面按一种切法、朗读按另一种切法」的分叉。
+ */
+fun ttsTextOf(message: HistoryMessageDto): String? =
+    if (message.mode.isNullOrBlank() || message.mode == "chat") {
+        ttsTextOf(parse(message.content).filterNot { it.isEmpty })
+    } else {
+        message.content.trim().takeIf { it.isNotEmpty() }
+    }
+
+/**
+ * 一次朗读失败该归到哪一档 —— 判据只看**服务端到底说了什么**，不看 HTTP 码的表面。
+ *
+ * ## 为什么分两档
+ * 这两档对用户的意思完全不同，混成一句就等于什么都没说：
+ * - [Soft]：**这会儿**没读出来（网络断了、令牌过期、网关抽风）。过一会儿再点是**有意义**的，
+ *   所以文案只陈述事实、不诱导、也不吓人；
+ * - [Unconfigured]：**配置**上就没这条路的。服务端明说了是哪种缺（`tts_persona_unmapped`
+ *   没有发音人映射 / `tts_no_character` 连生效人格都没有），重试**永远不会**成功 —— 所以文案要说
+ *   清「缺什么」，并且**不提重试**（提了就是在骗人点）。
+ */
+sealed interface TtsFailure {
+
+    /** 要说给用户的那一句话。 */
+    val message: String
+
+    /** 再点一次**可能**有用吗？（[Unconfigured] 恒 `false`：重试永远不会成功。） */
+    val retryable: Boolean
+
+    /** 这会儿没读出来：不解释原因（本端确实不知道是哪一段断了），也不诱导重试。 */
+    data object Soft : TtsFailure {
+        override val message: String = TTS_SOFT_FAILURE_MESSAGE
+        override val retryable: Boolean = true
+    }
+
+    /**
+     * 服务端明说了配置缺一块。[code] 就是服务端那个错误码（原样留着，排查时对得上号）。
+     */
+    data class Unconfigured(val code: String) : TtsFailure {
+        override val message: String = when (code) {
+            TTS_CODE_PERSONA_UNMAPPED -> TTS_PERSONA_UNMAPPED_MESSAGE
+            TTS_CODE_NO_CHARACTER -> TTS_NO_CHARACTER_MESSAGE
+            // 兜底：服务端回了一个本端还不认识的「配置缺失」类错误码。不猜它的意思，
+            // 但也不装作是临时故障——它毕竟带着一个明确的 code。
+            else -> TTS_UNCONFIGURED_MESSAGE
+        }
+        override val retryable: Boolean = false
+    }
+}
+
+/**
+ * 把一次朗读的异常分到 [TtsFailure] 两档里。
+ *
+ * 只有「服务端明确回了一个**配置缺失**类的 `code`」才进 [TtsFailure.Unconfigured]；其余一切
+ * ——网络失败、解析失败、401（令牌过期，续期后还能用）、`voice_unavailable` / `tts_failed` /
+ * `tts_empty`（对面这会儿不行，不是本端的配置问题）——都进 [TtsFailure.Soft]。
+ *
+ * `tts_empty`（静默空音频）刻意归到柔和档：那是**这一次**合成出来的东西不能用，换个时间再试
+ * 完全可能成功，说成「配置没配好」就是错的。
+ */
+fun ttsFailureOf(error: Throwable): TtsFailure {
+    val cause = (error as? CyreneException)?.error ?: return TtsFailure.Soft
+    return when (cause) {
+        is CyreneError.Server -> when (cause.code) {
+            TTS_CODE_PERSONA_UNMAPPED,
+            TTS_CODE_NO_CHARACTER,
+            -> TtsFailure.Unconfigured(cause.code)
+
+            else -> TtsFailure.Soft
+        }
+
+        is CyreneError.Unauthorized -> TtsFailure.Soft
+        is CyreneError.Local -> TtsFailure.Soft
+    }
+}
+
+/**
+ * 朗读在某一条播放通道上的**键**：`tts:<messageId>`。
+ *
+ * 播放通道只有一条（`ui.chat.VoicePlayer` 的那个实例，与语音副本共用），所以键必须与语音副本
+ * （键 = `voice` 的 `messageId`）分得开：前缀就是那道分界线。同一条消息的朗读与它的语音副本
+ * 因此**互斥**（点其中一个会停掉另一个）——这是对的，同一时刻只该有一个声音。
+ */
+fun ttsClipIdOf(messageId: String): String = TTS_CLIP_PREFIX + messageId
+
+/** 朗读入口那枚图标的读屏名字（也是设备验收时 `uiautomator` 的 `content-desc`）。 */
+const val TTS_SPEAK_DESCRIPTION: String = "朗读这条消息"
+
+/** 正在朗读时那枚图标的读屏名字（点它 = 停）。 */
+const val TTS_STOP_DESCRIPTION: String = "停止朗读"
+
+/** 正在取合成音频时那枚图标的读屏名字。 */
+const val TTS_LOADING_DESCRIPTION: String = "正在准备朗读"
+
+/** 柔和档：这会儿没读出来。**不说原因**（本端确实不知道断在哪一段），也不提重试。 */
+const val TTS_SOFT_FAILURE_MESSAGE: String = "这会儿没能把这段读出来"
+
+/** `tts_persona_unmapped`：人格有，但这个人格没有配发音人。 */
+const val TTS_PERSONA_UNMAPPED_MESSAGE: String = "这个角色还没配好发音人"
+
+/** `tts_no_character`：连生效人格都没有（会话没绑定、也没有全局默认人格）。 */
+const val TTS_NO_CHARACTER_MESSAGE: String = "这个会话还没有配好发音人"
+
+/** 服务端回了配置缺失类错误码、但本端还不认识那一个时的兜底文案。 */
+const val TTS_UNCONFIGURED_MESSAGE: String = "这个角色还没有配好朗读的发音人"
+
+/** 朗读播放通道的键前缀（与语音副本的键 `messageId` 区分开）。 */
+const val TTS_CLIP_PREFIX: String = "tts:"
+
+/** 服务端错误码：人格没有发音人映射。 */
+const val TTS_CODE_PERSONA_UNMAPPED: String = "tts_persona_unmapped"
+
+/** 服务端错误码：连生效人格都没有。 */
+const val TTS_CODE_NO_CHARACTER: String = "tts_no_character"

app/src/main/kotlin/top/yeij/cyrene/domain/parse/ChatContentParser.kt

@@ -14,15 +14,48 @@ import kotlin.math.min
  *   - `<p>…</p>`：每个完整块 = 一条独立气泡；无完整 `<p>` 时回退按空行 `\n\s*\n` 切分；
  *     单个 `\n` 是句内换行，绝不切分。未闭合的 `<p>` 不构成块，按普通文本处理（流式下会先缓存）。
  *     `<p>` 之外的非空白正文不会被丢弃：并入相邻气泡（若只是旁白/空白则依附之，否则自成一气泡）。
+ *   - `<br>`（`<br>` / `<br/>` / `</br>` 三种写法等价，大小写不敏感，属性不解析）：**与 `<p>` 同级
+ *     的气泡/消息分隔符**（契约 v0.89 的更正：`回执三十一`「对消息内的 `<br>` 始终处理为多条消息
+ *     隔断」）。它**不是行内标签**：`<p>甲<br>乙</p>` ⇒ 两条气泡，`甲<br>乙`（无 `<p>`）⇒ 同样两条；
+ *     中间的空气泡照旧丢弃（`<p>甲<br><br>乙</p>` ⇒ `甲`、`乙`）。切分在 [tokenize] 的**段/块这一层**
+ *     完成（[appendRegion]），所以行内解析层（`InlineMarkup`）几乎看不见它。
+ *     ⚠️ `回执三十三 §三②` 把「**始终**分隔」收紧了：**只有普通文本层的 `<br>` 才分隔**——
+ *     `<code>` / `<action>` / `<narration>` **内部**的不分隔（[appendRegion] 的保护区，
+ *     口径与理由写在它和 [protectedSpans] 的 KDoc 里）。
  *   - `<action>…</action>` / `<narration>…</narration>`：旁白/动作，不独立成气泡，依附气泡：
  *     首部连续块 → 挂气泡上方（head）；尾部连续块 → 挂下方（tail）；夹在正文中间的块 → 上提到 head。
+ *     注记内部**不做行内渲染**（既有口径），所以里面的 `<br>` 与 `<b>` 一样只是字面文本。
  *   - 漂移兼容：全角 `＊…＊`（无关键词时要求去空白后 ≤40 字符且不含换行 → action）；
  *     半角 `*…*` 仅当以 动作/旁白/内心/神态/轻声 开头才算旁白，否则保持普通文本（不吞 Markdown 强调）。
  *     关键词 旁白/内心 → narration，其余 → action。
- *   - 未闭合/畸形的标签一律回落为普通文本，绝不抛异常。
+ *   - 行内标签（`InlineMarkup.kt`，契约 v0.89）：`<b>`/`<strong>`、`<i>`/`<em>`、`<code>`、`<u>`
+ *     （**六项**标签名——`u` 由 `回执三十三 §一` 加回、`s` 仍不在内），成对才认、**标签名大小写不敏感**、
+ *     **属性一律不解析**（`<b class=x>` 就是粗体）、白名单外按纯文本原样显示、
+ *     **结构不平衡（未闭合 / 落单闭标签 / 交错）⇒ 该气泡的正文整段降级为原文**
+ *     （口径与理由见 `parseInlineMarkup`）。
+ *     它在**段落与 `<br>` 都定稿之后**才做（[toBubble] 里对最终正文做一次，**逐气泡各自一份**），
+ *     所以既不参与、也改不动上面的分段与归属。渲染文本落 `body` + `runs`，而片段 `parts` 仍是
+ *     逐字原文——编辑框、搜索片段、通知文案读的都是 `parts`，那些地方一个字都不许改。
+ *   - 落单标签容错：服务端确实会产出不配对的段落标签（实测形态 `<p><p>正文</p>`：多一个 `<p>`、
+ *     只有一个 `</p>`），块外也可能出现孤立的旁白标签。这类标签一律**剥掉**，绝不落进正文——
+ *     它们本就是服务端产出的标记、不是她说的话；渲染成正文等于往气泡里塞一串用户既看不懂、
+ *     也改不掉的字符，而剥掉只是少显示几个本就不该出现的字符，正文一个字都不动。
+ *     这只是客户端的容错，不代表服务端这样发是对的。
+ *     判据（[stripLooseTags]）分两种情形：消息里**已有完整块**时，段落结构已被完整块定死，块内
+ *     块外多出来的每个 `<p>` / `</p>`、以及块外孤立的旁白标签，都是冗余噪声，一律剥掉（块内的
+ *     落单旁白标签例外，见最后一条）；消息里**一个完整块都没有**时，按上一条整段回落字面文本，
+ *     只再剥两类连「被截断的结构」都算不上的东西：落单的 `</p>`，与后面什么都没有的空开标签。
+ *     只认「确定是标签」的形状：`<p>` / `<p 属性>` / `</p>` / `<action>` 等。`1 < 2`、`<3`、
+ *     `a<b`、`<p2>`、`<P>`（词表只有小写，与 `MessageEditText` 同一口径）、`<p`（残缺，没有 `>`）
+ *     都原样保留——见到 `<` 就吃，才是真正会丢字的那种错。
+ *   - 未闭合/畸形的其余标签一律回落为普通文本，绝不抛异常。块内没配对的 `<action>` / `</action>`
+ *     也保持字面文本，这是既有契约（`unclosedActionFallsBackToText` / `strayClosingTagStaysText`）。
  *
  * `ParsedBubble` 结构（每条气泡渲染一个）：
- *   - `body`  ：气泡正文（仅 Text 部分按原顺序拼接后 trim），已剔除全部旁白/动作块；
+ *   - `body`  ：气泡正文的**渲染文本**（仅 Text 部分按原顺序拼接后 trim，再消费掉行内标签：
+ *     白名单标签字符已去掉，白名单外与属性照旧逐字留着），已剔除全部旁白/动作块；
+ *     整段只有标记没有字、或行内标签**结构不平衡**时回落/降级为字面原文；
+ *   - `runs`  ：`body` 的行内样式切分（非空时拼起来就是 `body`；空列表 = 按字面画）；
  *   - `parts` ：该气泡按原始顺序解析出的全部片段（Text / Action / Narration），供下钻使用；
  *   - `head`  ：要渲染在气泡上方的旁白/动作块（首部块 + 中间块「上提」）；
  *   - `tail`  ：要渲染在气泡下方的旁白/动作块（尾部连续块）。
@@ -34,9 +67,28 @@ import kotlin.math.min
  *     因此 `finish() == parse(全部 delta 拼接)` 恒成立（逐字符/任意切分均一致）。
  *   - 未确定片段从以下最早位置开始整体扣留，不产出半截结果：
  *       1) 未闭合的 `<action>` / `<narration>` / `<p>` 开标签（从该开标签起扣留）；
- *       2) 尾部残缺标签（如 `<act`、`</act`、`<p`），仅当它可能继续补全为合法标签时才扣留；
+ *          行内开标签同样入栈扣留（词表见 [INLINE_TAG_NAMES]，判据见 [parseInlineTag]）：不扣的话
+ *          中间态会把 `<b>` 当字面吐上屏（`日落 <b>18`）、等 `</b>` 到了又被吃掉，屏幕上已经显示过的
+ *          两个字就改口了。**大小写与属性也走同一份判据**（v0.89）：`<B class=x>` 在扣留侧同样是
+ *          开标签，否则 `日落 <B class=x>18` 会先按字面吐上屏、收口时再变成粗体。
+ *          `<br>` 是分隔符、不成对，**不入栈**（入了就永远弹不出来）；它只在残缺（`<br`、`<br/`、
+ *          `</br`）时按词表扣留（[isPotentialTagPrefix] → [couldBeTagName]），完整的 `<br>` 直接放行
+ *          ——分隔符一出现，前缀就已经可解析了。
+ *          **保护区内的 `<br` 另外还有一道**：`<code>` / `<action>` / `<narration>` 的开标签本来就在
+ *          栈里，所以整个作用域（连同里面还没写完的 `<br`）一起被扣到闭合为止，残缺的 `<br` 不会
+ *          在半截作用域里先露一次脸（由 `streamingWithholdsPartialLineBreakInsideProtectedScopes` 钉着）。
+ *       2) 尾部残缺标签（如 `<act`、`</act`、`<p`、`<B`、`<br`），仅当它可能继续补全为合法标签时才扣留；
  *       3) 最近一个完整标签之后（自由文本区）的孤立全角 `＊`；
  *       4) 自由文本区中可能开启关键词半角星号（如 `*动`）的孤立 `*`。
+ *   - 落单标签的剥离**不需要**额外的扣留规则，这是「剥标签与扣留共用同一组标签正则」的直接结果：
+ *     扣留点取「第一个没闭合的开标签」，而落在前缀里的每个 `<p>` / `<action>` 开标签必定在
+ *     **同一个前缀内**配到闭合标签（否则它就是那个没闭合的，扣留点会落在它前面）。所以
+ *     「这个标签是不是落单的」在它被产出的那一刻就已经定死，中间态剥掉、收口时也不用再改口。
+ *   - 反过来放宽扣留是不行的：把重复的 `<p><p>` 当「外层冗余」让前缀继续推进，`<p>甲<p>乙`
+ *     就会在中间态把 `<p>甲` 当字面文本吐上屏，等 `</p>` 到了又变成 `甲乙`——字会跳。
+ *     剥标签与扣留的标签词表因此必须逐字一致（共用 OPEN_P_TAG_RE / CLOSE_P_TAG_RE /
+ *     OPEN_ROLE_TAG_RE / CLOSE_ROLE_TAG_RE，无大小写、无词表扩展），两边一旦分叉，
+ *     就会出现「中间态当正文、收口时又剥掉」的跳动。
  *   - 标签残缺判断只影响「何时产出」，不影响最终结果；扣留期间不会抛异常。
  *   - 本类无副作用、非线程安全，调用方保证单线程喂入即可。
  */
@@ -61,6 +113,16 @@ data class ParsedBubble(
     val parts: List<ContentPart>,
     val head: List<ContentPart>,
     val tail: List<ContentPart>,
+    /**
+     * `body` 的行内样式切分（`<b>` / `<i>` / `<code>` / `<u>`，见 [parseInlineMarkup]）：非空时
+     * 拼起来**就是** [body]。空列表 = 这段正文按字面画——**绝大多数消息都走这一档**（没有标签、
+     * 或者结构不平衡被整段降级、或者整段只有标记没有字）。
+     *
+     * 有默认值，是因为只有 [toBubble] 才该填它：其余构造点要么本来就该按字面画（`plainBubble`、
+     * 分享预览的兜底 `sharePreviewBlocks`），要么是测试里的手搓气泡。这也让「加一个字段」不必
+     * 惊动任何一个既有调用方。
+     */
+    val runs: List<InlineRun> = emptyList(),
 ) {
     val isEmpty: Boolean
         get() = body.isEmpty() && head.isEmpty() && tail.isEmpty()
@@ -91,12 +153,43 @@ private val BLANK_LINE_RE = Regex("\\n\\s*\\n")
 /** 无关键词的全角星块超过此长度即视为普通文本（对齐 Web `STAR_SHORT_RUNES`）。 */
 private const val FULL_STAR_MAX_LEN = 40
 
-private val TAG_NAMES = listOf("action", "narration", "p")
+/**
+ * 段落/旁白标签名（**只有小写**，与 `MessageEditText` 同一口径）：流式边界判定 [isPotentialTagPrefix]
+ * 补全残缺标签时用；[stripLooseTags] 判「是不是标签」用的是下面那组同词表的正则，两边必须同源。
+ *
+ * `<br>` 不在这个名单里：它是分隔符、且**大小写不敏感**（见 [BR_TAG_RE]），判据单独走
+ * [couldBeLineBreakNamePrefix]，否则 `<BR` 会被漏扣、中间态把 `<BR` 当正文吐上屏。
+ */
+private val STRUCTURE_TAG_NAMES = listOf("action", "narration", "p")
 private val OPEN_ROLE_TAG_RE = Regex("^<\\s*(action|narration)\\s*>$")
 private val CLOSE_ROLE_TAG_RE = Regex("^</\\s*(action|narration)\\s*>$")
 private val OPEN_P_TAG_RE = Regex("^<p(\\s[^>]*)?>$")
 private val CLOSE_P_TAG_RE = Regex("^</p>$")
 
+/** `<br>` 分隔符的标签名（[BR_TAG_RE] 与流式扣留侧共用，别在两处各写一遍）。 */
+private const val LINE_BREAK_TAG_NAME = "br"
+
+/**
+ * `<br>` **分隔符**（契约 v0.89 更正：`<br>` 不是行内标签，而是与 `<p>` 同级的「气泡/消息分隔符」）。
+ *
+ * 认下来的形状：`<br>` / `<br/>` / `<br />` / `</br>` / `<br class=x>` …——
+ *   - **三种写法等价**，前导 `/` 与自闭合 `/` 都照收（HTML5 口径，契约写死）；
+ *   - **大小写不敏感**（`<BR>` / `<Br>` 同样算）：v0.89 那句「标签名大小写不敏感」把 `br` 一起罩住了，
+ *     且后端 IM 出站 `channelbridge/sanitize.go` 的正则本来就是 `(?is)`（`回执三十` 的原话）；
+ *   - **属性不解析**（`<br class=x>` 照样分隔），但名字后面必须紧跟 `>`、空白或 `/`：
+ *     `<br2>` / `<boolean>` / `<br-x>` 因此**不是**分隔符，只是普通文本（这一条是「字符一个不丢」的闸门）。
+ *
+ * ⚠️ 已知边界：它**不看外层标签的属性结构**——所以写成 `<b title="<br>">甲</b>` 这种「属性里带 `<br>`」的
+ * 文本会被切开（`回执三十三 §三③` 登记为两端口径相同、不修）。`<p …>` 开标签是唯一例外，因为它在更早
+ * 一层就被 [P_BLOCK_RE] 整体吃掉了，属性里的 `<br>` 根本走不到这里。真实产出里没有这种形状
+ * （属性本身就不是产出侧的东西）。
+ *
+ * ⚠️ 它只认**普通文本层**的那些：`<code>` / `<action>` / `<narration>` **内部**的 `<br>` 由
+ * [appendRegion] 按保护区跳过（`回执三十三 §三②`）——所以 `findAll` 的结果**不再是**「所有分隔点」，
+ * 用它时要么走 [appendRegion]（会跳保护区），要么自己判一遍（别处没第二个消费者）。
+ */
+private val BR_TAG_RE = Regex("<\\s*/?\\s*${LINE_BREAK_TAG_NAME}(\\s[^<>]*|/\\s*)?>", RegexOption.IGNORE_CASE)
+
 /** 一次性解析：把一条消息的原始文本拆成若干独立气泡（含旁白依附关系）。 */
 fun parse(raw: String): List<ParsedBubble> {
     if (raw.isEmpty()) return emptyList()
@@ -144,29 +237,339 @@ private sealed interface Tok {
     object Break : Tok
 }
 
-/** 先切 `<p>` 块（决定气泡边界），再在每个文本区做旁白/星号解析。 */
+/**
+ * 先切 `<p>` 块（决定气泡边界），再按区剥落单标签与切 `<br>` 分隔符，最后在每个文本区做旁白/星号解析。
+ */
 private fun tokenize(raw: String): List<Tok> {
-    val pMatches = P_BLOCK_RE.findAll(raw).toList()
+    // 完整块必然以 `</p>` 收尾，所以最后一个 `</p>` 之后不可能再有块：切掉尾巴再让正则去扫。不切的话，
+    // 每个 `<p` 候选点都会带着懒惰的 `([\s\S]*?)</p>` 一路回溯到串尾——正文里 N 个落单标签时
+    // 这里就是 O(N²)：实测 20000 个要 8.2 秒（同一输入下 `stripLooseTags` 那边还要 23 秒，见
+    // [ContentAfterQuery]）。切掉后同一输入 1 毫秒内出结果，且匹配结果逐字不变（每个匹配都整体落在
+    // 被切下的前缀里，正则的尝试顺序也没变）。
+    val lastClose = raw.lastIndexOf("</p>")
+    val pMatches =
+        if (lastClose < 0) {
+            emptyList()
+        } else {
+            P_BLOCK_RE.findAll(raw.substring(0, lastClose + "</p>".length)).toList()
+        }
     val out = ArrayList<Tok>()
     if (pMatches.isEmpty()) {
-        appendAnnotations(raw, out, splitBlankLines = true)
+        // 一条完整块都没有：`<p>` 及其后内容按既有契约整段回落字面文本，`<action>` 这类旁白标签
+        // 落单时同理（`MessageEditTextTest.没闭合的 action 同样原样留着`）。此处只剥掉连「被截断的
+        // 结构」都算不上的东西：落单的 `</p>`，与后面什么都没有的空开标签。判据见 [stripLooseTags]。
+        appendRegion(raw, out, markupMode = false, stripStrayRoleTags = false, splitBlankLines = true)
         return out
     }
     var last = 0
     for (m in pMatches) {
         val lead = raw.substring(last, m.range.first)
-        if (lead.isNotEmpty()) appendAnnotations(lead, out, splitBlankLines = false)
+        if (lead.isNotEmpty()) {
+            appendRegion(lead, out, markupMode = true, stripStrayRoleTags = true, splitBlankLines = false)
+        }
         out.add(Tok.Break)
         val inner = m.groupValues[2]
-        if (inner.isNotEmpty()) appendAnnotations(inner, out, splitBlankLines = false)
+        if (inner.isNotEmpty()) {
+            // 块内只剥 `<p>` 族：`<action>` / `</action>` 落单时保留字面文本，是既有契约
+            // （unclosedActionFallsBackToText / strayClosingTagStaysText 钉住的行为）。
+            appendRegion(inner, out, markupMode = true, stripStrayRoleTags = false, splitBlankLines = false)
+        }
         out.add(Tok.Break)
         last = m.range.last + 1
     }
     val trail = raw.substring(last)
-    if (trail.isNotEmpty()) appendAnnotations(trail, out, splitBlankLines = false)
+    if (trail.isNotEmpty()) {
+        appendRegion(trail, out, markupMode = true, stripStrayRoleTags = true, splitBlankLines = false)
+    }
     return out
 }
 
+/**
+ * 解析一个文本区：先剥落单标签（[stripLooseTags]，`markupMode` / `stripStrayRoleTags` 由调用方给），
+ * 再按 `<br>` 分隔符切成若干段，每段各自做旁白/星号解析（[appendAnnotations]），段与段之间补一个
+ * [Tok.Break]（气泡边界）。
+ *
+ * **为什么 `<br>` 在这一层切**：契约 v0.89 的更正把 `<br>` 定成**与 `<p>` 同级的分隔符**
+ * （`回执三十一`「对消息内的 `<br>` 始终处理为多条消息隔断」）。它既然与 `<p>` 同级，就该与 `<p>`
+ * 走**同一套机制、同一个粒度**：产生 [Tok.Break]、由 `buildBubbles` 分组、空气泡照旧丢弃。
+ * 行内层（`InlineMarkup`）因此几乎看不见 `<br>` —— 那里只剩六个白名单标签（唯一例外见下面的保护区：
+ * `<code>` 内部的那个 `<br>` 会随正文交到行内层，在那里按「内容」字面显示）。
+ *
+ * **顺序：先切分、再逐段各自做行内解析**（`<b>甲<br>乙</b>` ⇒ 两段各按「不平衡 ⇒ 不渲染」处理，
+ * 两段都回落原文）。理由：
+ *   1. 「与 `<p>` 同级」这句话本身就规定了层序——分隔符先于行内解析，行内解析永远只看到**一段**；
+ *      跨过分隔符的标签在结构上不可能成立（一个气泡 = 一条消息，IM 出站也是先按气泡切开再剥标签，
+ *      后端 `sanitize.go` 的「成对平衡 ⇒ 剥标签留文本 / 不平衡 ⇒ 原样保留」同样是在**单条消息内**
+ *      判平衡的）⇒ 两端对同一段文本的结论天然一致；
+ *   2. 反过来（先整体行内解析、再按 `<br>` 切）会让「渲染文本」与「气泡」互相依赖：`<b>甲<br>乙</b>`
+ *      会先变成一个粗体片段再被切开，切点落在片段内部，`body` / `runs` 的一致性（`runs` 拼起来
+ *      **就是** `body`）当场就没了；
+ *   3. 实现上也最省：行内那层一个字节都不用改（它本来就逐气泡跑一次）。
+ *
+ * 剥标签**先于**切分（判据逐字不变）：[stripLooseTags] 里「这个落单 `<p>` 后面还有没有正文」看的是
+ * 整段原文，`<br>` 在那里只是一个普通字符，所以同一输入下它的判定与 W68 完全相同。
+ *
+ * ## 保护区：`<code>` 与角色注记**内部**的 `<br>` 不分隔（`回执三十三 §三②`）
+ * `回执三十一` 说的是「**始终**分隔」，`回执三十三` 把它收紧了：**只有普通文本层的 `<br>` 才分隔**。
+ * 后端给的两条理由在我们这边一字不差地同样成立，所以照改：
+ *   1. **会漏注记正文**：`<action>她<br>点点头</action>` 若切成两段，就成了「她」「点点头」**两条消息**
+ *      ——注记本来是不该当正文露出来的那一层，切开等于把它摆到台面上（后端原话：「那等于把注记正文
+ *      发给了对方」）；
+ *   2. **`<code>` 会被切坏**：它是**成对**元素，从中间切开必然两半都不平衡，按「不平衡 ⇒ 不渲染」的
+ *      硬口径**整段降级为字面量**，用户直接看到裸标签。
+ *
+ * 实现：先扫出保护区区间（[protectedSpans]），切分时**跳过**落在区间里的 `<br>`（它留在原文里，随该
+ * 作用域自己的语义走）。扫的是**已经剥过落单标签**的那一份文本，与切分用的是同一个对象。
+ *
+ * ### 作用域内部算什么语义（我们定的口径）：**普通字符、逐字原样**（不换行、也不消掉）
+ *   - `<code>`：这是它**既有的**口径——「里面连白名单标签也按内容处理」，`<code><b>甲</b></code>`
+ *     显示字面的 `<b>甲</b>`（`codeContentIsNotParsed` 钉着）。`<br>` 在这一层本来不是标签，用不着
+ *     另立规矩；`<code>` 也正好是「想原样显示尖括号怎么办」的现成答案。
+ *   - `<action>` / `<narration>`：**必须是字面**。注记那一行画的是 `parts` 里的原文
+ *     （`MessageBubble.AnnotationLine` 直接 `parts.joinToString`），而 `parts` = **逐字原文**是红线
+ *     ——换成 `\n` 或删掉，就是在静默改用户内容（编辑框、搜索、通知读的都是它）。顺带也就与既有
+ *     口径对齐：`<action>笑<b>了</b></action>` 里的 `<b>` 同样是字面（`narrationTextIsLeftExactlyAsWritten`）。
+ *   - 两个作用域取**同一条**规矩：它们是同一件事（`<br>` 落在作用域内部），各给一种读法才是真的
+ *     「各端各说各话」。
+ *   - 为什么不把它当换行（`<code>甲<br>乙</code>` ⇒ `甲\n乙`）：那必须在一处破例——要么在这里改掉
+ *     片段文本（`parts` 当场不再是原文），要么在行内层给 `<br>` 单开一条「代码里它算换行」的规则
+ *     （W68 刚把「`<br>` → `\n`」从行内层整体删掉，而且那会让**同两个字符**在 `<code>` 与 `<action>`
+ *     里各是一种意思）。两条都不值当，所以不做。
+ *
+ * ### 未闭合的作用域：**不算作用域**，里面的 `<br>` 照旧分隔
+ * 判据只看「**成对**」，且与各自的消费侧同一把尺子：`<code>` 要找到它的 `</code>`（大小写不敏感、
+ * 可带属性——行内层就这么认），`<action>` / `<narration>` 要找到**同名**闭合（只认小写、不带属性
+ * ——`ROLE_RE` 就这么认）。找不到闭合的开标签不是作用域，于是 `<code>甲<br>乙` 照旧切成两条。
+ *   - 理由一：**消费侧本来就不认它**。未闭合的 `<code>` 在行内层不是作用域（整段降级为原文），
+ *     未闭合的 `<action>` 在 `ROLE_RE` 那里也配不出旁白。去保护一个**消费侧根本不认**的作用域，
+ *     等于让「切分层」与「消费层」对同一段文本有两种结构判断——正是本项目一路在防的那种分叉
+ *     （W68/W69 的教训：消费侧与扣留侧的词表必须同源）。
+ *   - 理由二：**爆炸半径**。若把「未闭合 ⇒ 保护到这一段文本结尾」也算上，一个漏掉 `</code>` 的笔误
+ *     就会把**后面所有** `<br>` 一起吞掉、把本该分开的多条消息并成一条。「一个畸形标签改变整段的
+ *     分段」比「照旧分隔」坏得多。
+ *   - 两种读法都不渲染、都不丢字（未闭合那一档本来就是「不平衡 ⇒ 原样显示」），差别只在气泡怎么切；
+ *     我们选与消费侧一致的那种。
+ *   - **两支各算各的**（[protectedSpans] 用两个独立状态）：`<code>` 与角色注记各自配对，因为那本来
+ *     就是两个消费侧各自的尺子——行内层在 `<code>` 里只认自己的闭合、别的一律当内容；`ROLE_RE`
+ *     则完全不看 `<code>`（它在代码里照样配对）。所以「某一支没闭合」只影响**那一支**：
+ *     `<code>甲<action>她<br>点点头</action>乙` 里那个**已经配对好**的 `<action>` 照样保护它的
+ *     `<br>`（不产生区间的只是没闭合的 `<code>` 那一支）。
+ */
+private fun appendRegion(
+    text: String,
+    out: MutableList<Tok>,
+    markupMode: Boolean,
+    stripStrayRoleTags: Boolean,
+    splitBlankLines: Boolean,
+) {
+    val stripped = stripLooseTags(text, markupMode, stripStrayRoleTags)
+    // 保护区只在「这一区里真有作用域」时才扫：绝大多数消息连 `<` 都没有（一个字节都不多花）。
+    val protected = if (stripped.indexOf('<') < 0) emptyList() else protectedSpans(stripped)
+    var last = 0
+    var span = 0
+    for (m in BR_TAG_RE.findAll(stripped)) {
+        val at = m.range.first
+        // 区间按起点升序，跟着 `<br>` 的推进往前走一个游标就够（不回头、不重扫）。
+        while (span < protected.size && protected[span].last < at) span++
+        if (span < protected.size && at in protected[span]) continue
+        val piece = stripped.substring(last, at)
+        if (piece.isNotEmpty()) appendAnnotations(piece, out, splitBlankLines)
+        out.add(Tok.Break)
+        last = m.range.last + 1
+    }
+    val tail = stripped.substring(last)
+    if (tail.isNotEmpty()) appendAnnotations(tail, out, splitBlankLines)
+}
+
+/**
+ * 扫出这一区里**已配对**的保护区区间（左闭右开，按**起点**升序）：`<code>…</code>` 与
+ * `<action>…</action>` / `<narration>…</narration>`——[appendRegion] 据此跳过落在里面的 `<br>`
+ * （口径与理由写在它的 KDoc 里）。
+ *
+ * 一趟线性扫描，判据全部借现成的尺子：「哪儿是一个标签」用行内层的 [inlineTagEnd]；`code` 用
+ * 行内层的 [openInlineTagName] / [closeInlineTagName]（大小写不敏感、可带属性）；角色注记用
+ * [openNoteTagName] / [closeNoteTagName]（与 `ROLE_RE` 同口径：只认小写、不带属性、找**同名**闭合）。
+ *
+ * **两支各自独立配对**，因为那本来就是两个消费侧各自的尺子：`<code>` 那一支只认自己的开/闭
+ * （里面别的标签都是内容，与行内层一致）；角色那一支同理（与 `ROLE_RE` 的非贪婪配对一致——它
+ * 在 `<code>` 里照样配对，两边各算各的）。任一支没闭合 ⇒ **那一支**不产生区间。
+ *
+ * `indexOf('<')` + 逐段推进的扫描区间互不重叠（见 [inlineTagEnd]），每个 `<br>` 的判定是两个游标
+ * 各走一次，因此整体仍是 O(n)：成串的尖括号或成串的作用域都不会让它退回 O(N²)。
+ */
+private fun protectedSpans(text: String): List<IntRange> {
+    val codeSpans = ArrayList<IntRange>(2)
+    val noteSpans = ArrayList<IntRange>(2)
+    var openCode = -1
+    var openNoteName: String? = null
+    var openNote = -1
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是标签：往后挪**一个字符**（与 `claimTags` 同一把尺子，
+            // 不能跳到某个「下一个 `>`」——那会把中间真正的标签一起跳过）。
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        val end = gt + 1
+        if (openCode < 0) {
+            if (openInlineTagName(tag) == CODE) openCode = lt
+        } else if (closeInlineTagName(tag) == CODE) {
+            codeSpans.add(openCode until end)
+            openCode = -1
+        }
+        val noteOpen = if (openNoteName == null) openNoteTagName(tag) else null
+        if (noteOpen != null) {
+            openNoteName = noteOpen
+            openNote = lt
+        } else if (openNoteName != null && closeNoteTagName(tag) == openNoteName) {
+            noteSpans.add(openNote until end)
+            openNoteName = null
+        }
+        i = end
+    }
+    // 两支各自升序，合起来也按**起点**升序——[appendRegion] 的包含判定（「第一个右端 ≥ 这个 `<br>`
+    // 的区间」）以「按起点升序」为前提。合并后两支的区间可能相互嵌套（`<code>` 套注记、注记套
+    // `<code>`），那不影响判定：嵌套的那些都在同一个升序序列里。
+    return when {
+        noteSpans.isEmpty() -> codeSpans
+        codeSpans.isEmpty() -> noteSpans
+        else -> (codeSpans + noteSpans).sortedBy { it.first }
+    }
+}
+
+/** 角色注记的**开**标签名（只认小写的 `action` / `narration`、不带属性——与 `ROLE_RE` 同口径）。 */
+private fun openNoteTagName(tag: String): String? = OPEN_ROLE_TAG_RE.find(tag)?.groupValues?.get(1)
+
+/** 角色注记的**闭**标签名（同上；配对要求**同名**，与 `ROLE_RE` 的 `</\s*\1\s*>` 一致）。 */
+private fun closeNoteTagName(tag: String): String? = CLOSE_ROLE_TAG_RE.find(tag)?.groupValues?.get(1)
+
+/**
+ * 剥掉「落单标签」，其余字符逐字保留（返回原对象：没剥到东西时不做新分配）。
+ *
+ * [markupMode] = 这条消息里**已有完整 `<p>…</p>` 块**，段落结构已被完整块定死，于是块内/块外
+ * 多出来的每一个 `<p>` / `</p>` 都是冗余噪声，一律剥掉。
+ * 没有完整块时（`parse` 会整段回落字面文本，见 `unclosedParagraphStaysLiteralText`；编辑框也靠
+ * 这条保证不静默改字，见 `MessageEditTextTest.没闭合的 p 不抛异常`）只再剥两类不可能是正文的东西：
+ * 落单的 `</p>`，以及后面什么都没有的**空**开标签——它们连「被截断的段落」都算不上。
+ *
+ * [stripStrayRoleTags] 只对**块外**文本区为 true：那里的 `<action>` / `</action>` 若没被 [ROLE_RE]
+ * 认领（即没配成对），就是落单标签，剥掉。已配对的必须留给 [ROLE_RE] 解析成 Action/Narration，
+ * 提前剥掉等于把旁白降级为正文（`textOutsideParagraphsIsPreserved` 钉住的行为）。
+ */
+private fun stripLooseTags(text: String, markupMode: Boolean, stripStrayRoleTags: Boolean): String {
+    if (text.indexOf('<') < 0) return text
+    val roleRanges = if (stripStrayRoleTags) ROLE_RE.findAll(text).map { it.range }.toList() else emptyList()
+    // 「这个落单 `<p>` 后面还有没有正文」按位置记表：正文里 N 个落单标签，现扫是 O(N²)（见
+    // [ContentAfterQuery] 的 KDoc）。常规消息（没有落单 `<p>` 开标签）一次都不建表。
+    val contentAfter = ContentAfterQuery(text)
+    val out = StringBuilder(text.length)
+    var last = 0
+    var i = 0
+    while (i < text.length) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = text.indexOf('>', lt)
+        if (gt < 0) break
+        val tag = text.substring(lt, gt + 1)
+        val drop = when {
+            OPEN_P_TAG_RE.matches(tag) -> markupMode || !contentAfter.hasContentAfter(gt + 1)
+            CLOSE_P_TAG_RE.matches(tag) -> true
+            !stripStrayRoleTags -> false
+            roleRanges.any { lt in it } -> false
+            else -> OPEN_ROLE_TAG_RE.matches(tag) || CLOSE_ROLE_TAG_RE.matches(tag)
+        }
+        if (drop) {
+            out.append(text, last, lt)
+            last = gt + 1
+            i = last
+        } else {
+            i = lt + 1
+        }
+    }
+    if (last == 0) return text
+    out.append(text, last, text.length)
+    return out.toString()
+}
+
+/**
+ * [stripLooseTags] 判落单 `<p>` 用的「[from] 之后还有没有正文」查询：空白跳过，`<p>` / `</p>`
+ * 整段跳过，其余字符（别的标签、落单的 `<`）一律算有正文——跳过空白与后续 `<p>` 族标签后仍非空
+ * 即为有。判据与原实现逐字一致，只多了记忆化。
+ *
+ * **为什么要记忆化**：这条判据原本每次查询都一路现扫到串尾，而 [stripLooseTags] 对**每一个**
+ * 落单 `<p>` 都要问一次，正文里 N 个落单标签就是 O(N²)——20000 个落单 `<p>` 的输入实测这条判据
+ * 要 23 秒（同一次 `parse` 合计 31 秒），而 `parse` 跑在主线程上（`ui/chat/MessageBubble.kt` 的
+ * `remember`），用户粘一段 HTML 残骸就能把界面卡死十几秒。
+ *
+ * **为什么可以只算一次**：答案只取决于**位置**——同一个位置再问一次，走的一定是同一条链、到的
+ * 一定是同一个终点。所以走链时把沿途每个位置的答案落表，之后 O(1) 命中；每个位置至多被算一次，
+ * N 个落单标签整体就是线性的（同一输入实测这条判据从 23 秒降到毫秒级）。
+ *
+ * **为什么不改变语义**：判定用的就是原来那段扫描本身（[next] 逐分支对应原循环），没有另立一套
+ * 「什么算 `<p>` 标签」的判据——仍是同一组 [OPEN_P_TAG_RE] / [CLOSE_P_TAG_RE]。落表的答案是同一条
+ * 扫描推出来的，因此与逐次现扫逐字相同；连「起点落在标签内部」这种查询也一致（原扫描看到的是
+ * 标签里的字符、判有正文，[next] 在这里同样返回 null）。
+ *
+ * 惰性：没遇到落单 `<p>` 开标签的常规消息一次也不建表，一个字节都不多花。
+ */
+private class ContentAfterQuery(private val text: String) {
+    /** 每个位置的答案：`0` = 还没算、[NOISE_ONLY] = 后面只剩空白与 `<p>` 族标签、[HAS_CONTENT] = 有正文。 */
+    private val answers: ByteArray by lazy(LazyThreadSafetyMode.NONE) {
+        ByteArray(text.length + 1).also { it[text.length] = NOISE_ONLY }
+    }
+
+    /** 本次走链途经的位置，用来把 [answers] 一次落表。 */
+    private val path: IntArray by lazy(LazyThreadSafetyMode.NONE) { IntArray(text.length) }
+
+    /** 与原先「每次现扫到串尾」的判定逐字等价。 */
+    fun hasContentAfter(from: Int): Boolean {
+        var walked = 0
+        var i = from
+        while (true) {
+            val known = answers[i]
+            if (known != UNKNOWN) return finish(walked, known)
+            path[walked++] = i
+            val step = next(i)
+            if (step == null) return finish(walked, HAS_CONTENT)
+            i = step
+        }
+    }
+
+    /** 把这次走链途经的位置一次落表：它们与起点走的是同一条链，答案必然相同。 */
+    private fun finish(walked: Int, answer: Byte): Boolean {
+        for (k in 0 until walked) answers[path[k]] = answer
+        return answer == HAS_CONTENT
+    }
+
+    /**
+     * 原扫描的一步：空白 → 下一位；`<p>` 族标签 → 标签之后；其余（别的标签、落单的 `<`）→ `null`，
+     * 即「有正文」，扫描到此为止。走到 `text.length` 时由 [answers] 里预置的答案收口。
+     */
+    private fun next(i: Int): Int? {
+        val c = text[i]
+        if (c.isWhitespace()) return i + 1
+        if (c == '<') {
+            val gt = text.indexOf('>', i)
+            if (gt >= 0) {
+                val tag = text.substring(i, gt + 1)
+                if (OPEN_P_TAG_RE.matches(tag) || CLOSE_P_TAG_RE.matches(tag)) return gt + 1
+            }
+        }
+        return null
+    }
+
+    private companion object {
+        const val UNKNOWN: Byte = 0
+        const val NOISE_ONLY: Byte = 1
+        const val HAS_CONTENT: Byte = 2
+    }
+}
+
 /** 在文本区内按左到右顺序切出 Text / Action / Narration。 */
 private fun appendAnnotations(text: String, out: MutableList<Tok>, splitBlankLines: Boolean) {
     var last = 0
@@ -307,9 +710,21 @@ private fun toBubble(tokens: List<Tok>): ParsedBubble? {
             tail.add(part)
         }
     }
-    val bodyText = body.toString().trim()
+    // 行内标签在**段落与 `<br>` 都定稿之后**才消费（就在这一行，且是**逐气泡各自一份**）：上面那套
+    // 分段与归属一个字都不动，分段判据因此完全看不见行内标签（`<br>` 已经在 [appendRegion] 那层
+    // 变成气泡边界了）。runs 为空 = 这段正文按字面画（没有可渲染的行内标签、或行内标签结构不平衡
+    // 被整段降级），一个字都不会变。
+    val rawBody = body.toString().trim()
+    val runs = parseInlineMarkup(rawBody)
+    val bodyText = if (runs.isEmpty()) rawBody else runs.joinToString("") { it.text }
     if (bodyText.isEmpty() && head.isEmpty() && tail.isEmpty()) return null
-    return ParsedBubble(body = bodyText, parts = parts.toList(), head = head.toList(), tail = tail.toList())
+    return ParsedBubble(
+        body = bodyText,
+        parts = parts.toList(),
+        head = head.toList(),
+        tail = tail.toList(),
+        runs = runs,
+    )
 }
 
 // ---------------------------------------------------------------------------
@@ -354,28 +769,62 @@ private fun stablePrefixEnd(buf: String): Int {
 
 private fun openTagName(tag: String): String? {
     OPEN_ROLE_TAG_RE.find(tag)?.let { return it.groupValues[1] }
-    return if (OPEN_P_TAG_RE.matches(tag)) "p" else null
+    if (OPEN_P_TAG_RE.matches(tag)) return "p"
+    // 行内开标签也入栈（`<B class=x>` 这类形态由 [parseInlineTag] 判，与解析侧同源）。
+    // `<br>` 是自闭合的，**不入栈**（入了就永远弹不出来，扣留点会永久停在它前面，后面的话再也
+    // 显示不出来）——[openInlineTagName] 对 `<br>` / `<br/>` / `</br>` 一律返回 null。
+    return openInlineTagName(tag)
 }
 
 private fun closeTagName(tag: String): String? {
     CLOSE_ROLE_TAG_RE.find(tag)?.let { return it.groupValues[1] }
-    return if (CLOSE_P_TAG_RE.matches(tag)) "p" else null
+    if (CLOSE_P_TAG_RE.matches(tag)) return "p"
+    return closeInlineTagName(tag)
 }
 
-/** 尾部 `<…` 是否仍可能补全为合法标签（否则它只是普通文本里的 `<`）。 */
+/**
+ * 尾部 `<…` 是否仍可能补全为合法标签（否则它只是普通文本里的 `<`）。
+ *
+ * 词表分两半，每一半都与**自己的消费侧**同源，两条口径都在这里逐字对齐：
+ *   - 段落/旁白只认小写（`<P>` / `<Action>` 原样显示，既有契约）——名字里出现大写就与它无关；
+ *   - 行内标签与 `<br>` 分隔符**大小写不敏感**（契约 v0.89，[parseInlineTag] / [BR_TAG_RE]）
+ *     ——`<B` 与 `<b`、`<BR` 与 `<br` 一样要扣留。
+ * 少扣了就是「中间态把标签当正文吐上屏、收口时才吃掉」，屏幕上显示过的字会改口。
+ * 名字之后是空白或 `/` 都算「还可能补全」（属性 / 自闭合，v0.89 允许带属性，所以 `<b class=x>`
+ * 与 `<br/` 这两个中间态也必须扣住）；其它字符说明它压根不是标签（`<boolean>`、`<b2`）。
+ */
 private fun isPotentialTagPrefix(buf: String, lt: Int): Boolean {
     var j = lt + 1
     if (j < buf.length && buf[j] == '/') j++
     while (j < buf.length && buf[j].isWhitespace()) j++
     val nameStart = j
-    while (j < buf.length && buf[j] in 'a'..'z') j++
+    while (j < buf.length && isTagNameLetter(buf[j])) j++
     val name = buf.substring(nameStart, j)
-    if (j >= buf.length) return name.isEmpty() || TAG_NAMES.any { it.startsWith(name) }
-    if (name.isEmpty()) return false
-    if (!buf[j].isWhitespace()) return false
-    return TAG_NAMES.any { it.startsWith(name) }
+    if (name.isEmpty()) return j >= buf.length
+    if (!couldBeTagName(name)) return false
+    if (j >= buf.length) return true
+    return buf[j].isWhitespace() || buf[j] == '/'
 }
 
+/**
+ * [name] 是否可能是某个已知标签名的前缀；三半各按自己的大小写口径（见 [isPotentialTagPrefix]）：
+ * 段落/旁白小写、`<br>` 与行内标签大小写不敏感。
+ */
+private fun couldBeTagName(name: String): Boolean {
+    if (name.all { it in 'a'..'z' } && STRUCTURE_TAG_NAMES.any { it.startsWith(name) }) return true
+    val lower = name.lowercase()
+    if (couldBeLineBreakNamePrefix(lower)) return true
+    return couldBeInlineTagNamePrefix(lower)
+}
+
+/**
+ * [name]（已小写）是否可能是 `<br>` 分隔符的标签名前缀——`<br` / `</br` / `<BR` 这种残缺形态要不要
+ * 扣留由它说了算。判据与 [BR_TAG_RE] 同口径（大小写不敏感的 `br`）：两边一分叉，
+ * `甲<br` 会先把字面 `<br` 吐上屏，等 `>` 到了再变成两条气泡。
+ */
+private fun couldBeLineBreakNamePrefix(name: String): Boolean =
+    name.isNotEmpty() && LINE_BREAK_TAG_NAME.startsWith(name)
+
 /** 自由文本区内孤立的全角 `＊`（计数为奇）从最后一个起扣留。 */
 private fun withholdDanglingFullStar(buf: String, from: Int, cut: Int): Int {
     var count = 0

app/src/main/kotlin/top/yeij/cyrene/domain/parse/InlineMarkup.kt

@@ -0,0 +1,461 @@
+package top.yeij.cyrene.domain.parse
+
+/*
+ * InlineMarkup —— 气泡正文里「一小撮行内标签」的解析（纯 Kotlin，无 Android / Compose 依赖）。
+ *
+ * 口径 = 后端 2026-10-07 定下的**契约 v0.89** 及其同日更正（跨端必须逐字一致，否则同一个 `<b>`
+ * 在她那台设备上粗、在这台上不粗）。四条硬口径：
+ *   1. 白名单 = `b` / `strong` · `i` / `em` · `code` · `u`（**成对**，六项标签名）；标签名**大小写不敏感**；
+ *   2. **属性一律不解析**：`<b class=x onclick=y>` 只取标签名，属性整段丢掉、绝不落成任何视图属性；
+ *   3. **白名单外一律按纯文本原样显示**：`<script>` 显示成字面量，字符一个不丢；
+ *   4. **结构不平衡 ⇒ 整段降级为原文**（未闭合 / 落单闭标签 / 交错）——粗粒度是有意的，换来
+ *      「字符一个不丢」可以被逐字断言。
+ * 样式映射：`b`/`strong` → 粗体，`i`/`em` → 斜体，`code` → 等宽 + 轻微底色（且**里面的标签不解析**），
+ * `u` → 下划线。`s` **不在白名单里**：它按第 3 条逐字原样显示（见下）。
+ *
+ * ## `br` 不在这里（契约同日更正）
+ * `回执三十一`：「对消息内的 `<br>` **始终处理为多条消息隔断**」⇒ `<br>` **不是行内标签**，而是与
+ * `<p>` 同级的**气泡/消息分隔符**，切分在 [tokenize](ChatContentParser.kt) 的段/块那一层
+ * （`ChatContentParser.appendRegion`）完成，`<br>` / `<br/>` / `</br>` 三种写法等价。
+ * 这一层因此**只认成对标签**：`<br>` 到了这里只是几个普通字符，与 `<br2>`、`<boolean>` 同类。
+ * 它**真的会**走到这里，只是只有一条路：`<code>` 作用域内部——分隔符切分层有一个**保护区**
+ * （`ChatContentParser.protectedSpans`，`回执三十三 §三②`），落在 `<code>` / `<action>` / `<narration>`
+ * 内部的 `<br>` 不分隔，于是 `<code>` 里的那个 `<br>` 会随正文一起交到这一层，在代码作用域里按
+ * 「内容」处理（字面显示，与 `<code><b>甲</b></code>` 里的 `<b>` 同一规矩）。
+ *
+ * ## 白名单六项（`u` 加回、`s` 不做）
+ * `回执三十` 先把白名单收窄到五项、撤掉 `u`/`s`（理由是「多支持 = 制造跨端不一致」），但
+ * `回执三十三 §一` 更正：**那份「收窄到五项」是后端的疏漏**——主人随后裁定下划线保留、后端把 `u`
+ * 加回了契约（`1107b2a`）与 IM 出站（`74c9f2d`），只是**忘了发回执登记**。最终白名单 = **六项**：
+ * `b` / `strong` / `i` / `em` / `code` / **`u`**，`u` 在这里渲染成下划线。
+ * **`s` 仍不在内**（逐字原样）——「多支持反而制造跨端不一致」这条理由对它依然成立：Web 不渲染它。
+ *
+ * ## 为什么是「整段降级」而不是「只降级那一处」
+ * W67 那版是**局部**降级：`甲<b>粗</b>乙<b>没闭合` 里 `粗` 照旧加粗，只有后面那半个 `<b>` 留着字面。
+ * 契约把「结构不平衡」定成**整段不渲染**：一处不平衡，这一整段就一个标签都不认、原文逐字显示。
+ * 代价是「好好的一对 `<b>` 会被邻居的落单标签连累」，换来的是**可以逐字断言**的粗粒度：
+ * 「渲染文本 == 原文」或者「渲染文本 == 原文消费掉全部配对标签」，只有这两种形状，没有中间态
+ * （局部降级那种「一半认、一半留」在跨端对齐时最容易各说各话）。见 [parseInlineMarkup]。
+ *
+ * ## 「整段」是哪一段（我们采用的口径 + 理由）
+ * **整段 = 该气泡的正文**，也就是 [toBubble](ChatContentParser.kt) 里 `body.toString().trim()`
+ * 出来的那一段（`ParsedBubble.body` 对应的文本，通常正好是一个 `<p>…</p>` 块的正文，也可能是
+ * 块外文本并入相邻气泡后的那一份）。不是整条消息，也不是单个 `<p>` 块：
+ *   - **不是整条消息**：一条消息可以有多个分隔（`<p>` / `<br>`）= 多条气泡，一个气泡里写坏了一个
+ *     标签，不该把**别的**气泡一起按字面画出来——那既不是契约想说的「这一段」，也会让「她写坏了
+ *     一个标签」这种局部事故看起来像整条消息都坏了。
+ *   - **不是单个 `<p>` 块**（虽然大多数时候两者重合）：本端渲染的**最小单位就是气泡**，
+ *     `body` / `runs` 也都是按气泡算的。降级粒度与渲染粒度取同一个，实现上才有一条清晰的边界
+ *     （`toBubble` 一次调用 = 一次判定），断言也才写得出「这条气泡是原文、那条气泡照常渲染」。
+ *   - 后端已认可这一点（`回执三十`：「契约只承诺『不平衡 ⇒ 不渲染、字符一个不丢』，**具体粒度算
+ *     实现细节**」）。
+ *   - 因为切分（`<p>` / `<br>`）**先于**行内解析，跨分隔符的标签天然分属两段：
+ *     `<b>甲<br>乙</b>` ⇒ 两段各不平衡 ⇒ 两段都回落原文。
+ *
+ * ## 为什么不改 `parts`，只在 `ParsedBubble` 上加一个字段
+ * `ContentPart.Text` 的 `text` 必须保持**逐字原文**：编辑框（`MessageEditText.visibleTextOf`）、
+ * 搜索片段（`SessionSearchModel.plainSearchText`）、通知文案（`ProactiveNotify`）读的都是 `parts`，
+ * 在那里把标签改掉就是**静默改用户内容**。所以行内解析不改片段，只在 `toBubble` 里对**已经定稿的
+ * 正文**算一次，结果落在 `ParsedBubble.runs`；`body` 变成正文的**渲染文本**（白名单标签已消费），
+ * 而 `parts` 仍是原文——两侧各拿自己该拿的那一份。
+ *
+ * ## 与段落解析的分工（为什么不在 `tokenize` 里做）
+ * 行内解析发生在**段落/分隔符边界已经定稿之后**（`toBubble` 里，对最终 `body` 做一次）：`<p>` 与
+ * `<br>` 分气泡、空行回落、旁白归属、落单标签剥离全部照旧，行内标签既不参与、也改不动它们。
+ * 这也让 W63 在 `tokenize` 里去掉的两处 O(N²) 一行都不受影响：这里是对最终正文的一趟线性扫描。
+ *
+ * ## 大小写不敏感（v0.89）与「扣留侧必须一起改」
+ * `<B>` / `<STRONG>` 都认——但**消费侧与流式扣留侧（[ChatContentParser.stablePrefixEnd]）
+ * 必须同源**，否则两边分叉：`<B` 这种残缺形态若只在消费侧认，中间态就会把它当正文吐上屏、等 `</B>`
+ * 到了再吃掉，**屏幕上已经显示过的字就改口了**。所以标签名的字母判据（[isTagNameLetter]）与
+ * 「这个名字还可能补全吗」（[couldBeInlineTagNamePrefix]，以及 `ChatContentParser.isPotentialTagPrefix`
+ * 里的 `couldBeTagName`）都收在**这一份文件**里，两边引用同一份名单。
+ * 段落/旁白标签（`<p>` / `<action>` / `<narration>`）仍然**只认小写**：这是既有契约
+ * （`plainAngleBracketsAreNeverEaten` 钉着 `<P>` 原样、`MessageEditText` 同一口径），
+ * 且契约明确「`<action>`/`<narration>` 的既有行为逐字未改」。
+ *
+ * ## 明确不做（逐条理由）
+ * 1. **块级（`<p>` 之外的 `<div>` / `<h1>` / 列表…）不做**：契约写死「段落仍走 `<p>`」。
+ * 2. **`<a href>` 不做**：它不是一个样式，是一个**点击行为**（要唤浏览器），必须配一套安全策略
+ *    （只认 http/https、不许 `intent://` / `javascript:` 之类）。契约把它划成独立安全面，实测 0 命中。
+ * 3. **Markdown 的 `*` / `_` 一律不做**：星号这个字形在本项目**已经被占走了**——`ROLE_RE` 把全角
+ *    `＊…＊` 与半角 `*(动作|旁白|内心|神态|轻声)…*` 判成旁白/动作（`＊笑＊` 是动作，不是斜体），
+ *    既有测试钉着这条语义。再给同两个星号一个「斜体」的说法，同一条消息就有两种读法，还要先猜
+ *    哪一种是她的本意——那是改既有语义，不是加渲染。
+ * 4. **`#` 标题 / `- ` 列表 / 表格 / ``` 围栏 / `[链接](url)` / `~~删除~~` 一律不做**：真后端最近
+ *    100 条实测 0 命中；而且这些是**行级**规则，会把「正文里真有一行以 `- ` 开头」这种普通文本
+ *    改写成别的东西——0 命中 + 有改写风险 = 不做。
+ * 5. **HTML 实体（`&lt;` `&amp;` `&nbsp;` …）不做**：实测 0 命中；实体是一张**开放的清单**
+ *    （`&#39;` / `&#x27;` / 各种命名实体……），做一半比不做更糟——会出现「`&amp;` 解了、`&#x27;`
+ *    却原样显示」这种谁也说不清的口径。想在正文里显示尖括号，今天有 `<code>` 这一档。
+ * 6. **`<script>` / `<style>` 之类只会「原样显示」，绝不会被当 HTML 注入**：渲染侧是
+ *    `AnnotatedString` + `SpanStyle`（结构化），正文从来没有、也不会走任何 HTML 解析/注入路径。
+ *
+ * 契约与边界口径见 [parseInlineMarkup]。
+ */
+
+/**
+ * 一段行内样式，可叠加（`<b><i>粗斜</i></b>` 同时是粗与斜）。
+ *
+ * 只有这四种：换行不是样式——`<br>` 是气泡分隔符（切在 `ChatContentParser.tokenize` 那一层），
+ * 它只会在 `<code>` 作用域内部作为**内容**走到这里（按文件头那条口径字面显示），永远不成样式。
+ */
+enum class InlineStyle {
+    Bold,
+    Italic,
+    Code,
+
+    /** `<u>`：下划线（渲染成 `TextDecoration.Underline`）。`s` 不在白名单里，所以没有对应项。 */
+    Underline,
+}
+
+/**
+ * 正文里**样式一致的一段连续文本**：片段按顺序拼起来就是渲染文本，样式区间由「起始下标 + 长度」
+ * 就地累加得到（第 n 段的区间 = 前面各段长度之和 until 加上自己）。
+ *
+ * 相邻且样式相同的片段由 [parseInlineMarkup] 合并，所以同一段文本只有一种片段形状——
+ * 断言起来就是在断言「哪段字是什么样式」。
+ */
+data class InlineRun(val text: String, val styles: Set<InlineStyle>)
+
+/**
+ * `<code>` 的标签名（解析里要单独判它：里面的标签不再解析）。
+ * `internal` 是因为 `ChatContentParser.protectedSpans` 也要判它（保护区扫描），
+ * 名字只写这一处、两边不许各写一遍。
+ */
+internal const val CODE = "code"
+
+/**
+ * 成对标签的名字（契约 v0.89 最终版的**六项**，见文件头）：`strong` / `em` 是 `b` / `i` 的同义写法，
+ * `u` 是 `回执三十三 §一` 加回来的下划线。
+ * 只写这一处，[parseInlineTag] 与 [couldBeInlineTagNamePrefix] 都由它推出来。
+ * `br` 不在这里（它是分隔符，见文件头）；`s` 也不在（逐字原样）。
+ */
+private val PAIRED_TAG_NAMES = listOf("b", "strong", "i", "em", CODE, "u")
+
+/**
+ * 行内标签词表。**流式扣留侧（`ChatContentParser.stablePrefixEnd`）与这里必须同源**：
+ * 同一份名单既判「这是个行内标签」（消费侧），也判「这个标签名会不会继续补全」（扣留侧）。
+ * 两边一分叉，中间态就会把标签当正文吐上屏、收口时才吃掉——屏幕上已经显示过的那几个字就改口了。
+ */
+internal val INLINE_TAG_NAMES = PAIRED_TAG_NAMES
+
+/**
+ * 白名单行内标签认下来的两种形态。**认不出来的（白名单外、形状不对）一律返回 null**，
+ * 由调用方当普通文本原样显示（契约第 3 条：字符一个不丢）。
+ */
+internal sealed interface InlineTag {
+    val name: String
+
+    /** 成对的开标签（`<b>`、`<STRONG>`、`<b class=x onclick=y>`…）：要入栈等它的闭合。 */
+    data class Open(override val name: String) : InlineTag
+
+    /** 成对的闭标签（`</b>`、`</EM>`…）。 */
+    data class Close(override val name: String) : InlineTag
+}
+
+/** 标签名里允许出现的字母：ASCII 大小写，消费侧与扣留侧共用这一把尺子。 */
+internal fun isTagNameLetter(c: Char): Boolean = c in 'a'..'z' || c in 'A'..'Z'
+
+/**
+ * 把一段 `<…>` 文本判成白名单行内标签（不是则 null）。**一处判据，两个消费者**：解析侧用它认标签，
+ * 流式扣留侧用它算「这个开标签要不要入栈扣留」——同源才不会分叉。
+ *
+ * 认下来的形状（`<` 与名字之间可以有空白，与既有 `</\s*(action|narration)\s*>` 同一口径）：
+ *   - 名字 = ASCII 字母串，**大小写不敏感**，落成小写后必须在 [INLINE_TAG_NAMES] 里；
+ *   - 名字之后紧跟的必须是 `>`、空白或 `/`——`<boolean>` / `<br2>` / `<b-x>` 因此都不是标签
+ *     （否则 `b` 会把一大票以 b 开头的普通单词吃成粗体），这是「字符一个不丢」的第一道闸门；
+ *   - 再往后到 `>` 之间的一切（属性、`/`、空白）**整段丢掉**：契约第 2 条，只取标签名。
+ *     丢掉的只是白名单标签自己那对尖括号里的东西，正文一个字符都不动。
+ *
+ * `<br>` 在这里返回 null（它不再是行内标签，是气泡分隔符）——所以它落到「白名单外」那条路：
+ * 它只是几个普通字符。真实链路上**只有一条路**能把它送到这一层：`<code>` 作用域内部
+ * （分隔符切分层的保护区不分隔它，见 [appendRegion] 与 `ChatContentParser.protectedSpans`）。
+ */
+internal fun parseInlineTag(tag: String): InlineTag? {
+    val end = tag.length - 1
+    if (end < 2 || tag[0] != '<' || tag[end] != '>') return null
+    var i = 1
+    val closing = tag[i] == '/'
+    if (closing) i++
+    while (i < end && tag[i].isWhitespace()) i++
+    val nameStart = i
+    while (i < end && isTagNameLetter(tag[i])) i++
+    if (i == nameStart) return null
+    val name = tag.substring(nameStart, i).lowercase()
+    if (i < end && !tag[i].isWhitespace() && tag[i] != '/') return null
+    if (name !in PAIRED_TAG_NAMES) return null
+    return if (closing) InlineTag.Close(name) else InlineTag.Open(name)
+}
+
+/** 开标签名（不是行内开标签则 null）。 */
+internal fun openInlineTagName(tag: String): String? =
+    (parseInlineTag(tag) as? InlineTag.Open)?.name
+
+/** 闭标签名（不是行内闭标签则 null）。 */
+internal fun closeInlineTagName(tag: String): String? =
+    (parseInlineTag(tag) as? InlineTag.Close)?.name
+
+/**
+ * [name]（已小写）是否可能是某个行内标签名的**前缀**——流式扣留侧判「残缺的 `<b` 还可能补全吗」
+ * 用它。大小写不敏感与 [parseInlineTag] 一致，名单也是同一份。
+ */
+internal fun couldBeInlineTagNamePrefix(name: String): Boolean =
+    INLINE_TAG_NAMES.any { it.startsWith(name) }
+
+/** 标签名 → 样式；`strong` / `em` 落到与 `b` / `i` 同一个样式上。 */
+internal fun inlineStyleOf(name: String): InlineStyle = when (name) {
+    "i", "em" -> InlineStyle.Italic
+    CODE -> InlineStyle.Code
+    "u" -> InlineStyle.Underline
+    else -> InlineStyle.Bold
+}
+
+/**
+ * 把一段**已经定稿的正文文本**解析成行内片段（纯函数）。
+ *
+ * 契约（都由单测钉着）：
+ * 1. **返回空列表 = 这段文本按字面渲染**（正文一个字符都不动）。三种情形都落在这里：
+ *    没有可渲染的行内标签、**结构不平衡**（契约第 4 条，整段降级）、以及整段只有标记没有字。
+ *    这是绝大多数消息的路径（实测 100 条里只有 2 条带 `<b>`），也是 `plainBubble` 那条路。
+ * 2. 返回非空 ⇒ 片段拼起来**就是**渲染文本：白名单标签已被消费，且两端空白已去（见下）。
+ *    **除此之外逐字等于原文**——白名单外的标签（`<script>`）、属性、`<code>` 里的内容全都原样在
+ *    片段里。
+ * 3. **绝不把一段非空正文渲染成空**：整段只有标记没有字（`<b></b>`）时回落成第 1 条，
+ *    把标记原样显示——宁可让她的话里多几个尖括号，也不能给出一条空白气泡。
+ *
+ * ## 口径一：配成对且正确嵌套，否则**整段**降级为原文（契约第 4 条）
+ * 判定只看白名单标签的结构（白名单外的尖括号一律是普通字符，不参与判定）：
+ *   - **未闭合的开标签**（`<b>没有闭合`、`日落 <b>18:35`）、**落单的闭标签**（`没有闭合</b>`、
+ *     只有 `</b>`）、**交错**（`<b>甲<i>乙</b>丙</i>`：`</b>` 关不掉栈顶的 `i`）——三者任一出现，
+ *     这一整段**一个标签都不认**、原文逐字显示。
+ *   - 代价与收益都写清：`甲<b>粗</b>乙<b>没闭合` 里的 `粗` 也不再加粗（粗粒度），
+ *     换来的是渲染文本与原文之间只有两种关系（相等 / 消费掉全部配对标签），跨端可以逐字对齐。
+ *   - 判据只有这一条，不发明「宽容关闭」（`</b>` 顺手把里面没关的 `<i>` 也关掉）、也不按行/按句
+ *     局部生效：那种写法每端都能自圆其说，合起来就是跨端不一致。
+ *   - **跨分隔符的标签各自算**：`<b>甲<br>乙</b>` 里的 `<br>` 在更早一层就把气泡切开了，
+ *     到这里是两段文本（`<b>甲` 与 `乙</b>`），各自不平衡 ⇒ 各自回落原文。层序与理由见
+ *     `ChatContentParser.appendRegion` 的 KDoc。
+ *
+ * ## 口径二：`<code>` 里不再解析（与契约第 3 条一致，不是例外）
+ * `<code><b>甲</b></code>` 显示字面的 `<b>甲</b>`（等宽 + 底色），`<code>1 < 2 && a<b</code>`
+ * 原样显示。它与契约第 3 条（白名单外按纯文本显示）**不冲突、方向一致**，但**不是同一条规则**：
+ *   - 第 3 条管的是**白名单外的标签名**（`<script>`、`<div>`）——它们从来不是「标签」；
+ *   - `<code>` 是一条**作用域**规则：在白名单标签 `<code>` 内部，连白名单标签也按内容处理。
+ *     `code` 表达的是「这段是代码」，代码里的 `<b>` 就是四个字符——这是 W67 就定下的口径，
+ *     契约没有就「`<code>` 内部」单独措辞，我们**保留原行为**（换 HTML 那种「元素照常嵌套解析」的
+ *     语义，改动只是删掉 [claimTags] 里的跳过分支，等后端确权再动）；
+ *   - 两者的结果都落在同一条硬口径上：**字符一个不丢**。`<code>` 也正好是「想原样显示尖括号
+ *     怎么办」的现成答案。
+ * 内部的东西**不参与结构判定**：`<code><b>甲</code>` 里的 `<b>` 不算未闭合（它只是内容），
+ * 所以不会因为它把整段拖成字面——判定与显示用的都是同一套「里面不算标签」的口径。
+ * 代价是代码里的 `<b>` 不生效（实测 0 命中，也不存在「代码里也要粗体」这个需求）。
+ *
+ * ## 为什么两端空白要去掉
+ * 被标签让出来的空白（`<b> 甲 </b>` 里那两个字）留着的唯一效果是「气泡里看起来多了两个空格」，
+ * 而正文两端的空白本来就被去掉了（`toBubble` 里那句 `body.trim()`）。这一步只吃空白——一个可见
+ * 字符都不会掉；它同时兜住契约第 3 条：整段只有空白（`<b> </b>`）时回落字面，绝不给出一条
+ * 看起来空白的怪气泡。
+ *
+ * 复杂度 O(n)：两趟线性扫描（每个 `<` 只看一扇「到 `>` 或下一个 `<` 为止」的窗，绝不
+ * `indexOf('>')` 一路找配对）；正文里没有 `<` 时连集合都不建，一次就返回。
+ */
+fun parseInlineMarkup(text: String): List<InlineRun> {
+    if (text.indexOf('<') < 0) return emptyList()
+    // 结构不平衡 ⇒ 整段降级为原文（消费侧返回空列表 = 调用方按字面渲染）。
+    val claimed = claimTags(text) ?: return emptyList()
+    if (!claimed.any) return emptyList()
+    // 整段被吃空（`<b></b>` 这类只有标记没有字的形状）⇒ 回落字面路径，见契约第 3 条。
+    return runsOf(text, claimed).trimEdges().takeIf { it.isNotEmpty() } ?: emptyList()
+}
+
+/** 一趟扫下来的「哪些标签被认领」：开/闭标签的起始下标。 */
+private class ClaimedTags {
+    val openStarts = HashSet<Int>()
+    val closeStarts = HashSet<Int>()
+
+    val any: Boolean
+        get() = openStarts.isNotEmpty() || closeStarts.isNotEmpty()
+}
+
+/**
+ * 第一趟：扫出配成对且正确嵌套的那些标签（起始下标落在 [ClaimedTags] 的两个集合里）。
+ *
+ * 返回 **null = 结构不平衡**（未闭合 / 落单闭标签 / 交错），调用方据此整段降级为原文。
+ * 因为不平衡时整段都不认，所以有返回值时**每一个**白名单成对标签都是配好的（闭标签只关得掉栈顶
+ * 那个同名开标签，严格嵌套）。
+ *
+ * 白名单外的尖括号**完全不参与判定**：它们是普通字符（契约第 1、3 条），既不入栈、也不会因为
+ * 「没闭合」把整段拖成字面——`甲<b>粗</b><script>` 里粗体照常生效，`<script` 原样显示。
+ *
+ * `<code>` 开着的期间**整段跳过**：里面的标签一个都不认、也不算结构（见 [parseInlineMarkup] 的
+ * 口径二）。因为跳过的是「认不认」，所以 `<code>` 自己那一对仍照常被认领。
+ */
+private fun claimTags(text: String): ClaimedTags? {
+    val claimed = ClaimedTags()
+    val open = ArrayList<Pair<String, Int>>()
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) break
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是行内标签：往后挪**一个字符**再找。不能跳到某个「下一个 `>`」——
+            // 那会连同中间真正的标签一起跳过（`1 < 2 <b>甲</b>` 里的 `<b>` 就是这么丢的）。
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        val parsed = parseInlineTag(tag)
+        if (open.lastOrNull()?.first == CODE) {
+            // `<code>` 里的一切都是它的内容：`<b>` 是四个字符，也都不算结构（所以里面那个「未闭合的
+            // `<b>`」不会把整段拖成字面）。只有闭合它的 `</code>` 例外。
+            if (parsed == InlineTag.Close(CODE)) {
+                claimed.openStarts.add(open.removeAt(open.lastIndex).second)
+                claimed.closeStarts.add(lt)
+            }
+        } else {
+            when (parsed) {
+                is InlineTag.Open -> open.add(parsed.name to lt)
+                is InlineTag.Close ->
+                    // 落单的闭标签（栈空）、或交错（`</b>` 关不掉栈顶的 `i`）⇒ 整段降级。
+                    if (open.lastOrNull()?.first != parsed.name) return null
+                    else {
+                        claimed.openStarts.add(open.removeAt(open.lastIndex).second)
+                        claimed.closeStarts.add(lt)
+                    }
+
+                null -> Unit
+            }
+        }
+        i = gt + 1
+    }
+    // 还有开标签没配到闭合 ⇒ 整段降级。
+    if (open.isNotEmpty()) return null
+    return claimed
+}
+
+/**
+ * [lt] 处这个 `<` 起头的**行内**标签在哪结束（不是行内标签则 -1）。
+ *
+ * 一路走到 `>` 或**下一个 `<`** 为止：契约要求「属性一律不解析」，标签多长因此不再有上界
+ * （`<b class="…" onclick="…">` 可以很长），W67 那版「只看一扇定宽窗」的做法行不通了。
+ * 仍然刻意**不用** `indexOf('>', lt)` 一路找过去：正文里 N 个落单的 `<` 时那是 O(N²)
+ * （W63 在同一片区域刚踩过这个坑），而且它还会把中间真正的标签一起跳过。
+ * 逐段推进仍是线性的：每次从 `lt + 1` 扫到「下一个 `<`」或串尾，这些区间互不重叠。
+ *
+ * `internal` 是因为**标签边界只该有一把尺子**：分隔符切分层扫 `<br>` 保护区
+ * （`ChatContentParser.protectedSpans`）时也用它，两边若各写一套，「哪儿是一个标签」就会分叉。
+ */
+internal fun inlineTagEnd(text: String, lt: Int): Int {
+    var i = lt + 1
+    while (i < text.length) {
+        when (text[i]) {
+            '>' -> return i
+            '<' -> return -1
+        }
+        i++
+    }
+    return -1
+}
+
+/**
+ * 第二趟：把文本切成片段——被认领的标签消费掉（开/闭标签不入字），其余**逐字**进片段
+ * （白名单外的标签、`<code>` 里的内容、没有被认领的整段标记，都在这里原样吐回）。
+ * 因为第一趟只收严格嵌套的配对，这里的栈与它逐字对应，不会弹错人。
+ */
+private fun runsOf(text: String, claimed: ClaimedTags): List<InlineRun> {
+    val runs = ArrayList<InlineRun>()
+    val piece = StringBuilder()
+    val open = ArrayList<String>()
+    var styles = emptySet<InlineStyle>()
+
+    fun flush() {
+        if (piece.isEmpty()) return
+        val text0 = piece.toString()
+        piece.setLength(0)
+        val last = runs.lastOrNull()
+        if (last != null && last.styles == styles) {
+            runs[runs.lastIndex] = last.copy(text = last.text + text0)
+        } else {
+            runs.add(InlineRun(text0, styles))
+        }
+    }
+
+    var i = 0
+    while (true) {
+        val lt = text.indexOf('<', i)
+        if (lt < 0) {
+            piece.append(text, i, text.length)
+            break
+        }
+        if (lt > i) piece.append(text, i, lt)
+        val gt = inlineTagEnd(text, lt)
+        if (gt < 0) {
+            // 这一处起头的东西不是行内标签（`1 < 2` 里那个 `<`、残缺的 `<b`、属性里带 `<` 的…）：
+            // 把这个字符原样收下、从下一个字符继续。**必须与第一趟用同一把尺子**——这里若改用
+            // `indexOf('>', lt)` 找标签边界，第一趟认下的那对标签就会在这里被当成一个字面整段吞掉
+            // （`1 < 2 <b>甲</b>`）。
+            piece.append('<')
+            i = lt + 1
+            continue
+        }
+        val tag = text.substring(lt, gt + 1)
+        when {
+            claimed.openStarts.contains(lt) -> {
+                flush()
+                open.add(openInlineTagName(tag) ?: closeInlineTagName(tag).orEmpty())
+                styles = stylesOf(open)
+            }
+
+            claimed.closeStarts.contains(lt) -> {
+                flush()
+                open.removeAt(open.lastIndex)
+                styles = stylesOf(open)
+            }
+
+            else -> piece.append(tag)
+        }
+        i = gt + 1
+    }
+    flush()
+    return runs
+}
+
+private fun stylesOf(open: List<String>): Set<InlineStyle> =
+    if (open.isEmpty()) emptySet() else open.mapTo(LinkedHashSet(), ::inlineStyleOf)
+
+/** 去掉渲染文本两端的空白，并同步裁掉因此变空的片段——只吃空白，一个可见字符都不会掉。 */
+private fun List<InlineRun>.trimEdges(): List<InlineRun> {
+    var head = 0
+    for (run in this) {
+        val leading = run.text.takeWhile { it.isWhitespace() }.length
+        head += leading
+        if (leading < run.text.length) break
+    }
+    var tail = 0
+    for (i in indices.reversed()) {
+        val trailing = this[i].text.takeLastWhile { it.isWhitespace() }.length
+        tail += trailing
+        if (trailing < this[i].text.length) break
+    }
+    val total = sumOf { it.text.length }
+    val from = minOf(head, total)
+    val to = total - minOf(tail, total - from)
+    return cut(from, to)
+}
+
+/** 按字符下标从两端裁掉（只用于裁空白，所以裁点必然落在片段边界或空白中间）。 */
+private fun List<InlineRun>.cut(from: Int, to: Int): List<InlineRun> {
+    if (from == 0 && to == sumOf { it.text.length }) return this
+    val out = ArrayList<InlineRun>(size)
+    var pos = 0
+    for (run in this) {
+        val start = pos
+        pos += run.text.length
+        val head = maxOf(start, from)
+        val end = minOf(pos, to)
+        if (head < end) out.add(run.copy(text = run.text.substring(head - start, end - start)))
+    }
+    return out
+}

app/src/main/kotlin/top/yeij/cyrene/domain/share/SharePayload.kt

@@ -12,9 +12,27 @@ package top.yeij.cyrene.domain.share
  *
  * 还有第三件要说的：[contentUnreadable]——对方给了东西、本端**连地址都没认下来**。它连丢件计数
  * 都留不下（本端一条都没接收），所以单独一格；否则「分享点下去什么都不发生」正是它造成的。
+ *
+ * 正文那一格也多带一件要看的东西：[textSource]——这一段是从 `EXTRA_TEXT` 来的，还是从
+ * `EXTRA_SUBJECT` / `EXTRA_TITLE` **回落**来的。有些发送方根本不填 `EXTRA_TEXT`，本端为此把取正文
+ * 改成一条回落链（[ShareRules.extract]）；而回落来的正文与真正文长得一模一样，用户只能靠这一格分辨。
  */
 data class SharedContent(
+    /**
+     * 这次分享的正文（两侧空白已去掉；全空白算没有正文，见 [ShareRules.extract]）。
+     *
+     * 它可能是从 `EXTRA_SUBJECT` / `EXTRA_TITLE` **回落**来的（有些发送方根本不填 `EXTRA_TEXT`），
+     * 来源记在 [textSource] 里：回落来的那一段与真正文长得一模一样，用户只能靠那一格分辨。
+     */
     val text: String = "",
+    /**
+     * 正文是从哪个 extra 拿到的（默认 [ShareTextSource.Text] = 正文本来就是正文）。
+     *
+     * ⚠️ 它**不参与发送的内容**：这条消息发出去的正文只有 [text] 本身。它的唯一去处是**本端渲染层**
+     * 的那一句如实小字（见 `shareTextOriginNotice`）——回落来的正文必须能让用户察觉，否则「预览里只有
+     * 一句话」会被读成「对方发来的就是这句正文」。
+     */
+    val textSource: ShareTextSource = ShareTextSource.Text,
     val images: List<String> = emptyList(),
     /**
      * 非图片的分享文件。MIME 以 `image/` 开头者走 [images]，其余一律走这一条
@@ -31,13 +49,14 @@ data class SharedContent(
     /** 已接收但**拷贝失败**的文件条数。 */
     val failedDocuments: Int = 0,
     /**
-     * 这次分享**带着内容迹象**（`EXTRA_STREAM` 有值、或 `ClipData` 有条目），却一条可用内容都没
-     * 提取出来。
+     * 这次分享**带着内容迹象**（三个文本 extra 里躺着值、或 `EXTRA_STREAM` 有值、或 `ClipData`
+     * 有条目），却一条可用内容都没提取出来。
      *
      * 与 [failedImages] / [failedDocuments] **不是**同一件事：那两个说的是「本端已经认下来的地址
-     * 读不到」（对方给的东西本端拿不动），这里说的是「本端连地址都没认下来」（多为发送方把
-     * `EXTRA_STREAM` 塞成了本端认不出的形态，或用的是本端不读的 scheme）。它是**唯一**一种既没有
-     * 内容、也没有丢件计数的失败形态，所以要单独记一格，否则结局就是「用户点了分享、界面毫无反应」。
+     * 读不到」（对方给的东西本端拿不动），这里说的是「本端连可用的内容都没认下来」（多为发送方把
+     * `EXTRA_STREAM` 塞成了本端认不出的形态、用本端不读的 scheme，或把正文放在本端认不出的地方）。
+     * 它是**唯一**一种既没有内容、也没有丢件计数的失败形态，所以要单独记一格，否则结局就是
+     * 「用户点了分享、界面毫无反应」。
      */
     val contentUnreadable: Boolean = false,
 ) {
@@ -55,13 +74,43 @@ data class SharedContent(
      *
      * 判据只此一处：`ShareIntake.accept` 用它决定要不要往下接，`shareNoticeFor` 用它守卫「什么都没有
      * 的分享一个字都不说」那条边界——两处必须同一条，否则会出现「接了却不说」或「说了却没接」。
-     * 整条分享里什么都没有（`EXTRA_TEXT` 没有值、`EXTRA_STREAM` 也没有值、`ClipData` 也没有条目）
-     * 时它是 `false`：那次分享确实无话可说，静默才是对的。
+     * 整条分享里什么都没有（三个文本 extra 都没有值、`EXTRA_STREAM` 也没有值、`ClipData` 也没有条目）
+     * 时它是 `false`：那次分享确实无话可说，静默才是对的。而「有值、只是本端一段都读不出来」（含
+     * 空白与类型不符）**不**属于「什么都没有」：它由调用方以 `textPresent` 如实报进来，正是
+     * [contentUnreadable] 那一格要接的。
      */
     val worthDelivering: Boolean
         get() = !isEmpty || droppedImages > 0 || droppedDocuments > 0 || contentUnreadable
 }
 
+/**
+ * 这次分享的正文**是从哪个 extra 拿到的**。
+ *
+ * ## 为什么要把来源留下来
+ * 真实世界里有些发送方不填 `EXTRA_TEXT`：内容在 `EXTRA_SUBJECT`（少数在 `EXTRA_TITLE`）里。本端
+ * 此前只读 `EXTRA_TEXT`，那条分享因此**整条静默**——用户点了分享，界面毫无反应、也没有一句解释
+ * （正是本项目最忌讳的那种失败）。所以取正文改成一条**回落链**（[ShareRules.extract]）。
+ *
+ * 但「这段字其实只是对方给的标题」必须能让用户分辨：预览里只有一句话时，他会以为对方发来的就是这句
+ * 正文。于是一并记下**来源**，由渲染层如实标一句（`shareTextOriginNotice`）——那句话只出现在界面上，
+ * **绝不**进正文（来源标记不许拼进用户正文是项目红线，见 [ShareRules] 的「为什么正文一个字都不加」）。
+ *
+ * ## 为什么分成三档而不是一个布尔
+ * 三档是**如实登记**对方把内容放在哪个字段里：排查时「这条是从 SUBJECT 还是 TITLE 来的」是要看得见
+ * 的事实，而这两种形态在真实发送方里的出现频率差得很远（SUBJECT 常见、TITLE 罕见）。但两者对用户
+ * 说的是同一句话——标题与主题在用户眼里本来就是同一件事。
+ */
+enum class ShareTextSource {
+    /** `EXTRA_TEXT`：规范路径，也是唯一一条「正文本来就是正文」的路。 */
+    Text,
+
+    /** 从 `EXTRA_SUBJECT` 回落的（对方没给 `EXTRA_TEXT`，或给的是一段空白）。 */
+    Subject,
+
+    /** 从 `EXTRA_TITLE` 回落的。 */
+    Title,
+}
+
 /**
  * 一份分享进来的**非图片**文件。
  *
@@ -120,10 +169,19 @@ fun classifySharedStream(mime: String?): SharedStreamKind {
  * ⚠️ **字符串形态只认 `content://`**（判据见 [stringStreamUri]）：那是本端**新开**的一条读入口，
  * 松不得。被拒的条目**逐条跳过**——一次分享里有几条坏的，不该把整次分享废掉。
  *
+ * ## 正文的回落链（本模块补上的另一条兼容读取）
+ * 真实世界里有发送方**不填** `EXTRA_TEXT`：内容只在 `EXTRA_SUBJECT`（少数在 `EXTRA_TITLE`）里。
+ * 本端此前只读 `EXTRA_TEXT`，那样一次分享因此**整条静默**——用户点了分享，界面毫无反应、也没有一句
+ * 解释。所以取正文改成 `EXTRA_TEXT` → `EXTRA_SUBJECT` → `EXTRA_TITLE` 的**回落链**（[extract]），
+ * 来源记在 [SharedContent.textSource] 里，由渲染层如实标一句（见 [ShareTextSource]）。
+ *
  * ## 为什么正文一个字都不加
  * **绝不**往用户正文里拼「[用户分享]」之类的来源标记：来源标识走后端的独立 `RoleSystem`
  * 来源消息 + 结构化 `SenderName`（`02/F4` / `design/11 §10`），人类可见的标记只能放在本端
  * 渲染层。把标记拼进正文 = 让用户正文冒充系统指令，是项目红线。分享进来的正文**原样**发出。
+ *
+ * 回落来的正文（从 `EXTRA_SUBJECT` / `EXTRA_TITLE` 取到的那一段）同样**原样**发出：来源提示是界面
+ * 上的一句小字，**不是**正文的一部分——所以面板里那段预览与真正发出去的那条消息逐字相同。
  */
 object ShareRules {
 
@@ -170,9 +228,49 @@ object ShareRules {
     fun truncatedImagesNotice(kept: Int, dropped: Int): String? =
         if (dropped > 0) "一次最多 $MAX_IMAGES 张，超出的没发，只发送前 $kept 张" else null
 
+    /**
+     * 一次「批量投递」里，第 [index] 条要不要声明「她忙时发消息」那个偏好（`interrupt` / `parallel`）。
+     *
+     * ## 两个事实合起来只剩两种答案
+     * - **分享一次都不声明**（[fromShare]）：分享是「一次把东西倒进去」，N 张图就是 N 条消息；对每张
+     *   图各声明一次，第 2 条就会把第 1 条刚起的回合打掉——**批量动作自相残杀**。这是本端自己的判断
+     *   （后端口径 `02` F4：他们那边不需要做任何事）。
+     * - **手打那条只声明第一条**（`index == 0`）：一次发送切出来的第 2 条起若也声明，同样是在打断
+     *   自己刚起的上一轮。声明的是「这一次投递要怎样对待正在进行的回合」，一次发送只该有**一个**
+     *   这样的意思。
+     *
+     * 于是答案只有 `false`（分享，恒成立）与「只有第 0 条成立」（手打）两种形态。
+     *
+     * ## 为什么提成一个纯函数
+     * 这条边界原先散在 `ChatViewModel` 里（`applySendPreference && index == 0`，分享那条入口另传
+     * `false`）：两处各是半个判据、**一处都单测不到**，而「分享多图绝不互相打断」正是 W76 要一直
+     * 成立的那条边界（见 `05` 的多图自相打断一节）。合并成一处判据之后，入口与投递口用的必须是
+     * 同一条——与 `hasSendableContent`（`ui/chat/SendQueue.kt`）的情形完全一样。口径也与
+     * [truncatedImagesNotice] 一致：两条入口共用的规则，只有一个出处。
+     *
+     * @param fromShare 这条（这一批）是不是分享进来的
+     * @param index 在这次发送切出的消息里的位置（0 = 第一条）
+     */
+    fun declaresSendPreference(fromShare: Boolean, index: Int): Boolean = !fromShare && index == 0
+
     /**
      * 从分享 Intent 的原始字段提取内容。
      *
+     * ## 正文的回落链：`EXTRA_TEXT` → `EXTRA_SUBJECT` → `EXTRA_TITLE`
+     * 取**第一个非空白**的那一段当正文（口径与原先只读 `text` 时**完全一致**：两侧去空白、全空白算
+     * 没有）；来源记在 [SharedContent.textSource] 里，好让渲染层如实说一句（见 [ShareTextSource]）。
+     *
+     * 为什么要有这条链：真实世界里有些发送方**不填** `EXTRA_TEXT`，内容只在 `EXTRA_SUBJECT`
+     * （少数在 `EXTRA_TITLE`）里。此前只读 `EXTRA_TEXT` ⇒ 那样一次分享**整条静默**——用户点了分享，
+     * 界面毫无反应，后端零请求，也没有一句解释。前后两种口径的对外差别只有一个：**`EXTRA_TEXT`
+     * 非空时回落链一定不生效**（它是第一站），所以既有情形的结果一个字都没变。
+     *
+     * ## 三个文本 extra 都没换来正文时**不许闭嘴**
+     * 只要三个里**任意一个躺着原始值**（哪怕是一段空白、哪怕类型读不出来），这一次就不是「用户什么都
+     * 没分享」，而是「本端什么都没读出来」——[SharedContent.contentUnreadable] 如实告知，绝不静默。
+     * 「里面躺着值」这件事只有调用方知道（纯函数看不到原始值），所以由 [textPresent] 报进来，与
+     * [streamPresent] 同一个形态。
+     *
      * ## 优先顺序与去重（一次分享里多种来源并存时）
      * 顺序 = `EXTRA_STREAM` 的规范形态（[stream] 在前、[streams] 在后）→ 字符串兼容形态（保持原顺序）
      * → `ClipData`（只在前两者一条都没认下时兜底）。同一个地址串被两处各给一次时**只留先到的那一条**：
@@ -184,7 +282,10 @@ object ShareRules {
      *
      * @param action `Intent.action`；只认 [ACTION_SEND] / [ACTION_SEND_MULTIPLE]
      * @param text `EXTRA_TEXT`——按 `CharSequence` 收，因为它常常是 `Spanned`（带样式的
-     *   HTML 富文本），读成 `String` 会直接拿到 `null`
+     *   HTML 富文本），读成 `String` 会直接拿到 `null`。**回落链的第一站**
+     * @param subject `EXTRA_SUBJECT`——第二站。发送方「对象 / 标题」那个字段，正是有些 App 拿来放
+     *   正文的地方（`EXTRA_TEXT` 一个值都没有）
+     * @param title `EXTRA_TITLE`——第三站（少见，但真实发送方里确实有）
      * @param stream `EXTRA_STREAM` 的单值形态（[ACTION_SEND] 那个只放一条的字段）
      * @param streams `EXTRA_STREAM` 的列表形态（[ACTION_SEND_MULTIPLE] 的字段）
      * @param streamStrings `EXTRA_STREAM` 的**字符串兼容形态**（`String` / `String[]` /
@@ -195,6 +296,10 @@ object ShareRules {
      * @param streamPresent `EXTRA_STREAM` 里确实躺着**原始值**——由调用方读了原始值判出来（本函数
      *   看不到那个值），含本端**认不出形态**的那种。它只有一个用处：形态认不出时本端既不猜、也不该
      *   因此闭嘴，那照样是一次「带着内容迹象却什么都没读进来」。
+     * @param textPresent 三个文本 extra（[text] / [subject] / [title]）里**至少一个躺着原始值**——
+     *   同样由读了原始值的调用方判出来，含**读不出类型**与**只是一段空白**的那两种（`textPresent`
+     *   与 [streamPresent] 一样是「原料里有」「认下来的内容里没有」，用后者判会把「有值但读不出来」
+     *   误当成「什么都没分享」）。正文一旦读出来（哪怕是从标题回落的）它就不起作用了。
      * @param clipUris `ClipData` 各条目的 URI，纯文本条目是 `null`（本端**不读** `ClipData` 里的
      *   文本，所以「只有纯文本条目」等同于「读不进来」，用来判 [SharedContent.contentUnreadable]）
      * @param mimeOf 取一条 URI 的 MIME（Android 侧就是 `ContentResolver.getType`）。本函数是
@@ -204,17 +309,30 @@ object ShareRules {
     fun extract(
         action: String?,
         text: CharSequence? = null,
+        subject: CharSequence? = null,
+        title: CharSequence? = null,
         stream: String? = null,
         streams: List<String>? = null,
         streamStrings: List<String> = emptyList(),
         streamPresent: Boolean = false,
+        textPresent: Boolean = false,
         clipUris: List<String?> = emptyList(),
         mimeOf: (String) -> String? = { null },
     ): SharedContent {
         val recognized = action == ACTION_SEND || action == ACTION_SEND_MULTIPLE
         if (!recognized) return SharedContent()
 
-        val body = text?.toString().orEmpty().trim()
+        // 回落链（见 KDoc）：三段一起按同一个口径归一（`toString` → 两侧 trim → 非空才算有），
+        // 取先到的那个**非空白**值。`EXTRA_TEXT` 非空时它一定赢 ⇒ 既有情形逐字不变。
+        val picked = listOf(
+            ShareTextSource.Text to text,
+            ShareTextSource.Subject to subject,
+            ShareTextSource.Title to title,
+        ).firstNotNullOfOrNull { (source, value) ->
+            value?.toString()?.trim()?.takeIf(String::isNotEmpty)?.let { source to it }
+        }
+        val body = picked?.second.orEmpty()
+        val textSource = picked?.first ?: ShareTextSource.Text
 
         // 两个字段一并收：单值 / 列表是历史形态（当年靠 getParcelableExtra 与
         // getParcelableArrayListExtra 两个读法分开取，才不得不按 action 二选一），
@@ -239,9 +357,9 @@ object ShareRules {
             }
         }
 
-        // 「带着内容迹象」的判据取的是**原料**（EXTRA_STREAM 里躺着的原始值 / ClipData 的条目数），
-        // 不是「认下来的地址」——「有值但一条都认不出」正是要说的那种情形，用后者判反倒会把它当成
-        // 「什么都没分享」而闭嘴。
+        // 「带着内容迹象」的判据取的是**原料**（三个文本 extra 里躺着的原始值 / EXTRA_STREAM 里躺着的
+        // 原始值 / ClipData 的条目数），不是「认下来的内容」——「有值但一条都认不出」正是要说的那种
+        // 情形，用后者判反倒会把它当成「什么都没分享」而闭嘴。
         val hadStreamValue = streamPresent ||
             !stream.isNullOrBlank() ||
             streams.orEmpty().any(String::isNotBlank) ||
@@ -249,6 +367,7 @@ object ShareRules {
 
         return SharedContent(
             text = body,
+            textSource = textSource,
             images = images.take(MAX_IMAGES),
             // 提取阶段还不知道显示名与大小（要 ContentResolver），先放原样 URI；
             // ShareIntake 拷进 cache 后再换成 file:// + 显示名 + 真实字节数。
@@ -256,7 +375,7 @@ object ShareRules {
             truncatedImages = (images.size - MAX_IMAGES).coerceAtLeast(0),
             truncatedDocuments = (documents.size - MAX_DOCUMENTS).coerceAtLeast(0),
             contentUnreadable = unique.isEmpty() && body.isEmpty() &&
-                (hadStreamValue || clipUris.isNotEmpty()),
+                (hadStreamValue || textPresent || clipUris.isNotEmpty()),
         )
     }
 

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ChatHomeScreen.kt

@@ -28,11 +28,10 @@ private const val SESSION_GONE_NOTICE_MILLIS = 8_000L
  * 会话在别处被删掉时那句如实告知。
  *
  * 它必须由**这一层**持有，不能挂在 `ChatViewModel` 上：`onSessionGone` 一被调用，
- * `activeSessionId` 就会被收敛回主会话，ChatScreen 的 VM key（含会话 id）随之变化 ——
- * 变的是 key，于是**承载横幅的那段组合被销毁重建**；那个 VM 实例本身住在 Activity 级的
- * ViewModelStore 里，**仍然活着、继续收帧**（连登出都不回收它，见 `chatViewModelKey` 的 KDoc）。
- * 横幅挂在 VM 状态上的话活不过这一帧、一个字都来不及显示（真机实测过）。
- * 这一层的 `remember` 活得比它久。
+ * `activeSessionId` 就会被收敛回主会话，ChatScreen 的槽位（与 VM key 里的会话 id）随之变化 ——
+ * 于是**承载横幅的那段组合被销毁重建**；而那个 VM 这会儿正被交出去（本端删除那条路走
+ * `SessionsViewModel.deleteSession` 里的 `ChatSessionSlots.reclaim`，别处删除这条走 404 收敛），
+ * 挂在它状态上的横幅连这一帧都活不过。这一层的 `remember` 活得比它久。
  */
 private const val SESSION_GONE_MESSAGE = "这个会话在服务端已经不存在了（可能已在别处删除），已切回主会话"
 
@@ -66,6 +65,22 @@ fun ChatHomeScreen(
         }
     }
 
+    // 「点她那条通知进来 ⇒ 看主会话」（W53N）。意图活在进程里（通知可能在 App 还没起来、甚至还没
+    // 登录时就被点，见 ProactiveTapIntake），这里只负责把它落地成用户能看见的两件事：
+    // 回到聊天页、并切到主会话。走的是用户点抽屉里那一行的同一条路（select），不另造机制。
+    val pendingProactiveTap by container.proactiveTapIntake.openMainSession.collectAsState()
+    LaunchedEffect(pendingProactiveTap) {
+        if (!pendingProactiveTap) return@LaunchedEffect
+        container.proactiveTapIntake.consume()
+        // 通知说的是「她刚在主会话里说话」，所以落点必须是**那一页**：设置页 / 管理页 / 关于 /
+        // 抽屉还开着的话，用户点进来看到的仍是它们，这条通知就等于没兑现。
+        drawerOpen = false
+        showAbout = false
+        showSettings = false
+        showAdmin = false
+        sessionsViewModel.select(SessionSummaryDto.MAIN_SESSION_ID)
+    }
+
     BackHandler(enabled = showAdmin) { showAdmin = false }
     // 「关于」嵌在设置页里，所以两个条件必须**互斥**：在关于页时设置页的处理器关掉，
     // 返回才只退一层（关于 → 设置），不会一步跳回聊天。
@@ -137,6 +152,7 @@ fun ChatHomeScreen(
                     onDelete = { sessionsViewModel.deleteSession(it.id) },
                     onTogglePin = { sessionsViewModel.setPinned(it.id, !it.pinned) },
                     onRename = { sessionId, title -> sessionsViewModel.renameSession(sessionId, title) },
+                    onStopGenerating = { sessionsViewModel.stopGenerating(it.id) },
                     onOpenIot = { /* P2：IoT 页面 */ },
                     onOpenAdmin = {
                         drawerOpen = false

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ChatScreen.kt

@@ -1,5 +1,6 @@
 package top.yeij.cyrene.ui.chat
 
+import android.Manifest
 import android.content.ActivityNotFoundException
 import android.content.Context
 import android.content.Intent
@@ -30,6 +31,7 @@ import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
@@ -46,6 +48,7 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.input.ImeAction
 import androidx.compose.ui.unit.dp
+import androidx.core.content.ContextCompat
 import androidx.core.content.FileProvider
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.lifecycle.viewmodel.initializer
@@ -59,8 +62,12 @@ import kotlinx.coroutines.withContext
 import top.yeij.cyrene.app.AppContainer
 import top.yeij.cyrene.app.ShareIntake
 import top.yeij.cyrene.core.prefs.accountFingerprint
+import top.yeij.cyrene.core.session.ChatSessionSlots
 import top.yeij.cyrene.data.repository.DocumentCacheStore
 import top.yeij.cyrene.data.repository.ImageCacheStore
+import top.yeij.cyrene.data.repository.VoiceStore
+import top.yeij.cyrene.data.voice.VoiceRecorder
+import top.yeij.cyrene.data.voice.VoiceRecorderState
 import top.yeij.cyrene.data.ws.WsState
 import top.yeij.cyrene.domain.chat.DocumentChips
 import top.yeij.cyrene.domain.chat.DocumentDelivery
@@ -73,7 +80,10 @@ import top.yeij.cyrene.domain.chat.DocumentTarget
 import top.yeij.cyrene.domain.chat.DraftDocument
 import top.yeij.cyrene.domain.chat.ImageSource
 import top.yeij.cyrene.domain.chat.SharedTextPlan
+import top.yeij.cyrene.domain.chat.VoiceDraftInfo
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
 import top.yeij.cyrene.domain.chat.documentLoadFailureMessage
+import top.yeij.cyrene.domain.chat.isActiveFor
 import top.yeij.cyrene.domain.share.ShareRules
 import top.yeij.cyrene.domain.share.SharedContent
 import top.yukonga.miuix.kmp.basic.Button
@@ -90,6 +100,7 @@ import top.yukonga.miuix.kmp.icon.basic.Search
 import top.yukonga.miuix.kmp.icon.basic.Sidebar
 import top.yukonga.miuix.kmp.icon.extended.File
 import top.yukonga.miuix.kmp.icon.extended.Image
+import top.yukonga.miuix.kmp.icon.extended.Mic
 import top.yukonga.miuix.kmp.theme.MiuixTheme
 
 /** 判定「贴着底部」的容差（px）。 */
@@ -107,17 +118,29 @@ private const val SHARE_WAIT_NOTICE_MILLIS = 3_000L
 /** 「已定位 / 这条不在窗口里」那句告知挂多久（毫秒）。 */
 private const val SEARCH_NOTICE_MILLIS = 8_000L
 
+/**
+ * 麦克风相关的告知（没授权 / 起不来）挂多久（毫秒）。
+ *
+ * 与同页其它几条「动作刚发生的如实告知」取同一个值：它描述的也是刚刚那一次按键，
+ * 不是持续状态（权限是不是真的没有，用户再按一次麦克风就知道了）。
+ */
+private const val VOICE_FAILURE_NOTICE_MILLIS = 8_000L
+
 /** 输入栏下方预留的高度：避开屏幕圆角，同时承载忙碌提示。 */
 private val InputBottomSpacer = 22.dp
 
 /**
  * 聊天页那个 [ChatViewModel] 的 key（纯函数）：**账号指纹 + 会话 id**。
  *
- * `viewModel(key = ...)` 的 owner 是 **Activity 级的 ViewModelStore**，而登出只把本组合移出、
- * **不清理那个 store**（[ChatViewModel.onCleared] 是空的，全仓也没有 `ViewModelStore.clear()`）。
- * key 里只放 sessionId 的话，换账号/换服务器再进来时，`viewModel()` 会把**上一个环境**
- * 那个还活着的实例原样取回来——它会继续收那个环境的帧，屏幕上摆的就是别的服务器的消息。
- * 指纹进 key 之后，环境一变就取到新实例；同一个环境里切会话仍然各留一份状态（key 未变）。
+ * 它现在是**一格槽位之内**的名字（owner 是那一格自己的 `ViewModelStore`，见 [ChatSessionSlots]），
+ * 但它要挡的那件事一个字没变：owner 换了（换账号 / 换服务器之后再进来）而 key 不变的话，
+ * `viewModel()` 会把**上一个环境**那个还活着的实例原样取回来——它会继续收那个环境的帧，
+ * 屏幕上摆的就是别的服务器的消息。所以指纹**必须**在里面。
+ *
+ * 两道闸门现在是**各管一段**的：账号指纹进**槽位**的 key（`ChatSessionSlots.keyOf`，换账号天然
+ * 分格），同一个指纹再进**这一格 store 里**的 key（本函数）——同一格 store 只会装一个 VM，
+ * 但两处都写着同一份口径，任何一处将来被单独改掉都还挡得住（先例：`SessionPreferences` 的快照
+ * 与 `SessionsViewModel` 的 `pulledForIdentity` 也是同一份指纹的两处用法）。
  *
  * [accountFingerprint] 与 [SessionPreferences] / `SessionsViewModel` 是**同一份**口径：
  * 别在这里另拼一套字符串——两套判据早晚会分叉，而分叉的那一侧就是漏出去的那一侧。
@@ -164,28 +187,65 @@ fun ChatScreen(
     onSessionGone: () -> Unit = {},
     sessionNotice: String? = null,
 ) {
-    // 账号指纹：**必须进下面那两个 VM 的 key**。登出只是把本组合移出（见 CyreneApp 的 when），
-    // 而这两个 VM 住在 Activity 级的 ViewModelStore 里、**不会随登出回收**——key 里不带指纹的话，
-    // 换账号/换服务器再进来会按同一个 key 取回上一个环境那个还活着的实例，屏幕上摆的就是
-    // 别的服务器的消息。`remember` 每次进入本组合重算一次（换环境必经登出 ⇒ 本组合被销毁重建），
-    // 所以不会拿着上一份指纹；不在每次重组时读加密存储是因为流式期间重组非常频繁。
+    // 账号指纹：**必须进下面那两个 VM 的 key**（聊天那个 VM 还要进它那一格槽位的 key，见
+    // `ChatSessionSlots.keyOf`）。登出只是把本组合移出（见 CyreneApp 的 when），key 里不带指纹的话，
+    // 换账号/换服务器再进来时 `viewModel()` 会把**上一个环境**那个还活着的实例原样取回来，屏幕上
+    // 摆的就是别的服务器的消息（下面那个搜索 VM 就是这样：它没有人回收，只靠 key 分开）。
+    // `remember` 每次进入本组合重算一次（换环境必经登出 ⇒ 本组合被销毁重建），所以不会拿着上一份
+    // 指纹；不在每次重组时读加密存储是因为流式期间重组非常频繁。
     val account = remember {
         accountFingerprint(container.authManager.currentBaseUrl, container.sessionStore.load().username)
     }
+    // 这个会话的**槽位**：这一格的聊天状态住在这里面那份 `ViewModelStore` 里，所以它能被**单独**
+    // 回收（S4；此前每格都塞在 Activity 级那一个 store 里，而它只有整体 clear，收回一格的办法
+    // 只能是「让 key 换一代、旧实例继续留着」——那正是 S4 没修掉的那一半）。
+    //
+    // 组合期间只做这一件与账本有关的事：取（或建）槽位。VM 必须在组合里就拿出来，而槽位就是它的
+    // 存放处，所以这一步没法挪到组合之后；「谁最近」与「超了要不要收」都在下面那个 effect 里。
+    val sessionSlot = remember(account, sessionId) {
+        container.chatSessionSlots.slotFor(account, sessionId)
+    }
     val viewModel: ChatViewModel = viewModel(
+        viewModelStoreOwner = sessionSlot,
         key = chatViewModelKey(account, sessionId),
         factory = viewModelFactory { initializer { ChatViewModel(container, sessionId) } },
     )
     val state by viewModel.state.collectAsState()
     val listState = rememberLazyListState()
 
+    // 「聊天页此刻正显示着这个会话」——「她主动说的话要不要弹通知」的两半之一
+    // （判据 `core.notify.shouldNotifyProactive`：前台 ∧ 这一半 才不弹）。
+    //
+    // 报在这里是因为**组合就是「这一页在不在屏幕上」**：设置页 / 管理页时上层那段 `when` 根本不会
+    // 组合本函数，会话一换本函数也整个换掉——两个方向都自动成立，不需要谁去同步一份状态。
+    // 退出时记 `null`（不是「记成别的会话」）：那一刻屏幕上没有聊天页。
+    DisposableEffect(container, sessionId) {
+        container.appPresence.onChatSurface(sessionId)
+        onDispose { container.appPresence.onChatSurface(null) }
+    }
+
+    // 这个会话**刚刚成为当前会话**：这是「最近」的唯一表达处（口径见 `chatSessionEvictions`），
+    // 顺手按账本回收超出的格数。放在组合之后是刻意的——槽位可能刚在这一帧建出来，而账本不该在
+    // 组合期间被改动（组合被丢弃时不该留下「它被打开过」的结论）。
+    //
+    // `holdsUnsentWork` 收的是**现读的探针**：回收发生在别的会话被打开的那一刻，而那正是用户
+    // 可能刚在前一个会话里打了草稿、还没切走的时候（理由写在 `ChatSessionUsage`）。
+    LaunchedEffect(account, sessionId) {
+        container.chatSessionSlots.onOpened(
+            account = account,
+            sessionId = sessionId,
+            holdsUnsentWork = { viewModel.holdsUnsentWork },
+            nowMillis = System.currentTimeMillis(),
+        )
+    }
+
     // 这个会话在服务端已经没了（`404 session_not_found`，契约 v0.63）：交给上层把用户带回主会话。
     // 只有**非主会话**会置这个位（主会话回 404 说明部署出了问题，那时该显示的是普通错误横幅），
     // 所以这里不会出现「已经主会话还往上跳一次」的回环。
     //
     // ⚠️ **那句解释不能挂在这个 VM 上**：`onSessionGone` 一被调用，上层就会把 activeSessionId 收敛回
-    // 主会话，VM key 里的会话 id 随之变化 ⇒ **承载它的那段组合被销毁重建**。（变的是 key，
-    // 不是 VM：那个实例仍在 Activity 级的 ViewModelStore 里活着、继续收帧——见上面 key 的 KDoc。）
+    // 主会话，VM 里的会话 id 随之变化 ⇒ **承载它的那段组合被销毁重建**（换的是槽位与 key，不是
+    // 那一格 store 本身：它这会儿正被上一层的删除路径 `ChatSessionSlots.reclaim` 交出去）。
     // 挂在 VM 状态上的横幅活不过这一帧，一个字都来不及显示（真机实测过：切回主会话干净利落，
     // 用户完全不知道为什么）。所以文案由 [sessionNotice] 从上层注入（那个状态活得比本 VM 久）。
     LaunchedEffect(state.sessionGone) {
@@ -343,6 +403,136 @@ fun ChatScreen(
     }
     var imageTarget by remember { mutableStateOf<ImageSource?>(null) }
 
+    // —— 语音播放（接收侧）——
+    // 取字节的缓存层：服务端相对路径（`voice.url`）接到**当前服务器地址**上再发请求，字节落在
+    // `cacheDir/media/`（按存储名内容寻址 ⇒ 重复播放一个请求都不发）。`baseUrlProvider` 每次现读：
+    // 换服务器必然重进本组合，而 `mediaApi` 那条客户端也按 baseUrl 重建（见 AppContainer）。
+    val voiceStore = remember(container) {
+        VoiceStore(
+            download = container.mediaRepository::download,
+            cacheDir = container.appContext.cacheDir,
+            baseUrlProvider = { container.authManager.currentBaseUrl },
+        )
+    }
+    // 一条播放通道归**这一个会话**：换会话 = 换实例 = 上一条立刻停并释放；离开聊天页（本组合被
+    // 丢弃）时 `onDispose` 释放（MediaPlayer 不 release 会一直占着解码器，见 VoicePlayer 的 KDoc）。
+    val voicePlayer = rememberVoicePlayer(sessionId) { audio -> voiceStore.load(audio) }
+    val voicePlayback by voicePlayer.state.collectAsState()
+
+    // —— 语音输入（契约 v0.96 §3.15 ①「用户按住麦克风说话」）——
+    // 录音机归**这一个会话**：换会话 = 换实例（与上面那条播放通道同一个生命周期纪律），
+    // 离开聊天页时 `onDispose` 收掉麦克风——一段没发出去的录音不该在后台继续占着它。
+    //
+    // ⚠️ 录音中**转屏**会重建组合 ⇒ 这一段丢失。本端不为此加一个「录音仓」：录音是几秒钟的
+    // 动作，转屏 / 分屏重建时丢掉一次比在 VM 里维护一条 AudioRecord 生命周期便宜得多。
+    val recorder = remember(sessionId) { VoiceRecorder() }
+    DisposableEffect(recorder) {
+        onDispose { recorder.release() }
+    }
+    val recording by recorder.state.collectAsState()
+    val recordingState = recording as? VoiceRecorderState.Recording
+    // 麦克风起不来 / 没授权时的如实告知（本端的问题，不走 VM 的 `error` 通道：
+    // 那条通道的语义是「服务端 / 发送」，而这里一次都没上过路）。
+    var voiceFailure by remember { mutableStateOf<String?>(null) }
+    LaunchedEffect(voiceFailure) {
+        if (voiceFailure != null) {
+            delay(VOICE_FAILURE_NOTICE_MILLIS)
+            voiceFailure = null
+        }
+    }
+
+    val requestAudioPermission = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        if (granted) {
+            // 授权刚拿到手就直接开录（用户按麦克风的意思就是「现在说」，不必再按第二次）。
+            if (!recorder.start()) voiceFailure = VOICE_UNAVAILABLE_MESSAGE
+        } else {
+            voiceFailure = VOICE_PERMISSION_DENIED_MESSAGE
+        }
+    }
+
+    // 开始录音：有权限就直接起；没有就申请。起不来时**如实说一句**，绝不假装在录。
+    fun startVoiceRecording() {
+        // 已经在录就不重入（录音中麦克风那枚按钮本来就不在屏幕上，这里是第二道闸）。
+        if (recorder.state.value is VoiceRecorderState.Recording) return
+        val granted = ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) ==
+            PackageManager.PERMISSION_GRANTED
+        if (granted) {
+            if (!recorder.start()) voiceFailure = VOICE_UNAVAILABLE_MESSAGE
+        } else {
+            voiceFailure = null
+            requestAudioPermission.launch(Manifest.permission.RECORD_AUDIO)
+        }
+    }
+
+    // 「这一次收尾已经在飞」：防双击「发送」，也防它和「录满 60 秒自动收尾」撞在同一帧上。
+    // 第二次进入时录音机已经不在录了，`stop()` 会回 `null`——那会被误读成「没有录到声音」。
+    var finishingVoice by remember { mutableStateOf(false) }
+    // 结束录音并交给 VM：准入判据（空 / 太短 / 超限）全在 `VoiceClip.plan` 里，这里一个字节
+    // 都不自己判——空录音也照旧交给它，好让用户拿到那句「没有录到声音」。
+    fun finishVoiceRecording() {
+        if (finishingVoice) return
+        finishingVoice = true
+        scope.launch {
+            try {
+                val pcm = recorder.stop()
+                viewModel.sendVoice(pcm ?: ByteArray(0))
+            } finally {
+                finishingVoice = false
+            }
+        }
+    }
+
+    // 录满 60 秒：录音机只置位不自动发送（见 VoiceRecorder 的 KDoc），收尾由这一层做。
+    val reachedLimit = recordingState?.reachedLimit == true
+    LaunchedEffect(reachedLimit) {
+        if (reachedLimit) finishVoiceRecording()
+    }
+
+    // `voice_output` 到了就放（契约：这一帧只定向回本连接、断线不补投 ⇒ 不播就永远听不到）。
+    // 键里带 `file`：音频先落成本地文件再进状态，落好那一刻才是真正能播的时刻。
+    // `autoPlay` 只用一次：这一帧到达时用户可能在别的会话，切回来时不该突然响一段旧语音
+    // （判据见 VoiceReply.autoPlay）。「已经在放 / 正在载入」时不重新触发——否则第二次状态
+    // 到达会把正在响的那条停掉。
+    val voiceReply = state.voiceReply
+    LaunchedEffect(voiceReply?.id, voiceReply?.file) {
+        val reply = voiceReply ?: return@LaunchedEffect
+        val file = reply.file ?: return@LaunchedEffect
+        if (!reply.autoPlay) return@LaunchedEffect
+        viewModel.consumeVoiceReplyAutoPlay()
+        if (!voicePlayer.state.value.isActiveFor(reply.id)) {
+            voicePlayer.toggleClip(reply.id) { Result.success(file) }
+        }
+    }
+
+    // 朗读（W75）：字节一落到本机就交给**同一条**播放通道起播（键是 `tts:<messageId>`，
+    // 与语音副本天然互斥——点一个停另一个）。键里带 `file`：`null → 文件` 那一刻才是真正能播的
+    // 时刻。`autoPlay` 只用一次，理由与上面那条完全相同（用户可能已经切走了）。
+    //
+    // ⚠️ `autoPlay` 必须进键：用户「放 → 停 → 再点同一条」时 `(clipId, file)` 一对**没变**
+    // （同一份缓存文件），只按那一对做键就再也不会起播。置假那一次会把键改成 `false`、下一轮
+    // 点击改回 `true`，于是每一点都重新点着一次；置假本身触发的重入在第一行就返回了，不成环。
+    //
+    // 起播之后这一格**不再变**：播放走到哪一步是播放通道的事，VM 不需要知道（见 `TtsClip` 的
+    // 类 KDoc）。
+    val ttsClip = state.ttsClip
+    LaunchedEffect(ttsClip?.clipId, ttsClip?.file, ttsClip?.autoPlay) {
+        val clip = ttsClip ?: return@LaunchedEffect
+        val file = clip.file ?: return@LaunchedEffect
+        if (!clip.autoPlay) return@LaunchedEffect
+        viewModel.consumeTtsAutoPlay()
+        if (!voicePlayer.state.value.isActiveFor(clip.clipId)) {
+            voicePlayer.toggleClip(clip.clipId) { Result.success(file) }
+        }
+    }
+    // 这一屏**走了**就把还没到手的那一次自动起播作废（P2-1）。上面那个 effect 只在这一屏活着的
+    // 时候跑得到：人切走之后结果才落地，闸门没被消费过，切回来时一挂上就会突然响一段旧朗读。
+    // 判据在纯函数 [dropPendingTtsAutoPlay] 里（只动「还没到手」的那一格，绝不打断真的播放）。
+    DisposableEffect(viewModel) {
+        onDispose { viewModel.dropPendingTtsAutoPlay() }
+    }
+
     // 系统相册选择器（PickMultipleVisualMedia 走 Photo Picker 的多选形态，**不需要任何存储权限**）。
     // 上限就是本端的接收上限（[ShareRules.MAX_IMAGES]）：系统选择器会把可选张数卡在这个数上，
     // 并把「最多 4 张」明写在界面上——所以「超限」只会出现在少数不认这个上限的回落路径上
@@ -362,7 +552,9 @@ fun ChatScreen(
     ) { uris -> viewModel.onDocumentsPicked(uris.map { it.toString() }) }
 
     // 「分享到 App」的落地时机。待落地的内容活在 Compose 之外（`ShareIntake`），这里只做三件事：
-    // 挑时机、取走一条、交给既有发送路径。判据本身是纯函数 [shareLanding]（可单测）。
+    // 挑时机、请 VM 认领一条、交给**确认面板**（`ShareConfirmPanel`：内容一进来就发的那条老路已废，
+    // 2026-10-06 主人要求像其他 IM 一样先确认——只有点「发送」才真的发）。
+    // 判据本身是纯函数 [shareLanding]（可单测）。
     // - **取走必须晚于「连接就绪」**：短文本走 WS，而冷启动时握手还没完成（分享冷启动必然撞上），
     //   抢在那之前发只换来一次 `sendChat` 回 false 的「发送失败，请重试」；而 [ShareIntake.take] 是
     //   原子出队、没有归还路径 ⇒ 那一次「其实一次都没发出去」的失败会把内容从待发队列里抹掉，
@@ -373,10 +565,16 @@ fun ChatScreen(
     //   **不可恢复**的 `Offline` 那一档时说 [SHARE_OFFLINE_NOTICE]（「重新登录 / 检查服务器地址」）——
     //   那一档不会自动重连，「连上后自动发出」等的是一个永远不会到来的连接。哪档配哪句是纯函数
     //   [shareWaitingNotice]，两档的落地时机一模一样。
-    // - **只有当前会话的 ChatScreen 在组合**：已访问过的会话的 VM 都还活着（Activity 级
-    //   ViewModelStore），由 UI 层认领才不会让旧会话把内容抢走。
+    // - **只有当前会话的 ChatScreen 在组合**：别的会话的 VM 也可能还活着（各自那一格槽位里，
+    //   见 `ChatSessionSlots`），由 UI 层认领才不会让旧会话把内容抢走。
     // - [ShareIntake.take] 是原子出队：同一条内容不会被发两次。重组 / 切会话 / 连接变化都会重跑这个
     //   effect，哪怕其中一次拿着**已经过期的**快照进来，`take()` 给出的也只是队列里的下一条或 null。
+    // - **取走只发生一次，而且只发生在「手上什么都没有」的那一帧**：取到的那一份落进**VM 的状态**
+    //   （[ChatUiState.shareConfirm]，不是这里的一格 `remember`），面板靠它渲染。effect 的键里有连接
+    //   状态 ⇒ 它会反复重跑，而重跑**绝不会**再取一份、也绝不会重复发送：闸门在 `take()` **之前**，
+    //   而闸门的依据就是 VM 里那一格（`ChatViewModel.claimSharedContent` 的 KDoc 写着它为什么在
+    //   `take()` 之前）。面板开着时新来的分享**原地在队列里等**——键里的 `shareConfirm == null`
+    //   保证面板一关（发送 / 取消）就会再跑一次判据，把它接上。
     val pendingShares by ShareIntake.pending.collectAsState()
     val shareConnection = state.connection
     // 「这一轮等待已经等够久了」。计时只跟**「队列里有东西」与「连上了没有」这两个事实**走：
@@ -386,6 +584,13 @@ fun ChatScreen(
     // 「这一轮等待已经说过了」。它与上面那个标志的生命周期刻意不同：连接抖动（effect 因键变化重跑）
     // 不把它归零，否则同一句话会跟着抖动反复弹——刷屏。内容被取走、或队列清空，才算了结这一轮。
     var shareToldWaiting by remember(sessionId) { mutableStateOf(false) }
+    // 「一份分享已经取走、正在等用户确认」+ 用户补的那句描述。**它们刻意不在 Compose 里**：那一份
+    // 已经出队、没有归还路径，而这一格 `remember` 会随转屏 / 深浅色切换整份丢掉——丢掉的后果是
+    // 那份分享既不在队列里、也不在界面上，**静默消失**（用户什么都没看到，也没有任何提示）。
+    // 所以它住在 VM 的状态里（面板输入框那句描述与正文绑在同一个值里，见 [ShareConfirmDraft]）：
+    // `ChatSessionSlots` 的那一格 `ViewModelStore` 由 `AppContainer` 持有，比 Activity 活得久。
+    // ⚠️ 别把它挪回这里——「比 Activity 活得久」正是它存在的全部理由。
+    val shareConfirm = state.shareConfirm
     LaunchedEffect(sessionId, pendingShares.isEmpty(), shareConnection == WsState.Connected) {
         if (pendingShares.isEmpty() || shareConnection == WsState.Connected) {
             shareWaitedLong = false
@@ -395,8 +600,10 @@ fun ChatScreen(
         shareWaitedLong = true
     }
     // 这个 effect 的键里有连接状态 ⇒ 连接后来就绪时会重跑，内容因此**一次都不会漏发**（也不需要
-    // 任何轮询：状态一变就重来一遍判据）。
-    LaunchedEffect(sessionId, pendingShares, shareConnection, shareWaitedLong) {
+    // 任何轮询：状态一变就重来一遍判据）。键里还有 `shareConfirm == null`——面板一关（发送 / 取消）
+    // 它就翻回来、这个 effect 随之重跑，把面板开着那段时间里攒下的下一条分享接上（不加这个键，
+    // 那一条会一直躺在队列里，直到连接状态碰巧再变一次）。
+    LaunchedEffect(sessionId, pendingShares, shareConnection, shareWaitedLong, shareConfirm == null) {
         val landing = shareLanding(
             hasPending = pendingShares.isNotEmpty(),
             connection = shareConnection,
@@ -405,9 +612,15 @@ fun ChatScreen(
         )
         when (landing) {
             // 取走之后这一轮等待就结束了：下一批内容（或下一次断线）重新计时、重新有资格说那句话。
+            //
+            // **取走只在这一处发生**，而且闸门在 `take()` **之前**（判据是纯函数 [shareConfirmClaim]，
+            // 落在 `ChatViewModel.claimSharedContent` 里）：手上已经有了那份未确认的分享时，这一帧
+            // 一个字节都不动队列——面板开着时来的新分享原地留在待发队列里，等这一份确认完再接，
+            // 那样才不会出现「用户正看着 A，面板里的内容被换成了 B」。转屏重建之后新的一帧照样走到
+            // 这里，而那时**手上已经有东西**（它活在 VM 的状态里），所以也不会再取一次。
             ShareLanding.Send -> {
                 shareToldWaiting = false
-                ShareIntake.take()?.let { share -> viewModel.sendShared(share, shareNoticeFor(share)) }
+                viewModel.claimSharedContent()
             }
 
             // 两个告知档只差措辞（时机一致）：说哪句由纯函数 [shareWaitingNotice] 定，
@@ -486,8 +699,29 @@ fun ChatScreen(
                     images = state.draftImages,
                     documents = state.draftDocuments,
                     busyText = busyLabel(state),
+                    recordingMs = recordingState?.elapsedMs,
+                    voiceDraft = state.voiceDraft,
+                    voiceReply = state.voiceReply,
+                    voicePlayback = voicePlayback,
                     onValueChange = viewModel::onDraftChange,
                     onSend = viewModel::send,
+                    onStartRecording = { startVoiceRecording() },
+                    onStopRecording = { finishVoiceRecording() },
+                    onCancelRecording = { recorder.cancel() },
+                    onRetryVoice = viewModel::retryVoice,
+                    onDiscardVoice = viewModel::discardVoice,
+                    // 播放 / 停止与关闭都在这一个动作里收口：关掉卡片之后再响一秒是明确的 bug。
+                    onToggleVoiceReply = {
+                        val reply = state.voiceReply
+                        val file = reply?.file
+                        if (reply != null && file != null) {
+                            voicePlayer.toggleClip(reply.id) { Result.success(file) }
+                        }
+                    },
+                    onDismissVoiceReply = {
+                        voicePlayer.stop()
+                        viewModel.dismissVoiceReply()
+                    },
                     onPickImage = {
                         imagePicker.launch(
                             PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly),
@@ -519,7 +753,10 @@ fun ChatScreen(
                         val retry = shouldOfferRetryOnEmpty(
                             loading = state.loading,
                             hasError = state.error != null,
-                            hasItems = state.items.isEmpty(),
+                            // ⚠️ 语义是「**有没有**东西」而不是「是不是空」——W52/E 第一版这里传了
+                            // `isEmpty()`，极性反了，于是「列表为空」这个唯一会求值的场景里结论**永远为假**、
+                            // 按钮永远不出现（判据单测用的是正确语义，所以全绿；只有真机才露出来）。
+                            hasItems = state.items.isNotEmpty(),
                         )
                         CenterHint(
                             text = if (retry) FIRST_PAGE_FAILED_HINT else EMPTY_CONVERSATION_HINT,
@@ -546,6 +783,14 @@ fun ChatScreen(
                                     // 自己的外观，①②⑤ 与今天逐字相同。判定是纯函数，接线层不自己猜。
                                     phase = state.phaseOf(item.message),
                                     legBadge = state.legBadgeForMessage(item.message),
+                                    // 语音播放（接收侧）：状态来自**这一个会话**的那条播放通道，
+                                    // 点击交给它去取字节 / 放 / 停。气泡自己不认识 MediaPlayer。
+                                    voicePlayback = voicePlayback,
+                                    // 朗读（W75）：**只有这一条**的朗读状态进来（对不上的当没点过）。
+                                    // 播放状态仍是同一条通道——朗读的键是 `tts:<messageId>`，所以两枚
+                                    // 图标的「正在响」互不串台（判据在气泡里，这里只喂状态）。
+                                    ttsClip = state.ttsClip?.takeIf { it.messageId == item.message.id },
+                                    ttsPlayback = voicePlayback,
                                     onDocumentClick = { ref ->
                                         previewNotice = null
                                         previewTarget = DocumentTarget.of(ref)
@@ -560,6 +805,21 @@ fun ChatScreen(
                                     // 各自用同一份产品口径的纯函数判定。
                                     onEdit = viewModel::startEdit,
                                     onDelete = viewModel::startDelete,
+                                    onVoiceToggle = voicePlayer::toggle,
+                                    // 朗读：请求、失败分类、落盘全在 VM；但**这一下是停还是念**必须在
+                                    // 这里分（判据是纯函数 [ttsSpeakIntent]）。直通 `viewModel::speak`
+                                    // 会让「停止朗读」变成空操作（P1-1）：播放中 `TtsClip.pending` 是假
+                                    // ⇒ VM 的防抖放行、整格换成新 pending、缓存命中秒回，而下面那个起播
+                                    // effect 又因为「已经在放同一条」跳过 `toggleClip`——三处各自都对，
+                                    // 合起来点了没反应。唯一带停止语义的入口在播放通道上，所以在这一层分。
+                                    onSpeak = { message ->
+                                        val clip = state.ttsClip
+                                            ?.takeIf { it.messageId == message.id }
+                                        when (ttsSpeakIntent(voicePlayer.state.value, message.id, clip)) {
+                                            TtsSpeakIntent.Stop -> voicePlayer.stop()
+                                            TtsSpeakIntent.Speak -> viewModel.speak(message)
+                                        }
+                                    },
                                 )
 
                                 is ChatDisplayItem.Pending -> PendingBubble(
@@ -663,6 +923,14 @@ fun ChatScreen(
                     state.sendQueueNotice?.let { message ->
                         Banner(text = message, color = MiuixTheme.colorScheme.onSurfaceVariantSummary)
                     }
+                    // 语音输入被本端挡下（没录到 / 太短 / 太大）：与上面几条同档的如实告知。
+                    state.voiceNotice?.let { message ->
+                        Banner(text = message, color = MiuixTheme.colorScheme.onSurfaceVariantSummary)
+                    }
+                    // 麦克风起不来 / 没授权：这是真错误（功能整个不可用），所以用红色。
+                    voiceFailure?.let { message ->
+                        Banner(text = message, color = MiuixTheme.colorScheme.error)
+                    }
                     searchNotice?.let { message ->
                         Banner(text = message, color = MiuixTheme.colorScheme.onSurfaceVariantSummary)
                     }
@@ -744,6 +1012,24 @@ fun ChatScreen(
             )
         }
     }
+
+    // 分享进来的内容的**确认面板**（W53X：「一到就发」那条老路已废）。面板开着时**一个字节都还
+    // 没发出去**：点「发送」才走既有发送路径，点「取消」这一份就作废。这一处只做接线——内容与
+    // 描述都在 **VM 的状态**里（`state.shareConfirm`，理由见那里与 `ChatViewModel.claimSharedContent`
+    // 的 KDoc），面板本身与它的判据都在 `ShareConfirmPanel.kt`。转屏重建之后面板照旧在这里长出来，
+    // 因为 VM 比 Activity 活得久；**它绝不能被挪回这个组合里**。
+    //
+    // ⚠️ 取走是不可逆的（`ShareIntake.take()` 没有归还路径），所以「取消」**不把内容塞回队列**：
+    // 塞回去会让「用户刚作废的那一份」与「又来了新分享」变成同一件事，两种状态就再也分不开了。
+    shareConfirm?.let { draft ->
+        ShareConfirmPanel(
+            share = draft.share,
+            caption = draft.caption,
+            onCaptionChange = viewModel::onShareCaptionChange,
+            onSend = viewModel::sendShareConfirm,
+            onCancel = viewModel::cancelShareConfirm,
+        )
+    }
 }
 
 /**
@@ -798,14 +1084,43 @@ private fun Banner(text: String, color: Color, onDismiss: (() -> Unit)? = null)
     }
 }
 
+/**
+ * 输入栏：文本 / 图片 / 附件 / **语音**（契约 v0.96 §3.15 ①）。
+ *
+ * ## 三段语音形态各占一行（从上到下）
+ * 1. [VoiceReplyRow]——她的语音回复（`voice_output` 的产物）。放在最上面，因为它说的是
+ *    「刚刚那一轮的答复」，而下面几行是用户还要做的动作；
+ * 2. [VoiceDraftRow]——一段录好但没发出去的语音（重发 / 丢弃）；
+ * 3. **录音中**：整行换成 [VoiceRecordingRow]（录音中 / 取消 / 发送）。
+ *
+ * ## 录音中为什么把整行换掉
+ * 录音是一条有去无回的动作：那一行里同时留着一个「发送」按钮（文本的）与一个「结束录音」按钮，
+ * 手指落错就是把半句话当成文本发出去。换掉之后**文本发送那条路一个字节都没变**（不录音时
+ * 逐字与之前相同），而录音中屏幕上有且只有与该动作有关的两个选择。
+ *
+ * ## 语音入口为什么放在「发送」左边
+ * 与图片 / 附件同一侧（都是「加内容」），发送键仍在最右（肌肉记忆不变）。麦克风常驻——
+ * 它是与打字并列的**另一种输入方式**，不是某个附加能力。
+ */
 @Composable
 private fun InputBar(
     value: String,
     images: List<String>,
     documents: List<DraftDocument>,
     busyText: String,
+    recordingMs: Int?,
+    voiceDraft: VoiceDraftInfo?,
+    voiceReply: VoiceReply?,
+    voicePlayback: VoicePlaybackState,
     onValueChange: (String) -> Unit,
     onSend: () -> Unit,
+    onStartRecording: () -> Unit,
+    onStopRecording: () -> Unit,
+    onCancelRecording: () -> Unit,
+    onRetryVoice: () -> Unit,
+    onDiscardVoice: () -> Unit,
+    onToggleVoiceReply: () -> Unit,
+    onDismissVoiceReply: () -> Unit,
     onPickImage: () -> Unit,
     onRemoveImage: (Int) -> Unit,
     onPickDocument: () -> Unit,
@@ -818,6 +1133,25 @@ private fun InputBar(
             .imePadding()
             .padding(start = 12.dp, end = 12.dp, top = 8.dp, bottom = 4.dp),
     ) {
+        // 她的语音回复：最上面一行，因为它说的是「刚刚那一轮的答复」。
+        voiceReply?.let { reply ->
+            VoiceReplyRow(
+                reply = reply,
+                playback = voicePlayback,
+                onTogglePlay = onToggleVoiceReply,
+                onDismiss = onDismissVoiceReply,
+                modifier = Modifier.padding(bottom = 6.dp),
+            )
+        }
+        // 录好但没发出去的那一段：只在 `voice_input` 没能上行时出现。
+        voiceDraft?.let { draft ->
+            VoiceDraftRow(
+                draft = draft,
+                onRetry = onRetryVoice,
+                onDiscard = onDiscardVoice,
+                modifier = Modifier.padding(bottom = 6.dp),
+            )
+        }
         DraftImagePreviews(images = images, onRemove = onRemoveImage)
         // 待发附件：输入栏上方的一排可移除芯片（顺序即发送顺序，服务端也按这个顺序存）。
         // 整枚也可点：点开的是**本地**那一份预览（还没上传，还没有服务端存储名）。
@@ -826,46 +1160,64 @@ private fun InputBar(
             onRemove = onRemoveDocument,
             onClick = onPreviewDocument,
         )
-        Row(verticalAlignment = Alignment.Bottom) {
-            // 图片入口在还能再选时出现（上限 [ShareRules.MAX_IMAGES]）：选满之后没必要再给一个
-            // 必然被挡回来的入口。到顶这件事本身由 VM 管（入口藏起来只是不给他白跑一趟的机会）。
-            if (images.size < ShareRules.MAX_IMAGES) {
-                IconButton(onClick = onPickImage) {
+        if (recordingMs != null) {
+            VoiceRecordingRow(
+                elapsedMs = recordingMs,
+                onCancel = onCancelRecording,
+                onSend = onStopRecording,
+            )
+        } else {
+            Row(verticalAlignment = Alignment.Bottom) {
+                // 图片入口在还能再选时出现（上限 [ShareRules.MAX_IMAGES]）：选满之后没必要再给一个
+                // 必然被挡回来的入口。到顶这件事本身由 VM 管（入口藏起来只是不给他白跑一趟的机会）。
+                if (images.size < ShareRules.MAX_IMAGES) {
+                    IconButton(onClick = onPickImage) {
+                        Icon(
+                            imageVector = MiuixIcons.Image,
+                            contentDescription = "发送图片",
+                            tint = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                        )
+                    }
+                    Spacer(Modifier.width(4.dp))
+                }
+                // 附件入口一直在：一回合最多 5 份，到顶时由 VM 给出「已达上限」的提示（而不是把入口藏起来）。
+                IconButton(onClick = onPickDocument) {
                     Icon(
-                        imageVector = MiuixIcons.Image,
-                        contentDescription = "发送图片",
+                        imageVector = MiuixIcons.File,
+                        contentDescription = "添加文件附件",
                         tint = MiuixTheme.colorScheme.onSurfaceVariantSummary,
                     )
                 }
                 Spacer(Modifier.width(4.dp))
-            }
-            // 附件入口一直在：一回合最多 5 份，到顶时由 VM 给出「已达上限」的提示（而不是把入口藏起来）。
-            IconButton(onClick = onPickDocument) {
-                Icon(
-                    imageVector = MiuixIcons.File,
-                    contentDescription = "添加文件附件",
-                    tint = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                TextField(
+                    value = value,
+                    onValueChange = onValueChange,
+                    label = "和昔涟说点什么…",
+                    useLabelAsPlaceholder = true,
+                    maxLines = 5,
+                    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Send),
+                    keyboardActions = KeyboardActions(onSend = { onSend() }),
+                    modifier = Modifier.weight(1f),
                 )
-            }
-            Spacer(Modifier.width(4.dp))
-            TextField(
-                value = value,
-                onValueChange = onValueChange,
-                label = "和昔涟说点什么…",
-                useLabelAsPlaceholder = true,
-                maxLines = 5,
-                keyboardOptions = KeyboardOptions(imeAction = ImeAction.Send),
-                keyboardActions = KeyboardActions(onSend = { onSend() }),
-                modifier = Modifier.weight(1f),
-            )
-            Spacer(Modifier.width(8.dp))
-            Button(
-                onClick = onSend,
-                // 图片与附件都可以单独发出（契约：`text` / `image` / `documents` 任一项非空即可，
-                // 纯附件回合服务端**支持**）。
-                enabled = value.isNotBlank() || images.isNotEmpty() || documents.isNotEmpty(),
-            ) {
-                Text("发送")
+                Spacer(Modifier.width(4.dp))
+                // 麦克风（点按开始 / 点按结束，见 [VOICE_RECORD_DESCRIPTION] 的措辞）。
+                // 换行后的入口与图片 / 附件同档；不读偏好、不占文本发送的任何一条判据。
+                IconButton(onClick = onStartRecording) {
+                    Icon(
+                        imageVector = MiuixIcons.Mic,
+                        contentDescription = VOICE_RECORD_DESCRIPTION,
+                        tint = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                    )
+                }
+                Spacer(Modifier.width(4.dp))
+                Button(
+                    onClick = onSend,
+                    // 图片与附件都可以单独发出（契约：`text` / `image` / `documents` 任一项非空即可，
+                    // 纯附件回合服务端**支持**）。
+                    enabled = value.isNotBlank() || images.isNotEmpty() || documents.isNotEmpty(),
+                ) {
+                    Text("发送")
+                }
             }
         }
         // 输入栏下方预留的空间：让输入框/按钮避开屏幕圆角，同时放忙碌提示

app/src/main/kotlin/top/yeij/cyrene/ui/chat/DocumentPreviewDialog.kt

@@ -22,7 +22,9 @@ import androidx.compose.ui.window.Dialog
 import top.yeij.cyrene.data.repository.CachedDocument
 import top.yeij.cyrene.domain.chat.DocumentPreview
 import top.yeij.cyrene.domain.chat.DocumentPreviewPlan
+import top.yeij.cyrene.domain.chat.DocumentSource
 import top.yeij.cyrene.domain.chat.DocumentTarget
+import top.yeij.cyrene.domain.chat.PreviewMetadata
 import top.yeij.cyrene.domain.chat.PreviewSlice
 import top.yeij.cyrene.ui.common.PreferenceCard
 import top.yukonga.miuix.kmp.basic.BasicComponent
@@ -85,6 +87,15 @@ data class DocumentPreviewNotice(val message: String, val error: Boolean = false
  * [PreviewSlice.notice] 非空时在正文上方明写「只显示前 N」并指路另外两条出口——**绝不静默
  * 截断**：用户看到一段像是完整的正文却其实是前 256 KB，是最容易被误读的一种失败。
  *
+ * ## 正文下方那一行元数据
+ * 正文（非文本时是那句人话）**下方**还有一行灰色小字，写的是「这份文件是什么」的格式事实：
+ * 文本给行数 / 字符数（带口径）/ 解码口径 / 服务端的截断标记，非文本给服务端嗅探所得的 mime。
+ * 组装全在纯函数 [PreviewMetadata] 里（**「为什么某一项不显示」也写在那里**），这里只取证据、画一行。
+ *
+ * 它与上方那枚芯片刻意**不重复**：体积与服务端状态芯片上已经写着（同一个数字、同一个词，再写
+ * 一遍只是噪音）；字符数虽然也在芯片上，但芯片那个「8,000 字」没说清是谁的口径——本行补上
+ * 「（服务端注入口径）」，这才不算一句会把用户带偏的话。
+ *
  * @param target 被点开的那一枚芯片（来源判定见 [DocumentTarget.of]，弹层不自己判断）。
  * @param plan 正文区能不能按文本渲染（[DocumentTarget.previewPlan] 的产物，弹层不自己判断）。
  * @param notice 「用其它应用打开 / 保存」这一步的如实告知（没有 App 能开、保存成功或失败）；
@@ -135,22 +146,25 @@ fun DocumentPreviewDialog(
                     TextButton("重试", onClick = onRetry)
                 }
 
-                is DocumentPreviewState.Ready -> when (plan) {
-                    DocumentPreviewPlan.Text -> {
-                        state.slice.notice?.let { text ->
-                            Text(
-                                text = text,
-                                style = MiuixTheme.textStyles.footnote2,
-                                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
-                                modifier = Modifier.padding(bottom = 8.dp),
-                            )
+                is DocumentPreviewState.Ready -> {
+                    when (plan) {
+                        DocumentPreviewPlan.Text -> {
+                            state.slice.notice?.let { text ->
+                                Text(
+                                    text = text,
+                                    style = MiuixTheme.textStyles.footnote2,
+                                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                                    modifier = Modifier.padding(bottom = 8.dp),
+                                )
+                            }
+                            PreviewBody(state.slice)
                         }
-                        PreviewBody(state.slice)
-                    }
 
-                    // 非文本：**正文区留空**，只留那句人话。字节其实已经取回来了（两条出口要用），
-                    // 只是本端不会渲染它——把 PDF 的字节按 UTF-8 显示出来就是一屏乱码。
-                    is DocumentPreviewPlan.NotText -> PreviewHint(plan.message)
+                        // 非文本：**正文区留空**，只留那句人话。字节其实已经取回来了（两条出口要用），
+                        // 只是本端不会渲染它——把 PDF 的字节按 UTF-8 显示出来就是一屏乱码。
+                        is DocumentPreviewPlan.NotText -> PreviewHint(plan.message)
+                    }
+                    PreviewMetadataLine(state = state, plan = plan, target = target)
                 }
             }
 
@@ -199,6 +213,50 @@ fun DocumentPreviewDialog(
     }
 }
 
+/**
+ * 正文**下方**那一行灰色小字：关于这份文件的格式元数据（[PreviewMetadata] 的产物）。
+ *
+ * 组装全在纯函数里（逐档穷举单测），这里只做两件事：**取证据**、**画一行**。
+ * 取证据的两处来源都不许在 UI 层临场发挥：
+ * - 服务端那两件事实（注入字数 / 注入是否被截断）从[芯片模型][DocumentChipModel]里取——
+ *   它就是 DTO 那几字段的唯一换算落点（[DocumentChips.of]）；
+ * - 嗅探所得的 mime 只从 [DocumentSource.Server.mime] 取。本地待发附件**没有**这个结论
+ *   （那时还没上传过），所以它这一项缺席——**不拿扩展名编一个**（`DocumentTarget.openType()`
+ *   对本地来源回的是 `application/octet-stream` 这个兜底值，拿它当「类型」会是本端编的话）。
+ *
+ * 拼出来是空串时**整行不画**（一项证据都没有就没有这一行），绝不留一个空行或一排「未知」。
+ */
+@Composable
+private fun PreviewMetadataLine(
+    state: DocumentPreviewState.Ready,
+    plan: DocumentPreviewPlan,
+    target: DocumentTarget,
+) {
+    val items = remember(state.slice, plan, target) {
+        when (plan) {
+            // 文本：行数 / 字符数（带口径）/ 解码口径 / 服务端的截断标记。
+            // `truncatedLabel` 非空 ⟺ DTO 的 `truncated == true`（见 DocumentChipModel）。
+            DocumentPreviewPlan.Text -> PreviewMetadata.textItems(
+                slice = state.slice,
+                serverCharsLabel = target.chips.charsLabel,
+                contextTruncated = target.chips.truncatedLabel != null,
+            )
+
+            // 非文本：只有服务端嗅探所得的 mime（体积与状态已在上面那枚芯片里）。
+            is DocumentPreviewPlan.NotText ->
+                PreviewMetadata.fileItems((target.source as? DocumentSource.Server)?.mime)
+        }
+    }
+    val line = PreviewMetadata.join(items)
+    if (line.isEmpty()) return
+    Spacer(Modifier.height(10.dp))
+    Text(
+        text = line,
+        style = MiuixTheme.textStyles.footnote2,
+        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+    )
+}
+
 /** 正文区：按行分块、逐块可选中，块数上限由 [DocumentPreviewLimits] 保证。 */
 @Composable
 private fun PreviewBody(slice: PreviewSlice) {

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ImagePreviewDialog.kt

@@ -54,6 +54,7 @@ import top.yeij.cyrene.domain.chat.ImageOpenTypes
 import top.yeij.cyrene.domain.chat.ImageSize
 import top.yeij.cyrene.domain.chat.ImageSource
 import top.yeij.cyrene.domain.chat.ImageZoom
+import top.yeij.cyrene.domain.chat.PreviewMetadata
 import top.yeij.cyrene.domain.chat.ZoomPan
 import top.yeij.cyrene.domain.chat.imageLoadFailureMessage
 import top.yeij.cyrene.ui.common.PreferenceCard
@@ -145,6 +146,28 @@ fun ImagePreviewDialog(
         )
     }
 
+    // 预览内容下方那一行元数据要用的事实：像素与 EXIF 拍摄日期都得先读字节，所以放到 IO 上算。
+    // 键是**那一份缓存**：换一张图（或重试拿回新的字节）才重算，重组不会。
+    val facts by produceState(
+        initialValue = PreviewImageFacts(),
+        key1 = (state as? ImagePreviewState.Ready)?.cached,
+    ) {
+        val cached = (state as? ImagePreviewState.Ready)?.cached ?: return@produceState
+        value = withContext(Dispatchers.IO) { readPreviewImageFacts(cached.bytes) }
+    }
+    val ready = state as? ImagePreviewState.Ready
+    val metadata = PreviewMetadata.join(
+        PreviewMetadata.imageItems(
+            // 「图片通配」不是格式：嗅探与平台声明都判不出来时这一项就缺席，
+            // **不拿 `image/*` 冒充一个答案**。
+            mime = ready?.openType?.takeIf { it != ImageOpenTypes.ANY_IMAGE },
+            width = facts.width,
+            height = facts.height,
+            sizeBytes = ready?.cached?.bytes?.size?.toLong() ?: PreviewMetadata.UNKNOWN_BYTES,
+            capturedAt = facts.capturedAt,
+        ),
+    )
+
     // 保存到下载目录：与附件那条路同一取舍——MIME 恒 */*，落盘的是缓存里那一份**原始字节**
     // （不是重新编码过的位图，JPEG 存下来还是 JPEG）。
     val createDocument = rememberLauncherForActivityResult(
@@ -237,7 +260,8 @@ fun ImagePreviewDialog(
                 }
 
                 ExitPane(
-                    ready = state as? ImagePreviewState.Ready,
+                    ready = ready,
+                    metadata = metadata,
                     notice = notice,
                     note = nameNoteFor(source),
                     onOpen = { openElsewhere() },
@@ -344,12 +368,16 @@ private fun ZoomableImage(file: File, onUndecodable: () -> Unit) {
 /**
  * 底部那一列出口（与附件弹层同一形态）。
  *
+ * 最上面那一行是**预览内容下方**的格式元数据（[PreviewMetadata] 的产物，可能是空串——
+ * 那就整行不画，绝不留一个空行或一排「未知」）；再下面是 [notice]（刚才那个动作的结果）。
+ *
  * 字节还没到位（[ImagePreviewState.Loading] / [ImagePreviewState.Failed]）时两条出口**不给点**：
  * 点了也只能失败，不如让它们明摆着还没准备好。但**关闭**任何时候都在（右上角那个按钮）。
  */
 @Composable
 private fun ExitPane(
     ready: ImagePreviewState.Ready?,
+    metadata: String,
     notice: DocumentPreviewNotice?,
     note: String,
     onOpen: () -> Unit,
@@ -360,6 +388,14 @@ private fun ExitPane(
             .fillMaxWidth()
             .padding(top = 10.dp, bottom = 12.dp),
     ) {
+        if (metadata.isNotEmpty()) {
+            Text(
+                text = metadata,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                modifier = Modifier.padding(horizontal = EXIT_TEXT_MARGIN, vertical = 2.dp),
+            )
+        }
         notice?.let { line ->
             Text(
                 text = line.message,

app/src/main/kotlin/top/yeij/cyrene/ui/chat/MessageBubble.kt

@@ -24,10 +24,20 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalDensity
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.text.AnnotatedString
+import androidx.compose.ui.text.SpanStyle
+import androidx.compose.ui.text.buildAnnotatedString
+import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.rememberTextMeasurer
+import androidx.compose.ui.text.style.TextDecoration
 import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.text.withStyle
 import androidx.compose.ui.unit.dp
 import coil3.compose.AsyncImage
 import top.yeij.cyrene.core.prefs.LocalAppPrefs
@@ -37,9 +47,23 @@ import top.yeij.cyrene.domain.chat.DocumentChipModel
 import top.yeij.cyrene.domain.chat.DocumentChips
 import top.yeij.cyrene.domain.chat.DraftDocument
 import top.yeij.cyrene.domain.chat.ImageHostRebase
+import top.yeij.cyrene.domain.chat.TTS_LOADING_DESCRIPTION
+import top.yeij.cyrene.domain.chat.TTS_SPEAK_DESCRIPTION
+import top.yeij.cyrene.domain.chat.TTS_STOP_DESCRIPTION
 import top.yeij.cyrene.domain.chat.TurnPhase
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.hasVoice
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.isLoadingFor
+import top.yeij.cyrene.domain.chat.isVoiceMessage
+import top.yeij.cyrene.domain.chat.ttsClipIdOf
+import top.yeij.cyrene.domain.chat.ttsTextOf
+import top.yeij.cyrene.domain.chat.voiceFallbackNote
+import top.yeij.cyrene.domain.chat.voiceNote
 import top.yeij.cyrene.domain.enums.LocalEnumCatalog
 import top.yeij.cyrene.domain.parse.ContentPart
+import top.yeij.cyrene.domain.parse.InlineRun
+import top.yeij.cyrene.domain.parse.InlineStyle
 import top.yeij.cyrene.domain.parse.ParsedBubble
 import top.yeij.cyrene.domain.parse.parse
 import top.yukonga.miuix.kmp.basic.Icon
@@ -48,7 +72,13 @@ import top.yukonga.miuix.kmp.basic.Text
 import top.yukonga.miuix.kmp.icon.MiuixIcons
 import top.yukonga.miuix.kmp.icon.basic.Close
 import top.yukonga.miuix.kmp.icon.extended.More
+import top.yukonga.miuix.kmp.icon.extended.Pause
+import top.yukonga.miuix.kmp.icon.extended.Play
 import top.yukonga.miuix.kmp.theme.MiuixTheme
+import java.time.Instant
+import java.time.ZoneId
+import java.time.format.DateTimeFormatter
+import java.util.Locale
 
 /** 流式进行中的光标。 */
 private const val CURSOR = "▍"
@@ -62,6 +92,11 @@ private val MESSAGE_ACTION_ICON_SIZE = 18.dp
 /** 「⋯」与来源角标之间的间距。 */
 private val MESSAGE_ACTION_GAP = 4.dp
 
+/**
+ * 气泡外侧那枚时间与气泡之间的空隙：时间贴气泡，但不贴成一体（也不必去够屏幕边）。
+ */
+private val MESSAGE_TIME_GAP = 6.dp
+
 /** 「⋯」的读屏名字，同时也是设备验收时 `uiautomator` 拿来定位它的 `content-desc`。 */
 private const val MESSAGE_ACTION_DESCRIPTION = "消息操作"
 
@@ -82,6 +117,15 @@ private const val CONTENTLESS_MESSAGE_NOTE = "这条消息的内容没有被传
  *
  * 判据刻意**窄**，只有 `user` 消息才可能成立：
  * - 任何一项非空都不成立——`content` 里哪怕只有一个空格也算有内容（`isBlank` 只吃掉纯空白）；
+ * - **`voice` 键在就一律不成立**（[hasVoice]）：这一条问的是「这条里**有没有东西可看**」，不是
+ *   「有没有语音形态」，所以两档都要挡住：
+ *   - `status = empty` / `transcribed`（语音形态画得出来）：转写文本可能为空，但那条消息**不是
+ *     什么都没有** —— 它有一个语音形态（`VoiceMessageRow` 会把它画出来）。少了这一档，一条
+ *     「微信语音、没认出发音、也没有音频副本」的消息会被扣上「内容没有被传过来」这顶帽子，
+ *     而那句话是**假的**；
+ *   - `status = failed`（入站转写失败 / 出站合成降级）：**没有**语音形态，但有一条正文
+ *     （服务端那行诚实提示 / 降级后的原文本）和那行降级小标（[voiceFallbackNote] 的产物）——
+ *     同样不是「什么都没有」；
  * - `assistant` 一律不成立：她的空消息是另一个话题（可能是流式还没到、也可能是有意不说），
  *   顺手改会波及所有助手气泡，不在本次范围内。
  *
@@ -94,7 +138,11 @@ fun isContentlessUserMessage(message: HistoryMessageDto): Boolean =
         message.content.isBlank() &&
         message.image.isNullOrBlank() &&
         message.documents.isEmpty() &&
-        message.thinking.isNullOrBlank()
+        message.thinking.isNullOrBlank() &&
+        // 判据只有一处（domain.chat.hasVoice）：绝不在这里另写一个 `voice != null`。
+        // ⚠️ 用 hasVoice 而不是 isVoiceMessage：failed 行（转写失败 / 合成降级）也**不是**什么都没有
+        // —— 它有正文（服务端那行诚实提示 / 降级后的原文本）与那行降级小标（voiceFallbackNote）。
+        !hasVoice(message)
 
 /**
  * 一条落库消息渲染成一个或多个气泡：
@@ -103,11 +151,34 @@ fun isContentlessUserMessage(message: HistoryMessageDto): Boolean =
  * - 其它 mode 原样整条渲染，不解析标签；
  * - `thinking` 非空时（来自 REST `/messages`，owner 可见）在气泡上方显示思维链卡片；
  * - `documents` 非空时在气泡上方显示附件芯片（绝大多数消息是空列表，此时一个像素都不画）；
+ * - `voice` 键在时（🎤 判据 = **这个键存在且 `status != "failed"`**，契约 §4.4 + 后端 M57-M59
+ *   预告，见 `isVoiceMessage`）在正文之外多画一枚语音形态（[VoiceMessageRow]：播放 / 暂停 + 时长，
+ *   有副本时才有播放控件）；正文照常渲染——转写文本 / 服务端那行诚实提示都在里面，一个字都不改；
+ *   `status = "failed"` 那一档（入站转写失败 / 出站合成降级）**没有**语音形态可画，改为在正文之外
+ *   多画一行灰色小标（[VoiceFallbackNote]，文案由 `voiceFallbackNote` 给：固定前半句 +
+ *   服务端 `fallbackReason` 原样）；
  * - `image` 非空时在气泡上方显示图片，**点它进全屏查看**（[onImageClick]）；渲染前先过
  *   [ImageHostRebase]（见 [imageBaseUrl]）；
  * - `user` 消息**什么都没有**（[isContentlessUserMessage]）时，气泡位置改为一句如实的说明
  *   （[ContentlessNote]）——空气泡是最糟的一种呈现：用户完全不知道发生了什么。
  *
+ * ## 外侧那枚时间（W69）
+ * 每条**落库**消息在气泡外侧再画一枚灰色小字（主人：用户的气泡靠右 ⇒ 时间贴气泡左边；她的气泡
+ * 靠左 ⇒ 时间贴气泡右边）：文案由纯函数 [messageTimeLabel] 给（今天 `14:30` / `昨天 09:05` /
+ * `3月7日 09:05` / 跨年 `2025年12月31日`），布局与宽度取舍见 [BubbleWithTime]。
+ * 它是与气泡下方那行角标（来源 / 六态 / 「⋯」）**并列的另一块**：那块说的是「这条从哪来、能对它
+ * 做什么」，这一块说的是「它什么时候发生的」，两处一个字都不改。
+ *
+ * 挂在哪一块由纯函数 [messageTimeCarrier] 给：先找**最后一个有正文的气泡**（W69 原本那一档）；
+ * 这条**一个正文气泡都没有**时，改挂到**最后画出来的那个附件块**上（附件芯片排 / 图片 / 语音那一块
+ * ——语音形态或 `failed` 行的降级小标，`voice` 键在就必画其一）
+ * ——它旁边那一块就是这时唯一的位置参照物。少了这一档，一条只有附件的消息会因为
+ * `bubbles` 里那个 `body` 为空的占位气泡（`Bubble` 见空 body 就什么都不画）而**整条没有时间**
+ * （W72 补的就是它）。
+ *
+ * 只有落库消息有它：流式气泡（[StreamingBubble]）与待发气泡（[PendingBubble]，[PendingMessage]
+ * 本端就没有时间戳这个概念）走的都是「不显示」那一档。
+ *
  * 文本可自由选择：每个气泡/旁白各自包一层 [SelectionContainer]，
  * 因此选择菜单的「全选」只作用于当前那一块，而不是整个页面。
  *
@@ -136,6 +207,15 @@ fun isContentlessUserMessage(message: HistoryMessageDto): Boolean =
  *   回复侧在 [StreamingBubble] 上挂一次，用户就能把它们配起来。
  * @param onEdit 用户选中「编辑」：交给上层打开编辑弹层（本组件不自己发请求）。
  * @param onDelete 用户选中「删除」：交给上层打开删除确认（不可恢复，必须二次确认）。
+ * @param voicePlayback 那条**播放通道**此刻的状态（`ui.chat.VoicePlayer` 的 `state`）。只有指出
+ *   本条消息的那几个态（正在放 / 正在取字节 / 上一次失败）会改变这枚语音形态的外观；默认
+ *   [VoicePlaybackState.Idle] 则与「没有播放通道」逐像素相同（不画任何播放中的痕迹）。
+ * @param onVoiceToggle 用户点了这枚语音的播放 / 暂停：交给上层真正去取字节 / 放 / 停。
+ * @param ttsClip 这一条（或**别的一条**）的朗读状态；只有 `messageId` 对得上时才影响本条。
+ *   见 [TtsClip]：`null` / 对不上 / 本条没点过朗读 ⇒ 与加这一块之前逐像素相同。
+ * @param ttsPlayback 那条**播放通道**此刻的状态。朗读与语音副本共用它，所以朗读的键是
+ *   `ttsClipIdOf(message.id)` 而不是 `message.id` —— 两枚图标的「正在响」互不串台。
+ * @param onSpeak 用户点了「朗读」：交给上层发请求（本组件不自己发）。
  */
 @Composable
 fun MessageBubble(
@@ -143,10 +223,15 @@ fun MessageBubble(
     imageBaseUrl: String = "",
     phase: TurnPhase = TurnPhase.Sent,
     legBadge: String? = null,
+    voicePlayback: VoicePlaybackState = VoicePlaybackState.Idle,
+    ttsClip: TtsClip? = null,
+    ttsPlayback: VoicePlaybackState = VoicePlaybackState.Idle,
     onDocumentClick: (DocumentRefDto) -> Unit = {},
     onImageClick: (String) -> Unit = {},
     onEdit: (HistoryMessageDto) -> Unit = {},
     onDelete: (HistoryMessageDto) -> Unit = {},
+    onVoiceToggle: (HistoryMessageDto) -> Unit = {},
+    onSpeak: (HistoryMessageDto) -> Unit = {},
 ) {
     val isUser = message.role == "user"
     // 这里的 `chat` 是 **mode id**，与 `/meta/enums` 的 modes 表里那一条同源但用途不同：
@@ -168,6 +253,34 @@ fun MessageBubble(
     // 所以 ③ 排队中**不会**被渲染成灰态——规范 §1.3 特意点名不要合并这两态。
     val gray = phase == TurnPhase.Answering
 
+    // 气泡**外侧**那枚时间（W69）。它在组合期按当下时刻算一次，**不 remember**：文案是
+    // (时间戳, 现在, 时区) 的函数，而「现在」只在重组时才有机会更新——冻结它就等于让跨天之后
+    // 还挂着昨天的口径。代价是「页面开着不动、跨度又恰好跨过零点」时它不会自己变，
+    // 不为这一件事加一个 ticker（见 [messageTimeLabel]）。
+    val outsideTime = messageTimeLabel(
+        createdAt = message.createdAt,
+        nowMillis = System.currentTimeMillis(),
+    )
+    // 时间挂在哪一块：判据全在纯函数里（[messageTimeCarrier]，可单测）。原来是「最后一个有正文的
+    // 气泡」（而不是「列表最后一项」——解析出的末段偶尔只有旁白，那一项不画正文框，挂上去时间就
+    // 没有落脚点），于是**纯附件消息**（有 documents 或 image、`content` 为空 ⇒ 一个正文气泡都没有）
+    // 那一行根本没被画出来。
+    val timeCarrier = messageTimeCarrier(message, bubbles)
+
+    // —— 朗读（W75）——
+    // 「这条消息有没有可念的正文」：判据与 VM 发请求用的是**同一个纯函数**（[ttsTextOf]），
+    // 所以「画了入口」与「发得出去」永远不会分叉。这里喂的是**已经解析好的** `bubbles`：
+    // 它们就是屏幕上这些气泡，比让纯函数再解析一遍更贴近「用户看到的那段字」。
+    // 只给她的消息（`assistant`）——主人的话不该用她的声音念回来，VM 里还有第二道闸。
+    val speakable = !isUser && remember(bubbles) { ttsTextOf(bubbles) != null }
+    // 本条自己的那份朗读状态：`messageId` 对不上的（用户点了别的一条）一律当没点过。
+    val ownClip = ttsClip?.takeIf { it.messageId == message.id }
+    val ownClipId = remember(message.id) { ttsClipIdOf(message.id) }
+    val speakActive = ttsPlayback.isActiveFor(ownClipId)
+    // 「正在准备」有两个来源：VM 那边请求还在飞（网络 / 合成，绝大多数时间在这里），以及播放通道
+    // 正在取字节（本端落好的文件是直接给的，这一档只是一闪而过）。
+    val speakPending = ownClip?.pending == true || ttsPlayback.isLoadingFor(ownClipId)
+
     MessageGroup(
         isUser = isUser,
         footer = bubbleFooter(
@@ -177,19 +290,80 @@ fun MessageBubble(
             shared = isSharedMessage(message),
         ),
         onOpenMenu = openMenu,
+        onSpeak = if (speakable) { { onSpeak(message) } } else null,
+        speakActive = speakActive,
+        speakPending = speakPending,
+        ttsFailure = ownClip?.failure,
     ) {
         message.thinking?.takeIf { it.isNotBlank() }?.let { ThinkingCard(it) }
-        DocumentChipRow(
-            chips = message.documents.map(DocumentChips::of),
-            alignEnd = isUser,
-            onClick = { index -> message.documents.getOrNull(index)?.let(onDocumentClick) },
-        )
+        // 下面三块（附件芯片排 / 图片 / 语音形态）与正文气泡共用 [BubbleWithTime]：**这条一个正文
+        // 气泡都没有时**，它们中的一个就是时间的落脚点。不是那一个时 `time = null`，
+        // [BubbleWithTime] 连 `Box` 都不建 ⇒ 与 W69 之前逐像素相同。
+        if (message.documents.isNotEmpty()) {
+            BubbleWithTime(
+                time = outsideTime.takeIf { timeCarrier == MessageTimeCarrier.Attachments },
+                isUser = isUser,
+            ) { side ->
+                DocumentChipRow(
+                    chips = message.documents.map(DocumentChips::of),
+                    modifier = side,
+                    alignEnd = isUser,
+                    onClick = { index -> message.documents.getOrNull(index)?.let(onDocumentClick) },
+                )
+            }
+        }
         message.image?.takeIf { it.isNotBlank() }?.let { ImageHostRebase.apply(it, imageBaseUrl) }
-            ?.let { ChatImage(it, onImageClick) }
+            ?.let { image ->
+                BubbleWithTime(
+                    time = outsideTime.takeIf { timeCarrier == MessageTimeCarrier.Image },
+                    isUser = isUser,
+                ) { side ->
+                    ChatImage(model = image, onClick = onImageClick, modifier = side)
+                }
+            }
+        message.voice?.let { voice ->
+            // 语音形态画在正文**之外**（正文那条路一个字都不动）：转写文本 / 服务端那行诚实提示
+            // 照常由下面的气泡渲染。「无副本就只留文本、不画播放控件」与「durationMs 缺席就不显示
+            // 时长」两条判据都在 VoiceMessageRow 里（它自己调纯函数），这里不重复判一次。
+            if (isVoiceMessage(message)) {
+                BubbleWithTime(
+                    time = outsideTime.takeIf { timeCarrier == MessageTimeCarrier.Voice },
+                    isUser = isUser,
+                ) { side ->
+                    VoiceMessageRow(
+                        voice = voice,
+                        messageId = message.id,
+                        playback = voicePlayback,
+                        note = voiceNote(voice.status, message.content),
+                        alignEnd = isUser,
+                        onToggle = { onVoiceToggle(message) },
+                        modifier = side,
+                    )
+                }
+            } else {
+                // status == "failed"：这条**没有可播的声音**（入站转写失败 / 出站合成降级）。
+                // 正文照常按文字渲染（下面那条路），这里只多画一行灰色小标 —— **不**画语音形态：
+                // 画出来就是一个必然播不了的控件（见 isVoiceMessage 的 KDoc）。
+                // 没有这一行，这一条与普通文字消息逐像素相同，看的人无从知道它本来是一段声音。
+                voiceFallbackNote(voice)?.let { note ->
+                    BubbleWithTime(
+                        time = outsideTime.takeIf { timeCarrier == MessageTimeCarrier.Voice },
+                        isUser = isUser,
+                    ) { side ->
+                        VoiceFallbackNote(text = note, alignEnd = isUser, modifier = side)
+                    }
+                }
+            }
+        }
         if (isContentlessUserMessage(message)) {
             // 空气泡是最糟的一种呈现：用户完全不知道发生了什么。这里如实说一句（见 [ContentlessNote]）。
-            ContentlessNote(onLongPress = openMenu)
+            BubbleWithTime(time = outsideTime, isUser = isUser) { side ->
+                ContentlessNote(onLongPress = openMenu, modifier = side)
+            }
         } else {
+            // 时间挂在**最后一个有正文的气泡**外侧。`null` = 这条的落点在附件块上（或这条一个字都不画），
+            // 此时正文气泡一个都不带时间——时间挂在这条消息上一次，不跟着每个气泡重复。
+            val carrierIndex = (timeCarrier as? MessageTimeCarrier.TextBubble)?.index
             bubbles.forEachIndexed { index, bubble ->
                 Bubble(
                     bubble = bubble,
@@ -198,6 +372,7 @@ fun MessageBubble(
                     showCursor = gray,
                     onLongPress = openMenu,
                     gray = gray,
+                    sideTime = outsideTime.takeIf { index == carrierIndex },
                 )
             }
         }
@@ -300,6 +475,147 @@ fun bubbleFooter(
     return parts.takeIf { it.isNotEmpty() }?.joinToString(" · ")
 }
 
+/**
+ * 一条消息**外侧**那枚灰色时间的文案（纯函数，可单测）；`null` = 这条一个字都不画。
+ *
+ * 四档，全部按**本地日历日**分（不是「相差不到 24 小时」那种算法：`23:59` 与次日 `00:01` 只差
+ * 两分钟，却已经跨天，这一档必须是「昨天」）：
+ * - **今天**（与 `nowMillis` 落在同一个本地日期）→ `14:30`；
+ * - **昨天** → `昨天 09:05`；
+ * - **今年内更早** → `3月7日 09:05`（月日不补零，时分补零）；
+ * - **跨年** → `2025年12月31日`。**刻意不带时分**：一年前的消息精确到分没有意义，年月日已经
+ *   把「多久远」说清了，多四个字符反而更难扫。
+ *
+ * ## 未来时间：按「今天」那一档显示（不造「明天」这个词）
+ * 服务端时钟略快 / 本机时钟略慢时会出现几秒到几分钟「之后」的时间戳，它没有任何要表达的语义
+ * （这条就是刚刚到的），所以只显示 `HH:mm`——那正是这条消息发生的那一刻。判据因此写成
+ * `!day.isBefore(today)` 而不是 `day == today`：顺手也把「服务端时钟整整偏了一天 / 一年」这种
+ * 坏时钟吃掉——宁可只显示一个时刻，也不在用户眼皮底下编出一个他从没见过的「明天」或假日期。
+ *
+ * ## 非法 / 缺失（`<= 0`）：整条不画
+ * 这个字段是**毫秒 Unix 时间戳**；`0` / 负数只可能来自「这个键根本没传过来」或解析事故，不是
+ * 一个真实时刻。画成 `1970年1月1日` 或 `--:--` 都是在替服务端编一个它没说过的答案；而一条没有
+ * 时间的消息并不缺什么（正文、来源角标、动作入口都还在，见 [MessageBubble]）。
+ *
+ * ## 为什么在 UI 层算，而不是让 VM 把文案算好塞进 item
+ * 它只依赖（这条的时间戳，现在，时区）——前两个 UI 层本地就有。为了一个「现在」去动 item 模型与
+ * 列表的 key 不划算，而且那样还会把文案**冻住**：同一秒里算出来的字符串被 diff 当成同一个 item，
+ * 跨天之后那一屏就永远停在旧口径。
+ *
+ * `zone` 可注入（默认本机时区），`nowMillis` 由调用方喂：这条映射自己不读表，所以可单测、可复现
+ * （与 [searchHitTime] 同一条写法）。
+ */
+fun messageTimeLabel(
+    createdAt: Long,
+    nowMillis: Long,
+    zone: ZoneId = ZoneId.systemDefault(),
+): String? {
+    if (createdAt <= 0L) return null
+    val at = Instant.ofEpochMilli(createdAt).atZone(zone)
+    val day = at.toLocalDate()
+    val today = Instant.ofEpochMilli(nowMillis).atZone(zone).toLocalDate()
+    return when {
+        // 今天**与未来**同一档（见 KDoc：未来只可能是时钟漂移，不造「明天」这个词）。
+        !day.isBefore(today) -> at.format(MessageClockFormat)
+        day == today.minusDays(1) -> "$YESTERDAY_PREFIX ${at.format(MessageClockFormat)}"
+        day.year == today.year -> at.format(MessageDayFormat)
+        else -> at.format(MessageDateOnlyFormat)
+    }
+}
+
+/**
+ * 「今天」那一档，同时也是其余各档拼时分的零件：24 小时制、补零。
+ *
+ * `Locale.ROOT`：刻意不跟随设备 `locale`——这几档文案的形状是固定的（「3月7日」不会因为系统语言
+ * 变成别的写法），不给本地化留口子。
+ */
+private val MessageClockFormat = DateTimeFormatter.ofPattern("HH:mm", Locale.ROOT)
+
+/**
+ * 「今年内更早」那一档：`3月7日 09:05`（月日**不**补零，与 [messageTimeLabel] 的例一致）。
+ *
+ * 两处模式字母都要盯住：**`d`** 才是「月里的第几天」，大写 **`D`** 是「一年里的第几天」
+ * （`M'月'D'日'` 会把 8 月 14 日排成「8月226日」——W69 的单测就是在这一步拦下的）。
+ */
+private val MessageDayFormat = DateTimeFormatter.ofPattern("M'月'd'日' HH:mm", Locale.ROOT)
+
+/** 「跨年」那一档：`2025年12月31日`（刻意不带时分）。 */
+private val MessageDateOnlyFormat = DateTimeFormatter.ofPattern("yyyy'年'M'月'd'日'", Locale.ROOT)
+
+/** 「昨天」那两个字：只与时分连用（`昨天 09:05`），不会单独成句。 */
+private const val YESTERDAY_PREFIX = "昨天"
+
+/**
+ * 这条消息的时间**落在哪一块**上（[messageTimeCarrier] 的返回值）。
+ *
+ * 之所以要给它一个名字，是因为「时间挂在正文气泡上」与「时间挂在附件块上」在 [MessageBubble] 里
+ * 是**两处不同的调用点**（前者由 [Bubble] 经 `sideTime` 代画，后者各自包一层 [BubbleWithTime]），
+ * 而某条消息只能落一个地方。判据本身是纯函数，所以「纯附件消息也有时间」这件事能被单测直接钉住，
+ * 不必去跑一个 Compose 测试。
+ */
+sealed interface MessageTimeCarrier {
+    /** 正文气泡：`bubbles` 里的下标（[MessageBubble] 解析出来的第几个气泡）。 */
+    data class TextBubble(val index: Int) : MessageTimeCarrier
+
+    /** 附件芯片排（`documents` 非空才会画）。 */
+    data object Attachments : MessageTimeCarrier
+
+    /** 图片（`image` 非空才会画）。 */
+    data object Image : MessageTimeCarrier
+
+    /** 语音那一块（`voice` 键在才会画：语音形态，或 `failed` 行的降级小标）。 */
+    data object Voice : MessageTimeCarrier
+}
+
+/**
+ * 这条消息外侧那枚时间该挂在哪一块上（纯函数，可单测）；`null` = 什么都不挂。
+ *
+ * ## 判据 = 渲染顺序里**最后一块真的画得出来**的东西
+ *
+ * [MessageBubble] 那一列从上到下的顺序是：思维链 → 附件芯片排 → 图片 → 语音那一块 → 正文气泡。
+ * 时间贴在**最后一块**旁边，读起来就是「这条消息发生在什么时候」的落款。
+ *
+ * 1. **先找最后一个有正文的气泡**（W69 原本那一档，一个字都不改）。为什么不是「列表最后一项」：
+ *    解析出来的末段偶尔只有旁白（`<action>` / `<narration>`），那一项不画正文框，挂上去时间就
+ *    没有落脚点。为什么不是第一个：一条多段消息的时间该落在它**结束**的地方。
+ * 2. **一个正文气泡都没有**时，按「谁最后画」往回退：语音那一块 → 图片 → 附件芯片排。这一档就是
+ *    **纯附件消息**（`documents` 非空、`content` 为空）：`content` 空 ⇒ 解析出来的那个占位气泡
+ *    `body` 也是空 ⇒ [Bubble] 见空 body 什么都不画，于是 W69 的时间**整条没被画出来**
+ *    （主人 2026-10-07 验收时发现的缺口）。
+ *    「语音那一块」按 `voice` 键判（[hasVoice]）而**不**按 [isVoiceMessage]：`failed` 行不画语音
+ *    形态，但会画那行降级小标（[VoiceFallbackNote]）——它也占着一块，也照样能挂时间。
+ * 3. 三块也都没有 ⇒ `null`：这条消息确实一个可视的块都没有。
+ *
+ * ## 谁**不**走这一档
+ * - **真的空气泡**（[isContentlessUserMessage] 成立）：上面三块按判据一定都不在，所以这里返回
+ *   `null`；但那种消息**仍然有时间**——[MessageBubble] 把 [ContentlessNote] 自己包了一层
+ *   [BubbleWithTime]。两处刻意分开：那块的落脚点由 `ContentlessNote` 那条路自己交代，不必让这个
+ *   函数认识它（它只答「附件块和正文气泡里挂哪个」）。
+ * - **思维链卡片**：它永远画在最上面，不可能是「最后一块」（有别的块时被别的块盖过，没别的块时
+ *   这条消息的真问题也不是时间）。不把它算进来 ⇒ 只有思维链的助手消息与 W69 之前逐字相同。
+ * - **流式 / 待发气泡**：它们根本不调这个函数（见 [BubbleWithTime] 的 KDoc）。
+ *
+ * 与角色无关：她侧（`assistant`）也会带附件与图，同一条规则照用。贴哪一侧由 [BubbleWithTime]
+ * 按 `isUser` 定，不在这里判——这一层只回答「挂在哪一块」，不回答「挂在它的哪一边」。
+ *
+ * @param bubbles [MessageBubble] 已经解析好的气泡列表（本函数不去 `parse` 一遍：那一份判据在
+ *   `isChat` 上，重复算一次会多出「两份解析结果不一致」的可能）。
+ */
+fun messageTimeCarrier(
+    message: HistoryMessageDto,
+    bubbles: List<ParsedBubble>,
+): MessageTimeCarrier? {
+    val lastBody = bubbles.indexOfLast { it.body.isNotEmpty() }
+    if (lastBody >= 0) return MessageTimeCarrier.TextBubble(lastBody)
+    // 与 [MessageBubble] 里画它们的顺序**相反**：最后画的那一块才是时间的落点。
+    return when {
+        hasVoice(message) -> MessageTimeCarrier.Voice
+        !message.image.isNullOrBlank() -> MessageTimeCarrier.Image
+        message.documents.isNotEmpty() -> MessageTimeCarrier.Attachments
+        else -> null
+    }
+}
+
 /**
  * 乐观发送中的用户消息（还没落库）。
  *
@@ -334,6 +650,9 @@ fun PendingBubble(
             onClick = { index -> item.documents.getOrNull(index)?.let(onDocumentClick) },
         )
         item.imageUri?.takeIf { it.isNotBlank() }?.let { ChatImage(it, onImageClick) }
+        // 语音：正文是空的（本端不转写，用户说的话要等服务端 STT 之后才落库），
+        // 所以这一条消息至少要有「这是语音、多长」这一枚可见凭据——与接收侧的语音形态同一个外观。
+        item.voiceDurationMs?.let { durationMs -> VoiceClipLabel(durationMs) }
         if (item.text.isNotEmpty()) Bubble(plainBubble(item.text), isUser = true, isLast = true)
     }
 }
@@ -497,6 +816,10 @@ private fun MessageGroup(
     isUser: Boolean,
     footer: String? = null,
     onOpenMenu: (() -> Unit)? = null,
+    onSpeak: (() -> Unit)? = null,
+    speakActive: Boolean = false,
+    speakPending: Boolean = false,
+    ttsFailure: String? = null,
     content: @Composable ColumnScope.() -> Unit,
 ) {
     Column(
@@ -509,7 +832,7 @@ private fun MessageGroup(
         content()
         // 来源角标挂在消息组末尾，紧随它标注的那条消息（主人右下、昔涟左下）。
         // 「⋯」与它同一行：那枚图标是**看得见的**动作入口（长按同样能开，见 [MessageBubble]）。
-        if (footer != null || onOpenMenu != null) {
+        if (footer != null || onOpenMenu != null || onSpeak != null) {
             Row(
                 verticalAlignment = Alignment.CenterVertically,
                 horizontalArrangement = Arrangement.spacedBy(MESSAGE_ACTION_GAP),
@@ -522,6 +845,31 @@ private fun MessageGroup(
                         modifier = Modifier.padding(start = 6.dp, end = 6.dp),
                     )
                 }
+                // 「朗读」紧挨「⋯」：两枚都是这条消息的动作，分开放会让人以为是两个话题。
+                // 与「⋯」同一个尺寸、同一条 `Icon + clickable` 纪律（理由见下面那段注释）。
+                if (onSpeak != null) {
+                    Icon(
+                        imageVector = if (speakActive) MiuixIcons.Pause else MiuixIcons.Play,
+                        contentDescription = when {
+                            speakActive -> TTS_STOP_DESCRIPTION
+                            speakPending -> TTS_LOADING_DESCRIPTION
+                            else -> TTS_SPEAK_DESCRIPTION
+                        },
+                        // 正在响 ⇒ 主色（与语音形态那枚图标同一口径）；其余是角标行那档灰。
+                        tint = if (speakActive) {
+                            MiuixTheme.colorScheme.primary
+                        } else {
+                            MiuixTheme.colorScheme.onSurfaceVariantSummary
+                        },
+                        // 正在准备时**点不动**：这时候再发一次请求没有任何意义，用户想要的是
+                        // 「别再等了」——而那条路（取消在飞的合成）本端没有做，所以不给一个
+                        // 点了没反应的入口（见报告「未做」）。
+                        modifier = Modifier
+                            .size(MESSAGE_ACTION_ICON_SIZE)
+                            .clip(CircleShape)
+                            .clickable(enabled = !speakPending, onClick = onSpeak),
+                    )
+                }
                 if (onOpenMenu != null) {
                     // 用 Icon + clickable 而不是 IconButton：后者的最小交互尺寸会把每一条消息的
                     // 角标行撑到 48dp，整屏因此凭空变高一大截；这里只要一枚小图标能点中就够了
@@ -538,9 +886,104 @@ private fun MessageGroup(
                 }
             }
         }
+        // 朗读没成功时那一句。挂在角标行**下面**、自成一行：塞进那一行会把来源角标挤成两截，
+        // 而这句话是给用户看的一整句，不该跟角标抢横向空间。
+        // 颜色用 `error` 而不是灰：它是一条**如实告知**（不是装饰），但也不弹窗、不打断——
+        // 用户的眼睛本来就在他刚点的那条消息上。
+        if (ttsFailure != null) {
+            Text(
+                text = ttsFailure,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+                modifier = Modifier.padding(start = 6.dp, end = 6.dp),
+            )
+        }
     }
 }
 
+/**
+ * 气泡本体 + 它**外侧**那一枚灰色时间（主人 W69）：**用户**的气泡靠右 ⇒ 时间贴气泡**左边**；
+ * **她**的气泡靠左 ⇒ 时间贴气泡**右边**。
+ *
+ * ## 时间那一条的宽度是「量」出来的，不参与宽度分配
+ * 气泡可用宽度有限（[BubbleBody] 自己封了 `300.dp` 的上限），而时间与气泡**同一行**，必然分掉
+ * 一点横向空间。这里**不让两者去抢 weight**，而是先用 [rememberTextMeasurer] 把这一行字按
+ * **它将要用的那个 [MiuixTheme.textStyles.footnote2]** 量一遍，拿到它排出来的**精确宽度**，
+ * 再用 `padding` 把这条宽度从气泡的可用宽度里**先扣掉**：
+ * - 时间量得准（同一份 `TextStyle`、同一份字体缩放与字体回退，量出来的就是排出来的那一串字——
+ *   `Text` 内部只是在它自己那份 `style` 上 merge 显式参数，不参数字段一律不动），所以它**既不会
+ *   溢出屏幕、也不会被压成两行**；
+ * - 气泡吃**剩下的全部**宽度（`padding` 是在约束里扣的，气泡自己的 `widthIn(max = 300.dp)` 照旧
+ *   生效 ⇒ 实际可用宽度 = `min(300.dp, 屏宽 - 两边 14dp - 时间条)`），所以长消息照旧用满能用的宽度。
+ *   代价写在明处：**有时间的消息，气泡比加这一块之前最多窄一条时间的宽度**（这是「时间与气泡同行」
+ *   的必然结果，也是主人要的那件事）。只有「极窄屏 + 超大字号」这一条极端组合下气泡才会明显变窄
+ *   ——那时我们选择**如实把日期显示完整**：截断「2025年12月31日」比窄一点的气泡更亏。
+ *
+ * 为什么不用「把时间排在子节点前面、让它先占住宽度」这种零测量的写法：`Row` 给非 weight 子节点的
+ * 宽度是**按子节点顺序**递减的，所以「气泡在前」的那一侧（她那一侧）必然先把宽度吃光、把时间挤成
+ * 一条竖线；而 Compose 的 `Row` 只有「顺序摆放」一种排布，做不到「先量、后摆」。自写 `Layout` 当然
+ * 可以，但要自己接管窄屏下的钳制，而且那份宽度就是同一笔账——量一次是这里最小的一步。
+ *
+ * ## 摆在哪（三条都是「不许动气泡」的具体落实）
+ * - 时间在**气泡外边**：`padding` 在 `clip` / `background` 之外，所以它不是气泡的一部分——底色、
+ *   圆角、[SelectionContainer] 的选字范围、长按的点击区全都与加它之前逐像素 / 逐行为相同；
+ * - 时间与气泡**底对齐**：贴着气泡最后一行（气泡很高时它也不会跑到中间去）；
+ * - 与气泡之间有 [MESSAGE_TIME_GAP] 的空隙，免得那串灰字和气泡贴成一体。
+ *
+ * 整块（时间 + 气泡）仍由 [MessageGroup] 那一列按角色对齐（主人靠右、她靠左），所以**气泡自己那
+ * 一侧**离屏幕的边距与没有时间时**逐像素相同**——时间填的正是原本空着的那条区域。
+ *
+ * @param time `null` = 这条消息不显示时间（时间戳缺失 / 非法，见 [messageTimeLabel]）：此时**连
+ *   `Box` 都不建**，整个气泡与加这一块之前逐像素相同——流式气泡与待发气泡走的正是这一档
+ *   （后者本端还没有任何时间戳）。
+ */
+@Composable
+private fun BubbleWithTime(
+    time: String?,
+    isUser: Boolean,
+    bubble: @Composable (Modifier) -> Unit,
+) {
+    if (time == null) {
+        bubble(Modifier)
+        return
+    }
+    val measurer = rememberTextMeasurer()
+    val style = MiuixTheme.textStyles.footnote2
+    val density = LocalDensity.current
+    val strip = remember(measurer, density, time, style) {
+        with(density) {
+            measurer.measure(text = time, style = style, maxLines = 1, softWrap = false).size.width.toDp()
+        } + MESSAGE_TIME_GAP
+    }
+    Box {
+        bubble(
+            Modifier
+                .then(if (isUser) Modifier.padding(start = strip) else Modifier.padding(end = strip))
+                // 气泡贴回它自己那一侧：`strip` 已经吃掉了可用的余量，这里的对齐在正常宽度下是
+                // 恒等的（气泡就是最宽的那个孩子），留着是为了「万一条比气泡还宽」时也仍在原位。
+                .align(if (isUser) Alignment.BottomEnd else Alignment.BottomStart),
+        )
+        Text(
+            text = time,
+            style = style,
+            color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+            // 宽度已经量过、条也留够了，正常情况下一行必放得下；这两个参数是防「量完到排完之间
+            // 密度变了」这类不该发生的事——真发生也只是这串字自己被截，不会去挤气泡。
+            maxLines = 1,
+            softWrap = false,
+            modifier = Modifier.align(if (isUser) Alignment.BottomStart else Alignment.BottomEnd),
+        )
+    }
+}
+
+/**
+ * 一条消息在气泡层渲染成一个 / 多个气泡。
+ *
+ * [sideTime] 只由**携带时间的那个气泡**收到（[MessageTimeCarrier.TextBubble] 指的那一个），
+ * 其余气泡与旁白行都不带——时间挂在这条消息上一次，不跟着每个气泡重复。`body` 为空的气泡
+ * （比如纯附件消息解析出来的那个占位气泡）一个像素都不画，**连 [BubbleWithTime] 都不进**：
+ * 这也是纯附件消息会整条没有时间的原因（判据见 [messageTimeCarrier]）。
+ */
 @Composable
 private fun Bubble(
     bubble: ParsedBubble,
@@ -549,10 +992,24 @@ private fun Bubble(
     showCursor: Boolean = false,
     onLongPress: (() -> Unit)? = null,
     gray: Boolean = false,
+    sideTime: String? = null,
 ) {
     AnnotationLine(bubble.head)
-    val body = if (showCursor && isLast && bubble.body.isNotEmpty()) bubble.body + CURSOR else bubble.body
-    if (body.isNotEmpty()) BubbleBody(body, isUser, onLongPress, gray)
+    val withCursor = showCursor && isLast && bubble.body.isNotEmpty()
+    val body = if (withCursor) bubble.body + CURSOR else bubble.body
+    if (body.isNotEmpty()) {
+        BubbleWithTime(time = sideTime, isUser = isUser) { side ->
+            BubbleBody(
+                text = body,
+                runs = bubble.runs,
+                isUser = isUser,
+                onLongPress = onLongPress,
+                gray = gray,
+                trailingCursor = withCursor,
+                modifier = side,
+            )
+        }
+    }
     AnnotationLine(bubble.tail)
 }
 
@@ -582,7 +1039,14 @@ private fun LegBadge(text: String, onClick: (() -> Unit)?) {
     }
 }
 
-/** 旁白/动作：灰斜体小字，依附在气泡上/下。 */
+/**
+ * 旁白/动作：灰斜体小字，依附在气泡上/下。
+ *
+ * 这一行**不做行内解析**（正文那四类标签在这里照原样显示）。理由是它读的是 `parts` 里的原文，
+ * 而分享预览那行读的是同一批原文（`ShareConfirmPanel.ShareConfirmAnnotation`）——那边是红线、
+ * 本次一个字都不能动。只在这边渲染，就等于让「预览里看到的 == 发出去之后看到的」在旁白上又裂一次，
+ * 而 W65 刚把这道缝补上。要连带做，得两处一起改并单独拍板（实测 `<action>` 里带 `<b>` 的 0 命中）。
+ */
 @Composable
 private fun AnnotationLine(parts: List<ContentPart>) {
     if (!LocalAppPrefs.current.showNarration) return
@@ -610,11 +1074,14 @@ private fun AnnotationLine(parts: List<ContentPart>) {
  * ## 长按仍然开动作菜单
  * 这条消息在服务端是真实存在的一行，用户能做的事里最相关的一件就是**删掉它**（内容永远到不了了）。
  * 气泡没有正文可以让长按去选字，所以长按在这里没有歧义，直接接 [MessageBubble] 的那一个入口。
+ *
+ * [modifier] 由调用方（[BubbleWithTime]）喂进来，装着「外侧那枚时间占掉的那一条」的 `padding`：
+ * 和 [BubbleBody] 一样，它是**气泡外边**的留白，不参与这张灰底方块的绘制与点击区。
  */
 @Composable
-private fun ContentlessNote(onLongPress: (() -> Unit)? = null) {
+private fun ContentlessNote(onLongPress: (() -> Unit)? = null, modifier: Modifier = Modifier) {
     Box(
-        modifier = Modifier
+        modifier = modifier
             .widthIn(max = 300.dp)
             .clip(BubbleShape)
             .background(MiuixTheme.colorScheme.surfaceContainer)
@@ -648,16 +1115,35 @@ private fun ContentlessNote(onLongPress: (() -> Unit)? = null) {
  * 这一态的语义是「这条已经在被处理，但还没有答案」，它既不是用户说的话（不该是主人的青色），
  * 也不是她的回答（不该是助手的正常底色）。正文一个字都不改，只是**褪色**，让人一眼看出
  * 「没丢，只是在等」。
+ *
+ * [runs] 非空时**只画 [runs]**（拼起来就是 `text` 去掉末尾光标那一截，见 [inlineBody]）：
+ * 同一段正文不在这里再拼一遍，免得拼出两个版本的字。[runs] 为空 = 这段正文没有可渲染的行内标签，
+ * 走原来的 `Text(text)` 那条路（**绝大多数消息都是这一档，一个像素都不变**）。
+ *
+ * [trailingCursor] 说的是「`text` 末尾那枚光标」。光标必须**在片段之外**补上去：它不是正文，
+ * 不该继承她最后那一段的粗体/等宽底色。
+ *
+ * [modifier] 由调用方（[BubbleWithTime]）喂进来，装着「外侧那枚时间占掉的那一条」的 `padding`。
+ * 它排在这条链的**最前面**，所以那一层留白在 `clip` / `background` / `combinedClickable` 之外：
+ * 气泡自己的样子、选字范围、长按的点击区都还是原来的那一块。
  */
 @Composable
 private fun BubbleBody(
     text: String,
+    runs: List<InlineRun>,
     isUser: Boolean,
     onLongPress: (() -> Unit)? = null,
     gray: Boolean = false,
+    trailingCursor: Boolean = false,
+    modifier: Modifier = Modifier,
 ) {
+    val contentColor = when {
+        gray -> MiuixTheme.colorScheme.onSurfaceVariantSummary
+        isUser -> MiuixTheme.colorScheme.onPrimary
+        else -> MiuixTheme.colorScheme.onSurfaceContainer
+    }
     Box(
-        modifier = Modifier
+        modifier = modifier
             .widthIn(max = 300.dp)
             // clip + background 与原来那句 `background(color, shape)` 画出来完全一样，
             // 多出来的这一层是为了让长按的涟漪被圆角裁住（否则它会溢出到方角外）。
@@ -685,19 +1171,74 @@ private fun BubbleBody(
             .padding(horizontal = 14.dp, vertical = 10.dp),
     ) {
         SelectionContainer {
-            Text(
-                text = text,
-                style = MiuixTheme.textStyles.main,
-                color = when {
-                    gray -> MiuixTheme.colorScheme.onSurfaceVariantSummary
-                    isUser -> MiuixTheme.colorScheme.onPrimary
-                    else -> MiuixTheme.colorScheme.onSurfaceContainer
-                },
-            )
+            if (runs.isEmpty()) {
+                Text(
+                    text = text,
+                    style = MiuixTheme.textStyles.main,
+                    color = contentColor,
+                )
+            } else {
+                Text(
+                    text = inlineBody(
+                        runs = runs,
+                        codeBackground = if (isUser) {
+                            MiuixTheme.colorScheme.onPrimary.copy(alpha = INLINE_CODE_ON_USER_BACKGROUND)
+                        } else {
+                            MiuixTheme.colorScheme.surfaceContainerHigh
+                        },
+                        trailingCursor = trailingCursor,
+                    ),
+                    style = MiuixTheme.textStyles.main,
+                    color = contentColor,
+                )
+            }
         }
     }
 }
 
+/**
+ * `<code>` 那点底色在**主人那侧**（青色气泡）的透明度：`onPrimary` 压一层浅底。
+ * 昔涟那侧直接用 `surfaceContainerHigh`——它本来就是比气泡底（`surfaceContainer`）高一档的填充色，
+ * 同一套配色里现成的一档，不另造颜色。
+ */
+private const val INLINE_CODE_ON_USER_BACKGROUND = 0.18f
+
+/**
+ * 行内片段 → 一段 `AnnotatedString`：一个 `Text` 就同时承载粗体 / 斜体 / 下划线 / 等宽底色。
+ *
+ * **为什么不拼一串 `Text` 节点**：一条气泡本来就是**一整段可选中的文本**（[SelectionContainer]
+ * 的行为一个字都不用改），折行位置也由同一个排版器一次定完——拆成多个节点会让可选性与折行
+ * 各自为政。`<br>` 已经不在这一层（它是气泡分隔符，切在解析层），所以这里不再有「插一个换行」
+ * 这种活。
+ *
+ * 样式只给**有**的那几项（`null` = 继承气泡自己的字重/字体/装饰），所以非 `<code>` 的片段与原来逐像素相同。
+ *
+ * `u` 落到 `TextDecoration.Underline`（六项白名单里的那一项，见 `InlineMarkup.kt` 的文件头）；
+ * `s` 不在白名单里，所以这里**没有**删除线分支——写 `<s>甲</s>` 时那四个字符是按字面显示的正文，
+ * 走的是 `runs` 为空的那条路（`BubbleBody` 里的裸 `Text`）。
+ */
+private fun inlineBody(
+    runs: List<InlineRun>,
+    codeBackground: Color,
+    trailingCursor: Boolean,
+): AnnotatedString = buildAnnotatedString {
+    for (run in runs) {
+        val code = InlineStyle.Code in run.styles
+        withStyle(
+            SpanStyle(
+                fontWeight = if (InlineStyle.Bold in run.styles) FontWeight.Bold else null,
+                fontStyle = if (InlineStyle.Italic in run.styles) FontStyle.Italic else null,
+                textDecoration = if (InlineStyle.Underline in run.styles) TextDecoration.Underline else null,
+                fontFamily = if (code) FontFamily.Monospace else null,
+                background = if (code) codeBackground else Color.Unspecified,
+            ),
+        ) {
+            append(run.text)
+        }
+    }
+    if (trailingCursor) append(CURSOR)
+}
+
 /**
  * 气泡里的图片（缩略）。
  *
@@ -707,13 +1248,17 @@ private fun BubbleBody(
  * 涟漪不会溢出圆角）；读屏也需要知道点它会发生什么，所以带上 `contentDescription`。
  *
  * 高度不设限：图片按比例撑开，气泡那一列本来就是纵向排列。
+ *
+ * [modifier] 由调用方（[BubbleWithTime]）喂进来，装着「外侧那枚时间占掉的那一条」的 `padding`。
+ * 它排在这条链的**最前面**：那一层留白在 `widthIn` / `clip` / `clickable` 之外，所以图片自己的
+ * 尺寸上限、圆角与点击区都与加它之前逐像素 / 逐行为相同（与 [BubbleBody] 同一条纪律）。
  */
 @Composable
-private fun ChatImage(model: String, onClick: (String) -> Unit) {
+private fun ChatImage(model: String, onClick: (String) -> Unit, modifier: Modifier = Modifier) {
     AsyncImage(
         model = model,
         contentDescription = "查看图片",
-        modifier = Modifier
+        modifier = modifier
             .widthIn(max = 240.dp)
             .clip(RoundedCornerShape(14.dp))
             .clickable { onClick(model) },

app/src/main/kotlin/top/yeij/cyrene/ui/chat/PreviewImageFacts.kt

@@ -0,0 +1,74 @@
+package top.yeij.cyrene.ui.chat
+
+import android.graphics.BitmapFactory
+import android.media.ExifInterface
+import java.io.ByteArrayInputStream
+
+/**
+ * 从本端持有的那份字节里**现读**出来的图片事实：像素与拍摄日期。读不到的就是 `null`。
+ *
+ * ## 为什么这一层不在 `domain/` 里
+ * [PreviewMetadata][top.yeij.cyrene.domain.chat.PreviewMetadata] 是纯函数（JVM 单测里逐档穷举），
+ * 而这里调的两个都是 Android 平台类（`android.graphics.BitmapFactory` / `android.media.ExifInterface`），
+ * 在 JVM 单测里是**抛异常的 stub**。所以切口落在这里：读平台 → 得到两个可能为 `null` 的数 →
+ * 交给纯函数组装成那一行。判断「显示什么」的逻辑一个字都不在平台类里，测试因此能覆盖全部档位。
+ *
+ * ## 分辨率为什么用 `inJustDecodeBounds`
+ * 为了一行小字把 20 MiB 的大图解成位图是不可接受的（内存 + 主线程耗时）。`inJustDecodeBounds`
+ * 只读文件头，`outWidth` / `outHeight` 就是答案，`decodeByteArray` 返回 `null` 是有意的。
+ *
+ * ## EXIF 用的是**系统 API**，不引新依赖
+ * `android.media.ExifInterface`（`InputStream` 构造自 API 24 起可用，本工程 `minSdk = 33`）。
+ * 它认不出的容器（PNG / GIF / WebP / BMP 这些没有标准 EXIF 的格式）只会让 `getAttribute` 回
+ * `null`——**那正是「拿不到就整项不缺席」要的答案**，不是错误。⚠️ 它**只读 JPEG 与 RAW**，
+ * 所以「所有图片都有拍摄日期」是错的预期，能报出来的基本只有相机/相册里的 JPEG。
+ *
+ * ## 日期为什么不在这里格式化
+ * EXIF 的 `DateTimeOriginal` 是**没有时区**的墙钟字符串（`yyyy:MM:dd HH:mm:ss`），本层**原样**
+ * 交给 [PreviewMetadata.formatExifDateTime][top.yeij.cyrene.domain.chat.PreviewMetadata.formatExifDateTime]
+ * 去严格校验与格式化——那一步是纯函数，能逐档单测，也能把「不做时区换算」这条取舍写在明面上。
+ */
+data class PreviewImageFacts(
+    val width: Int? = null,
+    val height: Int? = null,
+    /** EXIF `DateTimeOriginal` 的原始字符串；缺席即 `null`。 */
+    val capturedAt: String? = null,
+)
+
+/**
+ * 读出这两个事实。**任何一步失败都只是少一项**（`runCatching`）：这一行是锦上添花，
+ * 它自己绝不许成为「图片打不开」的原因。
+ *
+ * 只从**已经在内存里**的那份字节读（[top.yeij.cyrene.data.repository.CachedDocument.bytes]，
+ * 预览与两条出口用的都是它），不再碰盘、不再联网。
+ */
+fun readPreviewImageFacts(bytes: ByteArray): PreviewImageFacts {
+    val bounds = readBounds(bytes)
+    return PreviewImageFacts(
+        width = bounds?.first,
+        height = bounds?.second,
+        capturedAt = readCapturedAt(bytes),
+    )
+}
+
+/**
+ * 文件头里的像素：任一侧 ≤ 0（解不出来 / 不是图片）就是 `null`。
+ *
+ * 与 `ZoomableImage` 里 Coil 报上来的那个尺寸是两回事：那个是**解码后**的位图尺寸，要等图片
+ * 真的解出来才有；这里是**打开弹层时立刻**就有（只看文件头）。两者一致是常态，不一致时以这里
+ * 为准——它描述的是文件本身。
+ */
+private fun readBounds(bytes: ByteArray): Pair<Int, Int>? = runCatching {
+    val options = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)
+    val width = options.outWidth
+    val height = options.outHeight
+    if (width > 0 && height > 0) width to height else null
+}.getOrNull()
+
+/** EXIF 的 `DateTimeOriginal`；没有这个标签 / 不是 EXIF / 读不动，一律 `null`。 */
+private fun readCapturedAt(bytes: ByteArray): String? = runCatching {
+    ByteArrayInputStream(bytes).use { stream ->
+        ExifInterface(stream).getAttribute(ExifInterface.TAG_DATETIME_ORIGINAL)
+    }
+}.getOrNull()?.trim()?.takeIf { it.isNotEmpty() }

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ReconnectReset.kt

@@ -0,0 +1,134 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.data.ws.WsState
+import top.yeij.cyrene.domain.chat.allClosed
+
+/**
+ * **连接重建**（不是第一次接上）时把本端的「进行中」一次性收口。
+ *
+ * ## 它修的是什么（主人 2026-10-06 报的现场）
+ * 后端卡在半路（回合在跑、或工具在跑）时被**重启**：那一轮在服务端**已经不存在了**，
+ * 所以本端**永远不会**再收到它的任何收口帧（`turn.end` / `stream_end` / 助手落库行）。
+ * 而本端「进行中」的每一条闸都只认**帧**：
+ *
+ * - 灰态（④「已读，正在回答…」）的唯一闸是 [top.yeij.cyrene.domain.chat.TurnBinding.closed]，
+ *   它只由 `turn.end` / 同 `turnId` 的助手落库行驱动（`ChatViewModel.onEvent`）；
+ * - 「思考中…」/「执行 X…」的唯一闸是流式路自己的 `thinkingActive` / `active` / 工具卡的 `phase`
+ *   （收口只发生在 `stream_end` / 助手落库行）；
+ * - 底栏那句「正在思考…」的唯一闸是 `session_busy` / `session_idle` 报的 [ChatUiState.busyMode]。
+ *
+ * 三条路都断在「没有帧」上 ⇒ **没有任何一条会自己收口**，界面于是永久停在那一格：气泡一直灰着、
+ * 卡片一直转、底栏一直说她在思考。三条里今天唯一被兜住的是 `session_idle` / `session_interrupted`
+ * 那两帧（`allClosed()` 的两个既有调用点）——而**后端重启时它们永远不会到**（说这话的进程已经没了）。
+ *
+ * 还有一处**不显眼但很要命**的连带：那条永远 `active` 的流式路永远是消息列表的**末项**
+ * （[ChatUiState.items] 的最后一项，`reverseLayout` 下就是**屏幕最下方**），而 `ChatScreen` 的
+ * 「跟随底部」判的正是 `items.lastOrNull()?.key`（`ChatScreen.kt:508`）——末项不再变化 ⇒
+ * **此后新到的消息不再把列表滚到底**，于是「最新一条」永远停在那一张转着的卡上。用户看到的就是
+ * 「拉不到新消息」（消息其实进得来，是屏幕不再跟着它走）。
+ *
+ * 收口之后这张卡变成**惰性**的（不再转、不再声称在思考）：它仍留在列表里（正文一个字都不删，
+ * 见下面「不许碰的东西」），直到它自己那一路的落库行到达、或**下一轮** `message.start` 把它当作
+ * 「已结束的路」丢掉（`TurnStreams.beginLeg`）——那时末项恢复推进，跟随底部也就回来了。
+ * 这条残留如实登记：收口**不**替这张卡删内容，所以它自己要等一个后续事件才消失。
+ *
+ * ## 触发时机：只做「连接重建」（(a)），**不做静默超时**（(b)）
+ * 判据落在 [isReconnect] 上，也就是 `WsState` **非 Connected → Connected** 的那一跳。三条理由：
+ * 1. **确定性**：后端重启必然重建连接，而重建连接**必然**让 `WsState` 走一遍 `Reconnecting →
+ *    Connected`（`ChatSocket.runConnectionLoop`）。这条判据是**事件驱动**的，不需要时间常量；
+ * 2. **可验证**：假后端 `POST /__control/ws-close`（或直接重启进程）就能复现，设备上判据是
+ *    「一条已在飞的回合 + 一次真踢」，不依赖「等多久」这种主观量；
+ * 3. **与既有纪律一致**：本项目自 W38 起就定死「状态驱动，不按时间轮」（见
+ *    `ChatViewModel.retryFirstPage` 的 KDoc），(b) 会在同一张表上引入第二个口径。
+ *
+ * (b)（某一路 N 秒没有任何帧就认为它结束了）**刻意没做**，代价与风险如实记在这里，留主人拍板：
+ * - 它要多一个**时间常量**，而那个数只能拍：太小会把「正常但慢」的回合（长思维链、长工具执行、
+ *   服务端排队）误杀成已结束，太大则回到「卡住很久」的老样子；
+ * - 它能在**连接没断**时兜底（后端进程活着但编排器死锁、或帧被中间设备悄悄丢掉），而 (a) 兜不住
+ *   这一档；但这一档今天**没有现场证据**（主人报的是「重启后端」，那是 (a)），按「先修有证据的」
+ *   不动它；
+ * - 两者叠加不会互相破坏（都是幂等收口），真要做时**先做 (a)、再把它当第二级**即可。
+ *
+ * ## 「第一次连接」不算重建
+ * 冷启动的 `Idle → Connecting → Connected` 必须**一个字节都不收口**，两条路都会踩到：
+ * - **刚进会话的 VM**：它订阅时连接可能**已经是** Connected，于是它看到的第一次 Connected 与
+ *   `history` / `turn_begin` / `steer_ack` 那一批首帧**几乎同时**到达（帧走 `socket.events`、
+ *   状态走 `socket.state`，两条流各自投递）。这时候本端手里可能**已经有**一条正当地灰着的气泡
+ *   （另一台设备起的那一轮），把它当成重建收口就是**在用户刚打开会话的瞬间**凭空把那一轮说成已答；
+ * - **冷启动**：`Idle → Connecting → Connected` 是每一个会话的第一跳，与「后端重启过」毫无关系。
+ *
+ * 所以判据必须是「**曾经**到过 Connected 之后又回到 Connected」，而不是「这一次是不是 Connected」。
+ */
+internal fun isReconnect(previous: WsState, current: WsState, everConnected: Boolean): Boolean {
+    // 不是「接上了」，谈不上重建（Connecting / Reconnecting / Offline / Idle 都不收口）。
+    if (current != WsState.Connected) return false
+    // 本 VM 见过 Connected ⇒ 这一次接上必然是**接回来**。这一条是主判据，而且**不受状态流合流影响**
+    // （理由与「为什么是一位记忆而不是看上一跳」见 `ChatViewModel.everConnected` 的 KDoc）。
+    if (everConnected) return true
+    // 没记过账时的第二证据：上一跳是**重连退避**（`ChatSocket.runConnectionLoop` 只在断开之后写
+    // `Reconnecting`；首次握手走的是 `Connecting`）。这一档只在一处是真的：**本 VM 是在离线期间
+    // 建起来的**（进次级会话时连接就是断的）⇒ 它自己的第一次 Connected 确实发生在一次重建之后。
+    // 它手里那时**什么都没有**（没有 turn / 没有流式路 / 没有 busyMode），所以 [settledAfterReconnect]
+    // 对它是恒等变换——判在这里不会误伤任何东西，反过来说也不必为它加第二条口径。
+    return previous == WsState.Reconnecting
+}
+
+/**
+ * 连接重建时把本端「进行中」的五个面一次性收口（纯函数，VM 与测试共用）。
+ *
+ * 收口的是**服务端那一轮留下来的本端投影**，一件一件说清它为什么该收：
+ * - [ChatUiState.busyMode]：「正在思考…」是**服务端报的**事实（`session_busy`）。旧连接没了，
+ *   这个事实就**不可知**了；继续显示它等于替服务端保证一件已经问不到的事；
+ * - [ChatUiState.activeTurns]：同上（「并行 N 路」）；归 `0` = 「不知道」，正是
+ *   [ChatUiState.activeTurns] 文档里那个「不知道」的取值；
+ * - [ChatUiState.queueDepth]：「已排队 N 条」也是服务端队列的事实，与 `session_idle` / 被打断
+ *   那两处的处置**逐字一致**（那两处也是 `busyMode = null, queueDepth = 0` + 全部收口）；
+ * - [ChatUiState.turns] ⇒ `allClosed()`：未收口的绑定全部标 `closed`（气泡 ④ → ⑤）；
+ * - [ChatUiState.streams] ⇒ `allFinished()`：每一路停止生长（思维链不再「思考中」、工具卡不再
+ *   「执行 X…」），**正文一个字都不删**。
+ *
+ * ## 收口之后**不许**碰的东西（可降级；也是本函数的红线）
+ * [ChatUiState.messages] / [ChatUiState.pending] / [ChatUiState.queuedKeys] /
+ * [ChatUiState.queuedForConnection] / 草稿与附件 / [ChatUiState.error] / [ChatUiState.sessionGone]
+ * **一律原样**：收口只改「进行中的外观」，**不删消息、不整表重拉、不给用户多加一条横幅**。
+ * 绑定表本身也**不删**（只标 `closed`）——并行路角标（`legBadgeForMessage`）靠它，删了等于事后
+ * 篡改历史。于是写死一条纪律：**收口是可降级的**，最坏的结果只是「少灰一会儿」。
+ *
+ * ## 「闪动」：收口会不会被随后到达的帧翻回进行中（如实回答）
+ * - 灰态**不会**：[top.yeij.cyrene.domain.chat.TurnBinding.closed] 是**单调**的既成事实
+ *   （`withTurnBegin` 合并时也**保持原值**，见那里第 2 条），所以「已答」之后不会退回「回答中」。
+ * - 流式卡片**会**：那一帧正文/思维链真的又来了，`withLeg` 就会把它重新变成 `active` /
+ *   `thinkingActive` —— 这是**如实**的（它确实又在生成了），而且是**自愈**的：正文不会因为
+ *   本端收过一次口而丢字（收口不删内容，后续 delta 照旧追加到同一路）。
+ * - `busyMode` **会**：服务端下一次 `session_busy` 一到就恢复。
+ *
+ * 也就是说：**代价落在「服务端那一轮其实还活着」（只是连接抖动过）这一档**——本端会提前一点点
+ * 把气泡显示成已答。这个代价是刻意选的，因为它比另一个方向小得多：今天的行为（永远灰着、
+ * 卡片永远转、底栏永远说她在思考、跟随底部永远失效）是**永久坏掉**，且用户唯一的出路是退出重进。
+ *
+ * ## 一条如实登记的行为变化
+ * 清掉 [ChatUiState.busyMode] 会**连带**改变下一次发送的声明：`ChatViewModel.emitAndDeliver` 用
+ * `busyMode != null` 算 `interruptScopeForSend` / `parallelForSend`（`ChatViewModel.kt:1793`）。
+ * 于是「她忙时发消息」偏好选「打断」的那一档，在重建后的**第一次**发送不再先发 `interrupt`。
+ * 如实说：连接重建之后本端**确实不知道**那一轮还在不在，而不打断的后果（这一条被服务端排在后面
+ * 或并行处理）比对着一个已经不存在的回合发 `interrupt` 小得多。服务端下一次报 `session_busy`
+ * 就恢复原样。
+ */
+internal fun ChatUiState.settledAfterReconnect(): ChatUiState {
+    val closedTurns = turns.allClosed()
+    val finishedStreams = streams.allFinished()
+    // 没有任何「进行中」可收时返回**同一个实例**：每次「接回来」都会调它一次，而无变化时制造新
+    // 实例会让 StateFlow 白白发一轮（也让测试里的 `assertSame` 失去意义）。
+    if (closedTurns === turns && finishedStreams === streams &&
+        busyMode == null && activeTurns == 0 && queueDepth == 0
+    ) {
+        return this
+    }
+    return copy(
+        busyMode = null,
+        activeTurns = 0,
+        queueDepth = 0,
+        turns = closedTurns,
+        streams = finishedStreams,
+    )
+}

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ShareConfirmDraft.kt

@@ -0,0 +1,51 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.domain.share.SharedContent
+
+/**
+ * 「一份**已经取走**、正等着用户确认的分享」，外加用户此刻补的那句描述。
+ *
+ * ## 为什么它必须活在 VM 里，而不是一格 `remember`
+ * 这份内容**已经**从待发队列里出队了（[top.yeij.cyrene.app.ShareIntake.take] 是原子出队、
+ * **没有归还路径**），而它此前只挂在一格 `remember(sessionId)` 上——那格状态属于**那一次组合**。
+ * Activity 因转屏 / 深浅色切换重建时组合整份丢掉：那份分享既不在队列里（已经出队）、也不在界面上
+ * （那格状态没了），**静默消失**——用户什么都没看到，也没有任何提示。所以它待在
+ * [ChatUiState.shareConfirm] 里：VM 由 `AppContainer` 那一层持有（`core.session.ChatSessionSlots`
+ * 的 `ViewModelStore`），比组合与 Activity 都活得久。
+ *
+ * 正文（[share]）与描述（[caption]）**绑在同一个值里**是刻意的：描述说的是「你要补的那一句话」，
+ * 它只对这一次确认有意义——分成两格迟早会出现「描述换了一份、正文还是上一份」。
+ *
+ * [caption] 初值**恒为空**：面板上半是这次分享进来的东西，下半才是用户要附加的话，预填一次就会在
+ * 面板里把同一句话排两遍（W53X 的第一版正是这么错的，见 `ShareConfirmPanel` 的 KDoc）。
+ */
+data class ShareConfirmDraft(
+    val share: SharedContent,
+    val caption: String = "",
+)
+
+/**
+ * 「手上这一份 + 去待发队列认领一次」⇒ 面板这一刻该拿着哪一份（**纯函数**，可单测）。
+ *
+ * ## 它回答的是**不可逆那一步该不该走**
+ * [take] 就是 `ShareIntake.take()`（**不可逆**），所以「什么时候允许调它」是这里唯一的正事：
+ * **手上已经有东西时一个字节都不动**——连队列里新来的那条也不碰，它原地等着，面板上此刻摆的
+ * 仍是用户正在看的那一份，不会被后来的一条顶掉。这就是「同一份分享只被取走一次」的落点：
+ * Activity 重建之后新的一帧会再问一次同样的问题，而那时 [holding] 里已经装着那份内容
+ * （它活在 VM 的状态里，活过了重建）⇒ 不会再 [take] 第二次。
+ *
+ * ## 为什么不是「取完之后再拿结果比一比」
+ * 不能靠「第二次 [take] 拿到 null 就当没发生过」兜底：第二次跑起来拿到的要么是 null（白跑一趟），
+ * 要么是**队列里的下一条**——后者会把用户正看着的那份顶掉，那是一次静默丢失。所以闸门必须在
+ * [take] **之前**，而不是在它之后回滚。
+ *
+ * @param holding 这一刻面板手上那一份（[ChatUiState.shareConfirm]）；null = 手上没东西。
+ * @param take 去待发队列认领一条（`ShareIntake.take()`）：**只在 [holding] 为 null 时被调用**，
+ *   且最多一次。返回 null（队列为空）时本函数也回 null——不造一个「什么都没有的面板」。
+ * @return 面板该拿着的那一份：手上原有的**原样**返回（连实例都不换——`ShareConfirmPanel` 用它做
+ *   `remember` 的键，换一份等值的新对象会让预览白重建一次）；手上没有时就是刚认领的那一条。
+ */
+internal fun shareConfirmClaim(
+    holding: ShareConfirmDraft?,
+    take: () -> SharedContent?,
+): ShareConfirmDraft? = holding ?: take()?.let { ShareConfirmDraft(share = it) }

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ShareConfirmPanel.kt

@@ -0,0 +1,757 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.SideEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.layout.onSizeChanged
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.text.TextLayoutResult
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import coil3.compose.AsyncImage
+import top.yeij.cyrene.domain.chat.DocumentChips
+import top.yeij.cyrene.domain.chat.DraftDocument
+import top.yeij.cyrene.domain.parse.ContentPart
+import top.yeij.cyrene.domain.parse.ParsedBubble
+import top.yeij.cyrene.domain.parse.parse
+import top.yeij.cyrene.domain.share.SharedContent
+import top.yeij.cyrene.domain.share.SharedDocument
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.basic.TextField
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+import top.yukonga.miuix.kmp.window.WindowDialog
+
+/**
+ * 「这次分享进来的内容」的确认面板（主人 2026-10-06 拍板：**像其他 IM 一样，先确认再发**）。
+ *
+ * ## 它补上的那一步
+ * 在这之前，分享进来的内容一到连接就绪就被 `ChatViewModel.sendShared` 直接发了出去
+ * （见 `ChatScreen` 里那段落地的 effect），用户**没有任何确认机会**：一张图、一份文件、
+ * 一段从浏览器带来的链接，点完分享就已经在对话里了。面板把这一步补上——**只有点「发送」才真的发**，
+ * 「取消」则本次分享作废（不发送、也不塞回待发队列：那会让「用户刚刚作废的那一份」与「又来了
+ * 新分享」混成同一件事，见 [top.yeij.cyrene.domain.share.PendingShareHolder]）。
+ *
+ * ## 取走只发生一次，面板只负责显示
+ * 这份 [share] **已经**从待发队列里被 `ShareIntake.take()` 取走了（原子出队、没有归还路径），
+ * 它现在活在 `ChatScreen` 的 Compose 状态里。所以本文件里的东西全是**无状态**的：面板不取内容、
+ * 不记账、也不判断「该不该弹」——那些判据与记账都在调用方，这里只把拿到的那一份画出来。
+ *
+ * ## 为什么用 Miuix 的 `WindowDialog`
+ * 项目里其余四个弹层（编辑 / 删除 / 附件预览 / 图片预览）用的是 Compose 的 `androidx.compose.ui.window.Dialog`
+ * + Miuix 内容，因为它当年在 Miuix 里找不到可用的弹层控件。Miuix 0.9.3 其实自带两族（**没有**旧版本的
+ * `extra.*` 包，别照那个去猜 import）：`top.yukonga.miuix.kmp.window.*`（`WindowDialog` /
+ * `WindowBottomSheet`，真正的弹窗）与 `top.yukonga.miuix.kmp.overlay.*`（`OverlayDialog` /
+ * `OverlayBottomSheet`，在当前组合里当一层浮层）。
+ *
+ * 本面板用 **window 族**，两个理由：
+ *
+ * 1. **overlay 族在调用点上是走不通的**（不是偏好，是硬约束）：`OverlayDialog` 靠
+ *    `MiuixPopupUtils.DialogLayout` 把自己登记进 `LocalDialogStates` / `LocalRootDialogStates`，
+ *    而这两个 `staticCompositionLocalOf` **只有 Miuix 的 `Scaffold` 会 provide**（`basic/Scaffold.kt`）。
+ *    本面板的调用点在 `ChatScreen` 里那个 `Scaffold` 的**外面**（与附件预览 / 编辑 / 删除那三个弹层
+ *    同一处），拿不到宿主——而它的默认值是一个没人读的空列表，于是**不报错、也不显示**：
+ *    分享进来会变成「什么都没发生」，正是本项目最忌讳的那种静默失败。（同批的 W53S 用的是
+ *    `OverlayDialog`，因为那个确认框就长在设置页的 `Scaffold` 里——两处调用点的处境不同。）
+ * 2. 它与既有那四个弹层是**同一个形态**：独立窗口、自带遮罩、点面板外或按返回键即取消
+ *    （`onDismissRequest`，这里接的正是「取消」）。这里要的只是一次确认，不需要底部面板那套
+ *    可拖拽的手势。
+ *
+ * ## 预览与输入框的分工（W53X3 更正：输入框是「用户附加的描述」，**不是**正文的复刻）
+ * 上半是**预览**：这次分享进来的东西本身——图片缩略图 / 文件芯片 / **分享自带的正文**。那才是这次
+ * 要发出去的内容，留着它用户才知道「她将收到的是什么」。
+ * 下半是**输入框**：**你**要附加的描述，初值**恒为空**（`caption` 由调用方给空串），空框时显示
+ * 占位符 [SHARE_CONFIRM_CAPTION_PLACEHOLDER]（与输入栏那句「和昔涟说点什么…」同一个写法）。
+ * 发送时真正发出去的正文由 [shareConfirmBody] 拼：分享正文（若有）+ 用户描述（若有），两段都在时
+ * **空行分隔**，只有一段就只用那一段。
+ *
+ * ⚠️ 这里曾经把两件事搞成一件（W53X 的第一版）：输入框被预填成分享进来的正文，在真机上就渲染成
+ * 「同一句话排两遍」——预览的「分享的文字」块一遍、输入框里又一遍，而输入框里那句还看着像一段
+ * 只读展示。错在「这次要发什么」与「你想补一句什么」本来是两件事：前者归预览，后者才归这个输入框。
+ */
+@Composable
+fun ShareConfirmPanel(
+    share: SharedContent,
+    caption: String,
+    onCaptionChange: (String) -> Unit,
+    onSend: () -> Unit,
+    onCancel: () -> Unit,
+) {
+    val preview = remember(share) { shareConfirmPreview(share) }
+
+    // `show = true` 恒成立：这个面板只在有内容可确认时被调用方组合出来（`shareConfirm?.let { … }`），
+    // 关掉它靠的是调用方把那格状态清空（取消 / 发送后的清理都在那边）。
+    WindowDialog(
+        show = true,
+        title = SHARE_CONFIRM_TITLE,
+        onDismissRequest = onCancel,
+    ) {
+        Column(modifier = Modifier.fillMaxWidth()) {
+            if (!preview.isEmpty) {
+                ShareConfirmPreviews(preview)
+                Spacer(Modifier.height(12.dp))
+            }
+            TextField(
+                value = caption,
+                onValueChange = onCaptionChange,
+                modifier = Modifier.fillMaxWidth(),
+                label = SHARE_CONFIRM_CAPTION_PLACEHOLDER,
+                useLabelAsPlaceholder = true,
+                maxLines = 4,
+            )
+            Spacer(Modifier.height(20.dp))
+            Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.End) {
+                // 「取消」放在「发送」之前（与编辑 / 删除那两个弹层同一个排法）：右端永远是那枚
+                // **会真的改动东西**的键。
+                TextButton("取消", onClick = onCancel)
+                Spacer(Modifier.width(8.dp))
+                TextButton(
+                    text = "发送",
+                    onClick = onSend,
+                    // 什么都没有可发时这枚键不该可点：「发送」发出去的那段正文就是 [shareConfirmBody]
+                    // 拼出来的那一段，而 `sendShared` 在「正文空白 + 没有图片 + 没有文件」时会**原地
+                    // 返回**（一次发送都不会发生）。判据是纯函数 [shareConfirmCanSend]，与那条早退同源。
+                    enabled = shareConfirmCanSend(share, caption),
+                )
+            }
+        }
+    }
+}
+
+/**
+ * 这次分享**该展示成哪几样东西**（纯数据，UI 照着渲染）。
+ *
+ * 与 [SharedContent] 不是同一个东西：[SharedContent] 是「用户分享了哪些字段」（还带着丢件计数、
+ * 超限计数这些**告知**用的账），本类型只保留**看得见的那几样**。混用一个类型的话，渲染层迟早会去
+ * 读那些计数字段并顺手显示出来，而它们该说的话由 `shareNoticeFor` 统一成句（它是唯一一处出处）。
+ */
+data class ShareConfirmPreview(
+    /** 要显示的图片（本端 cache 里的 `file://` 地址，顺序即发送顺序）。 */
+    val images: List<String>,
+    /** 要显示的文件（显示名 + 体积由既有的 `DocumentChipRow` 负责换算）。 */
+    val documents: List<SharedDocument>,
+    /** 要显示的正文；空白已归一成空串。 */
+    val text: String,
+) {
+    /** 这份分享带不带正文（空串与「全空白」都算不带——只显示一行空气不是预览）。 */
+    val hasText: Boolean get() = text.isNotEmpty()
+
+    /** 三样都没有 = 这次分享**没有可预览的内容**（此时预览区整块不出现）。 */
+    val isEmpty: Boolean get() = images.isEmpty() && documents.isEmpty() && !hasText
+}
+
+/**
+ * 把一份分享折算成要显示的那几样（**纯函数**，可单测）。
+ *
+ * 两处过滤是**空的也算没有**：一条空地址画出来就是一个空白缩略图（用户会以为图坏了），
+ * 一段全空白的正文占着一行什么也不说。正文两侧的空白一并去掉，与
+ * [top.yeij.cyrene.domain.share.ShareRules.extract] 取正文那一处同一个口径。
+ *
+ * 顺序原样保留：多张图的顺序**就是发送顺序**（第一条消息带第一张，见 `imageSendPlan`），
+ * 预览里换一个顺序就是在替用户改他要发的东西。
+ */
+fun shareConfirmPreview(share: SharedContent): ShareConfirmPreview = ShareConfirmPreview(
+    images = share.images.filter(String::isNotBlank),
+    documents = share.documents.filter { it.uri.isNotBlank() },
+    text = share.text.trim(),
+)
+
+/**
+ * 点「发送」时**真正发出去的那段正文**（**纯函数**，可单测）：分享自带的正文 + 用户附加的描述。
+ *
+ * 三段穷举（这也是它可测的全部形状）：
+ * - 两段都有 ⇒ `分享正文` + [SHARE_CONFIRM_BODY_SEPARATOR] + `用户描述`（**空行**分隔：两段话挨在
+ *   一起时读者分不清哪句是谁说的；空行是「这是两段」的最小表达，也让正文里本来换行的人不受影响）；
+ * - 只有一段 ⇒ 就是那一段（**不补分隔符**：给一段话收个尾是凭空多出来的东西）；
+ * - 都空 ⇒ 空串（此时能发的只剩图片 / 文件，正文那一栏本来就该空着）。
+ *
+ * **内容一字不丢**是红线，这一条覆盖三件事：
+ * 1. 分享正文按 [shareConfirmPreview] 的口径两侧去空白 —— 与 `ShareRules.extract` 取正文、
+ *    以及 `sendShared` 开头 `share.text.trim()` 是**同一个**口径，所以「这里非空」≙「那边发得出去」；
+ * 2. 用户描述同样只去两侧空白，**中间一个字不动**（用户自己换的行是他打的，不是我们排版的地方）；
+ * 3. 一律**不加**来源标记 —— 不拼「[用户分享]」、不加引号、不套模板。来源标识走后端的独立
+ *    `RoleSystem` 来源消息 + 结构化 `SenderName`（`02/F4` / `design/11 §10`）；把标记拼进正文
+ *    = 让用户正文冒充系统指令，那是项目红线。
+ *
+ * 顺序是「分享正文在前、用户描述在后」：先有「她收到的那份东西」，再有「你补的那句话」——反过来的
+ * 话，用户想给一条链接加注释就得先读注释再读链接，而他要注释的正是那条链接。
+ */
+fun shareConfirmBody(share: SharedContent, caption: String): String {
+    val shared = shareConfirmPreview(share).text
+    val own = caption.trim()
+    return when {
+        shared.isEmpty() -> own
+        own.isEmpty() -> shared
+        else -> shared + SHARE_CONFIRM_BODY_SEPARATOR + own
+    }
+}
+
+/**
+ * 两段正文之间的分隔（见 [shareConfirmBody]）：**一个空行**（`\n\n`），不是空格、也不是一行 `——`。
+ *
+ * 只在**两段都在**时出现：`\n\n` 是任何聊天客户端都认的「两段」写法，而多出来的装饰性分隔行
+ * （`---`、`· · ·`）会被对面当成内容读进去。
+ */
+const val SHARE_CONFIRM_BODY_SEPARATOR = "\n\n"
+
+/**
+ * 面板里那枚「发送」该不该可点（**纯函数**，可单测）。
+ *
+ * 判据与 `ChatViewModel.sendShared` 开头那条早退**是同一条**：那边算的是
+ * `share.text.trim()`（也就是本端 [shareConfirmBody] 会拼进去的那一段）非空、或图片非空、或文件非空；
+ * 三样都空时它原地 `return`——一次发送都不会发生。此时把键画成可点的，用户按下去只会看到面板关掉、
+ * 什么也没发生，而他会以为自己少发了一条。所以这里回 `false`。
+ *
+ * 正文那一支直接问 [shareConfirmBody]（**同一个**出处，不是另写一遍 `text + caption` 的非空判断）：
+ * 两条各写各的判据迟早会分叉，那时按钮会在「真发得出去」的时候变灰，或者反过来。
+ *
+ * ⚠️ 三样里**任意一样非空就可发**：纯图片 / 纯文件的回合服务端**支持**（契约：`text` / `image` /
+ * `documents` 任一项非空即可），本端也照旧只发得出去的那几样，不因为「没写文字」而拦下它。
+ */
+fun shareConfirmCanSend(share: SharedContent, caption: String): Boolean {
+    val preview = shareConfirmPreview(share)
+    return shareConfirmBody(share, caption).isNotEmpty() ||
+        preview.images.isNotEmpty() ||
+        preview.documents.isNotEmpty()
+}
+
+/** 面板标题（与顶栏那句「与昔涟」同一称呼）。 */
+const val SHARE_CONFIRM_TITLE = "发送给昔涟"
+
+/**
+ * 输入框的占位符（`useLabelAsPlaceholder`：**只在框里没字时**显示）。
+ *
+ * 与输入栏那句「和昔涟说点什么…」同一个写法、同一个语气：它说的是**你**要补一句什么。
+ * 框里的字是用户自己打的、默认没有（初值恒为空）——所以这句占位符是常态而不是罕见档。
+ */
+const val SHARE_CONFIRM_CAPTION_PLACEHOLDER = "加一句描述…"
+
+/**
+ * 预览区（图片 / 文件 / 正文）。
+ *
+ * ## 高度上限与内部滚动
+ * Miuix 那两族弹层的 `content` **不是 `ColumnScope`**（是普通的 `@Composable () -> Unit`），
+ * 所以这里用不了 `Modifier.weight(1f)`（那是 `ColumnScope` 的扩展）——预览区没法「占剩下的高度」。
+ * 极端的一次分享（4 张图 + 5 份文件 + 一段长正文，键盘还弹着）会把这一个面板顶得很高，
+ * 而面板在手机上贴着屏幕底（`BottomCenter`）：超出的部分会把下面的输入框与两枚按钮挤出屏幕。
+ * 所以预览区自己带一个高度上限 + 内部滚动：内容少时它按内容高（上限不生效），内容多时它滚动、
+ * 输入框与按钮原地不动。上限按状态取（[sharePreviewMaxHeight]）：收起态
+ * [SHARE_PREVIEW_MAX_HEIGHT]、用户展开后 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]。
+ *
+ * ## 正文走**与气泡同一套解析**（W65），所以这一窗里排的是「气泡块」而不是一段原样的字
+ * 正文不是原样铺进去的：它先过 [top.yeij.cyrene.domain.parse.parse]——与 `MessageBubble` 里那条
+ * 完全同一个函数、同一个口径（[sharePreviewBlocks] 只是给结果加了一道兜底）。于是在这里看到的就是
+ * 发出去之后气泡里的样子：每个 `<p>…</p>`（无标签时按空行分段）是**一个独立的块**，
+ * `<action>` / `<narration>`（以及星号那几种写法）不当正文、而是**灰斜体小字**的旁白块，标签本身
+ * 一个字符都不显示。
+ *
+ * 这一层修掉的是 W61 审查发现的一处「所见非所发」：预览此前把正文 `trim` 之后原样显示、**不过解析
+ * 器**，而发送后的气泡过解析器——分享一段 `"<p><p>正文</p>"` 进来，**预览里是一串标签、气泡里只剩
+ * 「正文」**。用户按发送之前看到的不是他将要发出的东西。
+ *
+ * ## 正文给三行，但三行之外是「滚」不是「省略号」
+ * 预览只是「分享进来的是什么」的一眼，而用户要的是按一下发送：把一段几万字的正文整个铺开，这个面板
+ * 就成了一个阅读器。所以正文那一窗**恒为三行高**（[SHARE_PREVIEW_TEXT_LINES]），面板不随正文长短
+ * 变化。
+ *
+ * 但三行之外**不再收成省略号**（W54D 主人拍板改掉了 W53X 的老行为）：W53X3 之后**面板里再没有第二
+ * 个地方放着这段正文**——输入框是「用户附加的描述」（初值恒为空），不再是正文的可编辑副本。于是截断
+ * 成省略号就等于「按发送之前读不到要发的那段正文」，而用户点这颗「发送」要确认的恰恰是它。所以这一窗
+ * 内部可滚（[ShareConfirmBody]）：**面板的高度一分不涨，正文滚着读完**。
+ *
+ * ## 三行读不下时，再给一次「展开」
+ * 三行窗 + 内部滚动管的是「读得到」，但一次只看得见三行；主人要的是**也能一次多看几行**
+ * （W56 拍板：滚动与展开**两个都要**）。所以这一窗**装不下**里面那几块时（判据是
+ * [sharePreviewTextOverflowsWindow]：量出来的内容自然高度比窗口高，正好放满不给）卡片右上一枚
+ * 「展开」把这一窗放到 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，再点「收起」回到三行。装得下时这一枚
+ * **不出现**——短正文上摆一枚点了没反应的「展开」比没有更糟。
+ *
+ * 「读不到尾」这条红线在两种状态下都守：收起态窗内滚，展开态由外层这一层滚（正文那一层不再设上限，
+ * 见 [ShareConfirmBody] 的「展开态为什么干脆不留这一层上限」）。
+ */
+@Composable
+private fun ShareConfirmPreviews(preview: ShareConfirmPreview) {
+    // 展开是用户对**这一段正文**的选择，键在 `preview.text` 上：换一份分享就回到默认的收起，同一份
+    // 分享里重组（写描述、列表刷新…）保持用户选过的样子。
+    //
+    // ⚠️ 转屏（Activity 重建）会回到收起：跨转屏要活下来就得进 `ChatUiState`——W54C 给「已取走的
+    // 分享」与描述走的就是那条路，而那是 `ChatScreen` / `ChatViewModel` 的地盘（本批不许碰）。
+    // `rememberSaveable` 是本仓一次都没用过的新写法，而且弹层窗口有没有带上 saveable registry 没在
+    // 真机上验过，不在这里试——如实留给主人定。
+    var textExpanded by remember(preview.text) { mutableStateOf(false) }
+
+    Column(
+        modifier = Modifier
+            .fillMaxWidth()
+            .heightIn(max = sharePreviewMaxHeight(textExpanded))
+            .verticalScroll(rememberScrollState()),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        if (preview.images.isNotEmpty()) {
+            // 与输入栏上方那排待发图片预览同一形态（同样 64dp、同样的圆角与间距），只是**没有**
+            // 逐张移除的叉：反悔的粒度是整份分享（「取消」），这里不另开一条「只丢掉其中一张」的路
+            // ——那条路要么改动待发队列、要么改动已取走的那一份，两种都会被「又来了新分享」搅浑。
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.spacedBy(6.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                preview.images.forEach { uri ->
+                    AsyncImage(
+                        model = uri,
+                        contentDescription = "这次分享的图片",
+                        modifier = Modifier
+                            .size(64.dp)
+                            .clip(RoundedCornerShape(10.dp)),
+                    )
+                }
+            }
+        }
+        if (preview.documents.isNotEmpty()) {
+            // 文件芯片就是气泡里那一排（显示名 + 体积），一枚都不藏：上限 5 份会占两到三行。
+            DocumentChipRow(chips = preview.documents.map { DocumentChips.of(it.toDraftDocument()) })
+        }
+        if (preview.hasText) {
+            // 「装不装得下」只有排完才知道（折行位置由字号与系统的大字体缩放决定，块数与旁白行数更是
+            // 解析出来的），所以它由正文那一窗量出来之后回调上来，标签这一行凭它决定要不要给出控件。
+            var bodyOverflows by remember(preview.text) { mutableStateOf(false) }
+            Column(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(12.dp))
+                    .background(MiuixTheme.colorScheme.surfaceContainer)
+                    .padding(10.dp),
+            ) {
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Text(
+                        text = "分享的文字",
+                        style = MiuixTheme.textStyles.footnote2,
+                        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                        // 标签是这一行唯一的权重子项，`fill = false` 让这五个字只占自己需要的宽度；
+                        // 真正保证展开控件不被挤掉的是 Row 的测量顺序——**非权重子项（控件与它前面
+                        // 的间距）先量**，权重只分配剩下的空间（同 `SessionDrawerContent` 里那一行）。
+                        modifier = Modifier.weight(1f, fill = false),
+                    )
+                    if (bodyOverflows) {
+                        // 控件挂在**标签这一行**，不挂在正文末尾：展开后正文可能有好几屏，末尾那枚
+                        // 「收起」就成了要滚到底才找得到的东西。
+                        Spacer(Modifier.width(8.dp))
+                        ShareConfirmExpandToggle(
+                            expanded = textExpanded,
+                            onToggle = { textExpanded = !textExpanded },
+                        )
+                    }
+                }
+                ShareConfirmBody(
+                    text = preview.text,
+                    expanded = textExpanded,
+                    onOverflowChange = { bodyOverflows = it },
+                )
+            }
+        }
+    }
+}
+
+/**
+ * 「展开 / 收起」那一枚（见 [ShareConfirmPreviews]）。
+ *
+ * 为什么是两个字而不是箭头图标：基础图标那一套（`MiuixIcons.Basic.*`）里没有展开 / 收起这一类字形
+ * （只有 `Close` / `Search` / `SearchCleanup` / `Sidebar` / `Check` / `ArrowRight` / `ArrowUpDown`
+ * 七枚），而这两句话本身就说清了点下去会怎样。另一处折叠入口——`AdminOverviewScreen` 的路径组头
+ * ——用的是扩展图标里的 `ChevronForward` 加旋转，那是列表行里的形态；这里是一张阅读用的卡片，
+ * 一句话更省地方，也更好认。
+ *
+ * 用 `Text` + `clickable` 而不是 `TextButton`：后者自带按钮高度，会把这一行（以及整块预览）撑高
+ * 一截——同 `MessageBubble` 里那枚「更多」的取舍。
+ */
+@Composable
+private fun ShareConfirmExpandToggle(expanded: Boolean, onToggle: () -> Unit) {
+    Text(
+        text = if (expanded) SHARE_PREVIEW_COLLAPSE_LABEL else SHARE_PREVIEW_EXPAND_LABEL,
+        style = MiuixTheme.textStyles.footnote2,
+        color = MiuixTheme.colorScheme.primary,
+        modifier = Modifier
+            .clip(RoundedCornerShape(8.dp))
+            .clickable(onClick = onToggle)
+            // 内边距写在 `clickable` **后面**：命中的就是这块带内边距的区域——只包住字身的触点太小。
+            .padding(horizontal = 6.dp, vertical = 2.dp),
+    )
+}
+
+/** 相邻两个气泡块之间的间距（见 [ShareConfirmBody]）。块与块靠这一层间距分开，不靠气泡底色。 */
+private val SHARE_PREVIEW_BLOCK_GAP = 6.dp
+
+/** 一个块里旁白行与正文行之间的间距（气泡里那两行也挨得很近，与 `AnnotationLine` 的 2dp 同源）。 */
+private val SHARE_PREVIEW_LINE_GAP = 2.dp
+
+/**
+ * 正文那一窗：**高度恒为三行、再长就在这一窗里滚**（W54D 主人拍板，见 [ShareConfirmPreviews]）；
+ * 用户点了「展开」之后这一窗撤掉自己的上限，全部内容交给外层预览区那一层滚（W56）。
+ *
+ * 里面排的**不是一段原样的字**，而是 [sharePreviewBlocks] 给出的那几个「气泡块」（W65 起走与
+ * `MessageBubble` 同一个 [parse]）。每个块自己排旁白行与正文行，块与块之间留
+ * [SHARE_PREVIEW_BLOCK_GAP]。
+ *
+ * ## 为什么量行高，而不是写一个 dp 常量
+ * 这个上限必须**正好三行**：矮了会在字身上切一刀（滚动停在一个被切开的字形上），高了就等于把「三行」
+ * 这个上限悄悄放宽。而三行有多高没法提前写出来——Miuix 的 `footnote1` 只给了 13sp 的字号，
+ * `lineHeight` 是 `Unspecified`，行高由系统字体的 ascent/descent 决定、随「大字体」设置一起缩放。
+ * 一个 dp 常量在默认字号档上勉强对得上，到了大字号档就会矮一大截（行数不足三行、末行被切）。
+ * 所以这里改为**量**：任一排版结果都能给出「一行多高」（`getLineBottom(0) - getLineTop(0)`），
+ * 窗口高度 = 它 × [SHARE_PREVIEW_TEXT_LINES]（[sharePreviewWindowHeight]）。
+ *
+ * **为什么不再取「第三行的底边」**（那是 W65 之前的量法）：那时这一窗里只有一个 `Text`，
+ * `getLineBottom(2)` 就是那一个文本的三行底。现在里面是**多个块**，每块还有自己的旁白行与间距——
+ * 在任何一个块上取「第三行」都不再是这个窗口的第三行。行高则是唯一一个跨块也成立、且与块数无关的
+ * 量：窗口恒为「三行字高」，块与旁白占掉多少就从这三行里吃掉多少（这正是它的语义）。
+ *
+ * ## 「装不下」是**量**出来的，不是**数**出来的（W65 换掉的判据）
+ * W65 之前这里数的是**一个 `Text` 的行数**（`lineCount > 3`）。多块之后行数不再是一个数得出来的量：
+ * 旁白行与块间距都占高度，却不属于任何一块的「行数」；字号缩放与折行位置也全落在行数之外。按行数算，
+ * 两块各三行加起来是 6、窗口只装得下 3 行——这条能对，但「一块三行 + 一条旁白 + 一层间距」这种更常见
+ * 的形状就数不准了，而这恰是解析之后最常见的形状。
+ *
+ * 所以现在比的是**高度**：内容排下来的自然高度 vs 这一窗的高度（[sharePreviewTextOverflowsWindow]）。
+ * 两个量都是排完才知道的：
+ * - 窗口高由上面的行高乘三给出；
+ * - 自然高由 [androidx.compose.ui.layout.onSizeChanged] 读到——它挂在 `verticalScroll` **里面**，
+ *   而 `verticalScroll` 给子项的是无界高度，所以读到的是内容的**自然高度**（不受这一窗上限影响的那
+ *   一个，收起态与展开态读到的是同一个数）。
+ *
+ * 「自然高度 > 窗口高度」就是「窗里还有东西没露出来」，正是那枚「展开」承诺的事；旁白、块间距、折行、
+ * 系统大字体缩放全被算在同一把尺子上——它可自证的地方在于：两边都是这一帧真实排出来的像素，没有一处
+ * 是我们估的行数或猜的 dp。
+ *
+ * ⚠️ 这个比较在**组合期**算完、由 [SideEffect] 报上去，**不**在排版回调里算：两个量都来自排版回调，
+ * 而在回调里读到的是**上一帧**组合里的值（`contentHeight` 与 `cap` 都不在本帧的组合里），在那里直接比
+ * 会永远差一帧——首帧报一次「不超窗」之后就再也不会报，长正文上那枚「展开」永远不出现。组合期读到的
+ * 一定是最新的一帧，代价只是一次幂等的重复上报（[SideEffect] 每次组合都跑，值没变就是空写）。
+ *
+ * ## ⚠️ 这一层绝不能拿到 [Dp.Infinity]（W58 修的崩溃）
+ * `heightIn(max = Dp.Infinity)` 等于**不施加约束**，而 `verticalScroll` 一旦在**无界高度**下被测量，
+ * Compose 的 `checkScrollableContainerConstraints` 会**直接抛 `IllegalStateException` 把 App 打崩**
+ * （真机复现：分享进来、面板刚打开就闪退，栈是 `ScrollNode.measure` ← `SizeNode.measure` ← `DialogLayout`）。
+ *
+ * 所以这一层的高度上限**只经 [shareConfirmWindowCap] 一个出口**，它给出的**恒是一个有限值**；
+ * 而「这一层干脆不设上限」只发生在展开态——那时它连 `verticalScroll` 一起去掉（见下一节），
+ * 于是「无界高度 + 滚动」这个组合在两种状态下都不成立：
+ * - **首帧**（还没量到）用 [SHARE_PREVIEW_MAX_HEIGHT] 兜底 —— 有限，且正好是收起态外层预览区的上限；
+ * - **展开态**整层不设上限，但**外层**预览区此时换成 [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，那仍是一层
+ *   有限的约束在管事（不是「没有约束」）。
+ *
+ * 上限只写一次（`cap` 还是 `null` 时才改），所以不会来回跳：拿到上限后重新排版，块的内容、宽度
+ * 与样式都没变，行高与首帧一致，量出来的值也一样。展开 / 收起切换**也不会改写它**——`cap` 记的
+ * 恒是收起态那一窗的高度（这一窗的折行只由宽度决定，两种状态下排出来的行高一样）。
+ *
+ * ## 展开态为什么干脆不留这一层上限
+ * 展开之后正文可能几屏长。若在这一窗上再设一个上限，就成了「窗外滚 + 窗内滚」两层都要滚的手势
+ * （手指先被内层吃掉、内层滚到底才轮到外层），而两层的上界还互相牵制——最容易出的错就是「明明展开
+ * 了、还剩半截读不到」。所以展开态**只留外层那一层**：预览区的上限抬到
+ * [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]，整段正文摊在里面，一层滚到底，读不读得到尾只取决于那一层。
+ * 代价是展开后不能「只滚正文、图片与文件钉着不动」——那要把两层滚动接起来，这个面板不值这个复杂度。
+ *
+ * ## 首帧的那次回流：留着，且确认它看不见
+ * 上限是**首帧之后**才量到的，所以长正文会先按 fallback（[SHARE_PREVIEW_MAX_HEIGHT]）排一次，
+ * 下一帧才收到三行。真机上**看不见**跳动，三条理由：
+ * 1. 首帧那一下撑不动任何别的东西——正文块是预览区里的**最后一个**元素（图片、文件都在它上面），
+ *    而预览区自己还有一层独立的上限在管可视高度：下面没有东西被它顶下去，上面那两样的位置一分
+ *    不动，可视的像素与量完之后**一样**（那些像素由 `heightIn` 的裁剪决定，裁剪高度不变）。
+ * 2. 展开态本来就没有这一层上限，不存在「量完再回落」；而展开 / 收起是用户主动的一次布局变化，
+ *    那一帧的尺寸变化是它的**目的**，不是回流。真正多出来的是展开控件本身——它要到第二帧才出现
+ *    （自然高度是排完才知道的），但这一枚也顶不动东西：标签行里那两句话用的是同一个 `footnote2`，
+ *    行高不变。
+ * 3. 首帧那一次比出来的是「自然高度 vs 150dp 兜底」而不是「vs 三行」：那一帧的结论**可能是错的**
+ *    （一段四五行的正文在 150dp 下看着「装得下」），但它在下一帧就被纠正，而这一枚控件本来就要到
+ *    第二帧才可能摆上——所以这条错判永远看不见。
+ *
+ * 另一条路是在组合期用 `rememberTextMeasurer` 把上限量出来，好让控件从首帧就摆上：那要先知道宽度
+ * （得外包一层 `BoxWithConstraints`），还要自己复现字号、字体缩放与字体回退，等于把排版做两遍——
+ * 为一个看不见的跳动换掉结构不划算，所以不做。
+ *
+ * ## 两层滚动怎么分工
+ * 收起态：这一窗自己滚（正文读完），外层 [ShareConfirmPreviews] 也滚（图片 + 文件芯片 + 这一块
+ * 合起来的高度上限）。手指停在正文上时先滚正文、滚到底再把余量交给外层——`verticalScroll` 本来
+ * 就走嵌套滚动，不用额外接线。
+ *
+ * ⚠️ **展开态必须把这一层整个去掉（上限 + 滚动一起），只留外层那一层滚。** 只去掉上限是不够的 ——
+ * 外层 [ShareConfirmPreviews] 自己就是一个 `verticalScroll`，它给内容的是**无界高度**；这一层若
+ * 留着 `verticalScroll`，那个 scroll 就会在无界高度下被测量 ⇒ 抛同一个
+ * `IllegalStateException`（W58 真机在「点展开」的那一下崩了第二次，就是这么来的）。
+ * 展开后读不读得到尾，只取决于外层那一层。
+ */
+@Composable
+private fun ShareConfirmBody(
+    text: String,
+    expanded: Boolean,
+    onOverflowChange: (Boolean) -> Unit,
+) {
+    val density = LocalDensity.current
+    val blocks = remember(text) { sharePreviewBlocks(text) }
+    // `null` = 还没量到。**不要**拿 [Dp.Infinity] 当这个哨兵值（见 KDoc 里那次崩溃）。
+    var cap by remember(text) { mutableStateOf<Dp?>(null) }
+    // 内容排下来的**自然高度**（见 KDoc：量在 `verticalScroll` 里面，拿到的是不受上限影响的那一个）。
+    var contentHeight by remember(text) { mutableStateOf(0) }
+    // 无条件 `remember`，避免在分支里建状态；滚动位置由这一窗自己的生命周期管。
+    val scroll = rememberScrollState()
+
+    val window = if (expanded) {
+        // 展开态：上限与滚动**一起**去掉（见 KDoc）。内容自然撑开，交给外层预览区那一层滚。
+        Modifier
+    } else {
+        Modifier
+            .heightIn(max = shareConfirmWindowCap(cap))
+            .verticalScroll(scroll)
+    }
+
+    // 一行有多高：正文行与旁白行同为 `footnote1`，所以第一个排完的文本就能给（不限是哪一块的哪一行）。
+    // 量到一次就定死——`cap` 只在这一个分支里被写、且只从 `null` 变成一个值，不会来回跳。
+    val measureLine: (TextLayoutResult) -> Unit = { layout ->
+        if (cap == null && layout.lineCount > 0) {
+            val line = layout.getLineBottom(0) - layout.getLineTop(0)
+            // 0 或负数（还没排稳）不记：150dp 的兜底比一扇零高的窗好（同 [shareConfirmWindowCap] 的取向）。
+            if (line > 0) cap = sharePreviewWindowHeight(with(density) { line.toDp() })
+        }
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxWidth()
+            .then(window)
+            .onSizeChanged { contentHeight = it.height },
+        verticalArrangement = Arrangement.spacedBy(SHARE_PREVIEW_BLOCK_GAP),
+    ) {
+        blocks.forEach { block -> ShareConfirmBlock(block, measureLine) }
+    }
+
+    // 见 KDoc：在组合期算完、由 SideEffect 报上去（两个量在排版回调里读到的是上一帧的值）。
+    val overflows = sharePreviewTextOverflowsWindow(
+        contentHeightPx = contentHeight,
+        windowHeightPx = with(density) { shareConfirmWindowCap(cap).roundToPx() },
+    )
+    SideEffect { onOverflowChange(overflows) }
+}
+
+/**
+ * 预览里的**一个气泡块**：上依附的旁白 + 正文 + 下依附的旁白。
+ *
+ * 这个顺序就是 `MessageBubble` 里那个 `Bubble` 的顺序（`head` → 正文 → `tail`），用的也是同一个
+ * [parse] 给出的同一批块——「预览里长这样」与「发出去之后长那样」因此是**同一套判据**的两次渲染。
+ *
+ * 块与块之间只留一层间距（外层 [ShareConfirmBody] 的 `spacedBy`），**不画气泡底色**：这一栏是面板里
+ * 的一张卡片（`surfaceContainer` 底），而气泡底色在聊天里表示「谁说的」——用户那条是 `primary` 色、
+ * 她那侧是灰。在确认面板里复刻一层假气泡底色会让人以为这里已经是聊天记录；而且那层内边距要从三行窗
+ * 里再吃掉近一行，正是 W54D 之后最不该动的那点可见正文。
+ */
+@Composable
+private fun ShareConfirmBlock(block: ParsedBubble, onTextLayout: (TextLayoutResult) -> Unit) {
+    Column(
+        modifier = Modifier.fillMaxWidth(),
+        verticalArrangement = Arrangement.spacedBy(SHARE_PREVIEW_LINE_GAP),
+    ) {
+        ShareConfirmAnnotation(block.head, onTextLayout)
+        if (block.body.isNotEmpty()) {
+            Text(
+                text = block.body,
+                style = MiuixTheme.textStyles.footnote1,
+                onTextLayout = onTextLayout,
+            )
+        }
+        ShareConfirmAnnotation(block.tail, onTextLayout)
+    }
+}
+
+/**
+ * 预览里的旁白行：**灰斜体小字**——与气泡里那行（`MessageBubble` 的 `AnnotationLine`）同一个形态、
+ * 同一种拼法（多个片段用一个空格连起来），字全是 [parse] 给的那几个 `ContentPart` 的原文。
+ *
+ * ⚠️ 这里**不**读 `LocalAppPrefs.showNarration`（气泡那行会读）。那个偏好管的是**聊天记录里**要不要
+ * 显示旁白，而这块面板回答的是「她将收到的是什么」：按那个偏好把旁白藏起来，就等于让用户在按下发送
+ * 之前看不到这次要发出去的一部分内容——而 W61 审查发现的那处「预览里是标签、气泡里只剩正文」，错的
+ * 正是同一件事（看到的不是要发的）。要改成与气泡一样随时可以，但那是主人拍板的事，不在这里顺手做。
+ */
+@Composable
+private fun ShareConfirmAnnotation(parts: List<ContentPart>, onTextLayout: (TextLayoutResult) -> Unit) {
+    val text = parts.joinToString(" ") { it.text }.trim()
+    if (text.isEmpty()) return
+    Text(
+        text = text,
+        style = MiuixTheme.textStyles.footnote1,
+        fontStyle = FontStyle.Italic,
+        color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+        onTextLayout = onTextLayout,
+    )
+}
+
+/**
+ * **收起态**那一窗的高度上限（**纯函数**，可单测）。
+ *
+ * 量到过就用量的，还没量到就用 [SHARE_PREVIEW_MAX_HEIGHT] 兜底 —— 兜底必须是**有限值**，因为
+ * `heightIn` 与 `verticalScroll` 就在同一串 modifier 上。
+ *
+ * 展开态**不走这里**：那一态连 `verticalScroll` 一起去掉（只留外层预览区那一层滚），没有「上限」
+ * 这个维度可给 —— 见 [ShareConfirmBody] 的 KDoc。
+ *
+ * ⚠️ 返回值**永远是一个有限值** —— `heightIn(max = Dp.Infinity)` 等于不施加约束，而
+ * `verticalScroll` 在无界高度下被测量时 Compose 会直接抛 `IllegalStateException` 把 App 打崩
+ * （W58 真机崩过两次：一次是初值用了 `Dp.Infinity`，一次是展开态只去掉了上限）。这条不变量有单测钉着。
+ *
+ * 所以非有限的那几个取值（[Dp.Infinity] 与 [Dp.Unspecified]，后者是 `NaN`）**与「还没量到」同等对待**，
+ * 一律回落 [SHARE_PREVIEW_MAX_HEIGHT]：这条 KDoc 写的是一条**判据**，而不该只是对调用方的请求——本函数
+ * 是这一层唯一的出口，它自己要能保证「给出去的上限总是有限」。今天唯一的调用方传的是 `null` 或
+ * [sharePreviewWindowHeight] 的结果（正数 × 三，恒有限），所以这一道守卫不改变任何现状；它挡的是
+ * **下一次**有人顺手把 `Dp.Infinity` 当「不设上限」传进来（那正是 W58 第一次崩溃的形状）。
+ */
+internal fun shareConfirmWindowCap(measured: Dp?): Dp =
+    measured?.takeIf { it.value.isFinite() } ?: SHARE_PREVIEW_MAX_HEIGHT
+
+/** 预览区在**收起态**的高度上限（见 [ShareConfirmPreviews]：超出的部分靠内部滚动看）。 */
+internal val SHARE_PREVIEW_MAX_HEIGHT = 150.dp
+
+/**
+ * 预览区在**展开态**的高度上限（用户点了「展开」之后，见 [ShareConfirmPreviews]）。
+ *
+ * 为什么要抬：展开是**用户自己的一个动作**，要的就是「一次多看几行」。上限不动的话这一窗永远只有
+ * 三行高，点开等于没点——正文那一窗顶到 [SHARE_PREVIEW_MAX_HEIGHT] 也只是把三行换成十来行里的一
+ * 小截。所以展开态必须真的给回高度。
+ *
+ * 为什么是 240dp 而不是更大：这个上限管的是**整个预览区**，而它下面还压着描述输入框（最多 4 行）
+ * 与两枚按钮，面板又贴着屏幕底（`BottomCenter`）、键盘一弹可用高度只剩半屏上下。150 → 240 在默认
+ * 字号档上把正文窗从三行抬到十行左右（`footnote1` 13sp，行高由系统字体决定、随机型与大字体设置一起
+ * 变），加上标题 / 输入框 / 按钮之后整块仍在半屏出头；再往上（例如给到整屏的六成）先被顶掉的会是
+ * 两枚按钮。
+ *
+ * ⚠️ 这个数**没有在真机上量过**，是按上面那笔账取的保守值，观感由主人验收。要调只改这一处：
+ * 预览区那一层的高度上限取的就是 [sharePreviewMaxHeight] 这一个出口。
+ */
+internal val SHARE_PREVIEW_EXPANDED_MAX_HEIGHT = 240.dp
+
+/**
+ * 预览里正文那一窗给几行（W54D 起**不再截断**，超出的部分在窗内滚动，见 [ShareConfirmBody]）。
+ *
+ * 它同时是窗口高度那笔账里唯一的数：窗口高 = **量到的行高** × 这个数（[sharePreviewWindowHeight]）。
+ *
+ * `internal` 是为了让 `ShareConfirmTest` 能把这个数钉成字面量：面板的滚动行为单测够不着（本模块没有
+ * Compose UI 测试的依赖），能钉住的只有「这一窗是三行」这条判据本身。
+ */
+internal const val SHARE_PREVIEW_TEXT_LINES = 3
+
+/**
+ * 展开控件上那两句话：点它就在这两句之间切换。
+ *
+ * 两句都必须是**动作**（「展开」/「收起」），不能是「更多」/「更少」——后者说的是内容有多少，读的人
+ * 不知道点下去会发生什么。
+ */
+internal const val SHARE_PREVIEW_EXPAND_LABEL = "展开"
+internal const val SHARE_PREVIEW_COLLAPSE_LABEL = "收起"
+
+/**
+ * 三行窗口有多高（**纯函数**，可单测）：量到的一行高度 × [SHARE_PREVIEW_TEXT_LINES]。
+ *
+ * 行高只能是**量**出来的（见 [ShareConfirmBody] 的「为什么量行高，而不是写一个 dp 常量」），所以这里
+ * 只做乘法、不掺任何 dp 常量：大字体档下量到的行高更大，窗口就跟着更高，「三行」始终是三行。把这个数
+ * 留在唯一一处，改它只改 [SHARE_PREVIEW_TEXT_LINES]。
+ */
+internal fun sharePreviewWindowHeight(lineHeight: Dp): Dp =
+    lineHeight * SHARE_PREVIEW_TEXT_LINES
+
+/**
+ * 预览正文区该渲染成哪几块（**纯函数**，可单测）——**走的就是气泡那一套解析**（W65 起）。
+ *
+ * 用的是 `MessageBubble` 里那同**一个** [parse]，连兜底都是同一条：解析结果为空（或全是被丢掉的空块）
+ * 时回落到「整段原样显示」的那一块，与那边 `parsed.ifEmpty { listOf(plainBubble(content)) }` 逐字同义。
+ * 所以「预览里看不到那一串标签」不是本函数自己剥出来的，而是 [parse] 的既有语义（落单标签一律剥掉、
+ * 完整块切气泡、旁白另成一类）——这里一个字符都不改写、也不另写一套「去标签」。
+ *
+ * **兜底不是可选项**：`parse` 对某些输入会回空列表（纯空白是既有的一档，落单标签被剥光是另一档，
+ * 见 `ShareTextPipelineTest` 里的 `<p><p>` 那几条），而面板的 [ShareConfirmPreview.hasText] 只管
+ * 「正文非空白」，管不到解析结果。少了这条兜底，用户就会在一块**空白**前面按发送——而正文这一栏是他按
+ * 发送之前唯一能核对的东西。
+ *
+ * 正文在这里**不再 trim**：两侧空白早在 [shareConfirmPreview] 那一站去过一次（`share.text.trim()`，
+ * 与 `sendShared` 开头同一个口径），这里再来一次只会多一个说法不一的出处。
+ */
+internal fun sharePreviewBlocks(text: String): List<ParsedBubble> =
+    parse(text).filterNot { it.isEmpty }.ifEmpty {
+        listOf(ParsedBubble(body = text, parts = emptyList(), head = emptyList(), tail = emptyList()))
+    }
+
+/**
+ * 这一窗**装不下**里面的内容吗（**纯函数**，可单测）——也就是「要不要给出展开控件」。
+ *
+ * ## 判据是**高度**，不是行数（W65 换掉的）
+ * W65 之前这里数的是**一个 `Text` 的行数**（`lineCount > SHARE_PREVIEW_TEXT_LINES`）。正文改走解析
+ * 之后这一窗里是**多个块**，每块还各自带旁白行与块间距，于是行数不再是一个覆盖得住窗口的量：
+ *
+ * - 旁白行与块间距都占高度，却谁也不属于哪一块的「行数」；
+ * - 折行位置、字号与系统大字体缩放都落在行数之外：「两个块各占两行、中间一层间距」这种最常见的形状，
+ *   按行数只能说「4 > 3」，说不出它到底差多少，也说不出一块内部的折行吃掉了第二块的位置；
+ * - 反过来也漏：「一块两行 + 一条两行的旁白」数出来是 4 行，但它真正超出的高度取决于那两层间距与
+ *   旁白自己的行高——行数这个量从头到尾没有把它们算进去。
+ *
+ * 所以比的是**两边真实排出来的像素**：内容自然高度（由挂在 `verticalScroll` 里面的
+ * [androidx.compose.ui.layout.onSizeChanged] 读到，见 [ShareConfirmBody]）vs 这一窗的高度
+ * （[sharePreviewWindowHeight] 那个口径：量到的行高 × 三）。「自然高度 > 窗口高度」**就是**「窗里还有
+ * 东西没露出来」，正是那枚「展开」承诺的事。它可自证的地方在于：两个量都是这一帧真实排出来的像素，
+ * 没有任何一处是我们估的行数或猜的 dp。
+ *
+ * 也不是 `hasVisualOverflow`：裁剪落在这一窗外面那层 `Column` 的 `heightIn(max = cap)` 上，而每个
+ * `Text` 自己的排版宽度是满宽、高度不受限（`verticalScroll` 给子项的就是无上限约束），所以它们永远报
+ * 「没有溢出」——拿它当判据会把控件在最长的那种正文上漏掉。
+ *
+ * ## 边界与首帧
+ * 严格大于：**正好一样高**就是整段都在窗里（窗口底下一条不多），此时给一枚「展开」是点了没有反应的
+ * 假控件。
+ *
+ * 任何一边还没量到（`0`）都回 `false`：首帧摆上一枚点了没有反应的「展开」比晚一帧出现更糟。
+ */
+internal fun sharePreviewTextOverflowsWindow(contentHeightPx: Int, windowHeightPx: Int): Boolean =
+    contentHeightPx > 0 && windowHeightPx > 0 && contentHeightPx > windowHeightPx
+
+/**
+ * 预览区当前该给多高（**纯函数**，可单测）：收起态 [SHARE_PREVIEW_MAX_HEIGHT]、展开态
+ * [SHARE_PREVIEW_EXPANDED_MAX_HEIGHT]。
+ *
+ * 把「哪个状态用哪个上限」收在这一处，调用点（[ShareConfirmPreviews]）只读结论：单测钉住的就是这条
+ * 判据本身——两个状态与两个上限的对应关系要是被改反了（例如展开反而变矮），会在这里被抓住。
+ */
+internal fun sharePreviewMaxHeight(expanded: Boolean): Dp =
+    if (expanded) SHARE_PREVIEW_EXPANDED_MAX_HEIGHT else SHARE_PREVIEW_MAX_HEIGHT
+
+/**
+ * 分享进来的一份文件 ⇒ 待发附件。
+ *
+ * `ChatViewModel.sendShared` 里也有同一段三字段的搬运（那边是发给上传链的），**不抽公共**是刻意的：
+ * 抽出来就要动那两个文件（一个是别的并行改动正在碰的 `ChatScreen` 附近，一个是发送路径），
+ * 而这一处只是给芯片显示用的**只读**形态——真正的发送仍然只经过 `sendShared` 那一条，
+ * 两条路各有各的用处。第三次复制出现时再抽（本项目对重复的硬规矩是三次起抽）。
+ */
+private fun SharedDocument.toDraftDocument(): DraftDocument = DraftDocument(
+    uri = uri,
+    displayName = displayName,
+    sizeBytes = sizeBytes,
+)

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ShareLanding.kt

@@ -20,7 +20,7 @@ enum class ShareLanding {
      */
     TellOffline,
 
-    /** 连接就绪：取走一条并交给既有发送路径。 */
+    /** 连接就绪：取走一条并交给确认面板（点「发送」才真的发出去）。 */
     Send,
 }
 
@@ -41,9 +41,9 @@ enum class ShareLanding {
  *
  * ## 判据与优先级
  * 1. **没有待发内容** ⇒ [ShareLanding.Nothing]：任何连接状态下都不做事、也不说话。
- * 2. **[WsState.Connected]** ⇒ [ShareLanding.Send]：取走一条并发送。它**压过**后面每一条——连接一到就该发，
- *    哪怕此前已经等够久、那句「等连上会自动发」也说过了。返回值是**单值动作**，所以「发送」与
- *    「告知」在类型上就不可能同时发生（不会既发了又报怨还没连上）。
+ * 2. **[WsState.Connected]** ⇒ [ShareLanding.Send]：取走一条并交给确认面板（点「发送」才真的发）。
+ *    它**压过**后面每一条——连接一到就该认领，哪怕此前已经等够久、那句「等连上会自动发」也说过了。
+ *    返回值是**单值动作**，所以「认领」与「告知」在类型上就不可能同时发生（不会既取了又报怨还没连上）。
  * 3. 未就绪且**还没等够久**（`waitedLong = false`）⇒ [ShareLanding.KeepWaiting]：继续等，什么都不说
  *    （刚分享进来就弹一句「还没连上」是噪声，握手正常也就几百毫秒）。
  * 4. 未就绪、已等够久、且**还没说过** ⇒ 说一次。说哪一句由连接状态分**两档**：可恢复的那三档

app/src/main/kotlin/top/yeij/cyrene/ui/chat/ShareTextOrigin.kt

@@ -0,0 +1,43 @@
+package top.yeij.cyrene.ui.chat
+
+import top.yeij.cyrene.domain.share.ShareTextSource
+import top.yeij.cyrene.domain.share.SharedContent
+
+/**
+ * 「这段正文是从对方给的**分享标题**回落来的」——面板上那句如实的小字（**纯函数**，可单测）。
+ *
+ * ## 它补的是哪一处
+ * 取正文的回落链（[top.yeij.cyrene.domain.share.ShareRules.extract]：`EXTRA_TEXT` →
+ * `EXTRA_SUBJECT` → `EXTRA_TITLE`）让「对方只给了标题」的那次分享**不再静默**——用户可以确认、可以
+ * 取消。但回落来的那一段与真正文**长得一模一样**：预览里只有一句话时，用户会以为对方发来的就是这句
+ * 正文，其实本端只拿到了标题。所以这里给出一句**只出现在界面上**的说明。
+ *
+ * ## 红线：它绝不进正文
+ * 这句话是**本端渲染层**的信息，一个字都不许拼进将要发送的那段正文（`shareConfirmBody` 拼的是分享
+ * 正文 + 用户描述，与这里无关）：把来源标记拼进正文 = 让用户正文冒充系统指令，是项目红线
+ * （见 `ShareRules` 的「为什么正文一个字都不加」）。所以这条消息的内容**永远只是正文本身**，
+ * 预览里那段字与发出去的那条消息逐字相同。
+ *
+ * ## 为什么 `Subject` 与 `Title` 共用一句
+ * 两档在**数据**上分得很清（[ShareTextSource]，排查时要看得见对方把内容塞进了哪个字段），但对用户说
+ * 的是同一件事：标题与主题在他眼里没有区别。各写一句只会多出一处迟早会走样的措辞。
+ *
+ * ## 不说「正文」的那一档为什么回 `null`
+ * [ShareTextSource.Text] 是规范路径（正文本来就是正文）：一切照旧，**一个字都不说**——正常落地时
+ * 说话才是噪声（与 `shareNoticeFor` 的静默边界同一条纪律）。
+ *
+ * @return 该说的那句话；没有要说的（正文来自 `EXTRA_TEXT`）回 `null`。
+ */
+fun shareTextOriginNotice(share: SharedContent): String? = when (share.textSource) {
+    ShareTextSource.Text -> null
+    ShareTextSource.Subject, ShareTextSource.Title -> SHARE_TEXT_FROM_TITLE_NOTICE
+}
+
+/**
+ * 那句话说出口的样子。
+ *
+ * 两件事要在同一句里说清：**它是什么**（对方给的分享标题）与**缺了什么**（对方没有提供正文）——
+ * 只说前一半，用户仍会以为这句话就是对方发来的正文；只说后一半，他不知道预览里那行字是从哪冒出来的。
+ * 刻意**不说**「失败」「错误」：这一次分享的内容一个字节都没丢，只是它本来就只有标题。
+ */
+const val SHARE_TEXT_FROM_TITLE_NOTICE = "这段文字来自对方的分享标题（对方没有提供正文）"

app/src/main/kotlin/top/yeij/cyrene/ui/chat/StreamingBlocks.kt

@@ -88,10 +88,13 @@ fun ToolCard(
                 FoldCardLabel("参数")
                 FoldCardBody(tool.arguments)
             }
-            if (tool.output.isNotBlank()) {
+            // 结果区是否出现**完全**由 [toolResultTextOf] 决定：`null` 就整块不画（连标签和
+            // 上方那道 Spacer 都不画），于是「摘要缺席」时这一屏与后端补这个键之前**逐字节相同**。
+            val result = toolResultTextOf(tool)
+            if (result != null) {
                 Spacer(Modifier.height(6.dp))
                 FoldCardLabel("结果")
-                FoldCardBody(tool.output)
+                FoldCardBody(result)
             }
         }
     }

app/src/main/kotlin/top/yeij/cyrene/ui/chat/TurnStreams.kt

@@ -108,6 +108,49 @@ fun List<StreamingLeg>.finishingLeg(
 fun List<StreamingLeg>.withoutLeg(bucket: TurnBucket): List<StreamingLeg> =
     if (none { it.bucket == bucket }) this else filterNot { it.bucket == bucket }
 
+/**
+ * **连接重建时收口每一路**（纯函数，[top.yeij.cyrene.ui.chat.settledAfterReconnect] 用它）。
+ *
+ * 与 [finishingLeg] 的关系：同一件事（这一路不再生长、思维链与工具卡不再声称自己在跑），
+ * 区别只在**触发点**——[finishingLeg] 是「收到了这一路的 `stream_end`」，这里没有那一帧，
+ * 是「连接重建了，而服务端那一轮在旧连接上，永远不会再有后续帧」（判据见
+ * [top.yeij.cyrene.ui.chat.isReconnect]，理由见它那一份 KDoc）。
+ *
+ * 两条纪律：
+ * 1. **正文与思维链一个字都不删**——用户可能正读到一半，而这已经不是服务端能再给一次的东西；
+ * 2. **没有任何可显示内容的那一路整条丢掉**：`active = true` 而什么都不画时，[StreamingBubble]
+ *    会画一个只有光标的空气泡，收口它等于把它变成一个**一个像素都不画、却仍占一个列表项**
+ *    （也因此占着「最新一项」这个位置）的幽灵——那种路丢掉是本函数的**唯一**删除动作，
+ *    而它删的是「本来就没有的东西」。
+ *
+ * 无变化时返回**同一个实例**（与 [finishingLeg] / `withoutLeg` 同一条纪律）。
+ */
+fun List<StreamingLeg>.allFinished(): List<StreamingLeg> {
+    val next = mapNotNull { it.finishedLeg() }
+    return if (next == this) this else next
+}
+
+/**
+ * 这一路**收口后**的样子；收口之后**什么都画不出来**时返回 `null`（整路丢掉，见 [allFinished]）。
+ *
+ * 三件事与 [finishingLeg] 逐字同义：不再 `active`（光标停、兜底路径不再当它是新回合）、
+ * 思维链不再 `thinkingActive`（标题从「思考中…」变回「思维链」），外加工具卡也一起收口
+ * （[settledAfterReconnect]，标题从「执行 X…」变回「工具调用 · X」）。
+ *
+ * ⚠️ `bubbles` / `thinking` / 工具卡的参数与输出**一个都没动**：这是「不再声称在跑」，
+ * 不是「清空这一路」。
+ */
+private fun StreamingLeg.finishedLeg(): StreamingLeg? {
+    val settled = state.copy(
+        active = false,
+        thinkingActive = false,
+        tools = state.tools.settledAfterReconnect(),
+    )
+    val anythingToShow =
+        settled.bubbles.isNotEmpty() || settled.thinking.isNotBlank() || settled.tools.isNotEmpty()
+    return if (anythingToShow) copy(state = settled) else null
+}
+
 /**
  * 这条**已落库**消息处在哪一态（六态判定，规范 §1.1）。
  *

app/src/main/kotlin/top/yeij/cyrene/ui/chat/VoiceBubble.kt

@@ -0,0 +1,219 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failureOf
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.isLoadingFor
+import top.yeij.cyrene.domain.chat.voiceAudio
+import top.yeij.cyrene.domain.chat.voiceDurationLabel
+import top.yukonga.miuix.kmp.basic.Icon
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.icon.MiuixIcons
+import top.yukonga.miuix.kmp.icon.extended.Pause
+import top.yukonga.miuix.kmp.icon.extended.Play
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 语音形态里那枚「这是个语音」的字样。它说的是**媒体类型**（判据 = 这条画的是语音形态，
+ * 见 `isVoiceMessage`），不是内容。
+ */
+const val VOICE_LABEL: String = "语音"
+
+/** 加载中那一句（与 [VOICE_LABEL] 同一行，替换掉时长那一格）。 */
+private const val VOICE_LOADING_LABEL = "加载中…"
+
+/** 播放控件那枚图标的读屏名字 —— 同时也是设备验收时 `uiautomator` 拿来定位它的 `content-desc`。 */
+const val VOICE_PLAY_DESCRIPTION: String = "播放语音"
+
+/** 正在放 / 加载中时那枚图标的读屏名字（点它 = 停）。 */
+const val VOICE_STOP_DESCRIPTION: String = "停止播放语音"
+
+/** 图标尺寸：与消息角标那枚「⋯」同一档，整条语音形态因此不比一条角标高多少。 */
+private val VOICE_ICON_SIZE = 18.dp
+
+/**
+ * 一条语音消息在**转写文本之外**的那个「语音」形态：`[播放/暂停] 语音 · 时长`。
+ *
+ * ## 画什么由三条契约判据决定（都在这一个函数里，不散落）
+ * - **🎤 判据 = `voice` 键存在 **且** `status != "failed"`**：本组件只有在这条消息要画语音形态时
+ *   才会被调用（调用点在 [MessageBubble]，判据是 `isVoiceMessage`），所以这里既不认识正文里有
+ *   没有 `[语音]` 字样、也不认识 `status`——`failed` 那一态（没有可播的声音）根本不走这条路，
+ *   它由 `VoiceFallbackNote` 单独画一行灰色小标；
+ * - **无副本 ⇒ 不画播放控件**（[voiceAudio] 回 `null`）：四个键（`name`/`mime`/`size`/`url`）
+ *   没凑齐时只留「语音」这一格 —— 不能给一个点下去必然失败的按钮。时长若服务端给了照样显示
+ *   （时长与副本**无关**）；
+ * - **缺席就不显示时长**（[voiceDurationLabel] 回 `null`）：绝不显示 `0:00` 冒充，也不拿
+ *   `size` 反算。
+ *
+ * ## 三处文案各自归谁
+ * - **正文**（转写 / 服务端的诚实提示）由 [MessageBubble] 照常渲染，本组件一个字符都不改、
+ *   也不隐藏它；
+ * - [note]（`status = empty` 且正文为空时那句「没有识别出文字」）由调用方用纯函数
+ *   `voiceNote` 算好传进来 —— 本组件不判 `status`；
+ * - [playback] 里这条消息的失败提示（[failureOf]）**只在失败时出现一行**，颜色用
+ *   `colorScheme.error`：可见但不夸张（不弹窗、不占整行、不挡住正文）。
+ *
+ * ## 图标从哪来（查过 AAR，不是猜的）
+ * `miuix-icons-android:0.9.3` 的 **basic** 包只有 7 枚（`Close` / `Search` / `SearchCleanup` /
+ * `Sidebar` / `Check` / `ArrowRight` / `ArrowUpDown`），**没有播放 / 暂停字形**；但 **extended**
+ * 包里有真的 `Play` / `Pause`（`javap` 确认过 `PlayKt.getPlay(MiuixIcons)`），而本模块本来就在用
+ * extended（`MessageBubble.kt` 的 `MiuixIcons.More`）。所以这里用真的字形，**不**自绘几何图形：
+ * 自绘一个三角形在扫读上并不比官方图标便宜，还要自己承担「像不像播放键」的风险。
+ * 官方文档写 `MiuixIcons.Xxx` 的用法对人不对包，以 AAR 为准 —— 这两枚就是 extended 包里的。
+ *
+ * ## 点哪儿
+ * **整枚可点**（不只是那 18dp 的图标）：读屏与手指都不必瞄准；图标只是「这里能按」的可见凭据
+ * （与 [LegBadge] 「看得出可点」同一条思路）。
+ *
+ * @param note 正文之外要多说的一句（没有就传 `null`）。
+ * @param playback 这条通道的当前状态（由调用方用 [rememberVoicePlayer] 那一个实例驱动）。
+ * @param onToggle 用户点了这枚语音：交给上层真正去取字节 / 放 / 停（本组件不发请求）。
+ */
+@Composable
+fun VoiceMessageRow(
+    voice: VoiceDto,
+    messageId: String,
+    playback: VoicePlaybackState,
+    note: String? = null,
+    alignEnd: Boolean = false,
+    onToggle: () -> Unit = {},
+    modifier: Modifier = Modifier,
+) {
+    val audio = voiceAudio(voice)
+    val active = playback.isActiveFor(messageId)
+    val loading = playback.isLoadingFor(messageId)
+    val failure = playback.failureOf(messageId)
+    val duration = voiceDurationLabel(voice.durationMs)
+
+    Column(
+        modifier = modifier,
+        horizontalAlignment = if (alignEnd) Alignment.End else Alignment.Start,
+        verticalArrangement = Arrangement.spacedBy(2.dp),
+    ) {
+        Row(
+            modifier = Modifier
+                .clip(RoundedCornerShape(12.dp))
+                .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+                .then(
+                    if (audio == null) {
+                        Modifier
+                    } else {
+                        Modifier
+                            .clickable(onClick = onToggle)
+                            // 可点的那一层（整枚）自己报「点它会发生什么」；里面的图标因此只是
+                            // 一笔装饰（`contentDescription = null`），读屏不会读到第二个焦点。
+                            .semantics {
+                                contentDescription = if (active) VOICE_STOP_DESCRIPTION else VOICE_PLAY_DESCRIPTION
+                            }
+                    },
+                )
+                .padding(start = 8.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            if (audio != null) {
+                Icon(
+                    imageVector = if (active) MiuixIcons.Pause else MiuixIcons.Play,
+                    contentDescription = null,
+                    tint = MiuixTheme.colorScheme.primary,
+                    modifier = Modifier
+                        .size(VOICE_ICON_SIZE)
+                        .clip(CircleShape),
+                )
+            }
+            Text(
+                text = VOICE_LABEL,
+                style = MiuixTheme.textStyles.footnote1,
+                color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            )
+            when {
+                // 「现在在干什么」与「点它会怎样」分开说：图标回答后者，这一格回答前者。
+                // ⚠️ 只有**真的在取字节**时才说「加载中…」：`active` 还包含「正在响」，
+                // 拿它当条件会让一条 30 秒的语音整段播放期间都写着「加载中…」。
+                loading -> Text(
+                    text = VOICE_LOADING_LABEL,
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+
+                duration != null -> Text(
+                    text = duration,
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+            }
+        }
+        note?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+            )
+        }
+        failure?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+            )
+        }
+    }
+}
+
+/**
+ * `status == "failed"` 那条消息**没有语音形态**，但要多说的一句话（`voice` 键在、没有可播的声音）。
+ *
+ * ## 为什么这一行必须存在
+ * 这一态的消息正文照常按文字渲染（入站是服务端那行诚实提示，出站是合成降级后的原文本）。少了这一行，
+ * 一条「她本想用语音、合成降级成文字」的消息与一条普通文字消息**逐像素相同**——看的人无从知道这条
+ * 本来是一段声音，也看不出它与别的话有什么不一样。所以这枚小标不是装饰，它是这一态**唯一**的可见
+ * 凭据（[VoiceMessageRow] 在这里根本不画，见 `isVoiceMessage`）。
+ *
+ * ## 样式为什么抄 [VoiceMessageRow] 里 note 那一行
+ * `footnote2` + `onSurfaceVariantSummary`：与语音形态旁边那几句说明（「没有识别出文字」/ 加载中 /
+ * 时长）**同一档**。这三处说的都是「关于这段声音的一句脚注」，同一个外观才让人读成一类东西；
+ * 换成正文那一档字级会被误读成消息内容的一部分，换成 `error` 又会把一次**降级**说成一次**失败**
+ * ——降级本身是服务端做对的一件事（她的话一个字没丢，只是没变成声音）。
+ *
+ * ## 不判 `status`，也不拼文案
+ * [text] 由调用方用纯函数 `voiceFallbackNote` 算好传进来（固定前半句 + 服务端 `fallbackReason` 原样）。
+ * 本组件只负责画：判据与措辞都在 domain 层单测钉着，这里再判一次就多出「两处判据不一致」的可能
+ * ——与 [VoiceMessageRow] 对 `note` 的处理同一条纪律。
+ *
+ * @param text 已经算好的那一整句（本组件不改一个字符）。
+ * @param alignEnd 用户侧（气泡在右）：整行贴右；否则贴左。
+ */
+@Composable
+fun VoiceFallbackNote(
+    text: String,
+    alignEnd: Boolean = false,
+    modifier: Modifier = Modifier,
+) {
+    Column(
+        modifier = modifier,
+        horizontalAlignment = if (alignEnd) Alignment.End else Alignment.Start,
+    ) {
+        Text(
+            text = text,
+            style = MiuixTheme.textStyles.footnote2,
+            color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+        )
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/ui/chat/VoiceInputBar.kt

@@ -0,0 +1,349 @@
+package top.yeij.cyrene.ui.chat
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.unit.dp
+import top.yeij.cyrene.domain.chat.VoiceDraftInfo
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failureOf
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.isLoadingFor
+import top.yeij.cyrene.domain.chat.voiceElapsedLabel
+import top.yeij.cyrene.domain.chat.voiceReplyNote
+import top.yukonga.miuix.kmp.basic.Button
+import top.yukonga.miuix.kmp.basic.Icon
+import top.yukonga.miuix.kmp.basic.IconButton
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.icon.MiuixIcons
+import top.yukonga.miuix.kmp.icon.basic.Close
+import top.yukonga.miuix.kmp.icon.extended.Mic
+import top.yukonga.miuix.kmp.icon.extended.Pause
+import top.yukonga.miuix.kmp.icon.extended.Play
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 输入栏那几个**语音**形态（录音中 / 待重发 / 她的语音回复），以及乐观气泡里那一枚「语音」。
+ *
+ * ## 为什么单独一个文件
+ * 它们四个共用同一套尺寸与配色，而这个文件之外没人需要知道这些细节：`ChatScreen` 只负责接线，
+ * `MessageBubble` 只调用最后一枚。放在一起，改一眼就能看全。
+ *
+ * ## 图标从哪来（查过 AAR，不是猜的）
+ * `miuix-icons-android:0.9.3` 的 **basic** 包只有 7 枚，**没有麦克风**；**extended** 包里有真的
+ * `Mic` / `MicSlash`（`javap` 确认过 `MicKt.getMic(MiuixIcons)`），而本模块本来就在用 extended
+ * （`VoiceBubble.kt` 的 `Play` / `Pause`、`ChatScreen.kt` 的 `File` / `Image`）。
+ *
+ * ## 读屏名字即设备验收的 `content-desc`
+ * 四枚可点控件的 `contentDescription` 都抽成了常量（[VOICE_RECORD_DESCRIPTION] 等）：
+ * `uiautomator dump` 靠它们定位，改文案等于改验收口径，两处一起改。
+ */
+
+/** 「开始录音」那枚麦克风的读屏名字。 */
+const val VOICE_RECORD_DESCRIPTION: String = "按住说话（点按开始录音）"
+
+/** 录音中那枚麦克风（点它 = 结束并发送）。 */
+const val VOICE_RECORD_STOP_DESCRIPTION: String = "结束录音并发送"
+
+/** 录音中的「取消」。 */
+const val VOICE_RECORD_CANCEL_DESCRIPTION: String = "取消这段录音"
+
+/** 待重发那一段的「重发」。 */
+const val VOICE_DRAFT_RETRY_DESCRIPTION: String = "重发这段语音"
+
+/** 待重发那一段的「丢弃」。 */
+const val VOICE_DRAFT_DISCARD_DESCRIPTION: String = "丢弃这段语音"
+
+/** 她的语音回复的播放 / 停止。 */
+const val VOICE_REPLY_PLAY_DESCRIPTION: String = "播放她的语音回复"
+const val VOICE_REPLY_STOP_DESCRIPTION: String = "停止播放她的语音回复"
+
+/** 关掉她的语音回复那一张卡片。 */
+const val VOICE_REPLY_DISMISS_DESCRIPTION: String = "关闭这条语音回复"
+
+/** 乐观气泡里那枚「语音」的字样（与接收侧的 [VOICE_LABEL] 同一个词，不另造）。 */
+const val VOICE_CLIP_LABEL: String = VOICE_LABEL
+
+/**
+ * 麦克风**没授权**时的如实告知。
+ *
+ * 说「到系统设置里允许」而不是再申请一次：本端只在第一次点麦克风时申请（平台规范），
+ * 被拒之后重复申请只会被系统静默挡回（Android 不再弹框），那样用户点十次都毫无反应。
+ */
+const val VOICE_PERMISSION_DENIED_MESSAGE: String =
+    "没有麦克风权限，到系统设置里允许后再试"
+
+/**
+ * 有权限、但麦克风**现在起不来**（被别的应用占用 / 设备不支持这组采样参数）。
+ *
+ * 与 [VOICE_PERMISSION_DENIED_MESSAGE] 分开：那一档用户要去设置页，这一档要等一会或换个应用；
+ * 说成同一句就是把人引向一个解决不了问题的动作。
+ */
+const val VOICE_UNAVAILABLE_MESSAGE: String = "麦克风现在打不开，可能被别的应用占着"
+
+/** 图标尺寸：与接收侧语音形态同一档。 */
+private val VOICE_ICON_SIZE = 18.dp
+
+/** 卡片底色与圆角：与 `VoiceMessageRow` 那一枚同形（同一个产品里的语音长一个样）。 */
+private val VOICE_CARD_SHAPE = RoundedCornerShape(12.dp)
+
+/**
+ * 录音中那一行：`🎤 录音中 · 0:07 [取消] [发送]`。
+ *
+ * 时长由**已收到的字节数**反算（见 `VoiceRecorder`），所以屏幕上这个数字与发出去的音频长度
+ * 严格一致。到 60 秒时 `VoiceRecorder` 会置「满了」标记、由调用方直接收尾——这里不做倒计时：
+ * 一个还在数的计时器在「已经满了」那一刻是假话。
+ *
+ * 两枚按钮分开（不是「点头像就发」那种手势）：录音是一条**有去无回**的动作（这段 bytes 一旦
+ * 发出就落进服务端编排），取消必须和发送一样容易按到。
+ */
+@Composable
+fun VoiceRecordingRow(
+    elapsedMs: Int,
+    onCancel: () -> Unit,
+    onSend: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.error,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "录音中 · ${voiceElapsedLabel(elapsedMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            modifier = Modifier.weight(1f),
+        )
+        IconButton(
+            onClick = onCancel,
+            modifier = Modifier.semantics { contentDescription = VOICE_RECORD_CANCEL_DESCRIPTION },
+        ) {
+            Icon(imageVector = MiuixIcons.Basic.Close, contentDescription = null)
+        }
+        Button(onClick = onSend) { Text("发送") }
+    }
+}
+
+/**
+ * 一段**录好但没发出去**的语音：`🎤 语音 · 0:07 [重发] [丢弃]`。
+ *
+ * 它只在一件事之后出现：`voice_input` 没能上行（连接没就绪 / 写帧失败）。此时那段字节**只在
+ * 内存里**，界面上必须给两条出路——重发（**复用同一个 `clientMsgId`**，服务端据此判重）或丢弃。
+ * 不给「退回到输入栏」那种出路：语音没有可以退回到输入框的形态。
+ */
+@Composable
+fun VoiceDraftRow(
+    draft: VoiceDraftInfo,
+    onRetry: () -> Unit,
+    onDiscard: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.primary,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "$VOICE_CLIP_LABEL · ${voiceElapsedLabel(draft.durationMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+            modifier = Modifier.weight(1f),
+        )
+        TextButton(
+            text = "重发",
+            onClick = onRetry,
+            modifier = Modifier.semantics { contentDescription = VOICE_DRAFT_RETRY_DESCRIPTION },
+        )
+        TextButton(
+            text = "丢弃",
+            onClick = onDiscard,
+            modifier = Modifier.semantics { contentDescription = VOICE_DRAFT_DISCARD_DESCRIPTION },
+        )
+    }
+}
+
+/**
+ * 她的语音回复：`[▶] 她的语音回复 · 0:03 [×]` + 她说的话（[VoiceReply.reply]）。
+ *
+ * ## 只有文字那一档
+ * `provider == "silent"`（或这一轮根本没有 audio）时**不画播放控件**，只画文字 + 一句
+ * [voiceSilentNote]（「这一轮她只回了文字，没有语音」）。契约的硬要求是「UI 别把它画成播放器」；
+ * 补那句解释是为了让「她选择只用文字」与「播放器坏了」在屏幕上分得开。
+ *
+ * ## 可播放但播不了
+ * 音频在、本机解码 / 落盘失败时**照样画**播放控件：点了会走到 [failureOf] 那一行如实说
+ * 「播不了」——这比一个看起来什么都没有的控件诚实。
+ */
+@Composable
+fun VoiceReplyRow(
+    reply: VoiceReply,
+    playback: VoicePlaybackState,
+    onTogglePlay: () -> Unit,
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    val active = playback.isActiveFor(reply.id)
+    val loading = playback.isLoadingFor(reply.id)
+    val failure = playback.failureOf(reply.id)
+    val text = reply.reply
+
+    Column(
+        modifier = modifier
+            .fillMaxWidth()
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 10.dp, end = 4.dp, top = 6.dp, bottom = 6.dp),
+        verticalArrangement = Arrangement.spacedBy(2.dp),
+    ) {
+        Row(
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            if (reply.playable) {
+                // 整枚可点（不只是 18dp 的图标），读屏名字说清「点它会怎样」。
+                Row(
+                    modifier = Modifier
+                        .clip(CircleShape)
+                        .clickable(onClick = onTogglePlay)
+                        .semantics {
+                            contentDescription = if (active) {
+                                VOICE_REPLY_STOP_DESCRIPTION
+                            } else {
+                                VOICE_REPLY_PLAY_DESCRIPTION
+                            }
+                        }
+                        .padding(2.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(6.dp),
+                ) {
+                    Icon(
+                        imageVector = if (active) MiuixIcons.Pause else MiuixIcons.Play,
+                        contentDescription = null,
+                        tint = MiuixTheme.colorScheme.primary,
+                        modifier = Modifier.size(VOICE_ICON_SIZE),
+                    )
+                    Text(
+                        text = "她的语音回复",
+                        style = MiuixTheme.textStyles.footnote1,
+                        color = MiuixTheme.colorScheme.primary,
+                    )
+                }
+            } else {
+                Text(
+                    text = "她的语音回复",
+                    style = MiuixTheme.textStyles.footnote1,
+                    color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+                )
+            }
+            // 「现在在干什么」与「点它会怎样」分开说（与接收侧语音形态同一条纪律）：
+            // 只有真的在取字节时才说「准备中…」，正在响时不冒充加载。
+            if (loading) {
+                Text(
+                    text = "准备中…",
+                    style = MiuixTheme.textStyles.footnote2,
+                    color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+                )
+            }
+            Row(
+                modifier = Modifier.weight(1f),
+                horizontalArrangement = Arrangement.End,
+            ) {
+                IconButton(
+                    onClick = onDismiss,
+                    modifier = Modifier.semantics { contentDescription = VOICE_REPLY_DISMISS_DESCRIPTION },
+                ) {
+                    Icon(imageVector = MiuixIcons.Basic.Close, contentDescription = null)
+                }
+            }
+        }
+        text?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote1,
+                color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+                modifier = Modifier.padding(start = 2.dp, end = 8.dp),
+            )
+        }
+        // 「只有文字」与「本机没准备好」是两件事，各说各的那句（判据是纯函数）。
+        voiceReplyNote(silent = reply.silent, hasAudioFile = reply.file != null)?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.onSurfaceVariantSummary,
+            )
+        }
+        failure?.let {
+            Text(
+                text = it,
+                style = MiuixTheme.textStyles.footnote2,
+                color = MiuixTheme.colorScheme.error,
+            )
+        }
+    }
+}
+
+/**
+ * 乐观气泡里那一枚「语音」：`🎤 语音 · 0:07`。
+ *
+ * 用户按住说话之后，气泡**立刻**出现（与文本消息的乐观路径同一个 `pending` 列表、同一个回滚），
+ * 只是正文还没到——转写要等服务端。所以这里只画媒体类型与时长，**不画播放控件**：
+ * 本地已经发出去的那段音频不在播放通道里（它已经在服务端了，回放应当走历史消息那条路）。
+ */
+@Composable
+fun VoiceClipLabel(durationMs: Int, modifier: Modifier = Modifier) {
+    Row(
+        modifier = modifier
+            .clip(VOICE_CARD_SHAPE)
+            .background(MiuixTheme.colorScheme.surfaceContainerHigh)
+            .padding(start = 8.dp, end = 10.dp, top = 6.dp, bottom = 6.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(6.dp),
+    ) {
+        Icon(
+            imageVector = MiuixIcons.Mic,
+            contentDescription = null,
+            tint = MiuixTheme.colorScheme.primary,
+            modifier = Modifier.size(VOICE_ICON_SIZE),
+        )
+        Text(
+            text = "$VOICE_CLIP_LABEL · ${voiceElapsedLabel(durationMs)}",
+            style = MiuixTheme.textStyles.footnote1,
+            color = MiuixTheme.colorScheme.onSurfaceContainerHigh,
+        )
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/ui/chat/VoicePlayer.kt

@@ -0,0 +1,230 @@
+package top.yeij.cyrene.ui.chat
+
+import android.media.AudioAttributes
+import android.media.MediaPlayer
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.rememberUpdatedState
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.chat.VOICE_UNPLAYABLE_MESSAGE
+import top.yeij.cyrene.domain.chat.VoiceAudio
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.failed
+import top.yeij.cyrene.domain.chat.finished
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.prepared
+import top.yeij.cyrene.domain.chat.pressed
+import top.yeij.cyrene.domain.chat.silenced
+import top.yeij.cyrene.domain.chat.voiceAudio
+import top.yeij.cyrene.domain.chat.voicePlaybackFailureMessage
+import java.io.File
+
+/**
+ * 「同一时刻只有一条语音在响」的那条**播放通道**（接收侧：播放别人发来的语音）。
+ *
+ * ## 用什么放（不引任何新依赖）
+ * 系统 **`android.media.MediaPlayer`**（平台 API，API 1 起就有）。选它而不是 ExoPlayer / Media3：
+ * 项目纪律是加依赖要先问，而这里要的只是「放一段 ogg / wav / mp3 的本地文件」，平台的解码器够用。
+ * 音源是**本地文件**（[load] 的产物）：字节由 `VoiceStore` 取一次、落在 `cacheDir/media/`，
+ * 于是播放本身不联网、不随时间抖动，也**不必**把 Bearer 头塞进播放器（`MediaPlayer` 的头部参数
+ * 不会走 401 续期那条路，那才是真的会出事的地方）。
+ *
+ * ## 生命周期：三处必须停下来并释放（`MediaPlayer` 不 `release()` 会一直占着解码器与音频通路）
+ * 1. **开始播另一条**：[toggle] 在任何新播放之前先 [stop]（旧的那条停下并释放，含正在下载的
+ *    那一次）——所以「一条没放完又点另一条」不会出现两条叠着响；
+ * 2. **离开会话 / 换会话**：调用方用 [rememberVoicePlayer]（它按 `sessionKey` 换实例并在
+ *    `onDispose` 里 [release]），换会话 = 换实例 = 旧的那条立刻停；
+ * 3. **组件销毁**：同上，`onDispose` 是组合被丢弃时唯一可靠的时刻（[release] 幂等，可重复调）。
+ *
+ * ⚠️ **本片没做的两件事（如实）**：
+ * - **不申请音频焦点**（`AudioManager` 那套）：需要 `Context` 与「焦点被抢走」的处理，属于
+ *   「播放器该有的完整行为」，与本期「收得到、放得出来」不是一档。后果是主人自己在放音乐时
+ *   语音会叠在上面；
+ * - **App 退到后台不停播**（要接 `LocalLifecycleOwner` 需要 `lifecycle-runtime-compose`，
+ *   本期不加依赖）。语音都很短，影响面是「切走那一两秒还在响」。
+ *
+ * ## 失败：可见、但不夸张
+ * 两档失败都会进 [VoicePlaybackState.Failed]（气泡据此把按钮变回「未播」并显示**一行**短提示）：
+ * 取字节失败（网络 / 404 / 地址拼不出来，文案来自 [voicePlaybackFailureMessage]）与解码起播失败
+ * （[VOICE_UNPLAYABLE_MESSAGE]）。**绝不静默**——一条点了没反应的语音在用户眼里就是坏的。
+ *
+ * ## 不缓存字节（这一层）
+ * 缓存是 [VoiceStore] 的事（按存储名落 `cacheDir/media/`，命中就不发请求）。本类只负责「拿到
+ * 文件 → 放 → 放完/停 → 释放」，因此它不认识网络，也不认识缓存策略。
+ *
+ * @param scope 驱动的协程作用域（调用方给，通常是组合的 `rememberCoroutineScope`）。
+ * @param load 取这条语音的**本地文件**（未命中缓存时内部会下载并落盘）。
+ */
+class VoicePlayer(
+    private val scope: CoroutineScope,
+    private val load: suspend (VoiceAudio) -> Result<File>,
+) {
+
+    private val _state = MutableStateFlow<VoicePlaybackState>(VoicePlaybackState.Idle)
+
+    /** 这条通道此刻的状态（气泡与按钮都看它）。状态机本身是纯函数，见 `domain.chat.VoicePlayback`。 */
+    val state: StateFlow<VoicePlaybackState> = _state.asStateFlow()
+
+    /** 正在取字节的那次协程；停下 / 换目标时一并取消（用户不该被一个慢下载困住）。 */
+    private var loading: Job? = null
+    /** 当前这一台 `MediaPlayer`（null = 没有）。回调里的身份比对都以它为准。 */
+    private var player: MediaPlayer? = null
+
+    /**
+     * 用户点了这条消息的播放 / 暂停。
+     *
+     * 判据全部走纯函数：拿不到 [VoiceAudio]（**无副本** ⇒ 四个键没凑齐）就**什么都不做**
+     * ——正常路径上那时气泡根本不画播放控件，这里是第二道闸（同一个判据，不在 UI 之外再猜一次）。
+     */
+    fun toggle(message: HistoryMessageDto) {
+        val audio = voiceAudio(message.voice) ?: return
+        val id = message.id
+        // 再点一下 = 停（加载中也算：那表示「别下了」）。
+        if (_state.value.isActiveFor(id)) {
+            stop()
+            return
+        }
+        stop()
+        _state.value = _state.value.pressed(id)
+        loading = scope.launch {
+            load(audio).fold(
+                onSuccess = { file ->
+                    // 这一帧还该不该放：用户可能已经点了停 / 点了别的（状态已不是 Loading(id)）。
+                    if (_state.value.isActiveFor(id)) play(id, file)
+                },
+                onFailure = { error ->
+                    _state.value = _state.value.failed(id, voicePlaybackFailureMessage(error))
+                },
+            )
+        }
+    }
+
+    /**
+     * 放一段**已经在手上**的音频（`voice_output` 那条路：base64 就在帧里，不需要下载）。
+     *
+     * 与 [toggle] 走**同一条通道**、同一套身份比对与释放纪律（同一台喇叭上永远只有一条语音在响），
+     * 差别只有两个：音频不是「按消息取字节」而是由调用方现给（[load]），而且键是
+     * `voice_output` 那一帧自己铸的 [clipId]（它不是历史消息，没有 `messageId` 可用）。
+     *
+     * 同样遵守「再点一下 = 停」：`clipId` 正在放 / 正在载入时，这一下是**停**。
+     *
+     * @param load 取这份本地文件（写缓存 / 解码都在里面，调用方应切到 IO）。
+     */
+    fun toggleClip(clipId: String, load: suspend () -> Result<File>) {
+        if (_state.value.isActiveFor(clipId)) {
+            stop()
+            return
+        }
+        stop()
+        _state.value = _state.value.pressed(clipId)
+        loading = scope.launch {
+            load().fold(
+                onSuccess = { file ->
+                    if (_state.value.isActiveFor(clipId)) play(clipId, file)
+                },
+                onFailure = { error ->
+                    _state.value = _state.value.failed(clipId, voicePlaybackFailureMessage(error))
+                },
+            )
+        }
+    }
+
+    /** 停下来并释放（幂等）：取消取字节、拆掉播放器、状态回 [VoicePlaybackState.Idle]。 */
+    fun stop() {
+        loading?.cancel()
+        loading = null
+        releasePlayer()
+        // ⚠️ `silenced` 而不是「只清 Playing」：失败那句话也要跟着走——换了目标 / 离开页面之后，
+        // 屏幕上不该还挂着上一条的失败。
+        _state.value = _state.value.silenced
+    }
+
+    /** 组件销毁 / 离开会话时调（等价于 [stop]，单列一个名字是为了让调用点的意图看得见）。 */
+    fun release() = stop()
+
+    private fun play(messageId: String, file: File) {
+        val mp = MediaPlayer()
+        player = mp
+        mp.setAudioAttributes(
+            AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                .build(),
+        )
+        mp.setOnPreparedListener { prepared ->
+            // 身份比对：已经换掉 / 已经 release 的那个实例，回调一律不改状态。
+            if (player !== prepared) return@setOnPreparedListener
+            prepared.start()
+            _state.value = _state.value.prepared(messageId)
+        }
+        mp.setOnCompletionListener { done ->
+            if (player !== done) return@setOnCompletionListener
+            releasePlayer()
+            _state.value = _state.value.finished(messageId)
+        }
+        mp.setOnErrorListener { broken, _, _ ->
+            if (player !== broken) return@setOnErrorListener true
+            releasePlayer()
+            _state.value = _state.value.failed(messageId, VOICE_UNPLAYABLE_MESSAGE)
+            // true = 这次错误已经处理（不让它再走 onCompletion，也不弹系统默认处理）。
+            true
+        }
+        try {
+            mp.setDataSource(file.absolutePath)
+            // prepareAsync 而不是 prepare：同步那一版会占着主线程等解码器，异步的失败同样会走到
+            // onError（format 不支持 / 文件损坏 / 已被清空都是这一档）。
+            mp.prepareAsync()
+        } catch (_: Exception) {
+            // setDataSource / prepareAsync 在状态不对、文件读不动时**同步抛**：如实报「播不了」。
+            releasePlayer()
+            _state.value = _state.value.failed(messageId, VOICE_UNPLAYABLE_MESSAGE)
+        }
+    }
+
+    /**
+     * 把当前那台播放器拆干净：先摘掉全部监听（免得 `stop()` / `release()` 触发的回调再改状态），
+     * 再 `stop()`（未 prepare 完时它会抛 `IllegalStateException`，所以包在 `runCatching` 里），
+     * 最后 `release()`。
+     */
+    private fun releasePlayer() {
+        val current = player ?: return
+        player = null
+        current.setOnPreparedListener(null)
+        current.setOnCompletionListener(null)
+        current.setOnErrorListener(null)
+        runCatching { current.stop() }
+        runCatching { current.release() }
+    }
+}
+
+/**
+ * 为**当前这段组合**（通常是一个会话的聊天页）记住一条播放通道，并在它被丢弃时释放。
+ *
+ * 两条纪律写在这里，因为它们是本类唯一的使用方式：
+ * - **[sessionKey] 变了就换一条通道**：换会话 = 换通道 = 上一条立刻停（`remember` 换实例 →
+ *   `DisposableEffect` 的旧 effect 走 `onDispose` → [VoicePlayer.release]）；
+ * - **[load] 变化不重建通道**：它由 `rememberUpdatedState` 顶着（每次重组拿到最新那个 lambda），
+ *   否则重组期间的一次实例更替会把正在放的那条停掉。
+ */
+@Composable
+fun rememberVoicePlayer(
+    sessionKey: Any?,
+    load: suspend (VoiceAudio) -> Result<File>,
+): VoicePlayer {
+    val scope = rememberCoroutineScope()
+    val currentLoad by rememberUpdatedState(load)
+    val player = remember(sessionKey) { VoicePlayer(scope) { audio -> currentLoad(audio) } }
+    DisposableEffect(player) {
+        onDispose { player.release() }
+    }
+    return player
+}

app/src/main/kotlin/top/yeij/cyrene/ui/chat/VoiceReply.kt

@@ -0,0 +1,49 @@
+package top.yeij.cyrene.ui.chat
+
+import java.io.File
+
+/**
+ * `voice_output` 在界面上的那一份「她的语音回复」（只管**这一条实时应答**，不进历史）。
+ *
+ * ## 为什么它不在消息列表里
+ * 契约 v0.96 §3.15：这一帧**只定向回发起 `voice_input` 的那条连接**、**连接断了不补投**，
+ * 而且回合的正文本来就会经流式 / `message_persisted` 落进消息列表。所以它不是一条消息，
+ * 是「这一次语音回合的音频 + 她说的话」这一次性产物：放在输入栏上方一条卡片里，
+ * 用户随时可以关掉（[ChatViewModel.dismissVoiceReply]），它不参与排序、不占历史。
+ *
+ * ## [hasAudio] 与 [file] 是两件事
+ * - [hasAudio]：**服务端**这一轮给了真音频（`provider != "silent"` 且 `audio` 非空白）。
+ *   为假 ⇒ 界面上**一个播放控件都不画**（画了就是点下去必然失败的按钮）。
+ * - [file]：音频在本机的那份文件。`hasAudio` 为真而它是 `null` = 本机解码 / 落盘失败
+ *   ——这一档**照样画**播放控件（点了会如实报「播不了」），**绝不**把本机的故障说成
+ *   「她这一轮只回了文字」（见 `domain.chat.voiceReplyNote`）。
+ *
+ * @property id 播放通道的键：每条 `voice_output` 现铸一个（它不是历史消息，没有 `messageId`）。
+ * @property reply 她说的那一句（音频念的就是它），见 `domain.chat.voiceReplyText`。
+ * @property transcript 转写（载荷里的 `text`）：那段音频被识别成什么；只作兜底与诊断。
+ * @property format 服务端给的音频格式；本端**不照抄它去解码**（`MediaPlayer` 按文件头嗅探）。
+ */
+data class VoiceReply(
+    val id: String,
+    val reply: String?,
+    val transcript: String?,
+    val format: String?,
+    val provider: String?,
+    val hasAudio: Boolean,
+    val file: File?,
+    /**
+     * 这一条还该不该**自动播放**（默认 true，播过就置假，见 [ChatViewModel.consumeVoiceReplyAutoPlay]）。
+     *
+     * 为什么要这一位：这一帧**只在到达时**有意义（断线不补投），而到达的那一刻用户可能正在别的
+     * 会话 / 别的页面里。若只按「音频落好了就放」来触发，等他切回来时会**突然响一段旧语音**
+     * ——那不是他刚做的事。所以自动播放只认**第一次**落好的那一下，之后靠卡片上的播放键。
+     */
+    val autoPlay: Boolean = true,
+) {
+
+    /** 能不能画「播放」那枚控件：这一轮**有**音频，而且它已经落到本机。 */
+    val playable: Boolean get() = hasAudio && file != null
+
+    /** 这一轮是不是「没有音频」（= `provider == "silent"` 或 `audio` 缺席）。 */
+    val silent: Boolean get() = !hasAudio
+}

app/src/main/kotlin/top/yeij/cyrene/ui/chat/VoiceSpeak.kt

@@ -0,0 +1,103 @@
+package top.yeij.cyrene.ui.chat
+
+import java.io.File
+import top.yeij.cyrene.domain.chat.VoicePlaybackState
+import top.yeij.cyrene.domain.chat.isActiveFor
+import top.yeij.cyrene.domain.chat.ttsClipIdOf
+
+/**
+ * 「把这一条念出来」在**本端**的那一份状态（W75，`POST /api/v1/audio/speech`）。
+ *
+ * ## 为什么它住在 VM 的状态里，而不是气泡自己的 `remember`
+ * 一次朗读要经过一段**跨组合重建**的等待（发请求、等字节、落盘）：转屏 / 滚出屏幕再滚回来
+ * 都不该让已经落好的那段音频消失，也不该让「正在准备」这件事凭空重置。所以请求发起、失败分类、
+ * 落盘结果都在 `ChatViewModel.speak` 里，气泡只是这份状态的视图。
+ *
+ * ## 一次只有一个：`ttsClip` 是**单格**
+ * 与 [VoiceReply] 同一取舍：同一时刻用户点的是**一条**消息，多留几条既占内存又没人看。
+ * 用户点了另一条 ⇒ 这一格被新的那条整个替换（旧那条的音频文件留在缓存里，下次点它命中不发请求）。
+ *
+ * ## 播放不在这一格里
+ * 「正在响 / 已经停了」由**唯一的播放通道**（`ui.chat.VoicePlayer` 的 `state`）说，键是
+ * [clipId]（`tts:<messageId>`，见 `domain.chat.ttsClipIdOf`）。这一格只负责「字节有没有到手、
+ * 上一次为什么没到手」。分成两处是必须的：播放器在响的时候这一格可以纹丝不动（它不需要知道
+ * `MediaPlayer` 走到了哪），而用户点了另一条语音副本时，播放通道换键、这一格照旧留着 —— 两件事
+ * 本来就不是一件事。
+ *
+ * @property messageId 这条朗读属于哪条消息（失败文案据此只挂在那一条下面）。
+ * @property clipId 播放通道上的键（`tts:<messageId>`）：与语音副本的键（= 它的 `messageId`）
+ *   分得开，于是「念这一条」与「放这条消息的语音副本」天然互斥（点一个停另一个）。
+ * @property file 合成音频在本机的那份 WAV；`null` = 还没到手（请求在飞，或已经失败了）。
+ * @property failure 上一次没成功时给用户看的那句话（`domain.chat.TtsFailure.message`）；
+ *   `null` = 没失败过 / 还没结果。
+ * @property retryable 再点一次**可能**有用吗（`domain.chat.TtsFailure.retryable`）。为假时图标
+ *   仍然可点 —— 但那是「重来一次」而不是「重试」，文案上不提重试（见 `TtsFailure.Unconfigured`）。
+ * @property autoPlay 这一次结果还该不该**自动起播**（默认 true，起播过就置假，见
+ *   `ChatViewModel.consumeTtsAutoPlay`）。
+ *
+ *   为什么要这一位：请求发出去之后用户可能已经切到别的会话 / 别的页面。若只按「文件到了就放」
+ *   来触发，等他切回来时会**突然响一段刚才点的朗读** —— 那不是他此刻的动作。所以自动起播只认
+ *   **第一次**落好的那一下，之后靠那枚图标。
+ */
+data class TtsClip(
+    val messageId: String,
+    val clipId: String,
+    val file: File?,
+    val failure: String?,
+    val retryable: Boolean,
+    val autoPlay: Boolean = true,
+) {
+
+    /** 请求还在飞（字节没到手、也还没有结论）：界面据此把图标画成「正在准备」。 */
+    val pending: Boolean get() = file == null && failure == null
+}
+
+/**
+ * 用户点了一下那枚朗读图标，**这一下该被当成什么**。
+ *
+ * 只有两档，因为只有两件事会发生：要么「停」，要么「（重新）念」。把它抽成纯函数是因为
+ * 判据跨了三处状态（这一格的 [TtsClip]、那条唯一播放通道的 [VoicePlaybackState]、以及
+ * `ttsClipIdOf` 铸的键），而它们谁都不该在自己的类里替对方下结论。
+ */
+sealed interface TtsSpeakIntent {
+
+    /** 这一条**正在响**，手上也有它的音频 ⇒ 这一下是「停」。 */
+    data object Stop : TtsSpeakIntent
+
+    /** 其余一切（没在响、响的是别的、失败过、缓存已命中想再听一遍）⇒ 交给 VM。 */
+    data object Speak : TtsSpeakIntent
+}
+
+/**
+ * 这一下点击是「停」还是「（重新）念」。
+ *
+ * ## 为什么必须有这条判据：否则「停止朗读」是空操作
+ * 图标在播放中画的是暂停符、读屏名字是 `TTS_STOP_DESCRIPTION`（见 `MessageBubble`），所以
+ * 用户点它时**意思是停**。但播放中 `TtsClip.pending` 是假的（文件早就到手了），于是
+ * `ChatViewModel.beginTtsSpeak` 的防抖放行、整格被换成新的 pending、缓存命中秒回、
+ * 起播 effect 又因为「已经在放同一条」而跳过 `toggleClip` —— 三处各自都「没错」，合起来就是
+ * 点了没反应。判据落在**播放通道**这一处（它是「有没有在响」的唯一真相），才不会有第二处
+ * 各自解释「播放中」是什么意思。
+ *
+ * ## 为什么要 `file != null`
+ * 「正在响」与「音频在手上」是两件事：通道处于 [VoicePlaybackState.Loading] 时它也算 active，
+ * 而那一刻 [TtsClip.file] 可能还是 `null`（字节在 VM 那边取）。那时把点击解释成「停」会停掉
+ * 一次**还没起播**的载入，而用户点它的本意是「念」——所以只有文件确实在手、通道确实在响时才判
+ * [TtsSpeakIntent.Stop]；其余一律 [TtsSpeakIntent.Speak]，由 VM 的 pending 分支去防抖。
+ *
+ * @param playback 那条唯一播放通道此刻的状态（`VoicePlayer.state`）。
+ * @param messageId 被点的那条消息。
+ * @param clip 这一条自己的朗读格（`messageId` 对不上的要当没点过，判据里再核一次）。
+ */
+fun ttsSpeakIntent(
+    playback: VoicePlaybackState,
+    messageId: String,
+    clip: TtsClip?,
+): TtsSpeakIntent {
+    val file = clip?.takeIf { it.messageId == messageId }?.file
+    return if (file != null && playback.isActiveFor(ttsClipIdOf(messageId))) {
+        TtsSpeakIntent.Stop
+    } else {
+        TtsSpeakIntent.Speak
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/ui/sessions/InactiveSessionPull.kt

@@ -1,5 +1,7 @@
 package top.yeij.cyrene.ui.sessions
 
+import top.yeij.cyrene.data.repository.MessageIncrement
+
 /**
  * 一帧 `message_persisted` 属于哪条路（[persistedRoute] 的取值）。
  *
@@ -18,11 +20,15 @@ internal enum class PersistedRoute {
 
     /**
      * **别的**会话落了新消息：它攒未读是正确行为（红点该亮），而本端**数不出这个数**
-     * （`message_persisted` 帧不带 `unreadCount`）⇒ 节流地静默重拉一次列表，问服务端要那个数。
+     * （`message_persisted` 帧不带 `unreadCount`）⇒ 节流地问服务端要。
      *
      * 这正是 W49 修的那一幕：**App 停在主会话时，次级会话来了新消息，抽屉红点不出现**。
      * 此前帧在这一档直接 `return`，而列表更新的触发点只有抽屉打开 / 新建 / 删除 / init 四处，
-     * 于是红点必须靠用户开一次抽屉（那次静默重拉）才补上。
+     * 于是红点必须靠用户开一次抽屉才补上。
+     *
+     * 「要」的是什么，W77 换过一次：原来是整表 `GET /sessions`，现在是**这条会话的消息增量**
+     * `GET /messages?after=`（见 [incrementCursors] / [applyIncrement]）；整表退回成「增量给不出
+     * 可信答案」时的回落。判据本身不受影响——这一档该不该被窗口挡住，与问的是哪种口径无关。
      */
     InactiveSession,
 }
@@ -190,3 +196,117 @@ internal fun silentRefreshStep(
  */
 internal fun throttleAfterPull(nowMillis: Long): SilentRefreshThrottle =
     SilentRefreshThrottle(lastPullAt = nowMillis)
+
+// ---------------------------------------------------------------------------------------------
+// W77：非激活会话的静默刷新，从「整表重拉 GET /sessions」换成「前向增量 GET /messages?after=」
+//
+// 后端明确批了这一换（回执二十八第 3 条：`?after=` 毫秒 `createdAt` 早就在册）。换掉的理由是**量**：
+// 整表一次要回**所有**会话（每条一行预览 + 未读计数），而这里只需要回**真的变了的那一个**会话的新消息。
+// 下面三个纯函数就是这一换的全部判据，放在这里而不是 VM 里，理由与 [silentRefreshStep] 一样：
+// 纯函数才穷举得了、才不用在 JVM 上摆一台假服务器。
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * 某个会话现在该从哪个 `createdAt` 起问增量（纯函数）；`null` = **这一行问不了**。
+ *
+ * 游标就取 [SessionItem.lastMessageAt]——最近一次权威 `GET /sessions` 给的、本端已知最新一条的
+ * `createdAt`——**不另立账本**：
+ * - 服务端的 `after` 是 `created_at > ?`（**严格**大于），而 [SessionItem.lastMessageAt] 正是
+ *   「已经见过的最新一条」⇒ 两边语义天然对齐，多立一个账本只会多一个会漂移的真相源；
+ * - 增量自己会把 [SessionItem.lastMessageAt] 推到新游标（[applyIncrement]），于是账本自洽地滚动，
+ *   不需要第二处推进。
+ *
+ * 两种「问不了」都落到 `null`，它们其实是同一件事——**本端不知道这条会话看到哪儿了**：
+ * - 行不在列表里（会话在别处新建、或本端那份列表还没拉到它）⇒ 没有游标可用；
+ * - 行在但 `lastMessageAt` 为 `null`（本端认为它一条消息都没有，却收到了它的落库广播）⇒
+ *   手里那份列表已经陈旧到不可信。
+ *
+ * 两种都由调用方回落到整表（唯一权威），见 `SessionsViewModel.flushPendingIncrements`。
+ */
+internal fun incrementCursorFor(item: SessionItem?): Long? = item?.lastMessageAt
+
+/**
+ * 一批待问增量的会话 id → 各自的 `after` 游标（纯函数）。
+ *
+ * `null` = **这批里有一个问不了**（[incrementCursorFor] 给了 `null`）⇒ 调用方**整批**回落整表。
+ * 不混着来是刻意的：一半靠增量、一半靠整表，得到的那份列表没有任何一处能说得清「它是什么时刻的」，
+ * 而未读面上最不能出的就是这种「说不清」。
+ *
+ * 返回 `emptyMap` = 这批本来就是空的（没有事要做），**不是**失败。
+ */
+internal fun incrementCursors(
+    sessionIds: Collection<String>,
+    sessions: List<SessionItem>,
+): Map<String, Long>? {
+    if (sessionIds.isEmpty()) return emptyMap()
+    val byId = sessions.associateBy { it.id }
+    val cursors = LinkedHashMap<String, Long>(sessionIds.size)
+    for (id in sessionIds) {
+        cursors[id] = incrementCursorFor(byId[id]) ?: return null
+    }
+    return cursors
+}
+
+/**
+ * 把一次增量折进列表（纯函数）：**只动那一行**，其余原样返回。
+ *
+ * ## 未读数怎么算：先过已读游标，再加
+ * 增量条数**不是**直接往角标上加的，要先按本地已知的已读游标 [readAt]（`readCursors[sessionId]`）筛一遍。
+ * **过滤口径**与服务端同源：`session_read.go` 的 `unreadCountQuery` 是 `count(created_at > read_at)`，
+ * 而 `read_at` 是**账号级单一游标**，可能比本端已知的最新消息还新——用户在这台机器上点开过它
+ * （[SessionsViewModel.select] 推的就是「现在」），随后别的设备又发了消息。那一刻
+ * `(lastMessageAt, readAt]` 之间的消息**服务端算已读**，一律加进角标就会多出来一个红点。所以只数
+ * `createdAt > readAt` 的那几条。
+ *
+ * 已有的 [SessionItem.unreadCount] 直接保留相加是安全的：它来自服务端，而这次增量里的每一条都严格新于
+ * [from]（服务端的 `after` 就是 `created_at > ?`），两者没有交集，不会重复计数。
+ *
+ * ## 已知边界：同源的只是**过滤口径**，基数仍是上次整表的旧值
+ * 相加的底数 [SessionItem.unreadCount] 来自上一次整表刷新，而 `read_at` 是账号级的、会被别的设备改写。
+ * 断线期间他端把某个会话读掉时，那条 `session_read` 帧本地**永久收不到**（断线不补帧），于是底数偏大，
+ * 这一行会一直多算那几条。这是**已接受的边界**，不是漏网：红点本来就只承诺「大概有几条新的」，漂移
+ * 到下一次整表刷新（打开抽屉 / 初始化 / 任何一次回落）就自愈。
+ *
+ * 这里**不**去检测它（例如「[readAt] > [from] ⇒ 底数可疑 ⇒ 回落整表」）：本端刚点开过这个会话时
+ * `readAt` 本来就被推到「现在」、必然大于 `lastMessageAt`，那是最常见的一档；拿它当异常信号会让增量
+ * 路径在正常使用下持续回落整表，而真正的「他端已读」它一样抓不全（断线时帧就丢了）。抓不准的闸门
+ * 不如不装。
+ *
+ * ## 并发的那一份真相
+ * [from] 不是「这次用了什么游标」的装饰：行上的 [SessionItem.lastMessageAt] **已经不等于** [from]，
+ * 就说明在这次请求飞在天上的时候，另一份更权威的结果（一次整表刷新、或另一次增量）已经推进过这一行。
+ * 那些条数已经被别人数过一遍了，再加一次就是重复计数 ⇒ 整行不动。
+ *
+ * 一行都没被改动时返回**同一个列表实例**（与 `applyBusyFrame` 同一习惯）：这条路径跑在后台，
+ * 没有必要为了「什么都没变」让整个抽屉重组一遍。
+ *
+ * @param from 这次请求用的 `after` 游标。
+ * @param readAt 本端已知的已读游标；`null` = 不知道（当作 `0`，即「一条都还没读过」）。
+ * @param increment 升序的增量（`MessageRepository.loadIncrement` 的产物）。
+ */
+internal fun List<SessionItem>.applyIncrement(
+    sessionId: String,
+    from: Long,
+    readAt: Long?,
+    increment: MessageIncrement,
+): List<SessionItem> {
+    if (increment.messages.isEmpty()) return this
+    val floor = readAt ?: 0L
+    val unseen = increment.messages.count { it.createdAt > floor }
+    // 升序 ⇒ 最后一条就是最新的一条（`loadIncrement` 保证这一点）。
+    val preview = increment.messages.last().content.toPreviewText().takeIf { it.isNotBlank() }
+    var touched = false
+    val updated = map { item ->
+        if (item.id != sessionId || item.lastMessageAt != from) {
+            item
+        } else {
+            touched = true
+            item.copy(
+                unreadCount = item.unreadCount + unseen,
+                lastMessage = preview,
+                lastMessageAt = increment.cursor,
+            )
+        }
+    }
+    return if (touched) updated else this
+}

app/src/main/kotlin/top/yeij/cyrene/ui/sessions/SessionBusy.kt

@@ -0,0 +1,88 @@
+package top.yeij.cyrene.ui.sessions
+
+import top.yeij.cyrene.data.ws.WsEvent
+
+/**
+ * 「这个会话正在跑」的本端账本（**纯逻辑**，`SessionsViewModel` 与测试共用）。
+ *
+ * 形状是 `Map<会话 id, 本端见过的、还没收到收尾帧的在途路 id>`。**空集合也是在跑**——
+ * `session_busy` 帧本身通常不带 `turnId`（它走编排器的状态通道），只凭它也知道那个会话忙。
+ *
+ * ## 只有活帧能点亮，而且绝不外推
+ * 唯二的点亮来源是 [WsEvent.SessionBusy]（服务端说它忙）与 [WsEvent.TurnBegin]（服务端刚起了
+ * 一路）：两条都是**连接着的这一刻**推下来的帧。握手**不回放**该状态（S9 登记的那一格），所以
+ * 「本端连上之后还没收到过任何一条这样的帧」= **不知道** ⇒ 抽屉里什么都不显示（宁可没有）。
+ * 也不从别的线索外推——REST 列表不带这个状态，聊天页有没有在转也不带会话归属，
+ * 拿它们当证据就等于把「本端不知道」说成「它闲着」或「它忙着」。
+ *
+ * 把 [WsEvent.TurnBegin] 也算证据，是因为它与 [WsEvent.SessionBusy] **同源**：服务端启动一路时
+ * 两条一起发（一个是状态、一个是这一路的身份）。收到它就等于服务端在那一刻确认「这个会话在跑」，
+ * 不是本端的推断——而它比 `session_busy` 更频繁（每一路都有），所以 `session_busy` 那一帧如果
+ * 因为重连错过，下一路起来时灯还能亮回来。
+ *
+ * ## 收尾：三条帧，方向都是「宁可少显示」
+ * - [WsEvent.SessionIdle]（规范 §1.5：**全部**在途路收尾且 pending 空）⇒ 无条件收掉。
+ * - [WsEvent.SessionInterrupted] ⇒ 只有 `activeTurns` 说没有别的路在跑时才收掉。`scope:"current"`
+ *   只取消在跑的那一路、别的路照跑，无条件收掉就会在并行时显示「已经停了」——那正是 v2 前端审计
+ *   记成「会错」的一条（`Cyrene_v2/DevDocs/audit/前端同步缺口-2026-10-05.md` 的 A7）。
+ *   键缺席（`null`，v0.65 之前的老服务端）⇒ 那一版还没有并行这回事，单路被打断就是真的闲了 ⇒ 收掉。
+ * - [WsEvent.TurnEnd] ⇒ 只收它**认得**的那一路（[WsEvent.TurnBegin] 记下来过），且收掉之后一路不剩
+ *   才灭灯。帧壳 `turnId` 没见过（本端中途才接上、或那一帧的键缺席）就什么都不做：拿别的一路的
+ *   收尾去灭灯，会把还在跑的那一路报成空闲。
+ *
+ * `stream_end` **刻意不参与**：它只结束某一次模型流（一轮里有多个正文段、工具循环里还有多次），
+ * 而 `turn.end` 才结束整轮。按它灭灯就是上面 A7 那类错误的另一个入口。
+ *
+ * 幂等：同一帧重复到达（重连补拉、服务端重复广播）不改变结论。
+ */
+internal fun Map<String, Set<String>>.applyBusyFrame(event: WsEvent): Map<String, Set<String>> {
+    val sessionId = event.sessionId.sessionKey() ?: return this
+    return when (event) {
+        is WsEvent.SessionBusy ->
+            this + (sessionId to this[sessionId].plusTurn(event.turnId.sessionKey()))
+
+        is WsEvent.TurnBegin ->
+            this + (sessionId to this[sessionId].plusTurn(event.turnId.sessionKey()))
+
+        is WsEvent.TurnEnd -> {
+            val turnId = event.turnId.sessionKey()
+            val tracked = this[sessionId].orEmpty()
+            if (turnId == null || turnId !in tracked) {
+                this
+            } else {
+                val left = tracked - turnId
+                if (left.isEmpty()) this - sessionId else this + (sessionId to left)
+            }
+        }
+
+        is WsEvent.SessionIdle -> this - sessionId
+
+        is WsEvent.SessionInterrupted ->
+            if ((event.activeTurns ?: 0) > 0) this else this - sessionId
+
+        else -> this
+    }
+}
+
+/**
+ * 抽屉里那一行「正在跑」的字。
+ *
+ * 与聊天页输入栏下方那一行**逐字相同**（`ChatScreen.busyLabel`）：同一类服务端帧说的是同一件事，
+ * 两处各写一句就会各自漂移。措辞不分 `mode`（`thinking` / `executing` / `subagent`）——聊天页
+ * 也只看「忙不忙」这一个事实，用户要的是「她在干活、可以停」，不是编排细节。
+ */
+internal const val SESSION_BUSY_LABEL = "正在思考…"
+
+/**
+ * 停止入口上的字。用文字而不是图标：`MiuixIcons.Basic.*` 里只有 7 个（`Close` / `Search` / …），
+ * 没有一个读作「停止」，而**猜**一个语义相近的图标（`Pause`？`Remove`？）正是本项目禁止的动作
+ * （先例：`LoginScreen` 的「显示 / 隐藏」也是在 `IconButton` 里放两个字）。
+ */
+internal const val SESSION_STOP_LABEL = "停止"
+
+/** 帧里的 id：空白 = 坏帧（不知道说的是谁）⇒ 整帧不消费，与 `SessionsViewModel.onSessionRead` 同一条口径。 */
+private fun String?.sessionKey(): String? = this?.takeIf { it.isNotBlank() }
+
+/** 把这一路记进去；`turnId` 缺席（帧壳没给）时只维持「在跑」这个事实，不记无法配对的路。 */
+private fun Set<String>?.plusTurn(turnId: String?): Set<String> =
+    if (turnId == null) orEmpty() else orEmpty() + turnId

app/src/main/kotlin/top/yeij/cyrene/ui/sessions/SessionDrawerContent.kt

@@ -62,6 +62,9 @@ import top.yukonga.miuix.kmp.theme.MiuixTheme
  *   两边签名逐字对应。
  * @param onDismissError 收起列表下方那条错误（[SessionsUiState.error]）。它不会自己消失，
  *   所以必须有个关闭入口；关掉的只是**本端已经显示的**这一条（边界见 `SessionsViewModel.dismissError`）。
+ * @param onStopGenerating 停掉这个会话正在跑的那一轮（只对 [SessionsUiState.busySessions] 里那些行
+ *   出现）。它落到的出口与「她忙时发消息 = 打断」那一档**是同一个**（见
+ *   `SessionsViewModel.stopGenerating`）。
  */
 @Composable
 fun ColumnScope.SessionDrawerContent(
@@ -71,6 +74,7 @@ fun ColumnScope.SessionDrawerContent(
     onDelete: (SessionItem) -> Unit,
     onTogglePin: (SessionItem) -> Unit,
     onRename: (String, String) -> Unit,
+    onStopGenerating: (SessionItem) -> Unit,
     onOpenIot: () -> Unit,
     onOpenAdmin: () -> Unit,
     onOpenSettings: () -> Unit,
@@ -111,11 +115,16 @@ fun ColumnScope.SessionDrawerContent(
                 // 角色名在这里回填而不是在 VM 里拼进 SessionItem：这里能拿到角色表（也就能表达
                 // 「角色表还没回来」的降级），而且 [personaLabelFor] 是一条可单测的纯函数。
                 personaLabel = personaLabelFor(session.personaId, state.personas),
+                // 「谁在跑」是**整个列表**共用的一份（`session_busy` 说的是别的会话时本端也要收下），
+                // 所以它挂在 state 上、按 id 逐行查，而不是塞进 SessionItem（那一份是 REST 快照的
+                // 投影，每次重拉都会被整表替换，塞进去反而要让重拉记得把它带回来）。
+                busy = session.id in state.busySessions,
                 active = session.id == state.activeSessionId,
                 onClick = { onSelect(session.id) },
                 onTogglePin = { onTogglePin(session) },
                 onRename = { pendingRename = session },
                 onDelete = { pendingDelete = session },
+                onStop = { onStopGenerating(session) },
             )
         }
     }
@@ -327,16 +336,22 @@ private val PERSONA_LIST_MAX_HEIGHT = 320.dp
  *
  * @param personaLabel 该会话绑定的**角色名**（[personaLabelFor] 的回填；拿不到就不显示）。
  *   它挂在摘要行前面——「这个会话是谁在答话」比最后一条消息更该先被看到。
+ * @param busy 这个会话**本端已知**正在跑（S9）。它多带来两样东西：摘要行下面那行「正在思考…」，
+ *   以及把置顶按钮换成「停止」。判据与收尾规则见 `session_busy` 那一套（`SessionsViewModel`）。
+ *   注意它**不是**「服务端此刻在跑」——握手不回放该状态，没收到过帧的会话就是 `false`（宁可没有）。
+ * @param onStop 停掉正在跑的那一轮（[SessionsViewModel.stopGenerating]）。
  */
 @Composable
 private fun SessionRow(
     session: SessionItem,
     personaLabel: String?,
+    busy: Boolean,
     active: Boolean,
     onClick: () -> Unit,
     onTogglePin: () -> Unit,
     onRename: () -> Unit,
     onDelete: () -> Unit,
+    onStop: () -> Unit,
 ) {
     val titleColor = BasicComponentDefaults.titleColor().color
     val summaryColor = BasicComponentDefaults.summaryColor().color
@@ -355,16 +370,30 @@ private fun SessionRow(
                         modifier = Modifier.padding(horizontal = 4.dp),
                     )
                 }
-                IconButton(onClick = onTogglePin) {
-                    Icon(
-                        imageVector = if (session.pinned) MiuixIcons.Unpin else MiuixIcons.Pin,
-                        contentDescription = if (session.pinned) "取消置顶" else "置顶",
-                        tint = if (session.pinned) {
-                            MiuixTheme.colorScheme.primary
-                        } else {
-                            MiuixTheme.colorScheme.onSurfaceVariantSummary
-                        },
-                    )
+                // 「停止」与置顶**同一个槽位**，不是并列的两个：上面那段注释算过，`endActions` 的
+                // 硬上限（内部可用宽度的 60%）连现有的三个 40dp 动作都快顶不住，再并一个就会把
+                // 图标挤到裁剪。正在跑的那几行里「停」比「置顶」要紧，而置顶**不丢**：这一轮结束
+                // （灯灭）它立刻回来。
+                if (busy) {
+                    IconButton(onClick = onStop) {
+                        Text(
+                            text = SESSION_STOP_LABEL,
+                            style = MiuixTheme.textStyles.footnote1,
+                            color = MiuixTheme.colorScheme.primary,
+                        )
+                    }
+                } else {
+                    IconButton(onClick = onTogglePin) {
+                        Icon(
+                            imageVector = if (session.pinned) MiuixIcons.Unpin else MiuixIcons.Pin,
+                            contentDescription = if (session.pinned) "取消置顶" else "置顶",
+                            tint = if (session.pinned) {
+                                MiuixTheme.colorScheme.primary
+                            } else {
+                                MiuixTheme.colorScheme.onSurfaceVariantSummary
+                            },
+                        )
+                    }
                 }
                 if (!session.isMain) {
                     IconButton(onClick = onDelete) {
@@ -416,6 +445,18 @@ private fun SessionRow(
                     overflow = TextOverflow.Ellipsis,
                 )
             }
+            // 第三行只给正在跑的会话。**另起一行而不是顶掉摘要**：摘要（最后一条消息）在这一刻
+            // 仍然有用——用户切走之后正是靠它认回「我刚才在哪个会话里说话」——而这一行是整行
+            // 宽度的普通文本，不需要从 `endActions` 或标题列里分走任何一个 dp。
+            if (busy) {
+                Text(
+                    text = SESSION_BUSY_LABEL,
+                    fontSize = MiuixTheme.textStyles.body2.fontSize,
+                    color = MiuixTheme.colorScheme.primary,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+            }
         }
     }
 }

app/src/main/kotlin/top/yeij/cyrene/ui/sessions/SessionsViewModel.kt

@@ -17,6 +17,7 @@ import top.yeij.cyrene.data.api.CyreneException
 import top.yeij.cyrene.data.api.dto.SessionSummaryDto
 import top.yeij.cyrene.data.ws.ChatSocket
 import top.yeij.cyrene.data.ws.WsEvent
+import top.yeij.cyrene.data.ws.WsState
 
 data class SessionItem(
     val id: String,
@@ -27,7 +28,8 @@ data class SessionItem(
     val lastMessage: String?,
     /**
      * 最后一条消息的时间戳（毫秒）；会话还没有消息时为 null。
-     * 只用于已读游标比对（见 [SessionItem.withReadCursor]），不直接显示。
+     * 两处用：已读游标比对（见 [SessionItem.withReadCursor]），以及增量追尾的 `after` 游标
+     * （见 `incrementCursorFor`，由 `applyIncrement` 推进到这次增量的 `cursor`）。不直接显示。
      */
     val lastMessageAt: Long? = null,
     /** 未读条数（服务端 `unreadCount`，D4）；`0` = 无未读、不显示角标。 */
@@ -58,6 +60,13 @@ data class SessionsUiState(
     val personasLoaded: Boolean = false,
     /** 角色目录拉取失败的原因。与会话列表的 [error] 分开：它只影响弹层里那几行，不动列表状态。 */
     val personaError: String? = null,
+    /**
+     * **本端已知正在跑**的会话 id（S9）。空 = 一个都不知道，抽屉里不显示任何「正在生成」。
+     *
+     * 它**不是**「服务端此刻在跑哪些会话」——握手不回放该状态，本端只知道**连上之后**收到过帧的
+     * 那些（判据与收尾规则见 [applyBusyFrame]）。所以它是「宁可没有」的一侧：拿不准就不显示。
+     */
+    val busySessions: Set<String> = emptySet(),
 )
 
 /**
@@ -74,9 +83,12 @@ data class SessionsUiState(
  *
  * **非激活会话攒未读**（别人发来、别的设备发来）本端**不自己数**——`message_persisted` 帧不带
  * `unreadCount`，逐条累加会与编辑 / 删除 / 别端操作漂移。本端做的是**自己去问一次服务端**：
- * 收到非激活会话的落库广播就**节流地静默重拉**（[requestSilentRefresh]，窗口
- * [SILENT_REFRESH_WINDOW_MILLIS]），于是抽屉的红点**不需要用户先开一次抽屉**就会出现
- * （S6，登记见 `devdocs/05-开发进度与交接.md`）。
+ * 收到非激活会话的落库广播就**节流地问一次那条会话的消息增量**（[requestSilentRefresh] →
+ * [flushPendingIncrements]，窗口 [SILENT_REFRESH_WINDOW_MILLIS]），于是抽屉的红点**不需要用户先开一次
+ * 抽屉**就会出现（S6，登记见 `devdocs/05-开发进度与交接.md`）。
+ *
+ * 取数走的是 `GET /messages?after=<ms>`（前向增量）而不是整表 `GET /sessions`——W77 换的，理由与回落
+ * 规则都写在 [flushPendingIncrements] 上。整表仍是**唯一权威**，只是不再需要为一条新消息付它的价钱。
  *
  * ## WS 连接：全 App 共享一条，而**本类是它唯一的主人**
  * `session_read` / `message_persisted` 都在 WS 上，这个连接就是**进程内共享**的那一条
@@ -128,6 +140,26 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
      */
     private var trailingRefreshJob: Job? = null
 
+    /**
+     * 窗口里攒下的「要问增量的会话 id」（W77）。
+     *
+     * 为什么是一个**集合**而不是一个 id：节流窗口把同一段时间里的落库广播合并成一次拉取，而那几个
+     * 会话**未必是同一个**（主会话说一句、另一个会话也说一句）。只记住最后一条的话，前面那个会话的
+     * 红点就永远不会出现——那正是 W49 修过的同一类病，只是换了个成因。
+     *
+     * 只在 [requestSilentRefresh] / [flushPendingIncrements] 两处写；登出时清空（它属于上一个身份）。
+     */
+    private val pendingIncrements = mutableSetOf<String>()
+
+    /**
+     * 「谁在跑」的账本（S9）：会话 id → 本端见过的、还没收到收尾帧的在途路 id。
+     *
+     * 与 [SessionsUiState.busySessions] 是**同一件事的两面**：这一份带配对用的路 id（`turn.end`
+     * 要靠它才知道收掉的是哪一路），推给界面的那一份只要 id 的集合。两份只在一处一起写
+     * （[onBusyFrame]），不会各自漂移。
+     */
+    private var busyTurns: Map<String, Set<String>> = emptyMap()
+
     /**
      * 手里这份列表是**为哪个身份**拉回来的（[fingerprint]）；`null` = 这份列表没有主人
      * （登出清空之后、换账号还没重拉）。
@@ -173,13 +205,22 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
                         // 「本端已知已删」也一样作废：它说的是**上一个环境**里那些 id 的结论，
                         // 换账号之后本端什么都不知道（与快照 / 已读游标同一档，见 GoneSessions 的类注释）。
                         container.goneSessions.clear()
+                        // 聊天页的槽位（W52A）同样一格不留：它们里面是上一个环境的消息列表与草稿，
+                        // 留着就是一份没人认领的常驻内存（而那一格里的 VM 还在订阅连接、还会在重连时
+                        // 补拉）。这一条把 `ChatSessionSlots` 那条「主会话永不回收」的例外也一起收干净
+                        // ——登出连主会话那一格也不留（代价：没发出去的草稿跟着没了，与上面几项同档）。
+                        container.chatSessionSlots.clear()
                         // 手里这份列表与它的节流账本都属于上一个身份，一起作废：留着账本会让
                         // 重登后那一次必要的重拉被上一轮的窗口挡住；留着补拉任务会让它带着一个
                         // 已经没有令牌的身份去发请求（必然 401，还会在抽屉里挂一行错误）。
                         trailingRefreshJob?.cancel()
                         trailingRefreshJob = null
                         silentRefreshThrottle = SilentRefreshThrottle()
+                        // 攒下的会话 id 同理：它们是上一个身份的会话，重登后那些 id 要么不存在、
+                        // 要么属于别人；留着只会让重登后的第一次窗口拿旧 id 去问增量。
+                        pendingIncrements.clear()
                         pulledForIdentity = null
+                        busyTurns = emptyMap()
                         _state.value = SessionsUiState()
                     }
 
@@ -207,6 +248,18 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
         }
         // 未读的两个下行来源都在这里收敛；见 [onEvent]。
         viewModelScope.launch { socket.events.collect(::onEvent) }
+        // 「谁在跑」只在**连接着的这段时间**里成立：握手不回放该状态，掉线期间服务端那边起了
+        // 什么、结束了什么，本端一个字节都收不到（S9 登记的那一格）。所以一离开 Connected 就当场
+        // 作废——否则一次「掉线时正好跑完」会让那盏灯**永远**亮着，而它旁边那个「停止」也永远点
+        // 不动（发出去只会撞上服务端对一个空闲会话的 no-op）：那是这个功能唯一会骗到人的地方。
+        // 代价是重连后要等下一路起来灯才回来（可能是这一轮、也可能是下一轮）——宁可没有。
+        viewModelScope.launch {
+            socket.state.collect { ws ->
+                if (ws == WsState.Connected || busyTurns.isEmpty()) return@collect
+                busyTurns = emptyMap()
+                _state.update { it.copy(busySessions = emptySet()) }
+            }
+        }
     }
 
     /**
@@ -281,42 +334,54 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
     }
 
     /**
-     * 节流地静默重拉一次列表 —— W49 修的「停在主会话时，次级会话来了新消息，抽屉红点不出现，
+     * 节流地静默对齐一次 —— W49 修的「停在主会话时，次级会话来了新消息，抽屉红点不出现，
      * 必须开一次抽屉才补上」（S6）。
      *
      * 列表此前只在抽屉打开 / 新建 / 删除 / init 四处更新，而 `message_persisted` 只处理
      * 「正在看的那个会话」—— 别的会话攒未读**没有任何人会去发现**。
      *
-     * ## 为什么是「重拉」而不是「本地把未读数加一」
-     * `message_persisted` 帧**不带 `unreadCount`**：本地没有逐条时间线，自己数出来的数会与编辑 /
+     * ## 为什么是「问服务端」而不是「本地把未读数加一」
+     * `message_persisted` 帧**不带 `unreadCount`**：本端没有逐条时间线，靠帧自己数出来的数会与编辑 /
      * 删除 / 别端操作漂移（这正是 [onMessagePersisted] 里那条纪律的由来）。所以这里**一个数都不造**，
-     * 只是把「服务端才是唯一真源」这件事提前做一次 —— 走的是**与抽屉打开时那次完全相同**的路径
-     * （[refresh]，含已读游标遮罩），只是不需要用户先开一次抽屉。
+     * 只是把「服务端才是唯一真源」这件事提前做一次。
+     *
+     * ## W77：问的是**那一条会话的增量**，不再是整表
+     * 曾经的落点是 `refresh(silent = true)`（整表 `GET /sessions`），一次要为**所有**会话付一行预览 +
+     * 未读计数的价钱，而真正变了的只有一个会话。现在落到 [flushPendingIncrements]：
+     * `GET /messages?after=<已见最大 createdAt>`，只回那几条新消息。整表仍是唯一权威，但只在
+     * 「增量给不出可信答案」时才请它出场（回落规则写在 [flushPendingIncrements] 上）。
      *
      * ## 三条纪律
      * 1. **节流**（判据 [silentRefreshStep]，窗口 [SILENT_REFRESH_WINDOW_MILLIS]）：一次连发只发一次
      *    请求；同时保证**最后一条之后还会再拉一次**（trailing），红点不会停在旧值上。
-     * 2. **静默**：`silent = true`，不闪「同步中…」——用户根本没开抽屉，不该有任何东西在动。
-     *    失败时做什么**完全沿用既有行为**（挂 [SessionsUiState.error] 那一行，只有打开抽屉才看得见；
-     *    以及「网络异常，显示 x 分钟前的结果」那一句），本方法不另加提示：一次后台的顺手对齐失败，
-     *    不该比用户自己打开抽屉时的那次刷新更吵。
-     * 3. **不抢跑**：不改 `activeSessionId`、不推进已读游标、不碰 [select]。[refresh] 内部唯一会动
-     *    `activeSessionId` 的地方是 [resolveActiveSession]（当前会话被别处删掉时收敛回主会话），
-     *    那是既有的、正确的收敛，不是重置。
+     * 2. **静默**：不闪「同步中…」——用户根本没开抽屉，不该有任何东西在动。失败时做什么**完全沿用既有
+     *    行为**（挂 [SessionsUiState.error] 那一行，只有打开抽屉才看得见；以及「网络异常，显示 x 分钟前
+     *    的结果」那一句），本方法不另加提示：一次后台的顺手对齐失败，不该比用户自己打开抽屉时的那次
+     *    刷新更吵。
+     * 3. **不抢跑**：不改 `activeSessionId`、不推进已读游标、不碰 [select]。回落那条路（[refresh]）
+     *    内部唯一会动 `activeSessionId` 的地方是 [resolveActiveSession]（当前会话被别处删掉时收敛回
+     *    主会话），那是既有的、正确的收敛，不是重置。
      *
      * @param cause 这次为什么要拉；决定它走不走窗口（见 [SilentRefreshCause]）。
+     * @param sessionId 这一帧说的是**哪个**会话；`null` = 没有具体会话（[SilentRefreshCause.ContextChanged]），
+     *   那一档只能走整表。窗口里攒下的 id 由 [pendingIncrements] 记着，因为一次窗口可能合并**几个不同**会话。
      */
-    private fun requestSilentRefresh(cause: SilentRefreshCause) {
+    private fun requestSilentRefresh(cause: SilentRefreshCause, sessionId: String? = null) {
         val step = silentRefreshStep(cause, System.currentTimeMillis(), silentRefreshThrottle)
         silentRefreshThrottle = step.throttle
+        // 没有具体会话时不留 id：那一次整表会把所有会话都对上，攒着的 id 一个也不缺。
+        if (sessionId != null) pendingIncrements += sessionId
         when (step.action) {
             // 该拉了。先把**等在半路**的那次补拉撤掉：它要做的就是同一件事，留着会多拉一次。
             // （只有 ContextChanged 压过窗口时才可能真的取消到一个活着的补拉任务——窗口外那一档
             // 走到这里时 trailingPending 必为 false，补拉早跑完了。）
+            //
+            // 撤掉补拉**不等于**可以丢掉它攒下的 id：[pendingIncrements] 是独立的一份账本，
+            // 这一趟会把它们一并做掉。
             SilentRefreshAction.PullNow -> {
                 trailingRefreshJob?.cancel()
                 trailingRefreshJob = null
-                refresh(silent = true)
+                flushPendingIncrements(fullTable = sessionId == null)
             }
 
             // 窗口内：排一次补拉。它是「最后一条之后还会再拉一次」的**唯一**保证——没有它，一串
@@ -330,15 +395,75 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
                 trailingRefreshJob = viewModelScope.launch {
                     delay(step.delayMillis)
                     silentRefreshThrottle = throttleAfterPull(System.currentTimeMillis())
-                    refresh(silent = true)
+                    flushPendingIncrements(fullTable = false)
                 }
             }
 
             // 窗口内、补拉已经排上：那一次本来就是把窗口里所有成因合起来做掉，这里不必再排。
+            // （但这一帧的会话 id 已经在上面记进 [pendingIncrements] 了 —— 补拉不会漏掉它。）
             SilentRefreshAction.Ignore -> Unit
         }
     }
 
+    /**
+     * 把 [pendingIncrements] 里攒下的会话**逐个问一次消息增量**，问不了就整批回落整表（W77）。
+     *
+     * 这就是 W49 那条「非激活会话落了新消息 ⇒ 整表重拉 `GET /sessions`」的替代品：整表一次要回
+     * **所有**会话（每条一行预览 + 未读计数），而这里只回**真的变了的那一个**会话的新消息。
+     *
+     * ## 回落的三条理由（都落到同一条路：整表）
+     * 1. **问不了增量**：[incrementCursors] 给 `null` —— 行不在列表里，或本端不知道它看到哪儿了；
+     * 2. **追不到尾**：`complete = false` —— 整个追尾里拿过整页（服务端的 `LIMIT` 切过一刀，那一刀
+     *    可能劈开了同一毫秒，而服务端只给严格 `>`，被劈开的尾巴再也追不回来；此后的空页与不满页
+     *    都说不清），或翻满了 `MessageRepository.MAX_INCREMENT_PAGES`。那时增量只覆盖了积压的一部分，
+     *    拿它当「全部」就是把红点做小；
+     * 3. **请求失败**：含会话已在别处被删掉的 `404` —— 那一档要靠整表把这一行从列表里去掉。
+     *
+     * 三条都是「增量给不出可信答案」⇒ 去问唯一权威。**一次批次最多回落一次**：整批共用这一个失败
+     * 出口，否则 N 个会话同时失败就是 N 次整表。
+     *
+     * ## 刻意不做的一件事：不写快照
+     * [refresh] 成功时会 `prefs.saveSnapshot`，这里**不写**。快照的类型是 `List<SessionSummaryDto>`
+     * （整表响应），而增量只回了消息——拿它去拼一份 DTO 列表，缺的字段（`type` / `createdAt` /
+     * `pinned` / `personaId`）只能靠猜，那等于用一个更差的东西覆盖掉一份好快照。代价是冷启动第一帧
+     * 可能显示上一次整表时的未读与预览，紧接着 `init` 里那次 `refresh()` 就会把它修正。
+     *
+     * ## 也不顺带刷角色目录
+     * [refresh] 会捎带 `loadPersonas()`，这条路径不会。角色目录的刷新点是 init / 新建 / 删除 / 抽屉
+     * 打开（那几个都是用户动作或一次性事件），「别的会话来了条消息」从来不是它的刷新时机——此前它只是
+     * 跟着整表搭了便车。W77 把便车取消，角色目录少掉的是几次没人要的请求。
+     *
+     * @param fullTable `true` = 这一趟没有具体会话（或已判明必须整表），直接走 [refresh]。
+     */
+    private fun flushPendingIncrements(fullTable: Boolean) {
+        val targets = pendingIncrements.toList()
+        pendingIncrements.clear()
+        if (fullTable) {
+            refresh(silent = true)
+            return
+        }
+        val cursors = incrementCursors(targets, _state.value.sessions)
+        if (cursors == null) {
+            refresh(silent = true)
+            return
+        }
+        // 空批次 = 没有事要做（不是失败）：不回落、也不发请求。
+        if (cursors.isEmpty()) return
+        viewModelScope.launch {
+            for ((sessionId, from) in cursors) {
+                val increment = container.messageRepository.loadIncrement(sessionId, after = from).getOrNull()
+                if (increment == null || !increment.complete) {
+                    refresh(silent = true)
+                    return@launch
+                }
+                val readAt = readCursors[sessionId]
+                _state.update {
+                    it.copy(sessions = it.sessions.applyIncrement(sessionId, from, readAt, increment))
+                }
+            }
+        }
+    }
+
     /**
      * 切换 / 进入会话。
      *
@@ -394,6 +519,14 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
                     // 记的是「本端已知」而不是「用户界面该怎么表现」：这不是要让谁弹一句告知
                     // （用户自己删的，他知道），只是让下一次补拉**事前**就判得掉。
                     container.goneSessions.mark(sessionId)
+                    // 这个会话在本端从此没有行可显示 ⇒ 「谁在跑」里那条也当场作废（留着它只会让
+                    // 账本永远不为空，而它对应的那一行早就不存在了）。
+                    forgetBusy(sessionId)
+                    // 同一件事的另一半（W52A）：把那一格**交出去**。上面那一笔只让「还活着的 VM」
+                    // 别再发补拉，而这一格本来就该跟着会话一起消失 —— 它的消息列表（含内联 base64
+                    // 图片）没有任何理由继续占着内存。两半都在这里，是因为这里是本端**唯一**的删除
+                    // 入口（别处删掉的会话只能靠 404 那一档发现，那一档的收敛在 VM 自己身上）。
+                    container.chatSessionSlots.reclaim(fingerprint(), sessionId)
                     if (_state.value.activeSessionId == sessionId) {
                         select(SessionSummaryDto.MAIN_SESSION_ID)
                     }
@@ -457,8 +590,20 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
      * 一个会话」的场景（`ChatViewModel`）用的，而本 VM 持有**整个会话列表**——按 activeSessionId
      * 过滤会把「别的会话被读了」这一帧直接丢掉，正是最该处理的一半。所以改为按帧里的会话 id
      * **逐行定位**（[applyReadCursor]，影响面严格限制在那一行）。
+     *
+     * 「谁在跑」（S9）比未读更早折一遍：[onBusyFrame] 的判据与上面的纪律**同一条**——它认的是
+     * 帧里那个会话 id，不是当前打开的那个（抽屉要回答的正是「别的会话在不在跑」）。这一折**只读**
+     * 帧、不碰下面的分支，所以两条既有路径（W49 的节流静默重拉、[persistedRoute] 的两档）语义
+     * 一个字节都没变。
+     *
+     * **通知不在这里**（W57 起）：她主动说的话那两条路（实时帧 / 带 `proactive` 的落库帧）**曾经**
+     * 在本 VM 的帧订阅里转交给 `core.notify.ProactiveNotifier`，而这份订阅挂在 `viewModelScope` 上
+     * ——从最近任务把 Activity 划掉时它就没了，进程被前台服务保活着也收不到帧。那条通路现在由
+     * **进程级**的消费点喂（`app.ProactiveFrameIntake`，与那条共享连接同一层、同寿），本类**不再
+     * 判断通知的任何一件事**：这里只剩列表自己的两件事（未读、「谁在跑」）。
      */
     private fun onEvent(event: WsEvent) {
+        onBusyFrame(event)
         when (event) {
             // 别处（Web 面板 / 别的设备 / 本端另一次请求）读了：清掉那一行的红点。
             is WsEvent.SessionRead -> onSessionRead(event)
@@ -474,6 +619,58 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
         }
     }
 
+    /**
+     * 把一帧折进「谁在跑」的账本（判据与收尾规则全在纯函数 [applyBusyFrame] 里），并只在**结论
+     * 真的变了**时推一次状态。
+     *
+     * 「变了才推」不是优化而是必需：这个函数对**每一帧**都会跑一遍，而流式那一串（`message.delta`
+     * / `thinking.delta`）是刷新率级的。无关帧在 [applyBusyFrame] 里原样返回**同一张表**，这里据此
+     * 直接返回，`_state` 因此一帧都不会被这些帧碰到。
+     */
+    private fun onBusyFrame(event: WsEvent) {
+        val next = busyTurns.applyBusyFrame(event)
+        if (next == busyTurns) return
+        busyTurns = next
+        _state.update { it.copy(busySessions = next.keys.toSet()) }
+    }
+
+    /** 本端从此不再（也不该再）关心这个会话在不在跑：它已经被删掉、本端再也没有可显示的那一行。 */
+    private fun forgetBusy(sessionId: String) {
+        if (sessionId !in busyTurns) return
+        busyTurns = busyTurns - sessionId
+        _state.update { it.copy(busySessions = busyTurns.keys.toSet()) }
+    }
+
+    /**
+     * 停掉**某一个会话**正在跑的那一轮（抽屉里那一行「停止」，W52B）。
+     *
+     * 走的是**既有的上行出口** [ChatSocket.sendInterrupt]：`interrupt{sessionId, scope}` 本来就带
+     * 会话归属（`WsOutbound.Interrupt` 的第一个参数就是它），所以「停某一个会话」既有的帧表达得了，
+     * **不需要新造帧**。
+     *
+     * ## 为什么恒发 `scope:"current"`
+     * 不读「她忙时发消息」那一档偏好：用户按的是一个**明确的动作**（停），不是「她忙时我该怎么办」
+     * 那档策略的延续。取值与 `InterruptMode.Interrupt.wireScope` 同一个，两条理由：
+     * 1. **本端从不发 `all`** 是一条既有不变式（`devdocs/02` 的 A2 补记、`devdocs/03` §4），
+     *    `dropped > 0` 那条「已打断，丢弃 N 条」的告知面在本端**不存在**；
+     * 2. `all` 会连**待处理队列**一起清掉，而队列里那些是用户自己敲进去、还没发出去的东西。
+     *    静默丢掉它们比不给这个按钮更坏。
+     *
+     * 于是这个按钮的语义是「**停掉正在跑的这一轮**」：排队中的消息照常会跑、灯随后会再亮起来——
+     * 那是实情，不是没按到。
+     *
+     * ## 刻意不在这里乐观灭灯
+     * 灯由服务端帧驱动（`session_interrupted` / `turn.end` / `session_idle`，见 [applyBusyFrame]）。
+     * 本端自己先灭，就等于替服务端宣布了一件还没发生的事；而帧一到，灯自然就灭了。
+     *
+     * 发不出去（WS 没连着）时**静默**：与 `ChatViewModel.interruptRunningTurn` 同一条纪律
+     * （那里写了三条理由）。而这一刻灯本来也不会亮——连接一断，账本当场作废（见 init 里那条订阅）。
+     */
+    fun stopGenerating(sessionId: String) {
+        if (sessionId.isBlank()) return
+        socket.sendInterrupt(sessionId, STOP_GENERATING_SCOPE)
+    }
+
     private fun onSessionRead(event: WsEvent.SessionRead) {
         if (event.sessionId.isBlank()) return
         recordReadCursor(event.sessionId, event.readAt)
@@ -487,23 +684,24 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
      * 两半共用同一条纪律：**本端哪里都不替服务端数未读**（逐条累加会与编辑 / 删除 / 别端操作漂移）。
      * 区别只在「那它靠什么显示」：
      * - [PersistedRoute.ActiveSession] ⇒ 就地清零 + 推进游标（这段一个字没改）；
-     * - [PersistedRoute.InactiveSession] ⇒ **节流地静默重拉**（[requestSilentRefresh]），
-     *   用服务端下发的 `unreadCount` 说话。这正是 W49 修的那一幕：此前这一档直接 `return`，于是
-     *   「App 停在主会话、次级会话来了新消息」没有任何人会去发现，红点要等用户打开一次抽屉（那次
-     *   静默重拉）才补上。
+     * - [PersistedRoute.InactiveSession] ⇒ **节流地问一次这条会话的消息增量**（[requestSilentRefresh]
+     *   带上 `sessionId` → [flushPendingIncrements] → `MessageRepository.loadIncrement`），未读由
+     *   「增量里越过已读游标的条数」说话（W77；W49 那一档原本整表重拉 `GET /sessions`）。
+     *   这正是 W49 修的那一幕：此前这一档直接 `return`，于是「App 停在主会话、次级会话来了新消息」
+     *   没有任何人会去发现，红点要等用户打开一次抽屉才补上。
      *
      * 两档的**载荷要求不同**，是刻意的：推游标要用消息自己的 `createdAt`（缺了就只能什么都不做），
-     * 而「重拉一次列表」不需要载荷里的任何一个字段 —— **帧壳本身就是全部证据**（服务端只为「某条
+     * 而「问一次增量」不需要载荷里的任何一个字段 —— **帧壳本身就是全部证据**（服务端只为「某条
      * 消息已在某会话落库」才推这一帧）。所以非激活那一档**不检查 `event.message`**：真遇上载荷解不出的
      * 坏帧（契约漂移的典型症状），宁可多问一次服务端，也不要让红点又停在旧值上。
      */
     private fun onMessagePersisted(event: WsEvent.MessagePersisted) {
         val sessionId = event.sessionId?.takeIf { it.isNotBlank() } ?: return
         when (persistedRoute(sessionId, _state.value.activeSessionId)) {
-            // 别的会话：本端数不出它的未读（帧不带 `unreadCount`）⇒ 节流地静默重拉一次列表，
-            // 红点于是在用户**没开抽屉**的时候也会出现。这一帧到此为止。
+            // 别的会话：本端数不出它的未读（帧不带 `unreadCount`）⇒ 节流地问一次**这条会话**的消息
+            // 增量，红点于是在用户**没开抽屉**的时候也会出现。这一帧到此为止。
             PersistedRoute.InactiveSession ->
-                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage)
+                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage, sessionId)
 
             // 屏幕上就是这个会话：就地清零 + 推进游标，**不发任何请求去拉列表**。
             // 这里用 `when` 穷举而不是「不满足上面那条就走这段」：路由将来多一档时，
@@ -527,9 +725,9 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
      * 判据也共用 [persistedRoute]（只是会话 id 由这一帧自己钉：它不带 `sessionId`）。
      *
      * 为什么必须在这里补一句：服务端的主动推送 Web 路由只发这一帧，**不补** `message_persisted`
-     * （那条只有 IM 路由会广播），所以 W49 那条「非激活会话落新消息 ⇒ 节流静默重拉」根本不会被
+     * （那条只有 IM 路由会广播），所以 W49 那条「非激活会话落新消息 ⇒ 节流刷新」根本不会被
      * 触发——抽屉里主会话的红点就停在她开口之前，直到用户自己开一次抽屉。这里复用**同一条**路
-     * （[requestSilentRefresh] + 既有的 [SilentRefreshCause.InactiveSessionMessage]），
+     * （[requestSilentRefresh] + 既有的 [SilentRefreshCause.InactiveSessionMessage]，会话 id 取主会话），
      * 不新写取数路径，也不动节流判据本身。
      *
      * `id` 缺席 = 服务端那一刻**没有落库行** ⇒ 历史里没有这一行，未读面上没有任何东西要更新
@@ -540,7 +738,7 @@ class SessionsViewModel(private val container: AppContainer) : ViewModel() {
         val sessionId = SessionSummaryDto.MAIN_SESSION_ID
         when (persistedRoute(sessionId, _state.value.activeSessionId)) {
             PersistedRoute.InactiveSession ->
-                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage)
+                requestSilentRefresh(SilentRefreshCause.InactiveSessionMessage, sessionId)
 
             // 屏幕上就是主会话：她这句话已经显示在聊天流里（ChatViewModel 那侧并入）⇒ 与
             // message_persisted 的同一档一样「看到即已读」，免得抽屉为她刚说的话亮一个红点。
@@ -612,6 +810,17 @@ internal fun unreadBadgeText(count: Int): String? = when {
 /** 角标显示的未读上限；超过就显示 `99+`。 */
 internal const val UNREAD_BADGE_MAX = 99
 
+/**
+ * 「停止」那一帧的 `scope`（见 [SessionsViewModel.stopGenerating]）。
+ *
+ * 取值必须与 `InterruptMode.Interrupt.wireScope` 一致——本端**从不发 `all`** 是一条既有不变式
+ * （`devdocs/02` 的 A2 补记、`devdocs/03` §4），而 `all` 会静默清空待处理队列。
+ * 这里写字面量而不是引用那个枚举：那边的类型是 `String?`（`Parallel` 档就是 `null`），
+ * 直接传下去会让「取值一旦被改坏」退化成「发出一条省略 scope 的帧」= 服务端眼里的 `"all"`，
+ * 而那正是最坏的方向。两处一致由 `SessionBusyTest` 钉住。
+ */
+internal const val STOP_GENERATING_SCOPE = "current"
+
 /** 整表替换（REST 快照）时，把本地已知已读的那些行压回 0 未读；见 `SessionsViewModel.readCursors`。 */
 internal fun List<SessionItem>.withReadCursors(cursors: Map<String, Long>): List<SessionItem> =
     map { item -> cursors[item.id]?.let { readAt -> item.withReadCursor(readAt) } ?: item }

app/src/main/kotlin/top/yeij/cyrene/ui/settings/KeepAliveRow.kt

@@ -0,0 +1,205 @@
+package top.yeij.cyrene.ui.settings
+
+import android.Manifest
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.provider.Settings
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.unit.dp
+import kotlinx.coroutines.launch
+import top.yeij.cyrene.core.keepalive.notificationsAllowed
+import top.yeij.cyrene.core.prefs.AppPrefs
+import top.yeij.cyrene.core.prefs.AppSettings
+import top.yeij.cyrene.ui.common.PreferenceCard
+import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
+import top.yukonga.miuix.kmp.preference.SwitchPreference
+import top.yukonga.miuix.kmp.theme.MiuixTheme
+
+/**
+ * 设置页的「后台保持连接」一行。
+ *
+ * ## 为什么单独一个文件
+ * 这一行自带状态与权限流程（授权状态、刚被拒的标记、发起申请、跳系统设置），是这块功能里唯一
+ * 会被改动的地方。`SettingsScreen.kt` 那边只留一行调用：改这里不会碰到别的行，改别的行也不会
+ * 碰到这里。
+ *
+ * ## 它只改一个偏好，**不起停服务**
+ * 起停只有一个主人（`CyreneApp` 里那个 `LaunchedEffect` + `core.keepalive.keepAliveAction`）：
+ * 这里写 `AppPrefs.keepAliveEnabled`，偏好一变，那边自己判、自己动手。两处各自 start / stop
+ * 迟早会打架（iOS/Android 都一样：能表达同一件事的地方只留一处）。
+ *
+ * ## 权限被拒时不假装成功
+ * `POST_NOTIFICATIONS` 是前台服务的**可见性**来源（minSdk 33，它是运行时权限）。被拒时本端
+ * **不打开开关**，并把原因写在开关下面：一个「开着但其实没跑」的开关比一个关着的开关更坏。
+ * 话说到「到系统设置里允许」为止还不够——用户不该自己摸进系统设置去找那一栏，所以那两档下面
+ * 直接给一个按钮，替他跳过去（见 [notificationSettingsFallback]）。
+ *
+ * @param settings 偏好写入口。
+ * @param prefs 当前偏好（开关的显示态）。
+ */
+@Composable
+internal fun KeepAliveRow(settings: AppSettings, prefs: AppPrefs) {
+    val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+
+    // 授权状态在本页内会变的只有两条路：我们刚发起的那次申请，以及我们刚把用户送去系统设置
+    // 又回来。后者靠 [openNotificationSettings] 的结果回调**直接复核**——从系统设置回来那一刻
+    // 才知道用户改成了什么，所以不需要再挂一个生命周期钩子去猜「是不是又回前台了」。
+    //
+    // ⚠️ 复核只纠正**这句话**，不改开关、也不起停服务：服务的起停判据在 `CyreneApp`，
+    // 而它的 `LaunchedEffect` 只认「开关」与「登录态」这两个键（权限是每次现读的入参）。
+    var allowed by remember { mutableStateOf(context.notificationsAllowed()) }
+    var justDenied by remember { mutableStateOf(false) }
+
+    val requestNotification = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        allowed = granted
+        justDenied = !granted
+        if (granted) scope.launch { settings.setKeepAliveEnabled(true) }
+    }
+
+    // 从系统设置回来：无论结果码是什么（那个页面一般回 RESULT_CANCELED），都现读一次真实授权。
+    val openNotificationSettings = rememberLauncherForActivityResult(
+        ActivityResultContracts.StartActivityForResult(),
+    ) {
+        allowed = context.notificationsAllowed()
+        // 刚回来时读到的就是最终答案，那句「刚刚被拒」已经过期了——留着它才是说假话。
+        justDenied = false
+    }
+
+    // 与 [keepAliveSummary] 里那两档**一一对应**：文案叫你「到系统设置里允许」，按钮就带你去
+    // 那里。这样两处不会各说各话（改了文案忘了按钮、或反过来，都会让用户觉得被耍）。
+    //
+    // 类型写全是有意的：`bottomAction` 收的是可空的可组合 lambda，写成 `if (...) null else {...}`
+    // 那种内联形状时要靠推导去猜哪一支是 `@Composable`，显式标出来省得编译器为难。
+    val settingsShortcut: (@Composable () -> Unit)? =
+        if (!allowed && (justDenied || prefs.keepAliveEnabled)) {
+            {
+                TextButton(
+                    text = "去系统设置",
+                    onClick = {
+                        // 先跳正式做法；有的 ROM 把那个页面砍了（`launch` 会抛
+                        // ActivityNotFoundException）⇒ 退到「应用详情页」，那里也有一栏「通知」。
+                        // 两次都失败就等于点了没反应，此时宁可什么都不做，也不让它崩。
+                        val direct = Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS)
+                            .putExtra(Settings.EXTRA_APP_PACKAGE, context.packageName)
+                        val launched = runCatching { openNotificationSettings.launch(direct) }.isSuccess
+                        if (!launched) {
+                            runCatching {
+                                openNotificationSettings.launch(notificationSettingsFallback(context))
+                            }
+                        }
+                    },
+                    modifier = Modifier.fillMaxWidth(),
+                )
+            }
+        } else {
+            null
+        }
+
+    KeepAliveSectionTitle()
+    PreferenceCard {
+        SwitchPreference(
+            title = "后台保持连接",
+            summary = keepAliveSummary(
+                enabled = prefs.keepAliveEnabled,
+                notificationsAllowed = allowed,
+                permissionJustDenied = justDenied,
+            ),
+            checked = prefs.keepAliveEnabled,
+            onCheckedChange = { wanted ->
+                justDenied = false
+                when {
+                    !wanted -> scope.launch { settings.setKeepAliveEnabled(false) }
+                    allowed -> scope.launch { settings.setKeepAliveEnabled(true) }
+                    // 还没授过（或授过又被撤）：按平台规范申请一次，结果由回调说话。
+                    else -> requestNotification.launch(Manifest.permission.POST_NOTIFICATIONS)
+                }
+            },
+            bottomAction = settingsShortcut,
+        )
+    }
+}
+
+/**
+ * 「去系统设置」的兜底去处。
+ *
+ * 首选是 `ACTION_APP_NOTIFICATION_SETTINGS` + `EXTRA_APP_PACKAGE`，那是 API 26 起的正式做法；
+ * 本端 minSdk 33，所以旧版那对 `"app_package"` / `"app_uid"` extra 与 API 24/25 的差异都用不着管。
+ * 剩下的一处差异不是 API 而是**厂商**：这个页面不是每个 ROM 都留着，砍了就退到这里
+ * （应用详情页，多一层才能点到「通知」）。
+ */
+private fun notificationSettingsFallback(context: Context): Intent =
+    Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
+        .setData(Uri.fromParts("package", context.packageName, null))
+
+/**
+ * 分段标题。样式与 `SettingsScreen.SectionTitle` 逐字一致：那边那个是 `private` 的，而这里要
+ * 的只是同一段样式，为此把它的可见性放宽不划算。两处将来若分叉，先动的是这个注释。
+ */
+@Composable
+private fun KeepAliveSectionTitle() {
+    Text(
+        text = "连接",
+        style = MiuixTheme.textStyles.subtitle,
+        color = MiuixTheme.colorScheme.primary,
+        modifier = Modifier.padding(start = 20.dp, top = 20.dp, bottom = 8.dp),
+    )
+}
+
+/**
+ * 开关下面那行字（**纯函数**，测试钉住）。它同时是**代价说明**与**当下真实状态**：
+ * 「关着会怎样」「开着要付出什么」「为什么没打开」——三件事都得说，且顺序上后者优先
+ * （用户刚被拒的那一次是此刻最要紧的信息）。
+ *
+ * 代价**必须自己说出来**，而且是**两份**：
+ * - 用户付的那份：一条常驻通知 + 多耗一点电。不说的代价会变成他某天「莫名其妙多了条通知」
+ *   的意外，那比不开这个功能更伤信任。
+ * - 系统收走的那份：`dataSync` 型前台服务在 targetSdk 37 下，**24 小时内累计最多 6 小时**
+ *   （`KeepAliveService.onTimeout` 到点自己收手，不硬撑到 ANR）。所以「全天候保活」做不到，
+ *   这句话不能只对他一个人藏着——一个以为买了全天候、结果 6 小时后悄悄断开的用户，
+ *   比一个从没开过这个开关的用户更亏。
+ *
+ * 因此「关 / 开」两档都带上了这条上限（[CAP_NOTE]）：关着的人要据此判断值不值得开，
+ * 开着的人要知道自己买到的到底是什么。
+ */
+internal fun keepAliveSummary(
+    enabled: Boolean,
+    notificationsAllowed: Boolean,
+    permissionJustDenied: Boolean,
+): String = when {
+    permissionJustDenied ->
+        "系统通知权限被拒绝，没能打开——前台服务没有通知就等于瞒着你常驻，本端不做这种事。到系统设置里允许 Cyrene 发送通知后再来打开"
+
+    enabled && !notificationsAllowed ->
+        "通知权限现在是关的，服务起不来：到系统设置里允许 Cyrene 发送通知后才会真的生效"
+
+    enabled ->
+        "已开：会常驻一条静默通知（不响铃、不震动），并多耗一点电；换来的是切到后台久了，实时连接也不被系统掐断。$CAP_NOTE"
+
+    else ->
+        "关：切到后台久了，系统可能冻结本进程并断开实时连接；消息不会丢（服务端已落库），回到前台会自动补上。$CAP_NOTE"
+}
+
+/**
+ * 系统给这类前台服务的额度。措辞刻意**不带情绪**：它是一个客观上限，不是遗憾——
+ * 说清了，用户才知道这开关换来的是「更久」而不是「永远」。
+ *
+ * 数字与 [top.yeij.cyrene.core.keepalive.KeepAliveService.onTimeout] 的注释同源（那边是机制，
+ * 这边是用户可见的说法）；改任何一处都得两处一起改。
+ */
+private const val CAP_NOTE = "不过系统对这种服务有上限：24 小时内累计最多 6 小时，用满会被停下"

app/src/main/kotlin/top/yeij/cyrene/ui/settings/SettingsScreen.kt

@@ -1,16 +1,23 @@
 package top.yeij.cyrene.ui.settings
 
+import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.launch
@@ -22,15 +29,18 @@ import top.yeij.cyrene.core.prefs.ThemeMode
 import top.yeij.cyrene.ui.common.PreferenceCard
 import top.yukonga.miuix.kmp.basic.BasicComponent
 import top.yukonga.miuix.kmp.basic.BasicComponentDefaults
+import top.yukonga.miuix.kmp.basic.ButtonDefaults
 import top.yukonga.miuix.kmp.basic.Icon
 import top.yukonga.miuix.kmp.basic.IconButton
 import top.yukonga.miuix.kmp.basic.Scaffold
 import top.yukonga.miuix.kmp.basic.SmallTopAppBar
 import top.yukonga.miuix.kmp.basic.Text
+import top.yukonga.miuix.kmp.basic.TextButton
 import top.yukonga.miuix.kmp.icon.MiuixIcons
 import top.yukonga.miuix.kmp.icon.extended.ChevronBackward
 import top.yukonga.miuix.kmp.icon.extended.ChevronForward
 import top.yukonga.miuix.kmp.icon.extended.Remove
+import top.yukonga.miuix.kmp.overlay.OverlayDialog
 import top.yukonga.miuix.kmp.preference.SwitchPreference
 import top.yukonga.miuix.kmp.theme.MiuixTheme
 
@@ -44,6 +54,8 @@ fun SettingsScreen(
     val prefs by container.appSettings.data.collectAsState(initial = AppPrefs())
     val scope = rememberCoroutineScope()
     val settings = container.appSettings
+    // 登出的二次确认。纯 UI 的开关，不进任何 VM：它不表达应用状态，只表达「这一次手指落在哪」。
+    var confirmLogout by remember { mutableStateOf(false) }
 
     Scaffold(
         topBar = {
@@ -102,6 +114,27 @@ fun SettingsScreen(
                 )
             }
 
+            /*
+             * 「免打扰」单独占一段，不塞进上面那个「聊天」里：它管的是**通知**（屏幕上会不会被
+             * 盖住），与「聊天页怎么渲染」是两件事。下一段「连接」也是同一个道理（那边问的是连接
+             * 会不会断）。
+             *
+             * 写法与「后台保持连接」那一行逐项对齐（`KeepAliveRow.kt`）：`SwitchPreference` 外面
+             * 必须包一层 `PreferenceCard`（Miuix 的 Preference 系列自己没有背景与圆角），副文案
+             * 走一个纯函数（好单测，见 `proactiveQuietSummary`），改开关只写偏好、**不在这里做
+             * 任何通知相关的事**——发通知时自己会现读（见 `AppSettings.current`）。
+             */
+            SectionTitle("通知")
+            PreferenceCard {
+                SwitchPreference(
+                    title = "免打扰",
+                    summary = proactiveQuietSummary(prefs.proactiveQuiet),
+                    checked = prefs.proactiveQuiet,
+                    onCheckedChange = { scope.launch { settings.setProactiveQuiet(it) } },
+                )
+            }
+            Spacer(Modifier.height(8.dp))
+
             SectionTitle("她忙时发消息")
             InterruptMode.entries.forEach { mode ->
                 PreferenceCard {
@@ -123,6 +156,8 @@ fun SettingsScreen(
                 Spacer(Modifier.height(8.dp))
             }
 
+            KeepAliveRow(settings = settings, prefs = prefs)
+
             SectionTitle("关于")
             PreferenceCard {
                 BasicComponent(
@@ -161,10 +196,51 @@ fun SettingsScreen(
                             tint = MiuixTheme.colorScheme.error,
                         )
                     },
-                    onClick = onLogout,
+                    onClick = { confirmLogout = true },
                 )
             }
             Spacer(Modifier.height(32.dp))
+
+            /*
+             * 退出登录的确认框。
+             *
+             * 为什么非要有：这一条是**整行可点**，而它紧挨着上面那条「版本」——两条长得一样、
+             * 只差一行，误触的代价却是一次真登出（`AuthManager.logout` 会吊销服务端 refresh
+             * 并把本机凭据整份清掉，没有「撤销」）。一行可点的危险动作，必须再问一次。
+             *
+             * 用的是 Miuix 自己的 `OverlayDialog`（`top.yukonga.miuix.kmp.overlay`）：它由
+             * 本页 `Scaffold` 自带的 `MiuixPopupHost` 承载，标题 / 说明 / 内容分槽。注意 Miuix
+             * 没有 `extra.*` 包（0.9.x 里对话框就在 `overlay` / `window` 两处），别照旧版本的
+             * import 去猜。
+             *
+             * 三处出口刻意一致：取消按钮、点框外、系统返回键全都只是关掉这个框，一个字都不改；
+             * 只有「退出登录」这一条路通向 [onLogout]——行为链路与加这个框之前一模一样。
+             */
+            OverlayDialog(
+                show = confirmLogout,
+                title = "退出登录？",
+                // 如实说清代价（服务器地址也要重填）：登出后回到登录页，那儿是空的。
+                summary = "退出后本机会清空登录信息（服务器地址也要重填），需要重新登录",
+                onDismissRequest = { confirmLogout = false },
+            ) {
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.End,
+                ) {
+                    TextButton(text = "取消", onClick = { confirmLogout = false })
+                    Spacer(Modifier.width(8.dp))
+                    TextButton(
+                        text = "退出登录",
+                        onClick = {
+                            // 先把框收掉再登出：登出会把整个设置页（连同这个框的 remember）从
+                            // 组合里摘掉，留着它等于把一次「正在关闭」的动画交给一个正在消失的宿主。
+                            confirmLogout = false
+                            onLogout()
+                        },
+                        colors = ButtonDefaults.textButtonColorsPrimary(),
+                    )
+                }
+            }
         }
     }
 }
@@ -206,3 +282,19 @@ private fun InterruptMode.summary(): String = when (this) {
     InterruptMode.Parallel ->
         "她正忙时不打断当前这一句，另起一路同时处理这条；两路各算一遍，会多花一份算力与 token"
 }
+
+/**
+ * 「免打扰」开关下面那行字（**纯函数**，测试钉住）。它要说清的只有一件事：
+ * **这不是静音** —— 关掉的是横幅，不是消息、也不是提示音。
+ *
+ * 为什么非说不可：「免打扰」四个字在系统里到处都是，用户对它的第一印象常是「什么都不响」。而这个
+ * 开关实际做的是「她的话照旧响一声、躺在通知栏里，只是不再盖住我正在做的事」——两句话指向的期待
+ * 差得很远，一句不说就等于让用户自己猜（猜错的代价是他以为通知坏了，或以为自己买到了完全静音）。
+ *
+ * 两档都说出**当下会怎么弹**：用户据以决定的就是「现在这样够不够吵」，而只写「开着 = 安静」
+ * 等于让他自己去比较两种安静。
+ */
+internal fun proactiveQuietSummary(enabled: Boolean): String = when {
+    enabled -> "已开：她主动找你说话只在通知栏提示（有提示音），不在屏幕顶部弹横幅"
+    else -> "关（默认）：她主动找你说话会在屏幕顶部弹横幅，同时有提示音与通知栏条目"
+}

app/src/test/kotlin/top/yeij/cyrene/app/ProactiveFrameIntakeTest.kt

@@ -0,0 +1,182 @@
+package top.yeij.cyrene.app
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Test
+import top.yeij.cyrene.core.notify.AppPresence
+import top.yeij.cyrene.core.notify.ProactiveNotifier
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
+import top.yeij.cyrene.data.ws.WsEvent
+
+/**
+ * 「她主动说的话」在**帧这一层**的消费点（W57）。
+ *
+ * 这里钉的是**接线**，不是判据（判据与去重仍在 `ProactiveNotifierTest`）：
+ * 1. **它不需要任何 Activity 活着就能收帧**——改前那份订阅挂在 `SessionsViewModel` 的
+ *    `viewModelScope` 上，从最近任务划掉 Activity 就没了，而 `ChatSocket.events` 是 `replay = 0`
+ *    的 `SharedFlow` ⇒ 没有订阅者的帧**当场丢掉**。本类的第一条测试就是那个 bug 的现场；
+ * 2. 哪些帧算「她主动说的话」、四个入参各取帧上的哪个键（[proactiveFrameOf]）——错在这两个方向
+ *    都是静默的（她开口了却不弹、普通消息也弹），所以逐键钉住；
+ * 3. 判据与去重在新的消费点上**没有被放松**：两条路仍只弹一次、看着主会话仍不弹、别的会话仍不弹。
+ *
+ * 收集用的调度器传 `Dispatchers.Unconfined`：`launch` 与 `tryEmit` 都在当前线程上把 collect 体
+ * 走完，于是测试是同步的（不需要等、也不需要 `runBlocking`）。
+ * **测不了的**：真·进程存活（Activity 没了而进程还在）这件事只有真机能造，本层只能钉住「订阅不挂
+ * 在任何会随 UI 结束的 scope 上」这个可测的部分。
+ */
+class ProactiveFrameIntakeTest {
+
+    private val presence = AppPresence()
+    private val posted = mutableListOf<String>()
+
+    /** 与 `ChatSocket` 同一档的订阅方式：无 replay、有缓冲、溢出丢最旧。 */
+    private val events = MutableSharedFlow<WsEvent>(
+        replay = 0,
+        extraBufferCapacity = EVENT_BUFFER,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST,
+    )
+
+    /** 真实的帧（键名与类型都对服务端）：实时帧带落库行 `id` + IM 号 + RFC3339 时间戳。 */
+    private val liveJson = """
+        {"type":"proactive_message","data":{"platform":"cyrene-backthink","channelId":"chan-1","channelType":"private","content":"记得喝水哦","contentType":"text","sender":"Cyrene","timestamp":"2026-10-06T01:20:05.123+08:00","messageId":"im-7","id":"1371","createdAt":1791212405123}}
+    """.trimIndent()
+
+    /** 同一条消息的另一条路：IM 桥那条路由补发的落库帧（判据键在载荷里）。 */
+    private val persistedProactiveJson = """
+        {"type":"message_persisted","sessionId":"web","data":{"proactive":true,"message":{"id":"1371","sessionId":"web","role":"assistant","content":"记得喝水哦","createdAt":1791212405123}}}
+    """.trimIndent()
+
+    /** 普通消息的落库广播（她正常回话）：**不是**她主动说的话。 */
+    private val ordinaryPersistedJson = """
+        {"type":"message_persisted","sessionId":"web","data":{"message":{"id":"1372","sessionId":"web","role":"assistant","content":"在的","createdAt":1791212405123}}}
+    """.trimIndent()
+
+    /** 她主动说的、但不属主会话：绝不弹（宁可漏，也不要把别处的消息说成是她在找我说话）。 */
+    private val liveJsonForAnotherSession = """
+        {"type":"proactive_message","sessionId":"sess-abc","data":{"content":"在吗","messageId":"im-9","id":"1373"}}
+    """.trimIndent()
+
+    private fun intake() = ProactiveFrameIntake(
+        events = events,
+        notifier = ProactiveNotifier(presence = presence, post = { text, _ -> posted += text }),
+        dispatcher = Dispatchers.Unconfined,
+    )
+
+    private fun parse(json: String): WsEvent = requireNotNull(WsEvent.parse(json)) { "帧本身要能成形" }
+
+    // —— 这一档就是那个 bug 的现场 ——
+
+    @Test
+    fun `her words still notify when no activity is alive`() {
+        // Activity 已经从最近任务里划掉（没有任何实例在 started 档、聊天页也不在），进程被
+        // KeepAliveService 撑着、连接照旧在收帧。改前这里是空的：订阅随 VM 一起没了。
+        assertFalse("这一档的前提就是前台没有任何 Activity", presence.appInForeground)
+        intake()
+
+        events.tryEmit(parse(liveJson))
+
+        assertEquals(listOf("记得喝水哦"), posted)
+    }
+
+    @Test
+    fun `the notification id comes from the notifier not from this layer`() {
+        // 号必须按消息派生（同一条 ⇒ 同一个号、不同的句子各占一条）。这一层只转交帧，不许自己
+        // 造号——这里用一个把号也记下来的假 post 确认它拿到的确实是「按消息派生」的那个值。
+        val ids = mutableListOf<Int>()
+        ProactiveFrameIntake(
+            events = events,
+            notifier = ProactiveNotifier(presence = presence, post = { _, id -> ids += id }),
+            dispatcher = Dispatchers.Unconfined,
+        )
+
+        events.tryEmit(parse(liveJson))
+        events.tryEmit(parse(ordinaryPersistedJson))
+
+        assertEquals(1, ids.size)
+    }
+
+    // —— 判据与去重在新的消费点上没有被放松 ——
+
+    @Test
+    fun `the live frame and the persisted frame of one message notify once`() {
+        intake()
+
+        events.tryEmit(parse(liveJson))
+        // 同一条的落库帧（另一条路）：认得出是同一条 ⇒ 不再弹。
+        events.tryEmit(parse(persistedProactiveJson))
+
+        assertEquals(listOf("记得喝水哦"), posted)
+    }
+
+    @Test
+    fun `a frame that lands on screen while the main session is open does not notify`() {
+        // 用户正看着她说话的那个会话：话就出现在他眼前，不打扰（判据本身在 ProactiveNotify.kt）。
+        presence.onActivityStarted(Any())
+        presence.onChatSurface(SessionSummaryDto.MAIN_SESSION_ID)
+        intake()
+
+        events.tryEmit(parse(liveJson))
+
+        assertEquals(emptyList<String>(), posted)
+    }
+
+    @Test
+    fun `a frame for another session never notifies`() {
+        intake()
+
+        events.tryEmit(parse(liveJsonForAnotherSession))
+
+        assertEquals(emptyList<String>(), posted)
+    }
+
+    @Test
+    fun `an ordinary persisted frame never notifies`() {
+        intake()
+
+        events.tryEmit(parse(ordinaryPersistedJson))
+
+        assertEquals(emptyList<String>(), posted)
+    }
+
+    // —— 哪些帧算她的话、四个入参各取自帧上的哪里 ——
+
+    @Test
+    fun `only the two proactive shapes are frames of her words`() {
+        assertNull("普通落库广播不是", proactiveFrameOf(parse(ordinaryPersistedJson)))
+        assertNull("流式增量不是", proactiveFrameOf(WsEvent.MessageDelta(delta = "在的", index = 0)))
+        assertNull("开始帧不是", proactiveFrameOf(WsEvent.MessageStart(index = 0)))
+    }
+
+    @Test
+    fun `the live frame takes the history row id and the im id apart`() {
+        val frame = requireNotNull(proactiveFrameOf(parse(liveJson)))
+
+        // 帧壳不带会话归属 ⇒「无法判定」，由「她主动说的话落主会话」这条事实兜住（见 ProactiveNotifier）。
+        assertNull(frame.sessionId)
+        assertEquals("1371", frame.id)
+        assertEquals("im-7", frame.messageId)
+        assertEquals("2026-10-06T01:20:05.123+08:00", frame.timestamp)
+        assertEquals("记得喝水哦", frame.content)
+    }
+
+    @Test
+    fun `the persisted frame has only the row id and never invents the other two`() {
+        val frame = requireNotNull(proactiveFrameOf(parse(persistedProactiveJson)))
+
+        assertEquals(SessionSummaryDto.MAIN_SESSION_ID, frame.sessionId)
+        assertEquals("1371", frame.id)
+        // 帧上就没有这两个键。编一个出来（比如把 `id` 也当 IM 号）就是伪造服务端键，去重会跟着漂。
+        assertNull(frame.messageId)
+        assertNull(frame.timestamp)
+        assertEquals("记得喝水哦", frame.content)
+    }
+
+    private companion object {
+        /** 与 `ChatSocket.EVENT_BUFFER` 同档：订阅方不设上限、发射方不阻塞。 */
+        const val EVENT_BUFFER = 8
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/app/ProactiveTapIntakeTest.kt

@@ -0,0 +1,56 @@
+package top.yeij.cyrene.app
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 「点通知进来要看主会话」那笔待落地的意图（W53N）。
+ *
+ * 这里**刻意不测** [ProactiveTapIntake.accept]（它要 `android.content.Intent`，单元测试里没有
+ * 真实现）——那条判断只有一条 extra 的字面量比较，而真正会出错的是这一半：**记账与消费的时机**
+ * （记账必须在通知被点的那一刻就发生，消费必须只发生一次、且只在真的落地之后）。
+ */
+class ProactiveTapIntakeTest {
+
+    @Test
+    fun `nothing is requested before a tap`() {
+        assertFalse(ProactiveTapIntake().openMainSession.value)
+    }
+
+    @Test
+    fun `a request survives until it is consumed`() {
+        // 通知可能在 App 还没起来、甚至还没登录时就被点：意图必须留着，等 ChatHomeScreen 能落地
+        // 的那一刻再来取（它一旦被丢掉，用户点了通知却什么都没发生）。
+        val intake = ProactiveTapIntake()
+
+        intake.requestMainSession()
+
+        assertTrue(intake.openMainSession.value)
+    }
+
+    @Test
+    fun `consuming clears it exactly once`() {
+        val intake = ProactiveTapIntake()
+        intake.requestMainSession()
+
+        intake.consume()
+
+        assertFalse(intake.openMainSession.value)
+        // 再消费一次也不该把「已经取走了」翻回成「还欠着」（它是个纯写入，没有副作用）。
+        intake.consume()
+        assertFalse(intake.openMainSession.value)
+    }
+
+    @Test
+    fun `a new tap after a consumed one is taken again`() {
+        // 第二次点通知必须照样生效：消费清的只是「这一笔」，不是把整个入口关掉。
+        val intake = ProactiveTapIntake()
+        intake.requestMainSession()
+        intake.consume()
+
+        intake.requestMainSession()
+
+        assertTrue(intake.openMainSession.value)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/app/ShareTextExtrasTest.kt

@@ -0,0 +1,143 @@
+package top.yeij.cyrene.app
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.domain.share.ShareRules
+import top.yeij.cyrene.domain.share.ShareTextSource
+
+/**
+ * 三个文本 extra（`EXTRA_TEXT` / `EXTRA_SUBJECT` / `EXTRA_TITLE`）**原始值**的读取
+ * （[shareTextExtrasOf]）。
+ *
+ * ## 为什么值得单测
+ * 这一层只有两件事要做，而两件都容易错：
+ *
+ * 1. **按形态读**（`as? CharSequence`）：真实分享里这几段常是 `Spanned`（富文本），按 `String` 读会
+ *    直接拿到 `null` —— 那正是「分享进来什么都没发生」的来处之一。而「读不出类型」（值是个数字、
+ *    别种 `Parcelable`……）时本端**不猜**：那一站读不到就是读不到，交给下一站。
+ * 2. **「里面躺着值」要如实报上去**（[ShareTextExtras.present]）：值与正文是两件事。空白值、读不出
+ *    类型的值都算「对方给了这个字段」，于是三个 extra 一起落空时本端会走「读不进来」那条如实告知，
+ *    而不是静默（判据见 `ShareRules.extract` 的 `textPresent`）。
+ *
+ * ⚠️ 这里**不**覆盖 `Bundle.getCharSequence` 到底抛不抛异常：那要真安卓运行时（JVM 单测里 android.jar
+ * 的桩方法一调就抛 `Stub!`）。结论与出处写在 `ShareIntake.kt` 的 `rawExtra` / [ShareTextExtras] 的
+ * KDoc 里（核的是 AOSP 的 `android/os/BaseBundle.java`：类型不符它自己 catch 掉回 `null`，会抛的是
+ * `unparcel()` 的 `BadParcelableException`，那一路由 `runCatching` 挡住）。
+ */
+class ShareTextExtrasTest {
+
+    @Test
+    fun `a plain string text is read through`() {
+        val extras = shareTextExtrasOf(text = "正文", subject = null, title = null)
+
+        assertEquals("正文", extras.text)
+        assertNull(extras.subject)
+        assertNull(extras.title)
+        assertTrue(extras.present)
+    }
+
+    @Test
+    fun `a spanned like char sequence is read through`() {
+        // 分享链路里的 `EXTRA_TEXT` 常常是 `Spanned`（带样式的 HTML 富文本）：它**不是** String，
+        // 按 String 读会直接拿到 null。（JVM 单测造不出 `android.text.Spanned`，用另一个
+        // `CharSequence` 实现把这条读法钉住。）
+        val raw: Any = StringBuilder("来自网页的一段富文本")
+
+        val extras = shareTextExtrasOf(text = raw, subject = null, title = null)
+
+        assertEquals("来自网页的一段富文本", extras.text)
+        assertTrue(extras.present)
+    }
+
+    @Test
+    fun `a value we cannot read as a char sequence yields no body but is still a value`() {
+        // 形态读不出来（这里是数字，真实世界是别种 Parcelable）：本端不猜它是什么意思 —— 但也不许
+        // 因此把整次分享当成「什么都没发生」，所以它照样算「里面躺着值」。
+        val extras = shareTextExtrasOf(text = 42, subject = null, title = null)
+
+        assertNull(extras.text)
+        assertTrue(extras.present)
+    }
+
+    @Test
+    fun `a blank value is still a value`() {
+        // 空白也算「对方给了这个字段」：`EXTRA_STREAM` 那边早就是这个口径（原始值非 null 即
+        // `streamPresent`），两个 extra 用同一条判据才不会出现「流的空值说话、文本的空值闭嘴」。
+        val extras = shareTextExtrasOf(text = "   ", subject = "", title = null)
+
+        assertEquals("   ", extras.text)
+        assertEquals("", extras.subject)
+        assertTrue(extras.present)
+    }
+
+    @Test
+    fun `an absent trio yields nothing and is not a value`() {
+        // 「连值都没有」才是真的没有：这条边界撑着「用户确实什么都没分享 ⇒ 一个字都不说」。
+        val extras = shareTextExtrasOf(text = null, subject = null, title = null)
+
+        assertNull(extras.text)
+        assertNull(extras.subject)
+        assertNull(extras.title)
+        assertFalse(extras.present)
+    }
+
+    @Test
+    fun `a subject only pair of raw values lands as the body`() {
+        // 端到端那一步：读出来的三段交给纯函数之后，只有 SUBJECT 的那次分享真的变成了正文，
+        // 并且来源如实记着。
+        val extras = shareTextExtrasOf(text = null, subject = "对方只给了标题", title = null)
+
+        val share = ShareRules.extract(
+            action = ShareRules.ACTION_SEND,
+            text = extras.text,
+            subject = extras.subject,
+            title = extras.title,
+            textPresent = extras.present,
+        )
+
+        assertEquals("对方只给了标题", share.text)
+        assertEquals(ShareTextSource.Subject, share.textSource)
+        assertTrue(share.worthDelivering)
+        assertFalse(share.contentUnreadable)
+    }
+
+    @Test
+    fun `raw values that are all unusable speak instead of vanishing`() {
+        // 三个 extra 里躺着值、而一段正文都没读出来：内容照旧为「空」，但**必须**有话可说 ——
+        // 这是本次要修的另一种静默（此前只有 `EXTRA_TEXT` 那一路，后两个 extra 落空时全静默）。
+        val extras = shareTextExtrasOf(text = 42, subject = "  ", title = null)
+
+        val share = ShareRules.extract(
+            action = ShareRules.ACTION_SEND,
+            text = extras.text,
+            subject = extras.subject,
+            title = extras.title,
+            textPresent = extras.present,
+        )
+
+        assertTrue(share.isEmpty)
+        assertTrue(share.contentUnreadable)
+        assertTrue(share.worthDelivering)
+    }
+
+    @Test
+    fun `nothing at all in the bundle is not a value`() {
+        // 与上一条成对：`ShareIntake` 拿到的原始值全是 null（误触分享、Intent 里什么都没有）时，
+        // 本端一个字都不说 —— 边界不许因为这批改动而放宽。
+        val extras = shareTextExtrasOf(text = null, subject = null, title = null)
+
+        val share = ShareRules.extract(
+            action = ShareRules.ACTION_SEND,
+            text = extras.text,
+            subject = extras.subject,
+            title = extras.title,
+            textPresent = extras.present,
+        )
+
+        assertFalse(share.worthDelivering)
+        assertFalse(share.contentUnreadable)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/keepalive/KeepAliveNotificationTest.kt

@@ -0,0 +1,32 @@
+package top.yeij.cyrene.core.keepalive
+
+import android.app.NotificationManager
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 常驻通知的**对外形状**（渠道 id / 重要级）。文案与图标测不了（要 Android 运行时），
+ * 但这两项能测，而且测它们是有意义的：
+ *
+ * - 重要级**建渠道那一刻就定死**了（应用改不动，只有用户能改）。它要是被写成 DEFAULT / HIGH，
+ *   这个「保活」功能就会开始响铃、震动、弹横幅——那不是保活，是骚扰，用户只能自己去关掉那条渠道。
+ * - 渠道 id 是用户静音设置的挂靠点：改了它等于换一条新渠道，用户之前对旧渠道的一切设置失效。
+ */
+class KeepAliveNotificationTest {
+
+    @Test
+    fun `the channel never rings or vibrates`() {
+        assertTrue(
+            "渠道重要级只许是 MIN / LOW，现在是 $KEEP_ALIVE_CHANNEL_IMPORTANCE",
+            KEEP_ALIVE_CHANNEL_IMPORTANCE == NotificationManager.IMPORTANCE_MIN ||
+                KEEP_ALIVE_CHANNEL_IMPORTANCE == NotificationManager.IMPORTANCE_LOW,
+        )
+    }
+
+    @Test
+    fun `the channel id is a stable literal`() {
+        // 恒定不变是刻意的：换 id = 换渠道 = 用户对旧渠道做的静音设置全部作废。
+        assertEquals("keep_alive", KEEP_ALIVE_CHANNEL_ID)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/keepalive/KeepAlivePolicyTest.kt

@@ -0,0 +1,93 @@
+package top.yeij.cyrene.core.keepalive
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.core.prefs.AppPrefs
+
+/**
+ * 「后台保持连接」的判据（纯函数）。
+ *
+ * 钉的是四件事：
+ * 1. **默认关**——这个功能会常驻一条通知、多耗电，主人拍板默认关，任何人把它改成默认开都是一次
+ *    产品决定，不该悄悄发生；
+ * 2. 三个条件缺一不可（开关 / 登录态 / 通知权限），任何一条不成立都不许跑；
+ * 3. 几种状态各自该走哪一步（登出一定停、关开关一定停、**自举中一定不动**）；
+ * 4. 四个入参的**全表 16 格**都与判据一致——尤其是「登录态未定 ⇒ 不动」这一条，写成穷举才排除得掉
+ *    「某个组合下热启动会把还跑着的服务收掉」这种走神。
+ */
+class KeepAlivePolicyTest {
+
+    @Test
+    fun `the feature is off until the user turns it on`() {
+        assertFalse("默认必须是关", AppPrefs().keepAliveEnabled)
+    }
+
+    @Test
+    fun `all three conditions are required`() {
+        assertFalse(shouldKeepAliveRun(enabled = false, loggedIn = true, notificationsAllowed = true))
+        assertFalse(shouldKeepAliveRun(enabled = true, loggedIn = false, notificationsAllowed = true))
+        assertFalse(shouldKeepAliveRun(enabled = true, loggedIn = true, notificationsAllowed = false))
+        assertTrue(shouldKeepAliveRun(enabled = true, loggedIn = true, notificationsAllowed = true))
+    }
+
+    @Test
+    fun `logging out stops the service even though the switch stays on`() {
+        // 登出只关连接，不改开关（AppSettings 是 App 级的，不随登出清空）——所以这里必须由判据
+        // 自己把服务收掉，不能指望开关被重置。
+        assertEquals(
+            KeepAliveAction.Stop,
+            keepAliveAction(enabled = true, sessionKnown = true, loggedIn = false, notificationsAllowed = true),
+        )
+    }
+
+    @Test
+    fun `an enabled switch with an undecided session is left alone`() {
+        // 热启动（Activity 重建、进程还活着）时自举会先经过 Unknown：这一刻把还跑着的服务收掉，
+        // 用户会看到通知消失又回来，而中间那段进程正好没人保护。
+        for (loggedIn in listOf(true, false)) {
+            for (allowed in listOf(true, false)) {
+                assertEquals(
+                    "登录态未定（sessionKnown=false）时不许动手：loggedIn=$loggedIn allowed=$allowed",
+                    KeepAliveAction.Leave,
+                    keepAliveAction(enabled = true, sessionKnown = false, loggedIn = loggedIn, notificationsAllowed = allowed),
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `switching off stops the service without waiting for a session`() {
+        assertEquals(
+            KeepAliveAction.Stop,
+            keepAliveAction(enabled = false, sessionKnown = false, loggedIn = false, notificationsAllowed = true),
+        )
+    }
+
+    @Test
+    fun `every combination of the four inputs agrees with the judgement`() {
+        val bools = listOf(true, false)
+        for (enabled in bools) {
+            for (known in bools) {
+                for (loggedIn in bools) {
+                    for (allowed in bools) {
+                        val wanted = known && shouldKeepAliveRun(enabled, loggedIn, allowed)
+                        val expected = when {
+                            wanted -> KeepAliveAction.Start
+                            // 唯一「不许有主张」的一格：开关开着，但登录态还没定。
+                            enabled && !known -> KeepAliveAction.Leave
+                            else -> KeepAliveAction.Stop
+                        }
+
+                        assertEquals(
+                            "enabled=$enabled known=$known loggedIn=$loggedIn allowed=$allowed",
+                            expected,
+                            keepAliveAction(enabled, known, loggedIn, allowed),
+                        )
+                    }
+                }
+            }
+        }
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/notify/AppPresenceTest.kt

@@ -0,0 +1,98 @@
+package top.yeij.cyrene.core.notify
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 「App 在不在前台」这个事实的记账（W53N）。
+ *
+ * 为什么值得单测：它最容易做成一个布尔量，而布尔量在**配置变更**上必然出错——旋转 / 系统深浅色
+ * 切换时，**新实例的 `onStart` 先于旧实例的 `onStop`**。记成布尔量的话，用户正看着聊天页，
+ * 她一句话却会弹出一条通知来。下面第二条就是这一幕。
+ */
+class AppPresenceTest {
+
+    private val presence = AppPresence()
+
+    private class Screen
+
+    @Test
+    fun `a process with no started activity is not in the foreground`() {
+        assertFalse(presence.appInForeground)
+    }
+
+    @Test
+    fun `a config change keeps the app in the foreground`() {
+        val old = Screen()
+        val new = Screen()
+        presence.onActivityStarted(old)
+
+        // 旋转：新实例先起来，旧实例之后才停。
+        presence.onActivityStarted(new)
+        presence.onActivityStopped(old)
+
+        assertTrue("新实例还活着，就不算后台", presence.appInForeground)
+    }
+
+    @Test
+    fun `two activities keep it in the foreground until the last one stops`() {
+        val first = Screen()
+        val second = Screen()
+        presence.onActivityStarted(first)
+        presence.onActivityStarted(second)
+
+        presence.onActivityStopped(first)
+        assertTrue("还有一屏在被看", presence.appInForeground)
+
+        presence.onActivityStopped(second)
+        assertFalse(presence.appInForeground)
+    }
+
+    @Test
+    fun `a stop from an activity that never started does not flip anything`() {
+        // 「只删自己那一行」的等价纪律：登出 / 销毁路径上多报一次 stop 不该把别人算掉。
+        val alive = Screen()
+        presence.onActivityStarted(alive)
+
+        presence.onActivityStopped(Screen())
+
+        assertTrue(presence.appInForeground)
+    }
+
+    @Test
+    fun `the chat surface reports the session it shows, verbatim`() {
+        presence.onChatSurface("web")
+
+        assertTrue(presence.isShowingChatSurface("web"))
+        // 主会话 `web` 与次级会话 `web:xxx` 是两个会话：等值比较，不是前缀。
+        presence.onChatSurface("web:7f3a")
+        assertFalse(presence.isShowingChatSurface("web"))
+        assertTrue(presence.isShowingChatSurface("web:7f3a"))
+    }
+
+    @Test
+    fun `leaving the chat page shows no session at all`() {
+        presence.onChatSurface("web")
+
+        presence.onChatSurface(null)
+
+        assertFalse(presence.isShowingChatSurface("web"))
+    }
+
+    @Test
+    fun `a blank session id is never being shown`() {
+        // 「没显示任何会话」与「显示了一个空 id 的会话」不是同一件事——空 id 不是任何会话的键。
+        presence.onChatSurface("")
+
+        assertFalse(presence.isShowingChatSurface(""))
+    }
+
+    @Test
+    fun `the chat surface fact does not imply the foreground fact`() {
+        // 两件事各报各的：Android 上 App 退到后台时组合并不会销毁，聊天页那一半会原样留着。
+        presence.onChatSurface("web")
+
+        assertFalse("没有 Activity 在可见档，就是后台", presence.appInForeground)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/notify/ProactiveNotifierTest.kt

@@ -0,0 +1,322 @@
+package top.yeij.cyrene.core.notify
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.data.api.dto.SessionSummaryDto
+
+/**
+ * 通知通路的整体判据（W53N）：**去重**与「什么时候弹」。
+ *
+ * 这里钉的都是**错了就肉眼可见**的边界：
+ * 1. 同一条消息走两条路（实时帧带落库行 `id`、落库帧带同一个 `message.id`）——**只许弹一次**；
+ * 2. 普通消息（不带 `proactive`）根本到不了这里，到了也不该弹（见 `WsEventPersistedProactiveTest`）；
+ * 3. 后台 + 聊天页仍挂着主会话那一档**要弹**（Android 上真实存在）；
+ * 4. 不在主会话的帧绝不弹。
+ */
+class ProactiveNotifierTest {
+
+    private val presence = AppPresence()
+    private val posted = mutableListOf<String>()
+    private val notifier = ProactiveNotifier(presence = presence, post = { text, _ -> posted += text })
+
+    /** 一个「Activity 实例」（身份即语义，见 [AppPresence]）。 */
+    private val screen = Any()
+
+    /** 后台、聊天页不在（最常见的「她说了句话」）：这一档必须弹。 */
+    private fun background() {
+        presence.onChatSurface(null)
+    }
+
+    /** 前台、正看着主会话：她的话出现在屏幕上，不该再有通知。 */
+    private fun onMainSessionInForeground() {
+        presence.onActivityStarted(screen)
+        presence.onChatSurface(SessionSummaryDto.MAIN_SESSION_ID)
+    }
+
+    // —— 两条路只弹一次 ——
+
+    @Test
+    fun `the live frame and the persisted frame notify once`() {
+        background()
+        // 实时帧：落库行 id 在 `data.id` 里（IM 侧消息号是另一个 id）。
+        val live = notifier.onProactiveFrame(
+            sessionId = null,
+            id = "1371",
+            messageId = "im-7",
+            timestamp = "2026-10-06T01:20:05.123+08:00",
+            content = "记得喝水哦",
+        )
+        // 落库帧：同一条的 `message.id`（服务端两侧同一个值）。
+        val persisted = notifier.onProactiveFrame(
+            sessionId = SessionSummaryDto.MAIN_SESSION_ID,
+            id = "1371",
+            messageId = null,
+            timestamp = null,
+            content = "记得喝水哦",
+        )
+
+        assertEquals(ProactiveNotifyOutcome.Posted, live)
+        assertEquals(ProactiveNotifyOutcome.Duplicate, persisted)
+        assertEquals(listOf("记得喝水哦"), posted)
+    }
+
+    @Test
+    fun `each message gets its own notification id while a replay does not`() {
+        // 「一事一条」在这一层就定好了：号由**去重键**派生，所以「认得出是同一条」与「落在同一条
+        // 通知上」是同一个判断的两面。第二条消息必须是另一个号——同一个号时 `notify` 是替换，
+        // 她连说两句用户就只看到最后一句（这就是改前的症状）。
+        background()
+        val ids = mutableListOf<Int>()
+        val recorder = ProactiveNotifier(presence = presence, post = { _, id -> ids += id })
+
+        recorder.onProactiveFrame(null, id = "1371", messageId = "im-7", timestamp = null, content = "记得喝水哦")
+        // 同一条的落库帧（另一条路）：认得出是同一条 ⇒ 不再发一条，也就不该多出第二个号。
+        recorder.onProactiveFrame(
+            SessionSummaryDto.MAIN_SESSION_ID,
+            id = "1371",
+            messageId = null,
+            timestamp = null,
+            content = "记得喝水哦",
+        )
+        recorder.onProactiveFrame(null, id = "1372", messageId = null, timestamp = null, content = "在忙吗")
+
+        assertEquals(2, ids.size)
+        assertNotEquals("两条不同的消息必须占两条通知", ids[0], ids[1])
+    }
+
+    @Test
+    fun `a frame without a row id is deduplicated by the im message id`() {
+        // 落库失败那一档：`id` / `createdAt` 一起缺席，但 IM 侧消息号还在——服务端重推同一帧
+        // （或本端重放）不该变成两条通知。
+        background()
+        fun frame() = notifier.onProactiveFrame(
+            sessionId = null,
+            id = null,
+            messageId = "im-9",
+            timestamp = "2026-10-06T01:20:05+08:00",
+            content = "在忙吗",
+        )
+
+        assertEquals(ProactiveNotifyOutcome.Posted, frame())
+        assertEquals(ProactiveNotifyOutcome.Duplicate, frame())
+        assertEquals(1, posted.size)
+    }
+
+    @Test
+    fun `a frame with no server key at all falls back to the text`() {
+        // 服务端一个键都没给：兜底键取正文。**少弹**是刻意选的那一侧（多弹一次才是骚扰）。
+        background()
+        fun frame() = notifier.onProactiveFrame(
+            sessionId = null,
+            id = null,
+            messageId = null,
+            timestamp = null,
+            content = "想你了",
+        )
+
+        assertEquals(ProactiveNotifyOutcome.Posted, frame())
+        assertEquals(ProactiveNotifyOutcome.Duplicate, frame())
+    }
+
+    @Test
+    fun `a blank id is treated as absent`() {
+        // 形状漂移（空串）与「这个键不在」必须是同一个结论，否则一条空 id 会把后面的都判成重复。
+        background()
+        notifier.onProactiveFrame(null, id = "  ", messageId = "im-3", timestamp = null, content = "甲")
+
+        val second = notifier.onProactiveFrame(null, id = null, messageId = "im-4", timestamp = null, content = "乙")
+
+        assertEquals(ProactiveNotifyOutcome.Posted, second)
+        assertEquals(2, posted.size)
+    }
+
+    // —— 什么时候弹 ——
+
+    @Test
+    fun `watching the main session in the foreground stays silent`() {
+        onMainSessionInForeground()
+
+        val outcome = notifier.onProactiveFrame(null, "1371", "im-7", null, "记得喝水哦")
+
+        assertEquals(ProactiveNotifyOutcome.SeenOnScreen, outcome)
+        assertTrue(posted.isEmpty())
+    }
+
+    @Test
+    fun `watching another session still notifies`() {
+        // 「不在聊天页」包括「在另一个会话的聊天页」：她的话进的是主会话，用户看不到它。
+        presence.onActivityStarted(this)
+        presence.onChatSurface("web:7f3a")
+
+        val outcome = notifier.onProactiveFrame(null, "1371", "im-7", null, "记得喝水哦")
+
+        assertEquals(ProactiveNotifyOutcome.Posted, outcome)
+    }
+
+    @Test
+    fun `the settings page still notifies`() {
+        // 前台但聊天页不在组合里（设置页 / 管理页 / 关于）：那一刻聊天页报的是 null。
+        presence.onActivityStarted(this)
+        presence.onChatSurface(null)
+
+        assertEquals(
+            ProactiveNotifyOutcome.Posted,
+            notifier.onProactiveFrame(null, "1371", "im-7", null, "记得喝水哦"),
+        )
+    }
+
+    @Test
+    fun `a backgrounded app notifies even though the chat page is still composed`() {
+        // 这是 AppPresence 的类注释说的那一档：Activity onStop 之后组合还挂着，「聊天页显示着主会话」
+        // 仍然为真，而用户根本看不见它。只看聊天页那一半就会把后台的每一句都漏掉。
+        presence.onChatSurface(SessionSummaryDto.MAIN_SESSION_ID)
+
+        assertEquals(
+            ProactiveNotifyOutcome.Posted,
+            notifier.onProactiveFrame(null, "1371", "im-7", null, "记得喝水哦"),
+        )
+    }
+
+    @Test
+    fun `a message that was already seen on screen is not notified by the other route`() {
+        // 先到的那一次说了算：他当场看过了，随后落库帧再补一帧时他可能已经切走——
+        // 但**看过就是看过**，不该为一句看过的话弹通知。
+        onMainSessionInForeground()
+        assertEquals(
+            ProactiveNotifyOutcome.SeenOnScreen,
+            notifier.onProactiveFrame(null, "1371", "im-7", null, "记得喝水哦"),
+        )
+
+        presence.onChatSurface("web:7f3a")
+        assertEquals(
+            ProactiveNotifyOutcome.Duplicate,
+            notifier.onProactiveFrame(SessionSummaryDto.MAIN_SESSION_ID, "1371", null, null, "记得喝水哦"),
+        )
+        assertTrue(posted.isEmpty())
+    }
+
+    // —— 硬边界：不该弹的绝不弹 ——
+
+    @Test
+    fun `a frame from another session never notifies`() {
+        background()
+
+        val outcome = notifier.onProactiveFrame(
+            sessionId = "sess-9",
+            id = "1371",
+            messageId = "im-7",
+            timestamp = null,
+            content = "今天在忙什么",
+        )
+
+        assertEquals(ProactiveNotifyOutcome.OtherSession, outcome)
+        assertTrue("别处的消息不许说成是她在找我说话", posted.isEmpty())
+    }
+
+    @Test
+    fun `an absent - blank session id on the frame is treated as the main session`() {
+        // 实时帧的帧壳**不带** sessionId（服务端构造时不设）⇒「无法判定」放行，归属由主会话那条事实兜住。
+        background()
+
+        assertEquals(
+            ProactiveNotifyOutcome.Posted,
+            notifier.onProactiveFrame(sessionId = null, id = "1", messageId = null, timestamp = null, content = "在吗"),
+        )
+        assertEquals(
+            ProactiveNotifyOutcome.Posted,
+            notifier.onProactiveFrame(sessionId = "", id = "2", messageId = null, timestamp = null, content = "在吗"),
+        )
+    }
+
+    @Test
+    fun `a frame with nothing to show is skipped`() {
+        background()
+
+        val outcome = notifier.onProactiveFrame(null, "1371", "im-7", null, "   ")
+
+        assertEquals(ProactiveNotifyOutcome.NothingToSay, outcome)
+        assertTrue(posted.isEmpty())
+    }
+
+    @Test
+    fun `a contentless frame does not burn the key of the message that does have content`() {
+        // 空帧**不记账**：同一条消息的另一条路上正文可能是齐的（形状漂移），记了就会把它挡成重复。
+        background()
+        notifier.onProactiveFrame(null, "1371", null, null, "")
+
+        assertEquals(
+            ProactiveNotifyOutcome.Posted,
+            notifier.onProactiveFrame(null, "1371", null, null, "记得喝水哦"),
+        )
+    }
+
+    @Test
+    fun `the posted text is her own words, not the raw markup`() {
+        background()
+
+        notifier.onProactiveFrame(null, "1", null, null, "<p>在的</p><action>轻轻笑</action>")
+
+        assertEquals(listOf("在的 轻轻笑"), posted)
+    }
+
+    @Test
+    fun `the main session constant has one spelling`() {
+        // `ui.chat.MAIN_SESSION_ID` 与 `SessionSummaryDto.MAIN_SESSION_ID` 是同一个事实的两处写法
+        // （判据里用的是后者）。两处一旦分叉，「主会话」这条归属就会静默判错——钉住它。
+        assertEquals("web", SessionSummaryDto.MAIN_SESSION_ID)
+        assertEquals(SessionSummaryDto.MAIN_SESSION_ID, top.yeij.cyrene.ui.chat.MAIN_SESSION_ID)
+    }
+}
+
+/**
+ * 去重账本本身（与 [ProactiveNotifierTest] 分开：一个是「弹不弹」，一个是「凭什么记得住」）。
+ */
+class RecentProactiveNoticesTest {
+
+    @Test
+    fun `the first arrival of a key is new and the second is not`() {
+        val recent = RecentProactiveNotices()
+
+        assertTrue(recent.markIfNew("1371"))
+        assertTrue(!recent.markIfNew("1371"))
+        assertTrue(recent.markIfNew("1372"))
+    }
+
+    @Test
+    fun `the ledger is bounded and drops the oldest first`() {
+        // 进程级账本**不许无限涨**：容量满了丢掉最老的那些（丢掉的代价最多是重复弹一次，
+        // 而那要等到「同一条又被重推」才可能发生）。
+        val recent = RecentProactiveNotices(capacity = 3)
+
+        recent.markIfNew("a")
+        recent.markIfNew("b")
+        recent.markIfNew("c")
+        recent.markIfNew("d")
+
+        assertEquals(3, recent.size())
+        assertTrue("最老的 a 已经被挤出去", recent.markIfNew("a"))
+        assertTrue("'b' 也早被挤出去（容量 3 只留 c/d/a）", recent.markIfNew("b"))
+    }
+
+    @Test
+    fun `a blank key is never considered new`() {
+        // 「没有键」不是一个可去重的身份：把它当新消息就等于每次都弹。
+        val recent = RecentProactiveNotices()
+
+        assertTrue(!recent.markIfNew(""))
+        assertTrue(!recent.markIfNew("   "))
+        assertEquals(0, recent.size())
+    }
+
+    @Test
+    fun `a zero capacity still remembers one key`() {
+        // 容量被误传成 0 / 负数时不许退化成「每条都弹」：至少记住最近一条。
+        val recent = RecentProactiveNotices(capacity = 0)
+
+        assertTrue(recent.markIfNew("1371"))
+        assertTrue(!recent.markIfNew("1371"))
+        assertEquals(1, recent.size())
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/notify/ProactiveNotifyTest.kt

@@ -0,0 +1,275 @@
+package top.yeij.cyrene.core.notify
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 「她主动说的话」的通知判据（W53N）——**纯函数**，四档组合穷举在这里。
+ *
+ * 主人对时机的原话是「App 不在前台，或者不在聊天页」；这个判据是它唯一的落地处，
+ * 而那四种组合**各有各的真实场景**（尤其是「不在前台、聊天页却还显示着主会话」那一档：
+ * Android 上 Activity `onStop` 之后组合并不销毁，只看聊天页就会把后台收到的**每一句**都漏掉）。
+ */
+class ShouldNotifyProactiveTest {
+
+    @Test
+    fun `being on the main session in the foreground is the only silent case`() {
+        assertFalse(
+            "用户正看着主会话，她的话就出现在他眼前——再弹一条通知是打扰",
+            shouldNotifyProactive(appInForeground = true, viewingTargetSession = true),
+        )
+    }
+
+    @Test
+    fun `any other combination notifies`() {
+        assertTrue(
+            "前台但不在聊天页（设置页 / 管理页 / 别的会话）——这条消息他不会正好看到",
+            shouldNotifyProactive(appInForeground = true, viewingTargetSession = false),
+        )
+        assertTrue(
+            "退到后台：两个事实都假",
+            shouldNotifyProactive(appInForeground = false, viewingTargetSession = false),
+        )
+        assertTrue(
+            "退到后台而组合还挂着（聊天页仍「显示」主会话）：用户根本看不见它，所以照弹",
+            shouldNotifyProactive(appInForeground = false, viewingTargetSession = true),
+        )
+    }
+}
+
+/**
+ * 通知正文（纯函数）：剥标记、折成一行、过长截断。
+ *
+ * 这几条**每一条错了都肉眼可见**：露一个 `<p>` 出来、把两句话粘成一个词、或截断劈开一个 emoji
+ * （半个代理码元在通知里是一块乱码方块）。
+ */
+class ProactiveNotificationTextTest {
+
+    @Test
+    fun `the markup she writes is stripped instead of shown`() {
+        // 服务端原样落库她的标记，直接显示会把标签露给用户（会话列表那一行早就踩过同一件事）。
+        assertEquals(
+            "今天下午 悄悄戳了戳你 你有空吗",
+            proactiveNotificationText("<p>今天下午</p><action>悄悄戳了戳你</action><p>你有空吗</p>"),
+        )
+    }
+
+    @Test
+    fun `newlines collapse into one line`() {
+        assertEquals("第一句 第二句", proactiveNotificationText("第一句\n\n第二句"))
+    }
+
+    @Test
+    fun `a short line is left untouched`() {
+        assertEquals("记得喝水哦", proactiveNotificationText("记得喝水哦"))
+    }
+
+    @Test
+    fun `a long line is truncated with an ellipsis`() {
+        val text = proactiveNotificationText("她".repeat(200), maxChars = 10)
+
+        assertEquals("她".repeat(10) + "…", text)
+    }
+
+    @Test
+    fun `truncation never splits a surrogate pair`() {
+        // 😀 在 UTF-16 里是两个码元。maxChars = 2 正好落在它的**高代理项**上：不后退一位就会留下
+        // 半个字符（通知里显示成乱码方块）。
+        val text = proactiveNotificationText("a😀b", maxChars = 2)
+
+        assertEquals("a…", text)
+        assertFalse(
+            "结果里不许有孤立的代理码元",
+            text!!.any { it.isHighSurrogate() || it.isLowSurrogate() },
+        )
+    }
+
+    @Test
+    fun `nothing to say returns null rather than an empty notification`() {
+        assertNull(proactiveNotificationText(""))
+        assertNull(proactiveNotificationText("   \n  "))
+        // 只有标记、没有一个字：解析器把它解成一串空白，也不该弹一条空通知。
+        assertNull(proactiveNotificationText("<p></p>"))
+    }
+}
+
+/**
+ * 通知 id / 渠道 id 的**对外形状**（与 `KeepAliveNotificationTest` 同一套理由）。
+ *
+ * 这两条只能在单元测试里钉住（文案与图标要 Android 运行时），而它们恰恰是最容易出大错的两处：
+ * 同 id 会**替换**掉保活那条常驻通知；同渠道会让「保活开始响铃」与「她的话不响铃」二选一。
+ */
+class ProactiveNotificationShapeTest {
+
+    @Test
+    fun `the proactive notification never replaces the keep-alive one`() {
+        // 同 id 的 notify 是替换：撞上就把「正在后台保持连接」那条常驻通知顶掉。
+        // 号现在按消息派生（见 `proactiveNotificationId`），所以这里钉的是「派生的号落在保活那条
+        // 之外」——扫一遍真实形状的键（服务端行 id、IM 消息号、时间字面量、正文兜底、空键）。
+        val keys = listOf(
+            "0",
+            "1",
+            "2",
+            "1371",
+            "im-7",
+            "4294967295",
+            "2026-10-06T01:20:05.123+08:00",
+            "记得喝水哦",
+            "",
+        )
+
+        keys.forEach { key ->
+            assertTrue(
+                "键「$key」派生出的号撞上了保活那条常驻通知",
+                proactiveNotificationId(key) != top.yeij.cyrene.core.keepalive.KEEP_ALIVE_NOTIFICATION_ID,
+            )
+        }
+    }
+
+    @Test
+    fun `proactive has its own channel`() {
+        assertTrue(
+            "两条渠道各自表达一件事，混在一条里就只能二选一",
+            PROACTIVE_CHANNEL_ID != top.yeij.cyrene.core.keepalive.KEEP_ALIVE_CHANNEL_ID,
+        )
+        // 🔴 这里是 `proactive_v2` 而**不是** `proactive`：渠道重要级一旦创建就改不了（只有用户能改），
+        // 2026-10-07 把它从 DEFAULT 提到 HIGH 对**已建过旧渠道**的设备不生效 ⇒ 只能换一个新 id
+        // 让系统按新重要级重新建。这条断言就是「以后谁要改重要级，必须同时换 id」的机器可读版本。
+        assertEquals("proactive_v2", PROACTIVE_CHANNEL_ID)
+        assertEquals("proactive", LEGACY_PROACTIVE_CHANNEL_ID)
+        assertTrue(
+            "新 id 必须不同于旧 id —— 相同就说明有人改了重要级却没换 id（对老设备无效）",
+            PROACTIVE_CHANNEL_ID != LEGACY_PROACTIVE_CHANNEL_ID,
+        )
+    }
+
+    /**
+     * 「免打扰」那条渠道：它必须是**另一条**，而且是**安静的那一条**。
+     *
+     * 这几件事各有各的坏法，且都很难在真机上发现：
+     * - 与 `PROACTIVE_CHANNEL_ID` 同 id ⇒ 开关两档发到同一条渠道，「开着免打扰照样弹横幅」；
+     * - 重要级不低于 HIGH ⇒ 它照样弹横幅，用户按了开关却什么都没变（而**不会有任何报错**）；
+     * - 撞上旧 id ⇒ 建新渠道时会被顺手删掉（那条通知随后就被系统静默丢弃）。
+     */
+    @Test
+    fun `the do-not-disturb channel is a second, quieter channel`() {
+        assertEquals("proactive_quiet", QUIET_PROACTIVE_CHANNEL_ID)
+        assertEquals(
+            "免打扰那一档只许是 DEFAULT（有提示音、不弹横幅）：HIGH 会照样弹横幅",
+            android.app.NotificationManager.IMPORTANCE_DEFAULT,
+            QUIET_PROACTIVE_IMPORTANCE,
+        )
+        assertTrue(
+            "两条渠道必须真的不同 —— 同 id 就等于「开关两档没有区别」",
+            QUIET_PROACTIVE_CHANNEL_ID != PROACTIVE_CHANNEL_ID,
+        )
+        assertTrue(
+            "它也不许撞上旧 id（否则建新渠道那一步会把自己删掉）",
+            QUIET_PROACTIVE_CHANNEL_ID != LEGACY_PROACTIVE_CHANNEL_ID,
+        )
+        assertTrue(
+            "更不许撞上保活那条（否则用户对保活的静音设置会被她的话一起改掉）",
+            QUIET_PROACTIVE_CHANNEL_ID != top.yeij.cyrene.core.keepalive.KEEP_ALIVE_CHANNEL_ID,
+        )
+    }
+
+    /**
+     * 开关 → 渠道 id 的**纯函数**（两档）。这是「免打扰」唯一的落地形状：横幅由渠道重要级决定，
+     * 而重要级建完就改不了 ⇒ 只能按开关选一条渠道发。
+     *
+     * 同时钉住 `ProactiveChannelSpec` 的**成对性**：id / 渠道名 / 重要级必须一起跟着开关走。四处
+     * 各写一份 `if (quiet)` 时的坏法是「换了 id 却没换重要级」，症状是「按了开关，什么都没变」。
+     */
+    @Test
+    fun `the switch picks the channel and the whole spec moves with it`() {
+        assertEquals(PROACTIVE_CHANNEL_ID, proactiveChannelId(quiet = false))
+        assertEquals(QUIET_PROACTIVE_CHANNEL_ID, proactiveChannelId(quiet = true))
+
+        val loud = proactiveChannelSpec(quiet = false)
+        val quiet = proactiveChannelSpec(quiet = true)
+        assertEquals(PROACTIVE_CHANNEL_ID, loud.id)
+        assertEquals(PROACTIVE_CHANNEL_NAME, loud.name)
+        assertEquals(PROACTIVE_IMPORTANCE, loud.importance)
+        assertEquals(QUIET_PROACTIVE_CHANNEL_ID, quiet.id)
+        assertEquals(QUIET_PROACTIVE_CHANNEL_NAME, quiet.name)
+        assertEquals(QUIET_PROACTIVE_IMPORTANCE, quiet.importance)
+
+        // 系统设置的渠道列表里这两行会并排出现，用户就是靠它判断「哪条会弹横幅」——同名等于白分两条。
+        assertNotEquals(
+            "两条渠道名必须一眼看得出区别",
+            PROACTIVE_CHANNEL_NAME,
+            QUIET_PROACTIVE_CHANNEL_NAME,
+        )
+        assertTrue(
+            "免打扰那条的渠道名要点明它是什么：$QUIET_PROACTIVE_CHANNEL_NAME",
+            QUIET_PROACTIVE_CHANNEL_NAME.contains("免打扰"),
+        )
+    }
+
+    @Test
+    fun `the channel is allowed to alert unlike the keep-alive one`() {
+        // 这一条**是**要来提醒人的；与保活那条（LOW）刻意相反，所以这里钉的是「它比 LOW 高」。
+        assertTrue(
+            "她要提醒人，重要级必须高于保活那条",
+            PROACTIVE_IMPORTANCE > top.yeij.cyrene.core.keepalive.KEEP_ALIVE_CHANNEL_IMPORTANCE,
+        )
+        // `HIGH`(4) 是**屏幕顶部弹横幅**的门槛：DEFAULT 只会响一声躺在通知栏里。
+        // 主人 2026-10-07 的原话「我在其他 APP 时没看到横幅」就是 DEFAULT 这一档造成的。
+        assertEquals(android.app.NotificationManager.IMPORTANCE_HIGH, PROACTIVE_IMPORTANCE)
+        assertTrue(
+            "免打扰那一档必须比它低 —— 否则「只关横幅」这件事就没有档位可用了",
+            QUIET_PROACTIVE_IMPORTANCE < PROACTIVE_IMPORTANCE,
+        )
+    }
+}
+
+/**
+ * 通知 id 的派生（W54A）——「一事一条」靠的就是它。
+ *
+ * 三条各自钉住一件**错了就肉眼可见**的事：
+ * 1. **同一条消息派生两次必须同号**：重放、或实时帧与落库帧两条路都到，落的是同一条通知；
+ * 2. **两条不同的消息必须不同号**：同号时 `notify` 是替换，她连说两句就只剩最后一句（改前的症状）；
+ * 3. **任何输入都得落在合法区间**：Android 的通知 id 是 int，而 `hashCode()` 可以为负、甚至正好是
+ *    `Int.MIN_VALUE`——那一个连 `abs` 都兜不住（`abs(Int.MIN_VALUE)` 在 int 域里仍是它自己）。
+ */
+class ProactiveNotificationIdTest {
+
+    @Test
+    fun `the same message derives the same id every time`() {
+        // 幂等：进程重启、两条路先后到达都不该改变「这条消息是哪一条通知」。
+        val key = proactiveNotifyKey("1371", "im-7", null, "记得喝水哦")
+
+        assertEquals(proactiveNotificationId(key), proactiveNotificationId(key))
+        // 键里那三个 id 的**优先级**也是同一件事的一半：同一条消息两条路给的是不同的入参形状，
+        // 落到同一个键上才算真的稳。
+        assertEquals(
+            key,
+            proactiveNotifyKey("1371", null, null, "记得喝水哦"),
+        )
+    }
+
+    @Test
+    fun `two different messages derive two different ids`() {
+        val first = proactiveNotificationId(proactiveNotifyKey("1371", "im-7", null, "记得喝水哦"))
+        val second = proactiveNotificationId(proactiveNotifyKey("1372", "im-8", null, "在忙吗"))
+
+        assertNotEquals("不同号是「先来的不被后来的顶掉」的全部前提", first, second)
+    }
+
+    @Test
+    fun `every derived id stays positive even when the hash is Int MIN_VALUE`() {
+        // 先钉住这条用例的前提：这个字符串的 hashCode **正好是** Int.MIN_VALUE（`abs` 兜不住的那个
+        // 值）。前提没了就等于这条用例什么都没验。
+        val extreme = "polygenelubricants"
+        assertEquals(Int.MIN_VALUE, extreme.hashCode())
+
+        val keys = listOf("", "0", "1371", "web", "她主动说的话", extreme)
+        keys.forEach { key ->
+            assertTrue("键「$key」派生出了非正号：${proactiveNotificationId(key)}", proactiveNotificationId(key) > 0)
+        }
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/prefs/AppPrefsQuietTest.kt

@@ -0,0 +1,49 @@
+package top.yeij.cyrene.core.prefs
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+
+/**
+ * 「免打扰」这个设置项的形状（默认值 + 读写往返）。
+ *
+ * `AppSettings` 本体要 Android + DataStore、单测里起不来（与 `InterruptModeTest` 同一条理由），
+ * 所以钉的是它两侧的**纯**部分。三件事各自对应一种真会发生的坏法：
+ *
+ * 1. **默认必须是 `false`（都弹）**：主人 2026-10-07 的话是「关闭时两者都弹，**默认都弹**」——
+ *    一个默认就安静的 App 会让人以为通知坏了（而这一条恰恰没有任何报错）；
+ * 2. **数据类的默认参数与落盘读取口的缺省值必须是同一个值**：它们表达的是同一个「缺省」，
+ *    分叉的症状是「开关显示关着、行为却安静」（或反过来），同样没有任何报错；
+ * 3. **读写往返**：写进去什么就读出什么，两个布尔都走一遍。这一档没有 `Enum` 那种映射层，
+ *    唯一会坏的方式就是某个分支被写反，而写反的后果正好是「开关与行为相反」。
+ */
+class AppPrefsQuietTest {
+
+    @Test
+    fun `do not disturb is off by default so both keep alerting`() {
+        assertFalse(
+            "默认必须是「都弹」：默认就安静只会让人以为通知坏了",
+            AppPrefs().proactiveQuiet,
+        )
+        assertFalse("缺省常量本身就是默认值，它不能是 true", PROACTIVE_QUIET_DEFAULT)
+    }
+
+    @Test
+    fun `the data-class default and the read seam agree on one default`() {
+        // 两条路读的是同一个「缺省」：进程刚起来（数据类默认参数）与盘上没有这个键（读取口）。
+        assertEquals(
+            "数据类的默认参数与落盘读取口的缺省值必须同源",
+            AppPrefs().proactiveQuiet,
+            (null as Boolean?).toProactiveQuiet(),
+        )
+    }
+
+    @Test
+    fun `the switch round-trips from the data class through the read seam`() {
+        listOf(false, true).forEach { wanted ->
+            val written = AppPrefs(proactiveQuiet = wanted).proactiveQuiet
+
+            assertEquals("写进去什么就得读出什么", wanted, (written as Boolean?).toProactiveQuiet())
+        }
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/session/ChatSessionEvictionTest.kt

@@ -0,0 +1,230 @@
+package top.yeij.cyrene.core.session
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 「留最近几格、其余交出去」这条判据（[chatSessionEvictions]）的口径。
+ *
+ * 钉住四件事，它们各自都是一条会出事的边界：
+ * 1. **「最近」的口径是 `lastUsedAt`**（最后一次成为当前会话）——谁新谁留下，最旧的先走；
+ * 2. **主会话与屏幕上那一格永不回收**，而且它们**占** `keep` 的名额（`keep` 是「本端同时留几格」
+ *    的内存目标，不是「除它们之外再留几格」）；
+ * 3. **还有没交代完的事的格子不回收**（草稿 / 排队等连接的发送：回收＝内容回不来），同样占名额
+ *    ——不然「最多 3 格」在豁免生效时会变成「3 + 豁免数」，那个数就没有上限了；
+ * 4. 结论是**槽位的 key**（账号指纹 + 会话 id），不是会话 id：同一个会话 id 在两个账号下是两格。
+ *
+ * 每个用例都把 `currentKey` 显式指出来，取值按真实情形（屏幕上那一格就是刚刚打开的那一格）。
+ */
+class ChatSessionEvictionTest {
+
+    private val main = "web"
+
+    /** 一个槽位的样子；[sessionId] 单列是刻意的（key 里另带着账号指纹，见 [ChatSessionUsage]）。 */
+    private fun usage(
+        sessionId: String,
+        at: Long,
+        unsent: Boolean = false,
+        account: String = "acct",
+    ) = ChatSessionUsage(
+        key = "$account|$sessionId",
+        sessionId = sessionId,
+        lastUsedAt = at,
+        holdsUnsentWork = unsent,
+    )
+
+    /** 账本 key（免得每个断言里手拼 `acct|` 前缀时写错一处）。 */
+    private fun key(sessionId: String, account: String = "acct") = "$account|$sessionId"
+
+    @Test
+    fun `the owner decision is three slots`() {
+        // N=3 是主人拍板的口径，不是随手取的一个数（改动它会同时改掉本端常驻的内存上限）。
+        assertEquals(3, CHAT_SESSION_SLOT_KEEP)
+    }
+
+    @Test
+    fun `nothing is reclaimed while the budget is not exceeded`() {
+        // 主会话 + 两个次级会话 = 正好 3 格。它是最常见的形态，也是「什么都不该发生」的那一档。
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3)),
+            mainSessionId = main,
+            currentKey = key("web:b"),
+        )
+        assertTrue(evicted.isEmpty())
+    }
+
+    @Test
+    fun `an empty ledger reclaims nothing`() {
+        assertTrue(
+            chatSessionEvictions(emptyList(), mainSessionId = main, currentKey = key(main)).isEmpty(),
+        )
+    }
+
+    @Test
+    fun `the oldest slots go first and the verdict lists them oldest first`() {
+        // 主会话（最旧）+ 三个次级会话：名额 3 里主会话与屏幕上那一格各占一个 ⇒ 只能再留 1 个
+        // ⇒ 最旧的那个走。（屏幕上那一格通常就是最新的那个，见下面的用例。）
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3), usage("web:c", 4)),
+            mainSessionId = main,
+            currentKey = key("web:c"),
+        )
+        assertEquals(listOf(key("web:a")), evicted)
+
+        // 再打开一个新会话 ⇒ 又该走一个，而且结论里**先列最旧的**（调用方按这个顺序交出去）。
+        val more = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3), usage("web:c", 4), usage("web:d", 5)),
+            mainSessionId = main,
+            currentKey = key("web:d"),
+        )
+        assertEquals(listOf(key("web:a"), key("web:b")), more)
+    }
+
+    @Test
+    fun `a slot that was never opened is the first to go`() {
+        // lastUsedAt = 0 是「建出来还没打开过」的空槽位（组合被丢弃时留下的那种）：它必然最旧。
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 10), usage("web:abandoned", 0), usage("web:a", 11), usage("web:b", 12)),
+            mainSessionId = main,
+            currentKey = key("web:b"),
+        )
+        assertEquals(listOf(key("web:abandoned")), evicted)
+    }
+
+    @Test
+    fun `the main session is never reclaimed even when it is the oldest`() {
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3), usage("web:c", 4), usage("web:d", 5)),
+            mainSessionId = main,
+            currentKey = key("web:d"),
+        )
+        // 主会话是最旧的那一格，但它一个字节都不许出现在结论里（名额照旧被它占着）。
+        assertTrue(main !in evicted.map { it.substringAfter('|') })
+        assertEquals(listOf(key("web:a"), key("web:b")), evicted)
+    }
+
+    @Test
+    fun `the session on screen is never reclaimed`() {
+        // 屏幕上那一格**可能**是账本里最旧的一格（它刚被打开、而别的格子刚收过心跳；或者时钟跳过）。
+        // 它照样不能收：收掉它 = 正在看的那一段从此不再更新（帧收不到、`viewModelScope` 已取消
+        // ⇒ 连发送都会静默不发），要等下一次重组才自己修回来。
+        val evicted = chatSessionEvictions(
+            listOf(
+                usage(main, 1),
+                usage("web:on-screen", 2),
+                usage("web:a", 3),
+                usage("web:b", 4),
+                usage("web:c", 5),
+            ),
+            mainSessionId = main,
+            currentKey = key("web:on-screen"),
+        )
+        assertEquals(listOf(key("web:a"), key("web:b")), evicted)
+    }
+
+    @Test
+    fun `a session holding unsent work is never reclaimed`() {
+        // a 是最旧的次级会话，但它手里有还没发出去的字（草稿 / 排队等连接的发送）——回收是
+        // 一条回不来的动作，所以该走的是**下一个**最旧的。
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2, unsent = true), usage("web:b", 3), usage("web:c", 4)),
+            mainSessionId = main,
+            currentKey = key("web:c"),
+        )
+        assertEquals(listOf(key("web:b")), evicted)
+    }
+
+    @Test
+    fun `a protected slot still eats one place of the budget`() {
+        // 主会话 + 两格有草稿 + 屏幕上那一格，就已经把「同时留 3 格」用掉了 ⇒ **干净的**那一格
+        // 才是该走的（豁免压过 keep，但豁免不会凭空多给名额）。
+        val evicted = chatSessionEvictions(
+            listOf(
+                usage(main, 1),
+                usage("web:a", 2, unsent = true),
+                usage("web:b", 3, unsent = true),
+                usage("web:c", 4),
+                usage("web:on-screen", 5),
+            ),
+            mainSessionId = main,
+            currentKey = key("web:on-screen"),
+        )
+        assertEquals(listOf(key("web:c")), evicted)
+    }
+
+    @Test
+    fun `keep counts the protected slots, so a tight budget reclaims every reclaimable one`() {
+        // keep = 1 而主会话与屏幕上那一格各占一个名额 ⇒ 可回收的全部走
+        //（`take` 的越界不报错，也不多收）。
+        val evicted = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3)),
+            mainSessionId = main,
+            currentKey = key("web:b"),
+            keep = 1,
+        )
+        assertEquals(listOf(key("web:a")), evicted)
+    }
+
+    @Test
+    fun `the default budget is the owner caliber`() {
+        val usages = listOf(usage(main, 1), usage("web:a", 2), usage("web:b", 3), usage("web:c", 4))
+        assertEquals(
+            chatSessionEvictions(usages, main, key("web:c"), keep = CHAT_SESSION_SLOT_KEEP),
+            chatSessionEvictions(usages, main, key("web:c")),
+        )
+    }
+
+    @Test
+    fun `ties fall back to the ledger order`() {
+        // 同一毫秒并列（真机上切会话在同一毫秒内发生）：退回账本顺序（先建出来的先走），
+        // 于是判据对同一份账本永远给同一个结论——不会在两次打开之间随机决定收谁。
+        val first = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:a", 5), usage("web:b", 5), usage("web:c", 6)),
+            mainSessionId = main,
+            currentKey = key("web:c"),
+        )
+        assertEquals(listOf(key("web:a")), first)
+
+        val flipped = chatSessionEvictions(
+            listOf(usage(main, 1), usage("web:b", 5), usage("web:a", 5), usage("web:c", 6)),
+            mainSessionId = main,
+            currentKey = key("web:c"),
+        )
+        assertEquals(listOf(key("web:b")), flipped)
+    }
+
+    @Test
+    fun `the verdict carries the slot key so two accounts never share a slot`() {
+        // 换账号之后同一个会话 id 是**另一格**（key 里的账号指纹分得开），而两格的 sessionId
+        // 都是主会话 ⇒ 两格都受「主会话永不回收」保护，能收的只有次级会话。
+        val usages = listOf(
+            usage(main, 1, account = "A"),
+            usage("web:s1", 2, account = "A"),
+            usage(main, 3, account = "B"),
+            usage("web:s1", 4, account = "B"),
+            usage("web:s2", 5, account = "B"),
+        )
+        assertEquals(
+            listOf(key("web:s1", "A"), key("web:s1", "B")),
+            chatSessionEvictions(usages, mainSessionId = main, currentKey = key("web:s2", "B")),
+        )
+    }
+
+    @Test
+    fun `the main session id is what the caller says it is`() {
+        // 判据不认识那个常量本身（主会话 id 由装配处注入）：换成别的 id 时口径跟着换，
+        // 说明它比的是**入参**，而不是某处写死的 "web"。
+        val usages = listOf(usage("web", 1), usage("web:a", 2), usage("web:b", 3), usage("web:c", 4))
+        // 换成别的 id 之后，最旧的 `web` 那一格就不再受保护了（它是第一个该走的）。
+        assertEquals(
+            listOf(key("web")),
+            chatSessionEvictions(usages, mainSessionId = "something-else", currentKey = key("web:c")),
+        )
+        // 而按真主会话的口径比，它一个字节都不许出现在结论里。
+        assertEquals(
+            listOf(key("web:a")),
+            chatSessionEvictions(usages, mainSessionId = main, currentKey = key("web:c")),
+        )
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/core/session/ChatSessionSlotsTest.kt

@@ -0,0 +1,144 @@
+package top.yeij.cyrene.core.session
+
+import org.junit.Assert.assertNotSame
+import org.junit.Assert.assertSame
+import org.junit.Test
+
+/**
+ * 会话槽位账本的粘合行为（[ChatSessionSlots]）：它只负责两件事——**给出去的那一格是不是同一格**
+ * （切回来时状态还在）与**什么时候把一格交出去**（判断本身在 [chatSessionEvictions]，这里钉的是
+ * 「判断的结论真的落到了那一格上」）。
+ *
+ * 观测方式刻意只用 `slotFor(...) === 原来的那个对象`：槽位被交出去之后，同样的账号 + 会话 id
+ * 会拿到一个**新**槽位（新的 `ViewModelStore` ⇒ 里面那个 VM 是重头建的），而没被交出去的一格
+ * 必须还是原来那个对象（否则「切回来还在」就没了）。这样测的是行为，不需要为测试开任何后门。
+ *
+ * 这里**不往 store 里放 VM**：本测试只跑在 JVM 上，构造 / 清空一份 `ViewModelStore` 不碰任何
+ * Android 与协程设施（回收那一半——`ViewModelStore.clear()` 会走 `onCleared`、取消 `viewModelScope`
+ * ——靠走查：那一行是库自己的语义，项目里没有能在 JVM 上安全建起来的 VM）。
+ */
+class ChatSessionSlotsTest {
+
+    private val account = "http://host-a:10942/|testuser"
+
+    private val slots = ChatSessionSlots(mainSessionId = "web")
+
+    /** 打开一个会话（= `ChatScreen` 记的那一笔账），并顺手返回它的槽位。 */
+    private fun open(
+        sessionId: String,
+        at: Long,
+        holdsUnsentWork: () -> Boolean = { false },
+    ): ChatSessionSlot = slots.slotFor(account, sessionId).also {
+        slots.onOpened(account, sessionId, holdsUnsentWork, at)
+    }
+
+    @Test
+    fun `the same account and session always yields the same slot`() {
+        assertSame(slots.slotFor(account, "web:a"), slots.slotFor(account, "web:a"))
+        // 另一个账号 / 另一个会话各是各的格子（账号指纹就在槽位 key 里）。
+        assertNotSame(slots.slotFor(account, "web:a"), slots.slotFor("other-account", "web:a"))
+        assertNotSame(slots.slotFor(account, "web:a"), slots.slotFor(account, "web:b"))
+    }
+
+    @Test
+    fun `taking a slot does not reclaim anything by itself`() {
+        // slotFor 只是「取或建」：组合期间碰它不该有任何回收动作（回收的触发点是 onOpened）。
+        val a = slots.slotFor(account, "web:a")
+        val b = slots.slotFor(account, "web:b")
+        val c = slots.slotFor(account, "web:c")
+        slots.slotFor(account, "web:d")
+        assertSame(a, slots.slotFor(account, "web:a"))
+        assertSame(b, slots.slotFor(account, "web:b"))
+        assertSame(c, slots.slotFor(account, "web:c"))
+    }
+
+    @Test
+    fun `opening one session beyond the budget gives the oldest slot back`() {
+        val main = open("web", 1)
+        val a = open("web:a", 2)
+        val b = open("web:b", 3)
+        val c = open("web:c", 4)
+
+        // 主会话（最旧）占一个名额 ⇒ 次级会话里最旧的 a 让位，其余原样。
+        assertSame(main, slots.slotFor(account, "web"))
+        assertNotSame(a, slots.slotFor(account, "web:a"))
+        assertSame(b, slots.slotFor(account, "web:b"))
+        assertSame(c, slots.slotFor(account, "web:c"))
+    }
+
+    @Test
+    fun `the slot on screen keeps its place even when every other slot holds unsent work`() {
+        // 屏幕上那一格按**身份**豁免（判据第 2 条）。没有它的话：四个格子都「不可回收」时预算
+        // 会变成负数，刚打开的这一格反而成了唯一可回收的那个——正在看的那一段从此不再更新。
+        open("web", 1)
+        open("web:a", 2) { true }
+        open("web:b", 3) { true }
+        open("web:c", 4) { true }
+        val onScreen = open("web:d", 5)
+
+        assertSame(onScreen, slots.slotFor(account, "web:d"))
+    }
+
+    @Test
+    fun `a slot created but never opened is swept away by the next reclaim`() {
+        // 组合被丢弃时会留下「建出来、从来没打开过」的空槽位：它 lastUsedAt 仍是 0 ⇒ 必然最旧。
+        open("web", 1)
+        val abandonedA = slots.slotFor(account, "web:abandoned-1")
+        val abandonedB = slots.slotFor(account, "web:abandoned-2")
+        val kept = open("web:kept", 2)
+        val kept2 = open("web:kept2", 3)
+
+        // 打开两个会话之后，两个空槽位先后被扫掉（每打开一格才收一格）。
+        assertNotSame(abandonedA, slots.slotFor(account, "web:abandoned-1"))
+        assertNotSame(abandonedB, slots.slotFor(account, "web:abandoned-2"))
+        assertSame(kept, slots.slotFor(account, "web:kept"))
+        assertSame(kept2, slots.slotFor(account, "web:kept2"))
+    }
+
+    @Test
+    fun `a slot holding unsent work is spared until it is clean`() {
+        var typing = true
+        val withDraft = open("web:a", 2) { typing }
+        open("web", 1)
+        val b = open("web:b", 3)
+        val c = open("web:c", 4)
+
+        // a 有还没发出去的字（虽然它在可回收的那些里最旧）：让位的是下一个最旧的 b。
+        assertSame(withDraft, slots.slotFor(account, "web:a"))
+        assertSame(c, slots.slotFor(account, "web:c"))
+
+        // 探针是**现读的**：草稿发出去之后，再打开一个会话时它就该让位了。
+        typing = false
+        open("web:d", 5)
+        assertNotSame(withDraft, slots.slotFor(account, "web:a"))
+        assertNotSame(b, slots.slotFor(account, "web:b"))
+        assertSame(c, slots.slotFor(account, "web:c"))
+    }
+
+    @Test
+    fun `reclaim gives exactly one slot back`() {
+        val a = open("web:a", 1)
+        val b = open("web:b", 2)
+        slots.reclaim(account, "web:a")
+
+        assertNotSame(a, slots.slotFor(account, "web:a"))
+        assertSame(b, slots.slotFor(account, "web:b"))
+    }
+
+    @Test
+    fun `reclaim of another account leaves this one alone`() {
+        val a = open("web:a", 1)
+        slots.reclaim("other-account", "web:a")
+        assertSame(a, slots.slotFor(account, "web:a"))
+    }
+
+    @Test
+    fun `clear gives every slot back`() {
+        val main = open("web", 1)
+        val a = open("web:a", 2)
+        slots.clear()
+
+        assertNotSame(main, slots.slotFor(account, "web"))
+        assertNotSame(a, slots.slotFor(account, "web:a"))
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/api/SpeechApiTest.kt

@@ -0,0 +1,156 @@
+package top.yeij.cyrene.data.api
+
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeoutOrNull
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.net.InetSocketAddress
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+
+/**
+ * `POST /api/v1/audio/speech` 的**运行时接线**：`ApiClientFactory.create`（主 REST client）→
+ * [SpeechApi]。
+ *
+ * 端到端跑**真 OkHttp + 真 Retrofit + 真 HTTP 服务端**（JDK 自带的 `com.sun.net.httpserver`，
+ * 与 [RestAttemptClientTest] 同一套做法，不引任何新依赖）。
+ *
+ * ## 它钉住的四条事实（每条都是判据，不是描述）
+ * 1. 请求真的写出去，落到 `POST <baseUrl>api/v1/audio/speech` —— 路径**不带前导 `/`**，
+ *    否则部署在子路径下的服务端地址会被整段丢掉（[SpeechApi] 的 KDoc 写的就是这条）。
+ * 2. 它带着 **owner Bearer 令牌**与 `X-API-Version: 1`：服务端是 owner-only 的双凭据门，
+ *    本端只走 Bearer 那一支（主人 2026-10-26 拍板不设 API Key 输入框）。
+ * 3. `sessionId` **有值时随体发出**——发音人由那条会话的生效人格决定，这是它唯一的来源。
+ * 4. `sessionId` 为 `null` 时字段**整个缺席**（`explicitNulls = false`），而不是发一个
+ *    `"sessionId": null`：契约里「省略」与「显式空」是两件事。
+ */
+class SpeechApiTest {
+
+    private val backend = FakeSpeechBackend()
+
+    @After
+    fun tearDown() {
+        backend.close()
+    }
+
+    /** 与生产同形：主 REST client（带令牌与 401 策略），只是 baseUrl 指向本地假端点。 */
+    private fun api(baseUrl: String = backend.baseUrl) = ApiClientFactory.create(
+        baseUrl = baseUrl,
+        service = SpeechApi::class.java,
+        tokenProvider = { TOKEN },
+    )
+
+    /** 发一次真请求并把响应体关掉（`@Streaming` 的体必须由调用方关闭）。 */
+    private suspend fun speech(dto: SpeechRequestDto) {
+        val response = withTimeoutOrNull(TIMEOUT_MILLIS) { api().speech(dto) }
+        response?.body()?.close()
+    }
+
+    @Test
+    fun `the request really puts a POST api v1 audio speech on the wire`() = runBlocking {
+        backend.reply(200, WAV)
+
+        speech(SpeechRequestDto(text = "你好"))
+
+        // 请求行不含 HTTP 版本（HttpExchange 只给 method + URI），判据是「方法 + 路径」。
+        assertEquals("POST /api/v1/audio/speech", backend.requestLines.single())
+    }
+
+    @Test
+    fun `the request carries the owner bearer token and the api version`() = runBlocking {
+        backend.reply(200, WAV)
+
+        speech(SpeechRequestDto(text = "你好"))
+
+        val headers = backend.headers.single()
+        assertEquals("Bearer $TOKEN", headers["authorization"])
+        assertEquals("1", headers["x-api-version"])
+    }
+
+    @Test
+    fun `the session id travels in the body because it decides the voice`() = runBlocking {
+        backend.reply(200, WAV)
+
+        speech(SpeechRequestDto(text = "你好", sessionId = SESSION_ID))
+
+        val raw = backend.bodies.single()
+        val sent = ApiClientFactory.json.decodeFromString(SpeechRequestDto.serializer(), raw)
+        assertEquals("你好", sent.text)
+        assertEquals(SESSION_ID, sent.sessionId)
+        assertTrue("sessionId 该随体发出，实际 $raw", raw.contains("\"sessionId\""))
+    }
+
+    @Test
+    fun `a null session id leaves the field out entirely instead of sending null`() = runBlocking {
+        backend.reply(200, WAV)
+
+        speech(SpeechRequestDto(text = "你好"))
+
+        val raw = backend.bodies.single()
+        val sent = ApiClientFactory.json.decodeFromString(SpeechRequestDto.serializer(), raw)
+        assertNull(sent.sessionId)
+        // 「省略」与「显式 null」在契约里是两件事：后者会让服务端以为本端知道是哪个会话。
+        assertFalse("sessionId 为 null 时不该出现这个键，实际 $raw", raw.contains("sessionId"))
+    }
+
+    /** 照着 `reply(...)` 回话的假 speech 端点：记下**请求行原文**、请求头原文与请求体原文。 */
+    private inner class FakeSpeechBackend : AutoCloseable {
+
+        private val server = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply {
+            executor = Executors.newFixedThreadPool(2)
+            createContext("/api/v1/audio/speech", ::handle)
+            start()
+        }
+
+        val baseUrl: String get() = "http://127.0.0.1:${server.address.port}/"
+
+        val requestLines = CopyOnWriteArrayList<String>()
+
+        /** 请求头按**小写键**记录：JDK 的 `Headers` 会把键规范化成 `X-Api-Version` 这种形状。 */
+        val headers = CopyOnWriteArrayList<Map<String, String>>()
+        val bodies = CopyOnWriteArrayList<String>()
+
+        @Volatile
+        private var status = 200
+
+        @Volatile
+        private var payload = WAV
+
+        fun reply(status: Int, body: ByteArray) {
+            this.status = status
+            this.payload = body
+        }
+
+        private fun handle(exchange: HttpExchange) {
+            requestLines += "${exchange.requestMethod} ${exchange.requestURI}"
+            headers += exchange.requestHeaders.entries.associate { it.key.lowercase() to it.value.joinToString(", ") }
+            bodies += String(exchange.requestBody.readBytes(), Charsets.UTF_8)
+            exchange.responseHeaders.add("Content-Type", "audio/wav")
+            exchange.sendResponseHeaders(status, payload.size.toLong())
+            exchange.responseBody.use { it.write(payload) }
+        }
+
+        override fun close() {
+            server.stop(0)
+        }
+    }
+
+    private companion object {
+        const val SESSION_ID = "web"
+        const val TOKEN = "test-token"
+        const val TIMEOUT_MILLIS = 10_000L
+
+        /** 一段形状正确的最小 WAV（`RIFF` + 长度 + `WAVE` + 40 字节的 `fmt `/`data` 区）。 */
+        val WAV: ByteArray =
+            "RIFF".toByteArray(Charsets.US_ASCII) +
+                byteArrayOf(36, 0, 0, 0) +
+                "WAVE".toByteArray(Charsets.US_ASCII) +
+                ByteArray(40)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/api/dto/VoiceDtoTest.kt

@@ -0,0 +1,261 @@
+package top.yeij.cyrene.data.api.dto
+
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.domain.chat.VoiceSource
+import top.yeij.cyrene.domain.chat.VoiceStatus
+
+/**
+ * `voice` 键的解码钉子（契约 **v0.67 登记、v0.79 已实现**，api-client.md §4.4 与 §1.2 U19）。
+ *
+ * 形状来源就是契约里那两处（示例 JSON + 语义段），**逐键手写**（没有 v0.79 的真实抓包）；
+ * 解码器用 [ApiClientFactory.json]（与生产同一份配置），所以这里过不了的形状线上也过不了。
+ *
+ * 要钉住的六件事：
+ * 1. **键名逐字照抄**：`source` / `status` / `name` / `mime` / `size` / `durationMs` / `url`，
+ *    外加**只在 `status = "failed"` 时**出现的第八个键 `fallbackReason`（后端 M57-M59 预告，
+ *    契约 v0.98 的正式回执尚未到）—— 键名不许自己发明（形状错一个字母线上就是「不是语音」）；
+ * 2. **缺席与 `null` 是同一件事**：非语音消息整键缺席 ⇒ `null`（不是 `{}`，也不是别的哨兵）；
+ * 3. **四者同生共死**：`name` / `mime` / `size` / `url` 全在或全不在（这里两侧都钉）；
+ * 4. **`durationMs` 可以缺席**（服务端「读不出来就省略键，绝不估算」）；
+ * 5. **`source` / `status` 的闭集取值原样保留**（含认不出的取值：本端不猜、不报错、不丢）；
+ *    `fallbackReason` 反过来**不是**闭集——本端原样留着、不做任何映射；
+ * 6. **未知键不炸**（`ignoreUnknownKeys`：服务端加字段不该让整条历史解码失败）。
+ */
+class VoiceDtoTest {
+
+    private val json = ApiClientFactory.json
+
+    private val name = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg"
+
+    /** 契约 §4.4 的示例逐字（含四个副本键 + `durationMs`）。 */
+    private val transcribed = """
+        {
+          "id": "msg-1",
+          "sessionId": "web",
+          "role": "user",
+          "content": "明天几点出发",
+          "createdAt": 1700000000000,
+          "voice": {
+            "source": "asr",
+            "status": "transcribed",
+            "name": "$name",
+            "mime": "audio/ogg",
+            "size": 12345,
+            "durationMs": 3200,
+            "url": "/api/v1/media/$name"
+          }
+        }
+    """.trimIndent()
+
+    private fun decode(body: String) = json.decodeFromString(HistoryMessageDto.serializer(), body)
+
+    @Test
+    fun `a transcribed voice decodes the seven keys verbatim`() {
+        val voice = decode(transcribed).voice!!
+
+        assertEquals(VoiceSource.ASR, voice.source)
+        assertEquals(VoiceStatus.TRANSCRIBED, voice.status)
+        assertEquals(name, voice.name)
+        assertEquals("audio/ogg", voice.mime)
+        assertEquals(12345L, voice.size)
+        assertEquals(3200, voice.durationMs)
+        // url 是**服务端相对路径**：本端绝不把它当绝对地址，也绝不自己拼这条路。
+        assertEquals("/api/v1/media/$name", voice.url)
+        assertFalse(voice.url!!.startsWith("http"))
+        // 转写成功的行不该有降级原因（服务端 `omitempty` 不下发）⇒ 解成 null，显示层据此不加小标。
+        assertNull(voice.fallbackReason)
+    }
+
+    @Test
+    fun `a message without the voice key decodes to null, not to an empty object`() {
+        val body = """
+            {"id":"msg-2","sessionId":"web","role":"user","content":"在的","createdAt":1700000000001}
+        """.trimIndent()
+
+        assertNull("🎤 判据 = 键存在：缺席必须是 null", decode(body).voice)
+    }
+
+    @Test
+    fun `an explicit null is the same thing as an absent key`() {
+        // 契约说 `voice` 是**指针**、非语音消息整键缺席（不是 null）；真收到 null 也按「没有」处理。
+        val body = """
+            {"id":"msg-3","sessionId":"web","role":"user","content":"在的","createdAt":1700000000002,
+             "voice":null}
+        """.trimIndent()
+
+        assertNull(decode(body).voice)
+    }
+
+    @Test
+    fun `a voice with no audio copy has all four copy keys absent`() {
+        // 微信（weixin-ilink）：平台自带转写就不白下载那份音频 ⇒ 只有 🎤 标记，四个键全缺席。
+        // ⚠️ 时长与副本**无关**：渠道给了就留着（所以这条夹具带着 durationMs，而四个副本键照样全缺）。
+        val body = """
+            {"id":"msg-4","sessionId":"web","role":"user","content":"在忙吗","createdAt":1700000000003,
+             "voice":{"source":"platform","status":"transcribed","durationMs":5000}}
+        """.trimIndent()
+
+        val voice = decode(body).voice!!
+        assertEquals(VoiceSource.PLATFORM, voice.source)
+        assertNull(voice.name)
+        assertNull(voice.mime)
+        assertNull(voice.size)
+        assertNull(voice.url)
+        assertEquals(5000, voice.durationMs)
+    }
+
+    @Test
+    fun `a copy keeps the four keys together including size zero and a missing duration`() {
+        // durationMs 缺席（服务端读不出来时不估算）——**其余四个键照样齐全**。
+        val body = """
+            {"id":"msg-5","sessionId":"web","role":"user","content":"","createdAt":1700000000004,
+             "voice":{"source":"asr","status":"empty","name":"$name","mime":"audio/ogg",
+                      "size":0,"url":"/api/v1/media/$name"}}
+        """.trimIndent()
+
+        val voice = decode(body).voice!!
+        assertEquals(name, voice.name)
+        assertEquals("audio/ogg", voice.mime)
+        assertEquals("size 为 0 也照样解码（本端不拿它推导任何东西）", 0L, voice.size)
+        assertEquals("/api/v1/media/$name", voice.url)
+        assertNull("缺席 ≠ 0：必须是 null，才能让界面「一个字符都不画」", voice.durationMs)
+    }
+
+    @Test
+    fun `a duration reported by the channel is kept as is`() {
+        val body = """
+            {"id":"msg-6","sessionId":"web","role":"user","content":"","createdAt":1700000000005,
+             "voice":{"source":"asr","status":"transcribed","durationMs":60000}}
+        """.trimIndent()
+
+        assertEquals(60_000, decode(body).voice!!.durationMs)
+    }
+
+    @Test
+    fun `the three statuses and both sources are kept verbatim, and an unknown one is not guessed`() {
+        val cases = listOf(
+            VoiceStatus.TRANSCRIBED to VoiceSource.ASR,
+            VoiceStatus.EMPTY to VoiceSource.ASR,
+            VoiceStatus.FAILED to VoiceSource.PLATFORM,
+            // 认不出的取值：原样保留（本端不猜、不报错、不丢——显示层对它们与本端不认识时同形）。
+            "future-status" to "future-source",
+        )
+
+        cases.forEach { (status, source) ->
+            val body = """
+                {"id":"msg-7","sessionId":"web","role":"user","content":"x","createdAt":1700000000006,
+                 "voice":{"source":"$source","status":"$status"}}
+            """.trimIndent()
+
+            val voice = decode(body).voice!!
+            assertEquals(status, voice.status)
+            assertEquals(source, voice.source)
+        }
+    }
+
+    @Test
+    fun `an unknown extra key inside voice does not break the message`() {
+        val body = """
+            {"id":"msg-8","sessionId":"web","role":"user","content":"x","createdAt":1700000000007,
+             "voice":{"source":"asr","status":"transcribed","waveform":[1,2,3]}}
+        """.trimIndent()
+
+        assertEquals(VoiceStatus.TRANSCRIBED, decode(body).voice!!.status)
+    }
+
+    @Test
+    fun `an empty voice object decodes as present`() {
+        // 契约说不会下发 `{}`（「不是 {} 也不是 null」），真收到时本端只认「键存在」这一条判据
+        // ⇒ 它算一条语音消息（四个副本键全缺 ⇒ 不画播放控件）。**刻意**在这里钉住这个选择：
+        // 「键在不在」是契约给的唯一判据，本端不额外发明一条「对象够不够完整」的判据。
+        val body = """
+            {"id":"msg-9","sessionId":"web","role":"user","content":"","createdAt":1700000000008,
+             "voice":{}}
+        """.trimIndent()
+
+        val voice = decode(body).voice
+        assertTrue(voice != null)
+        assertEquals("", voice!!.status)
+    }
+
+    @Test
+    fun `encoding a full voice keeps the seven key names`() {
+        // 反向也要钉一次：形状变了一处（键名写错 / 少一个键），这条用例立刻红。
+        // 这里没传 `fallbackReason`（非 failed 行本来就不该有）⇒ `explicitNulls = false` 不写这个键，
+        // 键集仍是七个。
+        val encoded = json.encodeToJsonElement(
+            VoiceDto.serializer(),
+            VoiceDto(
+                source = VoiceSource.ASR,
+                status = VoiceStatus.TRANSCRIBED,
+                name = name,
+                mime = "audio/ogg",
+                size = 12345,
+                durationMs = 3200,
+                url = "/api/v1/media/$name",
+            ),
+        ).jsonObject
+
+        assertEquals(
+            setOf("source", "status", "name", "mime", "size", "durationMs", "url"),
+            encoded.keys,
+        )
+    }
+
+    @Test
+    fun `encoding a fallback voice keeps the fallbackReason key`() {
+        // 第八个键（后端 M57-M59 预告）：只在 `status = "failed"` 时出现。它在 DTO 上是**真字段**，
+        // 不是靠 `ignoreUnknownKeys` 吞掉的陌生键——否则出站降级那一行写不出去。
+        val encoded = json.encodeToJsonElement(
+            VoiceDto.serializer(),
+            VoiceDto(
+                source = VoiceSource.TTS,
+                status = VoiceStatus.FAILED,
+                fallbackReason = "tts_timeout",
+            ),
+        ).jsonObject
+
+        assertEquals(setOf("source", "status", "fallbackReason"), encoded.keys)
+        assertEquals("tts_timeout", encoded["fallbackReason"]!!.jsonPrimitive.content)
+    }
+
+    @Test
+    fun `a fallback voice decodes its reason and has no copy`() {
+        // 降级行：没有可播的声音（四个副本键全缺席），原因原样留在 `fallbackReason` 里——
+        // 本端**不映射、不猜闭集**（取值集合后端尚未定稿），显示层原样小字。
+        val body = """
+            {"id":"msg-10","sessionId":"web","role":"user","content":"想跟你说句话",
+             "createdAt":1700000000009,
+             "voice":{"source":"tts","status":"failed","fallbackReason":"tts_timeout"}}
+        """.trimIndent()
+
+        val voice = decode(body).voice!!
+        assertEquals(VoiceSource.TTS, voice.source)
+        assertEquals(VoiceStatus.FAILED, voice.status)
+        assertEquals("tts_timeout", voice.fallbackReason)
+        assertNull("降级行没有可播的声音", voice.name)
+        assertNull(voice.mime)
+        assertNull(voice.size)
+        assertNull(voice.url)
+    }
+
+    @Test
+    fun `encoding a voice with no copy omits the nullable keys`() {
+        // `explicitNulls = false`（与后端 `omitempty` 同一口径）：无副本时那四个键**不写出来**，
+        // 而不是写成 `null`——否则服务端与别的客户端会看到一个「有键但值是 null」的陌生形状。
+        val encoded = json.encodeToJsonElement(
+            VoiceDto.serializer(),
+            VoiceDto(source = VoiceSource.PLATFORM, status = VoiceStatus.TRANSCRIBED),
+        ).jsonObject
+
+        assertEquals(setOf("source", "status"), encoded.keys)
+        assertEquals(VoiceSource.PLATFORM, encoded["source"]!!.jsonPrimitive.content)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/repository/MediaRepositoryTest.kt

@@ -0,0 +1,205 @@
+package top.yeij.cyrene.data.repository
+
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import kotlinx.coroutines.runBlocking
+import org.junit.After
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.MediaApi
+import top.yeij.cyrene.domain.chat.voicePlaybackFailureMessage
+import java.net.InetSocketAddress
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+
+/**
+ * `GET /api/v1/media/{name}` 的**线级**行为：真 OkHttp + 真 Retrofit + JDK 自带的 HTTP 服务端
+ * （与 `DocumentRepositoryTest` / `ImageCacheTest` 同一手法，不引新依赖）。
+ *
+ * 形状与状态码来源：契约 **v0.79** 的 §1.2 **U19** 一行（`200` / `206` / `304` / `401` / `403` /
+ * `404` / `416`；`Content-Type` 是音频类型；`404 media_not_found`）与 §4.5。
+ * **没有真实抓包**：这里的响应是按契约逐条手写的。
+ *
+ * 要证明的四件事：
+ * 1. 请求真的发到**服务端给的那条路径**（`/api/v1/media/<name>`；本端一个字都不拼）；
+ * 2. **必须带 `Authorization: Bearer`**（U19 是 `owner|admin` 端点：语音是私密内容）；
+ * 3. `200` 回的是**字节本身**（不是 JSON 信封），且一个字不改；
+ * 4. `404 media_not_found` / `401` / 非信封错误体 / 0 字节都折成可分支的失败，
+ *    **0 字节不算成功**（那会让下一次播放「命中缓存」一份什么都没有的文件）。
+ */
+class MediaRepositoryTest {
+
+    private val backend = FakeMediaBackend()
+
+    @After
+    fun tearDown() {
+        backend.close()
+    }
+
+    private fun repository() = MediaRepository(
+        ApiClientFactory.create(
+            baseUrl = backend.baseUrl,
+            service = MediaApi::class.java,
+            tokenProvider = { TOKEN },
+        ),
+    )
+
+    /** 一段假的音频字节：这里只关心「字节原样过」，不关心它是不是真能解码。 */
+    private val bytes = ByteArray(64) { it.toByte() }
+
+    @Test
+    fun `a copy is fetched from the path the server gave, with a bearer token`() = runBlocking {
+        backend.reply(200, bytes, "audio/ogg")
+
+        val fetched = repository().download(backend.mediaUrl(backend.name)).getOrThrow()
+
+        assertArrayEquals(bytes, fetched)
+        val request = backend.lastRequest()
+        assertEquals("GET", request.method)
+        assertEquals(
+            "请求路径必须**逐字**是服务端给的 voice.url（客户端绝不自己拼）",
+            "/api/v1/media/${backend.name}",
+            request.path,
+        )
+        assertEquals("语音是私密内容：U19 要求 owner|admin，必须带 Bearer", "Bearer $TOKEN", request.authorization)
+    }
+
+    @Test
+    fun `a missing copy is reported as not found, not as an empty audio`() = runBlocking {
+        backend.reply(
+            404,
+            """{"error":{"code":"media_not_found","message":"media not found"}}""".toByteArray(),
+            "application/json",
+        )
+
+        val error = repository().download(backend.mediaUrl(backend.name)).exceptionOrNull()
+
+        assertTrue(error is CyreneException)
+        // 非法名字 / 穿越 / 不存在服务端统一同码（不给探测面）⇒ 用户看到的就是本端那一句
+        // 「服务端上已经没有这条语音了」（**不是**把 media not found 原样抖给用户）。
+        assertEquals("服务端上已经没有这条语音了", voicePlaybackFailureMessage(error!!))
+        assertNull(repository().download(backend.mediaUrl(backend.name)).getOrNull())
+    }
+
+    @Test
+    fun `a non envelope error body is not parsed as an envelope`() = runBlocking {
+        // 416（Range 不可满足）由 Go 标准库直写 text/plain + Content-Range，**不套** JSON 信封
+        // （契约 §0.3 / §4.5）⇒ 本端不许拿 error.code 去解析它，也不能因此崩。
+        backend.reply(416, "invalid range".toByteArray(), "text/plain")
+
+        val error = repository().download(backend.mediaUrl(backend.name)).exceptionOrNull()
+
+        assertTrue(error is CyreneException)
+        val mapped = (error as CyreneException).error
+        assertTrue(mapped is CyreneError.Server)
+        assertEquals(
+            "非信封响应不许编出一个 code，也不许炸",
+            "",
+            (mapped as CyreneError.Server).code,
+        )
+        assertEquals(416, mapped.httpStatus)
+    }
+
+    @Test
+    fun `an unauthorized response is mapped as unauthorized`() = runBlocking {
+        backend.reply(
+            401,
+            """{"error":{"code":"unauthorized","message":"no token"}}""".toByteArray(),
+            "application/json",
+        )
+
+        val error = repository().download(backend.mediaUrl(backend.name)).exceptionOrNull()
+
+        assertTrue((error as CyreneException).error is CyreneError.Unauthorized)
+    }
+
+    @Test
+    fun `an empty two hundred is a failure, never a cached empty file`() = runBlocking {
+        backend.reply(200, ByteArray(0), "audio/ogg")
+
+        val error = repository().download(backend.mediaUrl(backend.name)).exceptionOrNull()
+
+        assertEquals(
+            "0 字节必须判失败（否则下一次播放会「命中」一份什么都没有的文件）",
+            CyreneError.Local(CyreneError.LocalKind.Parse),
+            (error as CyreneException).error,
+        )
+    }
+
+    @Test
+    fun `a server that is not there fails and is classified as a local failure`() = runBlocking {
+        // 对端不在听（换服务器 / adb reverse 掉了）。
+        val dead = MediaRepository(
+            ApiClientFactory.create(
+                baseUrl = "http://127.0.0.1:1/",
+                service = MediaApi::class.java,
+                tokenProvider = { TOKEN },
+            ),
+        )
+
+        val error = dead.download("http://127.0.0.1:1/api/v1/media/${backend.name}").exceptionOrNull()
+
+        assertTrue(error is CyreneException)
+        // 只要求「是本地那一档」：具体是哪一种由系统决定，不逐条钉死。
+        assertTrue((error as CyreneException).error is CyreneError.Local)
+    }
+
+    private class FakeMediaBackend {
+
+        val name = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg"
+
+        private val requests = CopyOnWriteArrayList<Request>()
+        private var status = 200
+        private var body = ByteArray(0)
+        private var contentType = "audio/ogg"
+
+        private val server: HttpServer = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply {
+            executor = Executors.newFixedThreadPool(2)
+            createContext("/") { exchange -> handle(exchange) }
+            start()
+        }
+
+        val baseUrl: String = "http://127.0.0.1:${server.address.port}/"
+
+        fun mediaUrl(name: String): String = "${baseUrl}api/v1/media/$name"
+
+        fun reply(status: Int, body: ByteArray, contentType: String) {
+            this.status = status
+            this.body = body
+            this.contentType = contentType
+        }
+
+        fun lastRequest(): Request = requests.lastOrNull() ?: error("服务端一个请求都没收到")
+
+        fun close() = server.stop(0)
+
+        private fun handle(exchange: HttpExchange) {
+            requests += Request(
+                method = exchange.requestMethod,
+                path = exchange.requestURI.path,
+                authorization = exchange.requestHeaders.getFirst("Authorization"),
+            )
+            exchange.responseHeaders.add("Content-Type", contentType)
+            // 空体用 -1（不是 0）：0 会让标准库改用 chunked，那样「0 字节」这条用例测的就不是
+            // 我们想测的那件事了（见 ImageCacheTest 的同名手法）。
+            if (body.isEmpty()) {
+                exchange.sendResponseHeaders(status, -1)
+            } else {
+                exchange.sendResponseHeaders(status, body.size.toLong())
+            }
+            exchange.responseBody.use { it.write(body) }
+        }
+
+        data class Request(val method: String, val path: String, val authorization: String?)
+    }
+
+    private companion object {
+        const val TOKEN = "fake-token-42"
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/repository/MessageIncrementRepositoryTest.kt

@@ -0,0 +1,234 @@
+package top.yeij.cyrene.data.repository
+
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import kotlinx.coroutines.runBlocking
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.ApiClientFactory
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.SessionsApi
+import java.net.InetSocketAddress
+import java.util.concurrent.ConcurrentLinkedQueue
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+
+/**
+ * 增量追尾（W77 `MessageRepository.loadIncrement`）的**数据层**。
+ *
+ * 与 `MessageAfterRepositoryTest` 同一套做法（真 OkHttp + 真 Retrofit + JDK 自带的
+ * `com.sun.net.httpserver`，不引新依赖），只是假后端从「一份固定响应」换成**响应队列**：
+ * 追尾是一次循环，翻页语义只有在「第一页满、第二页空」这种**按次序**的响应下才验得出来。
+ *
+ * 断言分两类，都不看实现细节：
+ * - **线上证据**：每次请求的原始 URI（`after=` 只能有一个值，且随游标前进）、请求次数；
+ * - **结论**：[MessageIncrement.complete] 与 `cursor` —— 这两项是调用方决定「要不要回落整表」的
+ *   唯一依据，错了就是红点做小或做多。
+ */
+class MessageIncrementRepositoryTest {
+
+    private val backend = FakeMessagesBackend()
+
+    @After
+    fun tearDown() {
+        backend.close()
+    }
+
+    private fun repository() = MessageRepository(
+        ApiClientFactory.create(baseUrl = backend.baseUrl, service = SessionsApi::class.java),
+    )
+
+    @Test
+    fun `a short page is the tail and only the forward cursor goes on the wire`() = runBlocking {
+        backend.enqueue(200, """{"data":[${message("m1", 100)}, ${message("m2", 200)}]}""")
+
+        val increment = repository().loadIncrement("web", after = 100).getOrThrow()
+
+        val uri = backend.uris.single()
+        assertTrue(uri, uri.contains("after=100"))
+        assertTrue(uri, uri.contains("limit=50"))
+        assertFalse(uri, uri.contains("before="))
+        assertFalse(uri, uri.contains("q="))
+        // 不满一页 ⇒ 真的追到尾巴了，游标停在最新一条。
+        assertTrue(increment.complete)
+        assertEquals(200L, increment.cursor)
+        assertEquals(listOf("m1", "m2"), increment.messages.map { it.id })
+    }
+
+    @Test
+    fun `an empty first page is a clean tail`() = runBlocking {
+        backend.enqueue(200, """{"data":[]}""")
+
+        val increment = repository().loadIncrement("web", after = 300).getOrThrow()
+
+        // 第一页就空 ⇒ 一条新消息都没有，没有可少给的：这是真的追到尾巴，游标原地不动。
+        assertEquals(1, backend.uris.size)
+        assertTrue(backend.uris.single(), backend.uris.single().contains("after=300"))
+        assertTrue(increment.complete)
+        assertEquals(300L, increment.cursor)
+        assertTrue(increment.messages.isEmpty())
+    }
+
+    @Test
+    fun `an empty page after a full page is not proof of a clean tail`() = runBlocking {
+        backend.enqueue(200, """{"data":[${message("m1", 100)}, ${message("m2", 200)}]}""")
+        backend.enqueue(200, """{"data":[]}""")
+
+        val increment = repository().loadIncrement("web", after = 0, pageSize = 2).getOrThrow()
+
+        // 满页 ⇒ 多问一次，第二次拿到空页。但客户端**分不出**这次空页是「干净的尾巴」还是
+        // 「空页底下还压着同一毫秒的几条」：服务端只给严格 `> cursor`，被页边界劈开的那一毫秒
+        // 再也追不回来。分不出来就只能说「没追完」，把「要不要回落整表」交回调用方。
+        assertEquals(2, backend.uris.size)
+        assertTrue(backend.uris[1], backend.uris[1].contains("after=200"))
+        assertFalse(increment.complete)
+        assertEquals(200L, increment.cursor)
+        assertEquals(listOf("m1", "m2"), increment.messages.map { it.id })
+    }
+
+    @Test
+    fun `a short page after a full page is not proof of a clean tail either`() = runBlocking {
+        // 页宽 2、积压 m1@500 / m2@500 / m3@500 / m4@600。第一页给 m1、m2 —— LIMIT 恰好把 500 那一
+        // 毫秒劈开；第二页 after=500 只能给 > 500 的，于是 [m4@600]、不满页。不满只证明「> 500 的行
+        // 就这一条」，对切点那一毫秒还有没有行一无所知：m3@500 既不 > 500，也就永远拿不到。
+        // 空页档与不满页档是同一个洞的两个出口，都要说「没追完」。
+        backend.enqueue(200, """{"data":[${message("m1", 500)}, ${message("m2", 500)}]}""")
+        backend.enqueue(200, """{"data":[${message("m4", 600)}]}""")
+
+        val increment = repository().loadIncrement("web", after = 0, pageSize = 2).getOrThrow()
+
+        assertEquals(2, backend.uris.size)
+        assertTrue(backend.uris[1], backend.uris[1].contains("after=500"))
+        assertFalse(increment.complete)
+        assertEquals(600L, increment.cursor)
+        assertEquals(listOf("m1", "m2", "m4"), increment.messages.map { it.id })
+    }
+
+    @Test
+    fun `a full page stuck on one millisecond is reported as incomplete`() = runBlocking {
+        // 真后端的形状：m1 / m2 / m3 三条落在同一毫秒，页宽 2。第一页给 m1、m2，第二页问
+        // `after=500` —— 严格 `>` 下后端只会回空页，m3@500 永远拿不到（这里不入队 m3：队列里
+        // 那份空响应就是真后端在 `after=500` 时会给的答案）。
+        backend.enqueue(200, """{"data":[${message("m1", 500)}, ${message("m2", 500)}]}""")
+        backend.enqueue(200, """{"data":[]}""")
+
+        val increment = repository().loadIncrement("web", after = 100, pageSize = 2).getOrThrow()
+
+        assertFalse(increment.complete)
+        // 游标停在那一毫秒（推不动就不装作推得动）。
+        assertEquals(500L, increment.cursor)
+        assertEquals(listOf("m1", "m2"), increment.messages.map { it.id })
+        // 线上证据：第二次真的带上了 `after=500`，即「m3 拿不到」的那一问。
+        assertEquals(2, backend.uris.size)
+        assertTrue(backend.uris[1], backend.uris[1].contains("after=500"))
+    }
+
+    @Test
+    fun `the page budget stops the chase instead of chasing forever`() = runBlocking {
+        // 永远满页：预算只有 1 页时必须停下来并如实说「没追完」。
+        backend.enqueue(200, """{"data":[${message("m1", 100)}, ${message("m2", 200)}]}""")
+
+        val increment = repository()
+            .loadIncrement("web", after = 0, pageSize = 2, maxPages = 1)
+            .getOrThrow()
+
+        assertEquals(1, backend.uris.size)
+        assertFalse(increment.complete)
+        assertEquals(200L, increment.cursor)
+    }
+
+    @Test
+    fun `a session deleted elsewhere surfaces as session_not_found with 404`() = runBlocking {
+        backend.enqueue(
+            404,
+            """{"error":{"code":"session_not_found","message":"session \"web:gone\" not found"}}""",
+        )
+
+        val error = repository().loadIncrement("web:gone", after = 0).exceptionOrNull() as CyreneException
+
+        val server = error.error as CyreneError.Server
+        assertEquals("session_not_found", server.code)
+        assertEquals(404, server.httpStatus)
+    }
+
+    @Test
+    fun `one increment costs one request and k messages instead of the whole table`() = runBlocking {
+        // 10 个会话的整表长什么样（每条一行预览 + 未读计数）：这是被换掉的那条路。
+        val wholeTable = """{"data":[${sessions(10)}]}"""
+        backend.enqueue(200, """{"data":[${message("new", 9_000)}]}""")
+
+        val increment = repository().loadIncrement("web", after = 8_000).getOrThrow()
+
+        assertEquals(1, backend.uris.size)
+        assertEquals(1, increment.messages.size)
+        assertTrue(increment.complete)
+        // 量级证据：增量回的字节数远小于整表（这里只有一条新消息 vs 十行会话预览）。
+        val incrementBytes = backend.responseBytes.single()
+        assertTrue(
+            "increment=$incrementBytes wholeTable=${wholeTable.toByteArray().size}",
+            incrementBytes * 4 < wholeTable.toByteArray().size,
+        )
+    }
+
+    /** 一条 `GET /messages` 形状的消息（字段与 `HistoryMessageDto` 对齐，只留断言用得到的）。 */
+    private fun message(id: String, createdAt: Long): String =
+        """{"id":"$id","sessionId":"web","role":"user","content":"内容","createdAt":$createdAt}"""
+
+    /** 一段 `GET /sessions` 形状的会话行（约 60 rune 预览 + 未读计数），只用于量级对比。 */
+    private fun sessions(count: Int): String = (1..count).joinToString(",") { i ->
+        val preview = "这是第 $i 个会话的最后一条消息预览，长度大致与真实数据同量级，用来量字节数。"
+        """{"id":"s$i","type":"secondary","title":"会话 $i","createdAt":${i * 1000},""" +
+            """"pinned":false,"personaId":null,"unreadCount":$i,""" +
+            """"lastMessage":{"id":"p$i","sessionId":"s$i","role":"assistant",""" +
+            """"content":"$preview","createdAt":${i * 1000}}}"""
+    }
+
+    /**
+     * 按**入队顺序**逐次回响应的假后端：追尾是一次循环，固定响应验不出翻页。
+     *
+     * 队列见底时重复最后一份 —— 这样「永远满页」那种用例只需要入队一次。
+     */
+    private inner class FakeMessagesBackend : AutoCloseable {
+
+        private val server = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply {
+            executor = Executors.newFixedThreadPool(2)
+            createContext("/", ::handle)
+            start()
+        }
+
+        val baseUrl: String get() = "http://127.0.0.1:${server.address.port}/"
+
+        /** 每次请求的原始 URI（含 query），按到达顺序。 */
+        val uris = CopyOnWriteArrayList<String>()
+
+        /** 每次响应体（UTF-8）的字节数，按到达顺序 —— 量化对比用。 */
+        val responseBytes = CopyOnWriteArrayList<Int>()
+
+        private val queue = ConcurrentLinkedQueue<Pair<Int, String>>()
+
+        private val last = java.util.concurrent.atomic.AtomicReference(200 to """{"data":[]}""")
+
+        fun enqueue(status: Int, body: String) {
+            queue += status to body
+        }
+
+        private fun handle(exchange: HttpExchange) {
+            uris += exchange.requestURI.toString()
+            val (status, body) = queue.poll() ?: last.get()
+            last.set(status to body)
+            val bytes = body.toByteArray()
+            responseBytes += bytes.size
+            exchange.responseHeaders.add("Content-Type", "application/json")
+            exchange.sendResponseHeaders(status, bytes.size.toLong())
+            exchange.responseBody.use { it.write(bytes) }
+        }
+
+        override fun close() {
+            server.stop(0)
+        }
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/repository/MessageMergeTest.kt

@@ -1,6 +1,7 @@
 package top.yeij.cyrene.data.repository
 
 import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
 import org.junit.Assert.assertEquals
 import org.junit.Test
 
@@ -86,6 +87,35 @@ class MessageMergeTest {
         assertEquals(listOf("m3"), idsOf(incoming))
     }
 
+    @Test
+    fun `a later copy carrying voice wins over the earlier copy of the same message`() {
+        // 同一条消息会从**多路**到本端：落库帧、握手 `history` 回放、REST 分页、编辑帧。
+        // 按 id 合并时「新到的那一份胜出」是这几路唯一的收口规则——不然后到的那份白到。
+        // 契约 v0.97 之后 `voice` **每一条路都带**（后端 M44 `fb55769`：落库顺序 INSERT →
+        // 写 voice 列 → notify），所以这条规则**不再是**「语音升级的唯一通路」；
+        // 但它照旧必需：谁哪天把「incoming 胜出」改成「保留旧的」，编辑过的正文与任何后补字段
+        // 都会永远不生效。
+        val withoutVoice = msg("m1", 100, content = "明天几点出发")
+        val withVoice = withoutVoice.copy(
+            voice = VoiceDto(
+                source = "asr",
+                status = "transcribed",
+                name = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg",
+                mime = "audio/ogg",
+                size = 12_345,
+                durationMs = 3_200,
+                url = "/api/v1/media/a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg",
+            ),
+        )
+
+        val merged = mergeMessages(listOf(withoutVoice), listOf(withVoice))
+
+        assertEquals(1, merged.size)
+        assertEquals("m1", merged.single().id)
+        assertEquals("asr", merged.single().voice?.source)
+        assertEquals(3_200, merged.single().voice?.durationMs)
+    }
+
     private fun msgIn(sessionId: String, id: String) = HistoryMessageDto(
         id = id,
         sessionId = sessionId,

app/src/test/kotlin/top/yeij/cyrene/data/repository/VoiceStoreTest.kt

@@ -0,0 +1,187 @@
+package top.yeij.cyrene.data.repository
+
+import kotlinx.coroutines.runBlocking
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.domain.chat.VoiceAudio
+import java.io.File
+import java.nio.file.Files
+
+/**
+ * 「播放前取字节」这一层（[VoiceStore]）：地址怎么拼、缓存怎么命中、落哪儿、失败留不留残骸。
+ *
+ * 用真临时目录 + 一个假的下载器（`suspend (String) -> Result<ByteArray>`）跑完，不需要网络也不需要
+ * Android（[VoiceStore] 这一层的行为全是文件系统与地址拼接）。**真的走 HTTP** 那一半在
+ * [MediaRepositoryTest]（JDK 自带服务端 + 真 OkHttp/Retrofit）。
+ *
+ * 要钉住的六件事：
+ * 1. **请求地址 = 当前服务器地址 + 服务端给的相对路径**（`voice.url` 逐字保留，本端不拼路径）；
+ * 2. **重复播放一个请求都不发**（内容寻址 ⇒ 命中永不失效）；
+ * 3. **落盘位置是 `<cacheDir>/media/`**，不在 `documents/`（那是 FileProvider 唯一暴露出去的根，
+ *    本片不扩大暴露面）；
+ * 4. 名字不可信 / 地址拼不出来 ⇒ **如实失败且不发请求**（绝不退回「自己拼一条路径」）；
+ * 5. 下载失败**不留半截文件**（否则下一次会命中一份被截断的音频）；
+ * 6. 0 字节的残留当**未命中**（重新取），缓存目录写不进去则如实报缓存不可用。
+ */
+class VoiceStoreTest {
+
+    private lateinit var cacheRoot: File
+
+    @Before
+    fun setUp() {
+        cacheRoot = Files.createTempDirectory("cyrene-voice").toFile()
+    }
+
+    @After
+    fun tearDown() {
+        cacheRoot.deleteRecursively()
+    }
+
+    private val name = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg"
+
+    private val ogg = ByteArray(64) { it.toByte() }
+
+    private fun audio(name: String = this.name, url: String? = null) =
+        VoiceAudio(
+            name = name,
+            mime = "audio/ogg",
+            size = ogg.size.toLong(),
+            url = url ?: "/api/v1/media/$name",
+            durationMs = 3_200,
+        )
+
+    private fun store(
+        baseUrl: String = BASE_URL,
+        download: suspend (String) -> Result<ByteArray>,
+    ) = VoiceStore(
+        download = download,
+        cacheDir = cacheRoot,
+        baseUrlProvider = { baseUrl },
+    )
+
+    @Test
+    fun `the request goes to the current server plus the path the server gave`() = runBlocking {
+        val requested = mutableListOf<String>()
+        val store = store(download = { url -> requested += url; Result.success(ogg) })
+
+        val file = store.load(audio()).getOrThrow()
+
+        assertEquals(listOf("$BASE_URL/api/v1/media/$name"), requested)
+        // 落盘位置：`<cacheDir>/media/<存储名>`（不是 documents/ —— 那是 FileProvider 那一层）。
+        assertEquals(File(VoiceStore.directory(cacheRoot), name), file)
+        assertEquals(ogg.size.toLong(), file.length())
+    }
+
+    @Test
+    fun `playing the same copy twice asks the server only once`() = runBlocking {
+        var downloads = 0
+        val store = store(download = { downloads++; Result.success(ogg) })
+
+        val first = store.load(audio()).getOrThrow()
+        val second = store.load(audio()).getOrThrow()
+
+        assertEquals("名字由内容决定 ⇒ 命中一个请求都不发", 1, downloads)
+        assertEquals(first, second)
+    }
+
+    @Test
+    fun `a zero byte leftover is treated as a miss and refetched`() = runBlocking {
+        val leftover = File(VoiceStore.directory(cacheRoot), name)
+        leftover.parentFile!!.mkdirs()
+        leftover.writeBytes(ByteArray(0))
+        var downloads = 0
+        val store = store(download = { downloads++; Result.success(ogg) })
+
+        val file = store.load(audio()).getOrThrow()
+
+        assertEquals(1, downloads)
+        assertEquals(ogg.size.toLong(), file.length())
+    }
+
+    @Test
+    fun `an unusable server address fails without any request`() = runBlocking {
+        var downloads = 0
+        val store = store(baseUrl = "", download = { downloads++; Result.success(ogg) })
+
+        val result = store.load(audio())
+
+        assertTrue(result.exceptionOrNull() is VoiceUrlUnavailableException)
+        assertEquals("拼不出可信地址就如实失败，绝不自己拼一条", 0, downloads)
+    }
+
+    @Test
+    fun `a relative path that is not a media path never becomes a request`() = runBlocking {
+        var downloads = 0
+        val store = store(download = { downloads++; Result.success(ogg) })
+
+        val result = store.load(audio(url = "/api/v1/documents/$name"))
+
+        assertTrue(result.exceptionOrNull() is VoiceUrlUnavailableException)
+        assertEquals(0, downloads)
+    }
+
+    @Test
+    fun `an untrustworthy name is never turned into a cache path`() = runBlocking {
+        var downloads = 0
+        val store = store(download = { downloads++; Result.success(ogg) })
+
+        // 地址那一半照旧可信（服务端给的路径正常），不可信的是**存储名**自己：拼缓存路径的那一步
+        // 必须挡住它（否则能爬出 `cacheDir/media/`）。
+        val result = store.load(audio(name = "../../escape.ogg", url = "/api/v1/media/escape.ogg"))
+
+        assertEquals(
+            CyreneError.Local(CyreneError.LocalKind.Parse),
+            (result.exceptionOrNull() as CyreneException).error,
+        )
+        assertEquals(0, downloads)
+        assertFalse("名字不可信时连缓存目录都不该被碰", VoiceStore.directory(cacheRoot).exists())
+    }
+
+    @Test
+    fun `a failed download leaves no half file for the next play to believe`() = runBlocking {
+        var attempted = 0
+        val failing = store(download = {
+            attempted++
+            Result.failure(CyreneException(CyreneError.Local(CyreneError.LocalKind.NoNetwork)))
+        })
+
+        val first = failing.load(audio())
+
+        assertTrue(first.isFailure)
+        val directory = VoiceStore.directory(cacheRoot)
+        assertTrue(
+            "失败不许留下任何文件（`.part` 临时文件也要清干净）",
+            !directory.exists() || directory.listFiles()!!.isEmpty(),
+        )
+
+        // 再点一次：真的重发（不是「命中一份空文件」）。
+        val retry = store(download = { attempted++; Result.success(ogg) }).load(audio()).getOrThrow()
+        assertEquals(2, attempted)
+        assertEquals(ogg.size.toLong(), retry.length())
+    }
+
+    @Test
+    fun `a cache directory that cannot be written is reported as such`() = runBlocking {
+        // 拿一个**普通文件**当缓存目录：建目录必然失败。
+        val blocked = File(cacheRoot, "blocked").apply { writeBytes("not a directory".toByteArray()) }
+        val store = VoiceStore(
+            download = { Result.success(ogg) },
+            cacheDir = blocked,
+            baseUrlProvider = { BASE_URL },
+        )
+
+        val result = store.load(audio())
+
+        assertTrue(result.exceptionOrNull() is DocumentCacheUnavailableException)
+    }
+
+    private companion object {
+        const val BASE_URL = "http://192.168.1.9:8080"
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/voice/SpeechClientTest.kt

@@ -0,0 +1,253 @@
+package top.yeij.cyrene.data.voice
+
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeoutOrNull
+import org.junit.After
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import java.io.File
+import java.net.InetSocketAddress
+import java.nio.file.Files
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+
+/**
+ * 「把一段文字念出来」的取字节层（[SpeechClient]）：发什么、收什么、落哪儿、失败算哪一档。
+ *
+ * 端到端跑**真 OkHttp + 真 Retrofit + 真 HTTP 服务端**（JDK 自带的 `com.sun.net.httpserver`，
+ * 与 [top.yeij.cyrene.data.api.RestAttemptClientTest] 同一套做法，不引任何新依赖），落盘用真临时目录。
+ *
+ * ## 它钉住的六条事实
+ * 1. **产物恒为 WAV，按字节嗅探**：`200` 却回 JSON 信封（网关/反代把错误包了一层的典型形态）
+ *    绝不喂给 `MediaPlayer`，如实判 [SpeechNotAudioException]。这一条刻意让假端点回
+ *    `Content-Type: audio/wav` —— 头是**不可信**的，判据只落在字节上。
+ * 2. **0 字节不算「一段静音」**，判解析失败（与 `MediaRepository` 同一口径）。
+ * 3. **落盘位置是 `<cacheDir>/media/tts_<hash>.wav`**：不在 `documents/`（那是 FileProvider 唯一
+ *    暴露出去的根），名字按 `(baseUrl, sessionId, text)` 内容寻址。
+ * 4. **同一段文字一个请求都不发第二次**（用请求计数断言，不是「文件存在」）。
+ * 5. **空文本连请求都不发**：服务端对它只会回 `400`，本端没必要走一次往返。
+ * 6. **非 2xx 保留服务端那句 `code`**：`tts_persona_unmapped` / `tts_no_character` 这两档的文案
+ *    完全不同，折成一句话就说不清了。
+ * 7. **换服务器不是命中**（P2-2）：同一个 `(sessionId, text)` 在另一台服务器上可能是另一个声音，
+ *    而地址末尾多写一个 `/` 必须**还是**同一份缓存（`trimEnd('/')` 归一）。
+ */
+class SpeechClientTest {
+
+    private lateinit var cacheRoot: File
+    private val backend = FakeSpeechBackend()
+
+    @Before
+    fun setUp() {
+        cacheRoot = Files.createTempDirectory("cyrene-tts").toFile()
+    }
+
+    @After
+    fun tearDown() {
+        backend.close()
+        cacheRoot.deleteRecursively()
+    }
+
+    /** 与生产同形：令牌由 [top.yeij.cyrene.data.api.ApiClientFactory] 的拦截器注入。 */
+    private fun client(baseUrl: String = backend.baseUrl) = SpeechClient(
+        baseUrlProvider = { baseUrl },
+        tokenProvider = { TOKEN },
+        cacheDir = cacheRoot,
+    )
+
+    private suspend fun speak(
+        client: SpeechClient = client(),
+        text: String = "你好",
+        sessionId: String? = SESSION_ID,
+    ): Result<File>? = withTimeoutOrNull(TIMEOUT_MILLIS) { client.speak(text, sessionId) }
+
+    @Test
+    fun `a real wav lands under media as a tts named file and comes back playable`() = runBlocking {
+        backend.reply(200, WAV)
+
+        val file = speak()!!.getOrThrow()
+
+        assertEquals("media", file.parentFile?.name)
+        assertTrue("缓存名该带 tts_ 前缀，实际 ${file.name}", file.name.startsWith("tts_"))
+        assertTrue("缓存名该是 .wav，实际 ${file.name}", file.name.endsWith(".wav"))
+        assertArrayEquals(WAV, file.readBytes())
+        // 令牌确实是本层挂上去的那一条（owner Bearer，不是 API Key）。
+        assertEquals("Bearer $TOKEN", backend.headers.single()["authorization"])
+    }
+
+    @Test
+    fun `the same text a second time sends no request at all`() = runBlocking {
+        backend.reply(200, WAV)
+
+        val first = speak()!!.getOrThrow()
+        val second = speak()!!.getOrThrow()
+
+        assertEquals(first, second)
+        assertEquals("第二次该命中缓存，一个请求都不发", 1, backend.requestLines.size)
+    }
+
+    @Test
+    fun `a json envelope served with 200 is rejected instead of fed to the player`() = runBlocking {
+        // 头照写 audio/wav —— 恰恰证明判据不能落在 Content-Type 上。
+        backend.reply(200, """{"error":{"code":"tts_failed","message":"合成失败"}}""".toByteArray())
+
+        val failure = speak()!!.exceptionOrNull()
+
+        assertTrue("200 却不是 WAV 该判 SpeechNotAudioException，实际 $failure", failure is SpeechNotAudioException)
+        // 绝不落盘：一份不是音频的缓存会在下一次「命中」并被喂给播放器。
+        assertNoCacheFile()
+    }
+
+    @Test
+    fun `an empty body is a parse failure rather than a silent clip`() = runBlocking {
+        backend.reply(200, ByteArray(0))
+
+        val failure = speak()!!.exceptionOrNull()
+
+        assertEquals(CyreneError.Local(CyreneError.LocalKind.Parse), (failure as CyreneException).error)
+        assertNoCacheFile()
+    }
+
+    @Test
+    fun `a persona without a voice keeps the server code instead of flattening it`() = runBlocking {
+        backend.reply(500, """{"error":{"code":"$CODE_PERSONA_UNMAPPED","message":"人格没有发音人映射"}}""".toByteArray())
+
+        val failure = speak()!!.exceptionOrNull() as CyreneException
+
+        val server = failure.error as CyreneError.Server
+        assertEquals(500, server.httpStatus)
+        assertEquals(CODE_PERSONA_UNMAPPED, server.code)
+        assertNoCacheFile()
+    }
+
+    @Test
+    fun `blank text fails locally without a round trip`() = runBlocking {
+        val failure = speak(text = "   \n ")!!.exceptionOrNull()
+
+        assertEquals(CyreneError.Local(CyreneError.LocalKind.Parse), (failure as CyreneException).error)
+        assertTrue("空文本不该发请求", backend.requestLines.isEmpty())
+    }
+
+    @Test
+    fun `two sessions with the same text are two different clips`() = runBlocking {
+        backend.reply(200, WAV)
+
+        val web = speak(sessionId = "web")!!.getOrThrow()
+        val phone = speak(sessionId = "phone")!!.getOrThrow()
+
+        // 发音人由会话的生效人格决定 ⇒ 同一段文字在不同会话里可以是两个声音，缓存名必须分开。
+        assertFalse("不同会话的同一段文字不该撞同一个缓存名", web == phone)
+        assertEquals(2, backend.requestLines.size)
+    }
+
+    @Test
+    fun `the same session and text on another server is not a cache hit`() = runBlocking {
+        backend.reply(200, WAV)
+        val here = speak(client = client(baseUrl = backend.baseUrl))!!.getOrThrow()
+
+        // 换一台服务器：会话 id 与文字都一样，但那边的人格映射 / 发音人 / 合成实现是它自己的。
+        val elsewhere = FakeSpeechBackend()
+        try {
+            elsewhere.reply(200, WAV)
+            val there = speak(client = client(baseUrl = elsewhere.baseUrl))!!.getOrThrow()
+
+            assertFalse("换服务器后不该命中上一台合成的那份 WAV（那是别人的声音）", here == there)
+            assertEquals("这台各请求一次", 1, backend.requestLines.size)
+            assertEquals("那台也请求了一次", 1, elsewhere.requestLines.size)
+        } finally {
+            elsewhere.close()
+        }
+    }
+
+    @Test
+    fun `a trailing slash on the base url is the same server`() = runBlocking {
+        backend.reply(200, WAV)
+
+        val withSlash = speak(client = client(baseUrl = backend.baseUrl))!!.getOrThrow()
+        val without = speak(client = client(baseUrl = backend.baseUrl.trimEnd('/')))!!.getOrThrow()
+
+        // 地址末尾多写一个 `/` 不该让整份合成缓存作废（归一在 `cacheName` 里）。
+        assertEquals(withSlash, without)
+        assertEquals(1, backend.requestLines.size)
+    }
+
+    @Test
+    fun `wav sniffing looks at the bytes and nothing else`() {
+        assertTrue(isWavBytes(WAV))
+        assertFalse("11 字节连 RIFF 头都不完整", isWavBytes(WAV.copyOf(11)))
+        assertFalse("空数组", isWavBytes(ByteArray(0)))
+        // RIFX 是 RIFF 的大端变体，不是本端承诺的产物形状。
+        assertFalse("RIFX 不是 WAVE", isWavBytes("RIFX".toByteArray() + WAV.copyOfRange(4, WAV.size)))
+        // 头对了但第 8 字节起不是 WAVE：RIFF 容器里装的是别的东西。
+        assertFalse("RIFF 里不是 WAVE", isWavBytes("RIFF".toByteArray() + ByteArray(WAV.size - 4)))
+    }
+
+    private fun assertNoCacheFile() {
+        val media = File(cacheRoot, "media")
+        val leftovers = media.listFiles()?.filter { it.name.startsWith("tts_") }.orEmpty()
+        assertTrue("失败时不该留下缓存文件，实际 $leftovers", leftovers.isEmpty())
+    }
+
+    /** 照着 `reply(...)` 回话的假 speech 端点：记下**请求行原文**与请求头原文。 */
+    private inner class FakeSpeechBackend : AutoCloseable {
+
+        private val server = HttpServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply {
+            executor = Executors.newFixedThreadPool(2)
+            createContext("/api/v1/audio/speech", ::handle)
+            start()
+        }
+
+        val baseUrl: String get() = "http://127.0.0.1:${server.address.port}/"
+
+        val requestLines = CopyOnWriteArrayList<String>()
+
+        /** 请求头按**小写键**记录：JDK 的 `Headers` 会把键规范化成 `X-Api-Version` 这种形状。 */
+        val headers = CopyOnWriteArrayList<Map<String, String>>()
+
+        @Volatile
+        private var status = 200
+
+        @Volatile
+        private var payload = WAV
+
+        fun reply(status: Int, body: ByteArray) {
+            this.status = status
+            this.payload = body
+        }
+
+        private fun handle(exchange: HttpExchange) {
+            requestLines += "${exchange.requestMethod} ${exchange.requestURI}"
+            headers += exchange.requestHeaders.entries.associate { it.key.lowercase() to it.value.joinToString(", ") }
+            exchange.requestBody.readBytes()
+            // 一律回 audio/wav：判据必须落在字节上，本测试**故意**让头说谎。
+            exchange.responseHeaders.add("Content-Type", "audio/wav")
+            exchange.sendResponseHeaders(status, payload.size.toLong())
+            exchange.responseBody.use { it.write(payload) }
+        }
+
+        override fun close() {
+            server.stop(0)
+        }
+    }
+
+    private companion object {
+        const val SESSION_ID = "web"
+        const val TOKEN = "test-token"
+        const val TIMEOUT_MILLIS = 10_000L
+        const val CODE_PERSONA_UNMAPPED = "tts_persona_unmapped"
+
+        /** 一段形状正确的最小 WAV（`RIFF` + 长度 + `WAVE` + 40 字节的 `fmt `/`data` 区）。 */
+        val WAV: ByteArray =
+            "RIFF".toByteArray(Charsets.US_ASCII) +
+                byteArrayOf(36, 0, 0, 0) +
+                "WAVE".toByteArray(Charsets.US_ASCII) +
+                ByteArray(40)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/ws/WsEventPersistedProactiveTest.kt

@@ -0,0 +1,114 @@
+package top.yeij.cyrene.data.ws
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 落库帧上的 `proactive` 判据键（W53N）。
+ *
+ * 这是 W53N 的**第一半**：她主动说的话有两条线上路径，其中走 IM 桥那条会把判据打在落库帧上，
+ * 而这个键此前被本端**整个丢掉**了（`PersistedData` 只解 `message`，生产 `Json` 又是
+ * `ignoreUnknownKeys = true` ⇒ 既不解也不报错）。丢掉它不报任何错，只是「她主动说的话」在客户端
+ * 少了一半入口——通知永远不会为那条路弹。
+ *
+ * 另外两件事也必须在这里钉住，它们各自都足以让整帧消失或让普通消息响起来：
+ * 1. 这个键**缺席**时必须是普通消息（主人只批了 proactive 这一档，普通消息绝不弹）；
+ * 2. 这个键**形状不认识**时，帧照旧成形（宁可判成「不是 proactive」，也不能让整帧消失——
+ *    那会连普通消息的落库广播一起弄没）。
+ */
+class WsEventPersistedProactiveTest {
+
+    private fun frame(data: String) = """{"type":"message_persisted","sessionId":"web","data":$data}"""
+
+    private val row = """
+        {"id":"1371","sessionId":"web","role":"assistant","content":"记得喝水哦","createdAt":1791212405123}
+    """.trimIndent()
+
+    @Test
+    fun `a proactive flag inside the payload is read back`() {
+        val event = WsEvent.parse(
+            frame("""{"proactive":true,"message":$row}"""),
+        ) as WsEvent.MessagePersisted
+
+        assertTrue("判据键必须真的读回来——这是整批任务的前提", event.proactive)
+        assertEquals("1371", event.message?.id)
+        assertEquals("记得喝水哦", event.message?.content)
+    }
+
+    @Test
+    fun `a proactive flag on the frame shell is read too`() {
+        // 契约说的是「帧顶带它」，而没说清是帧壳还是载荷。**猜错的方向是这个功能静默失效**，
+        // 所以两层都认（这里钉住帧壳那一层）。
+        val event = WsEvent.parse(
+            """{"type":"message_persisted","sessionId":"web","proactive":true,"data":{"message":$row}}""",
+        ) as WsEvent.MessagePersisted
+
+        assertTrue(event.proactive)
+        assertEquals("1371", event.message?.id)
+    }
+
+    @Test
+    fun `a string shaped flag is accepted instead of killing the frame`() {
+        // 同 `proactive_message` 的 `timestamp` 那条教训：线上形状只要不是客户端声明的那一种，
+        // 严格解码就会抛、被 `parse` 的 runCatching 吞成 null ⇒ **整帧消失**（连普通消息都受影响）。
+        // 宽容读法把「不认识」折成「不是 proactive」，帧本身照旧成形。
+        val event = WsEvent.parse(
+            frame("""{"proactive":"true","message":$row}"""),
+        ) as WsEvent.MessagePersisted
+
+        assertTrue(event.proactive)
+        assertEquals("1371", event.message?.id)
+    }
+
+    @Test
+    fun `an absent flag means an ordinary message`() {
+        // 硬边界：普通消息绝不弹通知。缺席是**唯一**的现实形状（老服务端 / 非 proactive 路由）。
+        val event = WsEvent.parse(frame("""{"message":$row}""")) as WsEvent.MessagePersisted
+
+        assertFalse(event.proactive)
+        assertEquals("1371", event.message?.id)
+    }
+
+    @Test
+    fun `a false flag means an ordinary message`() {
+        val event = WsEvent.parse(
+            frame("""{"proactive":false,"message":$row}"""),
+        ) as WsEvent.MessagePersisted
+
+        assertFalse(event.proactive)
+    }
+
+    @Test
+    fun `an unrecognised flag shape keeps the frame and reads as not proactive`() {
+        // 形状漂移（对象 / 数字 / null）一律按假：这一侧判错只会漏一次通知，
+        // 判成真会给普通消息弹一条通知——方向必须偏「不打扰」。
+        listOf("""{"proactive":{"v":1},"message":$row}""", """{"proactive":1,"message":$row}""", """{"proactive":null,"message":$row}""")
+            .forEach { data ->
+                val event = WsEvent.parse(frame(data)) as WsEvent.MessagePersisted
+                assertFalse("这条形状该被按成普通消息：$data", event.proactive)
+                assertNotNull("整帧不许因为一个判据键消失：$data", event.message)
+            }
+    }
+
+    @Test
+    fun `the frame still decodes when the payload is missing entirely`() {
+        val event = WsEvent.parse("""{"type":"message_persisted","sessionId":"web"}""") as WsEvent.MessagePersisted
+
+        assertFalse(event.proactive)
+        assertNull(event.message)
+    }
+
+    @Test
+    fun `channel persisted frames still decode`() {
+        // 两条帧共用一个载荷类型：给 `PersistedData` 加字段不许影响 IM 日志页那条路。
+        val event = WsEvent.parse(
+            """{"type":"channel_persisted","sessionId":"sess-9","data":{"message":{"id":"m-1","sessionId":"sess-9","role":"user","content":"在吗","createdAt":1}}}""",
+        ) as WsEvent.ChannelPersisted
+
+        assertEquals("m-1", event.message?.id)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/ws/WsEventPersistedVoiceTest.kt

@@ -0,0 +1,167 @@
+package top.yeij.cyrene.data.ws
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.domain.chat.hasVoice
+import top.yeij.cyrene.domain.chat.isVoiceMessage
+import top.yeij.cyrene.domain.chat.voiceAudio
+import top.yeij.cyrene.domain.chat.voiceFallbackNote
+
+/**
+ * 落库帧上的 `voice`（契约 **v0.97**，后端 M44 `fb55769`；`failed` / `fallbackReason` 见 M57-M59）。
+ *
+ * ## 这条钉子钉的是「撤掉兜底」之后剩下的判据
+ * W73 时期的旧口径是「`voice` 只在四个 REST 读取面填充，实时帧与握手回放缺席 ⇒ 实时到达的语音
+ * 先按普通文本显示，等下一次拉取自动升级」。后端把落库顺序改成 **INSERT → 写 `voice` 列 →
+ * notify** 之后，语音消息的**第一条** `message_persisted` / `channel_persisted` 帧就带 `voice`，
+ * 于是那条兜底**整条撤掉**。判据剩下两条：`voice` 键存在（`hasVoice`）**且** `status != "failed"`
+ * （`isVoiceMessage`）—— 降级行没有可播的声音，画成语音形态就是给一个点下去必然失败的按钮。
+ *
+ * 钉在这里的四件事，任何一件被将来的改动破坏都会让语音消息静默退回纯文本（或反过来，
+ * 把一条降级行画成播不出来的语音）：
+ * 1. `message_persisted` 载荷里的 `voice` **真的被解出来**（`PersistedData` 只解 `message`，
+ *    而生产 `Json` 是 `ignoreUnknownKeys = true` ⇒ 漏解不报错，只是判据永远为假）；
+ * 2. `channel_persisted` 同样——两条帧共用一个载荷类型；
+ * 3. `voice` 键**缺席**仍是「不是语音」（不为「实时帧可能不带」留任何分支）；
+ * 4. `status = "failed"` 的降级行**不是**语音形态，但也不是纯文本：正文 + 一行降级小标
+ *    （`voiceFallbackNote`），且 `voiceAudio` 为 null ⇒ 没有播放控件。
+ *
+ * 帧形状照服务端实现：`data:{message:{…}}`（`channel_persisted` 同形；与 `message_edited`
+ * 那条「`data` 就是消息本身」**不同**）。
+ */
+class WsEventPersistedVoiceTest {
+
+    private fun frame(type: String, data: String) = """{"type":"$type","sessionId":"web","data":$data}"""
+
+    private val copyName = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg"
+
+    /** 一条真实的入站语音行：转写文本在 `content` 里，`voice` 四键齐全（有音频副本）。 */
+    private val voiceRow = """
+        {"id":"1371","sessionId":"web","role":"user","content":"明天几点出发",
+         "voice":{"source":"asr","status":"transcribed","name":"$copyName","mime":"audio/ogg",
+                  "size":12345,"durationMs":3200,"url":"/api/v1/media/$copyName"},
+         "createdAt":1791088571785}
+    """.trimIndent().replace("\n", " ")
+
+    /** 微信那条真实的无副本形状：平台自带转写 ⇒ 只有 🎤 标记，四个音频键全缺席。 */
+    private val noCopyRow = """
+        {"id":"1372","sessionId":"web","role":"user","content":"晚上回来吃饭吗",
+         "voice":{"source":"platform","status":"transcribed"},
+         "createdAt":1791088571786}
+    """.trimIndent().replace("\n", " ")
+
+    private val plainRow = """
+        {"id":"1373","sessionId":"web","role":"user","content":"在的","createdAt":1791088571787}
+    """.trimIndent().replace("\n", " ")
+
+    /** 我们自己合成的出站语音（后端 M57-M59）：与入站语音**同形**，走同一条渲染路径。 */
+    private val ttsRow = """
+        {"id":"1375","sessionId":"web","role":"assistant","content":"早上好呀",
+         "voice":{"source":"tts","status":"transcribed","name":"$copyName","mime":"audio/ogg",
+                  "size":12345,"durationMs":3200,"url":"/api/v1/media/$copyName"},
+         "createdAt":1791088571789}
+    """.trimIndent().replace("\n", " ")
+
+    /** 合成降级那一行：`status = "failed"` + `fallbackReason`，四个副本键全缺席（没有可播的声音）。 */
+    private val fallbackRow = """
+        {"id":"1374","sessionId":"web","role":"assistant","content":"想跟你说句话",
+         "voice":{"source":"tts","status":"failed","fallbackReason":"tts_timeout"},
+         "createdAt":1791088571788}
+    """.trimIndent().replace("\n", " ")
+
+    @Test
+    fun `a persisted frame carries voice back to the decoder`() {
+        val event = WsEvent.parse(frame("message_persisted", """{"message":$voiceRow}""")) as WsEvent.MessagePersisted
+
+        val message = event.message!!
+        val voice = message.voice!!
+        assertEquals("asr", voice.source)
+        assertEquals("transcribed", voice.status)
+        assertEquals(copyName, voice.name)
+        assertEquals("audio/ogg", voice.mime)
+        assertEquals(12_345L, voice.size)
+        assertEquals(3_200, voice.durationMs)
+        assertEquals("/api/v1/media/$copyName", voice.url)
+        // 判据：键存在即语音——这条帧到达的那一刻就该是语音气泡，不需要任何后续拉取。
+        assertTrue("落库帧上的语音必须在第一帧就判成语音", isVoiceMessage(message))
+        assertEquals(copyName, voiceAudio(voice)?.name)
+    }
+
+    @Test
+    fun `a channel persisted frame carries voice too`() {
+        // 隔离会话那条帧与 message_persisted 共用 `PersistedData`：给载荷加字段不许只覆盖其中一条。
+        val event = WsEvent.parse(frame("channel_persisted", """{"message":$voiceRow}""")) as WsEvent.ChannelPersisted
+
+        val message = event.message!!
+        assertTrue(isVoiceMessage(message))
+        assertEquals(3_200, message.voice?.durationMs)
+    }
+
+    @Test
+    fun `a transcribed voice without an audio copy is still a voice message`() {
+        // 「是语音」与「能不能播」是两件事：判据只看键在不在，播放控件另看四键是否齐全。
+        val event = WsEvent.parse(frame("message_persisted", """{"message":$noCopyRow}""")) as WsEvent.MessagePersisted
+
+        val message = event.message!!
+        assertTrue(isVoiceMessage(message))
+        assertEquals("platform", message.voice?.source)
+        assertNull("没有副本就不许画播放控件", voiceAudio(message.voice!!))
+    }
+
+    @Test
+    fun `an absent voice key still means not a voice message`() {
+        // 判据只有一个方向上的推论：缺席 = 不是语音。这里刻意不留「实时帧可能不带，先按文本显示」
+        // 那条分支——M44 之后缺席就只意味着「这条本来就不是语音」。
+        val event = WsEvent.parse(frame("message_persisted", """{"message":$plainRow}""")) as WsEvent.MessagePersisted
+
+        assertNull(event.message?.voice)
+        assertFalse(isVoiceMessage(event.message!!))
+    }
+
+    @Test
+    fun `an edited frame keeps the voice of the message it replaces`() {
+        // 编辑帧的 `data` **就是**消息本身（没有 `message` 包一层），但它同样是 `voice` 的读面之一：
+        // 编辑正文不许把已渲染的语音气泡打回纯文本。
+        val event = WsEvent.parse(
+            """{"type":"message_edited","sessionId":"web","data":$voiceRow}""",
+        ) as WsEvent.MessageEdited
+
+        val message = event.message!!
+        assertTrue(isVoiceMessage(message))
+        assertEquals("明天几点出发", message.content)
+    }
+
+    @Test
+    fun `a tts fallback row is text with a note, not a voice bubble`() {
+        // 合成降级那一行：键在（`hasVoice` 为真 ⇒ 不许当成「什么都没有」），但 `status = "failed"`
+        // ⇒ 没有可播的声音，画语音形态就是给一个点下去必然失败的按钮。正文照旧 + 一行原样小标。
+        val event = WsEvent.parse(frame("message_persisted", """{"message":$fallbackRow}""")) as WsEvent.MessagePersisted
+
+        val message = event.message!!
+        val voice = message.voice!!
+        assertTrue("降级行仍来自一段声音", hasVoice(message))
+        assertFalse("但它没有可播的声音，不许画成语音形态", isVoiceMessage(message))
+        assertNull("没有副本 ⇒ 一个播放控件都不画", voiceAudio(voice))
+        assertEquals("想跟你说句话", message.content)
+        // 原因**原样**出现在小标里（不映射、不猜闭集）。
+        assertNotNull(voiceFallbackNote(voice))
+        assertTrue(voiceFallbackNote(voice)!!.contains("tts_timeout"))
+    }
+
+    @Test
+    fun `a synthesized voice row is an ordinary voice bubble`() {
+        // `source = tts` 与 asr / platform 走**同一条**路：判据只看 `status`，不看 `source`。
+        val event = WsEvent.parse(frame("message_persisted", """{"message":$ttsRow}""")) as WsEvent.MessagePersisted
+
+        val message = event.message!!
+        val voice = message.voice!!
+        assertEquals("tts", voice.source)
+        assertTrue(isVoiceMessage(message))
+        assertEquals(copyName, voiceAudio(voice)?.name)
+        assertNull("合成成功的那条不该有降级小标", voiceFallbackNote(voice))
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/ws/WsEventToolExecutionTest.kt

@@ -16,6 +16,10 @@ import org.junit.Test
  * 帧形状逐字取自后端 `internal/services/gateway/ws_bridge.go` 的 `toolExecutionData`
  * （`tool` + `phase` 恒在，`id` 空则省略该键，`delta` 只在 `.update` 且非空时出现）与
  * `streamEventData` 的类型名；这三帧**不带 `index` / `streamId`**（不属于模型流）。
+ *
+ * 新契约切片给 `.end` 补了一个**可选**的 `resultSummary`（脱敏 + 截断 ≤500 字符的成品，
+ * 只有这一轮真的拿到执行结果才在场）。服务端**尚未部署**它，所以「没有这个键」那一档才是
+ * 今天真机上的唯一路径——它必须解出 `null` 而不是报错。
  */
 class WsEventToolExecutionTest {
 
@@ -112,6 +116,75 @@ class WsEventToolExecutionTest {
         assertNull(ev.id)
     }
 
+    // —— end 的可选 resultSummary（新契约切片；服务端**未部署**） ——
+
+    @Test
+    fun `tool execution end decodes the result summary when the backend sends one`() {
+        val ev = parse(
+            frame(
+                "tool_execution.end",
+                """{"tool":"bash","phase":"done","id":"call_1","resultSummary":"12 行输出，退出码 0"}""",
+            ),
+        ) as WsEvent.ToolExecutionEnd
+
+        assertEquals("12 行输出，退出码 0", ev.resultSummary)
+        assertEquals("bash", ev.tool)
+        assertEquals("done", ev.phase)
+        assertEquals("call_1", ev.id)
+    }
+
+    @Test
+    fun `tool execution end without the key yields null rather than a runtime error`() {
+        // 服务端**当前未部署**这个键：老帧必须照旧解出来，`resultSummary` 是 `null`——
+        // 不是 `""`。两者在渲染上等价（都按「不画结果区」处理），但「键在不在」这件事别在下游丢掉。
+        val ev = parse(frame("tool_execution.end", """{"tool":"bash","phase":"done","id":"call_1"}"""))
+            as WsEvent.ToolExecutionEnd
+
+        assertNull(ev.resultSummary)
+        assertEquals("done", ev.phase)
+    }
+
+    @Test
+    fun `an empty result summary decodes to the empty string and is not invented into anything`() {
+        // 契约承诺不会用空串顶位；真出现了也照原样解，别在解码层替它编一个结论。
+        val ev = parse(
+            frame("tool_execution.end", """{"tool":"bash","phase":"done","resultSummary":""}"""),
+        ) as WsEvent.ToolExecutionEnd
+
+        assertEquals("", ev.resultSummary)
+    }
+
+    @Test
+    fun `a five hundred character summary survives decoding untouched`() {
+        // 后端已按同一份预算截断到 ≤500 字符；本端不许再截第二刀。
+        val summary = "输".repeat(500)
+
+        val ev = parse(
+            frame("tool_execution.end", """{"tool":"bash","phase":"done","resultSummary":"$summary"}"""),
+        ) as WsEvent.ToolExecutionEnd
+
+        assertEquals(summary, ev.resultSummary)
+    }
+
+    @Test
+    fun `only the end frame carries a result summary`() {
+        // 契约只给 `.end` 补了这个键：`.start` / `.update` 的领域事件上根本没有该字段。
+        // （多一个未知键也不该让整帧解析失败——[WsEvent.parse] 本来就是宽容的。）
+        val start = parse(
+            frame("tool_execution.start", """{"tool":"bash","phase":"running","resultSummary":"不该在这"}"""),
+        )
+        val update = parse(
+            frame(
+                "tool_execution.update",
+                """{"tool":"bash","phase":"running","delta":"x","resultSummary":"不该在这"}""",
+            ),
+        )
+
+        assertTrue(start is WsEvent.ToolExecutionStart)
+        assertEquals("bash", (update as WsEvent.ToolExecutionUpdate).tool)
+        assertEquals("x", update.delta)
+    }
+
     // —— 回归：三帧都不能再被丢弃 / 不能读错字段 ——
 
     @Test

app/src/test/kotlin/top/yeij/cyrene/data/ws/WsEventVoiceOutputTest.kt

@@ -0,0 +1,74 @@
+package top.yeij.cyrene.data.ws
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 下行帧 `voice_output`（契约 v0.96 §3.15）。
+ *
+ * 两个容易踩空的地方在这里钉死：
+ * 1. **帧壳没有 `sessionId`**（契约明写，会话 id 在 `data` 里）——解析层必须把它提到帧上，
+ *    否则 `isForSession` 会把本帧**放行给每一个会话的 VM**（空值 = 无法判定），切到别的会话
+ *    时也会响一段本属于别的会话的语音；
+ * 2. `text` / `reply` / `provider` 三个键**一个都不能丢**：`reply` 是她说的话、`text` 是转写、
+ *    `provider == "silent"` 是「这一轮没有音频」的唯一信号（判据在 `domain.chat`）。
+ */
+class WsEventVoiceOutputTest {
+
+    private val realFrame = """
+        {"type":"voice_output","data":{"audio":"UklGRg==","format":"wav","text":"你今天在吗","reply":"我在呢","sessionId":"web","deviceId":"voiceassist:cyrene:v1","provider":"emotiontts"}}
+    """.trimIndent()
+
+    @Test
+    fun `the real frame decodes with every payload key`() {
+        val event = WsEvent.parse(realFrame) as WsEvent.VoiceOutput
+
+        assertEquals("voice_output", event.type)
+        assertEquals("UklGRg==", event.audio)
+        assertEquals("wav", event.format)
+        assertEquals("你今天在吗", event.text)
+        assertEquals("我在呢", event.reply)
+        assertEquals("voiceassist:cyrene:v1", event.deviceId)
+        assertEquals("emotiontts", event.provider)
+        // 帧壳没有轮次 / 序号（这一帧不属任何流式段）。
+        assertNull(event.turnId)
+        assertNull(event.seq)
+    }
+
+    @Test
+    fun `the payload session id is lifted onto the frame so the session gate works`() {
+        val event = WsEvent.parse(realFrame) as WsEvent.VoiceOutput
+
+        assertEquals("web", event.sessionId)
+        assertTrue("本会话放行", event.isForSession("web"))
+        assertFalse("别的会话必须挡下（否则会在别的会话里响起来）", event.isForSession("web:other"))
+    }
+
+    @Test
+    fun `a silent frame keeps the marker and the text`() {
+        val frame = """
+            {"type":"voice_output","data":{"audio":"","format":"wav","text":"嗯","reply":"嗯，我在","sessionId":"web","provider":"silent"}}
+        """.trimIndent()
+
+        val event = WsEvent.parse(frame) as WsEvent.VoiceOutput
+
+        assertEquals("silent", event.provider)
+        assertEquals("", event.audio)
+        assertEquals("嗯，我在", event.reply)
+        assertEquals("web", event.sessionId)
+    }
+
+    @Test
+    fun `a frame without a payload still forms the event instead of vanishing`() {
+        // 坏帧（没有 data）：会话归属退化成「无法判定」，但「这一帧来过」必须留下痕迹——
+        // 整帧丢掉就是「她回了语音而屏幕上什么都没有」，那比一张空卡片糟得多。
+        val event = WsEvent.parse("""{"type":"voice_output"}""") as WsEvent.VoiceOutput
+
+        assertNull(event.audio)
+        assertNull(event.reply)
+        assertEquals("", event.sessionId)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/data/ws/WsOutboundVoiceTest.kt

@@ -0,0 +1,52 @@
+package top.yeij.cyrene.data.ws
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * 上行帧 `voice_input`（契约 v0.96 §3.15）。
+ *
+ * 两个键是**纯增量**：[WsOutbound.VoiceInput.deviceId] 与 `clientMsgId`。骨架里本来只有
+ * `audio` / `format` / `text` / `sessionId` 四个——那四者的线上形状在这里逐字钉死（老帧一个
+ * 字节都不许变），新增的两个只在有值时才出现（与后端 `omitempty` 同义）。
+ *
+ * `clientMsgId` 与文本 `chat` 帧**同形同语义**：同一个非空值服务端只承认第一条。所以真正的
+ * 「幂等」不在这一层（它只负责照发），而在 `ChatViewModel` + 纯函数 `voiceClientMsgIdFor`：
+ * 重发复用同一个键（那边有穷举单测）。
+ */
+class WsOutboundVoiceTest {
+
+    @Test
+    fun `the original four key frame is byte for byte what it was`() {
+        assertEquals(
+            """{"type":"voice_input","data":{"audio":"QUJD","format":"wav","sessionId":"web"}}""",
+            WsOutbound.VoiceInput(audio = "QUJD", format = "wav", sessionId = "web").toJson(),
+        )
+    }
+
+    @Test
+    fun `device id and client message id are carried next to the audio`() {
+        val frame = WsOutbound.VoiceInput(
+            audio = "QUJD",
+            format = "wav",
+            sessionId = "web",
+            deviceId = "voiceassist:cyrene:v1",
+            clientMsgId = "voice-9f3c",
+        ).toJson()
+
+        val expected = """{"type":"voice_input","data":{"audio":"QUJD","format":"wav","sessionId":"web","deviceId":"voiceassist:cyrene:v1","clientMsgId":"voice-9f3c"}}"""
+
+        assertEquals(expected, frame)
+    }
+
+    @Test
+    fun `omitting the idempotency key omits the key itself rather than sending null`() {
+        val json = WsOutbound.VoiceInput(audio = "QUJD", format = "wav").toJson()
+
+        assertFalse("省略时不该出现 clientMsgId 键：$json", json.contains("clientMsgId"))
+        assertFalse("省略时不该出现 deviceId 键：$json", json.contains("deviceId"))
+        assertNull(WsOutbound.VoiceInput(audio = "QUJD").reqId)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/chat/PreviewMetadataTest.kt

@@ -0,0 +1,358 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.data.api.dto.DocumentRefDto
+
+/**
+ * 预览内容下方那一行元数据的组装（逐档穷举）。
+ *
+ * 这一块的价值全在「**不出现**」上：一屏小字里凭空多出一项（一个假的编码、一个猜的日期、
+ * 一个 `--` 占位符）比少一项糟得多，而且它看起来完全正常。所以这里的断言分两类：
+ * 1. **有证据时逐字钉住那一项**（连限定语一起钉：`UTF-8（本端解码口径）` 少了括号里的四个字
+ *    就从「本端口径」变成了对文件编码的断言）；
+ * 2. **没证据时断言它整项缺席**（`assertFalse(line.contains(...))`），而不只是断言列表长度。
+ *
+ * 另有一档是「行数」本身：空文本 / 只有换行 / `\r\n` / 结尾没有换行这四种边界都在
+ * [textItems] 里重算过一次（不是照抄 `PreviewSlice.shownLines`），所以要从**字节**跑起，
+ * 走 [DocumentPreview.slice] 这条真实的路。
+ */
+class PreviewMetadataTest {
+
+    // —— 行数：从预览内容算，四个边界 ——
+
+    @Test
+    fun `empty text is zero lines`() {
+        val items = textItems(DocumentPreview.slice(ByteArray(0)))
+
+        assertEquals("0 行", items.first())
+    }
+
+    @Test
+    fun `a single newline is one line not two`() {
+        val items = textItems(DocumentPreview.slice("\n".toByteArray()))
+
+        assertEquals("1 行", items.first())
+    }
+
+    @Test
+    fun `carriage returns do not add lines`() {
+        // `\r\n` 只数 `\n`：Windows 换行不该被算成两行，`\r` 单独出现也不是换行。
+        val items = textItems(DocumentPreview.slice("a\r\nb\r\nc".toByteArray()))
+
+        assertEquals("3 行", items.first())
+    }
+
+    @Test
+    fun `a missing trailing newline still counts the last line`() {
+        val items = textItems(DocumentPreview.slice("a\nb".toByteArray()))
+
+        assertEquals("2 行", items.first())
+    }
+
+    @Test
+    fun `a trailing newline does not count an extra line`() {
+        val items = textItems(DocumentPreview.slice("a\nb\n".toByteArray()))
+
+        assertEquals("2 行", items.first())
+    }
+
+    @Test
+    fun `a preview cut short reports both the shown and the total line count`() {
+        // 5000 行上限正好等于上限时不截断；这里给 5001 行，确认「显示 / 共」两个数都在。
+        val bytes = lines(DocumentPreviewLimits.MAX_LINES + 1).toByteArray()
+        val slice = DocumentPreview.slice(bytes)
+
+        assertEquals(PreviewTruncation.Lines, slice.truncatedBy)
+        assertEquals(
+            "显示 ${grouped(DocumentPreviewLimits.MAX_LINES)} 行 / 共 ${grouped(DocumentPreviewLimits.MAX_LINES + 1)} 行",
+            textItems(slice).first(),
+        )
+    }
+
+    @Test
+    fun `a complete preview says one number only`() {
+        val items = textItems(DocumentPreview.slice("a\nb\nc".toByteArray()))
+
+        assertFalse(items.first(), items.first().contains("共"))
+        assertFalse(items.first(), items.first().contains("显示"))
+    }
+
+    // —— 字符数：两个口径分得开 ——
+
+    @Test
+    fun `the server character count is shown with its scope`() {
+        val items = textItems(sliceOf("hello"), serverCharsLabel = "8,000 字")
+
+        assertEquals("8,000 字（服务端注入口径）", items[1])
+    }
+
+    @Test
+    fun `without a server count the local one is used and says so`() {
+        val items = textItems(sliceOf("你好"), serverCharsLabel = null)
+
+        assertEquals("2 字（本端预览内容）", items[1])
+    }
+
+    @Test
+    fun `the local count is code points not utf16 units`() {
+        // 一个 emoji 在 UTF-16 里是两个单元（代理对）；「字符数」该数成 1。
+        val items = textItems(sliceOf("😀"), serverCharsLabel = null)
+
+        assertEquals("1 字（本端预览内容）", items[1])
+    }
+
+    @Test
+    fun `a server count of zero is still a report and is shown`() {
+        // `chars: 0` 是「服务端报了 0」，与「服务端没报」是两件事——不许被归一成后者。
+        val items = textItems(sliceOf("abc"), serverCharsLabel = DocumentChips.charsLabel(0))
+
+        assertEquals("0 字（服务端注入口径）", items[1])
+    }
+
+    // —— 解码口径 ——
+
+    @Test
+    fun `the decoding scope is always stated and never as a bare utf8`() {
+        val items = textItems(sliceOf("x"), serverCharsLabel = null)
+
+        assertTrue(items.toString(), items.contains("UTF-8（本端解码口径）"))
+        assertFalse("裸写 UTF-8 会被读成「这份文件是 UTF-8 编码的」", items.contains("UTF-8"))
+    }
+
+    // —— 服务端的 truncated：两态 ——
+
+    @Test
+    fun `the server truncation flag is spelled out when set`() {
+        val items = textItems(sliceOf("x"), serverCharsLabel = null, contextTruncated = true)
+
+        assertEquals("正文被截断（进上下文的部分）", items.last())
+    }
+
+    @Test
+    fun `nothing is said about truncation when the server did not report it`() {
+        val items = textItems(sliceOf("x"), serverCharsLabel = null, contextTruncated = false)
+
+        assertFalse(items.toString(), items.any { it.contains("截断") })
+        assertEquals(3, items.size)
+    }
+
+    // —— 非文本档：只有嗅探所得的 mime ——
+
+    @Test
+    fun `a binary file shows the sniffed mime`() {
+        assertEquals(listOf("application/pdf"), PreviewMetadata.fileItems("application/pdf"))
+    }
+
+    @Test
+    fun `a local draft without a server mime shows nothing at all`() {
+        assertEquals(emptyList<String>(), PreviewMetadata.fileItems(null))
+        assertEquals(emptyList<String>(), PreviewMetadata.fileItems(""))
+        assertEquals(emptyList<String>(), PreviewMetadata.fileItems("   "))
+    }
+
+    @Test
+    fun `a binary file line never invents a placeholder`() {
+        val line = PreviewMetadata.join(PreviewMetadata.fileItems(null))
+
+        assertEquals("", line)
+        assertFalse(line.contains("未知"))
+        assertFalse(line.contains("--"))
+    }
+
+    // —— 图片：四项各自的可有可无 ——
+
+    @Test
+    fun `a full image line carries format, size in pixels, bytes and the shot date`() {
+        val items = PreviewMetadata.imageItems(
+            mime = "image/jpeg",
+            width = 4032,
+            height = 3024,
+            sizeBytes = 2_411_724,
+            capturedAt = "2019:07:04 20:31:05",
+        )
+
+        assertEquals(
+            listOf("image/jpeg", "4032 × 3024", "2.3 MB", "拍摄于 2019年7月4日 20:31"),
+            items,
+        )
+    }
+
+    @Test
+    fun `an image with no exif simply has no date`() {
+        val items = PreviewMetadata.imageItems(
+            mime = "image/png",
+            width = 100,
+            height = 50,
+            sizeBytes = 2048,
+            capturedAt = null,
+        )
+
+        assertEquals(listOf("image/png", "100 × 50", "2.0 KB"), items)
+    }
+
+    @Test
+    fun `an undecodable size is left out rather than guessed`() {
+        val items = PreviewMetadata.imageItems(mime = "image/gif", width = null, height = null)
+
+        assertEquals(listOf("image/gif"), items)
+    }
+
+    @Test
+    fun `a half known size is not reported`() {
+        // `inJustDecodeBounds` 只会两侧都给或两侧都不给；真出现半边时宁可不报。
+        val items = PreviewMetadata.imageItems(mime = null, width = 800, height = null)
+
+        assertEquals(emptyList<String>(), items)
+    }
+
+    @Test
+    fun `non positive sizes are not reported`() {
+        val items = PreviewMetadata.imageItems(mime = null, width = -1, height = 0)
+
+        assertEquals(emptyList<String>(), items)
+    }
+
+    @Test
+    fun `an unknown byte count leaves the size out`() {
+        val items = PreviewMetadata.imageItems(
+            mime = null,
+            sizeBytes = PreviewMetadata.UNKNOWN_BYTES,
+        )
+
+        assertEquals(emptyList<String>(), items)
+    }
+
+    @Test
+    fun `the image wildcard is not a format and must not be shown`() {
+        // 调用方在这一档传的是 null（`image/` 通配由弹层滤掉）；纯函数这层再确认一遍空值不产出项。
+        assertEquals(emptyList<String>(), PreviewMetadata.imageItems(mime = null))
+        assertEquals(emptyList<String>(), PreviewMetadata.imageItems(mime = "  "))
+    }
+
+    // —— EXIF 日期：严格到不近人情 ——
+
+    @Test
+    fun `a canonical exif timestamp is formatted`() {
+        assertEquals("2019年7月4日 20:31", PreviewMetadata.formatExifDateTime("2019:07:04 20:31:05"))
+    }
+
+    @Test
+    fun `the time is zero padded and the date is not`() {
+        assertEquals("2001年1月2日 03:04", PreviewMetadata.formatExifDateTime("2001:01:02 03:04:09"))
+    }
+
+    @Test
+    fun `surrounding whitespace is tolerated`() {
+        assertEquals("2019年7月4日 20:31", PreviewMetadata.formatExifDateTime(" 2019:07:04 20:31:05 "))
+    }
+
+    @Test
+    fun `the all zero placeholder means unknown and is rejected`() {
+        assertNull(PreviewMetadata.formatExifDateTime("0000:00:00 00:00:00"))
+    }
+
+    @Test
+    fun `out of range components are rejected`() {
+        assertNull(PreviewMetadata.formatExifDateTime("2019:13:04 20:31:05"))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:07:32 20:31:05"))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:07:04 24:31:05"))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:07:04 20:61:05"))
+    }
+
+    @Test
+    fun `a leap second is a valid exif value`() {
+        assertEquals("2016年12月31日 23:59", PreviewMetadata.formatExifDateTime("2016:12:31 23:59:60"))
+    }
+
+    @Test
+    fun `malformed values are rejected rather than repaired`() {
+        assertNull("另一个分隔符的形态不当成 EXIF 认", PreviewMetadata.formatExifDateTime("2019-07-04 20:31:05"))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:07:04T20:31:05"))
+        assertNull("缺秒", PreviewMetadata.formatExifDateTime("2019:07:04 20:31"))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:7:4 20:31:05"))
+        assertNull(PreviewMetadata.formatExifDateTime("hello"))
+        assertNull(PreviewMetadata.formatExifDateTime(""))
+        assertNull(PreviewMetadata.formatExifDateTime(null))
+        assertNull(PreviewMetadata.formatExifDateTime("2019:07:04 20:31:05+08:00"))
+    }
+
+    @Test
+    fun `an invalid exif date leaves the whole item out`() {
+        val items = PreviewMetadata.imageItems(
+            mime = "image/jpeg",
+            capturedAt = "0000:00:00 00:00:00",
+        )
+
+        assertEquals(listOf("image/jpeg"), items)
+    }
+
+    @Test
+    fun `exif time is read as local wall clock with no timezone conversion`() {
+        // 同一串数字在任何时区下都得原样出来——EXIF 里根本没有偏移量字段，换算就是凭空错几小时。
+        assertEquals("2019年7月4日 20:31", PreviewMetadata.formatExifDateTime("2019:07:04 20:31:05"))
+    }
+
+    // —— 拼接 ——
+
+    @Test
+    fun `items are joined with a middle dot`() {
+        assertEquals("a · b · c", PreviewMetadata.join(listOf("a", "b", "c")))
+        assertEquals("", PreviewMetadata.join(emptyList()))
+    }
+
+    // —— 走一遍真实链路：DTO → 芯片 → 这一行 ——
+
+    @Test
+    fun `the chip model feeds the two server facts without re-formatting them`() {
+        val chip = DocumentChips.of(
+            DocumentRefDto(
+                name = "0123456789abcdef0123456789abcdef.txt",
+                mime = "text/plain",
+                size = 12_345,
+                chars = 8_000,
+                truncated = true,
+                status = DocumentStatus.EXTRACTED,
+            ),
+        )
+        val items = PreviewMetadata.textItems(
+            slice = DocumentPreview.slice("a\nb".toByteArray()),
+            serverCharsLabel = chip.charsLabel,
+            contextTruncated = chip.truncatedLabel != null,
+        )
+
+        assertEquals(
+            listOf("2 行", "8,000 字（服务端注入口径）", "UTF-8（本端解码口径）", "正文被截断（进上下文的部分）"),
+            items,
+        )
+    }
+
+    @Test
+    fun `a draft attachment only has the local half`() {
+        val chip = DocumentChips.of(
+            DraftDocument(uri = "content://x/y.txt", displayName = "notes.txt", sizeBytes = 1024),
+        )
+        val items = PreviewMetadata.textItems(
+            slice = DocumentPreview.slice("hello\n".toByteArray()),
+            serverCharsLabel = chip.charsLabel,
+            contextTruncated = chip.truncatedLabel != null,
+        )
+
+        assertEquals(listOf("1 行", "6 字（本端预览内容）", "UTF-8（本端解码口径）"), items)
+    }
+
+    private fun textItems(
+        slice: PreviewSlice,
+        serverCharsLabel: String? = null,
+        contextTruncated: Boolean = false,
+    ) = PreviewMetadata.textItems(slice, serverCharsLabel, contextTruncated)
+
+    private fun sliceOf(text: String): PreviewSlice = DocumentPreview.slice(text.toByteArray())
+
+    private fun lines(count: Int): String = (1..count).joinToString("\n") { "line $it" } + "\n"
+
+    private fun grouped(value: Int): String = String.format(java.util.Locale.ROOT, "%,d", value)
+}

app/src/test/kotlin/top/yeij/cyrene/domain/chat/VoiceClipTest.kt

@@ -0,0 +1,234 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 语音**上行**那一半的纯函数（契约 v0.96 §3.15 ①）：录音参数、WAV 封装、体积闸门、幂等键。
+ *
+ * 这一组钉的是「发出去的字节长什么样」——WAV 头一旦有一个字段写错，服务端的解码器与 STT
+ * 会**静默**给出垃圾（或直接拒），而客户端这边完全看不出问题。所以头的每个字段都在这里逐个
+ * 读出来断言，而不是只比长度。
+ */
+class VoiceClipTest {
+
+    // —— 换算：16 kHz / 单声道 / 16-bit ⇒ 1 ms = 32 字节 ——
+
+    @Test
+    fun `one second of pcm is 32 000 bytes at the chosen parameters`() {
+        assertEquals(32_000, VoiceClip.BYTES_PER_SECOND)
+        assertEquals(32_000, VoiceClip.pcmBytesFor(1_000))
+        assertEquals(1_000, VoiceClip.durationMillisOf(32_000))
+    }
+
+    @Test
+    fun `duration and byte count round trip for typical clips`() {
+        assertEquals(1_920_000, VoiceClip.MAX_PCM_BYTES)
+        assertEquals(VoiceClip.MAX_RECORDING_MILLIS, VoiceClip.durationMillisOf(VoiceClip.MAX_PCM_BYTES))
+        // 不足一毫秒的零头一律向下取整（绝不把 0 字节说成 1 毫秒）。
+        assertEquals(0, VoiceClip.durationMillisOf(31))
+        assertEquals(0, VoiceClip.durationMillisOf(0))
+        assertEquals(0, VoiceClip.durationMillisOf(-5))
+        assertEquals(0, VoiceClip.pcmBytesFor(-5))
+    }
+
+    // —— WAV 头：逐字段 ——
+
+    @Test
+    fun `the wav header carries the riff wav fmt data chunks of pcm`() {
+        val pcmBytes = 32_000
+        val header = VoiceClip.wavHeader(pcmBytes)
+
+        assertEquals("RIFF-WAVE 头恒为 44 字节", 44, header.size)
+        assertEquals("RIFF", header.ascii(0, 4))
+        // RIFF 的 size 字段 = 文件总长 - 8（不含 "RIFF" 与 size 自己）。
+        assertEquals(44 - 8 + pcmBytes, header.intLe(4))
+        assertEquals("WAVE", header.ascii(8, 4))
+        assertEquals("fmt ", header.ascii(12, 4))
+        assertEquals("fmt 子块长度 = 16（PCM）", 16, header.intLe(16))
+        assertEquals("audioFormat = 1（PCM）", 1, header.shortLe(20))
+        assertEquals("单声道", 1, header.shortLe(22))
+        assertEquals("采样率 16 kHz", 16_000, header.intLe(24))
+        assertEquals("字节率 = 采样率 × 声道 × 位深/8", 32_000, header.intLe(28))
+        assertEquals("块对齐 = 声道 × 位深/8", 2, header.shortLe(32))
+        assertEquals("16-bit", 16, header.shortLe(34))
+        assertEquals("data", header.ascii(36, 4))
+        assertEquals("data 子块长度 = PCM 字节数", pcmBytes, header.intLe(40))
+    }
+
+    @Test
+    fun `toWav length is header plus pcm and the payload is untouched`() {
+        val pcm = ByteArray(64) { (it + 1).toByte() }
+
+        val wav = VoiceClip.toWav(pcm)
+
+        assertEquals("字节数 = 44 + PCM", 44 + pcm.size, wav.size)
+        assertEquals(44 - 8 + pcm.size, wav.intLe(4))
+        assertEquals(pcm.size, wav.intLe(40))
+        // 头之后一个字节都不许动（重采样 / 量化是录音机的事，这里只搬字节）。
+        assertArrayEquals(pcm, wav.copyOfRange(44, wav.size))
+    }
+
+    @Test
+    fun `an empty pcm still yields a self consistent 44 byte wav`() {
+        val wav = VoiceClip.toWav(ByteArray(0))
+
+        assertEquals(44, wav.size)
+        assertEquals(44 - 8, wav.intLe(4))
+        assertEquals(0, wav.intLe(40))
+        assertEquals("RIFF", wav.ascii(0, 4))
+        assertEquals("data", wav.ascii(36, 4))
+    }
+
+    // —— 准入：空 / 太短 / 超限 / 可发 ——
+
+    @Test
+    fun `an empty recording is rejected as empty rather than too short`() {
+        assertEquals(VoiceClipPlan.Empty, VoiceClip.plan(ByteArray(0)))
+        assertEquals(VOICE_EMPTY_MESSAGE, voiceClipRejection(VoiceClipPlan.Empty))
+    }
+
+    @Test
+    fun `a few milliseconds of audio is rejected as too short`() {
+        // 100 字节 = 3 ms：按下就松手的那一下。
+        val plan = VoiceClip.plan(ByteArray(100))
+
+        assertTrue("极短录音判 TooShort，实际 $plan", plan is VoiceClipPlan.TooShort)
+        assertEquals(3, (plan as VoiceClipPlan.TooShort).durationMs)
+        assertEquals(VOICE_TOO_SHORT_MESSAGE, voiceClipRejection(plan))
+    }
+
+    @Test
+    fun `exactly one second is the shortest acceptable clip`() {
+        val plan = VoiceClip.plan(ByteArray(VoiceClip.pcmBytesFor(1_000)))
+
+        assertTrue("满一秒就该放行，实际 $plan", plan is VoiceClipPlan.Ready)
+        assertEquals(1_000, (plan as VoiceClipPlan.Ready).durationMs)
+        assertEquals(44 + 32_000, plan.wav.size)
+    }
+
+    @Test
+    fun `one millisecond under the minimum is still rejected`() {
+        val pcm = ByteArray(VoiceClip.pcmBytesFor(1_000) - 32) // 32 字节 = 1 ms
+
+        val plan = VoiceClip.plan(pcm)
+
+        assertTrue("999 ms 仍算太短，实际 $plan", plan is VoiceClipPlan.TooShort)
+        assertEquals(999, (plan as VoiceClipPlan.TooShort).durationMs)
+    }
+
+    // —— 体积闸门（含「等于」那一格）——
+
+    @Test
+    fun `the byte ceiling equals the server's decoded inline cap`() {
+        // 与 chat.image 解码后同一条线：契约没给 voice_input 的上限，本端按已知最严的那一档设计。
+        assertEquals(ChatImageBudget.SERVER_MAX_DECODED_BYTES, VoiceClip.MAX_AUDIO_BYTES)
+        assertEquals(5 * 1024 * 1024, VoiceClip.MAX_AUDIO_BYTES)
+    }
+
+    @Test
+    fun `a clip exactly at the ceiling is accepted`() {
+        val pcm = ByteArray(VoiceClip.MAX_AUDIO_BYTES - VoiceClip.HEADER_BYTES)
+
+        val total = VoiceClip.totalBytesFor(pcm.size)
+
+        assertEquals("上界取等于（<=）", VoiceClip.MAX_AUDIO_BYTES, total)
+        assertTrue(VoiceClip.withinLimit(total))
+        assertTrue("恰好到顶应当放行", VoiceClip.plan(pcm) is VoiceClipPlan.Ready)
+    }
+
+    @Test
+    fun `a clip one byte over the ceiling is refused with a named reason`() {
+        // 43 字节：total = 44 + 43 = MAX + 1。
+        val pcm = ByteArray(VoiceClip.MAX_AUDIO_BYTES - VoiceClip.HEADER_BYTES + 1)
+
+        val total = VoiceClip.totalBytesFor(pcm.size)
+
+        assertEquals(VoiceClip.MAX_AUDIO_BYTES + 1, total)
+        assertFalse(VoiceClip.withinLimit(total))
+        val plan = VoiceClip.plan(pcm)
+        assertTrue("超限判 TooLarge，实际 $plan", plan is VoiceClipPlan.TooLarge)
+        assertEquals(total, (plan as VoiceClipPlan.TooLarge).totalBytes)
+        assertEquals(VOICE_TOO_LARGE_MESSAGE, voiceClipRejection(plan))
+    }
+
+    @Test
+    fun `a 60 second recording stays well under the ceiling`() {
+        // 录满长度只用到闸门的 36%：撞上它说明硬件给了异常的量，不是正常路径。
+        val total = VoiceClip.totalBytesFor(VoiceClip.MAX_PCM_BYTES)
+
+        assertTrue(VoiceClip.withinLimit(total))
+        assertEquals(1_920_044, total)
+    }
+
+    @Test
+    fun `the rejection of a sendable clip is null`() {
+        val ready = VoiceClip.plan(ByteArray(VoiceClip.pcmBytesFor(2_000)))
+
+        assertNull(voiceClipRejection(ready))
+    }
+
+    // —— 录音中的时长文案 ——
+
+    @Test
+    fun `the elapsed label starts at zero and pads seconds`() {
+        assertEquals("0:00", voiceElapsedLabel(0))
+        assertEquals("0:00", voiceElapsedLabel(999))
+        assertEquals("0:07", voiceElapsedLabel(7_000))
+        assertEquals("1:05", voiceElapsedLabel(65_000))
+        // 负数（时钟回拨 / 调用方算错）不显示成 -1:-1。
+        assertEquals("0:00", voiceElapsedLabel(-1_000))
+    }
+
+    // —— 幂等键：重发必须复用（契约 v0.96：同一个非空值只承认第一条）——
+
+    @Test
+    fun `a fresh recording mints a new prefixed key`() {
+        val key = voiceClientMsgIdFor(null) { "9f3c" }
+
+        assertEquals("voice-9f3c", key)
+        assertTrue("前缀写进键里，好让服务端与日志一眼看出这条是语音", key.startsWith(VOICE_CLIENT_MSG_ID_PREFIX))
+    }
+
+    @Test
+    fun `retrying the same clip reuses its client message id`() {
+        val draft = VoiceDraftInfo(clientMsgId = "voice-keep", durationMs = 1_800, totalBytes = 57_644)
+
+        // 用户连点三次「重发」：每一次都必须拿同一个键（否则服务端会把同一句话答三遍）。
+        val attempts = List(3) {
+            voiceClientMsgIdFor(draft) { error("重发不该铸新键") }
+        }
+
+        assertEquals(listOf("voice-keep", "voice-keep", "voice-keep"), attempts)
+    }
+
+    @Test
+    fun `a different recording never inherits the old key`() {
+        val old = VoiceDraftInfo("voice-old", durationMs = 1_200, totalBytes = 38_444)
+
+        // 丢弃之后再录一段：状态里那一格已经清掉 ⇒ 现铸新键（否则新录音会被服务端当成重发吞掉）。
+        val fresh = voiceClientMsgIdFor(null) { "fresh" }
+
+        assertEquals("voice-fresh", fresh)
+        assertTrue(fresh != old.clientMsgId)
+    }
+}
+
+/** 从字节数组里取一段 ASCII（断言 WAV 头的四个 chunk 名用）。 */
+private fun ByteArray.ascii(offset: Int, length: Int): String =
+    String(this, offset, length, Charsets.US_ASCII)
+
+/** 小端有符号整数（WAV 头里全是 32 位小端）。 */
+private fun ByteArray.intLe(offset: Int): Int =
+    (this[offset].toInt() and 0xFF) or
+        ((this[offset + 1].toInt() and 0xFF) shl 8) or
+        ((this[offset + 2].toInt() and 0xFF) shl 16) or
+        ((this[offset + 3].toInt() and 0xFF) shl 24)
+
+/** 小端 16 位无符号整数。 */
+private fun ByteArray.shortLe(offset: Int): Int =
+    (this[offset].toInt() and 0xFF) or ((this[offset + 1].toInt() and 0xFF) shl 8)

app/src/test/kotlin/top/yeij/cyrene/domain/chat/VoiceMessageTest.kt

@@ -0,0 +1,342 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.data.repository.DocumentCacheUnavailableException
+import top.yeij.cyrene.data.repository.VoiceTooLargeException
+import top.yeij.cyrene.data.repository.VoiceUrlUnavailableException
+import top.yeij.cyrene.ui.chat.isContentlessUserMessage
+
+/**
+ * 语音消息的**呈现判据**（纯函数，接收侧）。
+ *
+ * 契约的权威形状见 `Cyrene_v2/Docs/api-client.md` §4.4 与 §1.2 U19，六条口径逐条钉在这里：
+ * 1. **🎤 判据 = `voice` 键存在 **且** `status != "failed"`**（`isVoiceMessage`）——**绝不**从正文里
+ *    认媒体类型（正文里可能出现用户自己打出的 `[语音]` 字样），也绝不把 `failed` 行画成语音形态
+ *    （那一行没有可播的声音，见 `isPlayableVoice` / `hasVoice`）；
+ * 2. **无副本 ⇒ 不画播放控件**（`voiceAudio` 要四个键齐全）；
+ * 3. **`durationMs` 缺席就不显示时长**（`voiceDurationLabel`），也不显示 `0:00` 冒充；
+ * 4. **三态 `status` 的差别只有一句补充说明**（`voiceNote`），正文一律照旧由调用方显示；
+ * 5. **`failed` 行多一行灰色小标**（`voiceFallbackNote`）：固定前半句 + 服务端 `fallbackReason` 原样；
+ * 6. **相对路径 `url` 接到当前服务器地址上**（`voiceMediaUrl`），拼不出来就**如实说拼不出来**，
+ *    绝不退回「自己拼一条 `/api/v1/media/<name>`」。
+ */
+class VoiceMessageTest {
+
+    private fun message(
+        content: String = "",
+        role: String = "user",
+        voice: VoiceDto? = null,
+    ) = HistoryMessageDto(
+        id = "msg-1",
+        sessionId = "web",
+        role = role,
+        content = content,
+        voice = voice,
+        createdAt = 1_791_088_571_785L,
+    )
+
+    private val copyName = "a1b2c3d4e5f60718293a4b5c6d7e8f90.ogg"
+
+    private fun voice(
+        source: String = VoiceSource.ASR,
+        status: String = VoiceStatus.TRANSCRIBED,
+        name: String? = copyName,
+        mime: String? = "audio/ogg",
+        size: Long? = 12_345,
+        durationMs: Int? = 3_200,
+        fallbackReason: String? = null,
+        url: String? = "/api/v1/media/$copyName",
+    ) = VoiceDto(
+        source = source,
+        status = status,
+        name = name,
+        mime = mime,
+        size = size,
+        durationMs = durationMs,
+        fallbackReason = fallbackReason,
+        url = url,
+    )
+
+    // —— 1. 「来自一条语音」的判据 = 键存在（`hasVoice`）——
+
+    @Test
+    fun `the voice key is the only criterion for coming from a voice`() {
+        assertTrue(hasVoice(message(voice = voice())))
+        assertFalse(hasVoice(message(content = "在的")))
+        // 正文里出现 `[语音]` 字样**不是**判据：QQ 那个占位标记自 v0.67 起不再下发，
+        // 而用户完全可以自己打出这四个字（这是契约点名的两个方向）。
+        assertFalse(hasVoice(message(content = "[语音]")))
+        assertFalse(hasVoice(message(content = "语音")))
+        assertTrue(hasVoice(message(content = "[语音]", voice = voice())))
+        // 「要不要画语音形态」是**另一个**问题（见下面第 4b 节），但键在是它的前提。
+        assertTrue(isVoiceMessage(message(content = "[语音]", voice = voice())))
+    }
+
+    // —— 2. 四者同生共死 ⇒ 能不能播 ——
+
+    @Test
+    fun `an audio copy is playable only when all four keys are there`() {
+        val audio = voiceAudio(voice())!!
+        assertEquals(copyName, audio.name)
+        assertEquals("audio/ogg", audio.mime)
+        assertEquals(12_345L, audio.size)
+        assertEquals("/api/v1/media/$copyName", audio.url)
+        assertEquals(3_200, audio.durationMs)
+    }
+
+    @Test
+    fun `a missing key on any of the four makes the copy unplayable`() {
+        // 四者同生共死：缺任何一个 ⇒ 一个播放控件都不画（不能给一个点下去必然失败的按钮）。
+        assertNull(voiceAudio(voice(name = null)))
+        assertNull(voiceAudio(voice(mime = null)))
+        assertNull(voiceAudio(voice(size = null)))
+        assertNull(voiceAudio(voice(url = null)))
+        // 空白与 null 同等对待（空白串拼出来是一条没有名字的地址）。
+        assertNull(voiceAudio(voice(name = "  ")))
+        assertNull(voiceAudio(voice(mime = "")))
+        assertNull(voiceAudio(voice(url = " ")))
+    }
+
+    @Test
+    fun `an absent voice key has no copy and a zero byte copy is still a copy`() {
+        assertNull(voiceAudio(null))
+        // size 只要求在（**不要求 > 0**）：契约说它恒在，本端也不拿它推导别的任何东西。
+        assertEquals(0L, voiceAudio(voice(size = 0))!!.size)
+    }
+
+    @Test
+    fun `a voice without a copy keeps its duration`() {
+        // 微信那条路：`source = platform`、四个副本键全缺 ⇒ 不可播，但时长照留（渠道给了）。
+        val platform = voice(
+            source = VoiceSource.PLATFORM,
+            name = null,
+            mime = null,
+            size = null,
+            url = null,
+            durationMs = 5_000,
+        )
+        assertNull(voiceAudio(platform))
+        assertEquals("0:05", voiceDurationLabel(platform.durationMs))
+    }
+
+    // —— 3. 时长 ——
+
+    @Test
+    fun `a missing duration shows nothing at all`() {
+        // 「缺席就不显示时长」：不拿 size / 码率反算，也不显示 `0:00` 冒充。
+        assertNull(voiceDurationLabel(null))
+        assertNull(voiceDurationLabel(0))
+        assertNull(voiceDurationLabel(-1))
+        // 不足一秒时**向下取整会发生什么**：100ms 会变成 `0:00` —— 那正是「冒充」，
+        // 所以这一条也当缺席（契约里不存在 0 秒的语音）。
+        assertNull(voiceDurationLabel(100))
+    }
+
+    @Test
+    fun `a duration is formatted as minutes and seconds`() {
+        assertEquals("0:01", voiceDurationLabel(1_000))
+        assertEquals("0:03", voiceDurationLabel(3_200))
+        assertEquals("0:59", voiceDurationLabel(59_999))
+        assertEquals("1:00", voiceDurationLabel(60_000))
+        assertEquals("1:05", voiceDurationLabel(65_000))
+        assertEquals("10:00", voiceDurationLabel(600_000))
+        // 不折算成小时制：语音消息不会长到那个量级，多一种表达就多一种自己发明的说法。
+        assertEquals("124:03", voiceDurationLabel(7_443_000))
+    }
+
+    // —— 4. 三态 status 在界面上多说的那一句 ——
+
+    @Test
+    fun `only an empty transcription with blank content gets the extra line`() {
+        assertEquals(VOICE_EMPTY_NOTE, voiceNote(VoiceStatus.EMPTY, ""))
+        assertEquals(VOICE_EMPTY_NOTE, voiceNote(VoiceStatus.EMPTY, "   "))
+        // transcribed：正文就是转写文本，多一句都是噪声。
+        assertNull(voiceNote(VoiceStatus.TRANSCRIBED, "明天几点出发"))
+        // failed：正文**就是**服务端那行诚实提示，本端一个字都不改、也不添油加醋。
+        assertNull(voiceNote(VoiceStatus.FAILED, "这段语音没能转成文字（未配置语音识别）"))
+        // 认不出的 status：不猜（与 failed 同形：只显示正文）。
+        assertNull(voiceNote("", ""))
+        assertNull(voiceNote("future-status", ""))
+        // empty 而正文非空（契约说不会出现）：不补一句自相矛盾的话。
+        assertNull(voiceNote(VoiceStatus.EMPTY, "其实有字"))
+    }
+
+    // —— 4b. failed 行：没有可播的声音，但仍然是「一条语音消息」——
+
+    @Test
+    fun `a failed voice is not a voice bubble but still a voice message`() {
+        // 判据拆成两个问题：hasVoice 答「这条来自一条语音吗」，isVoiceMessage 答「画不画语音形态」。
+        // 合成降级 / 转写失败的行两问的答案是「是」「否」——正因如此才不能混用。
+        val outbound = message(content = "想跟你说句话", voice = voice(source = VoiceSource.TTS, status = VoiceStatus.FAILED))
+        assertTrue(hasVoice(outbound))
+        assertFalse(isVoiceMessage(outbound))
+        // 入站转写失败同形：本端分不清（也不该分）这两个方向。
+        assertFalse(isVoiceMessage(message(voice = voice(status = VoiceStatus.FAILED))))
+        // 键缺席才是「不是语音消息」。
+        assertFalse(hasVoice(message(content = "在的")))
+    }
+
+    @Test
+    fun `a failed voice is excluded by status, not by its copy keys`() {
+        // 两个判据各判各的、互不顶替：voiceAudio 只看四键齐不齐（**不看** status），
+        // isPlayableVoice 只看 status（**不看**四键）。所以「四键齐全但 status = failed」这种
+        // 后端按契约不该发的形状，voiceAudio 照样能构造出来 —— 拦住语音形态的是 isVoiceMessage。
+        val contradictory = voice(status = VoiceStatus.FAILED)
+        assertNotNull(voiceAudio(contradictory))
+        assertFalse(isPlayableVoice(contradictory))
+        assertFalse(isVoiceMessage(message(voice = contradictory)))
+        // 反向：四键不齐的 transcribed 行照样「可播」（画语音形态、只是没有播放控件）。
+        val noCopy = voice(name = null, mime = null, size = null, url = null)
+        assertNull(voiceAudio(noCopy))
+        assertTrue(isPlayableVoice(noCopy))
+        assertTrue(isVoiceMessage(message(voice = noCopy)))
+    }
+
+    @Test
+    fun `the fallback reason is shown verbatim and never mapped`() {
+        // 原样放进括号：后端换一个取值本端一个字符都不改（闭集还没定，映射比原样更难排查）。
+        assertEquals(
+            "这条语音没有可播放的声音（tts_timeout）",
+            voiceFallbackNote(voice(source = VoiceSource.TTS, status = VoiceStatus.FAILED, fallbackReason = "tts_timeout")),
+        )
+        assertEquals(
+            "这条语音没有可播放的声音（budget_exceeded）",
+            voiceFallbackNote(voice(status = VoiceStatus.FAILED, fallbackReason = "budget_exceeded")),
+        )
+    }
+
+    @Test
+    fun `a failed voice without a reason still says something`() {
+        // 缺席 / 空白：只剩固定前半句。这一档同时是「空正文 + failed」的兜底 ——
+        // 屏幕上至少还有这行小标，而不是一个什么都没有的空白。
+        assertEquals(VOICE_FALLBACK_NOTE, voiceFallbackNote(voice(status = VoiceStatus.FAILED, fallbackReason = null)))
+        assertEquals(VOICE_FALLBACK_NOTE, voiceFallbackNote(voice(status = VoiceStatus.FAILED, fallbackReason = "  ")))
+    }
+
+    @Test
+    fun `only a failed voice gets a fallback note`() {
+        assertNull(voiceFallbackNote(null))
+        assertNull(voiceFallbackNote(voice()))
+        assertNull(voiceFallbackNote(voice(status = VoiceStatus.EMPTY)))
+        // 认不出的 status 也不加这一行：多画一句「没有可播放的声音」就是替服务端断言它没有。
+        assertNull(voiceFallbackNote(voice(status = "future-status")))
+    }
+
+    @Test
+    fun `a synthesized voice that went through is an ordinary voice bubble`() {
+        // source = tts 与 asr / platform 走**同一条**路：判据只看 status，不看 source。
+        val tts = voice(source = VoiceSource.TTS)
+        assertTrue(isVoiceMessage(message(content = "早上好呀", voice = tts)))
+        assertNotNull(voiceAudio(tts))
+        assertNull(voiceFallbackNote(tts))
+    }
+
+    @Test
+    fun `an unknown status is played rather than silently swallowed`() {
+        // fail-open：认不出的 status 一律当可播。这个方向错得便宜（多画一枚语音形态，最坏点了播不出来，
+        // 有既有的失败文案兜着）；反方向错得贵（把真有副本的语音静默吞成纯文字，用户再也点不到）。
+        assertTrue(isVoiceMessage(message(voice = voice(status = "truncated"))))
+    }
+
+    // —— 5. 相对路径接到当前服务器地址 ——
+
+    @Test
+    fun `a server relative path is rebased onto the current server`() {
+        assertEquals(
+            "http://192.168.1.9:8080/api/v1/media/$copyName",
+            voiceMediaUrl("/api/v1/media/$copyName", "http://192.168.1.9:8080"),
+        )
+        // 尾斜杠、带路径的 baseUrl、大小写 scheme：都按「scheme://authority」处理（与 ImageHostRebase 同）。
+        assertEquals(
+            "http://host:8080/api/v1/media/$copyName",
+            voiceMediaUrl("/api/v1/media/$copyName", "http://host:8080/"),
+        )
+        assertEquals(
+            "HTTPS://host/api/v1/media/$copyName",
+            voiceMediaUrl("/api/v1/media/$copyName", "HTTPS://host/cyrene"),
+        )
+    }
+
+    @Test
+    fun `an unusable base url yields nothing instead of a guessed path`() {
+        // 拼不出可信地址就回 null（调用方据此如实报「暂时播不了」），**绝不**退回自己拼一条路径。
+        assertNull(voiceMediaUrl("/api/v1/media/$copyName", ""))
+        assertNull(voiceMediaUrl("/api/v1/media/$copyName", "192.168.1.9:8080"))
+        assertNull(voiceMediaUrl("/api/v1/media/$copyName", "http://"))
+        assertNull(voiceMediaUrl("/api/v1/media/$copyName", "ftp://host"))
+    }
+
+    @Test
+    fun `a path that is not exactly one media name is refused`() {
+        // 只看服务端给的那条路径：不是「恰好一段 /api/v1/media/<name>」就不接（看不懂的不改、不发）。
+        assertNull(voiceMediaUrl("/api/v1/files/$copyName", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/.", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/..", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/a/../b.ogg", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/%2e%2e%2fsecret", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/a.ogg?token=x", "http://host"))
+        assertNull(voiceMediaUrl("/api/v1/media/a.ogg#f", "http://host"))
+        assertNull(voiceMediaUrl("http://evil/api/v1/media/a.ogg", "http://host"))
+    }
+
+    // —— 失败文案 ——
+
+    @Test
+    fun `a failure always says something, and says the server's own words when it has them`() {
+        // 服务端有话说（404 media_not_found 的两种情形同码）⇒ 只说本端能确定的那半句。
+        val notFound = CyreneException(
+            CyreneError.Server(code = "media_not_found", message = "media not found", httpStatus = 404),
+        )
+        assertEquals("服务端上已经没有这条语音了", voicePlaybackFailureMessage(notFound))
+        // 其它服务端错 / 本地网络错：原样带上服务端那句（或本端的分类说明），**绝不静默**。
+        assertEquals(
+            "语音加载失败，服务器开小差了",
+            voicePlaybackFailureMessage(
+                CyreneException(CyreneError.Server(code = "x", message = "服务器开小差了", httpStatus = 500)),
+            ),
+        )
+        assertEquals(
+            "语音加载失败，网络不可用，请检查连接",
+            voicePlaybackFailureMessage(
+                CyreneException(CyreneError.Local(CyreneError.LocalKind.NoNetwork)),
+            ),
+        )
+        assertEquals("当前服务器地址不可用，暂时播不了这条语音", voicePlaybackFailureMessage(VoiceUrlUnavailableException()))
+        assertEquals("这条语音太大，本机放不了", voicePlaybackFailureMessage(VoiceTooLargeException()))
+        assertEquals(
+            "本地缓存不可用，暂时播不了这条语音",
+            voicePlaybackFailureMessage(DocumentCacheUnavailableException()),
+        )
+        assertEquals("语音加载失败，请稍后重试", voicePlaybackFailureMessage(IllegalStateException("boom")))
+    }
+
+    // —— 与「这条消息什么都没有」那条既有判据的交界 ——
+
+    @Test
+    fun `a voice message is never reported as contentless`() {
+        // 语音的正文可能为空（status = empty，或服务端那行提示没到），但那条消息**不是什么都没有**
+        // ——它有语音形态。少了这一条，屏幕上会出现一句**假的**「内容没有被传过来」。
+        val empty = message(content = "", voice = voice(status = VoiceStatus.EMPTY, name = null, mime = null, size = null, url = null))
+        assertFalse(isContentlessUserMessage(empty))
+        // `failed` 那一档同样不成立，只是理由不同：它**没有**语音形态，但有那行降级小标
+        // （见 `voiceFallbackNote`）—— 同样不是「什么都没有」。判据因此挂在 `hasVoice` 上而**不是**
+        // `isVoiceMessage` 上：两种落点都画得出东西。
+        val failed = message(
+            content = "",
+            voice = voice(source = VoiceSource.TTS, status = VoiceStatus.FAILED, fallbackReason = "tts_timeout"),
+        )
+        assertFalse(isContentlessUserMessage(failed))
+        // 对照：同样空的正文，没有 voice 键 ⇒ 照旧成立（既有的空气泡修复一个字都没变）。
+        assertTrue(isContentlessUserMessage(message(content = "")))
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/chat/VoiceOutputTest.kt

@@ -0,0 +1,86 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * `voice_output` 的呈现判据（契约 v0.96 §3.15）：两件事必须判对，否则 UI 一定画错。
+ *
+ * 1. **这一轮有没有真音频**——`provider == "silent"` 是明文降级信号（`audio` 空、`text`/`reply`
+ *    有）。判错成「有」就会画出一个点下去必然失败的播放器；判错成「没有」则让本来能放的语音
+ *    变成一段文字。
+ * 2. **屏幕上该显示哪一句**——`reply` 是**她说的话**（音频念的就是它），`text` 是**转写**
+ *    （我们那段音频被识别成什么）。两者的顺序反过来，用户看到的就是自己说的话冒充她的回答。
+ */
+class VoiceOutputTest {
+
+    // —— provider 降级信号 ——
+
+    @Test
+    fun `the silent provider is recognised literally`() {
+        assertTrue(isSilentVoiceProvider(VoiceProvider.SILENT))
+        // 机器可读码：容忍首尾空白与大小写，但不容忍别的词。
+        assertTrue(isSilentVoiceProvider(" SILENT "))
+        assertFalse(isSilentVoiceProvider("emotiontts"))
+        assertFalse(isSilentVoiceProvider(""))
+        assertFalse(isSilentVoiceProvider(null))
+    }
+
+    @Test
+    fun `silent frames never count as having audio`() {
+        // 契约：silent ⇒ audio 空。万一服务端还是塞了字节，也不能画播放器（它自己说这轮没发音）。
+        assertFalse(voiceOutputHasAudio(audio = null, provider = VoiceProvider.SILENT))
+        assertFalse(voiceOutputHasAudio(audio = "QUJD", provider = VoiceProvider.SILENT))
+    }
+
+    @Test
+    fun `a normal provider needs actual bytes to be playable`() {
+        assertTrue(voiceOutputHasAudio(audio = "QUJD", provider = "emotiontts"))
+        // 没给 provider（老服务端 / 省略该键）、但有字节 ⇒ 能放。
+        assertTrue(voiceOutputHasAudio(audio = "QUJD", provider = null))
+        // 有 provider 却没字节 ⇒ 没有音频（空串与 null 同一档）。
+        assertFalse(voiceOutputHasAudio(audio = "", provider = "emotiontts"))
+        assertFalse(voiceOutputHasAudio(audio = null, provider = "emotiontts"))
+    }
+
+    // —— text vs reply ——
+
+    @Test
+    fun `reply wins because it is what she actually said`() {
+        assertEquals("我在呢", voiceReplyText(reply = "我在呢", text = "你今天在吗"))
+    }
+
+    @Test
+    fun `a missing reply falls back to the transcript`() {
+        assertEquals("你今天在吗", voiceReplyText(reply = null, text = "你今天在吗"))
+        assertEquals("你今天在吗", voiceReplyText(reply = "  ", text = "你今天在吗"))
+    }
+
+    @Test
+    fun `both missing means show nothing instead of inventing a line`() {
+        assertNull(voiceReplyText(reply = null, text = null))
+        assertNull(voiceReplyText(reply = "", text = " "))
+    }
+
+    // —— 那一句说明：两档说的不是同一件事 ——
+
+    @Test
+    fun `the silent note says only text this round`() {
+        assertEquals(VOICE_SILENT_NOTE, voiceReplyNote(silent = true, hasAudioFile = false))
+        // silent 档即便本地碰巧有个文件也不该说「本机没准备好」。
+        assertEquals(VOICE_SILENT_NOTE, voiceReplyNote(silent = true, hasAudioFile = true))
+    }
+
+    @Test
+    fun `a local decode failure is reported as a local problem not as silence`() {
+        assertEquals(VOICE_REPLY_LOCAL_UNAVAILABLE_NOTE, voiceReplyNote(silent = false, hasAudioFile = false))
+    }
+
+    @Test
+    fun `a playable reply needs no note`() {
+        assertNull(voiceReplyNote(silent = false, hasAudioFile = true))
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/chat/VoicePlaybackTest.kt

@@ -0,0 +1,152 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 语音播放通道的状态机（纯函数）。
+ *
+ * 它要钉住的是**跨气泡**的那几条事实——少了任何一条，真机上就会出现「两条一起响」、
+ * 「界面显示 A 在响而喇叭里是 B」或者「A 的失败提示挂在 B 上」：
+ *
+ * 1. 再点一下同一目标 = 停（**加载中也算**：用户不该被慢下载困住）；
+ * 2. 点另一条 = 从它重新开始（旧的那条由调用方停下并释放，纯函数只说状态变成什么）；
+ * 3. **迟到的回调不许改状态**：`prepared` / `failed` / `finished` 三个转换都只认「目标就是当前
+ *    这一条」，而且 `prepared` 只从 `Loading` 出发（正在响的那一条不会被一个迟到的失败说成失败）；
+ * 4. `Failed` 不粘：再点一次就是重试（回 `Loading`）；
+ * 5. `silenced`（停下 / 换会话 / 组件销毁）**收所有态**，包括 `Failed` 那句提示。
+ */
+class VoicePlaybackTest {
+
+    private val a = "msg-a"
+    private val b = "msg-b"
+
+    // —— 1 / 2. 按下与换目标 ——
+
+    @Test
+    fun `pressing from idle starts loading that message`() {
+        assertEquals(VoicePlaybackState.Loading(a), VoicePlaybackState.Idle.pressed(a))
+    }
+
+    @Test
+    fun `pressing the message that is playing stops it`() {
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Playing(a).pressed(a))
+    }
+
+    @Test
+    fun `pressing the message that is loading cancels it`() {
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Loading(a).pressed(a))
+    }
+
+    @Test
+    fun `pressing another message switches to it`() {
+        assertEquals(VoicePlaybackState.Loading(b), VoicePlaybackState.Playing(a).pressed(b))
+        assertEquals(VoicePlaybackState.Loading(b), VoicePlaybackState.Loading(a).pressed(b))
+    }
+
+    @Test
+    fun `pressing a failed message retries it`() {
+        val failed = VoicePlaybackState.Failed(a, "网络不可用")
+
+        assertFalse("失败不算「占着这条」，否则再点一下只会被当成「停」", failed.isActiveFor(a))
+        assertEquals(VoicePlaybackState.Loading(a), failed.pressed(a))
+    }
+
+    // —— 3. 迟到的回调 ——
+
+    @Test
+    fun `prepared only moves the message that was loading`() {
+        assertEquals(VoicePlaybackState.Playing(a), VoicePlaybackState.Loading(a).prepared(a))
+        // 用户已经点了别的 / 点了停：迟到的「准备好」不许把界面拽回去。
+        assertEquals(VoicePlaybackState.Loading(b), VoicePlaybackState.Loading(b).prepared(a))
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Idle.prepared(a))
+        // 正在响的那一条收到 prepared 也原样（它已经在响了）。
+        assertEquals(VoicePlaybackState.Playing(a), VoicePlaybackState.Playing(a).prepared(a))
+    }
+
+    @Test
+    fun `failed only moves the message that was loading`() {
+        assertEquals(VoicePlaybackState.Failed(a, "坏了"), VoicePlaybackState.Loading(a).failed(a, "坏了"))
+        // 正在响的那一条不该被一个迟到的失败回调说成失败（解码错误的真实顺序是「先停再报」）。
+        assertEquals(
+            VoicePlaybackState.Playing(a),
+            VoicePlaybackState.Playing(a).failed(a, "坏了"),
+        )
+        assertEquals(VoicePlaybackState.Loading(b), VoicePlaybackState.Loading(b).failed(a, "坏了"))
+    }
+
+    @Test
+    fun `finished only clears the message that was playing`() {
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Playing(a).finished(a))
+        assertEquals(VoicePlaybackState.Playing(b), VoicePlaybackState.Playing(b).finished(a))
+        assertEquals(VoicePlaybackState.Loading(a), VoicePlaybackState.Loading(a).finished(a))
+    }
+
+    // —— 4 / 5. 停下来收所有态 ——
+
+    @Test
+    fun `silencing collects every state including a failure note`() {
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Idle.silenced)
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Loading(a).silenced)
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Playing(a).silenced)
+        assertEquals(VoicePlaybackState.Idle, VoicePlaybackState.Failed(a, "坏了").silenced)
+    }
+
+    @Test
+    fun `a silenced channel is active for nobody`() {
+        assertFalse(VoicePlaybackState.Idle.silenced.isActiveFor(a))
+        assertTrue(VoicePlaybackState.Loading(a).isActiveFor(a))
+        assertTrue(VoicePlaybackState.Playing(a).isActiveFor(a))
+    }
+
+    // —— 视图查询（气泡据此决定画什么）——
+
+    @Test
+    fun `only playing counts as playing`() {
+        assertTrue(VoicePlaybackState.Playing(a).isPlayingFor(a))
+        assertFalse("加载中不算在响", VoicePlaybackState.Loading(a).isPlayingFor(a))
+        assertFalse(VoicePlaybackState.Playing(b).isPlayingFor(a))
+    }
+
+    @Test
+    fun `loading and playing are two different questions`() {
+        // 界面那一句「加载中…」只能在**真的在取字节**时出现（`isActiveFor` 会把「正在响」也算进来，
+        // 拿它当条件会让一条 30 秒的语音整段播放期间都写着「加载中…」）。
+        assertTrue(VoicePlaybackState.Loading(a).isLoadingFor(a))
+        assertFalse(VoicePlaybackState.Playing(a).isLoadingFor(a))
+        assertFalse(VoicePlaybackState.Loading(b).isLoadingFor(a))
+        assertFalse(VoicePlaybackState.Idle.isLoadingFor(a))
+        assertFalse(VoicePlaybackState.Failed(a, "坏了").isLoadingFor(a))
+    }
+
+    @Test
+    fun `a failure note is only reported for its own message`() {
+        val failed = VoicePlaybackState.Failed(a, "这条语音太大，本机放不了")
+
+        assertEquals("这条语音太大，本机放不了", failed.failureOf(a))
+        assertNull(failed.failureOf(b))
+        assertNull(VoicePlaybackState.Idle.failureOf(a))
+        assertNull(VoicePlaybackState.Playing(a).failureOf(a))
+    }
+
+    // —— 一条完整的用户路径 ——
+
+    @Test
+    fun `a full press load failure retry stop path`() {
+        var state: VoicePlaybackState = VoicePlaybackState.Idle
+
+        state = state.pressed(a)
+        assertEquals(VoicePlaybackState.Loading(a), state)
+        state = state.failed(a, "语音加载失败，请稍后重试")
+        assertEquals("失败提示挂在这一条上", "语音加载失败，请稍后重试", state.failureOf(a))
+        state = state.pressed(a)
+        assertEquals("重试清掉上一句", null, state.failureOf(a))
+        state = state.prepared(a)
+        assertEquals(VoicePlaybackState.Playing(a), state)
+        state = state.finished(a)
+        assertEquals("放完回初始外观，不留痕迹", VoicePlaybackState.Idle, state)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/chat/VoiceSpeakTest.kt

@@ -0,0 +1,178 @@
+package top.yeij.cyrene.domain.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.domain.parse.parse
+import java.io.IOException
+
+/**
+ * 「朗读」这条路上本端要说的那几句话与纯判据（[ttsTextOf] / [ttsFailureOf] / [ttsClipIdOf]）。
+ *
+ * 这个文件全是纯函数，不碰网络也不碰 Android：取字节在 `SpeechClientTest`（真 HTTP），
+ * 图标与播放接线在界面层。
+ *
+ * ## 它钉住的四件事
+ * 1. **念什么**：只念正文（`body`）——抬头（`head`）像字幕、旁白（`tail`）是舞台指示，都不念；
+ *    一条消息切成多个气泡时按 `\n` 拼，空正文不产生空行。
+ * 2. **能不能念**：「这条消息有没有可念的正文」是唯一判据，`ChatViewModel.speak`（发不发请求）与
+ *    `MessageBubble`（画不画图标）用的必须是同一个答案；`mode` 不是 `chat` 时念的是**原文**，
+ *    因为那时气泡里放的就是原文、一个 markup 都不解析。
+ * 3. **失败算哪一档**：只有服务端明确回了「配置缺失」类 `code` 才进
+ *    [TtsFailure.Unconfigured]（重试永远不会成功，文案要说清缺什么、且不提重试），
+ *    其余一切（网络、解析、401、`voice_unavailable` / `tts_failed` / `tts_empty`）都是
+ *    [TtsFailure.Soft]。
+ * 4. **播放键**：`tts:<messageId>`，与语音副本的键（就是 `messageId`）分得开。
+ */
+class VoiceSpeakTest {
+
+    // ---- 念什么：气泡 → 文本 ------------------------------------------------
+
+    @Test
+    fun `bubbles are joined by a newline so the pause lands between paragraphs`() {
+        assertEquals("你好\n再见", ttsTextOf(parse("<p>你好</p><p>再见</p>")))
+    }
+
+    @Test
+    fun `an empty message has nothing to read out loud`() {
+        assertNull(ttsTextOf(parse("")))
+        assertNull(ttsTextOf(emptyList()))
+    }
+
+    @Test
+    fun `narration alone is stage direction and is not read out loud`() {
+        // 旁白整段进 head（首部依附），正文为空 ⇒ 没有可念的字。
+        assertNull(ttsTextOf(parse("<p><narration>她笑了笑</narration></p>")))
+    }
+
+    @Test
+    fun `the speaker head is skipped and only the body is read`() {
+        val bubbles = parse("<p><narration>她笑了笑</narration>你好</p>")
+
+        assertEquals("你好", ttsTextOf(bubbles))
+    }
+
+    @Test
+    fun `a blank bubble does not become a blank line`() {
+        assertEquals("你好\n再见", ttsTextOf(parse("<p>你好</p><p> </p><p>再见</p>")))
+    }
+
+    // ---- 能不能念：一条消息 → 文本 ------------------------------------------
+
+    @Test
+    fun `a chat message is read after the markup is stripped`() {
+        assertEquals("你好\n再见", ttsTextOf(message(content = "<p>你好</p><p>再见</p>", mode = "chat")))
+    }
+
+    @Test
+    fun `a message without a mode counts as a chat message`() {
+        assertEquals("你好", ttsTextOf(message(content = "<p>你好</p>", mode = null)))
+        assertEquals("你好", ttsTextOf(message(content = "<p>你好</p>", mode = "  ")))
+    }
+
+    @Test
+    fun `a non chat mode is read verbatim because the bubble shows the raw text`() {
+        // 非 chat 的 mode 下气泡里放的就是原文（MessageBubble 的 isChat 判据），
+        // 所以朗读念的也必须是那同一段字，一个标签都不许吞。
+        assertEquals("<p>你好</p>", ttsTextOf(message(content = "<p>你好</p>", mode = "roleplay")))
+        assertEquals("你好", ttsTextOf(message(content = "  你好  ", mode = "roleplay")))
+    }
+
+    @Test
+    fun `a message with nothing to say answers null in both modes`() {
+        assertNull(ttsTextOf(message(content = "", mode = "chat")))
+        assertNull(ttsTextOf(message(content = "   ", mode = "roleplay")))
+        assertNull(ttsTextOf(message(content = "<p><narration>她笑了笑</narration></p>", mode = "chat")))
+    }
+
+    // ---- 失败算哪一档 ------------------------------------------------------
+
+    @Test
+    fun `a persona without a voice mapping says so and is not worth retrying`() {
+        val failure = ttsFailureOf(serverError(TTS_CODE_PERSONA_UNMAPPED))
+
+        assertEquals(TtsFailure.Unconfigured(TTS_CODE_PERSONA_UNMAPPED), failure)
+        assertEquals(TTS_PERSONA_UNMAPPED_MESSAGE, failure.message)
+        assertFalse("配置缺失类重试永远不会成功", failure.retryable)
+    }
+
+    @Test
+    fun `a session without any character says so instead of blaming the network`() {
+        val failure = ttsFailureOf(serverError(TTS_CODE_NO_CHARACTER))
+
+        assertEquals(TTS_NO_CHARACTER_MESSAGE, failure.message)
+        assertFalse(failure.retryable)
+    }
+
+    @Test
+    fun `an unrecognized code is not guessed into the configuration bucket`() {
+        // 本端认不出这个 code，就**不知道**它是配置缺失还是临时故障 ⇒ 不猜，落柔和档：
+        // 判成「配置没配好」等于对用户说了一句本端没有依据的话。
+        val failure = ttsFailureOf(serverError("tts_something_new"))
+
+        assertEquals(TtsFailure.Soft, failure)
+        assertTrue(failure.retryable)
+    }
+
+    @Test
+    fun `a configuration failure built from an unknown code still explains itself`() {
+        // 兜底分支：万一将来有调用点直接构造了一个本端还不认识的配置缺失码，
+        // 文案仍是「缺发音人」而不是「网络不好」，且照样不提重试。
+        val failure = TtsFailure.Unconfigured("tts_something_new")
+
+        assertEquals(TTS_UNCONFIGURED_MESSAGE, failure.message)
+        assertFalse(failure.retryable)
+    }
+
+    @Test
+    fun `a server that is merely unavailable right now stays in the soft bucket`() {
+        listOf("voice_unavailable", "tts_failed", "tts_empty").forEach { code ->
+            val failure = ttsFailureOf(serverError(code))
+
+            assertEquals("$code 该是柔和档", TtsFailure.Soft, failure)
+            assertEquals(TTS_SOFT_FAILURE_MESSAGE, failure.message)
+            assertTrue("$code 过一会儿再点是有意义的", failure.retryable)
+        }
+    }
+
+    @Test
+    fun `an expired token is soft because renewal can still save it`() {
+        val failure = ttsFailureOf(CyreneException(CyreneError.Unauthorized(code = "", message = "")))
+
+        assertEquals(TtsFailure.Soft, failure)
+    }
+
+    @Test
+    fun `a network or parse failure is soft and does not pretend to know why`() {
+        assertEquals(TtsFailure.Soft, ttsFailureOf(CyreneException(CyreneError.Local(CyreneError.LocalKind.Timeout))))
+        assertEquals(TtsFailure.Soft, ttsFailureOf(IOException("boom")))
+        // 非 CyreneException 一律柔和档：本端确实不知道断在哪一段。
+        assertEquals(TtsFailure.Soft, ttsFailureOf(IllegalStateException("boom")))
+    }
+
+    // ---- 播放键 ------------------------------------------------------------
+
+    @Test
+    fun `the clip key is namespaced so it never collides with a voice copy`() {
+        assertEquals("tts:m-1", ttsClipIdOf("m-1"))
+        assertFalse("朗读与语音副本的键必须分得开", ttsClipIdOf("m-1") == "m-1")
+    }
+
+    private fun serverError(code: String) = CyreneException(
+        CyreneError.Server(code = code, message = "服务端说明", httpStatus = 500),
+    )
+
+    private fun message(content: String, mode: String?) = HistoryMessageDto(
+        id = "m-1",
+        sessionId = "web",
+        role = "assistant",
+        content = content,
+        mode = mode,
+        createdAt = 0L,
+    )
+}

app/src/test/kotlin/top/yeij/cyrene/domain/parse/ChatContentParserTest.kt

@@ -68,6 +68,348 @@ class ChatContentParserTest {
         assertEquals(listOf(ContentPart.Action("笑")), bubbles[0].tail)
     }
 
+    // ------------------------------------------------------------------
+    // `<br>` 分隔符（契约 v0.89 更正：与 `<p>` 同级的气泡/消息分隔符，不是行内标签）
+    // ------------------------------------------------------------------
+
+    /** 契约表第一行：`<p>甲<br>乙</p>` ⇒ **两条**气泡。 */
+    @Test
+    fun lineBreakInsideParagraphSplitsBubbles() {
+        val bubbles = parse("<p>甲<br>乙</p>")
+        assertEquals(2, bubbles.size)
+        assertEquals(listOf("甲", "乙"), bubbles.map { it.body })
+        assertEquals(listOf(ContentPart.Text("甲"), ContentPart.Text("乙")), bubbles.flatMap { it.parts })
+    }
+
+    /** 契约表第二行：没有 `<p>` 时同理 ⇒ 两条气泡。 */
+    @Test
+    fun lineBreakWithoutParagraphAlsoSplitsBubbles() {
+        assertEquals(listOf("甲", "乙"), parse("甲<br>乙").map { it.body })
+        assertEquals(listOf("甲", "乙", "丙"), parse("甲<br>乙<br>丙").map { it.body })
+    }
+
+    /** 契约表第三行：`<p>甲<br><br>乙</p>` ⇒ `甲`、`乙`（**空气泡照旧丢弃**，与既有 `<p>` 口径一致）。 */
+    @Test
+    fun emptyBubblesBetweenLineBreaksAreDropped() {
+        assertEquals(listOf("甲", "乙"), parse("<p>甲<br><br>乙</p>").map { it.body })
+        assertEquals(listOf("甲", "乙"), parse("甲<br><br>乙").map { it.body })
+        assertEquals(listOf("甲", "乙"), parse("甲<br>\n<br>乙").map { it.body })
+        assertTrue(parse("<p><br></p>").isEmpty())
+        assertTrue(parse("<br>").isEmpty())
+        assertTrue(parse("<br><br>").isEmpty())
+    }
+
+    /** 契约表第四行：`<br>` 两侧都是空白 ⇒ 不产生多余空气泡（只吃空白，正文一个字不掉）。 */
+    @Test
+    fun whitespaceAroundLineBreakProducesNoExtraBubble() {
+        assertEquals(listOf("甲", "乙"), parse("甲 <br> 乙").map { it.body })
+        assertEquals(listOf("甲", "乙"), parse(" 甲<br>乙 ").map { it.body })
+        assertEquals(listOf("甲"), parse("  <br>甲").map { it.body })
+        assertEquals(listOf("甲"), parse("甲<br>  ").map { it.body })
+        assertEquals(listOf("甲", "乙"), parse("<p>甲<br>   </p><p>乙</p>").map { it.body })
+    }
+
+    /** 三种写法等价（`<br>` / `<br/>` / `</br>`），带属性一样算，`<br >` 这种空白写法也收。 */
+    @Test
+    fun lineBreakFormsAreEquivalent() {
+        for (form in listOf("<br>", "<br/>", "<br />", "</br>", "</br/>", "<br >", "<br class=x>")) {
+            assertEquals("「$form」应当是一样的一条分隔", listOf("甲", "乙"), parse("甲${form}乙").map { it.body })
+            assertEquals("「$form」在 `<p>` 里同理", listOf("甲", "乙"), parse("<p>甲${form}乙</p>").map { it.body })
+        }
+    }
+
+    /**
+     * 大小写不敏感（`<BR>` 也分隔）：v0.89 那句「标签名大小写不敏感」把 `br` 一起罩住了，且后端 IM
+     * 出站 `channelbridge/sanitize.go` 的正则本来就是 `(?is)`（`回执三十` 原话）。
+     */
+    @Test
+    fun lineBreakTagIsCaseInsensitive() {
+        for (form in listOf("<BR>", "<Br>", "</BR>", "<bR/>", "<BR class=x>")) {
+            assertEquals("「$form」应当是一样的一条分隔", listOf("甲", "乙"), parse("甲${form}乙").map { it.body })
+        }
+    }
+
+    /** 名字后面不是 `>`/空白/`/` 的都不是分隔符：`<br2>`、`<boolean>`、`<br-x>` 只是普通文本。 */
+    @Test
+    fun lookalikeTagsAreNotLineBreaks() {
+        for (raw in listOf("<br2>甲</br2>", "<boolean>甲</boolean>", "<br-x>甲</br-x>", "<br/x>甲", "1 < 2")) {
+            assertEquals("「$raw」不是分隔符", listOf(raw), parse(raw).map { it.body })
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // `<br>` 的**保护区**（`回执三十三 §三②`：只有普通文本层的 `<br>` 才分隔）
+    //
+    // `回执三十一` 说的是「**始终**处理为多条消息隔断」，`回执三十三` 把它收紧了：`<code>` 与角色
+    // 注记**内部**的不分隔。后端给的两条理由在我们这边同样成立：
+    //   1. `<code>` 是**成对**元素，从中间切开必然两半都不平衡 ⇒ 按硬口径「不平衡 ⇒ 不渲染」
+    //      **整段降级为字面量**，用户直接看到裸标签；
+    //   2. `<action>她<br>点点头</action>` 若切成两段，就成了「她」「点点头」**两条聊天消息**
+    //      ——等于把注记正文当正文发了出去。
+    // 口径与理由的全文写在 `ChatContentParser.appendRegion` / `protectedSpans` 的 KDoc 里。
+    // ------------------------------------------------------------------
+
+    /**
+     * `回执三十三 §三②` 第一半：**`<code>` 内部的 `<br>` 不分隔**，且作用域不能被切坏。
+     *
+     * 我们定的口径：作用域里的 `<br>` 就是**普通字符、逐字原样**——与 `<code><b>甲</b></code>` 里的
+     * `<b>` 同一规矩（`codeContentIsNotParsed` 钉着）。所以这条同时钉三件事：**只有一条气泡**、
+     * `<code>` 那一对**被消费掉**（正文里没有裸 `<code>` ⇒ 作用域没被降级）、内容**逐字保留**
+     * （含那个字面的 `<br>`，字符一个不丢）。
+     */
+    @Test
+    fun lineBreakInsideCodeDoesNotSplitAndTheScopeSurvives() {
+        val bubbles = parse("<p><code>甲<br>乙</code></p>")
+        assertEquals("`<code>` 里的 `<br>` 不该分隔", 1, bubbles.size)
+        assertEquals("甲<br>乙", bubbles.single().body)
+        assertEquals(listOf(run("甲<br>乙", InlineStyle.Code)), bubbles.single().runs)
+        assertFalse("`<code>` 作用域不该被降级成裸标签", bubbles.single().body.contains("<code"))
+        // 无 `<p>` 时同理（分隔符本来就与 `<p>` 同级）
+        assertEquals(listOf("甲<br>乙"), parse("<code>甲<br>乙</code>").map { it.body })
+        // 分隔符的三种写法 + 大小写 + 属性，在保护区里同样都拦下来（它们先要是分隔符候选）
+        for (form in listOf("<br>", "<br/>", "<br />", "</br>", "<BR>", "<br class=x>")) {
+            val one = parse("<p><code>甲${form}乙</code></p>")
+            assertEquals("「$form」在 `<code>` 里不该分隔", 1, one.size)
+            assertEquals("「$form」必须逐字留在代码里", "甲${form}乙", one.single().body)
+        }
+        // 保护区**只管**作用域内部：`<code>` 外面的 `<br>` 照旧分隔
+        assertEquals(listOf("丙", "甲<br>乙"), parse("<p>丙<br><code>甲<br>乙</code></p>").map { it.body })
+    }
+
+    /**
+     * `回执三十三 §三②` 第二半：**角色注记内部的 `<br>` 不分隔、不产生气泡**。
+     *
+     * 「不产生气泡」正是后端点名的信息泄露：切成两段等于把注记正文当两条聊天消息发出去。
+     * 我们这边的落点是**既有旁白语义**——注记整体被 `ROLE_RE` 认下、进 `head` / `tail`、正文为空；
+     * 注记文本**逐字原文**（`parts` 是红线：编辑框/搜索/通知都读它，而旁白那一行画的正是它），
+     * 所以里面那个 `<br>` 与 `<b>` 一样只是字面文本（`narrationTextIsLeftExactlyAsWritten` 同款）。
+     */
+    @Test
+    fun lineBreakInsideNoteBlocksDoesNotSplitAndProducesNoBubble() {
+        for (raw in listOf("<p><action>她<br>点点头</action></p>", "<action>她<br>点点头</action>")) {
+            val bubbles = parse(raw)
+            assertEquals("「$raw」不该切成两条消息", 1, bubbles.size)
+            assertEquals("注记仍然不产生正文气泡", "", bubbles.single().body)
+            assertTrue("注记不做行内渲染 ⇒ runs 为空", bubbles.single().runs.isEmpty())
+            assertEquals(listOf(ContentPart.Action("她<br>点点头")), bubbles.single().head)
+            assertEquals(
+                "注记文本逐字原文（`parts` 红线）",
+                listOf(ContentPart.Action("她<br>点点头")),
+                bubbles.single().parts,
+            )
+        }
+
+        // `<narration>` 同理，且**附着语义一个字没动**：尾部 → tail，首部 → head
+        val tailed = parse("<p>你好<narration>她<br>点点头</narration></p>").single()
+        assertEquals("你好", tailed.body)
+        assertEquals(listOf(ContentPart.Narration("她<br>点点头")), tailed.tail)
+        val headed = parse("<p><narration>她<br>点点头</narration>你好</p>").single()
+        assertEquals("你好", headed.body)
+        assertEquals(listOf(ContentPart.Narration("她<br>点点头")), headed.head)
+
+        // 保护区只管作用域内部：注记**外面**的 `<br>` 照旧分隔，旁白照旧附着到下一段
+        val across = parse("<p><action>她<br>点点头</action><br>你好</p>")
+        assertEquals(listOf("你好"), across.map { it.body })
+        assertEquals(listOf(ContentPart.Action("她<br>点点头")), across.single().head)
+    }
+
+    /**
+     * 保护区**只管 `<br>` 算不算分隔符**，别的语义一个字都不动；而且只有 `<code>` 与角色注记算
+     * 保护区——**白名单行内元素（`<b>` / `<i>` / `<u>`）不算**（W68 登记的「跨分隔符的标签各自回落
+     * 原文」因此逐字保留，见 [inlineTagsCannotSpanALineBreak]）。
+     */
+    @Test
+    fun onlyCodeAndNoteScopesProtectLineBreaks() {
+        // `<b>` 里那个 `<br>`：照样分隔（口径没变）
+        assertEquals(listOf("<b>甲", "乙</b>"), parse("<p><b>甲<br>乙</b></p>").map { it.body })
+        // `<u>` 一样（W71 刚加回白名单，但它不是作用域）
+        assertEquals(listOf("<u>甲", "乙</u>"), parse("<p><u>甲<br>乙</u></p>").map { it.body })
+        // 一个 `<code>` 里几个 `<br>` 全都不分隔
+        assertEquals(listOf("甲<br>乙<br>丙"), parse("<code>甲<br>乙<br>丙</code>").map { it.body })
+        // 保护区**不**改注记/旁白/星号的任何既有语义：注记照样进 tail、`＊笑＊` 照样是动作，
+        // 正文里只剩 `<code>` 那一段（它没被切开，`<br>` 是代码里的内容）
+        val mixed = parse("<p><code>甲<br>乙</code>与<action>她<br>点点头</action>＊笑＊</p>").single()
+        assertEquals("甲<br>乙与", mixed.body)
+        assertEquals(
+            listOf(ContentPart.Action("她<br>点点头"), ContentPart.Action("笑")),
+            mixed.tail,
+        )
+    }
+
+    /**
+     * **嵌套**：`<code>` 里再套白名单标签时，里面的东西仍是「内容」（不解析、不计结构），
+     * 保护区也照样罩着它；`<code>` 套在 `<b>` 里时两边的边界各自成立。
+     */
+    @Test
+    fun nestedTagsInsideACodeZoneAreContentAndTheirLineBreakStillDoesNotSplit() {
+        val codeInCode = parse("<p><code>甲<b>乙<br>丙</b></code></p>")
+        assertEquals(1, codeInCode.size)
+        assertEquals("甲<b>乙<br>丙</b>", codeInCode.single().body)
+        assertEquals(listOf(run("甲<b>乙<br>丙</b>", InlineStyle.Code)), codeInCode.single().runs)
+
+        val boldAroundCode = parse("<p><b>甲<code>乙<br>丙</code>丁</b></p>")
+        assertEquals(1, boldAroundCode.size)
+        assertEquals("甲乙<br>丙丁", boldAroundCode.single().body)
+        assertEquals(
+            listOf(
+                run("甲", InlineStyle.Bold),
+                run("乙<br>丙", InlineStyle.Bold, InlineStyle.Code),
+                run("丁", InlineStyle.Bold),
+            ),
+            boldAroundCode.single().runs,
+        )
+    }
+
+    /**
+     * ⚠️ **未闭合的作用域不算作用域**（我们定的口径，理由写在 `appendRegion` 的 KDoc 里）：
+     * 判据只看「**成对**」，而消费侧本来就不认未闭合的那个（未闭合的 `<code>` 在行内层不是作用域、
+     * 整段降级为原文；未闭合的 `<action>` 在 `ROLE_RE` 那里也配不出旁白）——去保护一个消费侧不认的
+     * 作用域，等于让切分层与消费层对同一段文本有两种结构判断。
+     * 另一条理由是**爆炸半径**：若「未闭合 ⇒ 保护到这段文本结尾」，一个漏掉 `</code>` 的笔误就会把
+     * 后面所有 `<br>` 一起吞掉、把本该分开的消息并成一条。
+     * 两种读法都不渲染、都不丢字（未闭合那一档本来就是「不平衡 ⇒ 原样显示」），差别只在气泡怎么切。
+     */
+    @Test
+    fun unclosedProtectedScopesDoNotProtectLineBreaks() {
+        assertEquals(listOf("<code>甲", "乙"), parse("<code>甲<br>乙").map { it.body })
+        assertEquals(listOf("<action>她", "点点头"), parse("<action>她<br>点点头").map { it.body })
+        assertEquals(listOf("<code>甲", "乙"), parse("<p><code>甲<br>乙</p>").map { it.body })
+        // 闭合写错了名字（`</code>` 写成别的）同样不算成对
+        assertEquals(listOf("<code>甲", "乙</action>"), parse("<code>甲<br>乙</action>").map { it.body })
+        // 而且它仍然是**字面**（未闭合那一档照旧「不平衡 ⇒ 不渲染」），一个字都没丢
+        assertEquals("<code>甲", parse("<code>甲<br>乙").first().body)
+    }
+
+    /**
+     * **两支各算各的**（我们定的口径，见 `protectedSpans`）：`<code>` 与角色注记各自配对，
+     * 因为那本来就是两个消费侧各自的尺子。所以「某一支没闭合」只影响**那一支**——里面那个已经
+     * 配对好的作用域照样保护它自己的 `<br>`，而没闭合的那一支里的 `<br>` 照旧分隔。
+     */
+    @Test
+    fun aPairedZoneStillProtectsItsLineBreakWhileAnotherZoneIsUnclosed() {
+        // 外层 `<code>` 没闭合（不保护），里面那个配对好的 `<action>` 照样保护它的 `<br>`
+        val bubbles = parse("<code>甲<br>乙<action>她<br>点点头</action>丙")
+        assertEquals(2, bubbles.size)
+        assertEquals(listOf("<code>甲", "乙丙"), bubbles.map { it.body })
+        assertEquals(
+            "注记整体被认下（语序照原文：`parts` 为准）",
+            listOf(ContentPart.Text("乙"), ContentPart.Action("她<br>点点头"), ContentPart.Text("丙")),
+            bubbles[1].parts,
+        )
+        assertEquals(listOf(ContentPart.Action("她<br>点点头")), bubbles[1].head)
+        assertTrue("注记不产生气泡正文 ⇒ 第二条气泡的 runs 为空", bubbles[1].runs.isEmpty())
+    }
+
+    /**
+     * 流式：**保护区**里的残缺 `<br` 一样不许把字吐上屏。
+     *
+     * 中间态靠的是既有那条扣留规则——`<code>` / `<action>` / `<narration>` 的开标签本来就在栈里，
+     * 所以整个作用域（连同里面还没写完的 `<br`）一起被扣到闭合为止。收口后与一次性解析逐字一致，
+     * 且作用域真的没被切开：`<code>` 里的那个 `<br>` 是字面内容。
+     */
+    @Test
+    fun streamingWithholdsPartialLineBreakInsideProtectedScopes() {
+        // 作用域还没闭合时，屏幕上只该有它前面那一段（里面的字面内容一个字都不许先露脸）
+        for (partial in listOf(
+            "甲<code", "甲<code>乙", "甲<code>乙<br", "甲<CODE>乙<br",
+            "甲<action>她", "甲<action>她<br", "甲<narration>她<br",
+        )) {
+            assertEquals(
+                "「$partial」残缺时必须扣住，只显示作用域前的正文",
+                listOf("甲"),
+                StreamingContentParser().onDelta(partial).map { it.body },
+            )
+        }
+
+        val text = "甲<code>乙<br>丙</code>丁"
+        val parser = StreamingContentParser()
+        var shown = emptyList<String>()
+        for (ch in text) {
+            val bodies = parser.onDelta(ch.toString()).map { it.body }
+            assertTrue("`<code>` 漏上了屏：$bodies", bodies.none { it.contains("<code") })
+            assertTrue("气泡数回退了：$shown → $bodies", bodies.size >= shown.size)
+            shown.forEachIndexed { i, body ->
+                assertTrue("已显示的正文改口了：$body → ${bodies[i]}", bodies[i].startsWith(body))
+            }
+            shown = bodies
+        }
+        assertEquals(listOf("甲乙<br>丙丁"), parser.finish().map { it.body })
+        assertEquals(parse(text), parser.finish())
+    }
+
+    /**
+     * 跨分隔符的行内标签：**先切分、再逐段各自做行内解析** ⇒ 两段各自「结构不平衡」⇒ 两段都回落原文。
+     *
+     * 层序理由写在 `ChatContentParser.appendRegion` 的 KDoc：`<br>` 与 `<p>` 同级 ⇒ 分隔符先于行内
+     * 解析；而且一个气泡 = 一条消息，跨分隔符的标签在结构上不可能成立（后端剥标签时同样是按单条
+     * 消息判平衡的）。
+     */
+    @Test
+    fun inlineTagsCannotSpanALineBreak() {
+        for (raw in listOf("<p><b>甲<br>乙</b></p>", "<b>甲<br>乙</b>")) {
+            val bubbles = parse(raw)
+            assertEquals("「$raw」两段都该回落原文", listOf("<b>甲", "乙</b>"), bubbles.map { it.body })
+            assertTrue(bubbles.all { it.runs.isEmpty() })
+        }
+
+        // 每一段**各自**平衡时照常渲染：粗体只罩住它自己那一段
+        val ok = parse("<p><b>甲</b><br><b>乙</b></p>")
+        assertEquals(listOf("甲", "乙"), ok.map { it.body })
+        assertEquals(listOf(run("甲", InlineStyle.Bold)), ok[0].runs)
+        assertEquals(listOf(run("乙", InlineStyle.Bold)), ok[1].runs)
+    }
+
+    /** `parts` 仍是**逐字原文**：分隔符 `<br>` 与 `<p>` / `</p>` 一样属于结构，不进片段。 */
+    @Test
+    fun lineBreakIsStructureSoItStaysOutOfParts() {
+        val bubble = parse("<p>日落 <b>18:35</b><br>记住了。</p>").first()
+        assertEquals(listOf(ContentPart.Text("日落 <b>18:35</b>")), bubble.parts)
+        assertEquals("日落 18:35", bubble.body)
+        assertEquals(listOf(run("日落 "), run("18:35", InlineStyle.Bold)), bubble.runs)
+    }
+
+    /** `<br>` 与旁白依附的关系：纯旁白那一段照旧不独立成气泡，跨分隔符附着到下一段（与 `<p>` 同款）。 */
+    @Test
+    fun noteOnlySegmentStillAttachesAcrossALineBreak() {
+        val bubbles = parse("<action>笑</action><br>你好")
+        assertEquals(1, bubbles.size)
+        assertEquals("你好", bubbles[0].body)
+        assertEquals(listOf(ContentPart.Action("笑")), bubbles[0].head)
+    }
+
+    /** 逐字符流式：中间态一帧都不许把 `<br` 当正文吐上屏，收口后真的变成两条气泡。 */
+    @Test
+    fun lineBreakSplitsBubblesWhileStreaming() {
+        val parser = StreamingContentParser()
+        var shown = emptyList<String>()
+        for (ch in "甲<br>乙") {
+            val bodies = parser.onDelta(ch.toString()).map { it.body }
+            assertTrue("中间态把标签漏上了屏：$bodies", bodies.none { it.contains('<') })
+            assertTrue("气泡数回退了：$shown → $bodies", bodies.size >= shown.size)
+            shown.forEachIndexed { i, body ->
+                assertTrue("已显示的正文改口了：$body → ${bodies[i]}", bodies[i].startsWith(body))
+            }
+            shown = bodies
+        }
+        assertEquals(listOf("甲", "乙"), parser.finish().map { it.body })
+    }
+
+    /** 残缺的 `<br` 同样扣留（否则中间态先把字面 `<br` 吐上屏、收口时再变成两条气泡——字会跳）。 */
+    @Test
+    fun streamingWithholdsPartialLineBreakTag() {
+        for (partial in listOf("甲<br", "甲<BR", "甲</br", "甲<br/", "甲<br ", "甲<br class=\"x\"")) {
+            val mid = StreamingContentParser().onDelta(partial)
+            assertEquals("「$partial」残缺时必须扣住，只显示分隔符前的正文", listOf("甲"), mid.map { it.body })
+        }
+
+        // 补全之后才产出第二条气泡，且已显示过的正文没有改口
+        val parser = StreamingContentParser()
+        assertEquals(listOf("甲"), parser.onDelta("甲<br").map { it.body })
+        assertEquals(listOf("甲"), parser.onDelta(" class=x").map { it.body })
+        assertEquals(listOf("甲", "乙"), parser.onDelta(">乙").map { it.body })
+        assertEquals(listOf("甲", "乙"), parser.finish().map { it.body })
+    }
+
     // ------------------------------------------------------------------
     // 旁白依附：首部 → head，尾部 → tail，中间 → 上提 head
     // ------------------------------------------------------------------
@@ -245,6 +587,117 @@ class ChatContentParserTest {
         assertTrue(bubbles[0].parts.any { it is ContentPart.Action })
     }
 
+    // ------------------------------------------------------------------
+    // 落单标签容错：宁可剥掉标签，也绝不把标签当正文
+    //
+    // 畸形 markup 来自服务端（客户端只做容错，不代表服务端这样发是对的）。
+    // 这些断言是上面「畸形 / 未闭合」那组的另一面，两边必须同时成立。
+    // ------------------------------------------------------------------
+
+    /** 线上实测的一条畸形消息：第三段多一个 `<p>`，只有一个 `</p>`。 */
+    private val malformedRealMessage =
+        "<p><action>满意地点点头</action></p>\n" +
+            "<p>真乖♪ 这可是今天最让人家放心的一句。</p>\n" +
+            "<p><p>那现在——想让人家陪你看会儿晚霞，还是安静坐着发会儿呆？</p>"
+
+    @Test
+    fun realMalformedMessageRendersCleanBubbles() {
+        val bubbles = parse(malformedRealMessage)
+        assertEquals(
+            listOf(
+                "真乖♪ 这可是今天最让人家放心的一句。",
+                "那现在——想让人家陪你看会儿晚霞，还是安静坐着发会儿呆？",
+            ),
+            bubbles.map { it.body },
+        )
+        // 纯旁白块照既有规则依附到下一个有正文的气泡上（head）。
+        assertEquals(listOf(ContentPart.Action("满意地点点头")), bubbles[0].head)
+        assertNoLooseTagInRenderedText(bubbles)
+    }
+
+    @Test
+    fun duplicatedOpeningTagIsDropped() {
+        assertEquals(listOf("正文"), parse("<p><p>正文</p>").map { it.body })
+    }
+
+    @Test
+    fun strayClosingTagIsDropped() {
+        assertEquals(listOf("正文"), parse("<p>正文</p></p>").map { it.body })
+    }
+
+    @Test
+    fun duplicatedOpeningTagInLaterBlockKeepsBubbleSplit() {
+        assertEquals(listOf("甲", "乙"), parse("<p>甲</p><p><p>乙</p>").map { it.body })
+    }
+
+    @Test
+    fun duplicatedOpeningTagKeepsTheNoteAttachedToTheNextParagraph() {
+        val bubble = parse("<p><action>点头</action></p><p><p>乙</p>").single()
+        assertEquals("乙", bubble.body)
+        assertEquals(listOf(ContentPart.Action("点头")), bubble.head)
+    }
+
+    @Test
+    fun duplicatedOpeningTagWithAttributesIsDropped() {
+        assertEquals(listOf("正文"), parse("<p><p class=\"line\">正文</p>").map { it.body })
+    }
+
+    @Test
+    fun looseTagsSurroundedByWhitespaceAreDropped() {
+        assertEquals(listOf("正文"), parse("  <p>\n<p>正文</p>\n</p>  ").map { it.body })
+    }
+
+    @Test
+    fun leadingAndTrailingLooseTagsLeaveNoEmptyBubble() {
+        assertEquals(listOf("甲"), parse("</p><p>甲</p></p>").map { it.body })
+    }
+
+    @Test
+    fun loneParagraphTagsProduceNoBubble() {
+        assertTrue(parse("<p>").isEmpty())
+        assertTrue(parse("</p>").isEmpty())
+        assertTrue(parse("  <p>  ").isEmpty())
+        assertTrue(parse("<p></p></p>").isEmpty())
+        assertTrue(parse("<p><p>").isEmpty())
+    }
+
+    @Test
+    fun unclosedTagAfterACompleteBlockIsDroppedNotShown() {
+        // 段落结构已被前一个完整块定死，尾部这个没闭合的 `<p>` 只可能是标记。
+        assertEquals(listOf("甲", "乙"), parse("<p>甲</p><p>乙").map { it.body })
+    }
+
+    /** 剥不剥只看它**后面**还有没有内容：后面有正文的留字面，后面什么都没有的才剥。 */
+    @Test
+    fun aLooseTagIsKeptWheneverThereIsStillContentAfterIt() {
+        assertEquals(listOf("<p>甲<p>乙"), parse("<p>甲<p>乙").map { it.body })
+        assertEquals(listOf("<p>甲"), parse("<p>甲<p>").map { it.body })
+        assertEquals(listOf("<p>甲"), parse("<p>甲<p><p><p>").map { it.body })
+    }
+
+    @Test
+    fun strayRoleTagOutsideParagraphIsDropped() {
+        assertEquals(listOf("甲"), parse("<p>甲</p></action>").map { it.body })
+        assertEquals(listOf("甲"), parse("</action><p>甲</p>").map { it.body })
+    }
+
+    @Test
+    fun plainAngleBracketsAreNeverEaten() {
+        assertEquals(listOf("1 < 2 且 3 > 2"), parse("1 < 2 且 3 > 2").map { it.body })
+        assertEquals(listOf("<3 是想你的意思"), parse("<3 是想你的意思").map { it.body })
+        assertEquals(listOf("a<b>c"), parse("a<b>c").map { it.body })
+        assertEquals(listOf("<div>这是一段 HTML</div>"), parse("<div>这是一段 HTML</div>").map { it.body })
+        assertEquals(listOf("<p2>这不关 p 标签的事</p2>"), parse("<p2>这不关 p 标签的事</p2>").map { it.body })
+        assertEquals(listOf("<P>大小写不认</P>"), parse("<P>大小写不认</P>").map { it.body })
+        assertEquals(listOf("你好<p"), parse("你好<p").map { it.body })
+    }
+
+    @Test
+    fun plainAngleBracketsInsideAParagraphAreNeverEaten() {
+        assertEquals(listOf("甲 1 < 2", "乙"), parse("<p>甲 1 < 2</p><p>乙</p>").map { it.body })
+        assertEquals(listOf("甲<p2>乙"), parse("<p>甲<p2>乙</p>").map { it.body })
+    }
+
     // ------------------------------------------------------------------
     // 流式增量：最终结果必须与一次性解析一致
     // ------------------------------------------------------------------
@@ -257,6 +710,7 @@ class ChatContentParserTest {
         <p>你好＊弯起眼睛＊</p>
         <p>这是*强调*文字</p>
         <p>*旁白：其实偷偷开心了一下*</p>
+        <p><p>那现在——想让人家陪你看会儿晚霞，还是安静坐着发会儿呆？</p>
         <p>晚安。</p>
     """.trimIndent()
 
@@ -315,6 +769,63 @@ class ChatContentParserTest {
         assertEquals(listOf("第一", "第二"), second.map { it.body })
     }
 
+    /** 逐字符喂实测畸形消息：中间态任何一帧都不许把标签当正文吐上屏。 */
+    @Test
+    fun streamingRealMalformedMessageNeverLeaksTheTag() {
+        val parser = StreamingContentParser()
+        for (ch in malformedRealMessage) {
+            assertNoLooseTagInRenderedText(parser.onDelta(ch.toString()))
+        }
+        assertEquals(parse(malformedRealMessage), parser.finish())
+    }
+
+    /** 中间态只许「加」，不许改口：已经显示过的正文不能因为后续 delta 变样（那才是跳动）。 */
+    @Test
+    fun streamingRealMalformedMessageOnlyGrowsWhatItAlreadyShowed() {
+        val parser = StreamingContentParser()
+        var shown = emptyList<String>()
+        for (ch in malformedRealMessage) {
+            val bodies = parser.onDelta(ch.toString()).map { it.body }
+            assertTrue("气泡数回退了：$shown → $bodies", bodies.size >= shown.size)
+            shown.forEachIndexed { i, body ->
+                assertTrue("已显示的正文改口了：$body → ${bodies[i]}", bodies[i].startsWith(body))
+            }
+            shown = bodies
+        }
+    }
+
+    @Test
+    fun streamingRandomChunksOfMalformedMessageMatchOneShot() {
+        val expected = parse(malformedRealMessage)
+        val random = Random(20261006)
+        repeat(25) {
+            val parser = StreamingContentParser()
+            var index = 0
+            while (index < malformedRealMessage.length) {
+                val size = 1 + random.nextInt(7)
+                val end = minOf(index + size, malformedRealMessage.length)
+                parser.onDelta(malformedRealMessage.substring(index, end))
+                index = end
+            }
+            assertEquals(expected, parser.finish())
+        }
+    }
+
+    /**
+     * 重复开标签必须连同它后面的正文一起被扣留到收口。
+     *
+     * 放宽扣留（把重复的 `<p>` 当「外层冗余」、让前缀继续推进）会把 `甲` 先吐上屏，
+     * 等 `</p>` 到了再变成 `甲乙`——用户看到的字会跳，所以这里钉住「中间态一帧都不吐」。
+     */
+    @Test
+    fun streamingWithholdsDuplicateOpeningTagUntilItsPartnerArrives() {
+        val parser = StreamingContentParser()
+        for (chunk in listOf("<p>甲", "<p>乙", "</p>")) {
+            assertNoLooseTagInRenderedText(parser.onDelta(chunk))
+        }
+        assertEquals(listOf("甲乙"), parser.finish().map { it.body })
+    }
+
     @Test
     fun streamingUnclosedActionFallsBackOnFinish() {
         val parser = StreamingContentParser()
@@ -347,4 +858,124 @@ class ChatContentParserTest {
         assertTrue(parser.onDelta("").isEmpty())
         assertEquals(listOf("新"), parser.onDelta("<p>新</p>").map { it.body })
     }
+
+    // ------------------------------------------------------------------
+    // 复杂度回归：一大段落单标签不许把 parse 拖成 O(N²)
+    //
+    // ⚠️ 这条测的是**复杂度**，不是精确耗时：阈值宽到 20000 个落单标签给 2 秒，只用来区分
+    // 「线性」与「平方」。修复前实测：2000 个 854ms、8000 个 4254ms、20000 个 26405ms（每翻
+    // 一倍涨约 4 倍，典型平方）；修复后 20000 个是十几毫秒。所以阈值别卡紧（CI 机器可能更慢），
+    // 这里量到的数也别当性能指标读——要盯的是「有没有退回 O(N²)」。
+    //
+    // 这个形状同时压住两处（修复前各占一部分，都在 `ChatContentParser` 里）：
+    //   - 落单标签的「后面还有没有正文」判据（`ContentAfterQuery`，修复前约 23 秒）；
+    //   - 完整块搜索 `P_BLOCK_RE.findAll`（没有 `</p>` 时每个 `<p` 候选点都回溯到串尾，约 8.2 秒）。
+    // ------------------------------------------------------------------
+
+    /** 复杂度回归的宽松上限（毫秒）：只区分线性与平方，不是耗时指标。 */
+    private val looseTagBudgetMs = 2_000L
+
+    @Test
+    fun hugeRunOfLooseTagsIsDroppedWithinALinearBudget() {
+        val count = 20_000
+        val inputs = listOf(
+            "<p>".repeat(count), // 一串纯落单开标签
+            " \n<p> ".repeat(count), // 标签之间夹空白：跳过空白后仍是「后面什么都没有」
+        )
+        for (input in inputs) {
+            val startedAt = System.nanoTime()
+            val bubbles = parse(input)
+            val elapsedMs = (System.nanoTime() - startedAt) / 1_000_000
+            assertTrue("落单标签应当被剥净，实际留下：${bubbles.map { it.body }}", bubbles.isEmpty())
+            assertTrue(
+                "${input.length} 字符（$count 个落单标签）用了 ${elapsedMs}ms，" +
+                    "超出线性预算 ${looseTagBudgetMs}ms——复杂度退回 O(N²) 了？",
+                elapsedMs < looseTagBudgetMs,
+            )
+        }
+    }
+
+    /**
+     * `<br>` 那趟扫描（[BR_TAG_RE] 的 `findAll`）同样不许把 `parse` 拖成平方：一串只有尖括号、
+     * 或一串「像分隔符但缺一个字符」的文本，每个 `<` 都只允许常数级尝试。
+     */
+    @Test
+    fun hugeRunOfLineBreakLookalikesStaysWithinALinearBudget() {
+        val count = 20_000
+        for (input in listOf("<br".repeat(count), "<".repeat(count), "<br)x".repeat(count / 3))) {
+            val startedAt = System.nanoTime()
+            val bubbles = parse(input)
+            val elapsedMs = (System.nanoTime() - startedAt) / 1_000_000
+            assertTrue("「${input.take(6)}…」不该分出气泡：${bubbles.size}", bubbles.size == 1)
+            assertTrue(
+                "${input.length} 字符（一串像 `<br>` 的文本）用了 ${elapsedMs}ms，" +
+                    "超出线性预算 ${looseTagBudgetMs}ms——复杂度退回 O(N²) 了？",
+                elapsedMs < looseTagBudgetMs,
+            )
+        }
+    }
+
+    /**
+     * W71 新增的那趟**保护区扫描**（[protectedSpans]）同样不许把 `parse` 拖成平方：一串只有作用域
+     * 开标签、或一串「像作用域」的尖括号，每个 `<` 都只允许常数级尝试；成对作用域那一趟靠
+     * 「区间按起点升序 + 游标不回头」，整体仍是线性的。判据与上一条同源（同样只是「线性 or 平方」）。
+     *
+     * ⚠️ 刻意**不**喂 `"<action>".repeat(n)`：那个形状会先踩到 `ROLE_RE` 自己的回溯（一串没有闭合的
+     * 角色开标签，正则引擎每处都要 `([\s\S]*?)` 一路试到串尾），那是**既有**的平方点、与本次改动无关，
+     * 拿它来当预算用例只会把一个既存问题记到新代码头上。这里用的是 `<code>`（不是 `ROLE_RE` 的词）。
+     */
+    @Test
+    fun hugeRunOfScopeLikeTagsStaysWithinALinearBudget() {
+        val count = 20_000
+        val budget = { input: String, label: String, elapsedMs: Long ->
+            assertTrue(
+                "${input.length} 字符（$label）用了 ${elapsedMs}ms，" +
+                    "超出线性预算 ${looseTagBudgetMs}ms——复杂度退回 O(N²) 了？",
+                elapsedMs < looseTagBudgetMs,
+            )
+        }
+
+        // 一串只有开标签：未闭合 ⇒ 不产生区间
+        val unclosed = "<code>".repeat(count)
+        val unclosedAt = System.nanoTime()
+        val unclosedBubbles = parse(unclosed)
+        budget(unclosed, "一串未闭合的 `<code>`", (System.nanoTime() - unclosedAt) / 1_000_000)
+        assertEquals(1, unclosedBubbles.size)
+        assertEquals(unclosed, unclosedBubbles.single().body)
+
+        // 一串「开标签 + `<br>`」：每个 `<br>` 都不在保护区里 ⇒ 每个都分隔
+        val split = "<code>甲<br>".repeat(count)
+        val splitAt = System.nanoTime()
+        val splitBubbles = parse(split)
+        budget(split, "$count 个未闭合的 `<code>` + `<br>`", (System.nanoTime() - splitAt) / 1_000_000)
+        assertEquals(count, splitBubbles.size)
+
+        // 一串**成对**的作用域（每个里面一个 `<br>`）：全部被保护 ⇒ 一条气泡、逐字内容
+        val paired = "<code>甲<br>乙</code>".repeat(count / 4)
+        val pairedAt = System.nanoTime()
+        val pairedBubbles = parse(paired)
+        budget(paired, "$count 个成对作用域", (System.nanoTime() - pairedAt) / 1_000_000)
+        assertEquals("每个 `<br>` 都在保护区里 ⇒ 一条气泡", 1, pairedBubbles.size)
+        assertEquals("甲<br>乙".repeat(count / 4), pairedBubbles.single().body)
+
+        // 角色注记那一支：一串成对的注记，各自保护自己的 `<br>`（一条气泡、注记全认下）
+        val noted = "<action>她<br>点点头</action>".repeat(2_000)
+        val notedAt = System.nanoTime()
+        val notedBubbles = parse(noted)
+        budget(noted, "2000 条成对注记", (System.nanoTime() - notedAt) / 1_000_000)
+        assertEquals(1, notedBubbles.size)
+        assertEquals(2_000, notedBubbles.single().head.size)
+        assertEquals("", notedBubbles.single().body)
+    }
+
+    /** 产出的任何片段里都不许出现段落标签本身——这是落单标签容错的底线。 */
+    private fun assertNoLooseTagInRenderedText(bubbles: List<ParsedBubble>) {
+        for (bubble in bubbles) {
+            for (part in bubble.parts) {
+                assertFalse("标签漏进了正文：${part.text}", part.text.contains("<p") || part.text.contains("</p"))
+            }
+        }
+    }
+
+    private fun run(text: String, vararg styles: InlineStyle) = InlineRun(text, styles.toSet())
 }

app/src/test/kotlin/top/yeij/cyrene/domain/parse/InlineMarkupTest.kt

@@ -0,0 +1,759 @@
+package top.yeij.cyrene.domain.parse
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.domain.chat.editableMessageOf
+import top.yeij.cyrene.ui.chat.plainSearchText
+import top.yeij.cyrene.ui.chat.sharePreviewBlocks
+import kotlin.random.Random
+
+/**
+ * 行内标签（`InlineMarkup.kt`）单测：六项白名单各自渲染成什么、边界口径、以及
+ * 「星号语义一个字都没被动过」的反证。
+ *
+ * 断言的是**纯函数的结果**（片段文本 + 样式），不碰 Compose：`runs` 拼起来就是渲染文本，
+ * 所以「哪段字是什么样式」在这里是直接可断言的。
+ *
+ * ## 口径沿革（三轮，都按后端契约改的）
+ * **W68 按 v0.89**：标签名**大小写不敏感**（`<B>` = `<b>`）；**属性一律不解析**
+ * （`<b class="x">` 就是粗体，属性整段丢掉）；**结构不平衡 ⇒ 该气泡正文整段降级为原文**
+ * （取代 W67 的「只坏那一对」）。⚠️ 大小写那条**消费侧与流式扣留侧必须一起改**：
+ * `<B` 这种残缺形态若只在消费侧认，中间态就会把它当正文吐上屏、等 `</B>` 到了再吃掉，
+ * 屏幕上显示过的字会改口（由 `streamingWithholdsMixedCaseAndAttributeTagsToo` 钉着）。
+ *
+ * **W69 按 `回执三十` / `回执三十一`**：
+ * 1. **白名单收窄到五项**（`b` / `strong` / `i` / `em` / `code`）⇒ **`u` / `s` 撤掉**：
+ *    它们在她 100 条输出里 0 命中，多支持反而是制造跨端不一致（Web 不渲染、我们渲染）。
+ * 2. **`<br>` 不是行内标签**，而是与 `<p>` 同级的气泡/消息分隔符 ⇒ 从这一层**整体移出**，
+ *    切分改在 `ChatContentParser.appendRegion`，用例搬去 `ChatContentParserTest`。
+ *    这一层里 `<br>` 只剩「普通字符」这一种身份（见 [lineBreakTagIsNotAnInlineTagHere]）。
+ *
+ * **W71 按 v0.89 最终版（`回执三十三`，收口）**：
+ * 1. **`u` 加回**：`回执三十三 §一` 明说「收窄到五项」是**后端的疏漏** —— 主人裁定下划线保留，
+ *    后端把 `u` 加回契约（`1107b2a`）与 IM 出站（`74c9f2d`），只是**忘了发回执登记**。
+ *    最终白名单 = **六项**，`u` 在这一层渲染成下划线（[underlineBecomesAnUnderlineRun]）；
+ *    **`s` 仍不在内**、逐字原样（[sEveryCaseAndShapeIsStillShownLiterally]）。
+ * 2. **`<br>` 的「始终分隔」收紧成「只有普通文本层才分隔」**（`回执三十三 §三②`）：`<code>` 与
+ *    角色注记**内部**的不分隔。那两处的切分在 `ChatContentParser`（保护区），这一层只是因此**真的**
+ *    会收到 `<br>` —— `<code>` 里的那个会走到这里，按「内容」字面显示
+ *    （[lineBreakInsideCodeStaysLiteralContent]）。
+ *
+ * 凡是不与这三轮契约冲突的老断言（绝不丢字、`parts` 逐字原文、星号语义、流式一致性、复杂度）
+ * 一条都没放松。
+ */
+class InlineMarkupTest {
+
+    // ------------------------------------------------------------------
+    // 六项白名单各自渲染成什么
+    // ------------------------------------------------------------------
+
+    @Test
+    fun boldTagBecomesABoldRun() {
+        assertEquals(listOf(run("18:35", InlineStyle.Bold)), parseInlineMarkup("<b>18:35</b>"))
+    }
+
+    @Test
+    fun strongIsJustAnotherWayToWriteBold() {
+        assertEquals(listOf(run("18:35", InlineStyle.Bold)), parseInlineMarkup("<strong>18:35</strong>"))
+    }
+
+    @Test
+    fun iAndEmBothBecomeItalicRuns() {
+        assertEquals(listOf(run("斜", InlineStyle.Italic)), parseInlineMarkup("<i>斜</i>"))
+        assertEquals(listOf(run("斜", InlineStyle.Italic)), parseInlineMarkup("<em>斜</em>"))
+    }
+
+    @Test
+    fun codeTagBecomesACodeRun() {
+        assertEquals(listOf(run("abc", InlineStyle.Code)), parseInlineMarkup("<code>abc</code>"))
+    }
+
+    /**
+     * W71 按 `回执三十三 §一` 新增（`u` 加回白名单，六项）：`<u>x</u>` 渲染成**下划线**
+     * （`InlineStyle.Underline` → `MessageBubble.inlineBody` 里的 `TextDecoration.Underline`）。
+     *
+     * 加回的原因写在类 KDoc：`回执三十` 那次「收窄到五项」是后端的疏漏，主人裁定下划线保留。
+     */
+    @Test
+    fun underlineBecomesAnUnderlineRun() {
+        assertEquals(listOf(run("重点", InlineStyle.Underline)), parseInlineMarkup("<u>重点</u>"))
+        // 大小写不敏感、属性同样整段丢掉（与其余五项同一套判据）
+        assertEquals(listOf(run("重点", InlineStyle.Underline)), parseInlineMarkup("<U>重点</U>"))
+        assertEquals(listOf(run("重点", InlineStyle.Underline)), parseInlineMarkup("<u class=x>重点</u>"))
+        // 与别的样式叠加、与别的标签混排
+        assertEquals(
+            listOf(run("加粗又下划线", InlineStyle.Bold, InlineStyle.Underline)),
+            parseInlineMarkup("<b><u>加粗又下划线</u></b>"),
+        )
+        val bubble = parse("<p><b>粗</b>与<u>下划线</u></p>").single()
+        assertEquals("粗与下划线", bubble.body)
+        assertEquals(
+            listOf(run("粗", InlineStyle.Bold), run("与"), run("下划线", InlineStyle.Underline)),
+            bubble.runs,
+        )
+        // 未配成对时仍是「整段降级」那一档，不因为多了一项而放松
+        assertTrue(parseInlineMarkup("<u>没有闭合").isEmpty())
+    }
+
+    @Test
+    fun mixedTagsSplitTheTextIntoStyledRuns() {
+        assertEquals(
+            listOf(run("记住 "), run("abc", InlineStyle.Code), run(" 与 "), run("斜体", InlineStyle.Italic), run(" 哦")),
+            parseInlineMarkup("记住 <code>abc</code> 与 <i>斜体</i> 哦"),
+        )
+    }
+
+    /** 线上实测的那一条：只有 `<b>` 一种标签，命中的正是她给的那个时间点。 */
+    @Test
+    fun theRealMessageRendersAsThreeRuns() {
+        val runs = parseInlineMarkup("日落 <b>18:35</b>，比上海晚了整整一小时呢。")
+        assertEquals(
+            listOf(
+                run("日落 "),
+                run("18:35", InlineStyle.Bold),
+                run("，比上海晚了整整一小时呢。"),
+            ),
+            runs,
+        )
+        assertEquals("日落 18:35，比上海晚了整整一小时呢。", runs.concat())
+    }
+
+    /** 没有标签时返回空列表 = 调用方走原来的字面路径（这是绝大多数消息的那一档）。 */
+    @Test
+    fun plainTextYieldsNoRunsAtAll() {
+        assertTrue(parseInlineMarkup("今天那儿是晴，13~25℃").isEmpty())
+        assertTrue(parseInlineMarkup("").isEmpty())
+        assertTrue(parseInlineMarkup("多行\n文本\n也是普通的").isEmpty())
+    }
+
+    // ------------------------------------------------------------------
+    // 契约 v0.89 之一：标签名大小写不敏感
+    // ------------------------------------------------------------------
+
+    /**
+     * W68 按契约 v0.89 新增（原口径「只认小写」与它冲突，见类 KDoc）：**六项**标签的大小写任意写法
+     * 都认，且改不成别的样式——`<B>` 就是 `<b>`（`u` 由 W71 按 `回执三十三 §一` 加回）。
+     */
+    @Test
+    fun tagNamesAreCaseInsensitive() {
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<B>粗</B>"))
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<Strong>粗</Strong>"))
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<STRONG>粗</STRONG>"))
+        assertEquals(listOf(run("斜", InlineStyle.Italic)), parseInlineMarkup("<I>斜</I>"))
+        assertEquals(listOf(run("斜", InlineStyle.Italic)), parseInlineMarkup("<Em>斜</Em>"))
+        assertEquals(listOf(run("码", InlineStyle.Code)), parseInlineMarkup("<CODE>码</CODE>"))
+        assertEquals(listOf(run("线", InlineStyle.Underline)), parseInlineMarkup("<U>线</U>"))
+
+        // 大小写混着嵌套也照常叠加
+        assertEquals(
+            listOf(run("粗斜", InlineStyle.Bold, InlineStyle.Italic)),
+            parseInlineMarkup("<B><i>粗斜</i></B>"),
+        )
+    }
+
+    /**
+     * 大写**只对行内标签**成立：段落/旁白标签仍只认小写（既有契约 `<P>大小写不认</P>`、
+     * `MessageEditText` 同一口径；契约也写明「`<action>`/`<narration>` 的既有行为逐字未改」）。
+     */
+    @Test
+    fun uppercaseStillMeansNothingForParagraphAndRoleTags() {
+        assertEquals(listOf("<P>大小写不认</P>"), parse("<P>大小写不认</P>").map { it.body })
+        assertEquals(listOf("甲<ACTION>笑</ACTION>"), parse("<p>甲<ACTION>笑</ACTION></p>").map { it.body })
+    }
+
+    // ------------------------------------------------------------------
+    // 契约 v0.89 之二：属性一律不解析
+    // ------------------------------------------------------------------
+
+    /**
+     * W68 按契约 v0.89 改（原口径「`<b class="x">` 原样保留」与它冲突，见类 KDoc）：
+     * 白名单标签带任何属性都按标签名处理，属性**整段丢掉**，绝不落进正文、更不落成任何视图属性。
+     */
+    @Test
+    fun attributesAreDroppedEntirely() {
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<b class=\"x\">粗</b>"))
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<b onclick=\"y\">粗</b>"))
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<b class=x onclick=y style=z>粗</b>"))
+        assertEquals(listOf(run("粗", InlineStyle.Bold)), parseInlineMarkup("<b data-甲=一>粗</b>"))
+        assertEquals(listOf(run("码", InlineStyle.Code)), parseInlineMarkup("<code class=lang>码</code>"))
+
+        // 属性里那串字一个都不许留在渲染文本里（`class` / `x` / `onclick` / `y` 全都不见）
+        val runs = parseInlineMarkup("日落 <b class=\"x\" onclick=\"y\">18:35</b>，比上海晚了整整一小时呢。")
+        assertEquals(
+            listOf(run("日落 "), run("18:35", InlineStyle.Bold), run("，比上海晚了整整一小时呢。")),
+            runs,
+        )
+        assertFalse(runs.concat().contains("class"))
+        assertFalse(runs.concat().contains("onclick"))
+
+        // 带属性的标签同样要配成对：`<b class=x>` 没闭合 ⇒ 整段降级（不是「属性被丢、粗体照旧」）
+        assertEquals("<b class=\"x\">甲", parse("<p><b class=\"x\">甲</p>").single().body)
+    }
+
+    // ------------------------------------------------------------------
+    // 边界 2：嵌套；边界 5：code 里的内容不再解析
+    // ------------------------------------------------------------------
+
+    @Test
+    fun nestedBoldItalicMergesTheTwoStyles() {
+        assertEquals(
+            listOf(run("粗", InlineStyle.Bold), run("粗斜", InlineStyle.Bold, InlineStyle.Italic)),
+            parseInlineMarkup("<b>粗<i>粗斜</i></b>"),
+        )
+    }
+
+    @Test
+    fun boldOutsideItalicKeepsBothStyles() {
+        assertEquals(
+            listOf(run("甲", InlineStyle.Bold), run("乙", InlineStyle.Bold, InlineStyle.Code), run("丙", InlineStyle.Bold)),
+            parseInlineMarkup("<b>甲<code>乙</code>丙</b>"),
+        )
+    }
+
+    /**
+     * `<code>` 里想显示什么就显示什么——包括尖括号（这也是「想显示尖括号怎么办」的答案）。
+     *
+     * 它与契约「白名单外按纯文本原样显示」**不冲突、方向一致**，但不是同一条规则：第 1 条管的是
+     * 白名单外的**标签名**，`<code>` 管的是一条**作用域**（里面连白名单标签也按内容处理）。
+     * 两者的结果都落在同一条硬口径上：字符一个不丢。理由写在 `parseInlineMarkup` 的 KDoc 里。
+     */
+    @Test
+    fun codeContentIsNotParsed() {
+        assertEquals(listOf(run("<b>甲</b>", InlineStyle.Code)), parseInlineMarkup("<code><b>甲</b></code>"))
+        assertEquals(listOf(run("1 < 2 && a<b", InlineStyle.Code)), parseInlineMarkup("<code>1 < 2 && a<b</code>"))
+        // 里面的东西也**不算结构**：这个「未闭合的 `<b>`」只是四个字符，不把整段拖成字面
+        assertEquals(listOf(run("<b>甲", InlineStyle.Code), run(" 尾")), parseInlineMarkup("<code><b>甲</code> 尾"))
+    }
+
+    /**
+     * W69（`回执三十一`）：`<br>` **不再是行内标签**，所以这一层对它只剩「普通字符」这一种身份——
+     * 它不换行、也不影响旁边的成对标签（`<b>甲<br>乙</b>` 在这里是一对正常的粗体，文本里带着
+     * 字面的 `<br>`）。
+     *
+     * 真实链路上这一层**只有一条路**会看到 `<br>`：`<code>` 作用域内部的那些（`回执三十三 §三②`
+     * 起，分隔符切分层有保护区，`<code>` / `<action>` / `<narration>` 里的 `<br>` 不分隔）。
+     * 其余形状只可能出现在「函数被单独调用」的场景里。气泡切分那一侧的用例在
+     * `ChatContentParserTest`（含三种写法等价、空气泡丢弃、保护区、跨分隔符的标签各自回落原文）。
+     */
+    @Test
+    fun lineBreakTagIsNotAnInlineTagHere() {
+        assertEquals(listOf(run("甲<br>乙", InlineStyle.Bold)), parseInlineMarkup("<b>甲<br>乙</b>"))
+        assertTrue(parseInlineMarkup("甲<br>乙").isEmpty())
+        assertTrue(parseInlineMarkup("甲<br/>乙").isEmpty())
+        assertTrue(parseInlineMarkup("甲</br>乙").isEmpty())
+        assertTrue(parseInlineMarkup("甲<br2>乙</br2>").isEmpty())
+    }
+
+    /**
+     * W71（`回执三十三 §三②`）：`<code>` 作用域**内部**的 `<br>` 走到这一层时，就是代码里的几个
+     * 普通字符——**逐字原样**（不换行、也不消掉），与 `<code><b>甲</b></code>` 里的 `<b>` 同一规矩。
+     *
+     * 口径的理由写在 `ChatContentParser.appendRegion` 的 KDoc 里（注记那一侧要显示 `parts` 的逐字
+     * 原文 = 红线，所以同一个形状不能在 `<code>` 里是一种意思、在 `<action>` 里又是另一种；
+     * 「换成 `\n`」还得在这一层破例给 `<br>` 单开一条规则——W68 刚从这一层把它整体删掉）。
+     */
+    @Test
+    fun lineBreakInsideCodeStaysLiteralContent() {
+        assertEquals(listOf(run("甲<br>乙", InlineStyle.Code)), parseInlineMarkup("<code>甲<br>乙</code>"))
+        // `<code>` 里再套 `<b>`、`<code>` 套在 `<b>` 里：内容一律字面，`<br>` 也是内容的一部分
+        assertEquals(
+            listOf(run("甲<b>乙<br>丙</b>", InlineStyle.Code)),
+            parseInlineMarkup("<code>甲<b>乙<br>丙</b></code>"),
+        )
+        assertEquals(
+            listOf(run("甲", InlineStyle.Bold), run("乙<br>丙", InlineStyle.Bold, InlineStyle.Code), run("丁", InlineStyle.Bold)),
+            parseInlineMarkup("<b>甲<code>乙<br>丙</code>丁</b>"),
+        )
+    }
+
+    /** 而它作为**气泡分隔符**的作用由气泡切分层负责：`<br>` 现在真的分成两条气泡。 */
+    @Test
+    fun lineBreakTagSplitsBubblesAtTheParserLevel() {
+        assertEquals(listOf("甲", "乙"), parse("<p>甲<br>乙</p>").map { it.body })
+        assertEquals(listOf("甲", "乙"), parse("甲<br>乙").map { it.body })
+    }
+
+    // ------------------------------------------------------------------
+    // 契约 v0.89 之三：结构不平衡 ⇒ 整段降级为原文
+    // （粒度是「该气泡的正文」；W67 的局部降级口径与它冲突，W68 已按契约改掉）
+    // ------------------------------------------------------------------
+
+    /**
+     * W68 按契约 v0.89 改：**未闭合**的开标签 ⇒ 整段原文。
+     * 返回空列表 = 调用方按字面渲染，正文一个字符都不动。
+     */
+    @Test
+    fun unpairedTagsStayLiteral() {
+        // 没有闭合 ⇒ 整段字面（列表为空 = 按字面渲染，正文一个字符都不动）
+        assertTrue(parseInlineMarkup("<b>没有闭合").isEmpty())
+        assertTrue(parseInlineMarkup("没有闭合</b>").isEmpty())
+        assertTrue(parseInlineMarkup("日落 <b>18:35").isEmpty())
+        assertTrue(parseInlineMarkup("<i>斜").isEmpty())
+        assertTrue(parseInlineMarkup("<code>看星星").isEmpty())
+        // 大小写混用、带属性也一样算未闭合
+        assertTrue(parseInlineMarkup("日落 <B>18:35").isEmpty())
+        assertTrue(parseInlineMarkup("日落 <b class=x>18:35").isEmpty())
+    }
+
+    /**
+     * W68 按契约 v0.89 改：原断言是「配成对的另一半照常生效，只有落单那半个留着字面」
+     * （`<b>甲<i>乙</i>` ⇒ `<b>甲` 字面 + `乙` 斜体）。契约把它换成了**整段降级**：
+     * 一处不平衡，这一整段一个标签都不认——粗粒度换来「可逐字断言」，理由见类 KDoc。
+     */
+    @Test
+    fun oneUnclosedTagFallsTheWholeBodyBackToLiteralText() {
+        assertTrue(parseInlineMarkup("<b>甲<i>乙</i>").isEmpty())
+        assertEquals("<b>甲<i>乙</i>", parse("<p><b>甲<i>乙</i></p>").single().body)
+        assertEquals(emptyList<InlineRun>(), parse("<p><b>甲<i>乙</i></p>").single().runs)
+    }
+
+    /**
+     * W68 按契约 v0.89 改：原断言是「`</b>` 关不掉 `i`，于是它连同 `<b>` 一起按字面留着，
+     * 只有配成对的 `<i>…</i>` 生效」。契约把它换成整段降级：**交错**是最容易各端各说各话的形状，
+     * 一律按原文显示。
+     */
+    @Test
+    fun interleavedTagsFallTheWholeBodyBackToLiteralText() {
+        assertTrue(parseInlineMarkup("<b>甲<i>乙</b>丙</i>").isEmpty())
+        assertEquals("<b>甲<i>乙</b>丙</i>", parse("<p><b>甲<i>乙</b>丙</i></p>").single().body)
+    }
+
+    /** W68 按契约 v0.89 改：原断言是「落在后面的那个 `</b>` 什么都不关，前面的粗体照旧」。 */
+    @Test
+    fun aStrayCloseTagFallsTheWholeBodyBackToLiteralText() {
+        // 落单的闭标签（栈空）与「只有闭标签」都是不平衡 ⇒ 整段原文
+        assertTrue(parseInlineMarkup("<b>甲</b>乙</b>").isEmpty())
+        assertTrue(parseInlineMarkup("</b>").isEmpty())
+        assertTrue(parseInlineMarkup("甲</i>乙</b>").isEmpty())
+        assertEquals("<b>甲</b>乙</b>", parse("<p><b>甲</b>乙</b></p>").single().body)
+    }
+
+    /**
+     * W68 按契约 v0.89 新增：**四种不平衡形状**各自的整段降级，且降级的是「整段原文」，
+     * 逐字对照。
+     */
+    @Test
+    fun everyImbalancedShapeFallsBackToTheOriginalTextCharacterForCharacter() {
+        for (raw in listOf(
+            "日落 <b>18:35", // 未闭合
+            "甲<b>粗</b>乙<b>没闭合", // 一半配好、后一半未闭合
+            "甲<b>粗</b>乙</b>", // 落单闭标签
+            "</b>", // 只有闭标签
+            "<b>甲<i>乙</b>丙</i>", // 交错
+            "<B>甲", // 大写 + 未闭合
+            "<b class=x>甲", // 属性 + 未闭合
+        )) {
+            assertTrue("「$raw」结构不平衡，必须整段降级", parseInlineMarkup(raw).isEmpty())
+            assertEquals("「$raw」必须逐字原文", raw, parse("<p>$raw</p>").single().body)
+            assertTrue(parse("<p>$raw</p>").single().runs.isEmpty())
+        }
+    }
+
+    /**
+     * 契约说的「整段」= **该气泡的正文**（粒度口径与理由写在 `parseInlineMarkup` 的 KDoc 里）。
+     * 这条钉住它的边界：**坏掉的那条气泡整段原文，别条气泡照常渲染**——既不是整条消息，
+     * 也不是（更细的）按行/按句局部生效。
+     */
+    @Test
+    fun theFallbackCoversOnlyTheBubbleThatIsBroken() {
+        val bubbles = parse("<p>日落 <b>18:35</b></p><p>甲<b>没闭合</p>")
+        assertEquals(listOf("日落 18:35", "甲<b>没闭合"), bubbles.map { it.body })
+        assertEquals(listOf(run("日落 "), run("18:35", InlineStyle.Bold)), bubbles[0].runs)
+        assertTrue(bubbles[1].runs.isEmpty())
+
+        // 落单闭标签同理：只影响它自己那条气泡
+        val strayClose = parse("<p>日落 <b>18:35</b></p><p>乙</b></p>")
+        assertEquals(listOf("日落 18:35", "乙</b>"), strayClose.map { it.body })
+        assertTrue(strayClose[1].runs.isEmpty())
+    }
+
+    // ------------------------------------------------------------------
+    // 契约之一：白名单外一律按纯文本原样显示（字符一个不丢）
+    // W71 起 `s` 在这一档里（六项白名单不含它；`u` 曾经短暂撤出、已加回）
+    // ------------------------------------------------------------------
+
+    @Test
+    fun plainAngleBracketsAreNeverEatenAndNeverRendered() {
+        for (text in listOf(
+            "1 < 2 且 3 > 2",
+            "a<b",
+            "a<b>c", // 没有 `</b>` ⇒ 未闭合 ⇒ 整段字面
+            "你好<b", // 残缺，没有 `>`
+            "<p2>这不关 p 标签的事</p2>",
+            "<span>不认识的标签</span>",
+            "<br2>名字后面不是空白</br2>",
+            "<b2>名字后面不是空白</b2>",
+            "<boolean>以 b 开头的普通单词</boolean>",
+        )) {
+            val runs = parseInlineMarkup(text)
+            assertTrue("「$text」不该被判成行内标签", runs.isEmpty())
+            assertEquals("「$text」必须逐字保留", text, parse("<p>$text</p>").single().body)
+        }
+    }
+
+    /**
+     * 契约第 1 条点名的形状：`<script>` 之类**白名单外**的标签显示成字面量，字符一个不丢——
+     * 渲染侧是 `AnnotatedString` + `SpanStyle`（结构化），正文从来不经过任何 HTML 解析/注入。
+     *
+     * **`s` 落在这一档**：白名单 v0.89 最终版是六项（`b`/`strong`/`i`/`em`/`code`/`u`），**`s` 不在内**
+     * ——`回执三十` 撤它、`回执三十三 §一` 加回 `u` 时明确「`s` 仍不在内」，所以它逐字原样。
+     * （`u` 在这一档里只待了 W69 一轮，见 [underlineBecomesAnUnderlineRun] 与类 KDoc。）
+     *
+     * ⚠️ 我们的读法（**待与后端确认**）：白名单外的标签**不参与结构判定**——它们按纯文本算，
+     * 所以既不会因为「没闭合」把整段拖成字面（下面第二条），配对与否也不改变别的标签；
+     * 只有白名单那**六个**名字才构成契约说的「结构」。
+     */
+    @Test
+    fun tagsOutsideTheWhitelistAreShownLiterallyWithoutLosingACharacter() {
+        val raw = "<script>alert(1)</script>"
+        assertTrue(parseInlineMarkup(raw).isEmpty())
+        assertEquals(raw, parse("<p>$raw</p>").single().body)
+
+        // 白名单外的标签不参与结构判定：旁边那对 `<b>` 照常生效，尖括号原样留着
+        val mixed = parse("<p>甲<b>粗</b><script>x</script>乙</p>").single()
+        assertEquals("甲粗<script>x</script>乙", mixed.body)
+        assertEquals(
+            listOf(run("甲"), run("粗", InlineStyle.Bold), run("<script>x</script>乙")),
+            mixed.runs,
+        )
+
+        // 落单的白名单外标签同理：它只是几个字符，不把整段拖成字面
+        assertEquals(
+            listOf(run("甲"), run("粗", InlineStyle.Bold), run("<script>乙")),
+            parseInlineMarkup("甲<b>粗</b><script>乙"),
+        )
+    }
+
+    /**
+     * W71 按 `回执三十三 §一` 改写：**`s` 仍然不在白名单里**（「`s` 保持逐字原样不变」是原话），
+     * 所以 `<s>` 的**每一种形态**都不产生样式、只按原文显示——这条与 [underlineBecomesAnUnderlineRun]
+     * 是一对：`u` 加回来了，`s` 没有。
+     *
+     * 枚举里也**不该**有 `Strikethrough`：本项目不留「白名单外却有渲染分支」的死代码
+     * （W69 撤 `u`/`s` 时连枚举、渲染分支、import 一起删净，这次只把 `Underline` 加回来）。
+     */
+    @Test
+    fun sEveryCaseAndShapeIsStillShownLiterally() {
+        for (raw in listOf(
+            "<s>改口</s>",
+            "<S>改口</S>",
+            "<s class=x>改口</s>",
+            "<s>没闭合",
+            "只有闭标签</s>",
+        )) {
+            assertTrue("「$raw」不在白名单里，不该产出任何样式", parseInlineMarkup(raw).isEmpty())
+            assertEquals("「$raw」必须逐字原文", raw, parse("<p>$raw</p>").single().body)
+        }
+        // 与真样式混在一起时同理：白名单那六项起作用，`s` 的字面留在文本里
+        val bubble = parse("<p><b>粗</b>与<s>删除线</s></p>").single()
+        assertEquals("粗与<s>删除线</s>", bubble.body)
+        assertEquals(
+            listOf(run("粗", InlineStyle.Bold), run("与<s>删除线</s>")),
+            bubble.runs,
+        )
+        // `u` 回来了、`s` 没有：枚举里只有前者，绝不留一条走不到的渲染分支
+        assertTrue(InlineStyle.entries.contains(InlineStyle.Underline))
+        assertTrue(InlineStyle.entries.map { it.name }.none { it == "Strikethrough" })
+    }
+
+    // ------------------------------------------------------------------
+    // 边界 6：HTML 实体（不做）
+    // ------------------------------------------------------------------
+
+    @Test
+    fun htmlEntitiesStayLiteralBecauseTheyAreNotDecoded() {
+        for (text in listOf("a &amp; b", "1 &lt; 2", "空&nbsp;格", "&#39;引号&#39;")) {
+            assertTrue(parseInlineMarkup(text).isEmpty())
+            assertEquals(text, parse("<p>$text</p>").single().body)
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 契约第 3 条：绝不把一段非空正文渲染成空
+    // ------------------------------------------------------------------
+
+    @Test
+    fun aBodyMadeOfTagsOnlyFallsBackToItsLiteralText() {
+        for (raw in listOf("<b></b>", "<b> </b>", "<i></i><b></b>", "<code></code>")) {
+            assertTrue("「$raw」没有可渲染的字，必须整段回落字面", parseInlineMarkup(raw).isEmpty())
+            assertEquals(raw, parse("<p>$raw</p>").single().body)
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 与既有的解析结果怎么接：body / runs / parts 各拿自己那一份
+    // ------------------------------------------------------------------
+
+    @Test
+    fun bodyIsTheRenderedTextAndRunsSpellItOut() {
+        val bubble = parse("<p>今天那儿是晴，13~25℃，日落 <b>18:35</b>，比上海晚了整整一小时呢。</p>").single()
+        assertEquals("今天那儿是晴，13~25℃，日落 18:35，比上海晚了整整一小时呢。", bubble.body)
+        assertEquals(
+            listOf(run("今天那儿是晴，13~25℃，日落 "), run("18:35", InlineStyle.Bold), run("，比上海晚了整整一小时呢。")),
+            bubble.runs,
+        )
+        assertEquals(bubble.body, bubble.runs.concat())
+    }
+
+    /** `parts` 保持**逐字原文**：编辑框、搜索片段、通知文案读的都是它，一个字都不许改。 */
+    @Test
+    fun partsKeepTheRawTextForEditingAndSearch() {
+        val bubble = parse("<p>日落 <b>18:35</b></p>").single()
+        assertEquals(listOf(ContentPart.Text("日落 <b>18:35</b>")), bubble.parts)
+        assertEquals("日落 <b>18:35</b>", bubble.parts.joinToString("") { it.text })
+    }
+
+    /**
+     * `parse` 的其它调用点一律照旧——这条是「本次改动只碰渲染」的证据，也是它们的护栏：
+     * 编辑框读到的是**原文**（行内标签一个都不掉）、搜索照样搜得到那句话、后台那段结论预览
+     * 跟着拿到渲染文本（标签不再露出来）。谁哪天想让这些地方换一套文本，必须先删掉这里的断言。
+     */
+    @Test
+    fun theOtherConsumersOfTheBubbleStillSeeWhatTheySawBefore() {
+        val plain = "日落 <b>18:35</b>，比上海晚了整整一小时呢。"
+        // 编辑框：原文不含 `<p>`/`<action>` 时是**恒等**变换（一个字节都不动，也不谎称有标记被替换）
+        val editable = editableMessageOf(plain)
+        assertEquals(plain, editable.text)
+        assertFalse(editable.hasMarkup)
+
+        // 编辑框：外层的 `<p>` 照旧被剥（既有语义），而行内标签**原样留着**——它是要被编辑的源码本身
+        val wrapped = editableMessageOf("<p>$plain</p>")
+        assertTrue(wrapped.hasMarkup)
+        assertEquals(plain, wrapped.text)
+
+        // 搜索：按片段原文拼纯文本，那句话照旧搜得到（`<b>` 夹在中间不影响那几个字连在一起）
+        val searchable = plainSearchText("<p>$plain</p>")
+        assertTrue(searchable.contains("日落"))
+        assertTrue(searchable.contains("18:35"))
+    }
+
+    /** 分享预览走的是同一个 [parse]（W65）⇒ 它拿到的正文与气泡逐字一致：标签同样不再露出来。 */
+    @Test
+    fun theSharePreviewSeesTheSameBodyAsTheBubble() {
+        val content = "<p>日落 <b>18:35</b>，比上海晚了整整一小时呢。</p>"
+        assertEquals(parse(content).map { it.body }, sharePreviewBlocks(content).map { it.body })
+    }
+
+    /** 旁白/动作行不做行内解析（理由见 `MessageBubble.AnnotationLine` 的 KDoc）：原文进 head，一个字不动。 */
+    @Test
+    fun narrationTextIsLeftExactlyAsWritten() {
+        val bubble = parse("<p><action>笑<b>了</b></action></p>").single()
+        assertEquals(listOf(ContentPart.Action("笑<b>了</b>")), bubble.head)
+        assertEquals("", bubble.body)
+        assertTrue(bubble.runs.isEmpty())
+    }
+
+    @Test
+    fun inlineTagsDoNotChangeBubbleSplitting() {
+        val bubbles = parse("<p>甲<b>乙</b></p><p>丙</p>")
+        assertEquals(listOf("甲乙", "丙"), bubbles.map { it.body })
+        assertEquals(listOf(ContentPart.Text("甲<b>乙</b>"), ContentPart.Text("丙")), bubbles.flatMap { it.parts })
+    }
+
+    /** 未闭合的 `<b>` 在一次性解析里同样是字面（与 `<action>` 那条既有契约同一口径）。 */
+    @Test
+    fun unclosedInlineTagFallsBackToLiteralText() {
+        val bubble = parse("<p>日落 <b>18:35</p>").single()
+        assertEquals("日落 <b>18:35", bubble.body)
+        assertTrue(bubble.runs.isEmpty())
+    }
+
+    // ------------------------------------------------------------------
+    // 反证：星号语义一个字都没被动过
+    //
+    // 行内解析发生在**段落/分隔符解析之后**（`toBubble` 里对最终正文做一次），而星号那一套
+    // 在 `appendAnnotations` 里就已经定稿并入 `parts` 了。所以「星号不产生斜体/粗体」这条
+    // 语义在结构上不可能被行内解析改了——下面这几条既是反证，也是它与它相邻的样子。
+    // ------------------------------------------------------------------
+
+    @Test
+    fun starsKeepTheirExistingMeaningInsteadOfBecomingMarkdown() {
+        // 半角 `*…*` 没有关键词 ⇒ 保持普通文本，**不**变成斜体（既有用例：halfWidthStarWithoutKeywordStaysMarkdownText）
+        val emphasis = parse("<p>这是*强调*文字</p>").single()
+        assertEquals("这是*强调*文字", emphasis.body)
+        assertTrue(emphasis.runs.isEmpty())
+
+        // 半角 `**…**` 同理：**不**变成粗体（既有用例：halfWidthDoubleStarStaysMarkdownText）
+        val double = parse("<p>这是**加粗**文字</p>").single()
+        assertEquals("这是**加粗**文字", double.body)
+        assertTrue(double.runs.isEmpty())
+
+        // 全角 `＊…＊` 仍是「动作」（既有用例：shortFullWidthStarWithoutKeywordBecomesAction）
+        val starred = parse("<p>你好＊弯起眼睛＊</p>").single()
+        assertEquals("你好", starred.body)
+        assertEquals(listOf(ContentPart.Action("弯起眼睛")), starred.tail)
+
+        // 带关键词的半角星号仍是旁白（既有用例：halfWidthStarWithNarrationKeywordBecomesNarration）
+        val narration = parse("<p>*内心：有点开心*你好</p>").single()
+        assertEquals("你好", narration.body)
+        assertEquals(listOf(ContentPart.Narration("有点开心")), narration.head)
+    }
+
+    /** 同一段正文里两种机制各干各的：`＊笑＊` 照旧是旁白，`<b>` 照旧是粗体。 */
+    @Test
+    fun starsAndInlineTagsCoexistWithoutTouchingEachOther() {
+        val bubble = parse("<p>日落 <b>18:35</b>＊笑＊</p>").single()
+        assertEquals("日落 18:35", bubble.body)
+        assertEquals(listOf(ContentPart.Action("笑")), bubble.tail)
+        assertEquals(listOf(run("日落 "), run("18:35", InlineStyle.Bold)), bubble.runs)
+    }
+
+    // ------------------------------------------------------------------
+    // 流式：未闭合的行内标签同样扣留（否则屏幕上已经显示过的字会改口）
+    // ------------------------------------------------------------------
+
+    /**
+     * 逐字符喂一条带 `<b>` 的消息：中间态**一帧都不许**把标签当正文吐上屏，且已经显示过的正文
+     * 只许「加」不许「改口」（与 `ChatContentParserTest` 那条同名的性质同源）。
+     *
+     * 这条消息刻意没有 `<p>`：有 `<p>` 的话整个段落本来就会被扣留，测不到行内标签这一条。
+     */
+    @Test
+    fun streamingWithholdsUnclosedInlineTags() {
+        val text = "日落 <b>18:35</b>，比上海晚了整整一小时呢。记住了。"
+        val parser = StreamingContentParser()
+        var shown = emptyList<String>()
+        for (ch in text) {
+            val bubbles = parser.onDelta(ch.toString())
+            val bodies = bubbles.map { it.body }
+            // 只看**渲染文本**（`body`）：`parts` 是逐字原文，配成对的标签本来就该留在里面
+            // （编辑框/搜索读的就是它），所以那一边不能用「有没有尖括号」来判。
+            for (bubble in bubbles) {
+                assertFalse("标签漏上了屏：${bubble.body}", bubble.body.contains("<b"))
+            }
+            assertTrue("气泡数回退了：$shown → $bodies", bodies.size >= shown.size)
+            shown.forEachIndexed { i, body ->
+                assertTrue("已显示的正文改口了：$body → ${bodies[i]}", bodies[i].startsWith(body))
+            }
+            shown = bodies
+        }
+        assertEquals(parse(text), parser.finish())
+        assertEquals("日落 18:35，比上海晚了整整一小时呢。记住了。", parser.finish().single().body)
+    }
+
+    /**
+     * W68 按契约 v0.89 新增（这条是那一轮最要紧的护栏）：**大小写混用与带属性**的标签，
+     * 流式中间态同样一个字符都不许漏上屏。
+     *
+     * 消费侧与扣留侧的词表一旦分叉（W67 只有消费侧认小写、扣留侧只扫 `a..z`），`<B` / `<b class`
+     * 这种残缺形态就会在中间态被当正文吐上屏、等 `>` 到了再被吃掉——屏幕上显示过的字当场改口。
+     * 所以这条同时钉住三件事：中间态不吐字面标签、已显示的正文只增不改、收口逐字等于一次性解析。
+     */
+    @Test
+    fun streamingWithholdsMixedCaseAndAttributeTagsToo() {
+        val text = "日落 <B class=\"x\">18:35</B> 记住了。"
+        val parser = StreamingContentParser()
+        var shown = emptyList<String>()
+        for (ch in text) {
+            val bubbles = parser.onDelta(ch.toString())
+            val bodies = bubbles.map { it.body }
+            for (bubble in bubbles) {
+                // 这条样本里渲染文本不该出现任何一个尖括号/属性字：全是标签字符或属性
+                assertFalse("标签或属性漏上了屏：${bubble.body}", bubble.body.contains('<') || bubble.body.contains('>'))
+            }
+            assertTrue("气泡数回退了：$shown → $bodies", bodies.size >= shown.size)
+            shown.forEachIndexed { i, body ->
+                assertTrue("已显示的正文改口了：$body → ${bodies[i]}", bodies[i].startsWith(body))
+            }
+            shown = bodies
+        }
+        assertEquals(parse(text), parser.finish())
+        assertEquals("日落 18:35 记住了。", parser.finish().single().body)
+    }
+
+    /**
+     * 逐字符 / 任意切分的流式结果必须与一次性解析完全一致（含行内标签、`<br>` 分隔符、
+     * 以及 W71 起新增的两处：`u` 与**保护区**内的 `<br>`）。
+     */
+    @Test
+    fun streamingAnyChunkingMatchesOneShot() {
+        val sample = """
+            <p>今天那儿是晴，13~25℃，日落 <b>18:35</b>，比上海晚了整整一小时呢。</p>
+            <p>记住 <CODE>abc</CODE>、<i>斜体</i> 与 <strong class="x">加粗</strong> 哦</p>
+            <p>这是<S>删除线</S>与<U>下划线</U>，＊弯起眼睛＊</p>
+            <p>1 < 2 且 <span class="y">白名单外的标签原样</span> 收尾</p>
+            <p>日落 <B>18:35</B></p>
+            <p>上一行<br>下一行</p>
+            <p>甲<br/>乙</br>丙</p>
+            <p><code>甲<br>乙</code>与<u>下划线</u></p>
+            <p>她<action>她<br>点点头</action></p>
+        """.trimIndent()
+        val expected = parse(sample)
+
+        val charByChar = StreamingContentParser()
+        for (ch in sample) charByChar.onDelta(ch.toString())
+        assertEquals(expected, charByChar.finish())
+
+        val random = Random(20261007)
+        repeat(25) {
+            val parser = StreamingContentParser()
+            var index = 0
+            while (index < sample.length) {
+                val end = minOf(index + 1 + random.nextInt(7), sample.length)
+                parser.onDelta(sample.substring(index, end))
+                index = end
+            }
+            assertEquals(expected, parser.finish())
+        }
+    }
+
+    /** 一整段只有标记时，收口也必须是字面（与一次性解析一致；未闭合的 `<p>` 同样照字面留着）。 */
+    @Test
+    fun streamingUnclosedInlineTagFallsBackOnFinish() {
+        val parser = StreamingContentParser()
+        parser.onDelta("<p>日落 <b>18:35")
+        assertEquals(listOf("<p>日落 <b>18:35"), parser.finish().map { it.body })
+    }
+
+    // ------------------------------------------------------------------
+    // 回归：正文里一串尖括号不许把后面的真标签「遮住」，也不许把扫描拖成 O(N²)
+    // ------------------------------------------------------------------
+
+    @Test
+    fun angleBracketsBeforeATagDoNotHideIt() {
+        assertEquals(
+            listOf(run("1 < 2 且 3 > 2，日落 "), run("18:35", InlineStyle.Bold)),
+            parseInlineMarkup("1 < 2 且 3 > 2，日落 <b>18:35</b>"),
+        )
+        // 半路那个 `<` 与它后面那个 `>` 之间还夹着一个真标签：不能「从 `<` 一路找到下一个 `>`」
+        // 就把整段跳过（那样 `<b>` 会被连同它一起跳过，粗体永远不生效）。
+        assertEquals(
+            listOf(run("1 < 2 "), run("甲", InlineStyle.Bold)),
+            parseInlineMarkup("1 < 2 <b>甲</b>"),
+        )
+    }
+
+    /**
+     * ⚠️ 与 `ChatContentParserTest` 那条复杂度回归同一性质：阈值只用来区分「线性」与「平方」，
+     * 不是耗时指标。正文里成串的 `<` 若用 `indexOf('>', lt)` 逐个找配对（找不到就一路扫到串尾），
+     * 这里就会退回 O(N²)——W63 刚在同一片区域修掉两处同形状的问题。
+     *
+     * W68 注意：因为契约要求「属性一律不解析」，标签长度不再有上界，`inlineTagEnd` 那扇定宽窗
+     * 换成了「扫到 `>` 或下一个 `<` 为止」。这条回归因此更要紧——它钉住换完之后仍是线性的。
+     */
+    @Test
+    fun aHugeRunOfAngleBracketsStaysWithinALinearBudget() {
+        val count = 20_000
+        for (body in listOf("<".repeat(count), "a<b".repeat(count / 3), "<b class=x".repeat(count / 9))) {
+            val startedAt = System.nanoTime()
+            val bubble = parse("<p>$body</p>").single()
+            val elapsedMs = (System.nanoTime() - startedAt) / 1_000_000
+            assertEquals(body, bubble.body)
+            assertTrue(bubble.runs.isEmpty())
+            assertTrue(
+                "${body.length} 字符（一串普通尖括号）用了 ${elapsedMs}ms——复杂度退回 O(N²) 了？",
+                elapsedMs < 2_000,
+            )
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 工具
+    // ------------------------------------------------------------------
+
+    private fun run(text: String, vararg styles: InlineStyle) = InlineRun(text, styles.toSet())
+
+    private fun List<InlineRun>.concat(): String = joinToString("") { it.text }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/share/ShareSendDeclarationTest.kt

@@ -0,0 +1,58 @@
+package top.yeij.cyrene.domain.share
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 批量投递的「声明」边界（[ShareRules.declaresSendPreference]）。
+ *
+ * 钉住的是一件**不许再走回去**的事：分享进来的 N 张图会落成 N 条消息（契约里 `chat.image` 是单图
+ * 字段），而这 N 条是**一次**投递动作——它们之间绝不许互相打断 / 互相取消（`02` F4 的后端口径、
+ * `05` 的多图自相打断一节）。一旦某一条在忙时声明了 `interrupt`，第 2 条就会把第 1 条刚起的回合打
+ * 掉；声明 `parallel` 同样把「一次倒进去」变成「几条并行回合」。
+ *
+ * 纯函数 ⇒ 不需要组合界面、不需要设备，就能把**整批**（0 到 [ShareRules.MAX_IMAGES] - 1）逐条穷举。
+ */
+class ShareSendDeclarationTest {
+
+    @Test
+    fun `share never declares on any message of the batch`() {
+        (0 until ShareRules.MAX_IMAGES).forEach { index ->
+            assertFalse(
+                "分享的第 $index 条不许声明（声明就会打断同一批里的上一条）",
+                ShareRules.declaresSendPreference(fromShare = true, index = index),
+            )
+        }
+    }
+
+    @Test
+    fun `share stays silent even past the image limit`() {
+        // 超限那张本来就不发（见 truncatedImagesNotice），但判据对它也不许翻成 true：
+        // 一旦有人把上限放宽而忘了这条，越界位置不该成为唯一声明的那一条。
+        (ShareRules.MAX_IMAGES..ShareRules.MAX_IMAGES + 3).forEach { index ->
+            assertFalse(ShareRules.declaresSendPreference(fromShare = true, index = index))
+        }
+    }
+
+    @Test
+    fun `the typed send declares on its first message only`() {
+        assertTrue(
+            "手打的第一条仍按「她忙时发消息」偏好投递",
+            ShareRules.declaresSendPreference(fromShare = false, index = 0),
+        )
+        (1 until ShareRules.MAX_IMAGES).forEach { index ->
+            assertFalse(
+                "手打的第 $index 条声明就是在打断自己刚起的上一轮",
+                ShareRules.declaresSendPreference(fromShare = false, index = index),
+            )
+        }
+    }
+
+    @Test
+    fun `a single message batch is the same rule`() {
+        // 只有一条时两种入口的差别正是全部差别：手打声明、分享不声明。
+        assertTrue(ShareRules.declaresSendPreference(fromShare = false, index = 0))
+        assertFalse(ShareRules.declaresSendPreference(fromShare = true, index = 0))
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/domain/share/ShareTextFallbackTest.kt

@@ -0,0 +1,170 @@
+package top.yeij.cyrene.domain.share
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * 正文的**回落链**：`EXTRA_TEXT` → `EXTRA_SUBJECT` → `EXTRA_TITLE`（[ShareRules.extract]）。
+ *
+ * ## 这条链修的是哪种静默
+ * 有些发送方**不填** `EXTRA_TEXT`，内容只在 `EXTRA_SUBJECT`（少数在 `EXTRA_TITLE`）里。本端此前只读
+ * `EXTRA_TEXT` ⇒ 那样一次分享**整条静默**：用户点了分享，界面毫无反应、后端零请求、也没有一句解释
+ * （`SharePayload.kt` 里那条 `contentUnreadable` 判据也不含这两个 extra）。修法就是这条链。
+ *
+ * ## 本文件钉住的三件事
+ * 1. **回落链本身**：只有 `SUBJECT` / 只有 `TITLE` ⇒ 用它当正文，且来源如实记进
+ *    `SharedContent.textSource`（渲染层靠它说一句「来自分享标题」）；
+ * 2. **既有情形逐字不变**：`EXTRA_TEXT` 非空时它**一定**赢（它是第一站），结果与今天的实现完全相同
+ *    ——回落链不许「取到更多东西」，它补的是原先那条缝；
+ * 3. **都不成正文时不许闭嘴**：三个文本 extra 里躺着值（含空白、含读不出类型）而没换来正文 ⇒
+ *    `contentUnreadable`，走既有的「读不进来」告知；而**三个都没有值**（用户确实什么都没分享）照旧
+ *    静默。两者的分野就是 `textPresent` 这个由调用方（读了原始值的那一层）报进来的事实。
+ *
+ * 真实 `Intent` 的读取在 `app/ShareIntake.kt`（`rawExtra` + [top.yeij.cyrene.app.shareTextExtrasOf]，
+ * 那个「值在不在」的判断与 `runCatching` 的守卫各有一份用例，见 `ShareTextExtrasTest`）。
+ */
+class ShareTextFallbackTest {
+
+    /** 一次最普通的 `ACTION_SEND`，只把三个文本 extra 摆出来（其余字段都空）。 */
+    private fun extract(
+        text: CharSequence? = null,
+        subject: CharSequence? = null,
+        title: CharSequence? = null,
+        textPresent: Boolean = false,
+    ): SharedContent = ShareRules.extract(
+        action = ShareRules.ACTION_SEND,
+        text = text,
+        subject = subject,
+        title = title,
+        textPresent = textPresent,
+    )
+
+    @Test
+    fun `a subject only share becomes the body and says where it came from`() {
+        // 这次分享的现场：`EXTRA_TEXT` 一个值都没有，内容全在 `EXTRA_SUBJECT` 里。
+        val share = extract(subject = "分享自某某App：一篇文章的标题")
+
+        assertEquals("分享自某某App：一篇文章的标题", share.text)
+        assertEquals(ShareTextSource.Subject, share.textSource)
+        // 拿到的是一段真内容 ⇒ 既不是「空分享」、也不是「读不进来」，与一次普通的文本分享没有区别。
+        assertFalse(share.isEmpty)
+        assertFalse(share.contentUnreadable)
+        assertTrue(share.worthDelivering)
+    }
+
+    @Test
+    fun `a title only share becomes the body`() {
+        val share = extract(title = "只有标题的一次分享")
+
+        assertEquals("只有标题的一次分享", share.text)
+        // 来源分档只为「如实登记」，用户那边 Subject 与 Title 说的是同一句话（见 `ShareTextOrigin.kt`）。
+        assertEquals(ShareTextSource.Title, share.textSource)
+        assertTrue(share.worthDelivering)
+    }
+
+    @Test
+    fun `a non blank text always wins the chain`() {
+        // 既有情形逐字不变：三个都有值时，正文与来源都是今天那一份（回落链对它**完全**不生效）。
+        val share = extract(text = "对方写的正文", subject = "对方给的标题", title = "对方给的另一个标题")
+
+        assertEquals("对方写的正文", share.text)
+        assertEquals(ShareTextSource.Text, share.textSource)
+    }
+
+    @Test
+    fun `a blank text falls back to the subject`() {
+        // 空白串（不是 null）同样是「没有正文」：口径与取 text 时那一次 trim 完判空完全一致。
+        val share = extract(text = "   \n\t ", subject = "标题顶上")
+
+        assertEquals("标题顶上", share.text)
+        assertEquals(ShareTextSource.Subject, share.textSource)
+    }
+
+    @Test
+    fun `a blank text and a blank subject fall back to the title`() {
+        val share = extract(text = " ", subject = "\n", title = "第三站顶上")
+
+        assertEquals("第三站顶上", share.text)
+        assertEquals(ShareTextSource.Title, share.textSource)
+    }
+
+    @Test
+    fun `the body is trimmed the same way whichever station it came from`() {
+        // 三站的归一化口径必须一模一样（`toString` → 两侧 trim）：不然同一段字从 SUBJECT 来就会多带
+        // 一个换行，而正文那一段是要**逐字**发出去的。
+        listOf(
+            ShareTextSource.Text to extract(text = "  正文  "),
+            ShareTextSource.Subject to extract(subject = "  正文  "),
+            ShareTextSource.Title to extract(title = "  正文  "),
+        ).forEach { (source, share) ->
+            assertEquals(source.name, "正文", share.text)
+            assertEquals(source.name, source, share.textSource)
+        }
+    }
+
+    @Test
+    fun `a fallen back body is a normal share in every other respect`() {
+        // 回落来的正文走的是同一条既有的路：`isEmpty` / `worthDelivering` / 附件上限这些判据一个字都
+        // 没为它改过 —— 除了「来源」那一格。
+        val text = extract(text = "正文")
+        val subject = extract(subject = "正文")
+
+        assertTrue(subject.text == text.text)
+        assertEquals(text.isEmpty, subject.isEmpty)
+        assertEquals(text.contentUnreadable, subject.contentUnreadable)
+        assertEquals(text.images, subject.images)
+        assertEquals(text.documents, subject.documents)
+        assertEquals(ShareTextSource.Text, text.textSource)
+    }
+
+    @Test
+    fun `when none of the three yields a body we speak instead of staying silent`() {
+        // 三者都空（甚至读不出类型）**不是**「什么都没分享」：用户点了分享，本端一个字节都没读出来。
+        // 那件事必须能说出口（`textPresent` 由读了原始值的调用方如实报进来），否则又是一次静默。
+        val share = extract(text = null, subject = "   ", title = null, textPresent = true)
+
+        assertTrue(share.isEmpty)
+        assertTrue(share.contentUnreadable)
+        assertTrue(share.worthDelivering)
+    }
+
+    @Test
+    fun `a share whose three extras hold nothing at all still stays silent`() {
+        // 边界（既有口径，不许放宽）：三个 extra **连值都没有** ⇒ 用户确实什么都没分享，说一句才是噪声。
+        // 分野就在 `textPresent` 这一个事实上，不在「正文是不是空的」上。
+        val share = extract()
+
+        assertTrue(share.isEmpty)
+        assertFalse(share.contentUnreadable)
+        assertFalse(share.worthDelivering)
+    }
+
+    @Test
+    fun `a fallen back body next to unusable streams is not a whole read failure`() {
+        // 「读不进来」那条判据只在**一条可用内容都没有**时成立：从标题回落的正文照样是一次拿到了东西
+        // 的分享，不能因为对方给的那几个地址用不了就说成「这次分享的内容没能读进来」。
+        val share = ShareRules.extract(
+            action = ShareRules.ACTION_SEND,
+            subject = "从标题来的正文",
+            streamStrings = listOf("file:///etc/hosts"),
+            textPresent = true,
+        )
+
+        assertEquals("从标题来的正文", share.text)
+        assertFalse(share.contentUnreadable)
+    }
+
+    @Test
+    fun `an unrelated intent with a subject in it still extracts to nothing`() {
+        // 不是分享 action 就不是分享：哪怕三个 extra 里照样躺着值，也不该走这条路（更不该出一条告知）。
+        val share = ShareRules.extract(
+            action = "android.intent.action.VIEW",
+            subject = "标题",
+            textPresent = true,
+        )
+
+        assertEquals(SharedContent(), share)
+    }
+}

app/src/test/kotlin/top/yeij/cyrene/ui/chat/ContentlessMessageTest.kt

@@ -5,6 +5,7 @@ import org.junit.Assert.assertTrue
 import org.junit.Test
 import top.yeij.cyrene.data.api.dto.DocumentRefDto
 import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
 
 /**
  * 「这条消息什么都没传过来」的判据（纯函数，`user` 消息的空气泡修复）。
@@ -15,8 +16,9 @@ import top.yeij.cyrene.data.api.dto.HistoryMessageDto
  *
  * 这个测试要钉住两件事：
  * 1. 真的什么都没有时成立（空 / 纯空白）；
- * 2. **任何**有内容的形态都不成立 —— 有正文（哪怕只有一个空格之外的字）、有图、有附件、有思维链，
- *    以及**所有 assistant 消息**。误伤一条就等于给一条好好的消息扣上「内容没传过来」的帽子。
+ * 2. **任何**有内容的形态都不成立 —— 有正文（哪怕只有一个空格之外的字）、有图、有附件、有思维链、
+ *    有 `voice` 键（语音形态），以及**所有 assistant 消息**。误伤一条就等于给一条好好的消息扣上
+ *    「内容没传过来」的帽子。
  */
 class ContentlessMessageTest {
 
@@ -26,6 +28,7 @@ class ContentlessMessageTest {
         image: String? = null,
         documents: List<DocumentRefDto> = emptyList(),
         thinking: String? = null,
+        voice: VoiceDto? = null,
     ) = HistoryMessageDto(
         id = "m1",
         sessionId = "web",
@@ -34,6 +37,7 @@ class ContentlessMessageTest {
         image = image,
         documents = documents,
         thinking = thinking,
+        voice = voice,
         createdAt = 1_791_088_571_785L,
     )
 
@@ -65,6 +69,17 @@ class ContentlessMessageTest {
         assertTrue(isContentlessUserMessage(message(image = "   ")))
     }
 
+    @Test
+    fun `a voice message is never contentless`() {
+        // 语音的转写文本可能为空（`status = empty`，或微信那条根本没有副本），但那条消息
+        // **不是什么都没有**：它有语音形态。判据只看 `voice` 键在不在（契约 §4.4）。
+        assertFalse(
+            isContentlessUserMessage(
+                message(content = "", voice = VoiceDto(source = "platform", status = "empty")),
+            ),
+        )
+    }
+
     // —— 不成立：凡有一点点内容就一个字都不说 ——
 
     @Test

app/src/test/kotlin/top/yeij/cyrene/ui/chat/MessageTimeCarrierTest.kt

@@ -0,0 +1,202 @@
+package top.yeij.cyrene.ui.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import top.yeij.cyrene.data.api.dto.DocumentRefDto
+import top.yeij.cyrene.data.api.dto.HistoryMessageDto
+import top.yeij.cyrene.data.api.dto.VoiceDto
+import top.yeij.cyrene.domain.parse.ParsedBubble
+
+/**
+ * 「这条消息外侧那枚时间挂在哪一块上」的判据（纯函数 [messageTimeCarrier]）。
+ *
+ * **背景**：主人 2026-10-07 验收 W69 时报的缺口 —— 纯文字消息都有时间，**纯附件消息边上没有**。
+ * 根因在 W69 的落脚点写法上：时间挂在「这条消息**最后一个有正文的气泡**」外侧，而纯附件消息
+ * （`documents` 非空 / `image` 非空、`content` 为空）解析出来的唯一那个气泡 `body` 也是空，
+ * [Bubble] 见空 `body` 什么都不画 ⇒ 那一行**根本没被画出来**。
+ *
+ * 这个测试要钉住三件事：
+ * 1. **一个正文气泡都没有时，时间落到最后画出来的那个附件块上**（附件芯片排 / 图片 / 语音形态），
+ *    而且顺序与渲染顺序一致（谁最后画谁拿）——这就是「纯附件消息也有时间」；
+ * 2. **有正文气泡时一个字都不许变**（W69 的口径：最后一个有正文的气泡，末段的纯旁白气泡不算）；
+ * 3. **真的空气泡**（[isContentlessUserMessage]）在这里返回 `null`，但那种消息**仍然有时间**
+ *    —— 那一处由 [MessageBubble] 给 [ContentlessNote] 单独包一层 [BubbleWithTime]，是另一条路。
+ *
+ * 「贴左还是贴右」不在这里测：那是 [BubbleWithTime] 按 `isUser` 定的，本函数只回答「挂在哪一块」。
+ */
+class MessageTimeCarrierTest {
+
+    private fun message(
+        role: String = "user",
+        content: String = "",
+        image: String? = null,
+        documents: List<DocumentRefDto> = emptyList(),
+        thinking: String? = null,
+        voice: VoiceDto? = null,
+        createdAt: Long = 1_791_088_571_785L,
+    ) = HistoryMessageDto(
+        id = "m1",
+        sessionId = "web",
+        role = role,
+        content = content,
+        image = image,
+        documents = documents,
+        thinking = thinking,
+        voice = voice,
+        createdAt = createdAt,
+    )
+
+    private val document = DocumentRefDto(
+        name = "6c1f0a2b3d4e5f60718293a4b5c6d7e8.txt",
+        mime = "text/plain",
+        size = 10,
+        chars = 10,
+        status = "extracted",
+    )
+
+    /** 解析出来的一个正文气泡（`plainBubble` 那份形状）。 */
+    private fun body(text: String) = ParsedBubble(
+        body = text,
+        parts = emptyList(),
+        head = emptyList(),
+        tail = emptyList(),
+    )
+
+    /**
+     * 纯附件消息的 `bubbles`：`content` 为空 ⇒ 解析器一个都没给 ⇒ `MessageBubble` 兜一个占位气泡
+     * （`plainBubble("")`）。它 `body` 为空，所以 [Bubble] 一个像素都不画 —— 缺口就在这一步。
+     */
+    private val placeholderBubbles = listOf(body(""))
+
+    private val voiceWithoutTranscript = VoiceDto(source = "asr", status = "empty")
+
+    // —— 一个正文气泡都没有：落到最后画出来的那个附件块上 ——
+
+    @Test
+    fun `an attachments only message hangs the time on the chip row`() {
+        val message = message(content = "", documents = listOf(document))
+
+        assertEquals(
+            MessageTimeCarrier.Attachments,
+            messageTimeCarrier(message, placeholderBubbles),
+        )
+    }
+
+    @Test
+    fun `an image only message hangs the time on the image`() {
+        val message = message(content = "", image = "http://host/api/v1/files/a.png")
+
+        assertEquals(MessageTimeCarrier.Image, messageTimeCarrier(message, placeholderBubbles))
+    }
+
+    @Test
+    fun `a voice message with nothing transcribed hangs the time on the voice row`() {
+        // `status = empty` ⇒ 正文为空，而这条消息**不是什么都没有**（`isContentlessUserMessage`
+        // 特意把语音排除掉）。它的可视块只有语音形态，时间就该落在那里。
+        val message = message(content = "", voice = voiceWithoutTranscript)
+
+        assertEquals(MessageTimeCarrier.Voice, messageTimeCarrier(message, placeholderBubbles))
+        assertFalse(isContentlessUserMessage(message))
+    }
+
+    @Test
+    fun `when several blocks are there the last one drawn wins`() {
+        // 渲染顺序是「附件芯片排 → 图片 → 语音形态」，所以时间的落点也按这个顺序往回退。
+        val chipsAndImage = message(
+            content = "",
+            documents = listOf(document),
+            image = "http://host/api/v1/files/a.png",
+        )
+        assertEquals(MessageTimeCarrier.Image, messageTimeCarrier(chipsAndImage, placeholderBubbles))
+
+        val allThree = message(
+            content = "",
+            documents = listOf(document),
+            image = "http://host/api/v1/files/a.png",
+            voice = voiceWithoutTranscript,
+        )
+        assertEquals(MessageTimeCarrier.Voice, messageTimeCarrier(allThree, placeholderBubbles))
+    }
+
+    @Test
+    fun `her attachments get the time too`() {
+        // 判据与角色无关：她也会发只有图 / 只有附件的一条。
+        val message = message(role = "assistant", content = "", documents = listOf(document))
+
+        assertEquals(
+            MessageTimeCarrier.Attachments,
+            messageTimeCarrier(message, placeholderBubbles),
+        )
+    }
+
+    // —— 有正文气泡时：W69 的口径一个字都不变 ——
+
+    @Test
+    fun `a text bubble always wins over the blocks above it`() {
+        val message = message(
+            content = "甲",
+            documents = listOf(document),
+            image = "http://host/api/v1/files/a.png",
+        )
+
+        assertEquals(MessageTimeCarrier.TextBubble(0), messageTimeCarrier(message, listOf(body("甲"))))
+    }
+
+    @Test
+    fun `the last non empty bubble carries the time`() {
+        val bubbles = listOf(body("甲"), body("乙"))
+
+        assertEquals(
+            MessageTimeCarrier.TextBubble(1),
+            messageTimeCarrier(message(content = "甲<p>乙</p>"), bubbles),
+        )
+    }
+
+    @Test
+    fun `a trailing annotation only bubble never carries the time`() {
+        // 末段只有旁白（`<action>`/`<narration>`）时不画正文框：时间退回上一个有正文的气泡。
+        val bubbles = listOf(body("甲"), body(""))
+
+        assertEquals(
+            MessageTimeCarrier.TextBubble(0),
+            messageTimeCarrier(message(content = "甲<action>她抬头</action>"), bubbles),
+        )
+    }
+
+    // —— 真的什么都没有：这里返回 null，时间由 ContentlessNote 那条路自己画 ——
+
+    @Test
+    fun `a truly empty user message has no block to hang the time on`() {
+        val message = message(content = "   ")
+
+        // 判据与 `isContentlessUserMessage` 是互补的：那条路**仍然**有时间（`BubbleWithTime`
+        // 包着 `ContentlessNote`），所以这里返回 null 不等于「这条消息没有时间」。
+        assertTrue(isContentlessUserMessage(message))
+        assertNull(messageTimeCarrier(message, placeholderBubbles))
+    }
+
+    @Test
+    fun `blank image strings and empty documents are not blocks`() {
+        val message = message(content = "", image = "   ", documents = emptyList())
+
+        assertNull(messageTimeCarrier(message, placeholderBubbles))
+    }
+
+    // —— 与时间戳缺失的关系：两件事分开判 ——
+
+    @Test
+    fun `the carrier ignores the timestamp and the label ignores the carrier`() {
+        // 「`createdAt <= 0` ⇒ 整条不画」是 [messageTimeLabel] 那一档的事：落点照旧算出来，
+        // 只是文案为 null ⇒ `BubbleWithTime` 连 `Box` 都不建。两处刻意分开判，谁都不替谁兜底。
+        val message = message(content = "", documents = listOf(document), createdAt = 0L)
+
+        assertEquals(
+            MessageTimeCarrier.Attachments,
+            messageTimeCarrier(message, placeholderBubbles),
+        )
+        assertNull(messageTimeLabel(createdAt = 0L, nowMillis = 1_791_088_571_785L))
+    }
+}