dsh-mobile-plugin 0.1.99 → 0.2.0

package/lib/shared/pair-throttle.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * 配对入口的限速闸门。
+ *
+ * 原来那套是「按来源分桶、错五次锁一分钟」，而这条链路上**没有可靠的来源**：经中转进来
+ * 的请求，宿主看到的对端永远是本机回环；客户端自带一个来源头又能覆盖它。于是这套机制
+ * 两头都错 —— 陌生人连错五次把所有人一起锁死，而换一个来源头就绕过。
+ *
+ * 换成不看来源的全局令牌桶：
+ *  - 正常每分钟 60 次，正经用户永远用不到上限；
+ *  - 连续失败超过 10 次降到 10 次/分钟，超过 30 次降到 2 次/分钟；
+ *  - 计数按「每 10 分钟减半」自己衰减，一次邻居乱按不会让这台机器长期变慢；
+ *  - 满了直接回 429 + `retry-after`，**不排队、不硬锁**。队列本身是新的拒绝服务把柄
+ *    （一个人挂着半条请求就能攥死整条队列），所以这里刻意没有队列。
+ *
+ * 为什么够了：六位码 100 万种，期望要试五十万次；按最低档 2 次/分钟，一天 2880 次，
+ * 期望半年。而任何一次成功都立刻换码（§5.1），所以这把「磨」的有效时间窗只对「一直没人
+ * 配成功」的机器成立 —— 那台机器本来也没人等着配。多来源并发也买不到更多次数，因为
+ * 桶是全局的。
+ *
+ * 新形状（带 `sealed`）没有可猜的东西，但它仍然要过这道闸：「解一次封」是无限次可做的
+ * 动作，需要有上限。
+ */
+
+/** 三档速率：每分钟允许的尝试次数。 */
+const PAIR_RATE_NORMAL = 60;
+const PAIR_RATE_WARN = 10;
+const PAIR_RATE_FLOOR = 2;
+
+/** 连续失败到这些次数就降档。 */
+const PAIR_FAILS_WARN = 10;
+const PAIR_FAILS_FLOOR = 30;
+
+/** 失败计数每这么久减半一次（按最后一次失败的时刻算，不做定时器）。 */
+const PAIR_DECAY_MS = 10 * 60 * 1000;
+
+/**
+ * 一道闸的全部状态。**两个入口各持一份**，不是共用：
+ *
+ * 局域网代理跑在旁路子进程里、宿主那条跑在主进程里，跨进程共用一份计数要么加锁要么走 RPC，
+ * 而两者的网络含义本来就不同（一条在局域网上、一条经中转）。各自限自己的就够 ——
+ * 攻击者要绕过必须同时打两条，而局域网那条他根本进不来。
+ */
+function createPairThrottle(options = {}) {
+  const now = () => (typeof options.now === 'function' ? options.now() : Date.now());
+  let tokens = PAIR_RATE_NORMAL;
+  let refilledAt = now();
+  let fails = 0;
+  let lastFailAt = 0;
+
+  /** 当前档位（每分钟多少次）。 */
+  function rate() {
+    if (fails >= PAIR_FAILS_FLOOR) return PAIR_RATE_FLOOR;
+    if (fails >= PAIR_FAILS_WARN) return PAIR_RATE_WARN;
+    return PAIR_RATE_NORMAL;
+  }
+
+  /** 按经过的时间补令牌。上限定成「一分钟的量」。 */
+  function refill(at) {
+    const limit = rate();
+    const elapsed = at - refilledAt;
+    if (elapsed <= 0) return;
+    const gained = (elapsed * limit) / 60_000;
+    tokens = Math.min(limit, tokens + gained);
+    refilledAt = at;
+    // 令牌上限跟着档位走：降档后如果还留着 60 个令牌，降档就形同虚设。
+    if (tokens > limit) tokens = limit;
+  }
+
+  /** 失败计数的衰减：每当过了一个衰减周期就折半，并且把基准往前推。 */
+  function decay(at) {
+    if (!lastFailAt) return;
+    const periods = Math.floor((at - lastFailAt) / PAIR_DECAY_MS);
+    if (periods <= 0) return;
+    fails = Math.floor(fails / (2 ** Math.min(periods, 30)));
+    lastFailAt += periods * PAIR_DECAY_MS;
+    if (fails === 0) lastFailAt = 0;
+  }
+
+  /**
+   * 试取一个令牌。
+   *
+   * @returns {{ allowed: true } | { allowed: false, retryAfterSec: number }}
+   *   `retryAfterSec` 供 429 的 `retry-after` 头用：按当前档位算出「下一个令牌要等多久」。
+   */
+  function take() {
+    const at = now();
+    decay(at);
+    refill(at);
+    if (tokens >= 1) {
+      tokens -= 1;
+      return { allowed: true };
+    }
+    const limit = rate();
+    const need = 1 - tokens;
+    const seconds = Math.max(1, Math.ceil((need * 60_000) / limit / 1000));
+    return { allowed: false, retryAfterSec: seconds };
+  }
+
+  /** 记一次失败。 */
+  function noteFail() {
+    const at = now();
+    // 上一次失败已经衰减干净了就先衰减，免得跨档位累计。
+    decay(at);
+    fails += 1;
+    lastFailAt = at;
+    // 降档立刻生效：不把旧档位攒下的令牌留着用。
+    const limit = rate();
+    if (tokens > limit) tokens = limit;
+  }
+
+  /** 成功：清零并回到最高档。 */
+  function noteSuccess() {
+    fails = 0;
+    lastFailAt = 0;
+    const at = now();
+    const limit = PAIR_RATE_NORMAL;
+    refill(at);
+    if (tokens > limit) tokens = limit;
+  }
+
+  /** 完全重置成满桶（测试用；`noteSuccess` 只清失败计数，不清已用掉的令牌）。 */
+  function reset() {
+    refilledAt = now();
+    fails = 0;
+    lastFailAt = 0;
+    tokens = PAIR_RATE_NORMAL;
+  }
+
+  /** 测试与自检用：当前状态快照。 */
+  function snapshot() {
+    const at = now();
+    decay(at);
+    refill(at);
+    return { rate: rate(), tokens, fails };
+  }
+
+  return { take, noteFail, noteSuccess, snapshot, reset };
+}
+
+module.exports = {
+  createPairThrottle,
+  PAIR_RATE_NORMAL,
+  PAIR_RATE_WARN,
+  PAIR_RATE_FLOOR,
+  PAIR_FAILS_WARN,
+  PAIR_FAILS_FLOOR,
+  PAIR_DECAY_MS,
+};

