@mrrisega/dsh-remote 0.6.12 → 0.6.13

package/clients/dsh-remote/dsh-bridge.mjs

@@ -505,6 +505,15 @@ export async function handleFrame(dchOrSend, frame) {
   if (id === undefined || id === null) return;
   const send = toSender(dchOrSend);
   if (type === "http") return handleHttpFrame(send, frame);
+  if (type === "http-abort") {
+    // 手机侧断开了这条流(切页/锁屏):掐掉上游,别在电脑上留一条永不结束的 SSE 连接。
+    const c = streamAborts.get(id);
+    if (c) {
+      streamAborts.delete(id);
+      try { c.abort(); } catch { /* ignore */ }
+    }
+    return;
+  }
   if (type === "ws-open") return handleWsOpen(send, frame);
   if (type === "ws-msg") return handleWsMessage(send, frame);
   if (type === "ws-close") return handleWsClose(send, frame);
@@ -541,7 +550,10 @@ function headerValue(headers, name) {
  * 保守策略:任一条件不满足都返回 null(原样回传):
  *   - 方法非 HEAD、状态非 204/304;
  *   - buf ≥ 1KB(太小不值得压);
- *   - 上游未编码(contentEncoding 为空;undici 已自动解压 body,这里只看原 header);
+ *   - `contentEncoding` 为空 —— ⚠️ 它指的是**手上这份 buf 的编码**,不是上游响应头的值:
+ *     上游头的 "gzip" 在 undici 解压后依然留着(见下),照抄过来只会让我们白丢压缩收益;
+ *     调用方必须传"buf 是否已编码",dsh-bridge 的 doHttp 因此**固定传空串**。
+ *     若哪天 buf 真是一段未解压的字节流,调用方才应把对应编码传进来(函数会保守放弃压缩)。
  *   - 请求 Accept-Encoding 含 gzip(手机浏览器必带;没有就不压,避免手机不会解压);
  *   - content-type 可压缩(排除 text/event-stream);
  *   - gzip 后确实更小(极小文件/不可压数据 gzip 反而更大,保守判断)。
@@ -565,6 +577,97 @@ export async function maybeCompressResponse({ buf, contentType, contentEncoding,
   return { buf: out, headers: { "content-encoding": "gzip" } };
 }
 
+/**
+ * 进行中的 SSE 流:frameId → AbortController。
+ * 手机侧断开时,中继会发 `http-abort`,这里据此掐掉上游(否则电脑上会留一条永不结束的连接)。
+ */
+const streamAborts = new Map();
+
+/**
+ * 中继在 `tunnel-register-ok` 里声明支持的**追加帧能力**。
+ *
+ * 为什么必须协商:browser→中继→bridge 是两段**独立升级**的链路。
+ * 新 bridge 的流式帧(`http-chunk`/`http-end`)对**旧中继**是不认识的 —— 旧中继会把
+ * "仅头部"帧当成一个完整的空响应直接 `end()`,SSE 于是变成"秒断 + 浏览器狂重连",
+ * 比原来的 120 秒挂起**更糟**。所以能力由中继声明:拿不到 `http-stream` 就老实退回
+ * 旧的整包缓冲行为(慢,但正确)。默认空集合 = 保守(连不上/旧中继都不冒险用新帧)。
+ */
+const routerCaps = new Set();
+
+/**
+ * SSE(`text/event-stream`)流式转发。
+ *
+ * 为什么必须流式:`doHttp` 是「整包 `await res.arrayBuffer()`」的语义,而 SSE **永不结束** ——
+ * 实测 DSH 的 `/plugins/events`(client-hmr 的事件通道)每次页面加载都把这条请求挂满
+ * bridge 的 120s 上游超时,然后报错;浏览器 EventSource 立刻重连,于是手机端 Network 里
+ * **永远有一条转圈的请求**,页面也始终拿不到事件。
+ *
+ * 帧协议(对中继**追加**、与既有 `http` 帧并存;不认识 streaming 的旧中继只会忽略后续
+ * chunk,退化成"空 body 后结束",不会把页面打挂):
+ *   ← { id, type:"http",       status, headers, streaming:true }  仅头部,无 body
+ *   ← { id, type:"http-chunk", seq, body, bodyBase64:true }       0..n 次
+ *   ← { id, type:"http-end",   seq }                              流结束(含出错收尾)
+ *   → { id, type:"http-abort" }                                   手机断开 → 掐上游
+ *
+ * ⚠️ E2EE 路径**不**走这里:信封是"一问一答"的结构,SSE 要逐块封/解需要另立协议;
+ *    而现实里 SSE 由 `EventSource` 发出、shim 不接管它(不带头部信封标记),
+ *    所以密文流根本不存在 —— 真要做时再单独设计,不要在这里偷偷降级成明文。
+ *
+ * @returns {Promise<{status:number, chunks:number, bytes:number, aborted?:boolean}>}
+ */
+async function doHttpStream(send, id, method, path, reqHeaders) {
+  const safe = safePath(path);
+  if (safe === null) throw new Error("非法路径");
+  const reqHdrs = sanitizeRequestHeaders(reqHeaders);
+  const ck = harnessCookieOf(); // 新版 dsh web 的浏览器会话 Cookie(否则 401 白页)
+  if (ck) reqHdrs.Cookie = ck;
+  const controller = new AbortController();
+  streamAborts.set(id, controller);
+
+  let res;
+  try {
+    res = await fetch(`${UPSTREAM}${safe}`, { method, headers: reqHdrs, signal: controller.signal });
+  } catch (e) {
+    streamAborts.delete(id);
+    throw e; // 头部都还没发出去 → 交给调用方回一个普通错误帧
+  }
+
+  const status = res.status;
+  // 头部帧:告诉中继"这是一条流",随后才逐块推 body
+  send({
+    id,
+    type: "http",
+    status,
+    headers: sanitizeResponseHeaders(Object.fromEntries(res.headers.entries())),
+    streaming: true
+  });
+
+  let seq = 0;
+  let bytes = 0;
+  try {
+    const reader = res.body && typeof res.body.getReader === "function" ? res.body.getReader() : null;
+    if (reader) {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value || value.length === 0) continue;
+        bytes += value.length;
+        send({ id, type: "http-chunk", seq: ++seq, body: Buffer.from(value).toString("base64"), bodyBase64: true });
+      }
+    }
+  } catch (e) {
+    // 头部已经发出去了:这里**绝不能**抛(调用方会用普通帧回 502,而中继那边响应头已定,
+    // 再写一次 head 会炸)。统一以 http-end 收尾,让 EventSource 按自己的节奏重连。
+    const aborted = controller.signal.aborted === true;
+    streamAborts.delete(id);
+    send({ id, type: "http-end", seq, ...(aborted ? { aborted: true } : { error: String(e?.message || e) }) });
+    return { status, chunks: seq, bytes, aborted };
+  }
+  streamAborts.delete(id);
+  send({ id, type: "http-end", seq });
+  return { status, chunks: seq, bytes };
+}
+
 async function doHttp(method, path, reqHeaders, body, isB64) {
   const safe = safePath(path);
   if (safe === null) throw new Error("非法路径");
@@ -624,7 +727,14 @@ async function doHttp(method, path, reqHeaders, body, isB64) {
   const compressed = await maybeCompressResponse({
     buf,
     contentType,
-    contentEncoding: res.headers.get("content-encoding") || "",
+    // 🔴 必须传空:这里的 `buf` 是 **undici 已经解压过**的明文,不是上游线速字节。
+    //    以前传的是 `res.headers.get("content-encoding")` —— 而 undici 解压之后**仍会把该头留着**
+    //    (本文件 sanitizeResponseHeaders 的注释正是这么写的:"undici 已自动解压 body,
+    //     content-encoding/length 会误导浏览器")。于是 maybeCompressResponse 看到 "gzip"
+    //    就保守地 `return null`,**永不重压** —— 实测代价:线上 dsh web 的 `/plugins/??`
+    //    聚合包本来 gzip 后 5.12MB,被原样发出 13.39MB(2.6×),免费档 1Mbps 下从 40 秒变成 100+ 秒。
+    //    传空之后语义才是自洽的:"我手上这份 buf 是未编码的明文,可以压"。
+    contentEncoding: "",
     acceptEncoding: headerValue(reqHeaders, "accept-encoding"),
     status: res.status,
     method
@@ -693,6 +803,13 @@ export async function handleHttpFrame(dchOrSend, frame) {
     }
   }
   try {
+    // SSE 必须流式转发(否则会挂满 120s 超时,见 doHttpStream 注释)。
+    // 客户端是 EventSource 时必带 Accept: text/event-stream,以此为准(不看路径白名单,免得漏)。
+    if (routerCaps.has("http-stream") && String(headerValue(headers, "accept") || "").includes("text/event-stream")) {
+      const s = await doHttpStream(send, id, method, path, headers);
+      console.log(`[bridge] ${method} ${path} → SSE ${s.status} (${Date.now() - t0}ms, ${s.chunks} 块 / ${(s.bytes / 1024).toFixed(1)}KB${s.aborted ? ", 手机已断开" : ""})`);
+      return;
+    }
     const reply = await doHttp(method, path, headers, body, !!isB64);
     reply.id = id;
     reply.type = "http";
@@ -1157,6 +1274,9 @@ function connectTunnel(token) {
     try {
       receive(raw, (frame) => {
         if (frame?.type === "tunnel-register-ok") {
+          // 记下中继声明的追加帧能力(旧中继不带 caps → 空集合 → 退回整包缓冲,见 routerCaps 注释)
+          routerCaps.clear();
+          for (const c of Array.isArray(frame.caps) ? frame.caps : []) routerCaps.add(String(c));
           // 中继注册成功 = 手机端此刻真的能进这台电脑:面板据此把阶段推进到 online(已连接 ✅)
           persistBridgeState({ device_id: DEVICE_ID, tunnel_registered_at: Date.now(), phase: "online", last_error: null });
           console.log(`[bridge] ✅ router 注册成功: ${DEVICE_ID},等待手机访问 /remote/${DEVICE_ID}/`);
@@ -1172,6 +1292,7 @@ function connectTunnel(token) {
     } catch (e) { console.log(`[bridge] 隧道帧错误: ${e.message}`); }
   });
   ws.on("close", (code, reason) => {
+    routerCaps.clear(); // 换中继/断线:能力重新协商,期间一律退回保守行为
     clearInterval(heartbeat);
     console.log(`[bridge] 隧道断开(code=${code}${reason ? ", " + reason : ""})`);
     closeAllWsSessions();

package/clients/dsh-remote/mobile-adapter.mjs

@@ -1096,6 +1096,36 @@ const SCRIPT = `(() => {
       } catch (e8) { /* 引导条失败绝不能影响主功能 */ }
     };
 
+    /* 适配层自己创建的「抽屉入口」引用(汉堡按钮 / 遮罩),提到 boot() 外层保存。
+       为什么必须提到外层:官方 SPA 重渲染时会整片替换 body 子树,把这两个节点一起冲掉;
+       留住引用才能在下面的「存在性看门狗」里把**同一个节点**补回去(节点不变 → 挂在它上面的
+       click 处理、CSS 类、aria 属性全都原样保留,不会出现"补回来点不动"的假按钮)。 */
+    let maHamburger = null, maScrim = null;
+
+    /* 节点是否已经脱离文档。判不出来时一律当作"还在"—— 宁可不补,也绝不重复插入。 */
+    const maDetached = (el) => {
+      if (!el) return false;
+      try { if (typeof el.isConnected === "boolean") return !el.isConnected; } catch (eConn) { /* 继续退化 */ }
+      try {
+        const b = document.body;
+        if (b && typeof b.contains === "function") return !b.contains(el);
+      } catch (eHas) { /* 继续退化 */ }
+      return false;
+    };
+
+    /* —— 存在性看门狗:「建好了」不等于「一直都在」----------------------------------
+       done=true 只保证**曾经**建出来过。官方在路由/会话切换时会重建 DOM 子树,我们的汉堡按钮
+       与遮罩会跟着消失 —— 用户看到的就是"抽屉按钮用着用着又没了"。
+       这里按**引用**补回(不是重建),只在窄屏做(宽屏本来就不需要抽屉入口)。
+       幂等:节点还在文档里 → 什么都不做;boot 还没成功(引用为 null) → 同样什么都不做。 */
+    const ensureDrawerChrome = () => {
+      try {
+        if (!NARROW() || !document.body) return;
+        if (maDetached(maScrim)) document.body.appendChild(maScrim);
+        if (maDetached(maHamburger)) document.body.appendChild(maHamburger);
+      } catch (eChrome) { /* 补不回去也不能影响抽屉开合本身 */ }
+    };
+
     let done = false;
     const boot = () => {
       if (!HOSTISH()) return;
@@ -1228,6 +1258,7 @@ const SCRIPT = `(() => {
       const scrim = document.createElement("div");
       scrim.className = "dsh-ma-scrim";
       document.body.appendChild(scrim);
+      maScrim = scrim;                          // 供「存在性看门狗」在被官方冲掉后补回
       scrim.addEventListener("click", (e) => {
         e.stopPropagation();
         userWantsOpen = false;                    // 用户明确要关(遮罩的作用就是关抽屉)
@@ -1245,6 +1276,7 @@ const SCRIPT = `(() => {
       hamburger.setAttribute("aria-label", "打开菜单");
       hamburger.innerHTML = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h10"/></svg>';
       document.body.appendChild(hamburger);
+      maHamburger = hamburger;                  // 供「存在性看门狗」在被官方冲掉后补回
       hamburger.addEventListener("click", (e) => {
         e.stopPropagation(); e.preventDefault();
         const nowOpen = document.documentElement.classList.contains("dsh-ma-sidebar-open");
@@ -1516,10 +1548,82 @@ const SCRIPT = `(() => {
     };
 
     if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot); else boot();
-    /* 官方模块系统异步挂载 UI,晚一点再补几次(幂等,done 守卫);同时等鲸鱼/设置弹层就位 */
-    [700, 1600, 3200, 7000, 12000].forEach((ms) =>
-      setTimeout(() => { try { boot(); whaleHookInit(); watchSettings(); } catch (e) { /* 幂等重试 */ } }, ms)
-    );
+
+    /* ================= 执行时机:无限期等待官方 DOM 就绪 =================
+       用户实测原话(2026-09-2x):「在网络比较慢的情况下,左边的抽屉按钮有时候出不来。
+                                   甭管网络有多慢,都要让那个抽屉能加载出来。」
+       ⚠️ 旧实现是**一组写死的固定重试**([700, 1600, 3200, 7000, 12000]ms),而汉堡按钮的创建
+          排在 boot() 里 "if (!frame) return;" 那一行之后 —— 官方 SPA bundle 有 13.4MB(实测未压缩),
+          免费档被中继限速到 128KB/s 时冷启动要 1-2 分钟,官方 frame 在 12 秒内根本没出现:
+          5 次重试全部在那一行返回 → done 永远为 false → 汉堡按钮**永远**不创建
+          → 用户看到"左边抽屉按钮出不来"。任何固定窗口都只是把这个阈值往后挪,治不了根。
+       现在改成「事件驱动 + 低频兜底」的**无限期**等待,只要抽屉入口还没建好就一直试:
+         · MutationObserver(document/subtree):官方 frame 一挂上就立刻跟上(网络快时零延迟);
+         · setInterval(1000ms):兜底 + 存在性看门狗 —— observer 不可用/被绕过时照样收敛,
+           也负责在 done 之后发现官方重渲染冲掉了我们的节点并补回。
+       两条路都只是"再调一次 pump()",pump 内部**全部幂等**(done / fabDone / whaleGuardsOn /
+       settingsWatchOn / drawerAutoCloseOn 等守卫都在),重复调用不会产生任何副作用,
+       也不改变"执行什么"——开合、遮罩不变量、sync()、isDrawer() 判定一行未动。 */
+    let maTorn = false, maInterval = 0, maObserver = null, maRafPending = false;
+    /* 廉价的"boot() 还有事可做吗"闸门(只读两个现成的布尔标志,不做任何 DOM 操作):
+         · fab 还没建出来(fabDone=false) → 要跑;
+         · 抽屉那段还没建好(done=false)且当前是窄屏 → 要跑(旋转/缩放回窄屏也能补建)。
+       两者都不成立 → boot() 里已无事可做,**绝不能**再跑:boot() 第一行 HOSTISH() 会把
+       documentElement.outerHTML 整个序列化一遍(最长 200KB),而官方流式输出时每帧都有 DOM
+       变更 —— 没有这道闸门就会变成每秒几十次全量序列化(旧实现只跑 5 次,不会有这个问题)。 */
+    const bootUseful = () => !fabDone || (!done && NARROW());
+    const pump = () => {
+      if (maTorn) return;
+      if (bootUseful()) { try { boot(); } catch (eBoot) { /* 幂等重试 */ } }
+      try { ensureDrawerChrome(); } catch (eChrome2) { /* 忽略 */ }
+      if (!whaleGuardsOn || !settingsWatchOn) {
+        try { whaleHookInit(); watchSettings(); } catch (eHook) { /* 两者内部都自带一次性守卫 */ }
+      }
+    };
+    /* 节流:一次 DOM 变更往往产生几十条记录,逐条 boot() 就是忙轮询。
+       统一合并成"本帧最多跑一次"(有 rAF 用 rAF,没有就退化成 0ms 宏任务) —— 天然去重。 */
+    const schedulePump = () => {
+      if (maTorn || maRafPending) return;
+      maRafPending = true;
+      const run = () => { maRafPending = false; pump(); };
+      try { if (typeof requestAnimationFrame === "function") { requestAnimationFrame(run); return; } } catch (eRaf) { /* 退化 */ }
+      setTimeout(run, 0);
+    };
+    /* 挂上"叫醒"的两条路。做成可重入(先清旧的再建新的),这样 bfcache 恢复后能重新武装。 */
+    const maArm = () => {
+      maTorn = false;
+      maRafPending = false;            // 冻结时若有一帧没跑到,不清掉就会永远挡住后续调度
+      try { if (maObserver) maObserver.disconnect(); } catch (eA1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eA2) { /* 忽略 */ }
+      maInterval = 0;
+      try {
+        if (typeof MutationObserver === "function" && document.documentElement) {
+          maObserver = new MutationObserver(schedulePump);
+          /* 只观察 childList+subtree:节点被官方换掉/新增才叫醒我们。
+             ⚠️ 刻意**不**观察 attributes —— 我们自己的 sync() 就会不停改 class,那会变成自激循环。 */
+          maObserver.observe(document.documentElement, { childList: true, subtree: true });
+        }
+      } catch (eObs) { maObserver = null; /* 退化:只靠下面的兜底表 */ }
+      try { maInterval = setInterval(pump, 1000); } catch (eInt) { maInterval = 0; }
+    };
+    maArm();
+    /* 清理:页面卸载时断开观察者与兜底表(bfcache/长驻页面都不留悬挂回调)。
+       pagehide 覆盖 bfcache 场景,unload 兜底更老的浏览器。 */
+    const maTeardown = () => {
+      maTorn = true;
+      try { if (maObserver) maObserver.disconnect(); } catch (eD1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eD2) { /* 忽略 */ }
+      maInterval = 0;
+    };
+    try { window.addEventListener("pagehide", maTeardown); } catch (ePh) { /* 忽略 */ }
+    try { window.addEventListener("unload", maTeardown); } catch (eUl) { /* 忽略 */ }
+    /* 手机上"切到别的 App 再切回来"走的常是 bfcache:pagehide(persisted=true) → pageshow(persisted=true)。
+       DOM 原样保留但计时器/观察者已断 —— 这里重新武装,否则回到页面后看门狗就永久失灵了。 */
+    try {
+      window.addEventListener("pageshow", (ev) => { try { if (ev && ev.persisted) maArm(); } catch (ePs) { /* 忽略 */ } });
+    } catch (ePs2) { /* 忽略 */ }
   } catch (e) { if (window.console) console.warn("[dsh-mobile-adapter]", e && e.message); }
 })();`;
 

package/clients/dsh-remote/test/bridge-gzip.test.mjs

@@ -15,7 +15,7 @@ import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import test, { after } from "node:test";
-import { gunzipSync } from "node:zlib";
+import { gunzipSync, gzipSync } from "node:zlib";
 
 // ---------- 本地假上游(doHttp 全链路用;端口先占再 import,UPSTREAM 在模块加载时固定) ----------
 
@@ -31,6 +31,25 @@ const upstream = http.createServer((req, res) => {
     res.end(BIG_JSON);
     return;
   }
+  /* 模拟**真实 dsh web**:上游自己就把响应 gzip 掉并回 content-encoding: gzip
+     (线上 `/plugins/??` 那个 13.4MB 的聚合包正是这样发的)。
+     这条路由是 bridge「丢弃上游压缩」那个 bug 的回归哨兵 —— 见文件末尾的集成用例。 */
+  if (req.url === "/upstream-gzip") {
+    const body = Buffer.from(BIG_JSON, "utf8");
+    if (String(req.headers["accept-encoding"] || "").includes("gzip")) {
+      const z = gzipSync(body);
+      res.writeHead(200, {
+        "content-type": "application/json; charset=utf-8",
+        "content-encoding": "gzip",
+        "content-length": String(z.length)
+      });
+      res.end(z);
+      return;
+    }
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    res.end(body);
+    return;
+  }
   if (req.url === "/tiny") {
     res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
     res.end(TINY_TEXT);
@@ -213,3 +232,51 @@ test("集成:204 响应不压缩", async () => {
   assert.equal(reply.status, 204);
   assert.equal(reply.headers["content-encoding"], undefined);
 });
+
+test("★ 回归:上游自己 gzip 过(content-encoding: gzip),bridge 仍必须重压回传", async () => {
+  /* 事故原貌(2026-09-23):
+   *   undici 的 fetch 会**自动解压** body,但**保留** `content-encoding: gzip` 响应头。
+   *   旧代码把该头当作"buf 已编码"传给 maybeCompressResponse → 函数保守 return null →
+   *   **永不重压**。于是线上 dsh web 的 /plugins/?? 聚合包(上游 gzip 后 5.12MB)
+   *   被按 13.39MB 原样塞进隧道(实测 3 次,每次 bridge 日志都是 13707KB)。
+   *   免费档 1Mbps 下这一条就把首屏从 ~40 秒拖到 100+ 秒。
+   *
+   * 这条用例守的是:**上游压过 ≠ 我们手上是压缩数据**。bridge 手上永远是 undici 解压后的明文,
+   * 所以必须照常走压缩分支 —— 一旦有人把这个头又接回去,这里立刻红。
+   */
+  const reply = await request({
+    id: "g5",
+    method: "GET",
+    path: "/upstream-gzip",
+    headers: { "accept-encoding": GZIP_ACCEPT, "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(
+    reply.headers["content-encoding"],
+    "gzip",
+    "上游压过也照样要重压 —— 少了这个头,隧道里就是 2.6 倍的白流量"
+  );
+  const raw = Buffer.from(reply.body, "base64");
+  const plainLen = Buffer.byteLength(BIG_JSON);
+  assert.ok(raw.length < plainLen, `重压后必须小于明文 (${raw.length} < ${plainLen})`);
+  assert.ok(
+    raw.length < plainLen * 0.6,
+    `应当真正压下去(实测明文 ${plainLen} → ${raw.length});若接近明文说明压缩没生效`
+  );
+  // 只解压一次就应得到原文 —— 这一条同时排除"双重 gzip"这种更坏的结果
+  assert.equal(gunzipSync(raw).toString("utf8"), BIG_JSON, "只能有一层 gzip;解压一次必须就是原文");
+});
+
+test("★ 回归:上游 gzip + 客户端没带 Accept-Encoding → 不压缩,但内容仍是明文原文", async () => {
+  // 上游按 accept-encoding 决定压不压;bridge 解压后原样回传(不带 content-encoding),
+  // 手机端按 identity 处理 → 内容正确,只是没省流量。绝不能出现"标了 gzip 其实是明文"。
+  const reply = await request({
+    id: "g6",
+    method: "GET",
+    path: "/upstream-gzip",
+    headers: { "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(reply.headers["content-encoding"], undefined);
+  assert.equal(Buffer.from(reply.body, "base64").toString("utf8"), BIG_JSON);
+});

package/clients/dsh-remote/test/mobile-adapter-late-frame.test.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * mobile-adapter 回归测试：**网络再慢，左侧抽屉按钮（汉堡）也必须最终出现**。
+ *
+ * 用户原话（2026-09-2x 手机实测）：
+ *   「在网络比较慢的情况下，左边的抽屉按钮有时候出不来。你要考虑修复这个问题，
+ *     甭管网络有多慢，都要让那个抽屉能加载出来。」
+ *
+ * 根因（本文件针对的 bug）：
+ *   注入脚本 boot() 的**执行时机**是写死的一组固定重试
+ *   （DOMContentLoaded + 700 / 1600 / 3200 / 7000 / 12000 ms），
+ *   而汉堡按钮的创建排在 `if (!frame) return;` **之后**：
+ *     · 官方 SPA bundle 有 13.4MB（实测未压缩），免费档被中继限速到 128KB/s 时冷启动要 1-2 分钟；
+ *     · 官方 frame 在 12 秒内根本没出现 → 5 次重试全部在那一行 return
+ *       → `done` 永远为 false → 汉堡按钮永远不创建 → 用户看到"左边抽屉按钮出不来"。
+ *
+ * 修法（本文件断言的契约）：
+ *   ① 不再依赖任何固定重试窗口 —— 改成「事件驱动（MutationObserver 观察 document/subtree）
+ *      + 低频兜底（setInterval 1000ms）」的**无限期**等待：只要 done 还是 false 就继续 boot()；
+ *   ② done=true 之后仍有「存在性看门狗」：官方重渲染把 dsh-ma-hamburger / dsh-ma-scrim
+ *      从 DOM 里冲掉时，按引用补回（节点不变 = 事件处理与类名都还在）；
+ *   ③ 两条路都必须幂等、有节流（观察者回调走 rAF 合并，兜底表 1s 一跳），
+ *      且页面卸载（pagehide/unload）时断开观察者与表。
+ *
+ * 本文件用假 DOM + vm 跑**真实注入脚本**，并把时间轴完全握在手里（不依赖真实计时器）：
+ *   · flushTimeouts()  —— 把旧的固定重试窗口一次性走完（正是"窗口耗尽"的现场）；
+ *   · tickIntervals()  —— 模拟兜底 setInterval 每秒一跳，可以一直跳到第 15 秒、第 60 秒；
+ *   · mountFrame()     —— 模拟官方 DOM 迟到挂载，并按真实 MutationObserver 语义通知观察者。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import vm from "node:vm";
+import { injectMobileAdapter } from "../mobile-adapter.mjs";
+
+/** 取注入结果里的真实 <script> 内容（不加壳，原样执行）。 */
+function adapterScript() {
+  const { html } = injectMobileAdapter("<!doctype html><html><head></head><body></body></html>");
+  const m = /<script id="[^"]*-js"[^>]*>([\s\S]*?)<\/script>/.exec(html);
+  assert.ok(m, "应能取出注入脚本");
+  return m[1];
+}
+
+// ── 极简假 DOM（与 mobile-adapter-runtime.test.mjs 同风格，另加父子链/isConnected） ──────
+
+class El {
+  constructor(tag = "div", attrs = {}) {
+    this.tagName = String(tag).toUpperCase();
+    this.attrs = { ...attrs };
+    this.children = [];
+    this.parent = null;
+    this._cls = new Set(String(attrs.class || "").split(/\s+/).filter(Boolean));
+    this._l = new Map();
+    this.style = {
+      setProperty: (k, v) => { this._cssVars[k] = v; },
+      removeProperty: (k) => { delete this._cssVars[k]; },
+      display: "",
+    };
+    this._cssVars = {};
+    this._rect = { left: 0, right: 0, top: 0, bottom: 0, width: 0, height: 0 };
+    this.hidden = false;
+    this.classList = {
+      add: (...cs) => cs.forEach((c) => this._cls.add(c)),
+      remove: (...cs) => cs.forEach((c) => this._cls.delete(c)),
+      contains: (c) => this._cls.has(c),
+      toggle: (c, on) => {
+        const want = on === undefined ? !this._cls.has(c) : !!on;
+        if (want) this._cls.add(c); else this._cls.delete(c);
+        return want;
+      },
+    };
+  }
+  set innerHTML(html) {
+    this._html = String(html);
+    this.children = [];
+    for (const m of String(html).matchAll(/<(\w+)([^>]*)>/g)) {
+      const el = new El(m[1]);
+      const cls = /class="([^"]*)"/.exec(m[2] || "");
+      if (cls) el.className = cls[1];
+      const type = /type="([^"]*)"/.exec(m[2] || "");
+      if (type) el.attrs.type = type[1];
+      this.appendChild(el);
+    }
+  }
+  get innerHTML() { return this._html || ""; }
+  get className() { return [...this._cls].join(" "); }
+  set className(v) { this._cls = new Set(String(v).split(/\s+/).filter(Boolean)); }
+  get textContent() { return this._text || ""; }
+  set textContent(v) { this._text = String(v); }
+  getAttribute(n) { return n in this.attrs ? this.attrs[n] : null; }
+  setAttribute(n, v) { this.attrs[n] = String(v); }
+  removeAttribute(n) { delete this.attrs[n]; }
+  hasAttribute(n) { return n in this.attrs; }
+  appendChild(c) { c.parent = this; this.children.push(c); return c; }
+  removeChild(c) { this.children = this.children.filter((x) => x !== c); if (c.parent === this) c.parent = null; return c; }
+  remove() { if (this.parent) this.parent.removeChild(this); }
+  contains(el) { let n = el; while (n) { if (n === this) return true; n = n.parent; } return false; }
+  /* 真实 DOM 语义：节点是否还挂在文档里。本假 DOM 以"能沿 parent 链走到 doc"为准。 */
+  get isConnected() { let n = this; while (n) { if (n._inDoc) return true; n = n.parent; } return false; }
+  prepend() {} focus() {} blur() {} scrollIntoView() {} setPointerCapture() {}
+  matches() { return false; }
+  addEventListener(t, fn) { if (!this._l.has(t)) this._l.set(t, []); this._l.get(t).push(fn); }
+  removeEventListener() {}
+  dispatchEvent() { return true; }
+  dispatch(t, ev = {}) { for (const fn of this._l.get(t) || []) fn({ stopPropagation() {}, preventDefault() {}, ...ev }); }
+  getBoundingClientRect() { return this._rect; }
+  querySelector(sel) {
+    const s = String(sel);
+    const hit = (el) => {
+      if (s.includes('input[type="range"]')) return el.tagName === "INPUT" && el.attrs.type === "range";
+      if (s.startsWith(".")) return el._cls.has(s.slice(1));
+      if (s.startsWith("input")) return el.tagName === "INPUT";
+      return false;
+    };
+    return this.children.find(hit) || null;
+  }
+  querySelectorAll(sel) { const one = this.querySelector(sel); return one ? [one] : []; }
+}
+
+/** 记录型 MutationObserver：可被手工触发，也可被 mountFrame 按真实语义叫醒。 */
+class MutationObserverStub {
+  constructor(cb) { this.cb = cb; this.targets = []; this.disconnected = false; MutationObserverStub.instances.push(this); }
+  observe(t, opts) { this.targets.push({ t, opts }); }
+  disconnect() { this.disconnected = true; }
+  fire(records) { if (!this.disconnected) this.cb(records, this); }
+  static reset() { MutationObserverStub.instances = []; }
+}
+MutationObserverStub.instances = [];
+
+/**
+ * 搭一个"官方 index.html 已经回来、但 13.4MB 的 SPA bundle 还没渲染出 frame"的现场：
+ *   · html.outerHTML 只有官方外壳特征（__ModuleLoader__ / DeepSeek Harness）——
+ *     与真实 index.html 一致，**不含** frame 的任何 data-* 标记；
+ *   · document.querySelector(官方 frame 选择器) 在 mountFrame() 之前一律返回 null
+ *     （= 官方 UI 还没挂载，正是用户网络慢时看到的状态）。
+ */
+function harness({ width = 390, height = 844 } = {}) {
+  MutationObserverStub.reset();
+  const intervals = [];
+  const timeouts = [];
+  let rafs = [];
+  const state = { mounted: false, pagehide: null };
+
+  const doc = new El("#document");
+  doc.tagName = "#DOCUMENT";
+  doc._inDoc = true;                     // 文档根：沿 parent 链能走到它就说明"在文档里"
+  const html = new El("html");
+  const body = new El("body");
+  doc.appendChild(html);
+  html.appendChild(body);
+  // 官方 index.html 外壳（真实 HTML 里就是这些字样；frame 是 bundle 跑起来之后才有的）
+  // outerHTML 做成计数器：boot() 第一行的 HOSTISH() 会整段序列化它，读数就是"整页判定"的次数
+  let outerHtmlReads = 0;
+  Object.defineProperty(html, "outerHTML", {
+    configurable: true,
+    get() { outerHtmlReads += 1; return '<html><head><script>window.__ModuleLoader__ = { mode: "queue" }</script>'
+      + "<title>DeepSeek Harness</title></head><body></body></html>"; },
+    set() { /* 允许写入（本用例不依赖） */ },
+  });
+
+  const frame = new El("div", { class: "pI_x6G_frame" });
+  frame.setAttribute("data-sidebar-collapsed", "true");
+  frame.querySelector = () => null;      // 本用例不涉及第三列/overlay 识别
+
+  doc.readyState = "complete";
+  doc.documentElement = html;
+  doc.body = body;
+  doc.createElement = (t) => new El(t);
+  doc.createTextNode = (t) => ({ nodeValue: t });
+  doc.getElementById = () => null;
+  doc.addEventListener = () => {};
+  doc.removeEventListener = () => {};
+  doc.querySelector = (sel) => {
+    const s = String(sel);
+    if (s.includes(".pI_x6G_frame") || /\[data-(sidebar|details|rightbar)-collapsed\]/.test(s) || s.includes("[data-shell-overlay]")) {
+      return state.mounted ? frame : null;   // ⬅️ 官方 UI 迟到：挂载前一律查不到
+    }
+    return null;
+  };
+  doc.querySelectorAll = () => [];
+
+  const loc = { href: "https://n.risegao.cn:13443/remote/dev-x/", host: "n.risegao.cn", pathname: "/remote/dev-x/", origin: "https://n.risegao.cn:13443" };
+  const win = {
+    innerWidth: width,
+    innerHeight: height,
+    devicePixelRatio: 2,
+    localStorage: { _d: {}, getItem(k) { return k in this._d ? this._d[k] : null; }, setItem(k, v) { this._d[k] = String(v); }, removeItem(k) { delete this._d[k]; } },
+    location: loc,
+    MutationObserver: MutationObserverStub,
+    ResizeObserver: class { observe() {} disconnect() {} },
+    getComputedStyle: () => ({ getPropertyValue: () => "", pointerEvents: "none" }),
+    addEventListener(t, fn) {
+      if (t === "pagehide" || t === "unload") state.pagehide = fn;
+      if (t === "pageshow") state.pageshow = fn;
+    },
+    removeEventListener() {},
+    /* 计时器全部"抓住不放"，时间轴由用例自己推 —— 不依赖真实时钟，也不会有测试结束后的悬挂回调。 */
+    setTimeout: (fn) => timeouts.push(fn),
+    clearTimeout: () => {},
+    setInterval: (fn) => { intervals.push(fn); return intervals.length; },
+    clearInterval: (id) => { if (id) intervals[id - 1] = null; },
+    requestAnimationFrame: (fn) => { rafs.push(fn); return rafs.length; },
+  };
+
+  const ctx = vm.createContext({
+    window: win, document: doc, console,
+    navigator: { userAgent: "iPhone Safari", maxTouchPoints: 5, platform: "iPhone" },
+    location: loc, localStorage: win.localStorage,
+    setTimeout: win.setTimeout, clearTimeout: win.clearTimeout,
+    setInterval: win.setInterval, clearInterval: win.clearInterval,
+    MutationObserver: MutationObserverStub, ResizeObserver: win.ResizeObserver,
+    requestAnimationFrame: win.requestAnimationFrame,
+    URL, Math, JSON, Object, Array, String, Number, RegExp, Boolean, Promise, Error, isNaN, parseInt, parseFloat,
+    HTMLElement: El,
+  });
+  ctx.globalThis = ctx;
+  ctx.self = win;
+
+  /** 官方 UI 迟到挂载：把 frame 挂进 body，并按真实 MutationObserver 语义通知观察祖先树的观察者。 */
+  const mountFrame = ({ notify = true } = {}) => {
+    state.mounted = true;
+    body.appendChild(frame);
+    if (!notify) return;
+    for (const ob of MutationObserverStub.instances.slice()) {
+      if (ob.disconnected) continue;
+      const targets = ob.targets.map((x) => x.t);
+      // 新节点加进 body → 观察 body / documentElement / document（subtree）的观察者都会收到 childList 记录
+      if (targets.includes(body) || targets.includes(html) || targets.includes(doc)) {
+        ob.fire([{ type: "childList", target: body, addedNodes: [frame] }]);
+      }
+    }
+  };
+  /** 把旧的"固定重试窗口"（700/1600/3200/7000/12000ms 那批 setTimeout）一次性走完。 */
+  const flushTimeouts = () => { const q = timeouts.splice(0, timeouts.length); for (const fn of q) fn(); };
+  /** 模拟兜底 setInterval 每秒一跳（间隔由实现决定，用例只关心"它一直在跳"）。 */
+  const tickIntervals = (seconds = 1) => {
+    for (let i = 0; i < seconds; i++) for (const fn of intervals.slice()) if (fn) fn();
+  };
+  const flushRaf = () => { const q = rafs; rafs = []; for (const fn of q) fn(); };
+  /** 模拟官方 SPA 的 DOM 变更风暴（流式输出时每帧都在改 DOM），并按真实语义通知观察者。 */
+  const churn = (n = 20) => {
+    for (let i = 0; i < n; i++) {
+      const d = new El("div");
+      body.appendChild(d);
+      for (const ob of MutationObserverStub.instances.slice()) {
+        if (ob.disconnected) continue;
+        const targets = ob.targets.map((x) => x.t);
+        if (targets.includes(body) || targets.includes(html) || targets.includes(doc)) {
+          ob.fire([{ type: "childList", target: body, addedNodes: [d] }]);
+        }
+      }
+      flushRaf();
+    }
+  };
+
+  return { ctx, doc, html, body, frame, win, state, mountFrame, flushTimeouts, tickIntervals, flushRaf, churn,
+    intervals, outerHtmlReads: () => outerHtmlReads };
+}
+
+function run(env, js) {
+  vm.runInContext(js, env.ctx, { timeout: 5000 });
+  return env;
+}
+
+const findHamburger = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-hamburger"));
+const findScrim = (env) => env.body.children.find((c) => c._cls.has("dsh-ma-scrim"));
+
+// ── 用例 ─────────────────────────────────────────────────────────────────────
+
+test("慢网回归：官方 frame 第 15 秒才出现，汉堡按钮最终仍必须创建（旧的 12s 固定重试窗口会永久放弃）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+
+  assert.ok(!findHamburger(env), "前提：官方 frame 还没出现时，不该凭空造出汉堡按钮");
+  assert.ok(!findScrim(env), "前提：官方 frame 还没出现时，不该凭空造出遮罩");
+
+  // ① 先把旧的固定重试窗口整批走完（700…12000ms 全部到点）—— 这正是当年"窗口耗尽"的现场
+  env.flushTimeouts();
+  assert.ok(!findHamburger(env), "官方 frame 未出现时仍不得创建汉堡按钮（不能提前造出无锚点的入口）");
+
+  // ② 再把时间推过 15 秒（兜底表每秒一跳），官方 frame 依然没来
+  env.tickIntervals(15);
+  assert.ok(!findHamburger(env), "前提：frame 还没来");
+
+  // ③ 第 15 秒：13.4MB 的 bundle 终于在 128KB/s 的限制下加载完，官方 frame 挂上 DOM。
+  //    这里刻意不通知观察者（notify:false）—— 只留"低频兜底 setInterval"这一条路，
+  //    证明它不是"靠事件侥幸"，而是真的无限期重试。
+  env.mountFrame({ notify: false });
+  assert.ok(!findHamburger(env), "前提：这一瞬间还没轮到兜底表跳");
+
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env),
+    "网络再慢，官方 frame 一出现抽屉按钮也必须最终创建出来（本次 bug 的回归点：固定重试窗口耗尽就永久放弃）");
+  assert.ok(findScrim(env), "遮罩同样必须补上（它和汉堡按钮在同一段之后创建）");
+});
+
+test("慢网回归：跳到第 60 秒（远超旧窗口 5 倍）官方 frame 才出现，汉堡按钮仍必须出现", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.flushTimeouts();
+  env.tickIntervals(60);                        // 60 秒过去，frame 还没来
+  assert.ok(!findHamburger(env), "前提：frame 仍然没来");
+  env.mountFrame({ notify: false });            // 第 60 秒才挂上
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env), "「甭管网络有多慢」——60 秒后才出现官方 frame 也必须能拿到抽屉按钮");
+});
+
+test("事件驱动：官方 frame 挂载的 DOM 变更直接叫醒适配层（观察者回调经 rAF 合并，不等兜底表）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  assert.ok(!findHamburger(env), "前提：frame 未挂载");
+  env.mountFrame();                             // 通知观察者
+  env.flushRaf();                               // 合并后的那一帧
+  assert.ok(findHamburger(env), "官方 frame 一挂上就必须立刻跟上（事件驱动路径），不必等 1s 兜底表");
+});
+
+test("存在性看门狗：done 之后官方重渲染把汉堡/遮罩冲掉，必须按引用补回来", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  const ham = findHamburger(env);
+  const scrim = findScrim(env);
+  assert.ok(ham && scrim, "前提：抽屉入口已建好");
+
+  // 模拟官方 SPA 重渲染：整片换掉 body 子树（实测某些路由/会话切换会重建 DOM）
+  env.body.removeChild(ham);
+  env.body.removeChild(scrim);
+  assert.ok(!findHamburger(env), "前提：官方重渲染把我们的节点冲掉了");
+  assert.equal(ham.isConnected, false, "假 DOM 语义：被移除的节点应报 isConnected=false");
+
+  env.tickIntervals(2);
+  assert.equal(findHamburger(env), ham, "补回的必须是**同一个节点**（事件处理与类名原样保留），而不是重建一个");
+  assert.equal(findScrim(env), scrim, "遮罩同样必须补回");
+  assert.equal(ham.isConnected, true, "补回后应重新在文档里");
+});
+
+test("清理：pagehide 必须断开观察者与兜底表（避免 bfcache/长驻页面泄漏）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  assert.equal(typeof env.state.pagehide, "function", "应注册 pagehide 清理钩子");
+  const observers = MutationObserverStub.instances.slice();
+  env.state.pagehide();
+  assert.ok(observers.every((o) => o.disconnected), "pagehide 必须 disconnect 所有已挂观察者");
+  // 断开后时间轴上再跳也不再工作（表已清）
+  env.mountFrame({ notify: false });
+  env.tickIntervals(2);
+  assert.ok(!findHamburger(env), "卸载后不得再往页面里塞东西");
+});
+
+test("bfcache：切走再切回来（pageshow persisted）必须重新武装看门狗，否则回来后就永久失灵", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  const ham = findHamburger(env);
+  assert.ok(ham, "前提：抽屉入口已就位");
+
+  env.state.pagehide();                          // 切走（进入 bfcache）
+  env.state.pageshow({ persisted: true });       // 切回来（从 bfcache 恢复）
+  env.body.removeChild(ham);                     // 官方此时重渲染冲掉我们的节点
+  env.tickIntervals(1);
+  assert.equal(findHamburger(env), ham, "bfcache 恢复后看门狗必须仍然有效（重新武装）");
+  env.state.pageshow({ persisted: false });      // 普通 pageshow 不得重复武装出第二套计时器
+  const live = env.intervals.filter(Boolean).length;
+  env.state.pageshow({ persisted: true });
+  assert.equal(env.intervals.filter(Boolean).length, live, "重新武装必须先清旧表（不能越切越多计时器）");
+});
+
+test("幂等：兜底表长时间空转不得重复插入节点（每类节点在 body 里最多一个）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(30);                        // 空转 30 秒
+  const count = (cls) => env.body.children.filter((c) => c._cls.has(cls)).length;
+  assert.equal(count("dsh-ma-hamburger"), 1, "汉堡按钮必须只有一个（幂等，不能每次 tick 都插一个）");
+  assert.equal(count("dsh-ma-scrim"), 1, "遮罩必须只有一个");
+});
+
+test("开销：抽屉入口就位后，官方的 DOM 变更风暴不得再触发整页判定（HOSTISH 会序列化整个 outerHTML）", () => {
+  const env = run(harness({ width: 390 }), adapterScript());
+  env.mountFrame({ notify: false });
+  env.tickIntervals(1);
+  assert.ok(findHamburger(env), "前提：抽屉入口已就位");
+
+  // 官方流式输出时每帧都在改 DOM —— 这时适配层必须已经"静默"，不能再做昂贵判定
+  const before = env.outerHtmlReads();
+  env.churn(30);                                 // 30 帧 DOM 变更（每帧都通知观察者）
+  env.tickIntervals(3);                          // 兜底表再空转 3 秒
+  assert.equal(env.outerHtmlReads(), before,
+    "入口已经建好且都在文档里时，不得再为每次 DOM 变更/每秒 tick 重新序列化整页（那是每秒几十次全量 outerHTML）");
+  // 但"看门狗"必须还在：真被冲掉时依然能补回来（静默 ≠ 失灵）
+  env.body.removeChild(findHamburger(env));
+  env.churn(1);
+  assert.ok(findHamburger(env), "静默之后看门狗仍必须工作");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrisega/dsh-remote",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "手机远程控制 DeepSeek Harness · Remote control DeepSeek Harness (dsh web) from any phone browser — 100% 全功能 App 级体验：发消息、看工具执行、审批权限、改设置、管凭据，含特权操作，免内网穿透。一条命令安装 npx @mrrisega/dsh-remote。Mobile remote control for DSH, self-host or SaaS, no server needed on LAN.",
   "keywords": [
     "deepseek-harness",
@@ -51,7 +51,7 @@
   },
   "scripts": {
     "test": "npm run test:router && npm run test:plugin && npm run test:bridge",
-    "test:router": "NODE_OPTIONS=\"--require $PWD/scripts/test-net-guard.cjs ${NODE_OPTIONS:-}\" node --test packages/relay-router/test/native-device-selection.test.mjs packages/relay-router/test/native-app-entry.test.mjs packages/relay-router/test/presence-report.test.mjs packages/relay-router/test/logger.test.mjs",
+    "test:router": "NODE_OPTIONS=\"--require $PWD/scripts/test-net-guard.cjs ${NODE_OPTIONS:-}\" node --test packages/relay-router/test/native-device-selection.test.mjs packages/relay-router/test/native-app-entry.test.mjs packages/relay-router/test/presence-report.test.mjs packages/relay-router/test/logger.test.mjs packages/relay-router/test/device-free-assets.test.mjs packages/relay-router/test/sse-streaming-contract.test.mjs",
     "_comment:test:plugin": "DSH_RELAY_BUNDLED_RUNTIME=/nonexistent = 强制走 npx 兜底分支（否则本机跑过 npm pack 后 packages/dsh-remote-web/runtime 存在，用例会改成走本地拷贝）。DSH_RELAY_SKIP_SERVICE=1 = 测试隔离：插件加载时不做真实系统操作（npx 补装 / launchctl / 重启 harness）；需要真实分支的用例自行 unset（见 account-switch / runtime-provision / harness-restart 用例注释）。DSH_RELAY_DEFAULT_API= 死端口：用例拆掉临时目录后，仍在飞的后台请求（装机上报重试等）会读到空配置并回落「默认云端地址」—— 指到本地死端口才不会打生产。",
     "test:plugin": "DSH_REMOTE_TELEMETRY=0 DSH_RELAY_SKIP_SERVICE=1 DSH_RELAY_DEFAULT_API=http://127.0.0.1:1 DSH_RELAY_BUNDLED_RUNTIME=/nonexistent-dsh-bundled NODE_OPTIONS=\"--require $PWD/scripts/test-net-guard.cjs ${NODE_OPTIONS:-}\" node --test --test-concurrency=1 packages/dsh-remote-web/test/*.test.mjs",
     "_comment:test:bridge": "⚠️ 必须 --test-concurrency=1（与 test:plugin 对齐）：tunnel-auth 有一条「bridge 5 秒内必须重连」的硬期限，并行跑时新增用例抢 CPU 会把它撞破 → 偶发假红（实测单独跑 2/2 通过、并发跑偶发 0/2）。假红比慢更贵。",

package/packages/dsh-remote-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "公网远程控制 DeepSeek Harness（dsh web）：安装即得专属加密地址，人在外面也能用手机访问电脑上的 dsh——无需同一局域网/WiFi、无需公网 IP 与内网穿透，全程加密；手机端 100% 还原电脑体验（对话/工具/审批/设置）。技术用户可选自建服务，流量走自己的服务器。Remote control DeepSeek Harness (dsh web) from anywhere over the public internet — install, get an encrypted URL, use it from your phone on any network (dual-half cordis plugin: Settings panel + same-origin /dsh-remote routes). (2026-09 由 dsh-remote-ui 更名 / renamed from dsh-remote-ui; dsh-remote 的 dsh web 插件半，不是纯 UI/皮肤插件)",
   "type": "module",
   "main": "lib/index.js",

package/packages/dsh-remote-web/runtime/clients/dsh-remote/dsh-bridge.mjs

@@ -505,6 +505,15 @@ export async function handleFrame(dchOrSend, frame) {
   if (id === undefined || id === null) return;
   const send = toSender(dchOrSend);
   if (type === "http") return handleHttpFrame(send, frame);
+  if (type === "http-abort") {
+    // 手机侧断开了这条流(切页/锁屏):掐掉上游,别在电脑上留一条永不结束的 SSE 连接。
+    const c = streamAborts.get(id);
+    if (c) {
+      streamAborts.delete(id);
+      try { c.abort(); } catch { /* ignore */ }
+    }
+    return;
+  }
   if (type === "ws-open") return handleWsOpen(send, frame);
   if (type === "ws-msg") return handleWsMessage(send, frame);
   if (type === "ws-close") return handleWsClose(send, frame);
@@ -541,7 +550,10 @@ function headerValue(headers, name) {
  * 保守策略:任一条件不满足都返回 null(原样回传):
  *   - 方法非 HEAD、状态非 204/304;
  *   - buf ≥ 1KB(太小不值得压);
- *   - 上游未编码(contentEncoding 为空;undici 已自动解压 body,这里只看原 header);
+ *   - `contentEncoding` 为空 —— ⚠️ 它指的是**手上这份 buf 的编码**,不是上游响应头的值:
+ *     上游头的 "gzip" 在 undici 解压后依然留着(见下),照抄过来只会让我们白丢压缩收益;
+ *     调用方必须传"buf 是否已编码",dsh-bridge 的 doHttp 因此**固定传空串**。
+ *     若哪天 buf 真是一段未解压的字节流,调用方才应把对应编码传进来(函数会保守放弃压缩)。
  *   - 请求 Accept-Encoding 含 gzip(手机浏览器必带;没有就不压,避免手机不会解压);
  *   - content-type 可压缩(排除 text/event-stream);
  *   - gzip 后确实更小(极小文件/不可压数据 gzip 反而更大,保守判断)。
@@ -565,6 +577,97 @@ export async function maybeCompressResponse({ buf, contentType, contentEncoding,
   return { buf: out, headers: { "content-encoding": "gzip" } };
 }
 
+/**
+ * 进行中的 SSE 流:frameId → AbortController。
+ * 手机侧断开时,中继会发 `http-abort`,这里据此掐掉上游(否则电脑上会留一条永不结束的连接)。
+ */
+const streamAborts = new Map();
+
+/**
+ * 中继在 `tunnel-register-ok` 里声明支持的**追加帧能力**。
+ *
+ * 为什么必须协商:browser→中继→bridge 是两段**独立升级**的链路。
+ * 新 bridge 的流式帧(`http-chunk`/`http-end`)对**旧中继**是不认识的 —— 旧中继会把
+ * "仅头部"帧当成一个完整的空响应直接 `end()`,SSE 于是变成"秒断 + 浏览器狂重连",
+ * 比原来的 120 秒挂起**更糟**。所以能力由中继声明:拿不到 `http-stream` 就老实退回
+ * 旧的整包缓冲行为(慢,但正确)。默认空集合 = 保守(连不上/旧中继都不冒险用新帧)。
+ */
+const routerCaps = new Set();
+
+/**
+ * SSE(`text/event-stream`)流式转发。
+ *
+ * 为什么必须流式:`doHttp` 是「整包 `await res.arrayBuffer()`」的语义,而 SSE **永不结束** ——
+ * 实测 DSH 的 `/plugins/events`(client-hmr 的事件通道)每次页面加载都把这条请求挂满
+ * bridge 的 120s 上游超时,然后报错;浏览器 EventSource 立刻重连,于是手机端 Network 里
+ * **永远有一条转圈的请求**,页面也始终拿不到事件。
+ *
+ * 帧协议(对中继**追加**、与既有 `http` 帧并存;不认识 streaming 的旧中继只会忽略后续
+ * chunk,退化成"空 body 后结束",不会把页面打挂):
+ *   ← { id, type:"http",       status, headers, streaming:true }  仅头部,无 body
+ *   ← { id, type:"http-chunk", seq, body, bodyBase64:true }       0..n 次
+ *   ← { id, type:"http-end",   seq }                              流结束(含出错收尾)
+ *   → { id, type:"http-abort" }                                   手机断开 → 掐上游
+ *
+ * ⚠️ E2EE 路径**不**走这里:信封是"一问一答"的结构,SSE 要逐块封/解需要另立协议;
+ *    而现实里 SSE 由 `EventSource` 发出、shim 不接管它(不带头部信封标记),
+ *    所以密文流根本不存在 —— 真要做时再单独设计,不要在这里偷偷降级成明文。
+ *
+ * @returns {Promise<{status:number, chunks:number, bytes:number, aborted?:boolean}>}
+ */
+async function doHttpStream(send, id, method, path, reqHeaders) {
+  const safe = safePath(path);
+  if (safe === null) throw new Error("非法路径");
+  const reqHdrs = sanitizeRequestHeaders(reqHeaders);
+  const ck = harnessCookieOf(); // 新版 dsh web 的浏览器会话 Cookie(否则 401 白页)
+  if (ck) reqHdrs.Cookie = ck;
+  const controller = new AbortController();
+  streamAborts.set(id, controller);
+
+  let res;
+  try {
+    res = await fetch(`${UPSTREAM}${safe}`, { method, headers: reqHdrs, signal: controller.signal });
+  } catch (e) {
+    streamAborts.delete(id);
+    throw e; // 头部都还没发出去 → 交给调用方回一个普通错误帧
+  }
+
+  const status = res.status;
+  // 头部帧:告诉中继"这是一条流",随后才逐块推 body
+  send({
+    id,
+    type: "http",
+    status,
+    headers: sanitizeResponseHeaders(Object.fromEntries(res.headers.entries())),
+    streaming: true
+  });
+
+  let seq = 0;
+  let bytes = 0;
+  try {
+    const reader = res.body && typeof res.body.getReader === "function" ? res.body.getReader() : null;
+    if (reader) {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value || value.length === 0) continue;
+        bytes += value.length;
+        send({ id, type: "http-chunk", seq: ++seq, body: Buffer.from(value).toString("base64"), bodyBase64: true });
+      }
+    }
+  } catch (e) {
+    // 头部已经发出去了:这里**绝不能**抛(调用方会用普通帧回 502,而中继那边响应头已定,
+    // 再写一次 head 会炸)。统一以 http-end 收尾,让 EventSource 按自己的节奏重连。
+    const aborted = controller.signal.aborted === true;
+    streamAborts.delete(id);
+    send({ id, type: "http-end", seq, ...(aborted ? { aborted: true } : { error: String(e?.message || e) }) });
+    return { status, chunks: seq, bytes, aborted };
+  }
+  streamAborts.delete(id);
+  send({ id, type: "http-end", seq });
+  return { status, chunks: seq, bytes };
+}
+
 async function doHttp(method, path, reqHeaders, body, isB64) {
   const safe = safePath(path);
   if (safe === null) throw new Error("非法路径");
@@ -624,7 +727,14 @@ async function doHttp(method, path, reqHeaders, body, isB64) {
   const compressed = await maybeCompressResponse({
     buf,
     contentType,
-    contentEncoding: res.headers.get("content-encoding") || "",
+    // 🔴 必须传空:这里的 `buf` 是 **undici 已经解压过**的明文,不是上游线速字节。
+    //    以前传的是 `res.headers.get("content-encoding")` —— 而 undici 解压之后**仍会把该头留着**
+    //    (本文件 sanitizeResponseHeaders 的注释正是这么写的:"undici 已自动解压 body,
+    //     content-encoding/length 会误导浏览器")。于是 maybeCompressResponse 看到 "gzip"
+    //    就保守地 `return null`,**永不重压** —— 实测代价:线上 dsh web 的 `/plugins/??`
+    //    聚合包本来 gzip 后 5.12MB,被原样发出 13.39MB(2.6×),免费档 1Mbps 下从 40 秒变成 100+ 秒。
+    //    传空之后语义才是自洽的:"我手上这份 buf 是未编码的明文,可以压"。
+    contentEncoding: "",
     acceptEncoding: headerValue(reqHeaders, "accept-encoding"),
     status: res.status,
     method
@@ -693,6 +803,13 @@ export async function handleHttpFrame(dchOrSend, frame) {
     }
   }
   try {
+    // SSE 必须流式转发(否则会挂满 120s 超时,见 doHttpStream 注释)。
+    // 客户端是 EventSource 时必带 Accept: text/event-stream,以此为准(不看路径白名单,免得漏)。
+    if (routerCaps.has("http-stream") && String(headerValue(headers, "accept") || "").includes("text/event-stream")) {
+      const s = await doHttpStream(send, id, method, path, headers);
+      console.log(`[bridge] ${method} ${path} → SSE ${s.status} (${Date.now() - t0}ms, ${s.chunks} 块 / ${(s.bytes / 1024).toFixed(1)}KB${s.aborted ? ", 手机已断开" : ""})`);
+      return;
+    }
     const reply = await doHttp(method, path, headers, body, !!isB64);
     reply.id = id;
     reply.type = "http";
@@ -1157,6 +1274,9 @@ function connectTunnel(token) {
     try {
       receive(raw, (frame) => {
         if (frame?.type === "tunnel-register-ok") {
+          // 记下中继声明的追加帧能力(旧中继不带 caps → 空集合 → 退回整包缓冲,见 routerCaps 注释)
+          routerCaps.clear();
+          for (const c of Array.isArray(frame.caps) ? frame.caps : []) routerCaps.add(String(c));
           // 中继注册成功 = 手机端此刻真的能进这台电脑:面板据此把阶段推进到 online(已连接 ✅)
           persistBridgeState({ device_id: DEVICE_ID, tunnel_registered_at: Date.now(), phase: "online", last_error: null });
           console.log(`[bridge] ✅ router 注册成功: ${DEVICE_ID},等待手机访问 /remote/${DEVICE_ID}/`);
@@ -1172,6 +1292,7 @@ function connectTunnel(token) {
     } catch (e) { console.log(`[bridge] 隧道帧错误: ${e.message}`); }
   });
   ws.on("close", (code, reason) => {
+    routerCaps.clear(); // 换中继/断线:能力重新协商,期间一律退回保守行为
     clearInterval(heartbeat);
     console.log(`[bridge] 隧道断开(code=${code}${reason ? ", " + reason : ""})`);
     closeAllWsSessions();

package/packages/dsh-remote-web/runtime/clients/dsh-remote/mobile-adapter.mjs

@@ -1096,6 +1096,36 @@ const SCRIPT = `(() => {
       } catch (e8) { /* 引导条失败绝不能影响主功能 */ }
     };
 
+    /* 适配层自己创建的「抽屉入口」引用(汉堡按钮 / 遮罩),提到 boot() 外层保存。
+       为什么必须提到外层:官方 SPA 重渲染时会整片替换 body 子树,把这两个节点一起冲掉;
+       留住引用才能在下面的「存在性看门狗」里把**同一个节点**补回去(节点不变 → 挂在它上面的
+       click 处理、CSS 类、aria 属性全都原样保留,不会出现"补回来点不动"的假按钮)。 */
+    let maHamburger = null, maScrim = null;
+
+    /* 节点是否已经脱离文档。判不出来时一律当作"还在"—— 宁可不补,也绝不重复插入。 */
+    const maDetached = (el) => {
+      if (!el) return false;
+      try { if (typeof el.isConnected === "boolean") return !el.isConnected; } catch (eConn) { /* 继续退化 */ }
+      try {
+        const b = document.body;
+        if (b && typeof b.contains === "function") return !b.contains(el);
+      } catch (eHas) { /* 继续退化 */ }
+      return false;
+    };
+
+    /* —— 存在性看门狗:「建好了」不等于「一直都在」----------------------------------
+       done=true 只保证**曾经**建出来过。官方在路由/会话切换时会重建 DOM 子树,我们的汉堡按钮
+       与遮罩会跟着消失 —— 用户看到的就是"抽屉按钮用着用着又没了"。
+       这里按**引用**补回(不是重建),只在窄屏做(宽屏本来就不需要抽屉入口)。
+       幂等:节点还在文档里 → 什么都不做;boot 还没成功(引用为 null) → 同样什么都不做。 */
+    const ensureDrawerChrome = () => {
+      try {
+        if (!NARROW() || !document.body) return;
+        if (maDetached(maScrim)) document.body.appendChild(maScrim);
+        if (maDetached(maHamburger)) document.body.appendChild(maHamburger);
+      } catch (eChrome) { /* 补不回去也不能影响抽屉开合本身 */ }
+    };
+
     let done = false;
     const boot = () => {
       if (!HOSTISH()) return;
@@ -1228,6 +1258,7 @@ const SCRIPT = `(() => {
       const scrim = document.createElement("div");
       scrim.className = "dsh-ma-scrim";
       document.body.appendChild(scrim);
+      maScrim = scrim;                          // 供「存在性看门狗」在被官方冲掉后补回
       scrim.addEventListener("click", (e) => {
         e.stopPropagation();
         userWantsOpen = false;                    // 用户明确要关(遮罩的作用就是关抽屉)
@@ -1245,6 +1276,7 @@ const SCRIPT = `(() => {
       hamburger.setAttribute("aria-label", "打开菜单");
       hamburger.innerHTML = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h10"/></svg>';
       document.body.appendChild(hamburger);
+      maHamburger = hamburger;                  // 供「存在性看门狗」在被官方冲掉后补回
       hamburger.addEventListener("click", (e) => {
         e.stopPropagation(); e.preventDefault();
         const nowOpen = document.documentElement.classList.contains("dsh-ma-sidebar-open");
@@ -1516,10 +1548,82 @@ const SCRIPT = `(() => {
     };
 
     if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot); else boot();
-    /* 官方模块系统异步挂载 UI,晚一点再补几次(幂等,done 守卫);同时等鲸鱼/设置弹层就位 */
-    [700, 1600, 3200, 7000, 12000].forEach((ms) =>
-      setTimeout(() => { try { boot(); whaleHookInit(); watchSettings(); } catch (e) { /* 幂等重试 */ } }, ms)
-    );
+
+    /* ================= 执行时机:无限期等待官方 DOM 就绪 =================
+       用户实测原话(2026-09-2x):「在网络比较慢的情况下,左边的抽屉按钮有时候出不来。
+                                   甭管网络有多慢,都要让那个抽屉能加载出来。」
+       ⚠️ 旧实现是**一组写死的固定重试**([700, 1600, 3200, 7000, 12000]ms),而汉堡按钮的创建
+          排在 boot() 里 "if (!frame) return;" 那一行之后 —— 官方 SPA bundle 有 13.4MB(实测未压缩),
+          免费档被中继限速到 128KB/s 时冷启动要 1-2 分钟,官方 frame 在 12 秒内根本没出现:
+          5 次重试全部在那一行返回 → done 永远为 false → 汉堡按钮**永远**不创建
+          → 用户看到"左边抽屉按钮出不来"。任何固定窗口都只是把这个阈值往后挪,治不了根。
+       现在改成「事件驱动 + 低频兜底」的**无限期**等待,只要抽屉入口还没建好就一直试:
+         · MutationObserver(document/subtree):官方 frame 一挂上就立刻跟上(网络快时零延迟);
+         · setInterval(1000ms):兜底 + 存在性看门狗 —— observer 不可用/被绕过时照样收敛,
+           也负责在 done 之后发现官方重渲染冲掉了我们的节点并补回。
+       两条路都只是"再调一次 pump()",pump 内部**全部幂等**(done / fabDone / whaleGuardsOn /
+       settingsWatchOn / drawerAutoCloseOn 等守卫都在),重复调用不会产生任何副作用,
+       也不改变"执行什么"——开合、遮罩不变量、sync()、isDrawer() 判定一行未动。 */
+    let maTorn = false, maInterval = 0, maObserver = null, maRafPending = false;
+    /* 廉价的"boot() 还有事可做吗"闸门(只读两个现成的布尔标志,不做任何 DOM 操作):
+         · fab 还没建出来(fabDone=false) → 要跑;
+         · 抽屉那段还没建好(done=false)且当前是窄屏 → 要跑(旋转/缩放回窄屏也能补建)。
+       两者都不成立 → boot() 里已无事可做,**绝不能**再跑:boot() 第一行 HOSTISH() 会把
+       documentElement.outerHTML 整个序列化一遍(最长 200KB),而官方流式输出时每帧都有 DOM
+       变更 —— 没有这道闸门就会变成每秒几十次全量序列化(旧实现只跑 5 次,不会有这个问题)。 */
+    const bootUseful = () => !fabDone || (!done && NARROW());
+    const pump = () => {
+      if (maTorn) return;
+      if (bootUseful()) { try { boot(); } catch (eBoot) { /* 幂等重试 */ } }
+      try { ensureDrawerChrome(); } catch (eChrome2) { /* 忽略 */ }
+      if (!whaleGuardsOn || !settingsWatchOn) {
+        try { whaleHookInit(); watchSettings(); } catch (eHook) { /* 两者内部都自带一次性守卫 */ }
+      }
+    };
+    /* 节流:一次 DOM 变更往往产生几十条记录,逐条 boot() 就是忙轮询。
+       统一合并成"本帧最多跑一次"(有 rAF 用 rAF,没有就退化成 0ms 宏任务) —— 天然去重。 */
+    const schedulePump = () => {
+      if (maTorn || maRafPending) return;
+      maRafPending = true;
+      const run = () => { maRafPending = false; pump(); };
+      try { if (typeof requestAnimationFrame === "function") { requestAnimationFrame(run); return; } } catch (eRaf) { /* 退化 */ }
+      setTimeout(run, 0);
+    };
+    /* 挂上"叫醒"的两条路。做成可重入(先清旧的再建新的),这样 bfcache 恢复后能重新武装。 */
+    const maArm = () => {
+      maTorn = false;
+      maRafPending = false;            // 冻结时若有一帧没跑到,不清掉就会永远挡住后续调度
+      try { if (maObserver) maObserver.disconnect(); } catch (eA1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eA2) { /* 忽略 */ }
+      maInterval = 0;
+      try {
+        if (typeof MutationObserver === "function" && document.documentElement) {
+          maObserver = new MutationObserver(schedulePump);
+          /* 只观察 childList+subtree:节点被官方换掉/新增才叫醒我们。
+             ⚠️ 刻意**不**观察 attributes —— 我们自己的 sync() 就会不停改 class,那会变成自激循环。 */
+          maObserver.observe(document.documentElement, { childList: true, subtree: true });
+        }
+      } catch (eObs) { maObserver = null; /* 退化:只靠下面的兜底表 */ }
+      try { maInterval = setInterval(pump, 1000); } catch (eInt) { maInterval = 0; }
+    };
+    maArm();
+    /* 清理:页面卸载时断开观察者与兜底表(bfcache/长驻页面都不留悬挂回调)。
+       pagehide 覆盖 bfcache 场景,unload 兜底更老的浏览器。 */
+    const maTeardown = () => {
+      maTorn = true;
+      try { if (maObserver) maObserver.disconnect(); } catch (eD1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eD2) { /* 忽略 */ }
+      maInterval = 0;
+    };
+    try { window.addEventListener("pagehide", maTeardown); } catch (ePh) { /* 忽略 */ }
+    try { window.addEventListener("unload", maTeardown); } catch (eUl) { /* 忽略 */ }
+    /* 手机上"切到别的 App 再切回来"走的常是 bfcache:pagehide(persisted=true) → pageshow(persisted=true)。
+       DOM 原样保留但计时器/观察者已断 —— 这里重新武装,否则回到页面后看门狗就永久失灵了。 */
+    try {
+      window.addEventListener("pageshow", (ev) => { try { if (ev && ev.persisted) maArm(); } catch (ePs) { /* 忽略 */ } });
+    } catch (ePs2) { /* 忽略 */ }
   } catch (e) { if (window.console) console.warn("[dsh-mobile-adapter]", e && e.message); }
 })();`;