merge: W3 — B1 /upload（大图走上传，历史只留 URL）

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

@@ -11,11 +11,13 @@ import top.yeij.cyrene.data.api.ApiClientFactory
 import top.yeij.cyrene.data.api.ChatApi
 import top.yeij.cyrene.data.api.MetaApi
 import top.yeij.cyrene.data.api.SessionsApi
+import top.yeij.cyrene.data.api.UploadApi
 import top.yeij.cyrene.data.repository.AdminRepository
 import top.yeij.cyrene.data.repository.ChatRepository
 import top.yeij.cyrene.data.repository.MessageRepository
 import top.yeij.cyrene.data.repository.MetaRepository
 import top.yeij.cyrene.data.repository.SessionRepository
+import top.yeij.cyrene.data.repository.UploadRepository
 import top.yeij.cyrene.data.ws.ChatSocket
 
 /** 手写 DI 容器（D：不引 Hilt）。 */
@@ -76,6 +78,31 @@ class AppContainer(context: Context) {
 
     val chatRepository: ChatRepository get() = ChatRepository(chatApi)
 
+    private var cachedUploadApi: UploadApi? = null
+    private var cachedUploadBaseUrl: String? = null
+
+    /**
+     * 图片上传端点（`POST /api/v1/upload`）；与 [chatApi] 同源（同一 baseUrl、同一 token/401 处理）——
+     * 上传的产物 URL 就是要交给 `POST /api/v1/chat` 的 `image` 字段的，两者必须在同一个后端上。
+     */
+    val uploadApi: UploadApi
+        get() {
+            val baseUrl = authManager.currentBaseUrl
+            val cached = cachedUploadApi
+            if (cached != null && cachedUploadBaseUrl == baseUrl) return cached
+            val created = ApiClientFactory.create(
+                baseUrl = baseUrl,
+                service = UploadApi::class.java,
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
+            )
+            cachedUploadBaseUrl = baseUrl
+            cachedUploadApi = created
+            return created
+        }
+
+    val uploadRepository: UploadRepository get() = UploadRepository(uploadApi)
+
     private var cachedAdminApi: AdminApi? = null
     private var cachedAdminBaseUrl: String? = null
 

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

@@ -0,0 +1,33 @@
+package top.yeij.cyrene.data.api
+
+import top.yeij.cyrene.data.api.dto.UploadResponse
+import okhttp3.MultipartBody
+import retrofit2.Response
+import retrofit2.http.Multipart
+import retrofit2.http.POST
+import retrofit2.http.Part
+
+/**
+ * 图片上传端点（`POST /api/v1/upload`，api-client §1 行 13）。权限 `owner|admin`。
+ *
+ * **上传本身不是目的**：服务端把 `chat.image` 字符串**原样落库**，于是每一页历史与每一次
+ * WS `history` 回放都要把整段 base64 再传一遍（协同 G3）。上传一次、消息里只留 URL，
+ * 是这条链路上唯一能把「历史重量」永久压下去的手段。
+ *
+ * 与 [ChatApi] 分开：它的请求体是 multipart（不是 JSON）、错误面也完全不同
+ * （`413 payload_too_large` / `415 unsupported_media_type` 是它的日常回执）。
+ *
+ * 返回原始 [Response] 而不是直接折成 `Result`：与其它端点一样由仓库层统一走
+ * [ApiErrorMapper]，状态码在这里**不承载额外语义**（`413`/`415` 的机器可读区分在
+ * `error.code` 里，所以仓库能用 [apiCall]）。
+ */
+interface UploadApi {
+
+    /**
+     * @param file **部件名必须是 `file`**（服务端 `r.FormFile("file")`）：字段名错了会回
+     *   `400 {error:{code:"bad_request",message:"file is required"}}`（已对着在线后端实测）。
+     */
+    @Multipart
+    @POST("api/v1/upload")
+    suspend fun upload(@Part file: MultipartBody.Part): Response<ApiEnvelope<UploadResponse>>
+}

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

@@ -0,0 +1,31 @@
+package top.yeij.cyrene.data.api.dto
+
+import kotlinx.serialization.Serializable
+
+/**
+ * `POST /api/v1/upload` 的成功载荷（api-client §1 行 13，v0.24 起的 B1 端点）。
+ *
+ * 线上形状（`internal/services/gateway/upload.go` 的 `uploadResponse`，字段名逐字如此）：
+ * ```
+ * 201 {"data":{"url":"http://192.168.1.10:10942/api/v1/files/<32hex>.png","size":1234,"mime":"image/png","name":"<32hex>.png"}}
+ * ```
+ *
+ * 语义要点：
+ * - [url] 是**绝对同源地址**（`scheme://host/api/v1/files/<name>`），**可直接作 `chat.image`**：
+ *   视觉层只把 `http(s)://` 开头当 URL，裸路径会被当成 base64 —— 所以这个字段必须按 URL 校验，
+ *   不能原样塞回去（见 `UploadRepository`）；
+ * - [name] 是服务端生成的 **32 位小写 hex + 白名单扩展名**，客户端原始文件名**被丢弃**（不可信输入）；
+ * - [size] 字节数与 [mime] 都是**服务端嗅探/统计的结果**，不是客户端声明的——客户端传的
+ *   `Content-Type` 一律不被采信（`sniffImageMIME`）。
+ *
+ * 全部字段带默认值：解码器是生产同一份 `Json`（`ignoreUnknownKeys` / `coerceInputValues`），
+ * 将来服务端加键不会让整次上传变成解析失败。**缺 `url`（或 `url` 不是绝对 http(s)）仍要判失败**——
+ * 那是「上传成功但拿不到可用地址」，由仓库层拦，绝不把空串/路径当 URL 发出去。
+ */
+@Serializable
+data class UploadResponse(
+    val url: String = "",
+    val size: Long = 0,
+    val mime: String = "",
+    val name: String = "",
+)

app/src/main/kotlin/top/yeij/cyrene/data/image/ChatImagePreparer.kt

@@ -8,6 +8,19 @@ import android.util.Base64
 import top.yeij.cyrene.domain.chat.ChatImageBudget
 import java.io.ByteArrayOutputStream
 
+/**
+ * 一次重编码的产物。
+ *
+ * [dataUri] 与 [bytes] 是**同一张图**的两种形态：内联（base64 `data:` URI）用前者，
+ * 上传（`POST /api/v1/upload`）用后者。上传时**不能**从 [dataUri] 反解一遍——那既多一次
+ * 解码与分配，也让「上传的字节」和「内联的字节」有漂移的余地。
+ */
+class PreparedImage(
+    val dataUri: String,
+    val bytes: ByteArray,
+    val mime: String,
+)
+
 /**
  * 把用户选的本地图片压成可以内联发送的 `data:` URI（**发送前的必经一步**）。
  *
@@ -23,6 +36,10 @@ import java.io.ByteArrayOutputStream
  * 任何一步失败（读不到 / 解不出 / 编不出 / 压不到预算内）都返回 `null`——由调用方回滚并报错，
  * **绝不**退回「原图 base64」：那既会撞服务端 5 MiB 硬顶，也会把历史背成几 MB。
  *
+ * 产物同时给出 `data:` URI 与**同一份**字节：**内联还是上传由调用方按体积定**
+ * （见 `ChatImageDelivery`）——本对象只管「编到预算内」，通道选择是另一件事，而且它需要
+ * 编完之后的真实字节数才谈得上。
+ *
  * 预算数学在 [ChatImageBudget]（纯函数，可单测）；本对象只剩「必须真机才有」的解码与编码。
  */
 object ChatImagePreparer {
@@ -33,10 +50,10 @@ object ChatImagePreparer {
     private const val MAX_ATTEMPTS = 4
 
     /**
-     * @return 可直接作为 `image` 字段发送的 `data:` URI；失败返回 `null`。
+     * @return 可内联发送的 `data:` URI 与可上传的同一份字节；失败返回 `null`。
      * 必须在后台线程调用（解码 + 缩放 + 编码都是重活）。
      */
-    fun prepare(context: Context, uri: Uri): String? {
+    fun prepare(context: Context, uri: Uri): PreparedImage? {
         val raw = readBytes(context, uri) ?: return null
         val decoded = decodeScaled(raw) ?: return null
         return try {
@@ -80,7 +97,7 @@ object ChatImagePreparer {
     }
 
     /** 逐档降尺寸，直到编码后字节数落进预算；都落不进返回 `null`。 */
-    private fun encodeWithinBudget(source: Bitmap): String? {
+    private fun encodeWithinBudget(source: Bitmap): PreparedImage? {
         var width = source.width
         var height = source.height
         repeat(MAX_ATTEMPTS) { attempt ->
@@ -92,7 +109,8 @@ object ChatImagePreparer {
 
             if (ChatImageBudget.withinTarget(bytes.size)) {
                 val dataUri = ChatImageBudget.dataUri(mime, Base64.encodeToString(bytes, Base64.NO_WRAP))
-                return dataUri.takeIf { ChatImageBudget.withinServerLimit(it.length) }
+                if (!ChatImageBudget.withinServerLimit(dataUri.length)) return null
+                return PreparedImage(dataUri = dataUri, bytes = bytes, mime = mime)
             }
             width = (width / 2).coerceAtLeast(1)
             height = (height / 2).coerceAtLeast(1)

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

@@ -0,0 +1,112 @@
+package top.yeij.cyrene.data.repository
+
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.MultipartBody
+import okhttp3.RequestBody.Companion.toRequestBody
+import top.yeij.cyrene.core.error.CyreneError
+import top.yeij.cyrene.data.api.CyreneException
+import top.yeij.cyrene.data.api.UploadApi
+import top.yeij.cyrene.data.api.apiCall
+
+/**
+ * 一次成功上传的可用形态。
+ *
+ * 调用方（`ChatViewModel`）只需要 [url]，其余三个字段由服务端生成、留着排查用：
+ * [size] 是服务端统计的字节数、[mime] 是**服务端嗅探**出的类型（不是客户端声明的）、
+ * [name] 是服务端存储名（客户端原始文件名已被丢弃）。
+ */
+data class UploadedImage(
+    val url: String,
+    val size: Long,
+    val mime: String,
+    val name: String,
+)
+
+/**
+ * 图片上传取数层（`POST /api/v1/upload`）。
+ *
+ * ## 为什么这台机器存在
+ * 服务端把 `chat.image` 字符串**原样落库**（api-client §1 行 3 + 协同 G3）：内联的 base64
+ * 会在**每一页历史**与**每一次 WS `history` 回放**里重传一遍。上传一次、消息里只留一个
+ * URL，是唯一能让历史不再随图片长大的路。
+ *
+ * ## 错误语义（这里是本仓库与只读仓库的差别）
+ * 用 [apiCall]：它的状态码**不承载额外语义**——`413 payload_too_large` 与
+ * `415 unsupported_media_type` 的机器可读区分都在 `error.code` 里（已对着在线后端实测，
+ * 见 `UploadDtoRealPayloadTest`），不像 `POST /api/v1/chat` 那样必须靠状态码分 `202` / `409`。
+ * 于是网络 / 超时 / `401` / 服务端拒绝一律折进 `Result.failure`，调用方按 `code` 或
+ * [CyreneError] 的类型分支。
+ *
+ * ## 两处**客户端**必须自己把关的地方（服务端帮不了）
+ * 1. **`url` 必须是绝对 http(s) 地址**：`chat.image` 的视觉层只把 `http(s)://` 当 URL
+ *    （`vision.ParseImageRef` 的判据就是 `strings.HasPrefix(src, "http://")`），裸路径
+ *    （如 `/api/v1/files/x.png`）会被当成 **base64** 载荷。拿到这种 url 还照发，就是把这一轮
+ *    丢进「图片解析失败」的黑洞——所以这里直接判解析失败，宁可当场重试。
+ * 2. **`url` 不能为空**：`201` 却没有可用地址 = 上传了但拿不到东西，同样判失败，**绝不**
+ *    退回内联 base64（那正是本任务要消灭的成本）。
+ */
+class UploadRepository(
+    private val api: UploadApi,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO,
+) {
+
+    /**
+     * 上传一张**已重编码**的图片，返回可作 `chat.image` 的绝对 URL。
+     *
+     * [bytes] 与 [mime] 必须来自同一次编码（`ChatImagePreparer` 的产物）：
+     * 服务端按**字节嗅探**判类型，声明的 `Content-Type` 只作参考，两者不一致时以字节为准。
+     */
+    suspend fun uploadImage(bytes: ByteArray, mime: String): Result<UploadedImage> =
+        withContext(dispatcher) {
+            apiCall { api.upload(partOf(bytes, mime)) }.fold(
+                onSuccess = { data ->
+                    val url = absoluteHttpUrl(data.url)
+                    if (url == null) {
+                        Result.failure(CyreneException(CyreneError.Local(CyreneError.LocalKind.Parse)))
+                    } else {
+                        Result.success(
+                            UploadedImage(url = url, size = data.size, mime = data.mime, name = data.name),
+                        )
+                    }
+                },
+                onFailure = { Result.failure(it) },
+            )
+        }
+
+    /**
+     * multipart 部件。
+     *
+     * **部件名固定 `file`**（服务端 `FormFile("file")`）。文件名也**必须给**：Go 的
+     * `mime/multipart` 只把带 `filename` 参数的部件当**文件**，不带的会落进普通表单值、
+     * 于是 `FormFile` 找不到它。扩展名与服务端白名单一致（服务端丢弃原始名，这里只是让
+     * 线上的部件看起来像一张真图，中间件不会因为怪名字做多余判断）。
+     */
+    private fun partOf(bytes: ByteArray, mime: String): MultipartBody.Part =
+        MultipartBody.Part.createFormData(
+            name = UPLOAD_FIELD_NAME,
+            filename = fileNameFor(mime),
+            body = bytes.toRequestBody(mime.toMediaTypeOrNull()),
+        )
+
+    private fun fileNameFor(mime: String): String = "upload." + when (mime) {
+        MIME_PNG -> "png"
+        MIME_GIF -> "gif"
+        MIME_WEBP -> "webp"
+        MIME_BMP -> "bmp"
+        else -> "jpg"
+    }
+
+    /** 只认绝对 http(s) 地址，且**大小写敏感**（与服务端 `ParseImageRef` 的判据同一口径：放宽只会放行服务端不认的东西）。 */
+    private fun absoluteHttpUrl(raw: String): String? = raw.trim()
+        .takeIf { it.startsWith("http://") || it.startsWith("https://") }
+}
+
+private const val UPLOAD_FIELD_NAME = "file"
+
+private const val MIME_PNG = "image/png"
+private const val MIME_GIF = "image/gif"
+private const val MIME_WEBP = "image/webp"
+private const val MIME_BMP = "image/bmp"

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

@@ -0,0 +1,51 @@
+package top.yeij.cyrene.domain.chat
+
+/** 一张**已重编码**的图片该怎么送上去。 */
+enum class ImageDelivery {
+    /** 直接把 `data:` URI 塞进 `chat.image`：一次请求，但字节永久留在历史里。 */
+    Inline,
+
+    /** 先 `POST /api/v1/upload` 换 URL，再把 URL 当 `chat.image`：多一次往返，历史里只留几十字节。 */
+    Upload,
+}
+
+/**
+ * 内联（base64）与上传（URL）的分界（纯函数，VM 与测试共用）。
+ *
+ * ## 这是一笔什么账
+ * 服务端把 `chat.image` 字符串**原样落库**，所以两边的成本不是「发一次」而是「发多少次」：
+ *
+ * | | 发出时 | 之后每一次历史取数 |
+ * |---|---|---|
+ * | 内联 | 请求体里带 base64（4/3 × B 字符） | **再带一遍**（REST 每页、WS `history` 每次回放、每次上拉） |
+ * | 上传 | 多**一次** HTTP 往返；字节同样只传一遍 | 只剩那个 URL（几十字节） |
+ *
+ * 也就是说：上传不是「省一次流量」，是**用一次往返买断此后所有的历史重量**。
+ *
+ * ## 阈值：64 KiB（[INLINE_MAX_BYTES]，含等于）
+ * 重编码后的字节数 `B`，内联的代价是每次历史取数再多 `4/3 × B`：
+ * - `B = 64 KiB` → 每次取数 +85 KB。一个会话里 20 张这种图，每次冷启动 / 重连回放就要多传
+ *   ≥1.7 MB（1 Mbps 下约 14 秒纯图片流量），而那次上传往返在局域网是毫秒、在移动网也就是
+ *   一两百毫秒——**从第二次取数起就稳赚**。
+ * - `B ≈ 32 KiB`（缩略图、小截图）→ 每次取数 +43 KB，省下的量与一次往返本身的量级相当，
+ *   而多出来的一次请求**必然**多一个失败面（上传失败就得让用户重发，内联不会）。
+ *   这种量级下「一次请求发完」更划算，所以留在内联。
+ *
+ * 阈值取整到 64 KiB 而不是更细的数，是因为它本来就是个成本量级的判断，不是服务端限制：
+ * 服务端的两个 5 MiB 上限（`chat.image` 与 `/upload`）离这里都还差两个数量级，
+ * **本决策与「装不装得下」无关**（重编码出口已保证 ≤ [ChatImageBudget.MAX_DECODED_BYTES]）。
+ */
+object ChatImageDelivery {
+
+    /**
+     * 内联与上传的分界：**重编码后**的字节数（含等于 → 内联）。
+     *
+     * 必须严格小于 [ChatImageBudget.MAX_DECODED_BYTES]，否则上传分支永远走不到（死代码）；
+     * 这一条由 `ChatImageDeliveryTest` 钉住。
+     */
+    const val INLINE_MAX_BYTES = 64 * 1024
+
+    /** @param preparedBytes [top.yeij.cyrene.data.image.ChatImagePreparer] 产出的字节数。 */
+    fun forPreparedBytes(preparedBytes: Int): ImageDelivery =
+        if (preparedBytes <= INLINE_MAX_BYTES) ImageDelivery.Inline else ImageDelivery.Upload
+}

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

@@ -11,10 +11,12 @@ import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import top.yeij.cyrene.app.AppContainer
+import top.yeij.cyrene.core.error.CyreneError
 import top.yeij.cyrene.data.api.CyreneException
 import top.yeij.cyrene.data.api.dto.ChatRequest
 import top.yeij.cyrene.data.api.dto.HistoryMessageDto
 import top.yeij.cyrene.data.image.ChatImagePreparer
+import top.yeij.cyrene.data.image.PreparedImage
 import top.yeij.cyrene.data.repository.ChatAck
 import top.yeij.cyrene.data.repository.MessageRepository
 import top.yeij.cyrene.data.repository.historyForSession
@@ -23,7 +25,9 @@ import top.yeij.cyrene.data.ws.ChatSocket
 import top.yeij.cyrene.data.ws.WsEvent
 import top.yeij.cyrene.data.ws.WsState
 import top.yeij.cyrene.data.ws.isForSession
+import top.yeij.cyrene.domain.chat.ChatImageDelivery
 import top.yeij.cyrene.domain.chat.ChatSendRouting
+import top.yeij.cyrene.domain.chat.ImageDelivery
 import top.yeij.cyrene.domain.chat.SendChannel
 import top.yeij.cyrene.domain.parse.ParsedBubble
 import top.yeij.cyrene.domain.parse.StreamingContentParser
@@ -219,6 +223,9 @@ data class ChatUiState(
  *
  * 上行两条通道（路由见 [ChatSendRouting]）：短文本走 WS `chat` 帧，长文本 / 任何图片走
  * REST `POST /api/v1/chat`（`stream:true`）——**收都在 WS 上**，所以两种发的体验一致。
+ * 图片在 REST 之前还多一层选择：小图内联成 `data:` URI，大图先 `POST /api/v1/upload`
+ * 换 URL 再发（见 [deliverImage]）——服务端把 `image` **原样落库**，内联的字节会在每一页
+ * 历史与每一次 `history` 回放里重传，上传是唯一能把这个成本买断的手段。
  *
  * 本 VM 只收**属于 [sessionId] 的帧**（见 [onEvent] 的会话闸）。服务端广播不按会话订阅，
  * 且每个会话各有一个 VM（各自的 socket 都还活着），没有这道闸就会串台。
@@ -287,7 +294,9 @@ class ChatViewModel(
      * 回来**（同一个编排器 + 广播路径），所以「REST 发、WS 收」不牺牲流式体验。
      *
      * 图片先在本端解码 / 缩放 / 重编码（[ChatImagePreparer]），这一步是重活，放在 IO 线程上；
-     * 气泡同步上屏，所以等待期间用户已经能看到它。
+     * 气泡同步上屏，所以等待期间用户已经能看到它。重编码之后再按体积决定**内联还是上传**
+     * （见 [deliverImage] 与 [ChatImageDelivery]）——大图宁可多走一次 `POST /api/v1/upload`，
+     * 也不把几 MB base64 永久留在每一页历史里。
      */
     fun send() {
         val snapshot = _state.value
@@ -324,7 +333,30 @@ class ChatViewModel(
                 if (!sent) rollback(localId, "发送失败，请重试")
             }
 
-            SendChannel.Rest -> sendViaRest(localId, text, image)
+            SendChannel.Rest -> if (image == null) {
+                sendViaRest(localId, text, image = null)
+            } else {
+                deliverImage(localId, text, image)
+            }
+        }
+    }
+
+    /**
+     * 一张图怎么送上去：小图内联成 `data:` URI，大图先上传、再把返回的 URL 当 `image`
+     * （阈值与这笔成本账见 [ChatImageDelivery]）。两者都走 REST `stream:true`，收都在 WS 上。
+     *
+     * **上传失败不回退内联**：回退等于把「省历史重量」这件事当场作废——用户以为发的是 URL、
+     * 落库的却是几 MB base64，而且是在他看不见的情况下换了一条语义不同的路。这里与
+     * [ChatImagePreparer] 同一纪律：宁可回滚、把图和文本还给输入框让用户重试。
+     */
+    private suspend fun deliverImage(localId: String, text: String, image: PreparedImage) {
+        when (ChatImageDelivery.forPreparedBytes(image.bytes.size)) {
+            ImageDelivery.Inline -> sendViaRest(localId, text, image.dataUri)
+
+            ImageDelivery.Upload -> container.uploadRepository
+                .uploadImage(image.bytes, image.mime)
+                .onSuccess { uploaded -> sendViaRest(localId, text, uploaded.url) }
+                .onFailure { e -> rollback(localId, uploadFailureMessage(e)) }
         }
     }
 
@@ -667,5 +699,24 @@ class ChatViewModel(
 private fun Throwable.userMessage(): String =
     (this as? CyreneException)?.error?.userMessage ?: "加载失败，请稍后重试"
 
+/**
+ * 上传失败的文案（纯函数，可单测）。
+ *
+ * 前两条是服务端的**机器可读**拒绝码（对着在线后端实测过，见 `UploadDtoRealPayloadTest`）：
+ * 在本端预算下它们不该出现（重编码出口 ≤ 1 MiB，类型非 png 即 jpeg，都在白名单里），
+ * 但真出现时正确的动作是「换一张图」而不是「重试」，文案必须把这两者分开。
+ *
+ * 其余（网络 / 超时 / 5xx）用既有错误口径，并**点明是上传这一步**失败——否则用户看到
+ * 「无法连接到服务器」会以为整条消息没发出去，而实际上文字也是跟着一起回滚的。
+ */
+fun uploadFailureMessage(e: Throwable): String {
+    val error = (e as? CyreneException)?.error
+    return when ((error as? CyreneError.Server)?.code) {
+        "payload_too_large" -> "图片超过服务端 5 MB 上限，请换一张更小的"
+        "unsupported_media_type" -> "服务端不接受这张图片的格式，请换一张"
+        else -> "图片上传失败，" + (error?.userMessage ?: "请重试")
+    }
+}
+
 /** 思维链在流式结束后继续保留的时长。 */
 private const val THINKING_LINGER_MILLIS = 10 * 60 * 1000L