dsh-mobile-plugin 0.4.0 → 0.4.4

package/lib/read-receipt.cjs

@@ -3,30 +3,19 @@
 /**
  * 「已读回执」台账：哪个会话在什么时候被读过，桌面端据此清掉自己的未读绿点。
  *
- * 背景：两端侧边栏的绿点来自**两份互不相干**的状态。
- *   - 手机端绿点 = 宿主按设备维度维护的完成提醒（lib/mobile/completion.js），
- *     由 `POST /api/mobile/v1/session/read` 清掉；
- *   - 桌面端绿点 = 浏览器渲染进程内存里的 `UiSession.completionUnread`
- *     （@deepseek-ai/dsh-client-ui-session），既不落盘也不过服务端。
- * 所以手机上点开一个会话，桌面那份完全不知情，绿点照旧。
+ * 两端的绿点来自两份互不相干的状态：手机端是宿主按设备维度维护的完成提醒（completion.js），
+ * 桌面端是渲染进程内存里的 `UiSession.completionUnread`，既不落盘也不过服务端。所以手机上
+ * 点开一个会话，桌面那份完全不知情。
  *
- * 这里补的就是这条缺失的通道：只要有人在某一端读过，宿主就往本模块记一条
- * `sessionId → readAt` 水位；插件的客户端半边（lib/client.js 的 startReadReceiptSync）
- * 每 2 秒拉一次 `GET /api/relay/read-receipt`，对水位前进过的会话做一次瞬时
- * `sessions.retain(id, { source: 'mainView' })` + `release()`，借桌面自己的
- * `reconcileStatus()` 把 `completionUnread` 摘掉。
+ * 这里补那条通道：只要有人在某一端读过，宿主就记一条 `sessionId → readAt` 水位；客户端半边
+ * 每 2 秒拉一次，对水位前进过的会话做一次瞬时 retain + release，借桌面自己的
+ * `reconcileStatus()` 把绿点摘掉。
  *
- * 这本台账还有第二个读者：宿主自己。手机侧栏的绿点由 App 拿「上一轮什么时候结束」和
- * 本机已读水位算出来，那一份水位（lib/mobile/session-last-turn.js 的事实地表）是进程内的，
- * 重启就空 —— 所以 `readAtOf` 让它在重启后从这盘上补回来。两头都写同一本账，
- * 「读过」这件事才不会随进程消失。
+ * 宿主自己也读这本账：`readAtOf` 让进程重启后的已读水位从盘上补回来，两头写同一本账，
+ * 「读过」才不会随进程消失。
  *
- * 为什么存 readAt 而不是一个「已读」布尔：冲突策略是 last-write-wins。
- * 桌面点开 → 客户端半边把该会话 POST 回 `/api/relay/desktop-read` → 宿主清掉
- * **所有设备**维度上的完成提醒（`clearCompletionForAllDevices`）。而「读完又来一轮」
- * 必须还能重新亮起来 —— 这一条由 completion.js 的 delete 语义本身保证：条目被清掉后
- * 重建出来的 `wasRunning` 是 false，历史折叠会拒绝确认，于是只有**之后**真正跑完的
- * 轮次才会把 completed 重新置真。
+ * 存 readAt 而不是布尔：冲突策略是 last-write-wins；「读完又来一轮」由 completion.js 的
+ * 条目重建语义保证能重新亮起来。
  */
 
 const fs = require('node:fs');

package/lib/relay/apply-ledger.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * 「按新配置重建隧道失败」的台账：最近一次失败的错误、时间与当时要切过去的地址。
+ *
+ * 以前装配层写的是 `void syncSidecar().catch(() => undefined)`：换地址失败被整个吞掉，
+ * 手机上看是「保存成功」然后永久离线，宿主日志里也一个字都没有 —— 用户唯一的线索是「连不上
+ * 了」，还得自己猜是不是地址填错了。台账只留最近一条，由
+ * `/api/mobile/v1/relay/diagnostics` 原样报给手机（「运行状态」那一页读它）。
+ *
+ * 只留一条是刻意的：这里回答的是「刚才那次为什么没成」，不是故障统计（故障统计归
+ * `host-guard` 的 faults）。成功一次记下 `okAt`（那一次 configure 被 worker 接下了），好让
+ * 界面能说清「失败过，后来又好了」；隧道到底连上没有，看同一份诊断里的 `tunnel`。
+ */
+
+/** 台账里 message 的上限：与 faults 同一条口径，手机上只看一句话。 */
+const MESSAGE_MAX = 300;
+
+let lastFailure = null;
+let lastOkAt = 0;
+
+/** 记一次失败。`target` 是当时配置里那份要切过去的中转地址（没有就不带）。 */
+function recordFailure(error, target) {
+  const raw = error instanceof Error ? error.message : String(error);
+  lastFailure = {
+    at: Date.now(),
+    // 只留第一行：facade 拼出来的错误后面可能跟着整段堆栈首行，手机上没用。
+    message: String(raw || '').split('\n')[0].slice(0, MESSAGE_MAX),
+    ...(target ? { target: String(target) } : {}),
+  };
+}
+
+/** 记一次成功下发：失败记录不删（它确实发生过），只补上「之后又通了」的时间。 */
+function recordSuccess() {
+  lastOkAt = Date.now();
+}
+
+/** 只读投影：诊断接口原样回这一份。 */
+function view() {
+  return {
+    lastFailure: lastFailure ? { ...lastFailure } : null,
+    okAt: lastOkAt || null,
+  };
+}
+
+/** 清空（只有测试用得到；生产里失败记录由下一次失败覆盖）。 */
+function reset() {
+  lastFailure = null;
+  lastOkAt = 0;
+}
+
+module.exports = { recordFailure, recordSuccess, view, reset, MESSAGE_MAX };

