@mrrisega/dsh-remote 0.6.13 → 0.6.15

package/packages/dsh-remote-web/runtime/dsh-setup.mjs

@@ -29,6 +29,7 @@ import path from "node:path";
 import { spawn, spawnSync, execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { childStopped, stopChildGracefully } from "./clients/dsh-remote/src/lifecycle.mjs";
+import { discoverUpstream, resolveUpstreamHint, FALLBACK_UPSTREAM } from "./clients/dsh-remote/upstream-discovery.mjs";
 
 const THIS_DIR = path.dirname(fileURLToPath(import.meta.url)); // 本包目录（仓库或 node_modules）
 const IS_NPM_INSTALL = THIS_DIR.includes(`${path.sep}node_modules${path.sep}`);
@@ -169,6 +170,7 @@ function printHelp() {
   dsh-remote status       查看配置与服务状态
   dsh-remote plugin       手动安装 dsh web 远程访问插件（--uninstall 卸载）
   dsh-remote repair       修复插件挂载（dsh web 起不来时用；只碰 profile，不联网）
+  dsh-remote doctor       一条命令自检「为什么连不上」（只读；含上游/进程/微信/日志尾部）
   dsh-remote --help       显示本用法（等同 dsh-remote help）
 
 自建模式（可选）:
@@ -201,7 +203,11 @@ const KNOWN_FLAGS = new Set([
     process.exit(1);
   }
 }
-try { ensureRuntimeCopy(); } catch (e) { console.warn(`⚠️ 运行时固化跳过: ${e.message}`); }
+// `doctor` 承诺"只读"：它连运行时脚本同步都不做 —— 否则"自检"会先往用户磁盘写 9 个文件，
+// 与承诺不符（也会把"我什么都没改却多了文件"变成新的困惑）。
+if (process.argv[2] !== "doctor") {
+  try { ensureRuntimeCopy(); } catch (e) { console.warn(`⚠️ 运行时固化跳过: ${e.message}`); }
+}
 
 /** 自启动服务应指向的 dsh-setup.mjs：优先配置目录内的固化副本，否则当前执行文件。 */
 function runtimeSetupPath() {
@@ -763,12 +769,32 @@ function restartBridgeService() {
     return startBridgeDarwin(plistPath);
   }
   if (process.platform === "linux") {
-    const r = sh(`systemctl --user restart dsh-bridge`);
-    if (!r.ok) return { ok: false, status: "failed", detail: (r.stderr || r.stdout).trim() || "systemctl restart 失败" };
-    const a = sh(`systemctl --user is-active dsh-bridge`);
-    return a.ok && a.stdout.trim() === "active"
-      ? { ok: true, status: "running", pid: null }
-      : { ok: false, status: "failed", detail: (a.stdout || a.stderr).trim() };
+    // 【0.6.15】飞牛 fnOS / 群晖这类 NAS 上**没有 user systemd 会话**（插件跑在系统服务里，
+    // 没有 XDG_RUNTIME_DIR）→ `systemctl --user` 只会报 "Failed to connect to bus"，
+    // 于是这一支原本必然失败、且没有任何兜底。现在：有会话就用 systemd（可自愈），
+    // 没有就退到脱离进程（spawnDetachedBridge，与 macOS 的兜底同一条路径）。
+    const hasUserSystemd = Boolean(process.env.XDG_RUNTIME_DIR) && sh("systemctl --user show-environment").ok;
+    if (hasUserSystemd) {
+      const r = sh(`systemctl --user restart dsh-bridge`);
+      if (r.ok) {
+        const a = sh(`systemctl --user is-active dsh-bridge`);
+        if (a.ok && a.stdout.trim() === "active") return { ok: true, status: "running", pid: null };
+        return { ok: false, status: "failed", detail: (a.stdout || a.stderr).trim() };
+      }
+      // 有会话却重启失败：继续往下走脱离进程兜底，绝不留一个"重启失败但没有任何进程"的空档
+    }
+    const d = spawnDetachedBridge();
+    if (d.ok) {
+      return {
+        ok: true,
+        status: "degraded-detached",
+        pid: d.pid,
+        detail: hasUserSystemd
+          ? "systemd --user 重启失败，已改为后台进程运行（现在可用；systemd 恢复后下一次重启会回到托管）"
+          : "本机没有 user systemd 会话（NAS/容器常见），已改为后台进程运行（现在可用，但不会开机自启）",
+      };
+    }
+    return { ok: false, status: "failed", detail: d.error || "systemd 与后台进程均启动失败" };
   }
   return { ok: false, status: "unsupported", detail: `平台 ${process.platform} 不支持自启动` };
 }
@@ -779,14 +805,21 @@ function restartBridgeService() {
  * 【2026-09-23 用户实测事故】这里原本处处写死 `http://127.0.0.1:3080`：只要用户的 dsh web
  * 不在默认端口（`dsh web --port 8090`、profile 里配了 port、或 `--port 0` 让系统分配空闲端口），
  * watcher 的在线探测就**永远**失败 → bridge 永远不启动，而面板只会说「正在启动 Bridge…」。
- * 优先级：显式环境变量 > 插件半留下的端口文件 > DSH_WEB_URL > 默认 3080。
- * 为什么要有「端口文件」这一层：开机自启（登录任务 / launchd）拉起 watcher 时**没有**任何环境变量，
- * 只有插件半知道 dsh web 真实监听在哪个端口，所以它会把地址落盘（见插件 half 的 publishUpstream）。
+ * 优先级：显式环境变量 > **运行时动态发现** > 插件半留下的端口文件 > DSH_WEB_URL > 默认 3080。
+ *
+ * 为什么还要「动态发现」这一层（2026-09-23 第二起实测，DSH Desktop）：
+ *   DSH Desktop（Electron 壳 `dsh-plugin-desktop`）默认把 Web 服务放在 **43120**，被占用还会 +1；
+ *   而端口文件要等**插件半**加载后才有。于是「端口文件还没写」或「写的是上一轮的旧端口」时，
+ *   光靠文件仍会永久探错端口。发现逻辑（含 DSH 进程实际监听端口 + Desktop 端口区间 + 身份校验）
+ *   统一在 clients/dsh-remote/upstream-discovery.mjs，watcher 与 bridge 共用同一份实现。
  */
 const UPSTREAM_FILE = ".dsh-upstream";
+/** 运行时动态发现到的上游（优于可能过期的端口文件；进程内缓存）。 */
+let discoveredUpstream = "";
 function upstreamUrl() {
   const explicit = String(process.env.DSH_BRIDGE_UPSTREAM || "").trim();
   if (explicit) return explicit.replace(/\/+$/, "");
+  if (discoveredUpstream) return discoveredUpstream;
   try {
     const fromFile = String(fs.readFileSync(path.join(CONFIG_DIR, UPSTREAM_FILE), "utf8")).trim();
     if (/^https?:\/\/[^\s]+$/i.test(fromFile)) return fromFile.replace(/\/+$/, "");
@@ -798,28 +831,69 @@ function upstreamUrl() {
       if (u.port) return `http://127.0.0.1:${u.port}`; // bridge 的 loopback 围栏只认 127.0.0.1
     } catch { /* 非 URL：忽略 */ }
   }
-  return "http://127.0.0.1:3080";
+  return FALLBACK_UPSTREAM;
 }
 /** 上游端口（诊断/日志用；取不到就回退 3080）。 */
 function upstreamPort() {
   try { return Number(new URL(upstreamUrl()).port) || 3080; } catch { return 3080; }
 }
 
+/** 发现结果缓存与冷却：避免每轮轮询都去 lsof/pgrep + 逐个端口探测。 */
+let upstreamDiscoveryAt = 0;
+let upstreamDiscoveryInflight = null;
+const UPSTREAM_DISCOVERY_COOLDOWN_MS = 15_000;
+
 /**
- * dsh web 是否正在运行（默认 127.0.0.1:3080，端口以 upstreamUrl() 为准）。
- * bridge 本身依赖 dsh web 才工作：dsh web 没开时 bridge 起来也会立刻退出，
- * 所以「装完当下 bridge 没在跑」是**正常状态**，不能当失败吓用户（见 install 汇总）。
+ * 动态发现上游（带身份校验），成功后写入 `discoveredUpstream` 供全局复用。
+ * @param {boolean} force 忽略冷却（探测失败后的重试用）
  */
-async function isDshWebUp(timeoutMs = 1200) {
+async function refreshUpstreamDiscovery(force = false) {
+  if (upstreamDiscoveryInflight) return upstreamDiscoveryInflight;
+  const now = Date.now();
+  if (!force && now - upstreamDiscoveryAt < UPSTREAM_DISCOVERY_COOLDOWN_MS) return upstreamUrl();
+  upstreamDiscoveryAt = now;
+  upstreamDiscoveryInflight = (async () => {
+    try {
+      const found = await discoverUpstream({ relayDir: CONFIG_DIR, log: (m) => console.log(`[dsh-remote] ${m}`) });
+      // 「提示地址验证通过」与「候选命中」都值得记下来；fallback（什么都没找到）不污染现有判断
+      if (found.url && found.source !== "fallback") discoveredUpstream = found.url;
+      return upstreamUrl();
+    } catch {
+      return upstreamUrl();
+    } finally {
+      upstreamDiscoveryInflight = null;
+    }
+  })();
+  return upstreamDiscoveryInflight;
+}
+
+/** 上游是否**有响应**（判据刻意宽松：4xx/5xx 也算"端口在听"，那种情况问题在别处）。 */
+async function upstreamReachable(url = upstreamUrl(), timeoutMs = 1200) {
   try {
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), timeoutMs);
-    await fetch(upstreamUrl() + "/", { signal: ac.signal });
+    await fetch(url + "/", { signal: ac.signal });
     clearTimeout(timer);
     return true;
   } catch { return false; }
 }
 
+/**
+ * dsh web 是否正在运行（端口以 upstreamUrl() 为准，**绝不写死 3080**）。
+ * bridge 本身依赖 dsh web 才工作：dsh web 没开时 bridge 起来也会立刻退出，
+ * 所以「装完当下 bridge 没在跑」是**正常状态**，不能当失败吓用户（见 install 汇总）。
+ *
+ * 探测失败时会**主动做一次动态发现**再试一次 —— 这一条正是 DSH Desktop 场景的关键：
+ * 上游在 43120（Desktop 默认，占用还会 +1），而端口文件可能还没写或写着上一轮的旧端口。
+ */
+async function isDshWebUp(timeoutMs = 1200) {
+  if (await upstreamReachable(upstreamUrl(), timeoutMs)) return true;
+  const before = upstreamUrl();
+  const after = await refreshUpstreamDiscovery(true);
+  if (after === before) return false;
+  return upstreamReachable(after, timeoutMs);
+}
+
 /**
  * 解析 dsh web profile 目录（安装与插件管理共用同一口径）。
  */
@@ -1125,14 +1199,13 @@ async function runBridge() {
   /** 限流提示只打一次，避免刷屏。 */
   let warnedRateLimit = false;
 
-  // watcher：检测 dsh web 是否存活（端口以 upstreamUrl() 为准，绝不写死 3080），存活才启动 bridge
-  const checkUpstream = () => new Promise((resolve) => {
-    const t = setTimeout(() => resolve(false), 2000);
-    fetch(upstreamUrl() + "/")
-      .then(() => { clearTimeout(t); resolve(true); })
-      .catch(() => { clearTimeout(t); resolve(false); });
-  });
+  // watcher：检测 dsh web 是否存活（端口动态解析，绝不写死 3080），存活才启动 bridge。
+  // 走 isDshWebUp()：探测失败会自动做一次动态发现（DSH Desktop 的 43120 / 自定义端口都靠它）。
+  const checkUpstream = () => isDshWebUp(2000);
 
+  // 先做一次动态发现再打印/派生：否则日志会长期写着错误的端口（用户实测就卡在
+  // 「等待 dsh web（127.0.0.1:3080）启动...」而真实上游在 43120）。
+  await refreshUpstreamDiscovery(true);
   console.log(`[dsh-remote] 等待 dsh web（${upstreamUrl()}）启动...`);
   let bridgeProc = null;
   let starting = false;
@@ -2284,6 +2357,134 @@ async function pluginCmd(argv) {
  *   resolve = dsh 的裸包名解析能不能走通（浏览器半注入面板就靠它）
  *   client = dsh.client.platform 声明在不在
  */
+/**
+ * `dsh-remote doctor` —— **一条命令回答「为什么连不上」**（只读，不改任何东西）。
+ *
+ * 【为什么产品上必须有它】2026-09-25 排查两条用户反馈（fb_7b4ee6ec9862 / fb_4cc2c9df749c）时，
+ * 判断"bridge 到底有没有被拉起来"花了大量时间，而且**只能靠翻日志行数估时间** ——
+ * 因为当时的日志连时间戳都没有，用户端也没有任何一个入口能把
+ * 「上游端口 / 守护状态 / 事件订阅 / 待补发队列」一次性说清楚。
+ * 那两个用户都是 linux + 「starting / bridge 未运行」，而我们的自愈当时在 Linux 上**根本没有实现**
+ * （见 0.6.15 的 startBridgeLinux）：如果有一份这样的自检，用户自己 10 秒就能看出问题在哪。
+ *
+ * 输出四段：① 身份与版本 ② 上游（含来源与探测结论） ③ 进程与自启动 ④ 通道（微信/加密/待补发）
+ * ⑤ 日志尾部（带时间戳）。任何一项失败都只影响那一行，绝不中断整份自检。
+ *
+ * @param {string[]} argv 额外参数（--profile <dir> 透传给插件挂载诊断）
+ */
+async function doctorCmd(argv = []) {
+  const mask = (s) => (s ? String(s).slice(0, 3) + "****" + String(s).slice(-2) : "");
+  const ms = (t) => (t ? new Date(Number(t)).toISOString().replace("T", " ").slice(0, 19) : "-");
+  const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; } };
+  const readText = (p) => { try { return fs.readFileSync(p, "utf8"); } catch { return ""; } };
+  const alive = (pid) => {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === "EPERM"; }
+  };
+
+  console.log("dsh-remote 自检（doctor，只读，不改任何东西）");
+  console.log("时间:", new Date().toISOString(), "| 平台:", `${process.platform}/${process.arch}`, "| node:", process.version);
+  console.log("配置目录:", CONFIG_DIR);
+
+  // ── ① 插件与运行环境版本 ────────────────────────────────────────────────
+  const pluginPkg = readJson(path.join(CONFIG_DIR, "node_modules", PLUGIN_ID, "package.json"))
+    || readJson(new URL("./packages/dsh-remote-web/package.json", import.meta.url));
+  const setupVersion = readText(path.join(CONFIG_DIR, ".dsh-setup-version")).trim();
+  console.log("\n① 版本");
+  console.log(`   插件        : ${pluginPkg && pluginPkg.version ? "v" + pluginPkg.version : "（读不到）"}`);
+  console.log(`   运行环境     : ${setupVersion ? "v" + setupVersion : "（未固化 / 未知）"}`);
+  console.log(`   运行环境入口 : ${fs.existsSync(runtimeSetupPath()) ? runtimeSetupPath() : "缺失！"}`);
+  try {
+    const profileDir = resolveProfileDir(argv);
+    if (fs.existsSync(path.join(profileDir, "package.json"))) printPluginDiagnostics(profileDir);
+    else console.log(`   [plugin]  未找到 profile（${profileDir}）`);
+  } catch (e) { console.log(`   [plugin]  诊断失败：${e.message}`); }
+
+  // ── ② 上游 dsh web（bridge 要连的那个本机地址） ──────────────────────────
+  console.log("\n② 上游 dsh web");
+  const hint = resolveUpstreamHint({ relayDir: CONFIG_DIR });
+  const probed = await discoverUpstream({ relayDir: CONFIG_DIR, log: (m) => console.log(`   ${m}`) });
+  console.log(`   提示来源     : ${hint.url ? `${hint.url}（${hint.source}）` : "（无）"}`);
+  console.log(`   最终采用     : ${probed.url}（${probed.source}）`);
+  console.log(`   身份校验     : ${probed.source === "fallback" ? "⚠️ 未找到在听的 dsh web（会一直重试）" : "✅ 已确认为本机 dsh web"}`);
+  if (probed.probed && probed.probed.length) console.log(`   探测过的端口 : ${probed.probed.join(", ")}`);
+
+  // ── ③ 守护与 bridge 进程 ───────────────────────────────────────────────
+  console.log("\n③ 进程与自启动");
+  const watcherPid = readPidFile(WATCHER_PID_FILE);
+  const bridgePid = readPidFile(BRIDGE_PID_FILE);
+  console.log(`   watcher pid  : ${watcherPid || "-"}${watcherPid ? (alive(watcherPid) ? "（在跑）" : "（已死，pid 文件过期）") : ""}`);
+  console.log(`   bridge pid   : ${bridgePid || "-"}${bridgePid ? (alive(bridgePid) ? "（在跑）" : "（已死，pid 文件过期）") : ""}`);
+  // 进程扫描（平台各自的方式）：只报数量，不猜
+  try {
+    const r = process.platform === "win32"
+      ? sh("tasklist /FI \"IMAGENAME eq node.exe\" /FO CSV 2>NUL")
+      : sh("pgrep -fl 'dsh-setup.mjs|dsh-bridge.mjs' 2>/dev/null");
+    const lines = String(r.stdout || "").split("\n").map((l) => l.trim()).filter((l) => l && !/pgrep/.test(l));
+    const watchers = lines.filter((l) => /dsh-setup\.mjs/.test(l));
+    const bridges = lines.filter((l) => /dsh-bridge\.mjs/.test(l)).filter((l) => !/dsh-setup/.test(l));
+    console.log(`   实测进程     : watcher ${watchers.length} 个 / bridge ${bridges.length} 个`);
+    if (watchers.length && !bridges.length) console.log("   ⚠️ 守护在跑、bridge 没起来 —— 这类情况看日志尾部（通常是在等 dsh web 或登录限流）");
+    if (!watchers.length && !bridges.length) {
+      console.log("   ⚠️ 一个进程都没在跑。手动起一次看报错：`dsh-remote run`（前台，能直接看到输出）");
+    }
+  } catch (e) { console.log(`   实测进程     : 扫描失败（${e.message}）`); }
+  if (process.platform === "linux") {
+    const hasUser = Boolean(process.env.XDG_RUNTIME_DIR);
+    console.log(`   自启动       : systemd --user ${hasUser ? "（有 runtime dir）" : "（无 XDG_RUNTIME_DIR → 本机没有 user systemd，插件会用后台进程兜底）"}`);
+    if (hasUser) {
+      const r = sh("systemctl --user is-active dsh-bridge");
+      console.log(`   systemd 状态 : ${r.ok ? r.stdout.trim() : (r.stderr || "").trim() || "查不到"}`);
+    }
+  }
+
+  // ── ④ 通道：E2EE / 微信 / 待补发 ───────────────────────────────────────
+  console.log("\n④ 通道");
+  const e2ee = readJson(path.join(CONFIG_DIR, ".e2ee-state.json"));
+  console.log(`   端到端加密   : ${e2ee ? (e2ee.enabled ? `已启用（${e2ee.reason || "ok"}）` : `未启用（${e2ee.reason || "?"}）`) : "（无状态文件 = 明文）"}`);
+  const wx = readJson(path.join(CONFIG_DIR, ".wechat-state.json"));
+  if (!wx) {
+    console.log("   微信通道     : 未使用（无状态文件）");
+  } else {
+    const outbox = Array.isArray(wx.pending_outbox) ? wx.pending_outbox.length : 0;
+    const faults = wx.last_fault && wx.last_fault.code ? `${wx.last_fault.code}（${ms(wx.last_fault.at)}）` : "无";
+    console.log(`   微信通道     : ${wx.bound ? "已绑定" : "未绑定"} | 最近成功推送 ${ms(wx.last_push_ok_at)}`);
+    console.log(`   待补发通知   : ${outbox ? `⚠️ ${outbox} 条（下次在微信里发一句话就会补上）` : "0 条"}`);
+    console.log(`   最近订阅异常 : ${faults}`);
+    console.log(`   当前会话     : ${wx.current_session_title || "-"}（${wx.current_session_id || "-"}）`);
+    console.log(`   最近完成     : ${wx.last_completed_session_title || "-"}（${ms(wx.last_completed_at)}）`);
+    if (outbox) console.log(`   ℹ️ 入站消息的形状（字段名，用于定位 context_token 缺失）：${wx.inbound_shape || "（还没记到）"}`);
+  }
+  const cfg = loadConfig();
+  console.log(`   账号         : ${mask(cfg.phone) || (cfg.local_key ? "自建（本地密钥）" : "（未登录）")}`);
+  console.log(`   中继/API     : ${cfg.tunnel_url || "-"} ${cfg.api_url ? `| ${cfg.api_url}` : ""}`);
+
+  // ── ⑤ 日志尾部（现在每行都有时间戳，直接能对时间） ─────────────────────
+  console.log("\n⑤ 日志尾部（bridge + 安装）");
+  for (const name of [".dsh-bridge.log", ".dsh-setup-install.log"]) {
+    const p = path.join(CONFIG_DIR, name);
+    if (!fs.existsSync(p)) { console.log(`   ${name}: （无）`); continue; }
+    let tail = "";
+    try {
+      const st = fs.statSync(p);
+      const len = Math.min(st.size, 8 * 1024);
+      const fd = fs.openSync(p, "r");
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, Math.max(0, st.size - len));
+      fs.closeSync(fd);
+      tail = buf.toString("utf8");
+    } catch { /* 读不了就当没有 */ }
+    const lines = tail.split("\n").map((l) => l.trim()).filter(Boolean).slice(-12);
+    console.log(`   --- ${name}（末尾 ${lines.length} 行 / ${p}）---`);
+    for (const l of lines) console.log("   " + l.slice(0, 220));
+    console.log("");
+  }
+  console.log("结论怎么读：① 版本对不上 → 面板点「一键修复 / 重装运行环境」；");
+  console.log("           ② 上游 fallback → 把 dsh web 起在本机可回环访问的端口（插件会自动发现）；");
+  console.log("           ③ 没有任何进程 → 先手动 `dsh-remote run` 看前台输出；");
+  console.log("           ④ 待补发 > 0 → 在微信里随便发一句话即可补收。");
+}
+
 function printPluginDiagnostics(profileDir) {
   const nmPlugin = path.join(profileDir, "node_modules", PLUGIN_ID);
   const link = describePluginLink(profileDir);
@@ -2369,6 +2570,7 @@ else if (cmd === "settings") settingsHint();
 else if (cmd === "run") await runBridge();
 else if (cmd === "plugin") await pluginCmd(process.argv.slice(3));
 else if (cmd === "repair") repairProfile(process.argv.slice(3));
+else if (cmd === "doctor") await doctorCmd(process.argv.slice(3));
 else if (cmd === "status") {
   const cfg = loadConfig();
   const local = Boolean(cfg.local_key);

package/packages/dsh-remote-web/test/connect-stuck-visibility.test.mjs

@@ -370,8 +370,23 @@ test("运行时 dsh-setup.mjs：上游端口只有一处真相源，watcher/子
   const code = SETUP_SRC.split("\n").filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l)).join("\n");
   assert.ok(!/fetch\("http:\/\/127\.0\.0\.1:3080/.test(code), "探测不得写死 3080（dsh web 可能在别的端口）");
   assert.ok(!/findstr ":3080"|iTCP:3080/.test(code), "按端口找 dsh web 进程也不得写死 3080");
-  assert.ok(/fetch\(upstreamUrl\(\) \+ "\/"\)/.test(code), "watcher 的在线判据必须用 upstreamUrl()");
+  assert.ok(/async function upstreamReachable\(url = upstreamUrl\(\)/.test(code), "在线判据必须用解析出来的上游地址");
+  assert.ok(/await upstreamReachable\(upstreamUrl\(\)/.test(code), "isDshWebUp 必须基于 upstreamUrl() 探测");
   assert.ok(/DSH_BRIDGE_UPSTREAM: upstreamUrl\(\)/.test(code), "必须把上游显式透传给 bridge 子进程");
+  // ── 上游端口动态发现（2026-09-23 第二起实测：DSH Desktop 默认 43120，占用还会 +1）──
+  // 只靠"端口文件"不够：文件可能还没写、或写着上一轮的旧端口；那时必须自己去找。
+  assert.ok(
+    /from "\.\/clients\/dsh-remote\/upstream-discovery\.mjs"/.test(SETUP_SRC),
+    "必须复用共享的上游发现实现（watcher/bridge 同一份，避免两边漂移）"
+  );
+  assert.ok(
+    /const after = await refreshUpstreamDiscovery\(true\)/.test(code),
+    "探测失败必须主动做一次动态发现再试（否则端口一变就永远卡在 starting）"
+  );
+  assert.ok(
+    /await refreshUpstreamDiscovery\(true\);/.test(code),
+    "启动时先发现再打印：日志不得再谎称固定端口"
+  );
   // 半装运行时的根因之一：本安装器自己 import 的 src/lifecycle.mjs 必须在同步表里
   assert.ok(/"src\/lifecycle\.mjs"/.test(SETUP_SRC), "RUNTIME_CLIENT_FILES 必须包含 src/lifecycle.mjs（否则会漏同步出半装运行时）");
 });

package/packages/dsh-remote-web/test/doctor-cli.test.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * `dsh-remote doctor` —— 一条命令自检「为什么连不上」的契约测试。
+ *
+ * 【为什么要这个功能】2026-09-25 两条用户反馈（fb_7b4ee6ec9862 / fb_4cc2c9df749c）都是
+ * linux + 「连接阶段: starting / bridge 未运行」，而排查时**没有任何一个入口**能一次性看清
+ * 「上游端口怎么来的 / 守护在不在 / 事件订阅有没有断 / 有没有通知发不出去」——
+ * 只能靠翻日志（而当时日志连时间戳都没有，连"这条错误发生在用户回话之前还是之后"都判断不了）。
+ *
+ * 本用例锁三件事：
+ *   ① 关键结论必须出现在输出里（上游来源与探测结论、进程、待补发、订阅异常、日志尾部）；
+ *   ② 日志尾部必须**带时间戳**（否则等于没有）；
+ *   ③ `doctor` 必须**真的只读**（连运行时脚本同步都不做，目录不留任何新文件）。
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SETUP = path.join(HERE, "..", "..", "..", "dsh-setup.mjs");
+
+/** 造一个"有故事"的配置目录：微信有待补发 + 有订阅异常 + 日志带时间戳。 */
+function makeRelayDir() {
+  const root = mkdtempSync(path.join(os.tmpdir(), "dsh-doctor-"));
+  const relayDir = path.join(root, ".dsh-remote");
+  const home = path.join(root, "home");
+  mkdirSync(relayDir, { recursive: true });
+  mkdirSync(home, { recursive: true });
+  writeFileSync(path.join(relayDir, ".dsh-config.json"), JSON.stringify({
+    api_url: "http://127.0.0.1:1", phone: "13800000000", password: "x", device_id: "dev-test",
+  }));
+  writeFileSync(path.join(relayDir, ".e2ee-state.json"), JSON.stringify({ enabled: true, reason: "ok" }));
+  writeFileSync(path.join(relayDir, ".wechat-state.json"), JSON.stringify({
+    bound: true,
+    last_push_ok_at: 1790331177460,
+    pending_outbox: [{ text: "跑完了", kind: "stopped", at: 1790331000000 }],
+    last_fault: { code: "follow-limit", message: "follow 流已达上限 8", at: 1790331100000 },
+    current_session_id: "session-abc", current_session_title: "当前任务",
+    last_completed_session_id: "session-done", last_completed_session_title: "刚跑完的活",
+    last_completed_at: 1790331165248,
+    inbound_shape: "msg_id,from_user_id,item_list",
+  }));
+  writeFileSync(path.join(relayDir, ".dsh-bridge.log"),
+    "[2026-09-25T09:29:58.147Z] [bridge] 隧道已连\n[2026-09-25T09:30:01.000Z] [wechat] sendmessage 失败:ret=-2\n");
+  writeFileSync(path.join(relayDir, ".dsh-setup-version"), "0.6.15\n");
+  return { root, relayDir, home, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+
+function runDoctor(env) {
+  const r = spawnSync(process.execPath, [SETUP, "doctor"], {
+    encoding: "utf8",
+    timeout: 60000,
+    env: {
+      ...process.env,
+      HOME: env.home,
+      DSH_RELAY_DIR: env.relayDir,
+      DSH_REMOTE_TELEMETRY: "0",
+      DSH_RELAY_DEFAULT_API: "http://127.0.0.1:1",
+      // 隔离：不碰真实 launchd / systemd
+      DSH_RELAY_SKIP_SERVICE: "1",
+    },
+  });
+  return String(r.stdout || "") + String(r.stderr || "");
+}
+
+test("★ doctor：上游来源/进程/待补发/订阅异常/日志尾部 必须一条命令全看到", () => {
+  const env = makeRelayDir();
+  try {
+    const out = runDoctor(env);
+    // ① 身份
+    assert.match(out, /dsh-remote 自检/, "要有明确的标题（用户才知道这是自检报告）");
+    assert.match(out, /① 版本/, "版本段缺失");
+    // ② 上游：来源与探测结论都要有（"3080 是默认值还是实测"是历史上最容易搞错的一点）
+    assert.match(out, /② 上游 dsh web/, "上游段缺失");
+    assert.match(out, /最终采用\s*: http:\/\/127\.0\.0\.1:/, "必须给出最终采用的上游地址");
+    assert.match(out, /身份校验\s*:/, "必须给出身份校验结论（否则用户不知道那个端口是不是 dsh web）");
+    // ③ 进程
+    assert.match(out, /③ 进程与自启动/, "进程段缺失");
+    assert.match(out, /watcher pid\s*:/, "要看得到守护 pid");
+    assert.match(out, /实测进程\s*:/, "要看得到实测进程数（pid 文件会过期）");
+    // ④ 通道：待补发与订阅异常是"没收到推送"的两个可判定信号
+    assert.match(out, /④ 通道/, "通道段缺失");
+    assert.match(out, /待补发通知\s*: ⚠️ 1 条/, "待补发条数必须显示（通知发不出去时唯一的可见信号）");
+    assert.match(out, /最近订阅异常\s*: follow-limit/, "订阅异常必须显示（旧实现这类故障完全静默）");
+    assert.match(out, /端到端加密\s*: 已启用/, "加密状态要显示");
+    assert.match(out, /最近完成\s*: 刚跑完的活/, "最近完成的任务要显示（回话目标就认它）");
+    assert.match(out, /msg_id,from_user_id,item_list/, "入站字段形状要显示（用于定位 context_token 缺失）");
+    // 手机号必须脱敏
+    assert.ok(!out.includes("13800000000"), "诊断报告会外发，手机号必须脱敏");
+    // ⑤ 日志尾部要带时间戳（没有时间戳 = 无法对时间，正是那次排查最贵的一课）
+    assert.match(out, /⑤ 日志尾部/, "日志段缺失");
+    assert.match(out, /\[2026-09-25T09:29:58\.147Z\]/, "日志行必须带时间戳");
+    assert.match(out, /sendmessage 失败/, "日志尾部要真的把内容带出来");
+  } finally { env.cleanup(); }
+});
+
+test("★ doctor 必须**真的只读**：不新建任何文件（否则「自检」本身就是一次写盘）", () => {
+  const env = makeRelayDir();
+  try {
+    const before = readdirSync(env.relayDir).sort();
+    runDoctor(env);
+    const after = readdirSync(env.relayDir).sort();
+    assert.deepEqual(after, before, "doctor 不得新增或删除配置目录里的任何文件");
+    assert.ok(!readdirSync(env.home).includes(".dsh-remote"), "也不得在 HOME 下凭空建目录");
+  } finally { env.cleanup(); }
+});
+
+test("用法里必须有 doctor（否则用户不知道有这个入口）", () => {
+  const r = spawnSync(process.execPath, [SETUP, "--help"], { encoding: "utf8", timeout: 30000 });
+  const out = String(r.stdout || "") + String(r.stderr || "");
+  assert.match(out, /dsh-remote doctor/, "用法里要列出 doctor");
+  assert.match(out, /为什么连不上/, "要一句话说清它是干什么的");
+});