dsh-remote-bridge 2.8.0 → 2.8.1

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.8.0
+  version: 2.8.1
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1
@@ -24,7 +24,7 @@ paths:
                 properties:
                   ok: { type: boolean, const: true }
                   version: { type: string, const: v1 }
-                  pluginVersion: { type: string, const: 2.8.0 }
+                  pluginVersion: { type: string, const: 2.8.1 }
   /debug/host-services:
     get:
       operationId: hostServices

package/kotlin-sdk/src/main/kotlin/ai/deepseek/dsh/workspace/MobileGatewayClient.kt

@@ -0,0 +1,437 @@
+package ai.deepseek.dsh.workspace
+
+import java.io.Closeable
+import java.util.Base64
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.Executors
+import java.util.concurrent.ScheduledFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicLong
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import kotlinx.serialization.json.put
+import okhttp3.HttpUrl
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import okhttp3.WebSocket
+import okhttp3.WebSocketListener
+
+/** `/ws/mobile` 的子协议名。握手时**必须**排在子协议列表第一位，服务端据此判断协议版本。 */
+const val MOBILE_PROTOCOL: String = "dsh-mobile-v1"
+
+/** hello 里宣告的协议修订号。与会话快照/问答审批的 `question-approval-v2` 是两码事。 */
+const val MOBILE_HELLO_PROTOCOL: Int = 3
+
+/** 服务端主动断开时用的 close code。4001 = 鉴权/配对失败或设备已被吊销，**重连无意义**。 */
+const val MOBILE_CLOSE_AUTH_FAILED: Int = 4001
+
+/**
+ * `/ws/mobile` 的凭证载体。三种二选一，与服务端 `onConnection` 的判定顺序一致：
+ * 1. [Pairing] → 子协议 `dsh-pair.<code>`，**必须**带 `X-DSH-Device-ID`；
+ * 2. [Token] → 子协议 `dsh-auth.<token>`（推荐，浏览器/受控环境下不必自定义头）；
+ * 3. [Bearer] → 子协议只留 `dsh-mobile-v1`，token 走 `Authorization: Bearer`。
+ *
+ * 刻意**没有** `?token=` 变体：服务端见到 URL query 里的 token/code 会直接 `close(4001)`，
+ * 因为它会漏进代理日志。别在这里补一个方便的后门。
+ */
+sealed class MobileCredentials {
+    /** 首配：一次性配对码 + 设备标识。配对成功后服务端会先推 `paired` 再推 `hello`。 */
+    data class Pairing(
+        val code: String,
+        val deviceId: String,
+        val deviceName: String? = null,
+    ) : MobileCredentials()
+
+    /** 已配对设备：把配对拿到的 token 放进子协议。 */
+    data class Token(val token: String) : MobileCredentials()
+
+    /** 已配对设备：token 放 Authorization 头，子协议只保留 `dsh-mobile-v1`。 */
+    data class Bearer(val token: String) : MobileCredentials()
+}
+
+/** hello 帧里的设备视图。回环管理员连接没有这一节（服务端会整段省略，而不是给 null）。 */
+@Serializable
+data class MobileDevice(
+    val id: String,
+    val name: String,
+    val scopes: List<String> = emptyList(),
+    val rootIds: List<String> = emptyList(),
+)
+
+/** 连接建立后服务端推的第一帧。`protocol` 必须等于 [MOBILE_HELLO_PROTOCOL]。 */
+@Serializable
+data class MobileHello(
+    val protocol: Int,
+    val capabilities: List<String> = emptyList(),
+    val authenticated: Boolean = false,
+    val device: MobileDevice? = null,
+    val port: Int? = null,
+    val clients: Int? = null,
+)
+
+/** 配对成功的凭证下发帧，只会在 `MobileCredentials.Pairing` 流程里出现，且**早于** hello。 */
+@Serializable
+data class MobilePaired(val token: String, val device: MobileDevice)
+
+/**
+ * 服务端 `error` 帧。`code` 是稳定契约（`UNKNOWN_TYPE` / `NOT_IMPLEMENTED` / `MISSING_PARAMS` /
+ * `FORBIDDEN_SCOPE` / `bad-request` …），`message` 是给人看的，可能变。
+ */
+class MobileGatewayException(
+    val code: String,
+    override val message: String,
+    val requestType: String? = null,
+    val requestId: String? = null,
+    val statusCode: Int? = null,
+) : RuntimeException(message)
+
+/** 请求发出去了但等不到回帧。多半是服务端不认识这个 type，或帧被背压队列丢了。 */
+class MobileRequestTimeoutException(val requestId: String, val type: String, val timeoutMs: Long) :
+    RuntimeException("$type (requestId=$requestId) 在 ${timeoutMs}ms 内没有回帧")
+
+/** 连接没等到 hello 就断了，或 hello 的 protocol 不匹配。 */
+class MobileHandshakeException(message: String) : RuntimeException(message)
+
+/**
+ * `/ws/mobile` 的一帧响应。`kind` 是 `MobileServerFrame.kind` 的成员之一；
+ * `requestId` 是从 `data` 里提出来的一等字段，方便直接关联。
+ */
+data class MobileFrame(val kind: String, val data: JsonElement) {
+    val requestId: String? = (data as? JsonObject)?.get("requestId")?.let {
+        (it as? JsonPrimitive)?.takeIf { p -> p.isString }?.content
+    }
+}
+
+/**
+ * `/ws/mobile` 的帧回调。全部方法都有默认空实现，调用方只覆盖关心的那几个。
+ *
+ * 回调都在 OkHttp 的读线程上跑，**不要**在里面做阻塞的 [MobileGatewayClient.request]：
+ * 那条路径要等读线程派发回帧，会自己把自己锁死。需要请求-响应就用 [MobileGatewayClient.request]，
+ * 它内部走的是独立的等待者，但仍建议在调用方线程里用。
+ */
+interface MobileGatewayListener {
+    /** 每条非 `event` 帧。hello/paired 已单独派发，这里不再重复。 */
+    fun onFrame(frame: MobileFrame) {}
+
+    /** `{kind:'event', data:{...}}`。事件本身带 `type`（如 `chat.message.delta`）。 */
+    fun onEvent(event: JsonElement) {}
+
+    /** 首帧 hello。`protocol != 3` 时先调这个，再走 [onPermanentFailure]。 */
+    fun onHello(hello: MobileHello) {}
+
+    /** 配对成功，拿到长期 token。只有配对流程会触发。 */
+    fun onPaired(paired: MobilePaired) {}
+
+    /** `ping` 的回帧。`at` 与 `time` 是同一毫秒（服务端刻意如此）。 */
+    fun onPong(at: Long, time: Long) {}
+
+    fun onConnectionChanged(connected: Boolean) {}
+
+    /** 重连没意义的失败（4001、hello 协议不匹配、配对码失效）。 */
+    fun onPermanentFailure(error: Throwable) {}
+}
+
+/**
+ * `/ws/mobile` 移动端网关客户端。
+ *
+ * 与 [DshWorkspaceClient] 的分工：REST 客户端覆盖「一次请求一次响应」的能力面，
+ * 本类覆盖长连接面 —— hello/能力协商、`event` 推送、HITL 交互、分块传输、
+ * 以及靠 `requestId` 关联的异步请求-响应。服务端是 WS 优先、REST 兜底，
+ * 所以**同一个能力两处都有**时优先走本类；本类没有的能力再回落到 REST。
+ *
+ * 用法：
+ * ```
+ * val client = MobileGatewayClient("ws://127.0.0.1:3090", MobileCredentials.Token(token)) { frame -> ... }
+ * val hello = client.awaitHello()
+ * client.subscribe(sessionId)
+ * client.request("session-stats", mapOf("sessionId" to sessionId))
+ * ```
+ *
+ * 线程模型：所有写都在 OkHttp 的 WebSocket 队列里串行；[request] 的等待者在调用方线程阻塞，
+ * 回帧由读线程按 `requestId` 唤醒。回调见 [MobileGatewayListener] 的线程说明。
+ */
+class MobileGatewayClient(
+    wsBaseUrl: String,
+    private val credentials: MobileCredentials,
+    private val http: OkHttpClient = OkHttpClient(),
+    private val listener: MobileGatewayListener = object : MobileGatewayListener {},
+) : Closeable {
+    private val json = Json { ignoreUnknownKeys = true }
+    private val url: HttpUrl = buildUrl(wsBaseUrl)
+    private val closed = AtomicBoolean(false)
+    private val scheduler = Executors.newSingleThreadScheduledExecutor()
+    private val pending = ConcurrentHashMap<String, CompletableFuture<MobileFrame>>()
+    private val requestSeq = AtomicLong(0)
+    private val helloFuture = CompletableFuture<MobileHello>()
+
+    @Volatile private var socket: WebSocket? = null
+    @Volatile private var retry: ScheduledFuture<*>? = null
+    @Volatile private var attempts = 0
+
+    /** 已收到的 hello；握手完成前为 null。 */
+    @Volatile
+    var hello: MobileHello? = null
+        private set
+
+    /** 配对流程拿到的 token；非配对流程恒为 null。 */
+    @Volatile
+    var pairedToken: String? = null
+        private set
+
+    init { connect() }
+
+    // ── 握手 ─────────────────────────────────────────────────────────────────
+
+    /**
+     * 把 `ws://host:port` 或 `http(s)://host:port` 归一成 `ws(s)://host:port/ws/mobile`。
+     * 传完整路径也接受（幂等），省得调用方两处拼路径拼出 `/ws/mobile/ws/mobile`。
+     */
+    private fun buildUrl(base: String): HttpUrl {
+        val normalized = when {
+            base.startsWith("ws://") -> "http://" + base.removePrefix("ws://")
+            base.startsWith("wss://") -> "https://" + base.removePrefix("wss://")
+            else -> base
+        }
+        val parsed = normalized.trimEnd('/').toHttpUrl()
+        if (parsed.encodedPath.endsWith("/ws/mobile")) return parsed
+        return parsed.newBuilder().addPathSegment("ws").addPathSegment("mobile").build()
+    }
+
+    /** 子协议列表：`dsh-mobile-v1` 永远第一位，凭证前缀紧随其后。 */
+    private fun subprotocols(): String = when (credentials) {
+        is MobileCredentials.Pairing -> "$MOBILE_PROTOCOL, dsh-pair.${credentials.code}"
+        is MobileCredentials.Token -> "$MOBILE_PROTOCOL, dsh-auth.${credentials.token}"
+        is MobileCredentials.Bearer -> MOBILE_PROTOCOL
+    }
+
+    private fun requestBuilder(): Request.Builder {
+        val builder = Request.Builder().url(url).header("Sec-WebSocket-Protocol", subprotocols())
+        when (credentials) {
+            is MobileCredentials.Pairing -> {
+                builder.header("X-DSH-Device-ID", credentials.deviceId)
+                // 设备名走 Base64(UTF-8)：HTTP 头只保证 ISO-8859-1，中文名直传会被截断。
+                credentials.deviceName?.takeIf { it.isNotBlank() }?.let {
+                    builder.header("X-DSH-Device-Name", Base64.getEncoder().encodeToString(it.toByteArray(Charsets.UTF_8)))
+                }
+            }
+            is MobileCredentials.Bearer -> builder.header("Authorization", "Bearer ${credentials.token}")
+            is MobileCredentials.Token -> Unit
+        }
+        return builder
+    }
+
+    private fun connect() {
+        if (closed.get()) return
+        socket = http.newWebSocket(requestBuilder().build(), object : WebSocketListener() {
+            override fun onOpen(webSocket: WebSocket, response: Response) {
+                attempts = 0
+                listener.onConnectionChanged(true)
+            }
+
+            override fun onMessage(webSocket: WebSocket, text: String) {
+                // 单帧解析失败不该掀桌子：服务端可能先于客户端升级而多发了一种帧。
+                runCatching { dispatch(text) }.onFailure(listener::onPermanentFailure)
+            }
+
+            override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                failPending(MobileHandshakeException("连接关闭：$code $reason"))
+                listener.onConnectionChanged(false)
+                when (code) {
+                    // 4001 覆盖「配对码无效/过期、设备 ID 缺失、token 被吊销」。
+                    // 重连只会刷出一串同样的 4001，所以直接判永久失败。
+                    MOBILE_CLOSE_AUTH_FAILED -> {
+                        val error = IllegalStateException("移动网关拒绝了凭证（$reason），需要重新配对或换 token。")
+                        helloFuture.completeExceptionally(error)
+                        listener.onPermanentFailure(error)
+                    }
+                    else -> reconnect()
+                }
+            }
+
+            override fun onFailure(webSocket: WebSocket, error: Throwable, response: Response?) {
+                failPending(error)
+                listener.onConnectionChanged(false)
+                // 429 = 连接数打满（上限 32，鉴权后才计数）。等一会儿再试是合理的，别当永久失败。
+                if (response?.code == 401 || response?.code == 403) {
+                    helloFuture.completeExceptionally(error)
+                    listener.onPermanentFailure(error)
+                } else {
+                    reconnect()
+                }
+            }
+        })
+    }
+
+    /**
+     * 指数退避重连：1s,2s,4s,8s,16s，封顶 30s。与 [EventSubscription] 同一套参数，
+     * 免得同一个 App 里两条长连接节奏不一样、把服务端 32 个槽位一起打满。
+     */
+    private fun reconnect() {
+        if (closed.get()) return
+        val delaySeconds = minOf(30L, 1L shl minOf(attempts++, 5))
+        retry?.cancel(false)
+        retry = scheduler.schedule(::connect, delaySeconds, TimeUnit.SECONDS)
+    }
+
+    private fun dispatch(text: String) {
+        val envelope = json.parseToJsonElement(text).jsonObject
+        val kind = envelope["kind"]?.jsonPrimitive?.contentOrNullSafe()
+            ?: throw MobileHandshakeException("服务端帧缺少 kind：${text.take(200)}")
+        val data = envelope["data"] ?: JsonObject(emptyMap())
+        val frame = MobileFrame(kind, data)
+
+        when (kind) {
+            "hello" -> {
+                val parsed = json.decodeFromJsonElement(MobileHello.serializer(), data)
+                hello = parsed
+                listener.onHello(parsed)
+                if (parsed.protocol != MOBILE_HELLO_PROTOCOL) {
+                    // 协议不匹配时**不要**继续用这条连接发帧：字段语义已经不可信了。
+                    val error = MobileHandshakeException(
+                        "移动网关协议是 ${parsed.protocol}，本 SDK 只支持 $MOBILE_HELLO_PROTOCOL。",
+                    )
+                    helloFuture.completeExceptionally(error)
+                    listener.onPermanentFailure(error)
+                    close()
+                    return
+                }
+                helloFuture.complete(parsed)
+            }
+            "paired" -> {
+                val parsed = json.decodeFromJsonElement(MobilePaired.serializer(), data)
+                pairedToken = parsed.token
+                listener.onPaired(parsed)
+            }
+            "pong" -> {
+                val at = (data as? JsonObject)?.get("at")?.jsonPrimitive?.contentOrNullSafe()?.toLongOrNull() ?: 0L
+                val time = (data as? JsonObject)?.get("time")?.jsonPrimitive?.contentOrNullSafe()?.toLongOrNull() ?: at
+                listener.onPong(at, time)
+            }
+            "event" -> listener.onEvent(data)
+            else -> listener.onFrame(frame)
+        }
+        // requestId 关联放在最后：即使上面某个分支已经派发过回调，等待者也必须被唤醒。
+        frame.requestId?.let { id -> pending.remove(id)?.complete(frame) }
+    }
+
+    /** 非字符串 primitive（数字/布尔）的 `content` 本身就是字面量文本，取它即可。 */
+    private fun JsonPrimitive.contentOrNullSafe(): String = content
+
+    // ── 请求-响应 ────────────────────────────────────────────────────────────
+
+    /**
+     * 发一帧并等它的回帧，靠 `requestId` 关联。
+     *
+     * 关联约定（与服务端一致，见 asyncapi 的 `/ws/mobile` 描述）：
+     * - `requestId` 是不透明字符串，服务端**原样回显**，客户端只管比对；
+     * - 服务端在没有 requestId 时**整段省略**这个键，不会回 `null` 或空串；
+     * - `file-resolve` / `file-download-open` / `file-upload-open` 三帧的 requestId 是**必填**，
+     *   缺了服务端回 `bad-request`；
+     * - 关联是**每连接**作用域，不同连接可以用同一个 requestId。
+     *
+     * @throws MobileGatewayException 服务端回 `error` 帧（`UNKNOWN_TYPE` / `MISSING_PARAMS` 等）。
+     * @throws MobileRequestTimeoutException 超时。
+     */
+    fun request(
+        type: String,
+        payload: Map<String, JsonElement> = emptyMap(),
+        requestId: String = "req-${requestSeq.incrementAndGet()}",
+        timeoutMs: Long = 30_000,
+    ): MobileFrame {
+        val future = CompletableFuture<MobileFrame>()
+        pending[requestId] = future
+        val frame = buildJsonObject {
+            put("type", type)
+            put("requestId", requestId)
+            payload.forEach { (key, value) -> put(key, value) }
+        }
+        return try {
+            sendRaw(frame)
+            val reply = future.get(timeoutMs, TimeUnit.MILLISECONDS)
+            if (reply.kind == "error") throw toException(reply, type)
+            reply
+        } catch (timeout: java.util.concurrent.TimeoutException) {
+            throw MobileRequestTimeoutException(requestId, type, timeoutMs)
+        } catch (failure: java.util.concurrent.ExecutionException) {
+            // failPending 会把连接错误包成 ExecutionException；还原成真实原因才好定位。
+            throw (failure.cause as? RuntimeException) ?: IllegalStateException("请求失败：$type", failure.cause)
+        } finally {
+            pending.remove(requestId)
+        }
+    }
+
+    /** 发一帧不等回帧（`message`、`subscribe`、`approval-response` 这类）。 */
+    fun send(frame: JsonObject) {
+        sendRaw(frame)
+    }
+
+    /** 便捷封装：`{type:'ping'}`。回帧走 [MobileGatewayListener.onPong]。 */
+    fun ping() {
+        sendRaw(buildJsonObject { put("type", "ping") })
+    }
+
+    /** 订阅单个会话的事件流。服务端会顺带回放该会话未决的审批/提问（带 `replayed:true`）。 */
+    fun subscribe(sessionId: String) {
+        sendRaw(buildJsonObject { put("type", "subscribe"); put("sessionId", sessionId) })
+    }
+
+    /** 取消订阅。之后事件流不再按会话过滤，回到全量。 */
+    fun unsubscribe() {
+        sendRaw(buildJsonObject { put("type", "unsubscribe") })
+    }
+
+    private fun sendRaw(frame: JsonObject) {
+        val target = socket ?: throw IllegalStateException("移动网关连接尚未建立。")
+        if (!target.send(json.encodeToString(JsonObject.serializer(), frame))) {
+            // send 返回 false 说明写队列已满/连接已关，帧根本没出去。静默丢帧比抛错更难查。
+            throw IllegalStateException("帧没有进入发送队列（连接已关闭或写缓冲已满）：$frame")
+        }
+    }
+
+    private fun toException(reply: MobileFrame, type: String): MobileGatewayException {
+        val data = reply.data as? JsonObject
+        val code = data?.get("code")?.jsonPrimitive?.contentOrNullSafe() ?: "UNKNOWN"
+        val message = data?.get("message")?.jsonPrimitive?.contentOrNullSafe() ?: code
+        return MobileGatewayException(
+            code = code,
+            message = message,
+            requestType = data?.get("requestType")?.jsonPrimitive?.contentOrNullSafe() ?: type,
+            requestId = reply.requestId,
+            statusCode = data?.get("statusCode")?.jsonPrimitive?.contentOrNullSafe()?.toIntOrNull(),
+        )
+    }
+
+    private fun failPending(error: Throwable) {
+        pending.values.forEach { it.completeExceptionally(error) }
+        pending.clear()
+    }
+
+    // ── 生命周期 ─────────────────────────────────────────────────────────────
+
+    /** 等 hello。握手失败（4001、协议不匹配、连接建立不起来）会抛异常而不是干等。 */
+    fun awaitHello(timeoutMs: Long = 15_000): MobileHello = try {
+        helloFuture.get(timeoutMs, TimeUnit.MILLISECONDS)
+    } catch (timeout: java.util.concurrent.TimeoutException) {
+        throw MobileHandshakeException("${timeoutMs}ms 内没有收到 hello")
+    } catch (failure: java.util.concurrent.ExecutionException) {
+        throw (failure.cause as? RuntimeException) ?: MobileHandshakeException("握手失败：${failure.cause?.message}")
+    }
+
+    override fun close() {
+        if (!closed.compareAndSet(false, true)) return
+        retry?.cancel(false)
+        failPending(IllegalStateException("客户端已关闭"))
+        socket?.close(1000, "Client closed")
+        scheduler.shutdownNow()
+    }
+}

