dsh-mobile-plugin 0.4.9 → 0.5.1

package/lib/relay/preview.js

@@ -3,21 +3,29 @@
 /**
  * 预览字节管道（宿主侧）。
  *
- * 手机 App 的内置浏览器要看到桌面机上「开发中的网页」，而那些 dev server 只监听宿主的
- * 127.0.0.1:<port>，手机、中转、局域网代理都够不着。所以链路上有一段跑在宿主进程里的搬运工。
+ * 手机 App 的内置浏览器要看到桌面机上「开发中的网页」，而那些 dev server 只在某一块网卡的
+ * 某个端口上，手机、中转、局域网代理都够不着。所以链路上有一段跑在宿主进程里的搬运工。
  *
- * 是字节管道而不是 HTTP 代理：一个页面是几百次请求加一条活着的 HMR WebSocket，端口在建立
+ * 是字节管道而不是 HTTP 代理：一个页面是几百次请求加一条活着的 HMR WebSocket，目标在建立
  * 管道时协商一次，之后完全不解析内容。于是内置浏览器的地址栏与实际 Host 都是
  * `localhost:3001`，dev server 生成的绝对地址自动闭环、零配置；做路径改写反而会立刻全 404。
  *
- * 环回地址要双栈试（macOS 上不少 dev server 只监听 `::1`）。WS 升级、SSE、分块传输原样穿过。
+ * 目标（`host` / `scheme` / `port`）由手机从查询串带过来，解析与拨号都发生在电脑这一侧：
+ * 手机永远只跟自己的 localhost 说明文，证书、ATS、明文限制那套就彻底与它无关了。https 的
+ * TLS 也在这里发起——目标是本机或私网，自签证书是本地开发的常态。
  *
- * 代价：宿主无法审查内容，端口就是唯一边界，所以 `protectedPorts()` 按身份拒绝——DSH 自身的
- * web 端口永远不许从预览进来。
+ * 环回目标要双栈试（macOS 上不少 dev server 只监听 `::1`）；别的目标只拨那一个。
+ * WS 升级、SSE、分块传输原样穿过。
+ *
+ * 代价：宿主无法审查内容，边界只有「端口」与「目标主机」两道。前者由 `protectedPorts()` 按
+ * 身份拒绝——DSH 自身的 web 端口永远不许从预览进来；后者由 `isAllowedPreviewHost` 收到本机、
+ * 私网与保留域名——放开公网，这条管道就等于一台任意目标的连接中转，移动 API 的能力面就扩了。
  */
 
 const net = require('node:net');
+const tls = require('node:tls');
 const { WebSocketServer } = require('ws');
+const { ipv4Number, ipv6Number } = require('./lan-network.cjs');
 
 /**
  * 同一个宿主上同时在跑的预览连接上限。
@@ -39,7 +47,7 @@ const SEND_RESUME_POLL_MS = 20;
 const UPSTREAM_CONNECT_TIMEOUT_MS = 10_000;
 
 /**
- * WS 握手已成、但上游 `net.connect` 还没连上的那几百微秒里，手机已经发出来的字节
+ * WS 握手已成、但上游还没连上的那几百微秒里，手机已经发出来的字节
  * 最多攒这么多。浏览器不会等我们连好上游才发请求，所以这段字节必须存住；攒过头说明
  * 上游根本连不上，这时宁可断掉这条管道，也不能无限吃内存。
  */
@@ -68,6 +76,89 @@ function parsePreviewPort(req) {
   return port;
 }
 