package/lib/shared/sse-write.js

@@ -169,14 +169,23 @@ function writeSse(res, payload, options = {}) {
     padEveryMs = 0,
     retryMs = SSE_RETRY_MS,
     shedWhenBuffered = shedWithoutSeq,
+    /**
+     * 协议 v2 的帧封装器：给出就说明这条流会说话的那一半已经加密（§8.3(5)）。
+     *
+     * 它返回 `{ v, n, c }` 形状的信封；`id:` 与 `retry:` 保持明文 —— 它们是 SSE 协议层
+     * 字段，客户端要靠 `id:` 回填 `Last-Event-ID`，而 `id:` 里的 sessionId 本来就在 URL 上。
+     */
+    sealFrame = null,
   } = options;
   const buffered = bufferedBytesOf(res);
   if (buffered > SSE_CLOSE_BUFFERED_BYTES) return { ok: false };
-  if (buffered > SSE_SHED_BUFFERED_BYTES && shedWhenBuffered(payload)) return { ok: true, shed: true };
-  const id = stableEventId(payload, frame, namespace);
+  if (buffered > SSE_SHED_BUFFERED_BYTES && shedWhenBuffered(payload)) return { ok: true, shed: true };  const id = stableEventId(payload, frame, namespace);
   const fields = [`retry: ${retryMs}`];
   if (id) fields.push(`id: ${id}`);
