@mrrisega/dsh-remote 0.6.13 → 0.6.14

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

@@ -76,6 +76,7 @@ import { promisify } from "node:util";
 import { gzip as gzipCb } from "node:zlib";
 // 移动端适配层(经隧道访问的官方 dsh web 窄屏注入;DSH_MOBILE_ADAPTER=0 可关闭,默认开启)
 import { maybeInjectMobileAdapter } from "./mobile-adapter.mjs";
+import { discoverUpstream, resolveUpstreamHint, FALLBACK_UPSTREAM } from "./upstream-discovery.mjs";
 // 镜像页 E2EE 加密 shim(Phase-4):text/html 注入;DSH_E2EE_SHIM=0 可关闭,叠加 e2ee.enabled 灰度门
 import { maybeInjectE2eeShim } from "./e2ee-shim.mjs";
 // E2EE(端到端加密)客户端基建(Phase-2):MK 派生/会话密钥/信封/握手/开关
@@ -114,7 +115,23 @@ const CONFIG_PATH = process.env.DSH_BRIDGE_CONFIG || DEFAULT_CONFIG;
 // 隧道模式(唯一):bridge 主动 WS 连 relay-router 的 /_bridge
 const TUNNEL_URL = (process.env.DSH_BRIDGE_TUNNEL_URL || "").replace(/\/+$/, "");
 const TUNNEL_HEARTBEAT_MS = Math.max(100, Number(process.env.DSH_BRIDGE_HEARTBEAT_MS) || 15_000);
-const UPSTREAM = process.env.DSH_BRIDGE_UPSTREAM || "http://127.0.0.1:3080";
+/**
+ * 上游 dsh web 的地址。
+ *
+ * ⚠️ 这里**不能**只信环境变量 + 写死 3080（2026-09-23 两起用户实测）：
+ *   ① `dsh web --port 8090` / `--port 0`（系统分配）→ 3080 没人听；
+ *   ② **DSH Desktop**（Electron 壳 `dsh-plugin-desktop`）默认 43120，被占用还会 +1。
+ * bridge 与 watcher 共用同一份发现实现（`upstream-discovery.mjs`）：
+ *   显式环境变量 > `<relayDir>/.dsh-upstream`（插件半用 ctx.webServer.port 落盘）> DSH_WEB_URL
+ *   > **动态发现**（本机 dsh 进程实际监听端口 + Desktop 端口区间，且每个候选都做身份校验）。
+ *
+ * 用 `let` 是因为：① 发现发生在启动之后（异步）；② 上游端口变了要能在**不重启 bridge** 的前提下跟上。
+ */
+const RELAY_DIR = path.dirname(CONFIG_PATH);
+let UPSTREAM = (() => {
+  const hint = resolveUpstreamHint({ relayDir: RELAY_DIR });
+  return hint.url || FALLBACK_UPSTREAM;
+})();
 // 微信机器人通道总开关:DSH_WECHAT=0 关闭(默认开启)。控制面只 bind 回环,且必须带 bridge_secret。
 const WECHAT_DISABLED = String(process.env.DSH_WECHAT || "") === "0";
 // 默认云端服务地址（dsh-remote setup 会显式传入；自建模式无需账号 API）
@@ -385,6 +402,37 @@ const STRIP_RES_HEADERS = new Set([
   "connection", "keep-alive", "upgrade"
 ]);
 
+
+/** 上游重新发现的冷却:失败请求可能连成片,不能每个都去 lsof/pgrep + 探端口。 */
+const UPSTREAM_REFRESH_COOLDOWN_MS = 15_000;
+let upstreamRefreshedAt = 0;
+let upstreamRefreshInflight = null;
+/**
+ * 重新解析上游地址(带身份校验;显式 DSH_BRIDGE_UPSTREAM 时是恒等操作)。
+ * 上游端口变了(Desktop 换端口 / dsh web 重启到别的端口)时,靠它自愈而不必重启 bridge。
+ */
+async function refreshUpstream(reason = "") {
+  if (upstreamRefreshInflight) return upstreamRefreshInflight;
+  const now = Date.now();
+  if (now - upstreamRefreshedAt < UPSTREAM_REFRESH_COOLDOWN_MS) return UPSTREAM;
+  upstreamRefreshedAt = now;
+  upstreamRefreshInflight = (async () => {
+    try {
+      const found = await discoverUpstream({ relayDir: RELAY_DIR });
+      if (found.url && found.url !== UPSTREAM) {
+        console.log(`[bridge] 上游地址切换: ${UPSTREAM} → ${found.url}（来源 ${found.source}${reason ? `,${reason}` : ""}）`);
+        UPSTREAM = found.url;
+      }
+      return UPSTREAM;
+    } catch {
+      return UPSTREAM;
+    } finally {
+      upstreamRefreshInflight = null;
+    }
+  })();
+  return upstreamRefreshInflight;
+}
+
 console.log(`[bridge] 设备 ${DEVICE_ID} → 隧道 ${TUNNEL_URL}/_bridge`);
 console.log(`[bridge] 上游 ${UPSTREAM}`);
 
