@mrrisega/dsh-remote 0.6.12 → 0.6.14

package/packages/dsh-remote-web/runtime/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(不可用)镜像 →
@@ -1096,6 +1206,36 @@ const SCRIPT = `(() => {
       } catch (e8) { /* 引导条失败绝不能影响主功能 */ }
     };
 
+    /* 适配层自己创建的「抽屉入口」引用(汉堡按钮 / 遮罩),提到 boot() 外层保存。
+       为什么必须提到外层:官方 SPA 重渲染时会整片替换 body 子树,把这两个节点一起冲掉;
+       留住引用才能在下面的「存在性看门狗」里把**同一个节点**补回去(节点不变 → 挂在它上面的
+       click 处理、CSS 类、aria 属性全都原样保留,不会出现"补回来点不动"的假按钮)。 */
+    let maHamburger = null, maScrim = null;
+
+    /* 节点是否已经脱离文档。判不出来时一律当作"还在"—— 宁可不补,也绝不重复插入。 */
+    const maDetached = (el) => {
+      if (!el) return false;
+      try { if (typeof el.isConnected === "boolean") return !el.isConnected; } catch (eConn) { /* 继续退化 */ }
+      try {
+        const b = document.body;
+        if (b && typeof b.contains === "function") return !b.contains(el);
+      } catch (eHas) { /* 继续退化 */ }
+      return false;
+    };
+
+    /* —— 存在性看门狗:「建好了」不等于「一直都在」----------------------------------
+       done=true 只保证**曾经**建出来过。官方在路由/会话切换时会重建 DOM 子树,我们的汉堡按钮
+       与遮罩会跟着消失 —— 用户看到的就是"抽屉按钮用着用着又没了"。
+       这里按**引用**补回(不是重建),只在窄屏做(宽屏本来就不需要抽屉入口)。
+       幂等:节点还在文档里 → 什么都不做;boot 还没成功(引用为 null) → 同样什么都不做。 */
+    const ensureDrawerChrome = () => {
+      try {
+        if (!NARROW() || !document.body) return;
+        if (maDetached(maScrim)) document.body.appendChild(maScrim);
+        if (maDetached(maHamburger)) document.body.appendChild(maHamburger);
+      } catch (eChrome) { /* 补不回去也不能影响抽屉开合本身 */ }
+    };
+
     let done = false;
     const boot = () => {
       if (!HOSTISH()) return;
@@ -1228,6 +1368,7 @@ const SCRIPT = `(() => {
       const scrim = document.createElement("div");
       scrim.className = "dsh-ma-scrim";
       document.body.appendChild(scrim);
+      maScrim = scrim;                          // 供「存在性看门狗」在被官方冲掉后补回
       scrim.addEventListener("click", (e) => {
         e.stopPropagation();
         userWantsOpen = false;                    // 用户明确要关(遮罩的作用就是关抽屉)
@@ -1245,6 +1386,7 @@ const SCRIPT = `(() => {
       hamburger.setAttribute("aria-label", "打开菜单");
       hamburger.innerHTML = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h10"/></svg>';
       document.body.appendChild(hamburger);
+      maHamburger = hamburger;                  // 供「存在性看门狗」在被官方冲掉后补回
       hamburger.addEventListener("click", (e) => {
         e.stopPropagation(); e.preventDefault();
         const nowOpen = document.documentElement.classList.contains("dsh-ma-sidebar-open");
@@ -1516,10 +1658,82 @@ const SCRIPT = `(() => {
     };
 
     if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", boot); else boot();
-    /* 官方模块系统异步挂载 UI,晚一点再补几次(幂等,done 守卫);同时等鲸鱼/设置弹层就位 */
-    [700, 1600, 3200, 7000, 12000].forEach((ms) =>
-      setTimeout(() => { try { boot(); whaleHookInit(); watchSettings(); } catch (e) { /* 幂等重试 */ } }, ms)
-    );
+
+    /* ================= 执行时机:无限期等待官方 DOM 就绪 =================
+       用户实测原话(2026-09-2x):「在网络比较慢的情况下,左边的抽屉按钮有时候出不来。
+                                   甭管网络有多慢,都要让那个抽屉能加载出来。」
+       ⚠️ 旧实现是**一组写死的固定重试**([700, 1600, 3200, 7000, 12000]ms),而汉堡按钮的创建
+          排在 boot() 里 "if (!frame) return;" 那一行之后 —— 官方 SPA bundle 有 13.4MB(实测未压缩),
+          免费档被中继限速到 128KB/s 时冷启动要 1-2 分钟,官方 frame 在 12 秒内根本没出现:
+          5 次重试全部在那一行返回 → done 永远为 false → 汉堡按钮**永远**不创建
+          → 用户看到"左边抽屉按钮出不来"。任何固定窗口都只是把这个阈值往后挪,治不了根。
+       现在改成「事件驱动 + 低频兜底」的**无限期**等待,只要抽屉入口还没建好就一直试:
+         · MutationObserver(document/subtree):官方 frame 一挂上就立刻跟上(网络快时零延迟);
+         · setInterval(1000ms):兜底 + 存在性看门狗 —— observer 不可用/被绕过时照样收敛,
+           也负责在 done 之后发现官方重渲染冲掉了我们的节点并补回。
+       两条路都只是"再调一次 pump()",pump 内部**全部幂等**(done / fabDone / whaleGuardsOn /
+       settingsWatchOn / drawerAutoCloseOn 等守卫都在),重复调用不会产生任何副作用,
+       也不改变"执行什么"——开合、遮罩不变量、sync()、isDrawer() 判定一行未动。 */
+    let maTorn = false, maInterval = 0, maObserver = null, maRafPending = false;
+    /* 廉价的"boot() 还有事可做吗"闸门(只读两个现成的布尔标志,不做任何 DOM 操作):
+         · fab 还没建出来(fabDone=false) → 要跑;
+         · 抽屉那段还没建好(done=false)且当前是窄屏 → 要跑(旋转/缩放回窄屏也能补建)。
+       两者都不成立 → boot() 里已无事可做,**绝不能**再跑:boot() 第一行 HOSTISH() 会把
+       documentElement.outerHTML 整个序列化一遍(最长 200KB),而官方流式输出时每帧都有 DOM
+       变更 —— 没有这道闸门就会变成每秒几十次全量序列化(旧实现只跑 5 次,不会有这个问题)。 */
+    const bootUseful = () => !fabDone || (!done && NARROW());
+    const pump = () => {
+      if (maTorn) return;
+      if (bootUseful()) { try { boot(); } catch (eBoot) { /* 幂等重试 */ } }
+      try { ensureDrawerChrome(); } catch (eChrome2) { /* 忽略 */ }
+      if (!whaleGuardsOn || !settingsWatchOn) {
+        try { whaleHookInit(); watchSettings(); } catch (eHook) { /* 两者内部都自带一次性守卫 */ }
+      }
+    };
+    /* 节流:一次 DOM 变更往往产生几十条记录,逐条 boot() 就是忙轮询。
+       统一合并成"本帧最多跑一次"(有 rAF 用 rAF,没有就退化成 0ms 宏任务) —— 天然去重。 */
+    const schedulePump = () => {
+      if (maTorn || maRafPending) return;
+      maRafPending = true;
+      const run = () => { maRafPending = false; pump(); };
+      try { if (typeof requestAnimationFrame === "function") { requestAnimationFrame(run); return; } } catch (eRaf) { /* 退化 */ }
+      setTimeout(run, 0);
+    };
+    /* 挂上"叫醒"的两条路。做成可重入(先清旧的再建新的),这样 bfcache 恢复后能重新武装。 */
+    const maArm = () => {
+      maTorn = false;
+      maRafPending = false;            // 冻结时若有一帧没跑到,不清掉就会永远挡住后续调度
+      try { if (maObserver) maObserver.disconnect(); } catch (eA1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eA2) { /* 忽略 */ }
+      maInterval = 0;
+      try {
+        if (typeof MutationObserver === "function" && document.documentElement) {
+          maObserver = new MutationObserver(schedulePump);
+          /* 只观察 childList+subtree:节点被官方换掉/新增才叫醒我们。
+             ⚠️ 刻意**不**观察 attributes —— 我们自己的 sync() 就会不停改 class,那会变成自激循环。 */
+          maObserver.observe(document.documentElement, { childList: true, subtree: true });
+        }
+      } catch (eObs) { maObserver = null; /* 退化:只靠下面的兜底表 */ }
+      try { maInterval = setInterval(pump, 1000); } catch (eInt) { maInterval = 0; }
+    };
+    maArm();
+    /* 清理:页面卸载时断开观察者与兜底表(bfcache/长驻页面都不留悬挂回调)。
+       pagehide 覆盖 bfcache 场景,unload 兜底更老的浏览器。 */
+    const maTeardown = () => {
+      maTorn = true;
+      try { if (maObserver) maObserver.disconnect(); } catch (eD1) { /* 忽略 */ }
+      maObserver = null;
+      try { if (maInterval) clearInterval(maInterval); } catch (eD2) { /* 忽略 */ }
+      maInterval = 0;
+    };
+    try { window.addEventListener("pagehide", maTeardown); } catch (ePh) { /* 忽略 */ }
+    try { window.addEventListener("unload", maTeardown); } catch (eUl) { /* 忽略 */ }
+    /* 手机上"切到别的 App 再切回来"走的常是 bfcache:pagehide(persisted=true) → pageshow(persisted=true)。
+       DOM 原样保留但计时器/观察者已断 —— 这里重新武装,否则回到页面后看门狗就永久失灵了。 */
+    try {
+      window.addEventListener("pageshow", (ev) => { try { if (ev && ev.persisted) maArm(); } catch (ePs) { /* 忽略 */ } });
+    } catch (ePs2) { /* 忽略 */ }
   } catch (e) { if (window.console) console.warn("[dsh-mobile-adapter]", e && e.message); }
 })();`;
 

package/packages/dsh-remote-web/runtime/clients/dsh-remote/upstream-discovery.mjs

@@ -0,0 +1,292 @@
+/**
+ * 上游（dsh web）地址发现 —— **单一实现**，watcher（dsh-setup.mjs）与 bridge（dsh-bridge.mjs）共用。
+ *
+ * ## 为什么需要它
+ *
+ * 桥接链路的两端（watcher 的存活探测、bridge 的转发目标）原本把上游写死
+ * `http://127.0.0.1:3080`（独立 `dsh web` 的默认端口）。但真实世界里端口是会变的：
+ *
+ *   · `dsh web --port 8090` / profile 里配了 port / `--port 0` 让系统分配空闲端口；
+ *   · **DSH Desktop**（Electron 壳 `dsh-plugin-desktop`）默认监听 **43120**，且被占用时按 +1 递增；
+ *   · `dsh web` 重启后端口可能不同。
+ *
+ * 2026-09-23 用户实测（DSH Desktop 2.0.4 + 插件 0.6.10）：上游在 43120，而 watcher 探 3080 →
+ * **永远探不到 → bridge 永远不被派生 → 面板永久停在「正在启动 Bridge…」**，设备从未登记。
+ * 这不是"某个用户环境特殊"，而是**所有改了端口的用户**都会踩的同一类问题，所以要有通用发现。
+ *
+ * ## 发现顺序（先便宜后昂贵，每一步都做**身份校验**）
+ *
+ *   1. `DSH_BRIDGE_UPSTREAM`（显式覆盖，部署/排障用）—— 唯一不做探测就采信的来源；
+ *   2. `<relayDir>/.dsh-upstream`（**插件半**在宿主进程里用 `ctx.webServer.port` 落盘，最权威）；
+ *   3. `DSH_WEB_URL` 的端口；
+ *   4. **实测端口**：本进程的祖先进程 / 本机 dsh 进程正在 LISTEN 的端口（lsof / netstat）；
+ *   5. 静态候选：3080 + DSH Desktop 的 43120 及其递增区间。
+ *
+ * ⚠️ 第 4、5 步必须**校验身份**：43120 之类的端口可能被别的本地程序占用，
+ *    把 bridge 接到一个陌生人身上既不可用、也可能泄露数据。判据见 `looksLikeDshWeb`。
+ *
+ * ⚠️ 探测全部**并行**且有总预算：本地端口连接被拒是瞬时的，只有"端口在听但不回包"才会等到超时，
+ *    串行探 12 个候选最坏要十几秒，会让 watcher 的轮询卡住。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** 插件半落盘的上游地址文件名（与 packages/dsh-remote-web/lib/index.js 的常量同名同义）。 */
+export const UPSTREAM_FILE = ".dsh-upstream";
+/** 独立 `dsh web` 的默认端口（历史行为，最后的兜底）。 */
+export const FALLBACK_UPSTREAM = "http://127.0.0.1:3080";
+/** DSH Desktop（Electron 壳）的默认 Web 端口；被占用时它按 +1 递增，所以要扫一段区间。 */
+export const DESKTOP_DEFAULT_PORT = 43120;
+/** Desktop 端口区间扫多少个（43120..43120+11）。 */
+export const DESKTOP_PORT_SCAN = 12;
+/** 单个候选的探测超时（本地回环，超过它基本就是"在听但不回包"）。 */
+const PROBE_TIMEOUT_MS = 900;
+
+/** 规范化：去尾斜杠；非 http(s) 一律丢弃（返回空串）。 */
+export function normalizeUpstream(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return "";
+  if (!/^https?:\/\/[^\s]+$/i.test(raw)) return "";
+  return raw.replace(/\/+$/, "");
+}
+
+/** 从字符串里取端口（拿不到返回 0）。 */
+function portOf(value) {
+  try {
+    const n = Number(new URL(String(value)).port);
+    return Number.isInteger(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** 1) 显式环境变量。 */
+export function upstreamFromEnv(env = process.env) {
+  return normalizeUpstream(env.DSH_BRIDGE_UPSTREAM);
+}
+
+/** 2) 插件半落盘的端口文件（插件不在场/首次安装时可能没有）。 */
+export function upstreamFromFile(relayDir) {
+  if (!relayDir) return "";
+  try {
+    return normalizeUpstream(fs.readFileSync(path.join(relayDir, UPSTREAM_FILE), "utf8"));
+  } catch {
+    return "";
+  }
+}
+
+/** 3) DSH_WEB_URL 的端口（bridge 的 loopback 围栏只认 127.0.0.1，这里也统一回环地址）。 */
+export function upstreamFromDshWebUrl(env = process.env) {
+  const raw = String(env.DSH_WEB_URL || "").trim();
+  if (!raw) return "";
+  const port = portOf(raw);
+  return port ? `http://127.0.0.1:${port}` : "";
+}
+
+/**
+ * 按优先级取出"提示地址"（不做任何网络探测）。
+ * @returns {{url: string, source: "env"|"file"|"dsh_web_url"|""}}
+ */
+export function resolveUpstreamHint({ relayDir = "", env = process.env } = {}) {
+  const explicit = upstreamFromEnv(env);
+  if (explicit) return { url: explicit, source: "env" };
+  const fromFile = upstreamFromFile(relayDir);
+  if (fromFile) return { url: fromFile, source: "file" };
+  const fromWebUrl = upstreamFromDshWebUrl(env);
+  if (fromWebUrl) return { url: fromWebUrl, source: "dsh_web_url" };
+  return { url: "", source: "" };
+}
+
+// ---------- 实测端口（best effort，任何失败都只是少一个候选，绝不影响主流程） ----------
+
+function tryExec(cmd, args, timeoutMs = 4000) {
+  try {
+    return String(execFileSync(cmd, args, { encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] }) || "");
+  } catch {
+    return "";
+  }
+}
+
+/** 某进程正在 LISTEN 的 TCP 端口。macOS/Linux 用 lsof，Windows 用 netstat -ano。 */
+export function listeningPortsOfPid(pid, platform = process.platform) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return [];
+  const ports = new Set();
+  if (platform === "win32") {
+    for (const line of tryExec("netstat", ["-ano"], 6000).split(/\r?\n/)) {
+      if (!/LISTENING/i.test(line)) continue;
+      const cols = line.trim().split(/\s+/);
+      if (cols.length < 5) continue;
+      if (Number(cols[cols.length - 1]) !== n) continue;
+      const m = /:(\d+)$/.exec(cols[1] || "");
+      if (m) ports.add(Number(m[1]));
+    }
+    return [...ports];
+  }
+  const out = tryExec("lsof", ["-nP", "-a", "-p", String(n), "-iTCP", "-sTCP:LISTEN"], 5000);
+  for (const line of out.split("\n")) {
+    const m = /:(\d+)\s*\(LISTEN\)/.exec(line);
+    if (m) ports.add(Number(m[1]));
+  }
+  return [...ports];
+}
+
+/** 祖先进程 pid（最多 6 层）：被插件/宿主拉起的 watcher、bridge 走这条路能找到宿主。 */
+export function ancestorPids(startPid = process.pid, maxDepth = 6, platform = process.platform) {
+  if (platform === "win32") return []; // Windows 无 ps；靠 netstat+pgrep 不可行，交给端口文件与静态候选
+  const out = [];
+  let pid = Number(startPid);
+  for (let i = 0; i < maxDepth; i++) {
+    const txt = tryExec("ps", ["-o", "ppid=", "-p", String(pid)], 2000).trim();
+    const ppid = Number(txt);
+    if (!Number.isInteger(ppid) || ppid <= 1) break;
+    out.push(ppid);
+    pid = ppid;
+  }
+  return out;
+}
+
+/** 本机 dsh 相关进程（pgrep）—— Desktop 壳/独立 dsh web 都可能命中。 */
+export function dshProcessPids(platform = process.platform) {
+  if (platform === "win32") return [];
+  const out = tryExec("pgrep", ["-f", "dsh"], 4000);
+  return out
+    .split(/\s+/)
+    .map((s) => Number(s))
+    .filter((n) => Number.isInteger(n) && n > 1 && n !== process.pid);
+}
+
+/**
+ * 候选列表（已去重，按"可能性"排序），每项带**来源标注**（用于日志与测试断言）。
+ * 顺序 = 提示里的端口 → 显式额外端口 → DSH_WEB_URL 的端口 → 祖先/dsh 进程实测监听端口
+ *        → 3080 → Desktop 默认端口区间。
+ * @returns {Array<{port:number, source:string}>}
+ */
+export function candidatePorts({ relayDir = "", env = process.env, extraPorts = [], platform = process.platform } = {}) {
+  const out = [];
+  const seen = new Set();
+  const push = (p, source) => {
+    const n = Number(p);
+    if (!Number.isInteger(n) || n <= 0 || n >= 65536 || seen.has(n)) return;
+    seen.add(n);
+    out.push({ port: n, source });
+  };
+  const hint = resolveUpstreamHint({ relayDir, env });
+  push(portOf(hint.url), hint.source || "hint");
+  for (const p of extraPorts) push(p, "extra");
+  push(portOf(upstreamFromDshWebUrl(env)), "dsh_web_url");
+  const pids = [...new Set([process.pid, ...ancestorPids(process.pid, 6, platform), ...dshProcessPids(platform)])];
+  for (const pid of pids) for (const p of listeningPortsOfPid(pid, platform)) push(p, "process");
+  push(3080, "static");
+  for (let i = 0; i < DESKTOP_PORT_SCAN; i++) push(DESKTOP_DEFAULT_PORT + i, "static");
+  return out;
+}
+
+// ---------- 身份校验 ----------
+
+/**
+ * 这个地址**真的**是 dsh web 吗？
+ *
+ * 为什么必须有：候选探测会去敲 43120 这类可能被别的程序占用的端口。只看"端口有响应"就把
+ * bridge 接上去，用户会得到一个"能连上但不工作"的怪状态，而且等于把这台机器的流量交给陌生服务。
+ * 判据取 dsh web 自身的稳定特征（HTML/标题/鉴权文案），任一命中即通过。
+ */
+export const DSH_WEB_MARKERS = [
+  "__ModuleLoader__",
+  "dsh-client-modules",
+  "deepseek harness",
+  "dsh web authentication required",
+  "dsh-remote"
+];
+
+export function looksLikeDshWeb(status, text) {
+  const body = String(text || "").toLowerCase();
+  if (!body) return false;
+  if (status >= 500) return false;
+  return DSH_WEB_MARKERS.some((m) => body.includes(m));
+}
+
+/**
+ * 探测一个候选：GET `/`，带身份校验。
+ * @returns {Promise<boolean>}
+ */
+export async function probeDshWeb(url, { timeoutMs = PROBE_TIMEOUT_MS, fetchImpl } = {}) {
+  const target = normalizeUpstream(url);
+  if (!target) return false;
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== "function") return false;
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    let res;
+    try {
+      // redirect: manual —— 不跟随跳转（跳走的多半不是我们要的宿主）
+      res = await doFetch(`${target}/`, { signal: ac.signal, redirect: "manual" });
+    } finally {
+      clearTimeout(timer);
+    }
+    const status = Number(res && res.status) || 0;
+    if (status >= 500) return false;
+    // 只读前 8KB 足够命中特征；读流失败按"不是"处理（宁可少一个候选，不可误接）
+    let text = "";
+    try {
+      if (res.body && typeof res.body.getReader === "function") {
+        const reader = res.body.getReader();
+        const { value } = await reader.read();
+        text = value ? Buffer.from(value).toString("utf8") : "";
+        try { await reader.cancel(); } catch { /* ignore */ }
+      } else if (typeof res.text === "function") {
+        text = await res.text();
+      }
+    } catch { /* 读失败 → text 为空 → 判否 */ }
+    return looksLikeDshWeb(status, text.slice(0, 8192));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 发现上游地址（带身份校验）。
+ *
+ * @param {number[]} [extraPorts] 调用方已知的额外候选(排在静态候选之前;测试与特化部署用)。
+ * @returns {Promise<{url: string, source: string, probed: number[], rejected: string[]}>}
+ *          source: env | file | dsh_web_url | process | static | extra | fallback
+ */
+export async function discoverUpstream({
+  relayDir = "",
+  env = process.env,
+  timeoutMs = PROBE_TIMEOUT_MS,
+  fetchImpl,
+  platform = process.platform,
+  extraPorts = [],
+  log
+} = {}) {
+  const hint = resolveUpstreamHint({ relayDir, env });
+  // ① 显式环境变量:部署方说是什么就是什么(不探测,保持既有语义)
+  if (hint.source === "env") return { url: hint.url, source: "env", probed: [], rejected: [] };
+  // ② 提示地址先验证:文件/DSh_WEB_URL 都可能过期(宿主换端口/换了程序占用)
+  if (hint.url && (await probeDshWeb(hint.url, { timeoutMs, fetchImpl }))) {
+    return { url: hint.url, source: hint.source, probed: [portOf(hint.url)], rejected: [] };
+  }
+
+  // ③ 候选并行探测(本地端口,拒绝是瞬时的;并行是为了不让 watcher 卡住)
+  const hintPort = portOf(hint.url);
+  const entries = candidatePorts({ relayDir, env, platform, extraPorts }).filter((e) => e.port !== hintPort);
+  const results = await Promise.all(entries.map(async (e) => ({ ...e, ok: await probeDshWeb(`http://127.0.0.1:${e.port}`, { timeoutMs, fetchImpl }) })));
+  const hit = results.find((r) => r.ok);
+  if (hit) {
+    const url = `http://127.0.0.1:${hit.port}`;
+    if (typeof log === "function") log(`[upstream] 动态发现上游 ${url}（来源 ${hit.source}；提示 ${hint.url || "无"} 不可用）`);
+    return { url, source: hit.source, probed: entries.map((e) => e.port), rejected: hint.url ? [hint.url] : [] };
+  }
+
+  // ④ 都没找到:保持历史行为(3080),让上层按"上游没起来"正常重试
+  return {
+    url: hint.url || FALLBACK_UPSTREAM,
+    source: hint.url ? hint.source : "fallback",
+    probed: entries.map((e) => e.port),
+    rejected: hint.url ? [hint.url] : []
+  };
+}