+/** 环回类主机：这些写法都指「电脑自己」，拨号要走双栈（见 `previewDialTargets`）。 */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', '::']);
+
+/**
+ * 能从预览拨过去的 IPv4 段。
+ *
+ * 比 `lan-network.cjs` 的「局域网候选」多两段：100.64/10（运营商级 NAT，VPN 与容器网段常用）
+ * 与 169.254/16（链路本地）——它们不该当直连候选，但都是开发服务真的会绑上去的地址。
+ */
+const ALLOWED_IPV4_RANGES = [
+  [0x0a000000, 0x0affffff], // 10/8
+  [0xac100000, 0xac1fffff], // 172.16/12
+  [0xc0a80000, 0xc0a8ffff], // 192.168/16
+  [0x64400000, 0x647fffff], // 100.64/10
+  [0xa9fe0000, 0xa9feffff], // 169.254/16
+  [0x7f000000, 0x7fffffff], // 127/8 回环
+];
+
+/**
+ * 只有内网 DNS / mDNS 才解析得了的保留后缀。
+ *
+ * `.test`、`.localhost` 是 RFC 留给本机测试的，`.local` 是 mDNS，`.internal` / `.lan` /
+ * `.home.arpa` 是各家路由器与公司内网的惯例。公网域名一律不放，哪怕它此刻解析到私网地址
+ * ——解析结果随时会变，白名单必须是静态可判的。
+ */
+const RESERVED_HOST_SUFFIXES = ['.localhost', '.test', '.local', '.internal', '.lan', '.home.arpa'];
+
+/**
+ * 这个主机能不能从预览拨过去（能力边界，和 App 侧「哪条地址该进内置浏览器」是同一条线）。
+ *
+ * @param {string} host 已经归一化（小写、无方括号）的主机
+ */
+function isAllowedPreviewHost(host) {
+  if (LOOPBACK_HOSTS.has(host)) return true;
+  const v4 = ipv4Number(host);
+  if (v4 !== null) return ALLOWED_IPV4_RANGES.some(([start, end]) => v4 >= start && v4 <= end);
+  const v6 = ipv6Number(host);
+  if (v6 !== null) {
+    // fc00::/7 是唯一本地地址（内网自己编的前缀），fe80::/10 只在本链路内通。
+    return v6 >> 121n === 0x7en || v6 >> 118n === 0x3fan;
+  }
+  return RESERVED_HOST_SUFFIXES.some((suffix) => host.length > suffix.length && host.endsWith(suffix));
+}
+
+/**
+ * 依次要拨的地址。
+ *
+ * 环回一律**双栈**：macOS 上 Vite 之类的 dev server 默认只监听 `::1`，只连 `127.0.0.1`
+ * 必然是 ECONNREFUSED，用户看到的就是「电脑上这个端口没有服务」。两个地址都是电脑自己，
+ * 谁在听就用谁。别的目标只拨它自己那一个——换地址重试就是把「连不上」变成「连上了另一台
+ * 机器」，那比失败更糟。
+ *
+ * @returns {string[]} 有顺序的拨号目标，前一个「还没连上就失败」才换下一个
+ */
+function previewDialTargets(host) {
+  return LOOPBACK_HOSTS.has(host) ? ['127.0.0.1', '::1'] : [host];
+}
+
+/**
+ * 从升级请求的查询串里取 host 与 scheme。
+ *
+ * 和 `port` 一样只能靠查询串带（中转的升级分发不看路径，宿主的升级匹配又按 pathname 精确、
+ * 忽略 query）。缺省是「电脑自己的环回 + 明文」，也就是内置浏览器最常见的那个形状。
+ *
+ * @returns {{host: string, scheme: 'http'|'https'}|null} host 为空、scheme 认不出都算非法
+ */
+function parsePreviewTarget(req) {
+  let params;
+  try {
+    params = new URL(req && req.url ? req.url : '/', 'http://preview.invalid').searchParams;
+  } catch {
+    return null;
+  }
+  const rawHost = params.get('host');
+  // 地址栏那种方括号写法（`[::1]`）会原样带过来，剥掉再判：留着它既不是环回、也拼不出地址。
+  const host = (rawHost === null ? 'localhost' : rawHost.trim().toLowerCase()).replace(/^\[|\]$/g, '');
+  if (host === '') return null;
+  const rawScheme = params.get('scheme');
+  const scheme = rawScheme === null || rawScheme === '' ? 'http' : rawScheme.trim().toLowerCase();
+  if (scheme !== 'http' && scheme !== 'https') return null;
+  return { host, scheme };
+}
+
 const HTML_HEAD = '<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">'
   + '<meta name="viewport" content="width=device-width,initial-scale=1">'
   + '<title>预览未建立</title><style>'
@@ -136,9 +227,11 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
   }
 
   /**
-   * 一条管道：完成 WebSocket 握手，然后把它与 `127.0.0.1:<port>` 对搬。
+   * 一条管道：完成 WebSocket 握手，然后把它与目标对搬。
+   *
+   * @param {{port: number, scheme: 'http'|'https', hosts: string[], servername?: string}} target 拨号计划
    */