@@ -816,6 +864,9 @@ export async function handleHttpFrame(dchOrSend, frame) {
     send(reply);
     console.log(`[bridge] ${method} ${path} → ${reply.status} (${Date.now() - t0}ms, ${(reply.body.length * 3 / 4 / 1024).toFixed(0)}KB)`);
   } catch (e) {
+    // 上游不可达是「端口可能变了」的最强信号（Desktop 换端口 / dsh web 重启到别的端口）：
+    // 触发一次带冷却的重新发现，后续请求自动跟上，不必重启 bridge。
+    void refreshUpstream("上游请求失败");
     console.log(`[bridge] ${method} ${path} 上游错误: ${e.message}`);
     send({ id, type: "http", status: 502, headers: { "content-type": "application/json" }, body: Buffer.from(JSON.stringify({ error: String(e.message || e) })).toString("base64"), bodyBase64: true });
   }
@@ -877,6 +928,7 @@ export async function handleLegacyFrame(dchOrSend, frame) {
     send({ id, status: reply.status, headers: reply.headers, body: text });
     console.log(`[bridge] legacy ${method} ${path} → ${reply.status} (${Date.now() - t0}ms)`);
   } catch (e) {
+    void refreshUpstream("上游请求失败(legacy)");
     console.log(`[bridge] legacy ${method} ${path} 上游错误: ${e.message}`);
     send({ id, status: 502, headers: {}, body: JSON.stringify({ error: String(e.message || e) }) });
   }