package/lib/index.d.ts

@@ -2208,12 +2208,36 @@ interface HostRemoteHandle {
 }
 //#endregion
 //#region src/host/ws-handler.d.ts
+/**
+ * `/ws/mobile` 的可调参数。
+ *
+ * 三个都有默认值，且**必须可注入**：默认值（32 / 30 s / 512）在单测里既等不起
+ * （30 s 的心跳周期）也压不满（512 深度要发五百多帧）。可注入才能把「第 33 条 429」
+ * 「两个周期踢人」「溢出补 resync」这三条**文档承诺的行为**变成可断言的用例。
+ */
+interface MobileGatewayOptions {
+  /** 同时允许的连接数上限，默认 {@link DEFAULT_MOBILE_MAX_CONNECTIONS}。 */
+  maxConnections?: number;
+  /** 心跳周期（毫秒），默认 {@link DEFAULT_MOBILE_HEARTBEAT_INTERVAL_MS}。 */
+  heartbeatIntervalMs?: number;
+  /** 单连接发送队列深度，默认 {@link DEFAULT_MOBILE_QUEUE_LIMIT}。 */
+  queueLimit?: number;
+}
 declare class MobileGatewayWsHandler {
   private readonly database;
   private readonly chat;
   private readonly auth;
   private readonly capabilitiesFlags;
   private readonly sockets;
+  /**
+   * 当前异步上下文里正在处理的那一帧客户端请求的 `requestId`。
+   *
+   * **为什么必须是 AsyncLocalStorage 而不是实例字段/闭包变量**：`webSocket.on('message')`
+   * 里是 `void this.handleMessage(...)`（不 await），同一条连接可以同时有多个请求在途；
+   * 任何「先存起来、发送时再读」的共享槽位都会把并发请求的 id 串到一起。ALS 把上下文
+   * 绑定在**这条 await 链**上，`await` 穿过它、并发分支各持一份，互不可见。
+   */
+  private readonly frameRequestId;
   private settingsService;
   private filesService;
   /**
@@ -2239,7 +2263,15 @@ declare class MobileGatewayWsHandler {
    * typertGateway+connection 后注入；传入 undefined 表示当前内核不提供（优雅降级）。
    */
   attachRemoteServices(remote: HostRemoteHandle | undefined): void;
-  constructor(database: WorkspaceDatabase, chat: DshChatAdapter, auth: AuthService, events: WorkspaceEventBus, capabilitiesFlags: CapabilityFlags);
+  /** 同时允许的连接数上限（鉴权后计数；server.ts 在 Upgrade 前据此回 429）。 */
+  private readonly maxConnections;
+  /** 心跳周期：每周期 ping 一次，连续两个周期没回 pong 就 terminate。 */
+  private readonly heartbeatIntervalMs;
+  /** 单连接发送队列深度（溢出时先丢可重建帧）。 */
+  private readonly queueLimit;
+  /** 心跳定时器（首个连接接入时惰性启动，{@link stop} 时清掉）。 */
+  private heartbeatTimer;
+  constructor(database: WorkspaceDatabase, chat: DshChatAdapter, auth: AuthService, events: WorkspaceEventBus, capabilitiesFlags: CapabilityFlags, options?: MobileGatewayOptions);
   private readonly eventBridge;
   /**
    * 判定这次 upgrade 是否属于 /ws/mobile。server.ts 负责实际的 WebSocket 升级，
@@ -2265,7 +2297,18 @@ declare class MobileGatewayWsHandler {
   private sendHello;
   private stateOf;
   private principalToDeviceView;
+  /**
+   * 收到一条文本帧的入口：解码 → 校验 → **绑定 requestId 上下文** → 分发。
+   *
+   * 这里同时是唯一的异常兜底点。调用方是 `webSocket.on('message')` 里的
+   * `void this.handleMessage(...)`（不 await），任何从这里冒出去的 rejection 都会成为
+   * 进程级 unhandledRejection —— DSH 宿主装了 `installFailLoud`，直接 `proc.exit(1)`。
+   * 而 `handleHistory` 等基础帧是直接 `await this.chat.*`，一次越权的 `sessionId` 就能抛
+   * `ApiError(404, 'SESSION_NOT_FOUND')`。所以分发必须整体包在 try/catch 里。
+   */
   private handleMessage;
+  /** 把一帧已解码、已校验的请求分发给对应的处理器（异常由 {@link handleMessage} 兜底）。 */
+  private routeFrame;
   private handlePing;
   private handleSubscribe;
   private handleUnsubscribe;
@@ -2279,10 +2322,41 @@ declare class MobileGatewayWsHandler {
   private handleSessions;
   private handleHistory;
   private handleAttachment;
-  /** 向一条连接发一条帧（带背压队列）。 */
+  /**
+   * 向一条连接发一条帧（带背压队列）。
+   *
+   * 应答帧统一在这里回显 `requestId`：从 {@link frameRequestId} 取**当前异步上下文**的
+   * requestId，交给 {@link withRequestIdEcho} 决定要不要塞进 `data`。处理器无需再各自
+   * 复制一遍（已手写回显的处理器不受影响 —— 注入规则是「`data` 里已有就不覆盖」）。
+   */
   private sendFrame;
+  /**
+   * 压入发送队列，队列满时**先牺牲可重建的帧**。
+   *
+   * 与 `/api/v1/events`（server.ts 的 `enqueue`）同一套取舍，只是这里没有「可重建事件
+   * 标记表」可用，改用 kind 判据。为什么不能无脑 `shift()` 丢最旧：最旧的那条可能正是
+   * 某次请求的**应答**，丢掉它客户端就会一直等到超时（而它等的那个东西其实早成功了），
+   * 反过来一条 `chat.message.delta` 丢了只影响一句的流式观感，history 一拉就齐。
+   *
+   * 被丢的帧数累加到 `state.dropped`，由 {@link drain} 在排空后补一条
+   * `connection-resync-required` 告知客户端 —— **静默丢帧比丢帧本身更糟**。
+   */
+  private enqueue;
   private sendError;
-  /** 把队列里的帧逐条发出去。 */
+  /**
+   * 把分发过程中冒出来的异常变成一条 `error` 帧（范式与各域处理器的 `reportError` 一致）。
+   *
+   * **这里的 try/catch 不是多余的**：`sendFrame` 第一行就是 `this.stateOf(webSocket)`，而
+   * `teardown` 会在 `close`/`error` 时把连接从 `sockets` 摘掉。连接已断时 `stateOf` 抛
+   * `ApiError(4001, 'NOT_AUTHENTICATED')` —— 在 catch 块里再抛一次，就等于没修。
+   */
+  private reportFrameError;
+  /**
+   * 把队列里的帧逐条发出去，排空后按需补一条「你漏了 N 帧」的告知帧。
+   *
+   * 补发放在**排空之后**而不是溢出当场：溢出那一刻队列正满，插一条进去还得再挤掉别人；
+   * 等排空再补，既不会二次溢出，也能把同一段时间内多次溢出合并成一条（`dropped` 累加）。
+   */
   private drain;
   /** 拒绝未鉴权连接（401 close code）。 */
   private closeUnauthorized;
@@ -2290,6 +2364,29 @@ declare class MobileGatewayWsHandler {
   private closeWithCode;
   /** 关闭所有连接（server.stop 时调用）。 */
   stop(timeoutMs?: number): Promise<void>;
+  /**
+   * 心跳循环：每 `heartbeatIntervalMs` ping 一次，**连续错过两个周期**才 terminate。
+   *
+   * 为什么必须有这一步：`/ws/mobile` 是手机上的长连接，切网、熄屏、NAT 表项过期都会留下
+   * **半开连接** —— 内核这边没有任何事件，TCP 要等自己超时才报错（默认以分钟计），期间
+   * 这条连接一直占着 `sockets` 里的额度、每次广播还白查一遍库。API 文档承诺「连续错过
+   * 2 个心跳周期 terminate」，这里就是把它兑现。
+   *
+   * 两个刻意的取舍：
+   * - `terminate()` 而不是 `close()`：对端已经不在，优雅挥手没人收，只会多等一个超时；
+   *   `close`/`error` 里注册的 `teardown` 会照常摘表、摘事件桥、中止语音与文件传输；
+   * - 存活标记用底层 `pong` 控制帧：客户端库自动回，不需要业务代码配合（业务层的
+   *   `ping` 帧是另一回事，用于测 RTT）。
+   */
+  private startHeartbeat;
+  private clearHeartbeat;
+  /**
+   * 连接数上限（供 server.ts 在 **Upgrade 之前**判定是否回 429）。
+   *
+   * 为什么要在 upgrade 前判：升级之后就只能发 WS 关闭码，`Retry-After` 根本无法表达，
+   * 客户端也拿不到「稍后再试」这个语义（只会看到一次莫名其妙的断连）。
+   */
+  connectionLimit(): number;
   /** 当前连接数（供 metrics / 观测）。 */
   connectionCount(): number;
 }