-  fields.push(`data: ${JSON.stringify(payload)}`);
+  // 每帧一条独立密文（自己的 nonce）：整条流套一个信封就得等流结束才能解，那等于把
+  // 流式取消了；一帧一密文也让「丢一帧」不至于让后面全部解不开。
+  const wire = typeof sealFrame === 'function' ? sealFrame(payload) : payload;
+  fields.push(`data: ${JSON.stringify(wire)}`);
   const extra = padding || (paddingBytes > 0
     // 按字节算：正文是中文时字符数只有字节数三分之一，按字符算会低估、补多。
     ? takePadding(res, Buffer.byteLength(`${fields.join('\n')}\n`, 'utf8'), Math.floor(paddingBytes), Math.floor(padEveryMs))
@@ -186,8 +195,10 @@ function writeSse(res, payload, options = {}) {
   try {
     // `write()` 返回 false 才是背压的正信号：数据已经堆到高水位，继续写只会把内存
     // 堆起来。把它当成功吞掉，正是那次 4GB OOM 的直接原因。
-    const accepted = res.write(`${fields.join('\n')}\n`);
-    return { ok: true, needDrain: accepted === false };
+    const frameText = `${fields.join('\n')}\n`;
+    const accepted = res.write(frameText);
+    // 字节数回给调用方：断线重放要按字节封顶（事件条数封不住「每帧都很大」的会话）。
+    return { ok: true, needDrain: accepted === false, bytes: Buffer.byteLength(frameText, 'utf8') };
   } catch { return { ok: false }; }
 }
 

package/lib/shared/via-header.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * 代理转发时给上游请求打「谁转发的」标记。
+ *
+ * 中转与局域网代理都跑在宿主这台机器上，它们转给本地上游的请求，socket 对端是回环地址、
+ * `host` 又是 `127.0.0.1:<上游端口>`，所以上游**任何**看来源地址或 Host 的判断都会把它们
+ * 当成「本机 DSH 设置页」。控制面因此是敞开的：不带实例头、不带 cookie 的
+ * `POST /api/relay/config` 经中转能改中转地址、改注册密钥、`revoke-all`。
+ *
+ * 判据只能落在「谁转发的」这个事实上，而这个头必须**由代理覆盖写入**：先删客户端自带的
+ * 同名副本（大小写不敏感、数组形态也删干净），再写自己的值。只写不删等于让客户端自己声明
+ * 「我是本机」。
+ */
+
+const VIA_HEADER = 'x-dsh-via';
+
+/**
+ * 这条请求是从哪条路转发进来的（`relay` / `lan`），本机直连返回空串。
+ *
+ * 设备列表要显示「最近一次走的是哪条路」，而这两条路最后都进到自己的代理里、
+ * 各自注入了标记 —— 所以宿主不用问中转，也不用等别的版本。
+ */
+function viaChannel(req) {
+  const headers = req?.headers;
+  if (!headers || typeof headers !== 'object') return '';
+  for (const [name, raw] of Object.entries(headers)) {
+    if (name.toLowerCase() !== VIA_HEADER) continue;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return text === 'relay' || text === 'lan' ? text : '';
+  }
+  return '';
+}
+
+/** 删掉任意大小写的同名头（Node 的 headers 可能是数组值）。 */
+function stripHeader(headers, name) {
+  const target = name.toLowerCase();
+  let removed = false;
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== target) continue;
+    delete headers[key];
+    removed = true;
+  }
+  return removed;
+}
+
+/**
+ * 复制一份转发用头：原头不动，去掉客户端自带的来源标记，写入代理自己的值。
+ *
+ * @param {Record<string, unknown>} incoming 客户端原始请求头
+ * @param {'relay'|'lan'} via 转发方
+ * @param {string} fallbackHost 客户端没给 host 时用哪个
+ * @returns {Record<string, unknown>}
+ */
+function withViaHeader(incoming, via, fallbackHost) {
+  const headers = { ...(incoming || {}) };
+  stripHeader(headers, VIA_HEADER);
+  // 保留手机端原始 Host（信任围栏按 Host 判定）；缺省回退本地上游。
+  if (!headers.host) headers.host = fallbackHost;
+  headers[VIA_HEADER] = via;
+  return headers;
+}
+
+module.exports = { VIA_HEADER, stripHeader, withViaHeader, viaChannel };

package/lib/shell/runtime.js

@@ -20,11 +20,18 @@
  */
 
 import { importGeneration, invalidateGeneration, resolveGeneration, resolveGenerations } from './manager.js'