@@ -1469,6 +1521,9 @@ function startWeChat() {
     const cfg = loadLocalConfig();
     wechatRuntime = createWeChatRuntime({
       relayDir,
+      // 上游地址在 runTunnel() 开头已完成动态发现（见 refreshUpstream），所以这里拿到的是真实端口。
+      // ⚠️ 这是**取值**而非引用：运行中若上游端口又变了（自愈重发现），微信通道要等 bridge 重启才跟上；
+      //    隧道转发那一侧不受影响（它每次都读最新的 UPSTREAM）。
       upstream: UPSTREAM,
       cookieOf: harnessCookieOf,
       secret: process.env.DSH_BRIDGE_SECRET || (typeof cfg.bridge_secret === "string" ? cfg.bridge_secret : ""),
@@ -1514,6 +1569,10 @@ function redactText(e) {
 }
 
 async function runTunnel() {
+  // 先动态确定上游再连隧道：上游端口不是 3080 时（DSH Desktop 默认 43120）这一步是关键 ——
+  // 否则 bridge 会连上中继、手机也能打开页面，但每个请求都打到一个没人听的端口。
+  await refreshUpstream("启动");
+  console.log(`[bridge] 上游地址已确定: ${UPSTREAM}`);
   const token = await resolveToken();
   if (!token) {
     console.error("[bridge] 隧道模式需要账号认证:请设 DSH_BRIDGE_TOKEN,或 DSH_BRIDGE_PHONE+DSH_BRIDGE_PASSWORD");

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

@@ -95,7 +95,34 @@ const RUNTIME_HOST_RE =
   /(data-sidebar-collapsed|data-details-collapsed|data-rightbar-collapsed|data-shell-overlay)|(pI_x6G_frame|hHd-Xa_root|hHd-Xa_toggle)/;
 
 const STYLE = `
-/* ===== dsh-remote mobile adapter (bridge 注入;仅 ≤820px 生效,桌面宽屏无任何规则) ===== */
+/* ===== 首屏加载提示（0.6.14）=====
+   为什么要有它：镜像页首屏要拉 dsh web 的全部客户端插件（实测 ~14 MB，一个不可拆分的
+   /plugins/?? 聚合请求），免费档限速下几十秒起步。此前页面上**只有官方那个转圈**，
+   用户无法区分"在加载"和"卡死了"，只能反复刷新 —— 反而更慢。
+   这里给一句人话提示 + 分阶段的补充说明，加载完成（或超时兜底）即自动移除。
+   ⚠️ 刻意**不**放进 @media (max-width:820px)：Windows/桌面浏览器打开镜像页同样要等。
+   ⚠️ pointer-events:none + 半透明：万一移除逻辑失效，也绝不挡住任何点击。 */
+.dsh-ma-boot {
+  position: fixed; inset: 0; z-index: 2147483000;
+  display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 14px;
+  background: color-mix(in srgb, var(--dsw-alias-bg-base, #0f1115) 88%, transparent);
+  backdrop-filter: blur(2px);
+  pointer-events: none;
+  font-family: inherit; text-align: center; padding: 24px;
+  transition: opacity .3s ease;
+}
+.dsh-ma-boot[data-fading="1"] { opacity: 0; }
+.dsh-ma-boot-spin {
+  width: 34px; height: 34px; border-radius: 50%;
+  border: 3px solid color-mix(in srgb, currentColor 22%, transparent);
+  border-top-color: currentColor;
+  animation: dsh-ma-boot-spin 1s linear infinite;
+}
+@keyframes dsh-ma-boot-spin { to { transform: rotate(360deg); } }
+.dsh-ma-boot-title { font-size: 15px; font-weight: 600; }
+.dsh-ma-boot-sub { font-size: 13px; line-height: 1.6; opacity: .75; max-width: 22em; }
+.dsh-ma-boot-elapsed { font-size: 12px; opacity: .55; font-variant-numeric: tabular-nums; }
+
 @media (max-width: 820px) {
   html, body { max-width: 100%; overflow-x: hidden; }
   html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
@@ -426,6 +453,89 @@ html[data-dsh-ma-merged-e2ee] #dsh-e2ee-badge { display: none !important; }
 const SCRIPT = `(() => {
   "use strict";
 
+  /* ===== 首屏加载提示（0.6.14）=====
+     用户反馈：「普通用户加载进入镜像页面时等待时间较长，目前等待过程中一直在转圈」
+     —— 官方那个转圈不告诉用户任何事。这里在**页面解析的第一时间**就挂上一条人话提示，
+     并在官方 UI 就绪（或兜底超时）后自动移除。
+
+     ⚠️ 必须放在所有主机判定（HOSTISH / NARROW）之前：首屏慢的正是这些判定等不到的时候。
+     ⚠️ 只做提示，不做任何拦截：pointer-events:none，也没有遮罩语义。 */
+  var maBootTip = null, maBootTimers = [], maBootStart = Date.now(), maBootElapsedTimer = 0, maBootWatchTimer = 0;
+  function maBootSet(cls, text) {
+    try { var n = maBootTip && maBootTip.querySelector(cls); if (n) n.textContent = text; } catch (e) { /* 忽略 */ }
+  }
+  function maBootShow() {
+    try {
+      if (maBootTip) return;
+      if (!document.body) return; // 解析太早（body 还没出来）→ 交给 DOMContentLoaded 再挂
+      maBootTip = document.createElement("div");
+      maBootTip.className = "dsh-ma-boot";
+      maBootTip.setAttribute("role", "status");
+      maBootTip.setAttribute("aria-live", "polite");
+      maBootTip.innerHTML =
+        '<div class="dsh-ma-boot-spin" aria-hidden="true"></div>' +
+        '<div class="dsh-ma-boot-title">正在加载远程桌面…</div>' +
+        '<div class="dsh-ma-boot-sub">首次打开需要下载较完整的前端资源，请稍候</div>' +
+        '<div class="dsh-ma-boot-elapsed">已等待 0 秒</div>';
+      document.body.appendChild(maBootTip);
+      // 秒表：让"到底等了多久"可见（用户据此判断是慢还是死了）
+      maBootElapsedTimer = setInterval(function () {
+        try {
+          var s = Math.floor((Date.now() - maBootStart) / 1000);
+          var n = maBootTip && maBootTip.querySelector(".dsh-ma-boot-elapsed");
+          if (n) n.textContent = "已等待 " + s + " 秒";
+        } catch (e) { /* 忽略 */ }
+      }, 1000);
+      maBootTimers.push(setTimeout(function () {
+        maBootSet(".dsh-ma-boot-sub", "网络较慢时可能需要一两分钟；加载完成后会自动进入，不用重复刷新");
+      }, 8000));
+      maBootTimers.push(setTimeout(function () {
+        maBootSet(".dsh-ma-boot-sub", "还在加载…如果长时间停在这里，可以下拉刷新重试（重复刷新不会更快）");
+      }, 30 * 1000));
+    } catch (e) { /* 提示失败绝不影响主功能 */ }
+  }
+  function maBootHide() {
+    try {
+      for (var i = 0; i < maBootTimers.length; i++) clearTimeout(maBootTimers[i]);
+      maBootTimers = [];
+      if (maBootElapsedTimer) { clearInterval(maBootElapsedTimer); maBootElapsedTimer = 0; }
+      if (maBootWatchTimer) { try { clearInterval(maBootWatchTimer); } catch (e) { /* 忽略 */ } maBootWatchTimer = 0; }
+      var tip = maBootTip;
+      maBootTip = null;
+      if (tip && tip.parentNode) {
+        try { tip.setAttribute("data-fading", "1"); } catch (e) { /* 忽略 */ }
+        setTimeout(function () { try { if (tip.parentNode) tip.parentNode.removeChild(tip); } catch (e) { /* 忽略 */ } }, 300);
+      }
+    } catch (e) { /* 忽略 */ }
+  }
+  /** 官方 UI 是否已经可用了（= 提示可以撤了）。 */
+  function maBootLooksReady() {
+    try {
+      // ① 适配层认出来的官方 frame（与下方 boot() 同一组选择器）
+      if (document.querySelector(".pI_x6G_frame, [data-sidebar-collapsed], [data-details-collapsed], [data-rightbar-collapsed]")) return true;
+      // ② 出现输入框/会话区也算"进来了"（官方改版首选信号失灵时的兜底）
+      return Boolean(document.querySelector('textarea, [contenteditable="true"], [role="textbox"]'));
+    } catch (e) { return false; }
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", maBootShow);
+  } else {
+    maBootShow();
+  }
+  // 轮询撤下：1s 一次，成本可忽略（只是两次 querySelector）；一旦撤下就自我停止。
+  // 上限与"4 分钟兜底"对齐，避免页面异常时留下常驻定时器。
+  maBootWatchTimer = setInterval(function () {
+    if (maBootLooksReady()) { maBootHide(); return; }
+    if (!maBootTip) { try { clearInterval(maBootWatchTimer); } catch (e) { /* 忽略 */ } maBootWatchTimer = 0; }
+  }, 1000);
+  maBootTimers.push(setTimeout(function () { maBootHide(); }, 240 * 1000));
+  // 页面卸载/进 bfcache 时收干净（测试与真机都靠这条不留悬挂定时器）
+  try {
+    var maBootBye = function () { maBootHide(); };
+    window.addEventListener("pagehide", maBootBye);
+    window.addEventListener("unload", maBootBye);
+  } catch (e) { /* 忽略 */ }
+
   /* —— 主机门解除(2026-09):镜像页(如 n.risegao.cn)经设备流认证回连同一台 127.0.0.1:3080,
      桥已把 Host 回环化并剥 Origin(不扩大信任面)。官方客户端以 transport.ownsHost 判定
      「自有主机」,非回环域名下不置 true 会把设置页置为 memory(不可用)镜像 →

package/clients/dsh-remote/test/boot-tip.test.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * 镜像页首屏加载提示的契约与行为测试（0.6.14）。
+ *
+ * 用户反馈：「普通用户加载进入镜像页面时等待时间较长，目前等待过程中一直在转圈。
+ *          建议给普通用户增加一个友好的提示（例如提示"正在排队中"）。」
+ *
+ * 首屏为什么慢：镜像页要拉 dsh web 的全部客户端插件（实测 ~14 MB 的一个**不可拆分**聚合请求），
+ * 免费档限速下几十秒起步。官方那个转圈不告诉用户任何事，用户只能反复刷新 —— 反而更慢。
+ *
+ * 这里守四件事：
+ *   ① 提示必须在**页面解析的第一时间**出现（早于所有主机判定 —— 首屏慢的正是判定等不到的时候）；
+ *   ② 分阶段补充说明（8s / 30s）与秒表，让"到底等了多久"可见；
+ *   ③ 官方 UI 就绪后自动撤下；且有 4 分钟兜底 + pagehide/unload 清理，绝不留悬挂定时器；
+ *   ④ 只做提示、不做拦截（pointer-events:none），提示失效也绝不挡住用户操作。
+ *
+ * 用法: node --test test/boot-tip.test.mjs
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import vm from "node:vm";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = readFileSync(path.join(HERE, "..", "mobile-adapter.mjs"), "utf8");
+const STYLE = SRC.slice(SRC.indexOf("const STYLE = `") + "const STYLE = `".length, SRC.indexOf("`;\n\n/**", SRC.indexOf("const STYLE = `")));
+const SCRIPT_START = SRC.indexOf("const SCRIPT = `(() => {") + "const SCRIPT = `".length;
+const SCRIPT = SRC.slice(SCRIPT_START, SRC.indexOf("`;\n\n/**", SCRIPT_START));
+/**
+ * 只取「首屏提示」这一段来跑行为。
+ * 为什么不像别的用例那样跑整个适配层：整段要一整套 DOM 桩（抽屉/遮罩/设置面板…），
+ * 而这里要验的是**提示的生命周期**，隔离出来既稳又准（改动范围也正好是这一段）。
+ */
+const BOOT = SCRIPT.slice(SCRIPT.indexOf("var maBootTip"), SCRIPT.indexOf("/* —— 主机门解除"));
+
+/** 极简 DOM 桩：只支撑"提示出现/撤下"这条路径。 */
+function makeDom({ body = true, ready = false, frame = false } = {}) {
+  const nodes = [];
+  const el = (tag) => {
+    const n = {
+      tagName: String(tag).toUpperCase(), className: "", _text: "", children: [], attrs: {}, parentNode: null,
+      set innerHTML(v) { this._html = v; }, get innerHTML() { return this._html || ""; },
+      set textContent(v) { this._text = String(v); }, get textContent() { return this._text; },
+      setAttribute(k, v) { this.attrs[k] = String(v); },
+      appendChild(c) { c.parentNode = this; this.children.push(c); return c; },
+      removeChild(c) { this.children = this.children.filter((x) => x !== c); c.parentNode = null; return c; },
+      querySelector(sel) {
+        const cls = String(sel).replace(/^\./, "");
+        const hit = (x) => (x.className || "").split(/\s+/).includes(cls);
+        const walk = (x) => { for (const c of x.children) { if (hit(c)) return c; const d = walk(c); if (d) return d; } return null; };
+        return walk(this);
+      }
+    };
+    return n;
+  };
+  const doc = {
+    readyState: ready ? "complete" : "loading",
+    listeners: {},
+    createElement: el,
+    querySelector(sel) {
+      if (sel === ".dsh-ma-boot") return nodes.find((n) => (n.className || "").includes("dsh-ma-boot")) || null;
+      if (frame && /frame|textarea|contenteditable|textbox|sidebar-collapsed/.test(sel)) return el("div");
+      return null;
+    },
+    addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
+    dispatch(type) { (this.listeners[type] || []).forEach((fn) => fn({})); }
+  };
+  if (body) { doc.body = el("body"); doc.body.className = ""; }
+  else { doc.body = null; doc.bodyHolder = el("body"); }
+  return { doc, nodes, el, attachBody() { doc.body = doc.bodyHolder; } };
+}
+
+function run(env) {
+  const timers = [];
+  const intervals = [];
+  const win = {
+    listeners: {},
+    addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
+    dispatch(type) { (this.listeners[type] || []).forEach((fn) => fn({})); },
+    innerWidth: 390, innerHeight: 844,
+    location: { href: "https://example.test/remote/dev-x/", origin: "https://example.test" },
+    MutationObserver: class { observe() {} disconnect() {} },
+    requestAnimationFrame: (fn) => { timers.push({ fn, ms: 0 }); return timers.length; },
+    cancelAnimationFrame() {}, matchMedia: () => ({ matches: false, addEventListener() {}, removeEventListener() {} })
+  };
+  const ctx = {
+    window: win,
+    document: env.doc,
+    location: win.location,
+    navigator: { userAgent: "node-test", language: "zh-CN" },
+    console: { warn() {}, log() {}, error() {} },
+    setTimeout: (fn, ms) => { timers.push({ fn, ms }); return timers.length; },
+    clearTimeout: () => {},
+    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return intervals.length; },
+    clearInterval: () => {},
+    Date, Math, JSON, Object, Array, String, Number, Boolean, Error, RegExp, Promise, Map, Set
+  };
+  vm.createContext(ctx);
+  vm.runInContext(BOOT, ctx, { timeout: 5000 });
+  return { win, timers, intervals };
+}
+
+test("样式：提示层不挡点击（pointer-events:none）、覆盖所有宽度、有转圈与秒表样式", () => {
+  assert.match(STYLE, /\.dsh-ma-boot\s*\{[\s\S]*?pointer-events:\s*none/, "提示层绝不能拦截点击");
+  assert.ok(!/@media \(max-width: 820px\) \{\s*\.dsh-ma-boot/.test(STYLE), "提示不受窄屏限定（Windows/桌面浏览器同样要等）");
+  assert.match(STYLE, /\.dsh-ma-boot-spin/, "要有加载动画");
+  assert.match(STYLE, /\.dsh-ma-boot-elapsed/, "要有秒表");
+});
+
+test("★ 行为：页面还在解析（readyState=loading）也要立刻挂出提示", () => {
+  const env = makeDom({ ready: false, frame: false });
+  const { win, timers } = run(env);
+  // 提示挂载挂在 DOMContentLoaded 上（此时 body 可能还没出来）
+  assert.ok((env.doc.listeners.DOMContentLoaded || []).length > 0, "必须监听 DOMContentLoaded 再挂提示");
+  env.doc.dispatch("DOMContentLoaded");
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "解析阶段就要出现提示（这正是首屏最慢的时候）");
+  assert.match(tip.innerHTML, /正在加载远程桌面/);
+  assert.match(tip.innerHTML, /首次打开需要下载/, "要说明为什么慢");
+  assert.ok(timers.some((t) => t.ms === 8000) && timers.some((t) => t.ms === 30000), "要有 8s/30s 两段补充说明");
+  assert.ok(timers.some((t) => t.ms === 240000), "要有 4 分钟兜底撤下");
+  assert.ok((win.listeners.pagehide || []).length > 0, "pagehide 要清理（不留悬挂定时器）");
+});
+
+test("★ 行为：官方 UI 就绪后自动撤下提示", () => {
+  const env = makeDom({ ready: true, frame: true }); // ready=complete → 立即挂；frame=true → 已就绪
+  const { intervals } = run(env);
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "先挂上");
+  assert.ok(intervals.length >= 2, "要有秒表 + 就绪轮询两个定时器");
+  // 两个 interval 都是 1000ms（秒表 / 就绪轮询），顺序不保证 —— 全部推一次，模拟"1 秒过去"
+  intervals.forEach((t) => t.fn());
+  assert.equal(tip.attrs["data-fading"], "1", "官方 UI 就绪后应进入淡出");
+});
+
+test("行为：脚本在 <head> 里先跑（readyState=loading，body 还没出来）也绝不能抛，body 就位后补挂", () => {
+  // 真实时序就是这条：适配层被内联在 <head>，执行时 body 可能还不存在
+  const env = makeDom({ body: false, ready: false });
+  assert.doesNotThrow(() => run(env), "body 缺失时绝不能抛（适配层其他逻辑还要跑）");
+  env.attachBody();
+  env.doc.dispatch("DOMContentLoaded");
+  const tip = env.doc.body.children.find((c) => (c.className || "").includes("dsh-ma-boot"));
+  assert.ok(tip, "body 就位后补挂提示");
+  assert.match(tip.innerHTML, /正在加载远程桌面/);
+});
+
+test("源码契约：提示必须早于主机判定（HOSTISH/NARROW），否则首屏最慢那段没有提示", () => {
+  // ⚠️ 基准要用 **HOSTISH 的定义**（const HOSTISH =），不能用 indexOf("HOSTISH")：
+  //    提示那段自己的注释里就提到了 HOSTISH，拿注释当基准会把顺序判反（第一版就这么红的）。
+  const iTip = SCRIPT.indexOf("var maBootTip");
+  const iHost = SCRIPT.indexOf("const HOSTISH");
+  assert.ok(iTip > 0 && iHost > 0, "找不到提示段或主机判定");
+  assert.ok(iTip < iHost, "提示段必须在主机判定之前");
+  assert.ok(BOOT.includes("pointer-events: none") || STYLE.includes("pointer-events: none"), "必须写明不拦截点击");
+  assert.ok(!/dsh-ma-boot[\s\S]{0,400}?pointer-events:\s*auto/.test(STYLE), "提示层不得改成可点击拦截");
+});

package/clients/dsh-remote/test/upstream-discovery.test.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * 上游（dsh web）地址发现契约测试。
+ *
+ * 背景（两起真实事故，见 upstream-discovery.mjs 顶部注释）：
+ *   ① `dsh web --port 8090` / `--port 0`（系统分配端口）→ 写死 3080 的探测永远失败；
+ *   ② **DSH Desktop**（Electron 壳 `dsh-plugin-desktop`）默认 43120、占用则 +1，插件 0.6.10
+ *      实测「面板永久停在 starting、设备从未登记」——watcher 探 3080 探不到就永不派生 bridge。
+ *
+ * 这里守四件事：
+ *   ① 提示优先级（env > 端口文件 > DSH_WEB_URL）与规范化；
+ *   ② **身份校验**：候选端口可能被别的程序占用，绝不能把 bridge 接到陌生人身上；
+ *   ③ 提示不可用时会去探候选（含 Desktop 端口区间），并报出**准确的来源**；
+ *   ④ 什么都找不到时保持历史行为（回退 3080），不能变成"抛错/空地址"。
+ *
+ * 用法: node --test test/upstream-discovery.test.mjs
+ */
+import assert from "node:assert/strict";
+import http from "node:http";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  candidatePorts,
+  discoverUpstream,
+  listeningPortsOfPid,
+  looksLikeDshWeb,
+  normalizeUpstream,
+  probeDshWeb,
+  resolveUpstreamHint,
+  DESKTOP_DEFAULT_PORT,
+  FALLBACK_UPSTREAM,
+  UPSTREAM_FILE
+} from "../upstream-discovery.mjs";
+
+const DIR = mkdtempSync(path.join(os.tmpdir(), "dsh-upstream-"));
+process.on("exit", () => { try { rmSync(DIR, { recursive: true, force: true }); } catch { /* ignore */ } });
+
+/** 假的 dsh web：回一段带官方特征标记的 HTML（身份校验靠它）。 */
+const DSH_HTML = "<!doctype html><html><head><title>DeepSeek Harness</title></head><body><script>__ModuleLoader__</script></body></html>";
+/** 冒牌服务：端口在听，但不是 dsh web。 */
+const STRANGER = "hello, I am some other local server";
+
+async function listen(handler) {
+  const srv = http.createServer(handler);
+  await new Promise((r) => srv.listen(0, "127.0.0.1", r));
+  return { srv, port: srv.address().port, url: `http://127.0.0.1:${srv.address().port}` };
+}
+const close = (x) => new Promise((r) => x.srv.close(r));
+
+const writeHint = (url) => writeFileSync(path.join(DIR, UPSTREAM_FILE), url + "\n");
+/**
+ * 把 3080 封掉的 fetch 包装。
+ * 为什么需要:开发机上真实存在一个 dsh web 监听 3080,候选扫描会命中它 ——
+ * 那是**宿主**而不是测试夹具,断言就变成了"看运气"。封掉它,测试才只依赖自己起的假服务。
+ */
+const realFetch = globalThis.fetch;
+const blockedFetch = (input, init) => {
+  const url = String(typeof input === "string" ? input : (input && input.url) || "");
+  if (/:3080(\/|$)/.test(url)) return Promise.reject(new Error("blocked: host 3080"));
+  return realFetch(input, init);
+};
+
+
+test("规范化:去尾斜杠;非 http(s) / 空值一律丢弃", () => {
+  assert.equal(normalizeUpstream("http://127.0.0.1:43120/"), "http://127.0.0.1:43120");
+  assert.equal(normalizeUpstream("  http://127.0.0.1:3080  "), "http://127.0.0.1:3080");
+  assert.equal(normalizeUpstream("wss://n.risegao.cn:13443"), "");
+  assert.equal(normalizeUpstream(""), "");
+  assert.equal(normalizeUpstream(undefined), "");
+});
+
+test("提示优先级:env > 端口文件 > DSH_WEB_URL", () => {
+  writeHint("http://127.0.0.1:43120");
+  assert.deepEqual(
+    resolveUpstreamHint({ relayDir: DIR, env: { DSH_BRIDGE_UPSTREAM: "http://127.0.0.1:9001" } }),
+    { url: "http://127.0.0.1:9001", source: "env" }
+  );
+  assert.deepEqual(resolveUpstreamHint({ relayDir: DIR, env: {} }), { url: "http://127.0.0.1:43120", source: "file" });
+  // 文件坏掉 → 落到 DSH_WEB_URL
+  writeHint("not-a-url");
+  assert.deepEqual(
+    resolveUpstreamHint({ relayDir: DIR, env: { DSH_WEB_URL: "https://example.com:8090/?token=x" } }),
+    { url: "http://127.0.0.1:8090", source: "dsh_web_url" }
+  );
+  writeHint("http://127.0.0.1:43120");
+});
+
+test("身份校验:只认 dsh web 特征,拒绝陌生服务与空响应", () => {
+  assert.equal(looksLikeDshWeb(200, DSH_HTML), true);
+  assert.equal(looksLikeDshWeb(401, "dsh web authentication required; reopen the URL printed by dsh web."), true);
+  assert.equal(looksLikeDshWeb(200, STRANGER), false);
+  assert.equal(looksLikeDshWeb(200, ""), false);
+  assert.equal(looksLikeDshWeb(500, DSH_HTML), false, "5xx 不算");
+});
+
+test("行为:probeDshWeb 认得出真 dsh web,也拒绝陌生服务与死端口", async () => {
+  const dsh = await listen((_req, res) => { res.writeHead(200, { "content-type": "text/html" }); res.end(DSH_HTML); });
+  const stranger = await listen((_req, res) => { res.writeHead(200, { "content-type": "text/plain" }); res.end(STRANGER); });
+  try {
+    assert.equal(await probeDshWeb(dsh.url), true);
+    assert.equal(await probeDshWeb(stranger.url), false, "端口在听但不是 dsh web → 必须拒绝");
+    assert.equal(await probeDshWeb("http://127.0.0.1:1"), false, "死端口 → false");
+    assert.equal(await probeDshWeb("wss://x"), false, "非 http(s) → false");
+  } finally {
+    await close(dsh); await close(stranger);
+  }
+});
+
+test("★ DSH Desktop 场景:端口文件过期/缺失时,靠候选探测找到 43120 上的 dsh web", async () => {
+  // 模拟 Desktop：dsh web 在 43120，而端口文件写的是上一轮的旧端口（已无人监听）
+  const desktop = await listen((_req, res) => { res.writeHead(200, { "content-type": "text/html" }); res.end(DSH_HTML); });
+  // 探测真的走 43120 —— 测试里换成"把 Desktop 端口作为 extraPorts 注入"，避免占用真实端口
+  writeHint("http://127.0.0.1:1"); // 过期提示
+  try {
+    const found = await discoverUpstream({
+      relayDir: DIR,
+      env: {},
+      extraPorts: [desktop.port],
+      fetchImpl: blockedFetch,
+      platform: "win32" // 隔离宿主：不走 ps/pgrep/netstat，候选只来自提示/额外端口/静态表
+    });
+    assert.equal(found.url, desktop.url, "必须落到候选命中的那个 dsh web");
+    assert.equal(found.source, "extra");
+    assert.ok(found.rejected.includes("http://127.0.0.1:1"), "过期提示应被记入 rejected");
+  } finally {
+    await close(desktop);
+  }
+});
+
+test("★ 候选探测不做身份校验的话会接错人:陌生服务在候选端口上也必须被拒绝", async () => {
+  const stranger = await listen((_req, res) => { res.writeHead(200, { "content-type": "text/plain" }); res.end(STRANGER); });
+  writeHint("http://127.0.0.1:1");
+  try {
+    const found = await discoverUpstream({ relayDir: DIR, env: {}, extraPorts: [stranger.port], fetchImpl: blockedFetch, platform: "win32" });
+    assert.notEqual(found.url, stranger.url, "陌生服务绝不能成为上游");
+    assert.equal(found.url, "http://127.0.0.1:1", "找不到时回落到提示地址(让上层按'上游没起来'重试)");
+  } finally {
+    await close(stranger);
+  }
+});
+
+test("提示可用时不做候选扫描(省掉无谓探测)", async () => {
+  const dsh = await listen((_req, res) => { res.writeHead(200, { "content-type": "text/html" }); res.end(DSH_HTML); });
+  writeHint(dsh.url);
+  try {
+    const found = await discoverUpstream({ relayDir: DIR, env: {}, fetchImpl: blockedFetch, platform: "win32" });
+    assert.equal(found.url, dsh.url);
+    assert.equal(found.source, "file");
+    assert.deepEqual(found.probed, [dsh.port], "只探了提示本身");
+  } finally {
+    await close(dsh);
+  }
+});
+
+test("显式 DSH_BRIDGE_UPSTREAM 直接采信(探测都不做) —— 保持既有语义", async () => {
+  const found = await discoverUpstream({
+    relayDir: DIR,
+    env: { DSH_BRIDGE_UPSTREAM: "http://127.0.0.1:63999" },
+    platform: "win32",
+    fetchImpl: () => { throw new Error("不该发请求"); }
+  });
+  assert.equal(found.url, "http://127.0.0.1:63999");
+  assert.equal(found.source, "env");
+  assert.deepEqual(found.probed, []);
+});
+
+test("什么都找不到 → 回退历史默认 3080(不抛错、不放空)", async () => {
+  writeHint("not-a-url");
+  const found = await discoverUpstream({ relayDir: DIR, env: {}, fetchImpl: blockedFetch, platform: "win32", timeoutMs: 120 });
+  assert.equal(found.url, FALLBACK_UPSTREAM);
+  assert.equal(found.source, "fallback");
+});
+
+test("候选构成:含 3080 与 DSH Desktop 默认端口区间,且去重、带来源", () => {
+  writeHint("http://127.0.0.1:43120");
+  const list = candidatePorts({ relayDir: DIR, env: {}, platform: "win32" });
+  const ports = list.map((e) => e.port);
+  assert.ok(ports.includes(3080), "必须包含历史默认端口");
+  for (let i = 0; i < 12; i++) assert.ok(ports.includes(DESKTOP_DEFAULT_PORT + i), `必须覆盖 Desktop 端口区间 +${i}`);
+  assert.equal(new Set(ports).size, ports.length, "不得重复");
+  assert.equal(list.find((e) => e.port === 43120).source, "file", "首个候选应来自端口文件");
+});
+
+test("实测端口:能从本进程真实监听端口里读出来(macOS/Linux 用 lsof)", async (t) => {
+  if (process.platform === "win32") return t.skip("Windows 走 netstat，另有实现");
+  const srv = await listen((_req, res) => res.end("x"));
+  try {
+    const ports = listeningPortsOfPid(process.pid);
+    assert.ok(ports.includes(srv.port), `应包含 ${srv.port}，实际 ${JSON.stringify(ports)}`);
+  } finally {
+    await close(srv);
+  }
+});