dsh-mobile-plugin 0.1.92 → 0.1.94

package/lib/reconnect-scheduler.cjs

@@ -9,20 +9,47 @@
  *
  * 这里把「同一个待触发窗口内只保留一个定时器」这一不变量收敛成一个模块，
  * 以便用毫秒级延迟做真实的行为测试。端到端数连接次数是分不出来的：
- * 生产里延迟固定 5s，且 startTunnel 开头的 stopTunnel 会吸收重复定时器
- * 造成的大部分可见差异。
+ * startTunnel 开头的 stopTunnel 会吸收重复定时器造成的大部分可见差异。
+ *
+ * 延迟本身带**抖动**与**退避**：
+ *  - 抖动：中转重启（或宿主机休眠醒来）之后，所有宿主都会在同一刻掉线，固定 5s 会让
+ *    它们踩着同一个点回来；上下抖两千毫秒就把这一波摊开。
+ *  - 退避：连续失败（中转没起来、注册密钥不对）时不该每 5 秒敲一次，逐次翻倍到上限；
+ *    一次成功的注册由调用方 `reset()` 清账。
  */
-function createReconnectScheduler({ delayMs, onFire, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+
+/** 连续失败最多翻到 delayMs 的 2^BACKOFF_EXP_CAP 倍（再被 maxDelayMs 压住）。 */
+const BACKOFF_EXP_CAP = 5
+
+function createReconnectScheduler({
+  delayMs,
+  jitterMs = 0,
+  maxDelayMs = Number.POSITIVE_INFINITY,
+  random = Math.random,
+  onFire,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
   if (typeof delayMs !== 'number' || !(delayMs >= 0)) throw new Error('invalid delayMs')
+  if (typeof jitterMs !== 'number' || !(jitterMs >= 0)) throw new Error('invalid jitterMs')
+  if (typeof maxDelayMs !== 'number' || !(maxDelayMs > 0)) throw new Error('invalid maxDelayMs')
+  if (typeof random !== 'function') throw new Error('invalid random')
   if (typeof onFire !== 'function') throw new Error('invalid onFire')
   let timer = null
+  let misses = 0
   return {
     /** 排程一次重连；已有待触发的定时器时返回 false，表示被幂等吸收。 */
     schedule() {
       if (timer !== null) return false
-      timer = setTimer(() => { timer = null; onFire() }, delayMs)
+      const backoff = misses === 0 ? 1 : 2 ** Math.min(misses, BACKOFF_EXP_CAP)
+      const base = Math.min(delayMs * backoff, maxDelayMs)
+      const wait = base + (jitterMs > 0 ? Math.floor(random() * jitterMs) : 0)
+      misses += 1
+      timer = setTimer(() => { timer = null; onFire() }, wait)
       return true
     },
+    /** 连上之后清掉连续失败计数（下一次掉线重新从 delayMs 起算）。 */
+    reset() { misses = 0 },
     /** 取消待触发的重连（显式停止隧道时调用）。 */
     cancel() {
       if (timer === null) return

package/lib/relay/lan-network.cjs

@@ -1,7 +1,12 @@
 /**
- * 网卡枚举与候选地址：私网 / 公网两份清单，外加「用户选中的那条排最前」。
+ * 网卡枚举与候选地址：私网 / 公网 / IPv6 全球单播三份清单，外加「用户选中的那条排最前」。
  *
  * 收口在这一个文件里，是因为 App 只认「按顺序挨个试」这一种语义 —— 顺序就是优先级。
+ *
+ * 三份的区别在**手机在哪**：私网那份是「同一个 Wi-Fi 里能直连」，公网那份是「这台机器
+ * 自己就挂在公网上」，IPv6 那份是「手机在别的网络里、从公网拨过来」——最后这份是 2026-10
+ * 新加的，它**不并进前两份**，因为 App 对它的用法完全不同（要和公网中转比速度，见
+ * `ipv6Candidates` 的注释）。
  */
 'use strict'
 
@@ -94,13 +99,19 @@ function interfaceRank(name) {
 }
 
 /**
- * 扫一遍网卡，把 `accept` 认的 IPv4 地址收成候选（剔除虚拟/VPN 网卡、按物理网卡优先级
- * 排序、去重、最多 16 条）。
+ * 扫一遍网卡，把 `accept` 认的、属于 `family` 的地址收成候选（剔除虚拟/VPN 网卡、按物理
+ * 网卡优先级排序、去重、最多 16 条）。
+ *
+ * 三份清单共用这一段：差别**只在 accept 与 family**——一个挑私网 v4、一个挑公网 v4、
+ * 一个挑全球单播 v6。网卡黑名单与排序规则必须一模一样，否则同一台机器上几份候选会给出
+ * 互相矛盾的顺序。
  *
- * `lanInterfaces` 与 `publicInterfaces` 共用这一段：两者的差别**只在 accept**——一个挑私网、
- * 一个挑公网。网卡黑名单与排序规则必须一模一样，否则同一台机器上两份候选会给出互相矛盾的顺序。
+ * 去重按 `key`：IPv4 是地址本身，IPv6 是解出来的数值 —— 同一个地址的压缩写法、展开写法
+ * 与大小写（`240e::1` / `240E:0:0:0:0:0:0:1`）必须算成一条，否则 App 会为同一个地址
+ * 各探一次。
  */
-function collectEndpoints(interfaces, accept) {
+function collectEndpoints(interfaces, accept, family = 'IPv4') {
+  const wantV6 = family === 'IPv6'
   const found = []
   let order = 0
   for (const [name, entries] of Object.entries(interfaces || {})) {
@@ -108,24 +119,46 @@ function collectEndpoints(interfaces, accept) {
     if (isVpnInterface(name) || isVirtualInterface(name)) continue
     for (const entry of entries || []) {
       if (!entry || entry.internal) continue
-      if (entry.family !== 'IPv4' && entry.family !== 4) continue
+      // family 必须**显式**对上：缺字段的畸形条目不参与任何一份清单
+      // （`test/lan-network.test.cjs` 的「空 / 异常入参不抛错」钉着这一条）。
+      const entryV6 = entry.family === 'IPv6' || entry.family === 6
+      const entryV4 = entry.family === 'IPv4' || entry.family === 4
+      if (wantV6 ? !entryV6 : !entryV4) continue
       if (!accept(entry.address)) continue
-      found.push({ name, address: entry.address, order: current })
+      found.push({
+        name,
+        address: entry.address,
+        order: current,
+        key: wantV6 ? String(ipv6Number(entry.address)) : entry.address,
+      })
     }
   }
   const seen = new Set()
   return found
     .sort((a, b) => interfaceRank(a.name) - interfaceRank(b.name) || a.order - b.order)
     .filter((item) => {
-      if (seen.has(item.address)) return false
-      seen.add(item.address)
+      if (seen.has(item.key)) return false
+      seen.add(item.key)
       return true
     })
     .slice(0, 16)
 }
 
-function toCandidates(list, port) {
-  return list.map((item) => ({ url: `http://${item.address}:${port}`, interface: item.name, family: 'IPv4', address: item.address }))
+/**
+ * 产候选。IPv6 在 URL 里**必须带方括号**（`http://[240e::1]:18787`），裸着写出来是
+ * `http://240e::1:18787` —— 一个解析不出来的坏地址。
+ *
+ * `address` 字段刻意**不带**方括号：面板的「手机优先用这条」是按地址匹配的
+ * （`orderCandidates`），用户看到与填进去的都是裸地址。
+ */
+function toCandidates(list, port, family = 'IPv4') {
+  const v6 = family === 'IPv6'
+  return list.map((item) => ({
+    url: `http://${v6 ? `[${item.address}]` : item.address}:${port}`,
+    interface: item.name,
+    family,
+    address: item.address,
+  }))
 }
 
 // Structured view of the usable LAN endpoints. The relay's `normalizeLanMetadata`
@@ -185,6 +218,112 @@ function publicCandidates(port, interfaces = os.networkInterfaces()) {
   return publicInterfaces(port, interfaces)
 }
 
+/**
+ * 把 IPv6 文本解成 8 段 16 位十六进制，处理内嵌 IPv4 尾巴、压缩写法与 zone id。
+ * 解不出来一律回 null —— 判据函数宁可不认，也不能把一串看不懂的东西当地址发出去。
+ */
+function ipv6Groups(text) {
+  const [head, tail, ...rest] = text.split('::')
+  if (rest.length) return null
+  const toGroups = (part) => (part === '' ? [] : part.split(':'))
+  const headGroups = toGroups(head)
+  const tailGroups = tail === undefined ? [] : toGroups(tail)
+  // 内嵌 IPv4 尾巴（`::ffff:192.168.1.1`、`64:ff9b::1.2.3.4`）折成两段。
+  const last = tailGroups.length ? tailGroups : headGroups
+  const embedded = last.length ? last[last.length - 1] : ''
+  if (embedded.includes('.')) {
+    const value = ipv4Number(embedded)
+    if (value === null) return null
+    last.splice(last.length - 1, 1, ((value >>> 16) & 0xffff).toString(16), (value & 0xffff).toString(16))
+  }
+  const isHexGroup = (group) => /^[0-9a-f]{1,4}$/.test(group)
+  if (![...headGroups, ...tailGroups].every(isHexGroup)) return null
+  if (tail === undefined) return headGroups.length === 8 ? headGroups : null
+  const fill = 8 - headGroups.length - tailGroups.length
+  if (fill < 1) return null
+  return [...headGroups, ...Array(fill).fill('0'), ...tailGroups]
+}
+
+/** IPv6 文本 → 128 位数值；非法回 null。方括号与 `%en0` 这类 zone id 都先剥掉。 */
+function ipv6Number(address) {
+  const text = String(address === null || address === undefined ? '' : address)
+    .trim()
+    .toLowerCase()
+    .replace(/^\[/, '')
+    .replace(/\]$/, '')
+    .split('%')[0]
+  if (!text.includes(':')) return null
+  const groups = ipv6Groups(text)
+  if (!groups) return null
+  let value = 0n
+  for (const group of groups) value = (value << 16n) | BigInt(parseInt(group, 16))
+  return value
+}
+
+function inV6Prefix(value, prefix, length) {
+  const shift = BigInt(128 - length)
+  return value >> shift === prefix >> shift
+}
+
+/**
+ * 值得上报的 IPv6 地址：**全球单播**（`2000::/3`）且不是下面这三种假公网。
+ *
+ *   - `2002::/16`（6to4）：地址里的那截 IPv4 要靠一台公网中继转，今天基本没人还在跑中继，
+ *     报出去就是一个拨不通的地址；
+ *   - `2001::/32`（Teredo）：隧道端点，本身不是能直接连的服务地址；
+ *   - `2001:db8::/32`：文档示例段。
+ *
+ * 其余非全球单播的一律不收：链路本地（`fe80::/10`）只在本链路内通，手机拿不到；
+ * ULA（`fc00::/7`）要同一个内网前缀，手机同样拿不到 —— 报了都是死地址；已废弃的站点本地
+ * `fec0::/10`、组播、回环、未指定、IPv4-mapped 同理。
+ *
+ * **不做**的事：不猜哪条是 RFC 4941 临时地址（`os.networkInterfaces()` 根本不暴露这个标志，
+ * 硬造的判据只会误伤稳定地址）。同一块网卡上并存的一条稳定地址与两条临时地址会一起报出去
+ * ——临时地址也是全球单播、当下也真的能连，等它轮换掉时 App 早就在下一轮发现里拿到新清单了。
+ */
+const V6_GLOBAL_UNICAST = [ipv6Number('2000::'), 3]
+const V6_NOT_GLOBAL = [
+  ['2002::', 16],
+  ['2001::', 32],
+  ['2001:db8::', 32],
+].map(([spec, length]) => [ipv6Number(spec), length])
+
+function isGlobalUnicastV6(address) {
+  const value = ipv6Number(address)
+  if (value === null) return false
+  if (!inV6Prefix(value, V6_GLOBAL_UNICAST[0], V6_GLOBAL_UNICAST[1])) return false
+  return !V6_NOT_GLOBAL.some(([prefix, length]) => inV6Prefix(value, prefix, length))
+}
+
+/**
+ * IPv6 全球单播候选：手机**不在同一个 Wi-Fi 里**时唯一有可能直连进来的地址。
+ *
+ * 为什么单独一份、不并进 `lanInterfaces`：那份的语义是「手机在同一 Wi-Fi 里能直连」，
+ * App 对它的处理是「在网就在、不在就连不上」——共用退避窗口的话，手机刚离开家里 Wi-Fi
+ * 的那一刻（正是最该试 IPv6 的时刻）局域网一进退避就把 IPv6 一起压住了。App 侧对应一条
+ * 独立通道，还要拿它和公网中转**比速度**，所以这里只负责如实产出、不去猜哪条更快。
+ *
+ * 最多 4 条：这台机器上通常是一到三条（一条稳定地址 + 一两条临时地址）。上限是为了二维码
+ * ——候选是随二维码一起带走的，条数一多二维码就密到扫不动。
+ */
+const IPV6_CANDIDATE_MAX = 4
+function ipv6Interfaces(port, interfaces = os.networkInterfaces()) {
+  return toCandidates(collectEndpoints(interfaces, isGlobalUnicastV6, 'IPv6'), port, 'IPv6')
+    .slice(0, IPV6_CANDIDATE_MAX)
+}
+function ipv6Urls(port, interfaces = os.networkInterfaces()) {
+  return ipv6Interfaces(port, interfaces).map((candidate) => candidate.url)
+}
+function ipv6Candidates(port, interfaces = os.networkInterfaces()) {
+  // 与 `advertisedCandidates` 同一条口径：取不到网卡（异常）时回空清单、绝不抛 —— 它喂的
+  // 也是二维码与 `/connection-info`，把它整条控制面拖下水不值得。
+  try {
+    return ipv6Interfaces(port, interfaces)
+  } catch {
+    return []
+  }
+}
+
 /**
  * 对外公布的候选地址：**先私网，一个都没有时才退到公网**。
  *
@@ -234,9 +373,11 @@ function orderCandidates(list, preferred) {
 
 module.exports = {
   ipv4Number,
+  ipv6Number,
   isPrivateLanAddress,
   isLanCandidateAddress,
   isPublicAddress,
+  isGlobalUnicastV6,
   isVpnInterface,
   isVirtualInterface,
   interfaceRank,
@@ -246,6 +387,9 @@ module.exports = {
   publicInterfaces,
   publicUrls,
   publicCandidates,
+  ipv6Interfaces,
+  ipv6Urls,
+  ipv6Candidates,
   advertisedCandidates,
   orderCandidates,
 }

package/lib/relay/lan-proxy.js

@@ -14,8 +14,10 @@
 const http = require('node:http');
 const { WebSocketServer, WebSocket } = require('ws');
 const core = require('./core.js');
+const { isGlobalUnicastV6 } = require('./lan-network.cjs');
 const { safeEqual } = require('../shared/dshtoken');
 const { isFreshRequest } = require('../shared/fresh-request');
+const { encodeJsonBody } = require('../shared/http-util');
 const credentials = require('../shared/credentials-entry.js').credentialsEntry();
 
 const HOP_BY_HOP = new Set([
@@ -62,6 +64,8 @@ function createLanProxy(opts) {
   } = opts;
 
   let server = null;
+  // IPv6 那条监听（`::`，ipv6Only）。它可能压根没建立（机器没有 IPv6），所以单独存一份。
+  let v6Server = null;
   let wss = null;
   // 活着的上游请求计数（自检台账与失控闸消费）：见 proxyToUpstream 的拆除注释。
   let upstreamOpen = 0;
@@ -76,6 +80,11 @@ function createLanProxy(opts) {
   function log(...args) {
     onLog('[lan-proxy]', ...args);
   }
+  /** 日志里的监听地址：IPv6 按 URL 习惯套方括号（`[::]`），IPv4 原样。 */
+  function formatHost(host) {
+    const text = String(host);
+    return text.includes(':') ? `[${text}]` : text;
+  }
 
   function isPairLocked(ip) {
     const l = pairLocks.get(ip);
@@ -192,8 +201,15 @@ function createLanProxy(opts) {
     const body = isFreshRequest(req.url) ? null : readSnapshot({ method: req.method, path: req.url });
     if (body && body.ok) {
       try {
-        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
-        res.end(JSON.stringify(body));
+        // 与中转那条同一条捷径：列表 / 工作区 / 消息 / 统计都在这里回，压缩才省得下来。
+        const encoded = encodeJsonBody(JSON.stringify(body), req.headers['accept-encoding']);
+        res.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8',
+          'cache-control': 'no-store',
+          vary: 'accept-encoding',
+          ...(encoded.gzip ? { 'content-encoding': 'gzip' } : {}),
+        });
+        res.end(encoded.body);
       } catch { /* 已关闭 */ }
       return;
     }
@@ -425,11 +441,31 @@ function createLanProxy(opts) {
 
   function start() {
     return new Promise((resolve, reject) => {
-      server = http.createServer((req, res) => {
+      /**
+       * v4 / v6 两条监听共用的请求处理器。协议族只影响 `req.socket.remoteAddress` 的
+       * 形状（IPv4 是 `::ffff:a.b.c.d` 或 `a.b.c.d`，IPv6 是原生地址），路由与鉴权完全一致。
+       */
+      const handleRequest = (req, res) => {
         const url = new URL(req.url, 'http://lan.local');
         try {
           if (url.pathname === '/__lan_pair' && req.method === 'POST') {
             const ip = req.socket.remoteAddress || '';
+            // 双栈之后这个**不需要凭据**的接口在公网 IPv6 上也够得着，而它本来是「同一个
+            // Wi-Fi 内的手机直接配对」用的。原生全球单播 IPv6 来源一律按「配对码错误」回
+            // （`pairDenied`：JSON、401，与码错完全同形，不承认这个接口为谁而开）——刚好
+            // 也是地图 A3-12 那条刻意设计要的形状：未认证请求绝不能回 2xx，否则 App 会把
+            // 连接通道钉在直连并重置熔断，随后 json 解析失败，既不回退中转也不提示重配。
+            //
+            // 不记限流计数：按源地址计数在 IPv6 上等于按 /128 计数，换个源地址就是新桶，
+            // 记了没用、白留痕迹。
+            //
+            // 只收这一格：只有公网 IPv4 的机器上，手机经公网 IPv4 打进来的配对是**现有受
+            // 支持流程**（配对二维码里就带公网 IPv4 候选），判据必须是「原生全球 IPv6」
+            // 而不是「公网地址」——后者会把那条正常用法一起拦掉。判据在 lan-network.cjs。
+            if (isGlobalUnicastV6(ip)) {
+              pairDenied(res);
+              return;
+            }
             let b = '';
             req.on('data', (c) => (b += c));
             req.on('end', () => {
@@ -541,7 +577,9 @@ function createLanProxy(opts) {
             res.end('internal error');
           } catch { /* ignore */ }
         }
-      });
+      };
+
+      server = http.createServer(handleRequest);
 
       wss = new WebSocketServer({ noServer: true });
       server.on('upgrade', handleUpgrade);
@@ -565,7 +603,8 @@ function createLanProxy(opts) {
           server.on('error', (err) => log('server error:', err.message))
           const address = server.address()
           actualPort = address && typeof address.port === 'number' ? address.port : port
-          log(`listening on 0.0.0.0:${actualPort}`)
+          const boundHost = address && address.address ? address.address : '0.0.0.0'
+          log(`listening on ${formatHost(boundHost)}:${actualPort}`)
           onBound()
         }
         server.once('error', onError)
@@ -573,6 +612,40 @@ function createLanProxy(opts) {
         server.listen(port, '0.0.0.0')
       })
 
+      /**
+       * IPv6 那条监听：拿 IPv4 实绑的端口，`::` + **显式 `ipv6Only: true`**。
+       *
+       * 为什么不合成一条双栈监听：`impl.js` 的端口占用探测真去 `listen(port, '0.0.0.0')`
+       * 试探，一条双栈的 `::` 会把首选端口一律探成「被占」，于是落到内核随机端口并写盘，
+       * 端口每次启动都可能漂；反过来把探测也改成 `::`，关掉 IPv6 的机器上探测会因
+       * EAFNOSUPPORT 永远判「被占」，同样漂。各管一个协议族就没这个问题：`ipv6Only: true`
+       * 之后 v6 那个 socket 不碰 IPv4（不设这个标志在 Linux 上才会撞），同端口可以共存。
+       *
+       * 它是**软的**：只有「手机不在同一 Wi-Fi、只有 IPv6」时才用得上，绑不上就记一行、
+       * 只留 IPv4 直连——绝不影响 IPv4，也绝不往上抛。
+       */
+      const startV6 = () => new Promise((onDone) => {
+        const v6 = http.createServer(handleRequest);
+        v6.on('upgrade', handleUpgrade);
+        v6.once('error', (err) => {
+          log(`IPv6 监听未建立（${err.code || err.message}），只保留 IPv4 直连`);
+          onDone();
+        });
+        v6.once('listening', () => {
+          v6.on('error', (err) => log('IPv6 server error:', err.message));
+          v6Server = v6;
+          const address = v6.address();
+          log(`listening on ${formatHost(address.address)}:${address.port}`);
+          onDone();
+        });
+        try {
+          v6.listen(actualPort, '::', { ipv6Only: true });
+        } catch (err) {
+          log(`IPv6 监听未建立（${err.code || err.message}），只保留 IPv4 直连`);
+          onDone();
+        }
+      });
+
       // 端口自适应：首选端口在探测之后、真正 listen 之前被别的进程抢走时（另一个
       // 实例刚起、或者上一轮 stop() 还没释放干净），退到内核分配的空闲端口，而不是
       // 让一次 EADDRINUSE 把整条 LAN 直连带走。
@@ -580,10 +653,10 @@ function createLanProxy(opts) {
       // catch 分支根本不会执行，外层那个 Promise 就永远 pending——服务器确实在监听，
       // 但调用方拿到的 start() 永不落定，lan.state 永远停在 connecting、error 还是
       // null。端口回退是兜底，不是主路径。
-      bind(lanPort).then(() => resolve(), async (error) => {
+      bind(lanPort).then(async () => { await startV6(); resolve() }, async (error) => {
         if (!error || error.code !== 'EADDRINUSE') return reject(error);
         log(`port ${lanPort} busy (${error.code}), falling back to an OS-assigned port`);
-        try { await bind(0); resolve() } catch (retryError) { reject(retryError) }
+        try { await bind(0); await startV6(); resolve() } catch (retryError) { reject(retryError) }
       });
     });
   }
@@ -604,6 +677,11 @@ function createLanProxy(opts) {
       try { server.closeAllConnections?.(); } catch { /* ignore */ }
       server = null;
     }
+    if (v6Server) {
+      try { v6Server.close(); } catch { /* ignore */ }
+      try { v6Server.closeAllConnections?.(); } catch { /* ignore */ }
+      v6Server = null;
+    }
   }
 
   // 对外只暴露「实际在监听的端口」。配置端口仍是 `lanPort`（那只是首选值）。

package/lib/relay/protocol.js

@@ -11,11 +11,11 @@
  * - 控制消息（register / httpHead 等）payload 为 UTF-8 JSON；
  * - ping/pong 为应用层心跳（经代理/负载均衡时比 WS 原生 ping 更可靠）。
  *
- * 协议语义见 ../../../server/dsh-mobile-server/PROTOCOL.md（v2 章节）。
+ * 协议语义见 ../../../server/dsh-mobile-server/server/relay-core/PROTOCOL.md。
  *
  * 本文件是自包含副本（插件包不能跨目录引用中转仓库的文件），完整内联了共用类型表
- * 与编解码实现。类型表的事实源是 server/relay-core/protocol-types.js，
- * 由 dsh-mobile-plugin/test/protocol-parity.test.cjs 逐项对账；
+ * 与编解码实现。类型表的事实源在独立中转仓库的 server/relay-core/protocol-types.js；
+ * 本仓的 protocol-parity 测试钉住线格式，中转仓库另做 Rust 与 JS 字节对撞；
  * 改动帧编号后必须同步修改本文件。
  */
 

package/lib/relay/tunnel.js

@@ -14,6 +14,7 @@ const http = require('node:http');
 const { WebSocket } = require('ws');
 const { T, jsonFrame, encodeFrame, createFrameDecoder, parseJson, encodeClosePayload, decodeClosePayload } = require('./protocol.js');
 const { isFreshRequest } = require('../shared/fresh-request');
+const { encodeJsonBody } = require('../shared/http-util');
 
 const HEARTBEAT_INTERVAL_MS = 15_000;
 // Relay currently expires an idle tunnel after 60s. Keep a wider client-side
@@ -464,7 +465,10 @@ class RelayTunnel {
           fn(arg);
         }
       };
-      const ws = new WebSocket(this.relayUrl, { perMessageDeflate: true });
+      // 中转侧是 tokio-tungstenite 手写的 101，从不回 `sec-websocket-extensions`，
+      // 所以 permessage-deflate 一次都没协商成功过；开着只会让人以为隧道压过。
+      // 真省字节靠的是响应体的 gzip（见 lib/shared/http-util.js）。
+      const ws = new WebSocket(this.relayUrl);
       this.ws = ws;
       const timer = setTimeout(() => {
         done(reject, new Error('注册超时'));
@@ -572,9 +576,18 @@ class RelayTunnel {
         if (this.readSnapshot && !isFreshRequest(msg.path) && (msg.method === 'GET' || msg.method === undefined)) {
           const body = this.readSnapshot({ method: msg.method, path: msg.path });
           if (body && body.ok) {
-            const data = Buffer.from(JSON.stringify(body));
-            this.queueHttpResponseFrame(id, entry, T.httpHead, { status: 200, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } }, true);
-            this.queueHttpResponseFrame(id, entry, T.httpChunk, data);
+            // 这条捷径回的是列表 / 工作区 / 消息 / 统计这几条最重的读取，压缩的收益全在这儿。
+            const encoded = encodeJsonBody(JSON.stringify(body), msg.headers?.['accept-encoding']);
+            this.queueHttpResponseFrame(id, entry, T.httpHead, {
+              status: 200,
+              headers: {
+                'content-type': 'application/json; charset=utf-8',
+                'cache-control': 'no-store',
+                vary: 'accept-encoding',
+                ...(encoded.gzip ? { 'content-encoding': 'gzip' } : {}),
+              },
+            }, true);
+            this.queueHttpResponseFrame(id, entry, T.httpChunk, encoded.body);
             this.queueHttpResponseFrame(id, entry, T.httpEnd, Buffer.alloc(0));
             return;
           }

package/lib/routes/control-plane.js

@@ -28,9 +28,13 @@ const pairingApproval = require('../relay/pairing-policy.js');
 // 端口自检用的是局域网代理**同一把探针**（见 `../relay/port-allocator.cjs` 的文件头）：
 // 这里说「可用」，真正 listen 时就不会 EADDRINUSE，两边不会各说各话。
 const { canListen } = require('../relay/port-allocator.cjs');
-// 面板的「手机该填哪个地址」要两份：私网（lanCandidates）与公网（publicCandidates）。
-// 两者刻意分开，理由写在 lan-network.cjs 里那两个函数头上。
-const { lanCandidates, publicCandidates } = require('../relay/lan-network.cjs');
+// 面板的「手机该填哪个地址」要三份：私网（lanCandidates）、公网（publicCandidates）与
+// IPv6 全球单播（ipv6Candidates）。三者刻意分开，理由写在 lan-network.cjs 里那三个函数头上。
+//
+// ⚠️ 面板里**能被选中的**那份仍然只能是 `lan`（没有私网时才退 `public`）——它与
+// `advertisedCandidates` 同口径。IPv6 那份只**显示**、不进那个选择：它由手机侧实测择优
+// （和公网中转比速度），做成可选中等于骗人（同 A3-40 的刻意设计）。
+const { lanCandidates, publicCandidates, ipv6Candidates } = require('../relay/lan-network.cjs');
 const desktopView = require('../desktop-view.cjs');
 const readReceipt = require('../read-receipt.cjs');
 // 客户端半边的活体台账：两条绿点同步通道都是「单向轮询 + 无回执」，不记账就永远分不开
@@ -289,7 +293,7 @@ function registerControlPlaneRoutes(deps) {
   // 控制面状态里额外带上面板页的绝对地址：客户端半边（lib/client.js）那一项现在只是
   // 一个「打开配置页面」的入口，链接必须是绝对的（原因见 panelUrlOf）。地址只在这里
   // 补，不动 createStatusView —— 那份 JSON 手机端也在读，127.0.0.1 的地址对它没意义。
-  // 面板的「手机该填哪个地址」：把检测到的网卡地址按**局域网 / 公网**分成两份报出来，
+  // 面板的「手机该填哪个地址」：把检测到的网卡地址按**局域网 / 公网 / IPv6**分成三份报出来，
   // 用户不用自己去 `ipconfig`，界面也能一眼看出该填哪个（引导第三、四页用它）。
   //
   // 只给面板看：移动端那份候选契约（二维码里带的 `lanUrls`）的**取舍**一个字都没动，那边的
@@ -297,10 +301,12 @@ function registerControlPlaneRoutes(deps) {
   //
   // `preferred` 是用户在这两份地址里选中的那条（设置项 `preferredLanAddress`）：界面靠它回显
   // 「现在选的是这条」。选中的地址要真生效在二维码与 `/connection-info` 里，不在这一条上。
+  // `ipv6` 是 2026-10 加的第三份：它**不参与** `preferred`，只用来显示「这台机器在公网
+  // IPv6 上是哪个地址」—— 真机验证时人要拿这个地址去拨，没有它就只能敲命令行。
   registerRoute({ kind: 'exact', path: '/api/relay/addresses', handler: localOnly('GET', async (_req, res) => {
     const port = lanPortInUse()
     const preferred = typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : ''
-    sendJson(res, 200, { ok: true, port, preferred, lan: lanCandidates(port), public: publicCandidates(port) })
+    sendJson(res, 200, { ok: true, port, preferred, lan: lanCandidates(port), public: publicCandidates(port), ipv6: ipv6Candidates(port) })
   }) })
   /**
    * 公用中转候选的测速（`POST /api/relay/probe-relays`，body `{ urls: string[] }`）。

package/lib/routes/mobile-api.js

@@ -36,6 +36,7 @@ const deepSeekAccount = require('../mobile/deepseek-account.js');
 const skills = require('../mobile/skills.js');
 const mobileCredentials = require('../mobile/credentials.js');
 const subagents = require('../mobile/subagents.js');
+const monitor = require('../mobile/monitor.js');
 const references = require('../mobile/references.js');
 const plugins = require('../mobile/plugins.js');
 const uploads = require('../mobile/uploads.js');
@@ -58,6 +59,9 @@ const API_VERSION = '1';
  *   let 变量，闭包捕获对象会让 handler 永远读到启动那一刻的旧快照（lan.updatedAt 停在
  *   进程启动时间，手机端看连接信息像失联了一样）。
  * @param {(port: number) => Array<object>} deps.safeLanCandidates 局域网候选地址
+ * @param {(port: number) => Array<object>} deps.safeIpv6Candidates 公网 IPv6 直连候选。
+ *   与上面那份并列、不并进它：手机拿这份和中转实测比快慢，掺进局域网那份就等于让它
+ *   跟「同一个 Wi-Fi」共用一套失败退避（手机刚离开家里 Wi-Fi 时正是最该试它的时候）。
  * @param {() => number} deps.lanPortInUse 手机该拨的局域网端口。**必须用取值器**：
  *   sidecar 自己 bind 到的端口可能与本进程解析出的不同（两条端口自适应），只认
  *   `state.lanPort` 会把这个接口变成「报一个没人监听的端口」——真机实测过 50933
@@ -71,7 +75,7 @@ const API_VERSION = '1';
  *   一次拒绝或一次握手。
  */
 function registerMobileRoutes(deps) {
-  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, lanPortInUse, preview, core, pairingApproval } = deps;
+  const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval } = deps;
   const route = (path, handler) => registerRoute({ kind: 'exact', path, handler: guarded(handler) })
 
   registerRoute({ kind: 'exact', path: '/api/mobile/v1/status', handler: guarded(async (_ctx, _req, res) => {
@@ -135,6 +139,14 @@ function registerMobileRoutes(deps) {
     const candidates = state.lanEnabled
       ? orderCandidates(safeLanCandidates(port), state.preferredLanAddress)
       : []
+    // IPv6 直连候选：单独一份、**不参与**上面的排序 —— 它和中转谁更快只有手机实测得出，
+    // 宿主无从判断对端走哪条路由。与局域网那份同一个开关管（那条监听挂在同一个代理上），
+    // 关掉局域网直连就没有这条通道。
+    //
+    // 这份是手机配对之后**唯一**能拿到新 IPv6 地址的地方：二维码里带的候选只在配对那一刻
+    // 是真值，而隐私地址按小时轮换、运营商换前缀之后旧的那条就拨不通了。少回这一格，
+    // 手机上那条通道就只能靠配对当时的旧地址活着。
+    const ipv6 = state.lanEnabled ? safeIpv6Candidates(port) : []
     const lanUpdatedAt = getSidecarSnapshot()?.lan?.updatedAt || Date.now()
     sendJson(res, 200, {
       ok: true,
@@ -143,16 +155,25 @@ function registerMobileRoutes(deps) {
       relayUrl: state.enabled ? (state.relayUrl || null) : null,
       lanUrls: candidates,
       lanCandidates: candidates,
+      ipv6Candidates: ipv6,
       updatedAt: lanUpdatedAt,
       lastSeen: lanUpdatedAt,
     })
   })
 
   route('/api/mobile/v1/sessions', sessions.handleSessions)
+  // 后台提醒服务专用：只回「在跑 / 刚完成 / 待回话 / 上一轮失败」这几格，
+  // 带 `?rev=` 条件刷新。它要替掉原生那边每 8 秒一发的完整清单（那份还得为 20 个
+  // 会话各读一次 history 补预览），见 mobile/monitor.js。
+  route('/api/mobile/v1/monitor', monitor.handleMonitor)
   route('/api/mobile/v1/session', sessions.handleSession)
   route('/api/mobile/v1/session/messages', sessions.handleMessages)
   route('/api/mobile/v1/session/attachment', sessions.handleSessionAttachment)
   route('/api/mobile/v1/session/send', sessions.handleSend)
+  // 正文水位探针：App 进对话前先问一句「这条会话的正文到哪个水位了」，跟本地缓存水位
+  // 一比就知道要不要重拉全量历史（几十字节换几兆）。**只读信号快照**：信号里没有就如实
+  // 回 known:false 让 App 退回全量，绝不现读一次历史——否则这探针就变成了它要省掉的那次请求。
+  route('/api/mobile/v1/session/head', sessions.handleSessionHead)
   route('/api/mobile/v1/commands', sessions.handleCommands)
   route('/api/mobile/v1/session/read', sessions.handleSessionRead)
   route('/api/mobile/v1/session/stop', sessions.handleStop)