-  function openPipe(ws, port) {
+  function openPipe(ws, { port, scheme, hosts, servername }) {
     activeStreams += 1;
     noteGrant(port);
 
@@ -197,29 +290,33 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
     ws.on('close', finish);
     ws.on('error', finish);
 
-    // 上游必须**双栈**拨号：macOS 上 Vite 之类的 dev server 默认只监听 `::1`，只连
-    // `127.0.0.1` 必然是 ECONNREFUSED，用户看到的就是「电脑上这个端口没有服务」。
-    // 两个地址都是环回，谁在听就用谁；只有在前一个「还没连上就失败」时才换下一个。
-    const upstreamHosts = ['127.0.0.1', '::1'];
+    // 拨号计划在进门时就定好了（见 `previewDialTargets`）：环回两个地址依次试，别的只拨一个。
     let hostIndex = 0;
     let connectTimer = null;
     let lastError = 'ECONNREFUSED';
 
+    /** 失败页与日志里怎么写「拨的是哪儿」：IPv6 带方括号，https 连协议一起写。 */
+    const describeTarget = (host) => {
+      const address = host.includes(':') ? `[${host}]:${port}` : `${host}:${port}`;
+      return scheme === 'https' ? `https://${address}` : address;
+    };
+
     const clearConnectTimer = () => {
       if (connectTimer) { clearTimeout(connectTimer); connectTimer = null; }
     };
 
-    /** 两个环回地址都连不上：握手已经成了，没法再用 HTTP 状态码，只能借管道送失败页。 */
+    /** 计划里的地址都连不上：握手已经成了，没法再用 HTTP 状态码，只能借管道送失败页。 */
     const failUpstream = () => {
       log(`preview port ${port}: ${lastError}`);
       // 这条管道本来就是透明的，索性由宿主写一段 502 响应借它送进内置浏览器——比让
-      // WebView 显示系统错误页清楚得多。
+      // WebView 显示系统错误页清楚得多。目标要照实写：用户得知道电脑去连的是哪儿。
       if (ws.readyState === ws.OPEN) {
+        const unreachable = hosts.map(describeTarget).join('，也连不上 ');
         const body = Buffer.from(renderFailureHtml({
           title: '电脑上这个端口没有服务',
           detail: lastError === 'ECONNREFUSED'
-            ? '开发服务可能已经停了。回到 DSH 重新启动它，再刷新这个页面。'
-            : `宿主连不上 127.0.0.1:${port}，也连不上 [::1]:${port}（${lastError}）。`,
+            ? `宿主连不上 ${unreachable}：开发服务可能已经停了。回到 DSH 重新启动它，再刷新这个页面。`
+            : `宿主连不上 ${unreachable}（${lastError}）。`,
           port,
         }), 'utf8');
         const head = Buffer.from(
@@ -234,17 +331,23 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
       finish();
     };
 
-    /** 换下一个环回地址；都试过了就按失败收场。 */
+    /** 换计划里的下一个地址；都试过了就按失败收场。 */
     const advanceHost = () => {
       if (finished) return;
       hostIndex += 1;
-      if (hostIndex < upstreamHosts.length) { dialUpstream(); return; }
+      if (hostIndex < hosts.length) { dialUpstream(); return; }
       failUpstream();
     };
 
     function dialUpstream() {
-      const host = upstreamHosts[hostIndex];
-      const socketToUpstream = net.connect({ host, port });
+      const host = hosts[hostIndex];
+      // https 的 TLS 在这里发起，手机那侧始终只看到自己环回上的明文。`rejectUnauthorized`
+      // 必须关掉：目标是本机或私网，自签证书是本地开发的常态。SNI 用手机点名的那个主机
+      // （见 `servername`）——浏览器访问 `localhost:5173` 发的就是 `localhost`，哪怕实际
+      // 拨过去的是 127.0.0.1。
+      const socketToUpstream = scheme === 'https'
+        ? tls.connect({ host, port, rejectUnauthorized: false, servername })
+        : net.connect({ host, port });
       upstream = socketToUpstream;
 
       // 握上手之前给一发超时；连上之后这条 TCP 就是长连接（SSE、HMR 都从它过），
@@ -271,9 +374,10 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
         failUpstream();
       });
 
-      socketToUpstream.on('connect', () => {
+      // TLS 的「连上了」以握手完成为准：`connect` 在 TLSSocket 上只代表 TCP 通了。
+      socketToUpstream.on(scheme === 'https' ? 'secureConnect' : 'connect', () => {
         clearConnectTimer();
-        log(`preview port ${port}: 管道已接通（${host}）`);
+        log(`preview port ${port}: 管道已接通（${describeTarget(host)}）`);
         upstreamReady = true;
 
         socketToUpstream.on('drain', () => { if (!finished && ws.readyState === ws.OPEN) ws.resume(); });
@@ -315,10 +419,20 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
     const port = parsePreviewPort(req);
     if (port === null) return refuseUpgrade(socket, 400, 'Bad Request', '缺少或非法的 port 参数');
 
+    const target = parsePreviewTarget(req);
+    if (target === null) return refuseUpgrade(socket, 400, 'Bad Request', '非法的 host 或 scheme 参数');
+
     let allowed = false;
     try { allowed = Boolean(authorized(req)); } catch { allowed = false; }
     if (!allowed) return refuseUpgrade(socket, 401, 'Unauthorized', '移动端凭据无效');
 
+    // 目标白名单与端口同一个道理：这条管道只负责把手机的一条连接接到电脑这一侧，能拨到
+    // 哪儿就是它能做成什么。公网目标在这里掐掉（见文件头与 `isAllowedPreviewHost`）。
+    if (!isAllowedPreviewHost(target.host)) {
+      return refuseUpgrade(socket, 403, 'Forbidden',
+        `目标 ${target.host} 不在预览允许的范围内（只允许本机、私网与保留域名）`);
+    }
+
     // DSH 自身的端口按**身份**拒绝，不是按数字拉黑。3080 是宿主 web 服务的实际端口
     // （`ctx.webServer.port`，可能被配置改过），从预览进来等于把桌面端 GUI/API 搬到了
     // 手机内置浏览器里——那条路刻意不做，所以在这里用同一个真值掐掉。
@@ -330,7 +444,14 @@ function createPreviewService({ authorized, protectedPorts, onLog }) {
       return refuseUpgrade(socket, 503, 'Service Unavailable', '预览连接数已达上限');
     }
 
-    wss.handleUpgrade(req, socket, head, (ws) => openPipe(ws, port));
+    wss.handleUpgrade(req, socket, head, (ws) => openPipe(ws, {
+      port,
+      scheme: target.scheme,
+      hosts: previewDialTargets(target.host),
+      // IP 字面量不给 SNI：Node 直接把 IP 当 servername 判成非法参数，环回双栈掉落出来的
+      // 地址也一样——所以这里取的是手机点名的那个主机。
+      servername: net.isIP(target.host) ? undefined : target.host,
+    }));
   }
 
   return {
@@ -352,6 +473,8 @@ module.exports = {
   MAX_PREVIEW_STREAMS,
   MAX_PREVIEW_MESSAGE_BYTES,
   createPreviewService,
+  isAllowedPreviewHost,
   parsePreviewPort,
+  previewDialTargets,
   renderFailureHtml,
 };

package/lib/routes/control-plane.js

@@ -33,6 +33,9 @@ const { canListen } = require('../relay/port-allocator.cjs');
 // `advertisedCandidates` 同口径。IPv6 那份只**显示**、不进那个选择：它由手机侧实测择优
 // （和公网中转比速度），做成可选中等于骗人（同 A3-40 的刻意设计）。
 const { lanCandidates, publicCandidates, ipv6Candidates } = require('../relay/lan-network.cjs');
+// 「手机连不上时哪一环断了」这份连接自检：本机只读、不改任何东西（口径见
+// connection-check.js 与 firewall-probe.js 的文件头）。
+const { createConnectionCheck } = require('../relay/connection-check.js');
 const desktopView = require('../desktop-view.cjs');
 const readReceipt = require('../read-receipt.cjs');
 // 客户端半边的活体台账：两条绿点同步通道都是「单向轮询 + 无回执」，不记账就永远分不开
@@ -275,6 +278,14 @@ function registerControlPlaneRoutes(deps) {
     getLanProxyStats,
   });
   const webAccessWindow = createWebAccessWindow();
+  /**
+   * 连接自检：面板的引导页与「连接状态」卡读它。
+   *
+   * 三条取值器都是现成的：`status()` 给监听与隧道、`lanCandidates()` 给监听地址清单、
+   * `mobileActivity()` 给「手机最近来过没有」。多出来的只有防火墙那一项，它自带缓存
+   * （见 `../relay/firewall-probe.js`）—— 面板打开弹窗与后台那一次巡检共用同一份结果。
+   */
+  const connectionCheck = createConnectionCheck({ status, lanCandidates, mobileActivity });
   const localOnly = createWebAccessLocalOnly({
     localOnly: baseLocalOnly,
     trustedLocalUi: typeof trustedLocalUi === 'function' ? trustedLocalUi : () => false,
@@ -704,6 +715,20 @@ function registerControlPlaneRoutes(deps) {
     }
     sendJson(res, 200, { ok: true, port, available: await canListen(port, '0.0.0.0'), ours: false, listening, currentPort })
   }) })
+  /**
+   * 连接自检：`GET /api/relay/selfcheck`（只读）。
+   *
+   * 回答「手机连不上时，这台电脑这一侧断在哪一环」。载荷与五档结论的口径写在
+   * `../relay/connection-check.js` 的文件头；防火墙那几格的口径写在
+   * `../relay/firewall-probe.js` 的文件头。
+   *
+   * **只在有人看的时候跑**（面板弹窗打开、或手机上久没来过时的那一次巡检）：
+   * 防火墙那条要 fork 进程，跟着面板三秒一轮的状态轮询跑等于每三秒起一个进程。
+   */
+  registerRoute({ kind: 'exact', path: '/api/relay/selfcheck', handler: localOnly('GET', async (req, res) => {
+    const force = /[?&]force=1\b/.test(String(req?.url || ''))
+    sendJson(res, 200, await connectionCheck.run({ force }))
+  }) })
   registerRoute({ kind: 'exact', path: '/api/relay/reconnect', handler: localOnly('POST', async (_req, res) => {
     await syncSidecar()
     sendJson(res, 200, status())
@@ -966,6 +991,7 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/revoke-all',
   '/api/relay/config',
   '/api/relay/check-port',
+  '/api/relay/selfcheck',
   '/api/relay/reconnect',
   '/api/relay/update/status',
   '/api/relay/update/check',

package/lib/routes/mobile-api.js

@@ -17,6 +17,7 @@ const { orderCandidates, withManualCandidate } = require('../relay/lan-network.c
 const sessions = require('../mobile/sessions.js');
 const sessionModelOptions = require('../mobile/session-model-options.js');
 const sessionFile = require('../mobile/session-file.js');
+const sessionStep = require('../mobile/session-step.js');
 const fileRead = require('../mobile/file-read.js');
 const stats = require('../mobile/stats.js');
 const agentPresets = require('../mobile/agent-presets.js');
@@ -225,6 +226,8 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/push-token', pushNotifyRoute.createPushTokenHandler({ pushNotify: deps.pushNotify }))
   route('/api/mobile/v1/session', sessions.handleSession)
   route('/api/mobile/v1/session/messages', sessions.handleMessages)
+  // 一步的过程详情：清单只带一行摘要，点开某一步才来这里取参数 / 输出 / diff / 思考全文。
+  route('/api/mobile/v1/session/step', sessionStep.handleSessionStep)
   route('/api/mobile/v1/session/attachment', sessions.handleSessionAttachment)
   // 会话文件：允许本会话 present 声明的路径及会话工作区内的文件（见 mobile/session-file.js）。
   route('/api/mobile/v1/session/file', sessionFile.handleSessionFile)

package/lib/shell/half-route.js

@@ -0,0 +1,73 @@
+/**
+ * 宿主半边的自检口：`/api/relay/host-half` 与它的 `/reload`。
+ *
+ * 这两条**必须由外壳注册**，不能放进实现：实现装载失败时整张 `/api/relay/*` 都不在，
+ * 而「它为什么没起来」只有外壳答得出来（外壳自己活得好好的是刻意的故障边界）。
+ * 现场的样子是设置页一句「插件宿主侧没有加载」，原因只打在宿主 stderr 里、桌面端不落盘，
+ * 用户看不见、我们也查不出来 —— 这两条就是那个原因唯一的出口。
+ *
+ * 放在 `lib/shell/` 而不是 `lib/index.js` 里，是因为外壳的守卫钉着「只该有装载逻辑」。
+ * 这里只干两件小事：把 state 拍成响应体（`half-view.js`），以及把「重新装载」转给
+ * runtime 那套换代秩序（串行、先停后起、失败回滚）。
+ *
+ * 两条都走 `localOnly`：拒绝中转/局域网转发来的请求、拒绝跨站、钉住 method。它们能读到的
+ * 是这台机器的插件装载状态，不值得让别处看见。
+ */
+
+import { createRequire } from 'node:module'
+import { hostHalfView } from './half-view.js'
+
+const require = createRequire(import.meta.url)
+const { localOnly } = require('../http/routing.js')
+const { sendJson } = require('../shared/http-util.js')
+
+export const HOST_HALF_PATH = '/api/relay/host-half'
+export const HOST_HALF_RELOAD_PATH = '/api/relay/host-half/reload'
+
+/**
+ * 挂上两条路由，返回清理函数（给 `ctx.effect` 当返回值用）。
+ *
+ * @param {object} ctx 外壳那份 context（只用它的 `webServer`）。
+ * @param {{status: () => object, reload: () => Promise<unknown>}} runtime 代际运行时。
+ * @param {{installedVersion?: () => string|null, installedShellHash?: () => string|null,
+ *   runningShellHash?: string|null}} [deps] 盘上那一份的坐标，只为「要不要重启」这一格。
+ */
+export function installHostHalf(ctx, runtime, deps = {}) {
+  const server = ctx?.webServer
+  if (typeof server?.register !== 'function') return () => {}
+  const installedVersion = typeof deps.installedVersion === 'function' ? deps.installedVersion : () => null
+  const installedShellHash = typeof deps.installedShellHash === 'function' ? deps.installedShellHash : () => null
+  const runningShellHash = typeof deps.runningShellHash === 'string' ? deps.runningShellHash : null
+  const view = () => hostHalfView(runtime.status(), {
+    installedVersion: installedVersion(),
+    shellChanged: installedShellHash() !== null && installedShellHash() !== runningShellHash,
+  })
+  const offs = [
+    server.register({
+      kind: 'exact',
+      path: HOST_HALF_PATH,
+      handler: localOnly('GET', async (_req, res) => sendJson(res, 200, view())),
+    }),
+    server.register({
+      kind: 'exact',
+      path: HOST_HALF_RELOAD_PATH,
+      handler: localOnly('POST', async (_req, res) => {
+        try {
+          await runtime.reload()
+          return sendJson(res, 200, view())
+        } catch (error) {
+          // 装载失败时外壳已经按老规矩回滚过了，这里只把原因与回滚后的状态一起交出去：
+          // 面板要能原样显示「还是不行，因为……」。
+          return sendJson(res, 200, {
+            ...view(),
+            ok: false,
+            error: { code: 'reload-failed', message: String((error && error.message) || error) },
+          })
+        }
+      }),
+    }),
+  ].filter(off => typeof off === 'function')
+  return () => {
+    for (const off of offs) off()
+  }
+}

package/lib/shell/half-view.js

@@ -0,0 +1,37 @@
+/**
+ * 宿主半边自检的响应体：把 `runtime.status()` 收成设置页能读的那几格。
+ *
+ * 为什么单独一个纯函数：拼响应体的地方在外壳里，而外壳不好在测试里跑起来（它一 apply
+ * 就真的去装载实现）。这里只做取值与白名单，测试直接喂一份 status 就能钉住形状。
+ *
+ * **`lastError` 是这一条接口存在的理由**：实现装载失败时外壳仍然活着，于是路由 404、
+ * 设置页只显示一句「插件宿主侧没有加载」，而真正的原因（等哪个服务超时、哪一代装不上）
+ * 只打在宿主 stderr 里，桌面端不落盘、用户看不见、我们也就查不出来。这条接口把它原样
+ * 交给设置页。
+ */
+
+/**
+ * @param {object} status `runtime.status()` 的快照。
+ * @param {{installedVersion?: string|null, shellChanged?: boolean}} [extra]
+ *   盘上那一份的坐标（市场装完立刻变，和跑着的对照就看得出要不要重启）。
+ */
+export function hostHalfView(status, extra = {}) {
+  const s = status && typeof status === 'object' ? status : {};
+  const info = extra && typeof extra === 'object' ? extra : {};
+  return {
+    ok: true,
+    half: {
+      version: typeof s.version === 'string' ? s.version : null,
+      source: typeof s.source === 'string' ? s.source : null,
+      previousVersion: typeof s.previousVersion === 'string' ? s.previousVersion : null,
+      activatedAt: typeof s.activatedAt === 'string' ? s.activatedAt : null,
+      lastError: typeof s.lastError === 'string' ? s.lastError : null,
+      /** 启动时那几次没成、现在仍在后台按长间隔重试 —— 面板据此劝人「再等等」而不是重装。 */
+      retrying: s.retrying === true,
+      retryAttempts: Number.isFinite(s.retryAttempts) ? s.retryAttempts : 0,
+      nextRetryAt: typeof s.nextRetryAt === 'string' ? s.nextRetryAt : null,
+      installedVersion: typeof info.installedVersion === 'string' ? info.installedVersion : null,
+      shellChanged: info.shellChanged === true,
+    },
+  };
+}

package/lib/shell/runtime.js

@@ -16,10 +16,26 @@ import { checkGenerationAlive } from './self-check-after-swap.js'
 
 /** 换代前等在飞请求归零的上限。 */
 const DRAIN_TIMEOUT_MS = 2000
-/** 等一代装载完成的上限。装载卡住（依赖永远不来）时不能把整个外壳拖死。 */
-const ACTIVATE_TIMEOUT_MS = 20000
+/**
+ * 等一代装载完成的上限。装载卡住（依赖永远不来）时不能把整个外壳拖死。
+ *
+ * 20s 在慢机器上不够：失败的首要原因就是注入的服务（typertGateway / apiProxy）比本插件
+ * 晚就位，而 Windows 冷启动、装了一堆插件的 DSH 要几十秒才轮到那条服务。真实现场是
+ * 「重启还是不行」—— 设置页一句 404，日志里什么都没有。
+ */
+const ACTIVATE_TIMEOUT_MS = 60000
 /** 首次装载全失败后的重试间隔与次数（重试理由见 `start()`）。 */
 const START_RETRY_LIMIT = 6
+/**
+ * 启动那一轮没成之后，后台继续按这个节奏重试多久。
+ *
+ * 失败代价是**整张控制面路由表都不在**，而根因多半是「服务晚到」这种会自己好的事。
+ * 只重试启动那六次（约五分钟）然后就躺平，等于把一个瞬态问题固定成故障，用户唯一的
+ * 出路是重启 —— 而重启正好又落回同一个时间窗里。这里按长间隔再试一小时，并让设置页
+ * 看得到「还在试」。
+ */
+const RETRY_BACKLOG_MS = 120000
+const RETRY_BACKLOG_LIMIT = 30
 /** 间隔可用环境变量压低，只给测试（与 `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)
@@ -68,6 +84,15 @@ export function createRuntime() {
    * 读到这条已经发生过的事实（`lastApply.rolledBack` 就是从它来的）。
    */
   let lastRollback = null
+  /**
+   * 后台补齐重试的账：启动那一轮失败后接着试，试到成功或额度用完。
+   *
+   * 这三格同时也是说给用户听的：`retrying` 决定面板劝人「再等等」还是「重装」，
+   * `nextRetryAt` 让人知道下一次是几分钟后。
+   */
+  let retryTimer = null
+  let retryAttempts = 0
+  let nextRetryAt = null
 
   /** 对外状态快照。控制面接口直接把它交给客户端。 */
   function status() {
@@ -80,6 +105,9 @@ export function createRuntime() {
       inFlight,
       swapping: swapping !== null,
       lastRollback,
+      retrying: retryTimer !== null,
+      retryAttempts,
+      nextRetryAt,
     }
   }
 
@@ -261,6 +289,7 @@ export function createRuntime() {
             throw error
           }
         }
+        clearBacklogRetry()
         return status()
       } catch (error) {
         // 自检那条已经在上面退回过一次了，别退第二遍（第二遍会把刚装回去的旧代再卸一次）。
@@ -286,37 +315,103 @@ export function createRuntime() {
    * （typertGateway / apiProxy）比本插件晚就位、撞上 20s 装载上限，或者第一次装载撞上
    * IO/时序抖动。一次失败就永久躺平到下次重启，等于把一个瞬态问题固定成故障。
    */
+  /**
+   * 把当前可用的每一代都试一遍：成功就装成当前代并返回 `{ok:true}`，全失败返回
+   * `{ok:false, failures}`。`start()` 与后台补齐重试共用这一份，别各写一遍。
+   *
+   * 候选**现算**而不是启动时抓一份快照：市场换过代、OTA 落过一版之后，这里要能看见新目录。
+   */
+  async function attemptAll() {
+    const failures = []
+    for (const target of resolveGenerations()) {
+      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 { ok: true, version: target.version }
+      } catch (error) {
+        failures.push(`装载 ${target.version}（${target.source}）失败：${error?.message || error}`)
+      }
+    }
+    return { ok: false, failures }
+  }
+
+  /** 停掉后台补齐重试（装成功后调用：再试一次只会撞同一批路由）。 */
+  function clearBacklogRetry() {
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer)
+      retryTimer = null
+    }
+    retryAttempts = 0
+    nextRetryAt = null
+  }
+
+  /**
+   * 启动那一轮没成之后接着试：长间隔、有额度，成功即停。
+   *
+   * 它是 `lastError` 之外的第二次机会，也是「用户什么都不做也能自己好」的那条路。
+   */
+  function scheduleBacklogRetry(log) {
+    if (detached || retryTimer !== null || retryAttempts >= RETRY_BACKLOG_LIMIT) return
+    retryAttempts += 1
+    nextRetryAt = new Date(Date.now() + RETRY_BACKLOG_MS).toISOString()
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      nextRetryAt = null
+      if (detached) return
+      void attemptAll().then(result => {
+        if (result.ok) {
+          retryAttempts = 0
+          log('info', 'dsh-mobile-plugin: 后台补齐成功，已装载 %s', result.version)
+          return
+        }
+        lastError = `所有可用插件实现均装载失败：${result.failures.join('；')}`
+        log('warn', 'dsh-mobile-plugin: 后台补齐仍未成功：%s', lastError)
+        scheduleBacklogRetry(log)
+      }).catch(error => {
+        lastError = `后台补齐装载出错：${error?.message || error}`
+        scheduleBacklogRetry(log)
+      })
+    }, RETRY_BACKLOG_MS)
+    if (typeof retryTimer.unref === 'function') retryTimer.unref()
+  }
+
+  /**
+   * 第一次激活；最高代装载失败时按优先级尝试保留的回退代；全失败则按固定间隔重试有限次，
+   * 之后交给后台补齐接着试。
+   *
+   * 为什么要重试：一次失败 = **整张控制面路由表都不在**，而设置页
+   * 的「移动端」照样画得出来（客户端半边按包扫描，不看宿主 fiber 活没活），于是现场只表现成
+   * 「读取宿主状态失败: HTTP 404」。失败最常见的原因恰好是**可能自己好**的：注入的服务
+   * （typertGateway / apiProxy）比本插件晚就位、撞上装载上限，或者第一次装载撞上 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 缺失')
+    if (!resolveGenerations().length) throw new Error('找不到任何一代实现：包内的 lib/impl.js 缺失')
     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}`)
-        }
+      const result = await attemptAll()
+      if (result.ok) {
+        clearBacklogRetry()
+        return status()
       }
-      lastFailure = `所有可用插件实现均装载失败：${failures.join('；')}`
+      lastFailure = `所有可用插件实现均装载失败：${result.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)
     }
     lastError = lastFailure
+    // 抛出去是为了让外壳那行日志照旧留下；后台补齐另起一条线，两条不冲突。
+    scheduleBacklogRetry(log)
     throw new Error(lastFailure)
   }
 
@@ -331,6 +426,7 @@ export function createRuntime() {
   /** 外壳被卸载时调用：停当前代，之后不再接受换代。 */
   async function detach() {
     detached = true
+    clearBacklogRetry()
     const oldFiber = fiber
     fiber = null
     current = null

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Mobile plugin",
+    "description": "Connect your phone or tablet to this computer's DSH: conversations, file transfer and plugin management on mobile."
+  }
+}