+import { checkGenerationAlive } from './self-check-after-swap.js'
 
 /** 换代前等在飞请求归零的上限。 */
 const DRAIN_TIMEOUT_MS = 2000
 /** 等一代装载完成的上限。装载卡住（依赖永远不来）时不能把整个外壳拖死。 */
 const ACTIVATE_TIMEOUT_MS = 20000
+/** 首次装载全失败后的重试间隔与次数（重试理由见 `start()`）。 */
+const START_RETRY_LIMIT = 6
+/** 间隔可用环境变量压低，只给测试（与 `DSH_MOBILE_PROFILE_NODE_MODULES` 同款逃生口）。 */
+const START_RETRY_MS = Number(process.env.DSH_MOBILE_START_RETRY_MS) > 0
+  ? Number(process.env.DSH_MOBILE_START_RETRY_MS)
+  : 30000
 
 /**
  * 代没有声明 `inject` 时的兜底（只有测试里的假代会走这里）。
@@ -61,6 +68,14 @@ export function createRuntime() {
   let lastError = null
   let activatedAt = null
   let detached = false
+  /**
+   * 最近一次「装上了、但新版自检没过，于是自己退回去」的记录。
+   *
+   * 为什么要它：这件事**不能靠手机按回滚** —— 装坏的后果是 App 连不上这台设备，那一刻
+   * 手机上任何按钮都发不出去。所以退回是宿主自己做的，而手机只能在**下一次连上之后**
+   * 读到这条已经发生过的事实（`lastApply.rolledBack` 就是从它来的）。
+   */
+  let lastRollback = null
 
   /** 对外状态快照。控制面接口直接把它交给客户端。 */
   function status() {
@@ -72,6 +87,7 @@ export function createRuntime() {
       lastError,
       inFlight,
       swapping: swapping !== null,
+      lastRollback,
     }
   }
 
@@ -113,6 +129,70 @@ export function createRuntime() {
     return { version: loaded.version, source: loaded.source, hostPath: loaded.hostPath ?? dir ?? null }
   }
 