package/lib/relay/core.js

@@ -1,7 +1,9 @@
 /**
  * relay.json 的状态形状与读写，外加实例 ID / 配对码 / 隧道地址这几个纯函数。
  *
- * 内存里的 `state` 是本进程唯一真值，这里只负责落盘与还原（见 A3-20 的坑）。
+ * 内存里的 `state` 是本进程唯一真值，这里只负责落盘与还原（见 A3-20 的坑）。中转地址的
+ * 规范形态（`normalizeRelayUrl`）也在这里：配置里、设备手上、`MIGRATE` 帧里必须是同一份
+ * 字符串，否则「地址变了」会被判错，迁移登记白跑一次。
  */
 'use strict';
 
@@ -87,6 +89,15 @@ function saveState(state) {
   fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
   fs.renameSync(tmp, STATE_FILE);
 }
+/**
+ * 中转地址的规范形态：去首尾空白、去尾斜杠。
+ *
+ * 设备手上存的那份、`MIGRATE` 帧里报出去的 `to`、配置里落盘的那份，必须是同一个字符串 ——
+ * 差一个尾斜杠就是「地址变了」，换地址那套迁移登记会白跑一次。
+ */
+function normalizeRelayUrl(relayUrl) {
+  return String(relayUrl || '').trim().replace(/\/+$/, '');
+}
 /**
  * 中转地址 → 隧道 WebSocket 地址。
  *
@@ -96,7 +107,7 @@ function saveState(state) {
  * `/api/relay/config` 能在保存时就给出明确反馈。
  */
 function tunnelWsUrl(relayUrl) {
-  const raw = String(relayUrl || '').trim().replace(/\/+$/, '');
+  const raw = normalizeRelayUrl(relayUrl);
   if (!/^https?:\/\/[^\s/]+/i.test(raw)) {
     throw new Error(`无效的中转地址「${relayUrl || ''}」：必须以 http:// 或 https:// 开头`);
   }
@@ -107,5 +118,5 @@ function verifyLanToken(secret, token, instanceId) { return sharedToken.verifyLa
 
 module.exports = {
   STATE_FILE, MOBILE_TOKEN_TTL_SEC, MOBILE_BEARER_TTL_SEC, loadState, saveState, rotatePairing, genInstanceId, genPairingCode, genPairingTicket,
-  tunnelWsUrl, signLanToken, verifyLanToken,
+  tunnelWsUrl, normalizeRelayUrl, signLanToken, verifyLanToken,
 };

package/lib/relay/lan-network.cjs

@@ -1,12 +1,11 @@
 /**
  * 网卡枚举与候选地址：私网 / 公网 / IPv6 全球单播三份清单，外加「用户选中的那条排最前」。
  *
- * 收口在这一个文件里，是因为 App 只认「按顺序挨个试」这一种语义 —— 顺序就是优先级。
+ * 收口在一个文件里，是因为 App 只认「按顺序挨个试」这一种语义，顺序就是优先级。
  *
- * 三份的区别在**手机在哪**：私网那份是「同一个 Wi-Fi 里能直连」，公网那份是「这台机器
- * 自己就挂在公网上」，IPv6 那份是「手机在别的网络里、从公网拨过来」——最后这份是 2026-10
- * 新加的，它**不并进前两份**，因为 App 对它的用法完全不同（要和公网中转比速度，见
- * `ipv6Candidates` 的注释）。
+ * 三份的区别在手机在哪：私网是「同一个 Wi-Fi 里能直连」，公网是「这台机器自己就挂在公网上」，
+ * IPv6 是「手机在别的网络里拨过来」。IPv6 不并进前两份：App 对它的用法不同，要和公网中转
+ * 比速度。
  */
 'use strict'
 
@@ -22,17 +21,11 @@ function ipv4Number(address) {
 function inRange(value, start, end) { return value >= start && value <= end }
 
 /**
- * RFC1918 里**不由容器/虚拟机/虚拟网桥占掉**的那几段。
+ * RFC1918 里不由容器 / 虚拟机 / 虚拟网桥占掉的那几段。
  *
- * 172.16/12 原本是一个整段，但 Docker 默认把 `172.17.0.0/16` 给 `docker0`，于是
- * 客户机器上的 `172.17.0.1` 会被当成一条「局域网地址」摆到面板与二维码里 —— 手机拨过去
- * 要么不通，要么连到容器上的别的东西。同理 `172.18/16`（docker compose 的默认网络）、
- * `172.19/16` 与 `172.20/16`（compose / k3d 的下一批）、`172.24~172.31/16`（kubeadm 的
- * `k8s-pod-network` 与常见 overlay）也都是工具按默认值抢走的。
- *
- * 判据是「这个段是不是被某个常见的非宿主网络工具预留了」，而不是「这台机器上有没有跑它」：
- * 我们读不到网络配置，只能按默认值收敛。留下的 172.16~172.23 是 172.16/12 里没被任何
- * 主流工具默认占用的部分；真有人在这几段上跑业务网，网卡名黑名单（下一条）仍然是第一道闸。
+ * Docker 默认拿走 172.17/16，compose / k3d / kubeadm 又按默认值各占几段；把它们当候选，
+ * 手机拨过去要么不通，要么连到容器上的别的东西。我们读不到网络配置，只能按「常见工具会不会
+ * 默认占用」收敛；网卡名黑名单仍然是第一道闸。
  */
 const RESERVED_172 = [
   [0xac110000, 0xac11ffff], // 172.17/16 docker0
@@ -175,21 +168,14 @@ function lanCandidates(port, interfaces = os.networkInterfaces()) {
 }
 
 /**
- * 公网地址：同一遍扫描，挑出**真能从外网拨过来**的那些。
+ * 公网地址：同一遍扫描，挑出真能从外网拨过来的那些。
  *
  * 判据是「不在任何特殊网段里」，而不是「不是 RFC1918」——后者会把 169.254/16（链路本地）、
  * 100.64/10（CGNAT）、198.18/15（基准测试）这些同样拨不通的地址当成公网地址发出去。
- * 实测踩过：macOS 上一块多出来的网卡带着 `169.254.87.131`，被当成「公网地址」摆到面板上。
- * 这份特殊网段清单和本文件开头那句「intentionally excludes VPN/CGNAT, link-local and
- * benchmarking/test ranges」是同一条口径。
- *
- * 为什么不并进 `lanInterfaces`：那份列表的语义是「手机和这台机器在同一个 Wi-Fi 里能直连的
- * 地址」，混进公网地址会改掉 App 的探测顺序与中转上报的内容（`test/lan-network.test.cjs`
- * 既钉着「WAF 容器的 192.168.0.1 被当成候选」那次事故，也钉着「只有公网地址的机器候选为空」）。
  *
- * 需要公网地址的地方只有两处，都在取回来之后再决定怎么用：面板显示「手机该填哪个地址」，
- * 以及一台只有公网 IP 的机器上给不出任何私网候选时的兜底（见 `../impl.js` 的
- * `safeLanCandidates`）。
+ * 不并进 `lanInterfaces`：那份的语义是「同一 Wi-Fi 里能直连」，混进公网地址会改掉 App 的
+ * 探测顺序与中转上报的内容。需要公网地址的只有两处：面板显示该填哪个地址，以及一台只有
+ * 公网 IP 的机器上给不出任何私网候选时的兜底。
  */
 const NOT_PUBLIC_RANGES = [
   [0x00000000, 0x00ffffff], // 0/8        “本网络”
@@ -328,8 +314,8 @@ function ipv6Candidates(port, interfaces = os.networkInterfaces()) {
  * 对外公布的候选地址：**先私网，一个都没有时才退到公网**。
  *
  * 为什么要有这一条：`lanInterfaces` 只认 RFC1918，于是「DSH 装在一台只有公网 IP 的服务器上」
- * 时那份列表**恒为空** —— 二维码里一个可拨的地址都没有，「手机直连」这条路从根上走不通
- * （2026-10-11 用户报的现场）。只在为空时才退：有私网地址的机器，候选列表一个字都不变。
+ * 时那份列表**恒为空** —— 二维码里一个可拨的地址都没有，「手机直连」这条路从根上走不通。
+ * 只在为空时才退：有私网地址的机器，候选列表一个字都不变。
  *
  * 取不到网卡（异常）时回空清单、绝不抛：它喂的是二维码与移动端的连接信息，
  * 让它把整条控制面拖下水不值得。

package/lib/relay/lan-proxy.js

@@ -4,11 +4,10 @@
  * 局域网直连代理：手机在同一个 Wi-Fi 下直接访问
  * http://<电脑IP>:<lanPort>，带上配对拿到的令牌后代理到本机 dsh web。
  *
- * 只服务 App：未认证的请求一律 JSON 401，不给任何网页。曾经的 HTML 配对页
- * 与配对后能进入的网页本体已删除（见 docs/decisions.md 2026-10-19）。
+ * 只服务 App：未认证的请求一律 JSON 401，不给任何网页（网页版配对页与网页本体已删除）。
  *
- * 与中转隧道的关系：同网用本代理（零延迟、不依赖公网），
- * 异地走 dsh-mobile-server 中转。两者互不影响，可同时开启。
+ * 与中转隧道的关系：同网走本代理（零延迟、不依赖公网），异地走 dsh-mobile-server 中转；
+ * 两者互不影响，可同时开启。
  */
 
 const http = require('node:http');
@@ -352,22 +351,18 @@ function createLanProxy(opts) {
     /**
      * 手机走了，必须把上游这条请求一起拆掉。
      *
-     * 旧实现只挂了 `error`：手机断开之后上游请求还活着，宿主那边的响应就永远等不到
-     * `close`，于是 events 流与每条会话流的订阅**永不退订**——宿主继续往一条没人读的
-     * 连接上生成帧与正文。2026-10-19 实测：一台机器 12 条手机连接攒出 216 条上游长流，
-     * 宿主进程涨到 3.5～5G、CPU 30～40%，重启后回到 530M。同一个插件的中转路径有
-     * `httpCancel` 帧负责拆（tunnel.js），只有局域网这条路漏了。
+     * 只挂 `error` 的话，手机断开后上游请求还活着，宿主那边的响应永远等不到 `close`，events
+     * 流与每条会话流的订阅就永不退订，宿主继续往一条没人读的连接上生成帧与正文。中转路径有
+     * `httpCancel` 帧负责拆，局域网这条路同样要有。
      *
-     * `res.writableEnded` 是判据：正常活完的响应结束时就已置位，不该再去动上游；
-     * 只有「客户端提前走」才会落到 false。
+     * 判据是 `res.writableEnded`：正常活完的响应结束时就已置位，只有客户端提前走才落到 false。
      */
     res.on('close', () => {
       if (res.writableEnded) return;
       try { up.destroy() } catch { /* 已断开 */ }
     });
     // GET/HEAD 没有请求体：直接收尾发出去，不要依赖 `req` 的 `end` 事件 —— SSE 客户端的
-    // 那条连接未必会像普通 fetch 一样把请求流收掉，`pipe` 一直不 end，上游就永远不处理
-    // （2026-10-24 现场：设备级 SSE 每 32 秒重试，宿主侧一次都没进处理器）。
+    // 那条连接未必会像普通 fetch 一样把请求流收掉，`pipe` 一直不 end，上游就永远不处理。
     if (req.method === 'GET' || req.method === 'HEAD') up.end();
     else req.pipe(up);
   }
@@ -783,16 +778,14 @@ function createLanProxy(opts) {
       })
 
       /**
-       * IPv6 那条监听：拿 IPv4 实绑的端口，`::` + **显式 `ipv6Only: true`**。
+       * IPv6 那条监听：拿 IPv4 实绑的端口，`::` + 显式 `ipv6Only: true`。
        *
-       * 为什么不合成一条双栈监听：`impl.js` 的端口占用探测真去 `listen(port, '0.0.0.0')`
-       * 试探，一条双栈的 `::` 会把首选端口一律探成「被占」，于是落到内核随机端口并写盘，
-       * 端口每次启动都可能漂；反过来把探测也改成 `::`，关掉 IPv6 的机器上探测会因
-       * EAFNOSUPPORT 永远判「被占」，同样漂。各管一个协议族就没这个问题：`ipv6Only: true`
-       * 之后 v6 那个 socket 不碰 IPv4（不设这个标志在 Linux 上才会撞），同端口可以共存。
+       * 不合成一条双栈监听：`impl.js` 的端口占用探测真去 `listen(port, '0.0.0.0')` 试探，
+       * 一条双栈的 `::` 会把首选端口一律探成「被占」，于是落到内核随机端口、端口每次启动都
+       * 可能漂；把探测也改成 `::`，关掉 IPv6 的机器上又会因 EAFNOSUPPORT 永远判「被占」。
+       * 各管一个协议族就没这个问题。
        *
-       * 它是**软的**：只有「手机不在同一 Wi-Fi、只有 IPv6」时才用得上，绑不上就记一行、
-       * 只留 IPv4 直连——绝不影响 IPv4，也绝不往上抛。
+       * 它是软的：只有「手机不在同一 Wi-Fi、只有 IPv6」时才用得上，绑不上就记一行、只留 IPv4。
        */
       const startV6 = () => new Promise((onDone) => {
         const v6 = http.createServer(handleRequest);

package/lib/relay/migrate.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * 换中转地址前的「搬迁登记」：在**旧隧道**上告诉中转「这台搬家到 to」，给帧留出真的离开
+ * 本机的时间，再建新隧道；新隧道注册不上就把那条登记收回来（`to:""`）。
+ *
+ * 为什么非得在旧隧道上说：设备手上握的是旧地址，它只会在旧中转上找这台电脑。不先登记，
+ * 换完地址那一刻，所有不在同一个局域网的设备就永远找不到它了 —— 「换服务器之后拿旧地址的
+ * 设备永远学不到新地址」就是缺这一帧。
+ *
+ * 旧隧道**不立刻关**（两条路都一样）：新隧道注册期间它还在服务在途请求；失败时更是只有它
+ * 还能发撤销。注册完成后再留 `OLD_TUNNEL_LINGER_MS`，让「已受理」或「失败」那一发响应
+ * 沿着老路回去 —— 这一发的结果是用户填完地址之后唯一的反馈。
+ *
+ * 顺序只有这一份实现：worker 的 `configure()` 在检测到中转地址变了之后调 `switchRelay`，
+ * 手机端与控制面两个入口都走同一条下发路径，不各写一套。
+ */
+
+const { T } = require('./protocol.js');
+const core = require('./core.js');
+
+/** MIGRATE 帧发出后留给它离开发送队列的时间：一次 `ws.send` 就进内核，200ms 足够。 */
+const MIGRATE_FLUSH_MS = 200;
+
+/** 新隧道注册成功后旧隧道还留多久：够一发 HTTP 响应（含中转那段）沿着旧路回完。 */
+const OLD_TUNNEL_LINGER_MS = 1500;
+
+const wait = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+/** 登记用的目标地址：与配置、设备手上那份同一个规范形态。 */
+function migrateTarget(relayUrl) {
+  return core.normalizeRelayUrl(relayUrl);
+}
+
+/** 在旧隧道上登记迁移；没连着就回 false（那就没什么可登记的）。 */
+function announce(tunnel, relayUrl) {
+  if (!tunnel || !tunnel.connected) return false;
+  return tunnel.sendJson(T.migrate, 0, { to: migrateTarget(relayUrl), at: Date.now() }) === true;
+}
+
+/** 撤销登记（`to` 空串 = 这台没搬走）。 */
+function revoke(tunnel) {
+  if (!tunnel || !tunnel.connected) return false;
+  return tunnel.sendJson(T.migrate, 0, { to: '', at: Date.now() }) === true;
+}
+
+/**
+ * 换地址：登记 → 等帧出去 → 起新隧道 → 成功则稍后收旧隧道 / 失败则撤销并抛错。
+ *
+ * @param {object} opts
+ * @param {object|null} opts.oldTunnel 旧隧道（可能没连上，那就只是重建）
+ * @param {string} opts.relayUrl 要切过去的中转地址
+ * @param {() => Promise<unknown>} opts.open 建一条**新**隧道并返回它的注册 Promise；
+ *   不许先停旧的（旧的还要发撤销、还要把响应送回去）
+ * @param {(tunnel: object) => void} opts.drop 停掉一条隧道
+ * @returns {Promise<boolean>} 旧隧道上到底登记出去没有
+ */
+async function switchRelay({ oldTunnel, relayUrl, open, drop }) {
+  /** 留一段再收旧隧道：那一发「已受理 / 失败原因」的响应还在它上面往回走。 */
+  const dropLater = (tunnel) => {
+    if (!tunnel) return;
+    const linger = setTimeout(() => { try { drop(tunnel); } catch { /* 已经断开 */ } }, OLD_TUNNEL_LINGER_MS);
+    if (typeof linger.unref === 'function') linger.unref();
+  };
+  const announced = announce(oldTunnel, relayUrl);
+  // 帧必须先真的离开发送队列：紧接着建新隧道（以及失败后的撤销）都和这一帧的到达顺序有关。
+  if (announced) await wait(MIGRATE_FLUSH_MS);
+  let registered;
+  try {
+    registered = await open();
+  } catch (error) {
+    // 新地址没通：把登记收回去，旧中转别再把设备往一个连不上的地址送。
+    revoke(oldTunnel);
+    // 撤销之后也别立刻关：错误要沿旧隧道回到发起这次切换的那一发请求上 ——「如实回给
+    // 调用方」只有这一条物理路径。
+    dropLater(oldTunnel);
+    throw error;
+  }
+  dropLater(oldTunnel);
+  return announced && Boolean(registered);
+}
+
+module.exports = {
+  switchRelay,
+  announce,
+  revoke,
+  migrateTarget,
+  MIGRATE_FLUSH_MS,
+  OLD_TUNNEL_LINGER_MS,
+};

package/lib/relay/pairing-policy.js

@@ -3,16 +3,13 @@
 /**
  * 配对授权策略。
  *
- * 被删除的桌面端用弹窗逐次确认；无头宿主没有这个界面，授权改由本地策略决定。
- * 两条链路都汇聚到父进程的 /api/relay/internal/approval：隧道收到 pairRequest 时，
- * 以及局域网代理的 onApprove。sidecar 只接受显式 true，所以 'deny' 与原来恒定
- * 返回 { approved: false } 的行为完全一致。
+ * 无头宿主没有弹窗确认界面，授权改由本地策略决定。两条链路都汇聚到父进程的
+ * `/api/relay/internal/approval`：隧道收到 pairRequest 时，以及局域网代理的 onApprove。
+ * sidecar 只接受显式 true，所以 'deny' 与恒定返回 `{ approved: false }` 等价。
  *
- *   'code' — 凭配对码放行。中转（dsh-mobile-server/server.js:400）与局域网
- *            （lib/relay/lan-proxy.js:243）在询问宿主之前都已用恒定时间比较校验过
- *            配对码，中转还有失败锁定；配对码只在用户主动索取时展示，可用
- *            /api/relay/regenerate 轮换、用 /api/relay/revoke-all 连同 lanSecret
- *            一并作废。
+ *   'code' — 凭配对码放行。两条链路在询问宿主之前都已用恒定时间比较校验过配对码，中转还有
+ *            失败锁定；配对码只在用户主动索取时展示，可用 `/api/relay/regenerate` 轮换、
+ *            用 `/api/relay/revoke-all` 连同 lanSecret 一并作废。
  *   'deny' — 拒绝一切新配对。
  */
 

package/lib/relay/preview.js

@@ -3,34 +3,17 @@
 /**
  * 预览字节管道（宿主侧）。
  *
- * 手机 App 的内置浏览器要能看到桌面机上「开发中的网页」，而那些 dev server 只监听
- * 宿主机的 127.0.0.1:<port>。手机、中转、局域网代理都够不着它，所以链路上必须有一
- * 段跑在宿主进程里的搬运工——就是这里。
+ * 手机 App 的内置浏览器要看到桌面机上「开发中的网页」，而那些 dev server 只监听宿主的
+ * 127.0.0.1:<port>，手机、中转、局域网代理都够不着。所以链路上有一段跑在宿主进程里的搬运工。
  *
- * 为什么是**字节管道**而不是又一个 HTTP 代理：
- * 一个页面不是「一次请求」而是「几百次请求」——ES 模块、CSS、图片、XHR、还有 HMR
- * 那条活着的 WebSocket。浏览器引擎自己发这些请求，App 侧的 JS 拦不住。所以端口只在
- * 建立管道时协商一次，之后这管道对内容一无所知，只搬字节。
+ * 是字节管道而不是 HTTP 代理：一个页面是几百次请求加一条活着的 HMR WebSocket，端口在建立
+ * 管道时协商一次，之后完全不解析内容。于是内置浏览器的地址栏与实际 Host 都是
+ * `localhost:3001`，dev server 生成的绝对地址自动闭环、零配置；做路径改写反而会立刻全 404。
  *
- * 这么做的收益是结构性的：内置浏览器地址栏里是 `http://localhost:3001/`，宿主机上
- * 的 dev server 看到的 Host 也是 `localhost:3001`——两边对「我在哪」的认知完全一致。
- * 于是 dev server 生成的一切绝对地址（资源路径、接口地址、跳转 Location、HMR 连接
- * 地址）都自动闭环，**dev server 零配置**。反过来说，如果这里做半吊子的路径改写，
- * `/assets/app.js` 这类绝对路径立刻全 404。
+ * 环回地址要双栈试（macOS 上不少 dev server 只监听 `::1`）。WS 升级、SSE、分块传输原样穿过。
  *
- * 这一层刻意「不认识」HTTP 与 WebSocket：
- *
- *   - 手机侧的原生模块把 WebView 写下的原始字节塞进 WebSocket 的二进制帧；
- *   - 这里 `net.connect(<环回地址>, port)` 之后双向对搬。环回地址要**双栈**试：macOS 上
- *     不少 dev server（Vite 等）默认只监听 `::1`，只拨 `127.0.0.1` 会连不上；
- *   - 中间任何一层都不解析、不改写，所以 WS 升级、SSE、分块传输、自定义子协议全都
- *     原样穿过（HMR 不用砍也不用绕——浏览器和 Vite 自己完成握手与分帧）。
- *
- * 代价要说清楚：正因为宿主无法审查内容，**端口就是这里唯一的边界**，所以下面有
- * `protectedPorts()` 那道按身份的拒绝（DSH 自身的 web 端口永远不许从预览进来）。
- *
- * 与仓库里 `dsh-mobile-server/scripts/adb-ws-bridge.cjs` 是同一个套路（原始 TCP 流包进 WebSocket 帧），
- * 那个先例证明这条路在本项目里走得通。
+ * 代价：宿主无法审查内容，端口就是唯一边界，所以 `protectedPorts()` 按身份拒绝——DSH 自身的
+ * web 端口永远不许从预览进来。
  */
 
 const net = require('node:net');

package/lib/relay/protocol.js

@@ -3,20 +3,16 @@
 /**
  * dsh-mobile-server 隧道协议 v2 编解码（取代 v1 的 JSON/base64 文本帧）。
  *
- * 每条隧道消息 = 一个 WS binary 帧：
- *   [type: 1B][id: 4B 大端][length: 4B 大端][payload: length B]
+ * 每条隧道消息 = 一个 WS binary 帧：`[type: 1B][id: 4B 大端][length: 4B 大端][payload]`。
+ * 数据通道的 payload 是原始字节（不再 base64），控制消息是 UTF-8 JSON，ping/pong 为应用层
+ * 心跳（经代理/负载均衡时比 WS 原生 ping 可靠）。
  *
- * - 数据通道（httpBody / httpChunk / wsText / wsBinary）的 payload 为
- *   原始字节，不再 base64（消除 ~33% 体积膨胀）；
- * - 控制消息（register / httpHead 等）payload 为 UTF-8 JSON；
- * - ping/pong 为应用层心跳（经代理/负载均衡时比 WS 原生 ping 更可靠）。
+ * 控制帧 `migrate`（0x1C）是「这台搬家了」的登记：宿主在**旧隧道**上发出，中转据此把还
+ * 握着旧地址的设备导向新地址，`to` 空串表示撤销。发送与撤销的时序见 relay/migrate.js。
  *
- * 协议语义见 ../../../server/dsh-mobile-server/server/relay-core/PROTOCOL.md。
- *
- * 本文件是自包含副本（插件包不能跨目录引用中转仓库的文件），完整内联了共用类型表
- * 与编解码实现。类型表的事实源在独立中转仓库的 server/relay-core/protocol-types.js；
- * 本仓的 protocol-parity 测试钉住线格式，中转仓库另做 Rust 与 JS 字节对撞；
- * 改动帧编号后必须同步修改本文件。
+ * 本文件是自包含副本（插件包不能跨目录引用中转仓库）：完整内联了共用类型表与编解码实现。
+ * 事实源在中转仓库的 relay-core，本仓的 protocol-parity 测试钉住线格式；改动帧编号后必须
+ * 同步修改本文件。
  */
 
 const T = {
@@ -47,6 +43,7 @@ const T = {
   revokeAllAck: 0x19,  // id=0  JSON {ok, revoked}；中转确认已清空
   pushRegister: 0x1A,  // id=0  JSON {deviceId, platform, token}；宿主代 App 上报 iOS 推送令牌（本实例）
   pushSend: 0x1B,      // id=0  JSON {deviceId, title, body, sessionId?, kind}；宿主请求中转发一条 APNs 推送
+  migrate: 0x1C,       // id=0  JSON {to, at}；宿主在旧隧道上登记「这台搬去哪个中转」，to 空串 = 撤销
 };
 
 const TYPE_NAME = {};

package/lib/relay/status.js

@@ -3,15 +3,12 @@
 /**
  * 中转状态视图：把「此刻这台宿主到底怎么样」拼成一份 JSON。
  *
- * 这份 JSON 有三个消费方，形状必须一模一样：桌面端设置页（`client.js`）轮询
- * `/api/mobile/v1/status`，手机端首屏也读同一条，而二维码里嵌的也是它的子集。
- * 以前它是 apply() 闭包里的一坨内联函数，混在 sidecar 生命周期与镜像推送之间——想核对
- * 某个字段拼对没有，只能通读 1000 行装配代码。抽出来之后可以直接 require 单元测试，
- * 也让 index.js 只剩装配。
+ * 这份 JSON 有三个消费方，形状必须一模一样：桌面设置页、手机首屏都轮询
+ * `/api/mobile/v1/status`，二维码里嵌的也是它的子集。抽出来之后可以直接 require 测试，
+ * index.js 只剩装配。
  *
- * 注意 `TUNNEL_ADMISSION`：它靠**正则匹配中转返回的错误文案**来判断隧道为什么被拒。
- * 这是个脆弱契约（中转改一个字就漏判），但在没有更好信号之前只能这样——错误文案是
- * 当前唯一穿过隧道边界回来的信息。判定放宽到只认关键词，见下。
+ * `TUNNEL_ADMISSION` 靠正则匹配中转返回的错误文案来判断隧道为什么被拒。这是个脆弱契约
+ * （中转改一个字就漏判），但错误文案是当前唯一穿过隧道边界回来的信号，判定放宽到只认关键词。
  */
 
 const os = require('node:os')

package/lib/relay/tunnel.js

@@ -44,18 +44,17 @@ class RelayTunnel {
    * @param {object} opts
    * @param {string} opts.relayUrl  隧道 WSS 地址（含 /tunnel），如 wss://relay.example.com/tunnel
    * @param {string} opts.instanceId
-   * @param {string} [opts.pairingCode] 仅本进程自用（面板显示）；**不发往中转**，见 registrationPayload
+   * @param {string} [opts.pairingCode] 仅本进程自用（面板显示），不发往中转
    * @param {string} [opts.name]
    * @param {string[]} [opts.lanUrls] LAN sidecar candidates (metadata only)
    * @param {object[]} [opts.lanCandidates] LAN candidate metadata (metadata only)
    * @param {string} opts.upstream  本地上游，如 http://127.0.0.1:52323
-   * @param {string} [opts.registerSecret] 中转侧 TUNNEL_REGISTER_SECRET 的对偶值。
-   *        优先于环境变量 DSH_RELAY_REGISTER_SECRET：桌面版 DSH 是从图标/启动台
-   *        拉起的，拿不到 shell 环境变量，密钥只能走 relay.json（0600）。
+   * @param {string} [opts.registerSecret] 中转侧 TUNNEL_REGISTER_SECRET 的对偶值，优先于环境
+   *   变量 DSH_RELAY_REGISTER_SECRET：桌面版从图标拉起时拿不到 shell 环境变量，密钥只能走
+   *   relay.json（0600）。
    * @param {() => void} [opts.onRegistered] 注册成功回调（用于状态展示）
    * @param {(code: number, reason: string) => void} [opts.onClose] 连接断开回调（用于断线重连）
-   * @param {(msg: {requestId: string, device?: {name?: string, ip?: string, platform?: string, osVersion?: string, version?: string, appVersion?: string, id?: string, deviceId?: string}}) => void} [opts.onPairRequest]
-   *        中转转发来的配对授权请求（手机配对码已通过校验，需桌面用户确认）
+   * @param {(msg: object) => void} [opts.onPairRequest] 中转转发来的配对授权请求（配对码已校验）
    * @param {(msg: string) => void} [opts.onLog]
    */
   constructor(opts) {
@@ -110,15 +109,11 @@ class RelayTunnel {
   }
 
   /**
-   * 发送队列积压到上限时**只丢这一帧，不断开隧道**。
+   * 发送队列积压到上限时只丢这一帧，不断开隧道。
    *
-   * 旧实现在两个分支里都 `ws.terminate()`：积压超限时把整条隧道掐掉。可积压本身是
-   * 「手机/中转读得慢」，不是「隧道坏了」——掐掉它，所有设备（包括正在正常转发的
-   * 那些）一起掉线，还要等 5s 重连。中转侧的同名判定（dsh-mobile-server/lib/proxy-http.js
-   * 的 sendFrame）已经改成只 `return false`，两侧口径必须一致：丢一帧可以恢复，
-   * 关一条隧道是全网断流。
-   *
-   * 真正的「隧道已死」由心跳兜底：PONG_TIMEOUT_MS 收不到 pong 时才会 terminate。
+   * 积压本身是「手机/中转读得慢」，不是隧道坏了；掐掉整条隧道会让所有设备一起掉线再等 5s
+   * 重连。中转侧的同名判定已经改成只 `return false`，两侧口径必须一致：丢一帧可以恢复，
+   * 关一条隧道是全网断流。真正的「隧道已死」由心跳兜底：收不到 pong 才 terminate。
    */
   dropOverBudget(bytes, frameLength) {
     const total = bytes + frameLength;

package/lib/relay/verify.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * 试连中转：拿**新地址**真注册一次，注册上了才算这个地址能用，随后立刻断开。
+ *
+ * 手机和电脑面板上改中转地址，最坏的结果是这台电脑从网上消失 —— 而改地址的入口本身就挂在
+ * 那条隧道上。先落盘再重建等于让用户在一次手滑之后自己走回电脑前，所以改之前必须先验证：
+ * 这个动作就是那个验证。
+ *
+ * **临时实例 id**：中转按实例 id 认人，拿正式 id 去试连会把正在服务的那条顶掉（真机上表现
+ * 为「点了一下验证，手机立刻掉线」）。所以用正式 id 加 `~probe~` 加随机段，连完马上断，
+ * 不在中转上留实例。随机段不是防御性加盐：同一个实例连第二次探测时，中转那条旧记录还没被
+ * 心跳清掉，撞上就会互相取代。
+ */
+
+const { randomBytes } = require('node:crypto');
+
+const { RelayTunnel } = require('./tunnel.js');
+const core = require('./core.js');
+
+/** 临时实例 id 里的标记段：出错时一眼能看出这不是一台真的宿主。 */
+const PROBE_MARK = '~probe~';
+
+/** 试连的实例 id：正式 id + 标记 + 随机段，必然与正式 id 不同。 */
+function probeInstanceId(instanceId) {
+  return `${String(instanceId || '')}${PROBE_MARK}${randomBytes(4).toString('hex')}`;
+}
+
+/**
+ * 用 `instanceId`（调用方给的是临时 id）连 `relayUrl` 并等到 `registered` 帧。
+ *
+ * resolve = 这个地址登录得了；reject = 地址形状不对、连不上、注册被拒或超时（消息原样往上
+ * 回，手机上看的就是这句）。无论成败都断开：留一个实例在中转上，下次真连接会被它顶一下。
+ */
+async function verifyRelayRegistration({ relayUrl, instanceId, upstreamPort, name, registerSecret }) {
+  // 地址形状不对在这里当场抛（与保存配置同一个判据），别等到 WebSocket 才炸。
+  const tunnel = new RelayTunnel({
+    relayUrl: core.tunnelWsUrl(relayUrl),
+    instanceId,
+    name: name || '',
+    upstream: `http://127.0.0.1:${upstreamPort}`,
+    registerSecret: typeof registerSecret === 'string' ? registerSecret : '',
+  });
+  try {
+    await tunnel.start();
+    return { ok: true };
+  } finally {
+    try { tunnel.stop(); } catch { /* 已经断开 */ }
+  }
+}
+
+module.exports = { probeInstanceId, verifyRelayRegistration, PROBE_MARK };