@mrrisega/dsh-remote 0.6.18 → 0.7.0-beta.2

package/packages/dsh-remote-web/runtime/clients/dsh-remote/wechat-runtime.mjs

@@ -340,7 +340,7 @@ export class WeChatRuntime {
   /**
    * @param {{
    *   relayDir: string,
-   *   upstream?: string,              // dsh web 地址,默认 http://127.0.0.1:3080
+   *   upstream?: string|(() => string), // dsh web 地址,默认 http://127.0.0.1:3080;函数=每次重连重新求值
    *   cookieOf?: () => string,        // 读 .harness-cookie.json 的回调(bridge 已有该逻辑)
    *   secret?: string,                // 控制面密钥(bridge_secret);空则控制面拒绝所有请求
    *   logger?: any,
@@ -356,6 +356,16 @@ export class WeChatRuntime {
     if (!opts.relayDir) throw new Error("WeChatRuntime: 缺少 relayDir");
     this.relayDir = opts.relayDir;
     this.upstream = String(opts.upstream || "http://127.0.0.1:3080").replace(/\/+$/, "");
+    /**
+     * 上游地址的**取值器**：恰好是字符串时是常量函数。
+     *
+     * 为什么不让它是个固化字符串：宿主端口会变（`dsh web --port 0`、DSH Desktop 每次启动随机端口），
+     * 而事件订阅器是**长连接** —— 固化字符串的后果是端口一变就永久重连到旧端口。
+     * 【2026-10-09 真机实证】bridge 启动时宿主还是 3080，随后换成 19387；隧道转发侧
+     * （每次都读最新 UPSTREAM）一切正常，唯独微信事件通道死循环刷
+     * `connect ECONNREFUSED 127.0.0.1:3080` —— 手机能开页面，但**任务完成没有任何推送**。
+     */
+    this.upstreamOf = typeof opts.upstream === "function" ? opts.upstream : () => this.upstream;
     this.cookieOf = typeof opts.cookieOf === "function" ? opts.cookieOf : () => "";
     this.secret = String(opts.secret || "");
     this.clock = opts.clock || Date.now;
@@ -1597,7 +1607,8 @@ export class WeChatRuntime {
     // 而且完全静默。现在无论订阅器是新建还是注入,都保证挂上处理器(WeakSet 去重,可重复调用)。
     if (!this.subscriber) {
       this.subscriber = createEventSubscriber({
-        upstream: this.upstream,
+        // 传**取值器**而不是当次的值：见构造函数里 upstreamOf 的说明（端口变了要能跟上）。
+        upstream: () => this.upstreamOf(),
         cookie: () => this.cookieOf(),
         follow: true,
         log: (level, message, meta) => {

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

@@ -173,6 +173,12 @@ function printHelp() {
   dsh-remote doctor       一条命令自检「为什么连不上」（只读；含上游/进程/微信/日志尾部）
   dsh-remote --help       显示本用法（等同 dsh-remote help）
 
+目标 profile（默认 Web 版）:
+  dsh-remote --profile desktop    装进 DeepSeek Harness **桌面端**的插件目录
+                                  （~/.dsh/profiles/desktop；装前请先完全退出桌面应用）
+  桌面端也可以在应用内「插件」页直接安装 dsh-remote-web —— 那是官方路径，无需退出。
+  ⚠️ 桌面端与 Web 版共享 ~/.dsh（会话/设置/凭据），但**插件互相隔离**，两边要各自安装。
+
 自建模式（可选）:
   dsh-remote setup --server wss://你的域名:端口 --key 访问密钥
 
@@ -239,19 +245,109 @@ function resolveExecutable(p) {
   } catch { return null; }
 }
 
+/**
+ * 宿主是否跑在 **Electron 的 Node 模式**下（DeepSeek Harness 桌面端的 Host 就是）。
+ *
+ * 桌面端 `process.execPath` 是 **Electron 应用二进制**而不是 node：不带
+ * `ELECTRON_RUN_AS_NODE=1` 直接拿它跑脚本，得到的不是「跑脚本的 node」，而是
+ * **又启动一个桌面端应用实例**。自启动服务是系统在应用退出后拉起的，踩到这里
+ * 的表现是「服务登记成功、进程秒退、bridge 永远起不来」，与 0.6.15 那次端口事故
+ * 一样难排查 —— 所以必须在**写服务定义时**就把变量带上。
+ */
+const IS_ELECTRON_HOST = Boolean(process.versions && process.versions.electron);
+
+/**
+ * DeepSeek Harness **桌面端自带 Node** 的稳定落点候选。
+ *
+ * 为什么需要：桌面端主打的正是**机器上没有系统 node** 的用户；而自启动服务要活过
+ * 桌面端的退出、甚至升级/重装（`.app` 路径会变、可能被换掉）。桌面端把自带运行时装在
+ * **用户目录** `~/.dsh/dsh-runtimes/…`，它不随应用包更新而移动 —— 所以只要它存在，
+ * 就该优先于任何指向 `.app` 内部的路径。
+ *
+ * 目录布局随桌面端版本演进（可能多套一层 runtime/node），故按多个候选探测；
+ * `resolveExecutable()` 会过滤掉不存在的路径，多列无害。
+ * @returns {string[]} 候选可执行文件绝对路径（可能都不存在）。
+ */
+function desktopRuntimeNodeCandidates() {
+  const isWin = process.platform === "win32";
+  const exe = isWin ? "node.exe" : "node";
+  const out = [];
+  // ① 稳定落点：装在**用户目录**，桌面端升级/重装都不动它。
+  //    ⚠️ 真实布局是 `dependencies/node/bin/<exe>`（2026-10-07 拆官方 0.2.0-rc.2 DMG 实测：
+  //    `…/Resources/runtime/primary-runtime/dependencies/node/bin/node` → Node v24.21.0）。
+  //    其余几个是兼容不同版本的兜底；resolveExecutable() 会过滤掉不存在的路径，多列无害。
+  const roots = [
+    process.env.DSH_DESKTOP_RUNTIME_DIR || "",
+    path.join(os.homedir(), ".dsh", "dsh-runtimes", "dsh-primary-runtime"),
+    path.join(os.homedir(), ".dsh", "dsh-runtimes", "primary-runtime"),
+  ].filter(Boolean);
+  for (const root of roots) {
+    out.push(
+      path.join(root, "dependencies", "node", "bin", exe),
+      path.join(root, "bin", exe),
+      path.join(root, "node", "bin", exe),
+      path.join(root, "runtime", "bin", exe),
+    );
+  }
+  // ② 应用自己把自带 node 的路径交给子进程（其 `runtime/bin/node` shim 就是靠这个变量）——
+  //    平台无关，且是"应用自己说的"，比我们猜路径可靠。
+  if (process.env.DSH_DESKTOP_NODE_EXECUTABLE) out.push(process.env.DSH_DESKTOP_NODE_EXECUTABLE);
+  // ③ 最后才是指向应用包内部的绝对路径：它是**真实存在的 node**，但会随桌面端更新换路径，
+  //    所以排在稳定落点之后（自启动服务登记它属于"聊胜于无"，好过登记 Electron 本体）。
+  if (isWin) {
+    const local = process.env.LOCALAPPDATA || "";
+    if (local) out.push(path.join(local, "Programs", "DeepSeek Harness", "resources", "runtime", "primary-runtime", "dependencies", "node", exe));
+  } else {
+    out.push(
+      "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/primary-runtime/dependencies/node/bin/node",
+      "/Applications/DSH Desktop.app/Contents/Resources/runtime/primary-runtime/dependencies/node/bin/node",
+    );
+  }
+  return out;
+}
+
 function preferredNode() {
+  // 先归一化"自己的可执行文件"，用来判断最终选中的解释器是否就是 Electron 本体。
+  const selfReal = resolveExecutable(process.execPath) || process.execPath;
   const candidates = [
     process.env.DSH_SETUP_NODE20 || "",
     process.env.DSH_SETUP_NODE || "",
+    // 桌面端（Electron 宿主）：**真实 node 优先**。服务要活过桌面应用的退出与更新
+    //（.app 路径会变、可能被换掉），登记一个真实 node 才稳；找不到才回落 Electron 自身，
+    // 那时由 SERVICE_NODE_ENV 补上 ELECTRON_RUN_AS_NODE=1 把它变成 node。
+    ...(IS_ELECTRON_HOST
+      ? [
+          // 桌面端自带 Node 的**稳定**落点：装在用户目录（~/.dsh/dsh-runtimes/…），
+          // 桌面端升级/重装都不动它 —— 比 .app 内部路径更该登记进自启动服务。
+          ...desktopRuntimeNodeCandidates(),
+          "/opt/homebrew/opt/node@20/bin/node", "/usr/local/opt/node@20/bin/node", "/opt/homebrew/bin/node", "/usr/local/bin/node",
+        ]
+      : []),
     process.execPath
   ].filter(Boolean);
   for (const p of candidates) {
     const real = resolveExecutable(p);
-    if (real) return real;
-  }
-  return process.execPath;
+    if (real) return { bin: real, electron: IS_ELECTRON_HOST && real === selfReal };
+  }
+  return { bin: process.execPath, electron: IS_ELECTRON_HOST };
+}
+const INTERPRETER = preferredNode();
+const NODE_BIN = INTERPRETER.bin;
+/** 解释器是 Electron 二进制时必须注入的变量（真实 node 时为空对象，行为与本改动前一致）。 */
+const SERVICE_NODE_ENV = INTERPRETER.electron ? { ELECTRON_RUN_AS_NODE: "1" } : {};
+/** plist `EnvironmentVariables` 里追加的条目（真实 node 时为空串 → 模板逐字节不变）。 */
+const SERVICE_NODE_ENV_PLIST = Object.entries(SERVICE_NODE_ENV)
+  .map(([k, v]) => `<key>${k}</key><string>${v}</string>`).join("");
+/** systemd unit 里追加的 `Environment=` 行（真实 node 时为空串 → 模板逐字节不变）。 */
+const SERVICE_NODE_ENV_UNIT = Object.entries(SERVICE_NODE_ENV)
+  .map(([k, v]) => `Environment=${k}=${v}\n`).join("");
+/**
+ * 供**子进程 spawn** 用的环境（继承当前环境 + 解释器变量）。
+ * 本文件里凡是用 NODE_BIN 拉起子进程的地方都要带上它。
+ */
+function nodeEnv(extra) {
+  return { ...process.env, ...SERVICE_NODE_ENV, ...(extra || {}) };
 }
-const NODE_BIN = preferredNode();
 
 /**
  * 自启动服务里注入的 PATH。
@@ -516,10 +612,17 @@ function writeWinHiddenLauncher(node, setup) {
   const vbsPath = winHiddenLauncherPath();
   const commandLine = `"${node}" "${setup}" run`; // 真正要执行的命令行
   const literal = commandLine.replace(/"/g, '""'); // 嵌进 VBS 字符串字面量后
+  // 解释器是 Electron（桌面端宿主且机器上没有真实 node）时，必须先设 ELECTRON_RUN_AS_NODE=1：
+  // 否则 wscript 拉起的不是 bridge 守护，而是**又开一个桌面端应用**。
+  // VBScript 侧的写法是往进程环境里塞，再 Run（不能像 shell 那样内联前缀）。
+  const envLines = Object.entries(SERVICE_NODE_ENV).map(([k, v]) => `sh.Environment("PROCESS")("${k}") = "${v}"`);
+  const runLines = envLines.length > 0
+    ? [`Set sh = CreateObject("WScript.Shell")`, ...envLines, `sh.Run "${literal}", 0, False`]
+    : [`CreateObject("WScript.Shell").Run "${literal}", 0, False`];
   const src = [
     "' dsh-remote 自动生成（勿手改，重装会覆盖）",
     "' 隐藏启动 bridge 守护：窗口样式 0 = 不显示窗口；False = 不等待，node 成为独立进程。",
-    `CreateObject("WScript.Shell").Run "${literal}", 0, False`,
+    ...runLines,
     "",
   ].join("\r\n");
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
@@ -532,6 +635,12 @@ function writeWindowsTask() {
   const setup = runtimeSetupPath();
   // 首选 wscript 包装（无黑窗）；写不了 .vbs 就退回直接启动（有窗，但保底能自启）
   let direct = `"${node}" "${setup}" run`;
+  // 解释器是 Electron 时，直接启动这条路没有 .vbs 可以设环境变量，只能借 cmd 的 `set`
+  // （schtasks 的 /TR 只接受一条命令行，不能内联 env）。
+  if (Object.keys(SERVICE_NODE_ENV).length > 0) {
+    const sets = Object.entries(SERVICE_NODE_ENV).map(([k, v]) => `set ${k}=${v}`).join(" && ");
+    direct = `cmd.exe /c ${sets} && "${node}" "${setup}" run`;
+  }
   let tr = direct;
   let hidden = false;
   try {
@@ -599,7 +708,7 @@ function writeAutostartFile() {
   <key>LimitLoadToSessionType</key><array><string>Aqua</string><string>Background</string></array>
   <key>StandardOutPath</key><string>${path.join(CONFIG_DIR, ".dsh-bridge.log")}</string>
   <key>StandardErrorPath</key><string>${path.join(CONFIG_DIR, ".dsh-bridge.log")}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${SERVICE_PATH}</string><key>DSH_BRIDGE_INSTALL_SOURCE</key><string>${INSTALL_SOURCE}</string><key>DSH_BRIDGE_INSTALL_VERSION</key><string>${INSTALL_VERSION}</string></dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${SERVICE_PATH}</string>${SERVICE_NODE_ENV_PLIST}<key>DSH_BRIDGE_INSTALL_SOURCE</key><string>${INSTALL_SOURCE}</string><key>DSH_BRIDGE_INSTALL_VERSION</key><string>${INSTALL_VERSION}</string></dict>
 </dict></plist>`;
     // ~/Library/LaunchAgents 在全新账户/精简系统上可能不存在,必须先建目录,
     // 否则 writeFileSync 抛 ENOENT 直接把安装流程打断(用户反馈里也踩过类似的路径问题)。
@@ -615,7 +724,7 @@ function writeAutostartFile() {
   if (process.platform === "linux") {
     const dir = path.join(os.homedir(), ".config/systemd/user");
     fs.mkdirSync(dir, { recursive: true });
-    const unit = `[Unit]\nDescription=dsh-remote bridge (auto-starts with dsh web)\n\n[Service]\nExecStart=${runCmd}\nRestart=on-failure\nRestartSec=5\nEnvironment=PATH=${SERVICE_PATH}\nEnvironment=DSH_BRIDGE_INSTALL_SOURCE=${INSTALL_SOURCE}\nEnvironment=DSH_BRIDGE_INSTALL_VERSION=${INSTALL_VERSION}\n\n[Install]\nWantedBy=default.target\n`;
+    const unit = `[Unit]\nDescription=dsh-remote bridge (auto-starts with dsh web)\n\n[Service]\nExecStart=${runCmd}\nRestart=on-failure\nRestartSec=5\nEnvironment=PATH=${SERVICE_PATH}\n${SERVICE_NODE_ENV_UNIT}Environment=DSH_BRIDGE_INSTALL_SOURCE=${INSTALL_SOURCE}\nEnvironment=DSH_BRIDGE_INSTALL_VERSION=${INSTALL_VERSION}\n\n[Install]\nWantedBy=default.target\n`;
     const unitPath = autostartFilePath();
     fs.writeFileSync(unitPath, unit);
     return unitPath; // 路径在最终汇总里统一展示
@@ -673,7 +782,7 @@ function spawnDetachedBridge() {
     const child = spawn(NODE_BIN, [runtimeSetupPath(), "run"], {
       detached: true,
       stdio: ["ignore", out, out],
-      env: process.env,
+      env: nodeEnv(),
       // Windows 上 detached 即 DETACHED_PROCESS：子进程**不继承父控制台**，
       // 控制台程序（node.exe）会因此拿到一个**全新的可见窗口**。
       // 必须显式 windowsHide 才会带上 CREATE_NO_WINDOW（POSIX 上该选项被忽略）。
@@ -894,14 +1003,63 @@ async function isDshWebUp(timeoutMs = 1200) {
   return upstreamReachable(after, timeoutMs);
 }
 
+/** 已知的 DSH profile 名（`--profile web` / `--profile desktop` 这种写法要能用）。 */
+const KNOWN_PROFILE_NAMES = ["web", "desktop"];
+/** profile 名 → 目录（与 dsh 自己的 `$DSH_HOME/profiles/<name>` 口径一致）。 */
+function profileDirOfName(name) {
+  return path.join(os.homedir(), ".dsh", "profiles", name);
+}
+/** 目标目录是否就是**桌面端**保留的 profile（由 Electron 应用独占管理）。 */
+function isDesktopProfileDir(dir) {
+  return path.resolve(dir) === path.resolve(profileDirOfName("desktop"));
+}
+
 /**
- * 解析 dsh web profile 目录（安装与插件管理共用同一口径）。
+ * 解析目标 profile 目录（安装与插件管理共用同一口径）。
+ *
+ * 三种写法都支持：
+ *   · `--profile web` / `--profile desktop` → `~/.dsh/profiles/<name>`
+ *     （新增：DeepSeek Harness 桌面端的 profile 就叫 `desktop`）
+ *   · `--profile <任意路径>`                → 原样当目录用（老行为，保持不变）
+ *   · `DSH_PROFILE_DIR` 环境变量            → 与 `--profile` 同口径
+ * 缺省仍是 Web 版 profile，行为与改动前完全一致。
  */
 function resolveProfileDir(argv = []) {
   const i = argv.indexOf("--profile");
-  return i > -1 && argv[i + 1]
-    ? argv[i + 1]
-    : process.env.DSH_PROFILE_DIR || path.join(os.homedir(), ".dsh", "profiles", "web");
+  const explicit = i > -1 && argv[i + 1] ? argv[i + 1] : process.env.DSH_PROFILE_DIR;
+  if (!explicit) return profileDirOfName("web");
+  if (KNOWN_PROFILE_NAMES.includes(explicit)) return profileDirOfName(explicit);
+  return explicit;
+}
+
+/**
+ * 从任意 argv 里挑出 profile 选择参数。
+ *
+ * 为什么需要：安装主流程 `setup()` 的 argv 里可能带 `--profile desktop`，但它内部调用
+ * `pluginCmd()` 时原本传的是空数组 —— 于是"指定 desktop profile"会被静默忽略、
+ * 插件仍然装进 Web 版 profile（桌面端用户装了却看不到面板，且极难自查）。
+ */
+function profileArgvOf(argv = []) {
+  const i = argv.indexOf("--profile");
+  return i > -1 && argv[i + 1] ? ["--profile", argv[i + 1]] : [];
+}
+
+/**
+ * 目标 profile 是桌面端时给出的前置提醒（安装前调用）。
+ *
+ * 桌面端的 `profiles/desktop` 由 Electron 应用**独占**：应用运行时它会持有 profile 写锁，
+ * 且运行中的进程不会重新装载我们刚写进去的插件。所以要么完全退出应用再装，要么
+ * 直接在应用内的「插件」页安装（那是官方路径，无需退出）。
+ * 这里只做提醒，不阻断 —— 用户可能正是在"应用已退出"的状态下跑安装器。
+ */
+function warnIfDesktopProfile(dir) {
+  if (!isDesktopProfileDir(dir)) return;
+  console.log("");
+  console.log("ℹ️ 目标 profile 是 DeepSeek Harness **桌面端**的保留 profile（~/.dsh/profiles/desktop）。");
+  console.log("   · 请先**完全退出** DeepSeek Harness 应用再安装（应用独占该 profile，运行中写入不会被装载）；");
+  console.log("   · 装完后重新打开应用即可。更省事的做法是在应用内「插件」页直接安装 dsh-remote-web；");
+  console.log("   · 桌面端与 Web 版共用 ~/.dsh 下的会话/设置/凭据，但**插件互相隔离**，两边需要各自安装。");
+  console.log("");
 }
 
 /**
@@ -1032,7 +1190,7 @@ logLine("已重新拉起 dsh web：pid=" + String(child.pid));
   try {
     fs.mkdirSync(CONFIG_DIR, { recursive: true });
     fs.writeFileSync(helper, src);
-    const child = spawn(NODE_BIN, [helper], { detached: true, stdio: "ignore", cwd: os.homedir(), windowsHide: true });
+    const child = spawn(NODE_BIN, [helper], { detached: true, stdio: "ignore", cwd: os.homedir(), windowsHide: true, env: nodeEnv() });
     child.on("error", () => { /* 有 error 监听：绝不能把宿主/安装器打挂 */ });
     child.unref();
     return { ok: true, how: "Windows 重启助手（原命令行自拉起）" };
@@ -1357,7 +1515,7 @@ async function runBridge() {
       // 只有它能让我们在停 bridge 之前请它跑完退出钩子（notifystop）—— 见 stopChildGracefully。
       bridgeProc = spawn(NODE_BIN,
         [path.join(THIS_DIR, "clients/dsh-remote/dsh-bridge.mjs")],
-        { env: childEnv, stdio: ["inherit", "inherit", "inherit", "ipc"] });
+        { env: nodeEnv(childEnv), stdio: ["inherit", "inherit", "inherit", "ipc"] });
       bridgeProc.on("exit", () => {
         removePidFile(BRIDGE_PID_FILE);
         console.log("[dsh-remote] bridge 退出，等待重启...");
@@ -1480,7 +1638,10 @@ async function setup(argv) {
   let pluginResult = null;
   if (!noPlugin) {
     try {
-      pluginResult = await pluginCmd([]);
+      // ⚠️ 必须把 `--profile` **透传下去**：否则 `--profile desktop`（桌面端）会被静默忽略，
+      // 插件装进 Web 版 profile，而用户面对的是桌面端 —— 面板永远不出现。
+      warnIfDesktopProfile(resolveProfileDir(argv));
+      pluginResult = await pluginCmd(profileArgvOf(argv));
     } catch (e) {
       console.warn(`⚠️ 插件安装未完成：${e.message}`);
     }
@@ -2178,7 +2339,7 @@ function probePluginResolve(profileDir) {
     "}));",
   ].join("\n");
   try {
-    const r = spawnSync(process.execPath, ["-e", script], { encoding: "utf8", timeout: 30_000, windowsHide: true });
+    const r = spawnSync(process.execPath, ["-e", script], { encoding: "utf8", timeout: 30_000, windowsHide: true, env: nodeEnv() });
     if (r.error) return { ok: false, reason: `无法启动解析探测进程：${r.error.message}` };
     if (r.status !== 0) {
       const line = String(r.stderr || "").split("\n").find((l) => /MODULE_NOT_FOUND|ERR_|Error/.test(l)) || "解析失败";
@@ -2452,8 +2613,19 @@ async function pluginCmd(argv) {
   const pluginDir = path.join(THIS_DIR, "packages", PLUGIN_ID);
 
   if (!fs.existsSync(pkgFile) || !fs.existsSync(patchFile)) {
-    console.error(`❌ 未找到 dsh web profile（${profileDir}）。`);
-    console.error("   请先安装 DeepSeek Harness（npx @deepseek-ai/dsh web）并初始化默认 profile。");
+    console.error(`❌ 未找到 profile（${profileDir}）。`);
+    if (isDesktopProfileDir(profileDir)) {
+      // 桌面端 profile 由 Electron 应用**自己初始化**：npm 版 `dsh` 明确拒绝管理它
+      // （apps/cli 的 rejectElectronProfile），所以 Web 版那句 "npx @deepseek-ai/dsh web"
+      // 在桌面端**不成立**，照抄只会让用户白折腾。这里必须给桌面端专属的三步。
+      console.error("   桌面端 profile 由 DeepSeek Harness 应用自己创建，不能像 Web 版那样用 npx 造出来：");
+      console.error("   ① 先启动一次 DeepSeek Harness 应用，让它初始化该 profile；");
+      console.error("   ② 完全退出应用（应用独占该 profile，运行中安装不会被装载）；");
+      console.error("   ③ 再执行本次安装：dsh-remote --profile desktop");
+      console.error("   更省事的官方路径：直接在应用内「插件」页安装 dsh-remote-web。");
+    } else {
+      console.error("   请先安装 DeepSeek Harness（npx @deepseek-ai/dsh web）并初始化默认 profile。");
+    }
     process.exit(1);
   }
   if (!fs.existsSync(pluginDir)) {

package/packages/dsh-remote-web/test/desktop-compat.test.mjs

@@ -0,0 +1,269 @@
+/**
+ * 桌面端（DeepSeek Harness Desktop / Electron）适配回归。
+ *
+ * 背景：DeepSeek Harness 于 2026-09-29 发布桌面端 v0.2 预览（Electron 薄壳 + 完整 dsh Web Host，
+ * Host 以 `--no-open --port 0` 启动，端口随机、每进程令牌鉴权）。dsh-remote 的两大难点
+ * （随机端口、会话 Cookie）此前已因真实事故适配过，因此这次新增的适配**集中在三处**：
+ *
+ *   ① **Electron 宿主下 process.execPath 不是 node**：它是 Electron 应用二进制。
+ *      直接 `spawn(process.execPath, [script])` 得到的不是"跑脚本的 node"，而是**又开一个桌面端应用**
+ *      （还会撞桌面端单实例锁）。必须补 `ELECTRON_RUN_AS_NODE=1` —— 官方桌面端自己也正是这么做的
+ *      （其内置 CLI 就是 `ELECTRON_RUN_AS_NODE=1 exec <Electron> --expose-internals <cli.js>`）。
+ *   ② **自启动服务里的解释器必须活过桌面应用的退出与更新**：`.app` 路径会变、可能被换掉，
+ *      所以"真实 node 优先，找不到才回落 Electron 自身（并带上 ① 的变量）"。
+ *   ③ **重启语义不同**：桌面端 Host 由 Electron 托管，插件杀掉它会触发桌面端**原生致命恢复弹窗**，
+ *      用户观感是"应用崩了"。故 restartHarness 在 Electron 宿主下**有意拒绝**并如实说明，
+ *      面板据此不摆一个点了必然失败的按钮。
+ *
+ * ⚠️ 这些分支无法在开发机上"真装一个桌面端"来跑，所以本用例用两种手段：
+ *   · 对纯函数（spawnEnv / resolveProfileDir）用**行为断言**（切片 eval，注入宿主相关常量）；
+ *   · 对散落在多文件的模板与分支用**锚点不变量**（跨文件必须同构，防漂移）。
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const INDEX_SRC = readFileSync(path.join(HERE, "..", "lib", "index.js"), "utf8").replace(/\r\n/g, "\n");
+const CLIENT_SRC = readFileSync(path.join(HERE, "..", "lib", "client.js"), "utf8").replace(/\r\n/g, "\n");
+const SETUP_SRC = readFileSync(path.join(HERE, "..", "..", "..", "dsh-setup.mjs"), "utf8").replace(/\r\n/g, "\n");
+
+// ─────────────── ① 子进程环境：Electron 宿主必须补 ELECTRON_RUN_AS_NODE ───────────────
+
+/**
+ * 以给定的宿主形态构造一个真实的 spawnEnv 并调用它。
+ * 切片只含 spawnEnv 函数体，故它引用的模块级常量/工具必须显式注入。
+ *
+ * ⚠️ 必须注入 **process 桩**（2026-10-09）：`spawnEnv` 的第一件事是 `...process.env`，
+ *   而这个套件**是在 DSH 宿主里跑的** —— 从桌面端应用内跑 `npm run test:plugin` 时，
+ *   环境里天然带着 `ELECTRON_RUN_AS_NODE=1`（那正是"宿主是 Electron"的标志）。
+ *   于是"Web 版绝不得注入这个变量"那条断言会读到**宿主自己的**变量而必红 ——
+ *   可被测代码其实一个字节都没往 env 里加。注入干净环境后，这条用例检验的才是插件的行为
+ *   （而不是"运行测试的这台机器是不是桌面端"）。
+ *
+ * @param {object} selfNodeEnv 该宿主形态下 SELF_NODE_ENV 的值
+ * @param {object} [extra] 调用方业务变量
+ * @param {object} [sourceEnv] 宿主进程环境（默认干净：只含 PATH）
+ */
+function makeSpawnEnv(selfNodeEnv, extra, sourceEnv) {
+  const start = INDEX_SRC.indexOf("function spawnEnv(extra)");
+  const end = INDEX_SRC.indexOf("function safeSpawn(");
+  assert.ok(start > 0 && end > start, "切片锚点失效：spawnEnv / safeSpawn 结构变了");
+  const src = INDEX_SRC.slice(start, end);
+  const make = new Function("SELF_NODE_ENV", "isWindows", "delimiter", "dirname", "process", "path",
+    `${src}\nreturn spawnEnv;`);
+  const processStub = { env: sourceEnv ?? { PATH: "/usr/bin:/bin" }, execPath: "/usr/bin/node" };
+  return make(selfNodeEnv, () => false, path.posix.delimiter, path.posix.dirname, processStub, path.posix)(extra);
+}
+
+test("桌面端：Electron 宿主下 spawnEnv 必须注入 ELECTRON_RUN_AS_NODE=1", () => {
+  const env = makeSpawnEnv({ ELECTRON_RUN_AS_NODE: "1" });
+  assert.equal(env.ELECTRON_RUN_AS_NODE, "1",
+    "缺这个变量时 spawn(process.execPath, [script]) 会变成'又开一个桌面端应用'，bridge/watcher 永远起不来");
+});
+
+test("Web 版（真实 node）：绝不得注入 ELECTRON_RUN_AS_NODE（不能污染既有环境）", () => {
+  const env = makeSpawnEnv({});
+  assert.ok(!("ELECTRON_RUN_AS_NODE" in env),
+    "非 Electron 宿主下注入该变量会污染子进程环境、并让 node 版本探测类工具困惑");
+});
+
+test("Web 版：宿主环境**已经带着** ELECTRON_RUN_AS_NODE 时，最终 env 与宿主逐键一致（插件没加料）", () => {
+  // 这条是上面那条的补充（2026-10-09）：上面那条断言"结果里没有这个键"，在 Electron 宿主里
+  // 跑测试时**天然不成立**（键来自宿主 process.env）。真正的判据是"插件有没有往 env 里加料"，
+  // 故这里显式把宿主环境造成带这个变量，验证：最终 env **逐键等于宿主环境 + PATH 调整**，
+  // 一个多余的键都没有（`{}` 展开是恒等）。这样这条用例在任何宿主里都恒真且有意义。
+  const hostEnv = { PATH: "/usr/bin:/bin", ELECTRON_RUN_AS_NODE: "1", HOME: "/Users/tester" };
+  const env = makeSpawnEnv({}, undefined, hostEnv);
+  const expectedPath = ["/usr/bin", "/usr/bin:/bin", "/usr/local/bin", "/opt/homebrew/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":");
+  assert.deepEqual(env, { ...hostEnv, PATH: expectedPath },
+    "除 PATH 外不得新增/删除/改动任何键（否则就是插件在污染子进程环境）");
+  assert.equal(env.ELECTRON_RUN_AS_NODE, "1", "宿主自己的值原样透传，不算插件注入");
+});
+
+test("spawnEnv：NODE_INTERPRETER 变量不得挤掉调用方的业务变量，PATH 仍按平台分隔符拼接", () => {
+  const env = makeSpawnEnv({ ELECTRON_RUN_AS_NODE: "1" }, { DSH_BRIDGE_INSTALL_SOURCE: "npx" });
+  assert.equal(env.DSH_BRIDGE_INSTALL_SOURCE, "npx", "业务变量必须仍能覆盖");
+  assert.ok(env.PATH.includes(path.delimiter), "PATH 必须用平台分隔符（写死 ':' 会让 Windows 上 node/npx 全找不到）");
+});
+
+// ─────────────── ② 服务定义：plist / systemd 必须带上解释器变量（跨文件同构）───────────────
+
+test("跨文件不变量：插件与安装器的 plist / systemd 模板都必须带解释器变量占位", () => {
+  // 为什么是"两份都要查"：历史上前述两份模板漂移过、并因此各造成一个真机事故
+  // （插件每次自愈都会重写 plist，谁写谁说了算 → 漂移等于把另一份正确的覆盖掉）。
+  for (const [name, src] of [["lib/index.js", INDEX_SRC], ["dsh-setup.mjs", SETUP_SRC]]) {
+    assert.match(src, /const SERVICE_NODE_ENV\b/, `${name}: 必须有 SERVICE_NODE_ENV`);
+    assert.match(src, /<key>PATH<\/key><string>\$\{SERVICE_PATH\}<\/string>\$\{SERVICE_NODE_ENV_PLIST\}/,
+      `${name}: plist 的 EnvironmentVariables 必须紧跟 PATH 注入 SERVICE_NODE_ENV_PLIST`);
+    // ⚠️ systemd 模板两种写法都要认：lib/index.js 是多行模板（真换行），
+    //    dsh-setup.mjs 是单行模板（字面量 `\n`）。只认其中一种就会漏掉另一份 —— 那正是"漂移"本身。
+    assert.match(src, /Environment=PATH=\$\{SERVICE_PATH\}(?:\n|\\n)\$\{SERVICE_NODE_ENV_UNIT\}Environment=DSH_BRIDGE/,
+      `${name}: systemd unit 必须在 PATH 之后注入 SERVICE_NODE_ENV_UNIT`);
+  }
+});
+
+test("桌面端：真实 node 存在时服务定义必须优先登记它（.app 路径会随更新失效）", () => {
+  for (const [name, src] of [["lib/index.js", INDEX_SRC], ["dsh-setup.mjs", SETUP_SRC]]) {
+    assert.match(src, /electron: IS_ELECTRON_HOST/,
+      `${name}: 解释器解析结果必须显式标注"是不是 Electron 二进制"（服务定义据此决定要不要补变量）`);
+  }
+  // 安装器额外要求：把"当前可执行文件"归一化后再比对，避免 symlink/node@20 造成误判
+  assert.match(SETUP_SRC, /const selfReal = resolveExecutable\(process\.execPath\)/,
+    "dsh-setup.mjs: 必须归一化自身可执行文件再判断是否为 Electron 本体");
+});
+
+// ─────────────── ③ 重启语义：桌面端必须拒绝，且如实说明 ───────────────
+
+test("桌面端：restartHarness 在 Electron 宿主下**行为级**拒绝（不靠源码字符串）", async () => {
+  // 为什么需要行为级：源码锚点（下面那条）只能证明"代码里写了"，证明不了"跑起来真的是这个结果"。
+  // 注入 IS_ELECTRON_HOST=true、skipsSystemOps=false（模拟**生产**：
+  // 桌面端下 DSH_RELAY_SKIP_SERVICE 不会设置，故必须走到 Electron 守卫而不是被测试隔离短路）。
+  const start = INDEX_SRC.indexOf("async function restartHarness(");
+  const end = INDEX_SRC.indexOf("async function relayFetch(");
+  assert.ok(start > 0 && end > start, "切片锚点失效：restartHarness 结构变了");
+  const src = INDEX_SRC.slice(start, end);
+  // 只注入守卫之前会被求值的两个依赖；函数体其余部分不会被走到（守卫提前 return），
+  // 故其引用的模块级标识符无需注入（new Function 只在**执行**时才解析标识符）。
+  const make = new Function("IS_ELECTRON_HOST", "skipsSystemOps", `${src}\nreturn restartHarness;`);
+  const restartHarness = make(true, () => false);
+  const r = await restartHarness("/tmp/does-not-matter");
+  assert.equal(r.ok, false, "桌面端重启必须如实返回失败，不得假装成功");
+  assert.equal(r.status, "desktop-managed", "面板据该状态改文案，不能是通用错误");
+  assert.equal(r.mode, "desktop");
+  assert.match(r.detail, /退出并重新打开/, "必须告诉用户正确做法");
+  // 对照组：非 Electron 宿主**不得**走这条分支（否则 Web 版重启会被误禁）
+  const restartWeb = make(false, () => true); // skipsSystemOps=true 模拟测试隔离，避免真的重启
+  const rw = await restartWeb("/tmp/does-not-matter");
+  assert.notEqual(rw.status, "desktop-managed", "Web 版绝不能返回桌面端状态");
+});
+
+test("桌面端：restartHarness 必须拒绝重启 Host，并返回可识别的 desktop-managed 状态", () => {
+  // 切片终点用 restartHarness **之后**的下一个顶层函数（buildRestartHelperSource 在它之前，不能用）
+  const fn = INDEX_SRC.slice(INDEX_SRC.indexOf("async function restartHarness("),
+    INDEX_SRC.indexOf("async function relayFetch("));
+  assert.ok(fn.length > 0, "切片锚点失效：restartHarness 找不到了");
+  assert.match(fn, /if \(IS_ELECTRON_HOST\)/, "必须先有 Electron 宿主守卫");
+  assert.match(fn, /status: "desktop-managed"/, "必须返回可识别状态（面板据此换文案、不摆失败按钮）");
+  assert.match(fn, /退出并重新打开 DeepSeek Harness/, "必须如实告诉用户正确做法");
+  // 守卫必须在真正生成重启脚本**之前**：否则仍会写脚本、动 launchd
+  assert.ok(fn.indexOf("if (IS_ELECTRON_HOST)") < fn.indexOf("const cmd = selfCommand();"),
+    "守卫必须早于 selfCommand()/脚本生成");
+});
+
+test("桌面端：状态接口必须下发宿主形态，面板才能自适应", () => {
+  assert.match(INDEX_SRC, /desktopHost: IS_ELECTRON_HOST,/, "composeStatus 必须下发 desktopHost");
+  assert.match(INDEX_SRC, /restartSupported: !IS_ELECTRON_HOST,/, "必须下发 restartSupported");
+});
+
+test("桌面端：面板不得自动倒计时重启，且不摆点了必然失败的重启按钮", () => {
+  assert.match(CLIENT_SRC, /var desktopHost = !!\(st && st\.desktopHost\)/, "面板必须读 desktopHost");
+  assert.match(CLIENT_SRC, /isRestartHard \|\| desktopHost \|\| busy !== ""/,
+    "自动倒计时重启必须在桌面端短路（Host 由 Electron 托管，不能替用户重启）");
+  assert.match(CLIENT_SRC, /\(desktopHost && !isRefreshOnly\) \? null : h\("button"/,
+    "桌面端且非'刷新即可'时不得渲染重启按钮");
+  // 旧版 host 不下发该字段 → undefined → 行为必须与改动前一致
+  assert.match(CLIENT_SRC, /\? "🔄 插件已更新：重启 dsh web 后生效"[\s\S]{0,40}: "🔄 插件已更新：刷新页面即可生效"\);/,
+    "非桌面端文案必须保留原有判据 isRestartHard（不得顺手改发布版文案）");
+});
+
+test("桌面端：面板文案改为引导'退出并重开应用'，且不影响 Web 版", () => {
+  assert.match(CLIENT_SRC, /退出并重新打开 DeepSeek Harness 后生效/, "桌面端要有明确引导");
+  assert.match(CLIENT_SRC, /桌面端由应用本身托管运行环境/, "底部常驻按钮位置要有桌面端说明");
+});
+
+// ─────────────── ④ 安装：--profile desktop 必须真的生效 ───────────────
+
+/**
+ * 用安装器切片构造真实的 resolveProfileDir（注入 os / path / process，伪造 HOME 与空环境）。
+ *
+ * ⚠️ 必须注入 **process 桩**（2026-10-09）：`resolveProfileDir` 的第二来源是
+ *   `process.env.DSH_PROFILE_DIR`，而这个测试套件**是在 DSH 宿主里跑的** ——
+ *   从桌面端应用内跑 `npm run test:plugin` 时，环境里天然带着
+ *   `DSH_PROFILE_DIR=/Users/<me>/.dsh/profiles/desktop`，于是"缺省仍是 Web 版"那条断言
+ *   会读到真实 HOME 下的 desktop，**在任何装了桌面端的机器上必红**（假红，且指向错误结论）。
+ *   注空环境 = 这条用例从此只验证被测逻辑，不受宿主环境影响。
+ */
+function makeResolveProfileDir(home) {
+  const start = SETUP_SRC.indexOf("const KNOWN_PROFILE_NAMES");
+  const end = SETUP_SRC.indexOf("function warnIfDesktopProfile");
+  assert.ok(start > 0 && end > start, "切片锚点失效：profile 解析函数结构变了");
+  const src = SETUP_SRC.slice(start, end);
+  const osStub = { homedir: () => home };
+  const processStub = { env: {} };
+  const make = new Function("os", "path", "process", `${src}\nreturn { resolveProfileDir, profileArgvOf, isDesktopProfileDir, profileDirOfName };`);
+  return make(osStub, path, processStub);
+}
+
+test("安装器：--profile desktop 解析到桌面端 profile 目录，不再是相对路径/被忽略", () => {
+  const { resolveProfileDir, isDesktopProfileDir } = makeResolveProfileDir("/Users/tester");
+  assert.equal(resolveProfileDir(["--profile", "desktop"]), path.join("/Users/tester", ".dsh", "profiles", "desktop"));
+  assert.ok(isDesktopProfileDir(resolveProfileDir(["--profile", "desktop"])), "必须能识别出这是桌面端 profile");
+  // 老行为必须原样保留
+  assert.equal(resolveProfileDir(["--profile", "web"]), path.join("/Users/tester", ".dsh", "profiles", "web"));
+  assert.equal(resolveProfileDir(["--profile", "/custom/dir"]), "/custom/dir", "任意路径仍原样当目录用");
+  assert.equal(resolveProfileDir([]), path.join("/Users/tester", ".dsh", "profiles", "web"), "缺省仍是 Web 版");
+});
+
+test("安装器：setup() 必须把 --profile 透传给插件挂载步骤", () => {
+  const { profileArgvOf } = makeResolveProfileDir("/Users/tester");
+  assert.deepEqual(profileArgvOf(["--profile", "desktop"]), ["--profile", "desktop"]);
+  assert.deepEqual(profileArgvOf([]), [], "未指定时不得凭空塞参数");
+  // 事故面：setup() 原本调 pluginCmd([]) → --profile desktop 被静默忽略、插件装进 web profile
+  assert.match(SETUP_SRC, /pluginCmd\(profileArgvOf\(argv\)\)/, "setup 必须透传 profile 选择");
+  assert.ok(!/pluginCmd\(\[\]\)/.test(SETUP_SRC), "不得再有硬编码空参数（会把 --profile 吞掉）");
+});
+
+test("安装器：desktop profile 未初始化时给桌面端专属引导（不得照抄 Web 版的 npx 说法）", () => {
+  // 用定长切片而不是尾部锚点：这段逻辑就在 pluginCmd 开头，之后的结构变化不该让用例变脆。
+  const start = SETUP_SRC.indexOf("async function pluginCmd(");
+  assert.ok(start > 0, "切片锚点失效：pluginCmd 找不到了");
+  const fn = SETUP_SRC.slice(start, start + 2500);
+  assert.match(fn, /isDesktopProfileDir\(profileDir\)/, "必须区分桌面端 profile");
+  assert.match(fn, /启动一次 DeepSeek Harness 应用/, "必须给桌面端专属引导：profile 由应用自己创建");
+  assert.match(fn, /完全退出应用/, "必须提醒完全退出（应用独占 profile，运行中安装不会被装载）");
+  // 事故面：桌面端 profile 由 Electron 应用初始化，npm 版 dsh 明确拒绝管理它
+  //（apps/cli 的 rejectElectronProfile）—— 照抄 Web 版那句会让用户白折腾。
+  assert.ok(!/未找到 dsh web profile/.test(fn), "不得再把桌面端统一报成 'dsh web profile'");
+});
+
+// ─────────────── ⑤ 桌面端自带 Node：跨平台候选（Windows 用 node.exe）───────────────
+
+test("桌面端自带 Node 的候选：跨平台 + 命中官方真实布局 + 稳定落点优先", () => {
+  for (const [name, src] of [["lib/index.js", INDEX_SRC], ["dsh-setup.mjs", SETUP_SRC]]) {
+    assert.match(src, /function desktopRuntimeNodeCandidates\(\)/, `${name}: 必须有候选构造器`);
+    // 真实布局（2026-10-07 拆官方 0.2.0-rc.2 DMG 实测）：
+    //   …/Resources/runtime/primary-runtime/dependencies/node/bin/node  （Node v24.21.0）
+    assert.match(src, /"dependencies", "node", "bin"/,
+      `${name}: 必须命中官方真实布局 dependencies/node/bin（猜错路径等于没这个候选）`);
+    assert.match(src, /DSH_DESKTOP_NODE_EXECUTABLE/,
+      `${name}: 必须采信应用自报的 node 路径（平台无关，比猜路径可靠）`);
+    assert.match(src, /\.\.\.desktopRuntimeNodeCandidates\(\)/,
+      `${name}: 必须真的并入解释器候选（不是死代码）`);
+  }
+
+  // 行为断言：注入平台与 HOME，验证真实产出（而不是只查字符串）
+  const start = SETUP_SRC.indexOf("function desktopRuntimeNodeCandidates()");
+  const end = SETUP_SRC.indexOf("function preferredNode()");
+  assert.ok(start > 0 && end > start, "切片锚点失效：候选构造器结构变了");
+  const src = SETUP_SRC.slice(start, end);
+  const make = new Function("process", "os", "path", `${src}\nreturn desktopRuntimeNodeCandidates;`);
+  const home = path.join(path.sep, "Users", "tester");
+  const win = make({ platform: "win32", env: {} }, { homedir: () => home }, path)();
+  const mac = make({ platform: "darwin", env: {} }, { homedir: () => home }, path)();
+
+  assert.ok(win.length > 0 && win.every((p) => p.endsWith("node.exe")),
+    `Windows 候选必须都是 node.exe（否则永远解析不到解释器），实际 ${JSON.stringify(win)}`);
+  assert.ok(mac.length > 0 && mac.every((p) => p.endsWith("node")),
+    `POSIX 候选必须都是 node，实际 ${JSON.stringify(mac)}`);
+  // 稳定落点优先：首条必须落在用户目录，且命中官方真实布局
+  assert.ok(mac[0].startsWith(home),
+    `首条候选必须在用户目录（要活过桌面端更新），实际 ${mac[0]}`);
+  assert.ok(mac[0].endsWith(path.join("dependencies", "node", "bin", "node")),
+    `首条候选必须是官方真实布局 dependencies/node/bin/node，实际 ${mac[0]}`);
+  // 会随桌面端更新失效的 .app 路径只能当后手
+  assert.ok(!mac[0].startsWith("/Applications"),
+    "不得把 .app 内部路径排在稳定落点之前（桌面端一升级自启动就失效）");
+});