+  /**
+   * 换代之后问一次自己的 `/health`：这一代真的在跑、路由真的挂上了吗？
+   *
+   * 端口取**运行中那一份**（`ctx.webServer.port`），不是配置里的默认值 —— 端口被改过之后
+   * 两者可能不同，按配置去问会问到一个没人监听的地方，于是「自检失败」全是假的。
+   * 拿不到端口时返回 `skip` 而不是失败：那种现场（老宿主、测试里的假 ctx）不代表新版坏了。
+   */
+  async function checkSelfCheck() {
+    let port = null
+    try { port = ctx?.webServer?.port ?? null } catch { port = null }
+    return checkGenerationAlive({ port })
+  }
+
+  /**
+   * 把上一代装回去，并记下「退回过」这件事。
+   *
+   * 顺序是刻意的：**先用内存里那份**（`loadedCurrent`），因为它一定还在；盘上那份可能
+   * 已经被这次安装带走了（pnpm 换 store 目录），照版本号找会找空。
+   *
+   * 记 `lastRollback` 是给手机的：它不按回滚，只在**下一次连上之后**读到这条已经发生过
+   * 的事实（`lastApply.rolledBack`）。容器里带 `ok`，退失败也要如实说。
+   */
+  async function rollbackTo(oldCurrent, oldLoaded, reason) {
+    let ok = false
+    try {
+      if (oldLoaded) {
+        const { fiber: nextFiber } = await activateLoaded(oldLoaded)
+        fiber = nextFiber
+        loadedCurrent = oldLoaded
+        current = describe(oldLoaded, oldCurrent?.dir ?? null)
+        activatedAt = new Date().toISOString()
+        ok = true
+      } else {
+        const fallback = resolveGeneration(oldCurrent?.version)
+        if (fallback) {
+          const { loaded, fiber: nextFiber } = await activate(fallback)
+          fiber = nextFiber
+          loadedCurrent = loaded
+          current = describe(loaded, fallback.dir)
+          activatedAt = new Date().toISOString()
+          ok = true
+        }
+      }
+    } catch (rollbackError) {
+      lastError = `${reason}；回滚到 ${oldCurrent?.version ?? '上一代'} 也失败：${rollbackError?.message || rollbackError}`
+      lastRollback = {
+        at: new Date().toISOString(),
+        ok: false,
+        toVersion: null,
+        fromVersion: previous?.version ?? null,
+        reason,
+      }
+      return false
+    }
+    lastRollback = {
+      at: new Date().toISOString(),
+      ok,
+      toVersion: ok ? (current?.version ?? null) : null,
+      fromVersion: previous?.version ?? null,
+      reason,
+    }
+    return ok
+  }
+
   /**
    * 换到指定版本（默认版本最高的那一代）。
    *
@@ -145,6 +225,9 @@ export function createRuntime() {
       await drain()
       const oldFiber = fiber
       const oldCurrent = current
+      // 旧的**模块本体**要在激活新代之前抓住：`loadedCurrent` 一旦被新代覆盖，回滚就只能
+      // 拿到刚装坏的那一份（真机上表现为「自检没过、退回去的还是坏的那个」）。
+      const oldLoaded = loadedCurrent
       fiber = null
       current = null
       if (oldFiber) {
@@ -163,34 +246,37 @@ export function createRuntime() {
         if (oldCurrent) previous = oldCurrent
         activatedAt = new Date().toISOString()
         lastError = null
-        return status()
-      } catch (error) {
-        lastError = `装载 ${target.version} 失败：${error?.message || error}`
-        if (oldCurrent) {
-          // 回滚：把上一代装回去，尽量让插件保持可用。
-          //
-          // 顺序是刻意的：**先用内存里那份**（`loadedCurrent`），因为它一定还在；盘上那份
-          // 可能已经被市场这次安装带走了（pnpm 换 store 目录），照版本号找会找空。
-          try {
-            if (loadedCurrent) {
-              const { fiber: nextFiber } = await activateLoaded(loadedCurrent)
-              fiber = nextFiber
-              current = describe(loadedCurrent, oldCurrent.dir ?? null)
-              activatedAt = new Date().toISOString()
-            } else {
-              const fallback = resolveGeneration(oldCurrent.version)
-              if (fallback) {
-                const { loaded, fiber: nextFiber } = await activate(fallback)
-                fiber = nextFiber
-                loadedCurrent = loaded
-                current = describe(loaded, fallback.dir)
-                activatedAt = new Date().toISOString()
-              }
+        // 装起来了不等于**手机要打的那批接口**可用：端口没绑上、守卫没挂上、某个 handler
+        // 永远不回包，这些都要真打一发才看得见。所以换完之后问一次自己的 `/health`。
+        //
+        // 不过就自己退回去 —— 这一步刻意放在宿主里，不交给手机：装坏的后果正是 App
+        // 连不上这台设备，那时候手机上一颗按钮都发不出去。
+        if (options.selfCheck !== false && oldCurrent) {
+          const alive = await checkSelfCheck()
+          if (alive.ok === false) {
+            const failure = `新版 ${target.version} 换上来之后没通过自检：${alive.reason}`
+            // **先把刚装起来的新代卸掉**：它占着同一批路由路径，不卸就装不回旧代
+            // （webserver: duplicate exact route）。这条是自检回滚与「装载直接抛错」两条路
+            // 唯一的区别 —— 后者根本没有新 fiber 可卸。
+            const brokenFiber = fiber
+            fiber = null
+            if (brokenFiber) {
+              try { await brokenFiber.dispose() } catch { /* 新代自己卸不干净时，回滚仍然照试 */ }
             }
-          } catch (rollbackError) {
-            lastError = `${lastError}；回滚到 ${oldCurrent.version} 也失败：${rollbackError?.message || rollbackError}`
+            await rollbackTo(oldCurrent, oldLoaded, failure)
+            const error = new Error(failure)
+            error.code = 'self_check_failed'
+            throw error
           }
         }
+        return status()
+      } catch (error) {
+        // 自检那条已经在上面退回过一次了，别退第二遍（第二遍会把刚装回去的旧代再卸一次）。
+        // 但它记下的「退回也失败」那句话不能在这里被覆盖掉 —— 那才是真机上最要紧的一条。
+        if (error?.code !== 'self_check_failed') {
+          lastError = `装载 ${target.version} 失败：${error?.message || error}`
+          if (oldCurrent) await rollbackTo(oldCurrent, oldLoaded, lastError)
+        }
         throw error
       }
     })().finally(() => {
@@ -199,28 +285,47 @@ export function createRuntime() {
     return swapping
   }
 
-  /** 第一次激活；最高代装载失败时按优先级尝试保留的回退代。 */
-  async function start(context) {
+  /**
+   * 第一次激活；最高代装载失败时按优先级尝试保留的回退代；全失败则按固定间隔重试有限次。
+   *
+   * 为什么要重试（2026-10-25 真机 404）：一次失败 = **整张控制面路由表都不在**，而设置页
+   * 的「移动端」照样画得出来（客户端半边按包扫描，不看宿主 fiber 活没活），于是现场只表现成
+   * 「读取宿主状态失败: HTTP 404」。失败最常见的原因恰好是**可能自己好**的：注入的服务
+   * （typertGateway / apiProxy）比本插件晚就位、撞上 20s 装载上限，或者第一次装载撞上
+   * IO/时序抖动。一次失败就永久躺平到下次重启，等于把一个瞬态问题固定成故障。
+   */
+  async function start(context, options = {}) {
     ctx = context
+    const log = typeof options.log === 'function' ? options.log : () => {}
     const candidates = resolveGenerations()
     if (!candidates.length) throw new Error('找不到任何一代实现：包内的 lib/impl.js 缺失')
-    const failures = []
-    for (const target of candidates) {
-      try {
-        const { loaded, fiber: startedFiber } = await activate(target)
-        fiber = startedFiber
-        loadedCurrent = loaded
-        current = describe(loaded, target.dir)
-        activatedAt = new Date().toISOString()
-        lastError = failures.length
-          ? `${failures.join('；')}；已回退到 ${target.version}（${target.source}）`
-          : null
-        return status()
-      } catch (error) {
-        failures.push(`装载 ${target.version}（${target.source}）失败：${error?.message || error}`)
+    let lastFailure = ''
+    for (let attempt = 1; attempt <= START_RETRY_LIMIT; attempt += 1) {
+      const failures = []
+      for (const target of candidates) {
+        if (detached) throw new Error('插件已经卸载，不再重试装载')
+        try {
+          const { loaded, fiber: startedFiber } = await activate(target)
+          fiber = startedFiber
+          loadedCurrent = loaded
+          current = describe(loaded, target.dir)
+          activatedAt = new Date().toISOString()
+          lastError = failures.length
+            ? `${failures.join('；')}；已回退到 ${target.version}（${target.source}）`
+            : null
+          return status()
+        } catch (error) {
+          failures.push(`装载 ${target.version}（${target.source}）失败：${error?.message || error}`)
+        }
       }
+      lastFailure = `所有可用插件实现均装载失败：${failures.join('；')}`
+      if (attempt >= START_RETRY_LIMIT) break
+      lastError = `${lastFailure}（第 ${attempt} 次，${START_RETRY_MS / 1000}s 后重试）`
+      log('warn', 'dsh-mobile-plugin: 装载失败，%d 秒后重试：%s', START_RETRY_MS / 1000, lastFailure)
+      await sleep(START_RETRY_MS)
     }
-    throw new Error(`所有可用插件实现均装载失败：${failures.join('；')}`)
+    lastError = lastFailure
+    throw new Error(lastFailure)
   }
 
   /** 等在飞请求结束（最多 `DRAIN_TIMEOUT_MS`）。 */

package/lib/shell/self-check-after-swap.js

@@ -0,0 +1,93 @@
+/**
+ * 换代之后的自检：新版装起来之后，**手机要打的那批接口**真的能用吗？不能就退回上一代。
+ *
+ * ## 为什么这一条不能交给手机
+ *
+ * 装坏的后果是「App 连不上这台设备」。那一刻手机上没有任何按钮发得出去 —— 让 App 去按
+ * 「回滚」等于让一个已经断线的客户端去救自己的连接。所以这件事必须由**还活着的宿主进程**
+ * 自己做完，手机那边只在事后读到一条「上次装失败了，已自动退回 X」。
+ *
+ * ## 判据：问它自己的 `/health`，看回的是什么
+ *
+ * 不看日志、不猜堆栈，直接打本机的 `127.0.0.1:<宿主端口>`：
+ *
+ *  · 回 200 + `service: 'dsh-mobile-plugin'` → 活，路由挂上了；
+ *  · 回 401 → 也活：移动端守卫先核 token 再谈路由，没带 token 回 401 说明实现与守卫都在；
+ *  · 回 404 / 别的 service → **死了**：端口在、但插件那批路由没挂上，手机打过去就是这个 404；
+ *  · 超时 → **死了**：连上了但不回包，多半是某个 handler 卡在等一个永远不来的依赖；
+ *  · 连不上（ECONNREFUSED）→ **不算数**：那是宿主 webServer 自己没起来，与新代无关，
+ *    退回去也救不了。如实报 `skip`。
+ *
+ * 最后那一条是这次刻意分开的：把「宿主没在监听」当成「新版坏了」会退掉一次其实成功的
+ * 更新（开发机上跑测试时就是这么一种现场：假 webServer 有个端口号，但没有任何东西在听）。
+ *
+ * ## 端口从哪儿来
+ *
+ * 用宿主的 `ctx.webServer.port`（运行中那一份），不是配置里的默认值 —— 端口被改过之后，
+ * 配置与实绑可能不同，按配置去问会问到一个没人监听的地方，于是「自检失败」全是假的。
+ */
+
+/** 自检的超时上限：本机环回，正常几十毫秒。给 3 秒已经很宽。 */
+export const SELF_CHECK_TIMEOUT_MS = 3000
+
+/** 请求的那条路径：与 App 首屏打的是同一条（见 lib/routes/mobile-api.js）。 */
+export const SELF_CHECK_PATH = '/api/mobile/v1/health'
+
+/** 服务标识：宿主自己的 /health 回的就是这个（中转回 'dsh-mobile-relay'）。 */
+export const SELF_CHECK_SERVICE = 'dsh-mobile-plugin'
+
+/** 连接层失败（宿主 webServer 没起来）的错误码。 */
+const CONNECTION_ERRORS = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL'])
+
+/** 从 fetch 抛出来的东西里挖出底层 syscall 错误码（undici 把它塞在 cause 里）。 */
+function connectionCodeOf(error) {
+  let cursor = error
+  for (let depth = 0; depth < 4 && cursor; depth += 1) {
+    if (typeof cursor.code === 'string' && CONNECTION_ERRORS.has(cursor.code)) return cursor.code
+    cursor = cursor.cause
+  }
+  return null
+}
+
+/**
+ * 问一次：这一代实现活着吗？
+ *
+ * @param {object} options
+ * @param {number} options.port 宿主 webServer 实绑端口
+ * @param {number} [options.timeoutMs]
+ * @param {typeof fetch} [options.fetchImpl] 注入只为测试
+ * @returns {Promise<{ok: true} | {skip: true, reason: string} | {ok: false, reason: string}>}
+ */
+export async function checkGenerationAlive({ port, timeoutMs = SELF_CHECK_TIMEOUT_MS, fetchImpl = fetch } = {}) {
+  const value = Number(port)
+  if (!Number.isFinite(value) || value <= 0) {
+    return { skip: true, reason: '拿不到宿主端口，跳过自检' }
+  }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${value}${SELF_CHECK_PATH}`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    })
+    if (response.status === 401) return { ok: true }
+    if (response.status === 404) {
+      return { ok: false, reason: `自检接口 404：新版没有把 ${SELF_CHECK_PATH} 挂上` }
+    }
+    if (!response.ok) return { ok: false, reason: `自检接口回了 HTTP ${response.status}` }
+    const body = await response.json().catch(() => null)
+    if (!body || body.service !== SELF_CHECK_SERVICE) {
+      return { ok: false, reason: `自检接口回的不是本插件（${body && body.service ? String(body.service) : '没有 service 字段'}）` }
+    }
+    return { ok: true }
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      return { ok: false, reason: `自检超时（${timeoutMs}ms）：插件起来了但接口没应答` }
+    }
+    const code = connectionCodeOf(error)
+    if (code) return { skip: true, reason: `宿主 webServer 没在 ${value} 端口上监听（${code}），与新版无关，跳过自检` }
+    return { ok: false, reason: `自检请求失败：${String(error?.message || error)}` }
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/lib/shell/updater.js

@@ -375,18 +375,37 @@ async function runUpdate({ runtime, base, hostService = () => null, updateState,
   let swapped = false
   let swapFailure = null
   let deferred = false
+  /**
+   * 换代之后自检没过、外壳自己退回去了。
+   *
+   * 判据与动作都在 `runtime.js`（它才知道新版到底装起来了没有），这里只把那条**已经发生
+   * 过的事实**抄进这一轮的账。手机端不按回滚 —— 装坏的后果正是 App 连不上，那时候它按不了
+   * 任何东西 —— 它只用这条记录在**下一次连上之后**如实显示「上次装失败了，已退回 X」。
+   */
+  let rollback = null
   if (outcome.installed === true || newerOnDisk) {
     const attempt = await swapTo(runtime, disk ?? runningBefore, { auto, log })
     swapped = attempt.swapped
     swapFailure = attempt.failure
     deferred = attempt.deferred === true
+    rollback = attempt.rollback ?? null
   }
+  const rolledBack = Boolean(rollback && rollback.ok)
   const lastApply = {
     ...outcome,
     installed: outcome.installed === true,
     swapped,
-    state: swapFailure ? 'installed-not-swapped' : (outcome.state ?? (outcome.installed || outcome.skipped ? 'succeeded' : 'failed')),
-    failure: swapFailure ?? outcome.failure ?? null,
+    state: rolledBack
+      ? 'rolled-back'
+      : swapFailure ? 'installed-not-swapped' : (outcome.state ?? (outcome.installed || outcome.skipped ? 'succeeded' : 'failed')),
+    // 退回去了的话，真正失败的原因是自检那句话，而不是「换代码抛错」那个笼统说法。
+    failure: rolledBack
+      ? { code: 'self_check_failed', message: rollback.reason }
+      : (swapFailure ?? outcome.failure ?? null),
+    /** 装上了、但新版没通过自检，于是外壳自己退回了上一代。 */
+    rolledBack,
+    /** 退回之后跑着的版本（退成功才有）。 */
+    runningAfterRollback: rolledBack ? (rollback.toVersion ?? null) : null,
     // 换代由外壳就地做，市场那套「装完要重启」在本项目一律不照做。只为如实上报。
     restartRequired: false,
     refreshRequired: false,
@@ -422,14 +441,29 @@ async function swapTo(runtime, target, { auto = false, log = () => {} } = {}) {
     }
   }
   swapAttempts.set(key, Math.max(tried, 1))
+  let rollback = null
   try {
     const status = await runtime.reload()
     swapAttempts.delete(key)
+    // 外壳把「装起来了但自检没过、于是自己退回去」记在 `lastRollback` 上，而不是抛错
+    // （它退成功了，进程还活着）。这里把它捞出来，交给这一轮的账 —— 手机端要读的就是它。
+    rollback = status?.lastRollback ?? null
+    if (rollback && rollback.ok) {
+      log('warn', 'dsh-mobile-plugin: 新版自检没过，已退回 %s：%s', rollback.toVersion, rollback.reason)
+      return {
+        swapped: false,
+        rollback,
+        failure: { code: 'self_check_failed', message: rollback.reason },
+      }
+    }
     log('info', 'dsh-mobile-plugin: 已就地换到 %s（无需重启 DSH）', status?.version ?? key)
     return { swapped: true, status }
   } catch (error) {
+    // 新版装载直接抛错：runtime 已经按老规矩回滚过一代了，那条回滚也记在 `lastRollback`。
+    try { rollback = runtime.status()?.lastRollback ?? null } catch { rollback = null }
     return {
       swapped: false,
+      rollback,
       failure: { code: 'swap_failed', message: `新版已经装到盘上（${key}），但换代码没成：${String(error?.message || error)}` },
     }
   }