@mrrisega/dsh-remote 0.6.6 → 0.6.7-beta.2

package/dsh-setup.mjs

@@ -26,7 +26,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { spawn, execSync } from "node:child_process";
+import { spawn, spawnSync, execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { childStopped } from "./clients/dsh-remote/src/lifecycle.mjs";
 
@@ -45,6 +45,22 @@ const DEFAULT_API = "https://n.risegao.cn:13443/relay-api";
 const DEFAULT_APP_URL = "https://n.risegao.cn:13443/app/";
 const REPO_URL = "https://github.com/mrRisega/dsh-remote";
 
+// ---------- 平台（0.6.7 起支持 Windows） ----------
+const IS_WIN = process.platform === "win32";
+/**
+ * Windows 自启动 = 任务计划程序（Task Scheduler）里的登录任务。
+ * 为什么不是「启动文件夹快捷方式」：生成 .lnk 需要额外依赖或 COM 调用，而 schtasks 系统自带，
+ * 且**不需要管理员**就能为当前用户建 ONLOGON 任务（默认「仅在用户登录时运行」，不存密码）。
+ */
+const WIN_TASK_NAME = "dsh-remote-bridge";
+/**
+ * watcher / bridge 的 pid 文件（Windows 必需）。
+ * Windows 没有 pgrep/ps，插件半（dsh-remote-web）与安装器都靠这两个文件发现进程：
+ * watcher = 本安装器 `run` 子命令的进程，bridge = 它拉起的 dsh-bridge.mjs 子进程。
+ */
+const WATCHER_PID_FILE = ".dsh-watcher.pid";
+const BRIDGE_PID_FILE = ".dsh-bridge.pid";
+
 // ---------- 运行时自物化（npm/npx 安装 → 固化到配置目录，脱离 npx 缓存） ----------
 // npx 每次安装的缓存目录（~/.npm/_npx/<hash>）不固定：缓存一旦清理，指向它的自启动服务
 // 就会像“找不到模块”一样崩溃。因此 npm 形态安装时把 dsh-setup.mjs + clients + 依赖(ws)
@@ -135,6 +151,49 @@ function ensureRuntimeCopy() {
   fs.writeFileSync(verFile, ver);
   console.log(`✅ 运行时: ${CONFIG_DIR}`);
 }
+/** 打印用法（唯一实现：提前退出与末尾分派共用，避免两处漂移）。 */
+function printHelp() {
+  console.log(`dsh-remote — 手机远程控制 dsh web（隧道模式）
+
+用法:
+  dsh-remote              一键安装（默认命令，无需任何参数；含插件与自启动）
+  dsh-remote settings     显示登录/连接配置指引（独立设置页已移除）
+  dsh-remote run          前台运行 bridge（调试）
+  dsh-remote status       查看配置与服务状态
+  dsh-remote plugin       手动安装 dsh web 远程控制插件（--uninstall 卸载）
+  dsh-remote repair       修复插件挂载（dsh web 起不来时用；只碰 profile，不联网）
+  dsh-remote --help       显示本用法（等同 dsh-remote help）
+
+自建模式（可选）:
+  dsh-remote setup --server wss://你的域名:端口 --key 访问密钥
+
+登录/连接配置: 打开 dsh web → 设置 → 「远程控制」→ 注册或登录手机号即可
+（自建用户切「自建服务」标签或直接用上方 setup 命令，无需另开页面）。
+文档: ${REPO_URL}
+`);
+}
+
+// 认识的参数（只给 flag 也要能装上去，所以不认识时才拦）。
+const KNOWN_FLAGS = new Set([
+  "--api", "--server", "--key", "--profile",
+  "--no-autostart", "--no-plugin", "--no-restart", "--uninstall"
+]);
+
+// ⚠️ 这一整块必须挡在 ensureRuntimeCopy() **之前**：它会往 ~/.dsh-remote 同步运行时脚本。
+// 看用法、或参数拼错，都不该改动用户磁盘 —— 此前 `dsh-remote --help` 会一路走到 setup，
+// 什么都不问就开始安装。
+{
+  const first = process.argv[2];
+  if (first === "-h" || first === "--help" || first === "help") {
+    printHelp();
+    process.exit(0);
+  }
+  if (first && first.startsWith("-") && !KNOWN_FLAGS.has(first)) {
+    console.error(`❌ 未知参数: ${first}`);
+    console.error("   直接安装就用 dsh-remote（不带参数）；查看用法用 dsh-remote --help。");
+    process.exit(1);
+  }
+}
 try { ensureRuntimeCopy(); } catch (e) { console.warn(`⚠️ 运行时固化跳过: ${e.message}`); }
 
 /** 自启动服务应指向的 dsh-setup.mjs：优先配置目录内的固化副本，否则当前执行文件。 */
@@ -188,7 +247,7 @@ const NODE_BIN = preferredNode();
  */
 const SERVICE_PATH = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin";
 
-// ---------- 安装口径（随 bridge 环境变量注入；服务端存到设备行，供运营统计） ----------
+// ---------- 安装口径（随 bridge 环境变量注入；服务端存到设备行，用于区分安装来源） ----------
 /**
  * install_source：本文件即「一键安装器」→ 默认 npx（用户自己跑 `npx @mrrisega/dsh-remote` 的那条路径）。
  * 插件市场那条路径由插件半自愈补装：插件 spawn 本安装器时显式传入
@@ -268,6 +327,95 @@ function sleepSync(ms) {
   catch { /* 极端环境不支持 → 退化为忙等一小会 */ const end = Date.now() + ms; while (Date.now() < end) { /* spin */ } }
 }
 
+/**
+ * 运行 schtasks（Windows 任务计划程序）。
+ * **不走 sh()**：/TR 里必然带引号（node 路径与脚本路径都可能含空格），
+ * 经 cmd.exe 转一层会把嵌套引号绞碎；spawnSync 直接把 argv 交给 CreateProcess，
+ * 由 Node 负责转义，参数原样到达 schtasks。
+ */
+function schtasks(args, timeoutMs = 15000) {
+  try {
+    const r = spawnSync("schtasks", args, { encoding: "utf8", timeout: timeoutMs, windowsHide: true });
+    return {
+      ok: r.status === 0,
+      code: r.status,
+      stdout: String(r.stdout || ""),
+      stderr: String(r.stderr || (r.error && r.error.message) || ""),
+    };
+  } catch (e) {
+    return { ok: false, code: -1, stdout: "", stderr: e.message };
+  }
+}
+
+/** 写 pid 文件（Windows 进程发现用；失败不致命，插件半还有 PowerShell 兜底扫描）。 */
+function writePidFile(name, pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(path.join(CONFIG_DIR, name), String(pid));
+  } catch { /* 非关键 */ }
+}
+
+function removePidFile(name) {
+  try { fs.rmSync(path.join(CONFIG_DIR, name), { force: true }); } catch { /* 非关键 */ }
+}
+
+function readPidFile(name) {
+  try {
+    const n = Number(String(fs.readFileSync(path.join(CONFIG_DIR, name), "utf8")).trim());
+    return Number.isInteger(n) && n > 0 ? n : null;
+  } catch { return null; }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+/**
+ * 注册 Windows 登录任务（幂等：先删再建）。
+ * /DELAY 0000:15：登录后等 15 秒再起，避免与桌面环境抢启动时机
+ * （watcher 本身就会等 dsh web 的 3080 端口，晚起没有任何副作用）。
+ * ⚠️ 已知限制（如实告知，不假装完美）：ONLOGON 任务在用户会话里运行，登录时会有一个控制台窗口；
+ * 想彻底隐藏需要"不管用户是否登录都运行"(存密码/S4U) 或第三方隐藏器，都需要额外凭据或依赖，
+ * 故这里只做「能自启」，并在安装汇总里说明用户可在任务计划程序里勾「隐藏」。
+ */
+let winTaskCache = null;
+
+function writeWindowsTask() {
+  const node = NODE_BIN;
+  const setup = runtimeSetupPath();
+  const tr = `"${node}" "${setup}" run`;
+  if (tr.length > 255) {
+    console.log(`⚠️ 自启动命令过长（${tr.length} 字符，schtasks 上限 261）：${tr}`);
+    console.log("   建议把 dsh-remote 装到更短的路径，或用 `dsh-remote run` 手动运行 bridge。");
+  }
+  schtasks(["/Delete", "/TN", WIN_TASK_NAME, "/F"]); // 幂等清理（不存在也只是非 0 退出，不影响后续
+  const created = schtasks(["/Create", "/TN", WIN_TASK_NAME, "/TR", tr, "/SC", "ONLOGON", "/DELAY", "0000:15", "/F"]);
+  if (!created.ok) {
+    winTaskCache = false;
+    console.warn(`⚠️ 自启动任务注册失败: ${(created.stderr || created.stdout).trim() || `schtasks 退出码 ${created.code}`}`);
+    console.warn("   可手动执行 `dsh-remote run` 运行 bridge（功能完全一样，只是不随登录自启）。");
+    return null;
+  }
+  winTaskCache = true;
+  return `任务计划程序 / ${WIN_TASK_NAME}`; // 汇总里展示的"路径"
+}
+
+/** 查询 Windows 登录任务是否已注册（退出码 0 = 存在；不解析本地化输出）。 */
+function windowsTaskInstalled() {
+  return schtasks(["/Query", "/TN", WIN_TASK_NAME]).ok;
+}
+
+/**
+ * 本次进程内查询一次登录任务是否已注册（汇总里多处要用，避免反复起 schtasks）。
+ * 注册/删除任务时同步刷新缓存，保证汇总看到的是最终状态。
+ */
+function winTaskOk() {
+  if (winTaskCache === null) winTaskCache = windowsTaskInstalled();
+  return winTaskCache;
+}
+
 function writeAutostartFile() {
   const runCmd = `"${NODE_BIN}" "${runtimeSetupPath()}" run`;
   if (process.platform === "darwin") {
@@ -311,7 +459,8 @@ function writeAutostartFile() {
     fs.writeFileSync(unitPath, unit);
     return unitPath; // 路径在最终汇总里统一展示
   }
-  console.log("⚠️ 当前平台暂不支持自启动，请手动运行 `dsh-remote run`");
+  if (IS_WIN) return writeWindowsTask();
+  console.log(`⚠️ 当前平台（${process.platform}）暂不支持自启动，请手动运行 \`dsh-remote run\``);
   return null;
 }
 
@@ -429,6 +578,22 @@ function startBridgeDarwin(plistPath) {
 }
 
 function restartBridgeService() {
+  if (IS_WIN) {
+    if (!windowsTaskInstalled()) writeWindowsTask(); // 静默补生成(调用方会汇总展示)
+    // /Run 只是"现在跑一次"；等 pid 文件出现才算真的起来了（schtasks 的退出码只说明任务被触发）
+    const r = schtasks(["/Run", "/TN", WIN_TASK_NAME]);
+    if (!r.ok) return { ok: false, status: "failed", detail: (r.stderr || r.stdout).trim() || `schtasks /Run 退出码 ${r.code}` };
+    for (let i = 0; i < 20; i += 1) {
+      const pid = readPidFile(WATCHER_PID_FILE);
+      if (pid && pidAlive(pid)) return { ok: true, status: "running", pid };
+      sleepSync(400);
+    }
+    return {
+      ok: false,
+      status: "degraded-detached",
+      detail: "已触发自启动任务，但没等到 bridge 守护进程（dsh web 可能还没运行；打开 dsh web 后会自动接上）",
+    };
+  }
   const svcFile = autostartFilePath();
   if (svcFile && !fs.existsSync(svcFile)) {
     writeAutostartFile(); // 静默补生成(调用方会汇总展示路径)
@@ -474,8 +639,21 @@ function resolveProfileDir(argv = []) {
     : process.env.DSH_PROFILE_DIR || path.join(os.homedir(), ".dsh", "profiles", "web");
 }
 
-/** 监听 127.0.0.1:3080 的进程 pid（= dsh web）。lsof 不可用时回退 pgrep。 */
+/**
+ * 监听 127.0.0.1:3080 的进程 pid（= dsh web）。
+ * macOS/Linux：lsof → pgrep；Windows：netstat -ano 取 LISTENING 行的最后一列
+ * （netstat 是系统自带，比每次都起 PowerShell 快得多）。
+ */
 function dshWebPid() {
+  if (IS_WIN) {
+    const r = sh('netstat -ano | findstr ":3080"');
+    for (const line of String(r.stdout || "").split("\n")) {
+      if (!/LISTENING/i.test(line)) continue;
+      const m = line.trim().match(/(\d+)\s*$/);
+      if (m) return Number(m[1]);
+    }
+    return null;
+  }
   const l = sh("lsof -nP -iTCP:3080 -sTCP:LISTEN -t 2>/dev/null || true");
   const pid = String(l.stdout || "").trim().split(/\s+/).filter(Boolean)[0];
   if (pid && /^\d+$/.test(pid)) return Number(pid);
@@ -512,8 +690,10 @@ function dshWebLaunchdJob() {
 }
 
 function restartDshWeb() {
-  const uid = process.getuid();
+  // ⚠️ process.getuid 只在 macOS 分支里取：Windows 上**没有这个函数**，
+  // 旧写法把它放在函数首行无条件调用 → 安装流程在 Windows 直接 TypeError 中断。
   if (process.platform === "darwin") {
+    const uid = process.getuid();
     const job = dshWebLaunchdJob();
     if (job) {
       const r = sh(`launchctl kickstart -k gui/${uid}/${job}`);
@@ -524,6 +704,7 @@ function restartDshWeb() {
     const r = sh("systemctl --user restart dsh-web 2>/dev/null || systemctl --user restart dsh 2>/dev/null");
     if (r.ok) return { ok: true, how: "systemctl --user restart dsh-web" };
   }
+  if (IS_WIN) return restartDshWebWindows();
   // 兜底：沿用原命令行重启（只在能拿到真实 node 入口时做，npx 缓存路径不可靠）
   const pid = dshWebPid();
   if (!pid) return { ok: false, how: "", detail: "未找到 dsh web 进程" };
@@ -540,6 +721,95 @@ function restartDshWeb() {
   }
 }
 
+/**
+ * Windows：重启 dsh web（沿用原命令行自拉起）。
+ *
+ * 与插件半的重启助手同源思路：**先校验新进程拉得起来，再动旧进程**；用 node 跑一个 .mjs 助手，
+ * 不经过任何 shell（Windows 没有 /bin/sh，cmd.exe 的引号规则又极易把带空格的 node/入口路径绞碎）。
+ * 拿不到命令行（例如经 npx 启动）时如实拒绝，让用户手动重启，绝不"杀掉却起不来"。
+ */
+function restartDshWebWindows() {
+  const pid = dshWebPid();
+  if (!pid) return { ok: false, how: "", detail: "未找到监听 3080 的进程（dsh web 没在运行？）" };
+  const cmdline = windowsProcessCommandLine(pid);
+  if (!cmdline) return { ok: false, how: "", detail: "无法获取 dsh web 的启动命令行，请手动重启" };
+  if (/_npx|node_modules\\\.bin|node_modules\/\.bin/.test(cmdline)) {
+    return { ok: false, how: "", detail: "dsh web 是经 npx 启动的，无法安全复用命令行，请手动重启" };
+  }
+  const argv = parseWindowsCommandLine(cmdline);
+  if (!argv.length || !fs.existsSync(argv[0])) {
+    return { ok: false, how: "", detail: "dsh web 的启动命令无法解析为可执行程序，请手动重启" };
+  }
+  const helper = path.join(CONFIG_DIR, ".dsh-restart-dshweb.mjs");
+  const plan = JSON.stringify({ pid, argv, log: path.join(CONFIG_DIR, ".dsh-restart.log") });
+  const src = `import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, openSync, closeSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+const PLAN = ${plan};
+function logLine(m) { try { appendFileSync(PLAN.log, "\\n[" + new Date().toISOString() + "] " + m + "\\n"); } catch (e) {} }
+if (!existsSync(PLAN.argv[0])) { logLine("重启中止：可执行文件不存在 " + PLAN.argv[0]); process.exit(1); }
+function alive(p) { try { process.kill(p, 0); return true; } catch (e) { return e.code === "EPERM"; } }
+logLine("dsh web 重启助手启动：旧 pid=" + PLAN.pid);
+await delay(1000);
+try { process.kill(PLAN.pid); } catch (e) {}
+const deadline = Date.now() + 30000;
+while (Date.now() < deadline && alive(PLAN.pid)) await delay(200);
+if (alive(PLAN.pid)) spawnSync("taskkill", ["/PID", String(PLAN.pid), "/T", "/F"], { windowsHide: true });
+let out = "ignore";
+try { out = openSync(PLAN.log, "a"); } catch (e) {}
+const child = spawn(PLAN.argv[0], PLAN.argv.slice(1), { detached: true, stdio: ["ignore", out, out], windowsHide: true });
+child.on("error", (e) => logLine("重新拉起失败：" + e.message));
+child.unref();
+if (typeof out === "number") { try { closeSync(out); } catch (e) {} }
+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 });
+    child.on("error", () => { /* 有 error 监听：绝不能把宿主/安装器打挂 */ });
+    child.unref();
+    return { ok: true, how: "Windows 重启助手（原命令行自拉起）" };
+  } catch (e) {
+    return { ok: false, how: "", detail: e.message };
+  }
+}
+
+/** 读某进程的完整命令行（PowerShell CIM；取不到返回空串）。 */
+function windowsProcessCommandLine(pid) {
+  const script = `(Get-CimInstance Win32_Process -Filter "ProcessId=${Number(pid)}").CommandLine`;
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+  try {
+    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
+      { encoding: "utf8", timeout: 8000, windowsHide: true });
+    return String(r.stdout || "").trim();
+  } catch { return ""; }
+}
+
+/**
+ * 把 Windows 命令行拆成 argv（按 CreateProcess/CRT 的引号规则）。
+ * 不引第三方依赖；处理 `"a b" c`、`a\b c`、`"a\"b"` 等常见形态即可。
+ */
+function parseWindowsCommandLine(cmd) {
+  const out = [];
+  let cur = "";
+  let inQuote = false;
+  let started = false;
+  for (let i = 0; i < cmd.length; i += 1) {
+    const ch = cmd[i];
+    if (ch === "\\" && cmd[i + 1] === '"') { cur += '"'; i += 1; started = true; continue; }
+    if (ch === '"') { inQuote = !inQuote; started = true; continue; }
+    if (!inQuote && /\s/.test(ch)) {
+      if (started) { out.push(cur); cur = ""; started = false; }
+      continue;
+    }
+    cur += ch;
+    started = true;
+  }
+  if (started) out.push(cur);
+  return out;
+}
+
 function installAutostart() {
   const svcPath = writeAutostartFile();
   const r = restartBridgeService();
@@ -565,6 +835,15 @@ dsh-remote：独立的本地设置页已移除。
 
 // ---------- run：前台跑 bridge（带配置 + 自启动 watcher） ----------
 async function runBridge() {
+  // Windows 去重：登录任务（Task Scheduler）与插件半的自愈都可能拉起 watcher，
+  // 两个 bridge 会抢同一个设备登记 → 这里以 pid 文件为准，已有守护在跑就直接退出。
+  if (IS_WIN) {
+    const other = readPidFile(WATCHER_PID_FILE);
+    if (other && other !== process.pid && pidAlive(other)) {
+      console.log(`[dsh-remote] 已有一个 bridge 守护在运行（pid=${other}），本进程直接退出，避免重复实例。`);
+      return;
+    }
+  }
   let cfg = loadConfig();
   let warnedNoLogin = false;
 
@@ -629,7 +908,13 @@ async function runBridge() {
       bridgeProc = spawn(NODE_BIN,
         [path.join(THIS_DIR, "clients/dsh-remote/dsh-bridge.mjs")],
         { env: childEnv, stdio: "inherit" });
-      bridgeProc.on("exit", () => { console.log("[dsh-remote] bridge 退出，等待重启..."); });
+      bridgeProc.on("exit", () => {
+        removePidFile(BRIDGE_PID_FILE);
+        console.log("[dsh-remote] bridge 退出，等待重启...");
+      });
+      // Windows：落 pid 文件，供插件半发现进程（Windows 没有 pgrep/ps）。
+      // 插件半启动 bridge 走的就是本函数，所以这里写一次两边都覆盖到。
+      if (IS_WIN) writePidFile(BRIDGE_PID_FILE, bridgeProc.pid);
       setTimeout(() => { starting = false; }, 5000);
     } else if (!alive && bridgeProc && bridgeProc.exitCode === null) {
       console.log("[dsh-remote] dsh web 离线，停止 bridge...");
@@ -637,6 +922,16 @@ async function runBridge() {
     }
   };
 
+  // Windows：watcher 自身的 pid 也要落盘（插件半据此判断"守护在跑"并避免重复拉起）
+  if (IS_WIN) {
+    writePidFile(WATCHER_PID_FILE, process.pid);
+    const cleanup = () => { removePidFile(WATCHER_PID_FILE); removePidFile(BRIDGE_PID_FILE); };
+    process.on("exit", cleanup);
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK"]) {
+      try { process.on(sig, () => { cleanup(); process.exit(0); }); } catch { /* 该信号在本平台不可注册 */ }
+    }
+  }
+
   await ensureBridge();
   setInterval(ensureBridge, 10000); // 每 10s 检查
   console.log("[dsh-remote] 守护运行中（Ctrl-C 退出）");
@@ -792,13 +1087,23 @@ async function setup(argv) {
   const svcSkipped = st.status === "skipped" || st.status === "unsupported" || !svc.path;
   // 第三态:起来了、但本机 launchd 不保证崩溃自愈(on-demand-only 的 gui domain 只能靠 kickstart 拉起),
   // 必须与"完全正常"分开说 —— 否则用户以为有自启,进程一崩就永久掉线且找不到原因。
-  const svcFragile = !svcSkipped && st.ok && st.selfHealing === false;
+  // Windows 没有 launchd，这条判断对它不成立（否则会把 win32 误报成"本机不支持崩溃自愈"）。
+  const svcFragile = !IS_WIN && !svcSkipped && st.ok && st.selfHealing === false;
   const svcDegraded = st.status === "degraded-detached";
-  const svcState = svcSkipped
-    ? (st.status === "skipped" ? "未安装（本次显式跳过）" : "未安装（当前平台不支持自启动）")
-    : (st.ok
-        ? `✅ 运行中${st.pid ? ` (pid=${st.pid})` : ""}${svcFragile ? "，但本机不支持崩溃自愈" : ""}`
-        : (svcDegraded ? "⚠️ 未被系统托管（已用后台进程兜底）" : `未运行 (${st.detail || st.status})`));
+  // Windows：自启动 = 任务计划程序里的登录任务。口径与 macOS/Linux 不同
+  // （"任务已注册" ≠ "进程此刻在跑"），所以单独给文案，避免复用"未被系统托管"这种会误导的措辞。
+  const winTask = IS_WIN && winTaskOk();
+  const svcState = IS_WIN
+    ? (st.status === "skipped"
+        ? "未安装（本次显式跳过）"
+        : (!winTask
+            ? "未注册（登录任务创建失败，可用 `dsh-remote run` 手动运行 bridge）"
+            : (st.ok ? `✅ 已注册，守护进程在运行${st.pid ? ` (pid=${st.pid})` : ""}` : "✅ 已注册（登录后自动运行；dsh web 打开时会立刻接上）")))
+    : (svcSkipped
+        ? (st.status === "skipped" ? "未安装（本次显式跳过）" : "未安装（当前平台不支持自启动）")
+        : (st.ok
+            ? `✅ 运行中${st.pid ? ` (pid=${st.pid})` : ""}${svcFragile ? "，但本机不支持崩溃自愈" : ""}`
+            : (svcDegraded ? "⚠️ 未被系统托管（已用后台进程兜底）" : `未运行 (${st.detail || st.status})`)));
   const L = [];
   L.push("✅ 安装完成");
   if (selfHosted) {
@@ -823,7 +1128,13 @@ async function setup(argv) {
     L.push("   如果 dsh web 已经开着但看不到本机，先重启 dsh web 让插件生效。");
   } else if (!st.ok) {
     L.push("");
-    if (svcDegraded) {
+    if (IS_WIN) {
+      // Windows：登录任务已注册，只是此刻 bridge 守护还没就绪（dsh web 刚起、或还没登录账号）
+      L.push(`ℹ bridge 守护还没就绪: ${st.detail || st.status}`);
+      L.push(`   已注册登录任务「${WIN_TASK_NAME}」，下次登录会自动运行；`);
+      L.push("   也可以现在执行 `dsh-remote run` 前台运行 bridge（Ctrl-C 退出）。");
+      L.push(`   日志: ${CONFIG_DIR}\\.dsh-bridge.log`);
+    } else if (svcDegraded) {
       // launchd 托管失败但进程活着:能立刻用,只是没有自启/自愈。如实说明,别让用户以为有自启。
       L.push(`⚠️ ${st.detail}`);
       L.push(`   bridge 已在后台运行${st.pid ? `（pid=${st.pid}）` : ""}，现在就能用；`);
@@ -1163,24 +1474,143 @@ function copyPluginIntoProfile(profileDir, pluginDir) {
 }
 
 /** 把插件挂到 <profile>/node_modules/<PLUGIN_ID>(裸包名解析需要),指向拷贝目录;缺失/指错时重建。 */
+/**
+ * 判定 `node_modules/<PLUGIN_ID>` 是否**真的可用**。
+ *
+ * 判据绝不是"函数有没有抛错" —— 这是 0.6.7-beta.1 在 Windows 上翻车的根因：
+ * 非特权进程 + 开发者模式关闭时，`fs.symlinkSync(target, path, "dir")` 会**既不抛错也产不出可用链接**
+ * （实测：用户目录下留下一个空目录；%TEMP% 下什么都不留；同一位置两次运行一次报成功一次抛 UNKNOWN）。
+ * 于是"用 try/catch 探测能力"这个前提在 Windows 上根本不成立，写在其 catch 里的 junction 兜底永不执行。
+ *
+ * 这里只认 dsh 自己那条解析路径能不能走通：
+ *   ① 读得到 package.json 且 name 正确（cordis 加载器 + @deepseek-ai/dsh-client-modules 靠它读 dsh.client）；
+ *   ② 读得到 lib/index.js（节点半入口）；
+ *   ③ 要么 realpath 指回本地拷贝目录（链接形态），要么入口内容与本地拷贝逐字节一致（整目录拷贝形态）。
+ */
+function pluginLinkUsable(nmPlugin, pluginLocalDir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(nmPlugin, "package.json"), "utf8"));
+    if (pkg.name !== PLUGIN_ID) return false;
+    if (!fs.existsSync(path.join(nmPlugin, "lib", "index.js"))) return false;
+  } catch { return false; }
+
+  let real = "";
+  try { real = fs.realpathSync(nmPlugin); } catch { /* 悬空链接 */ }
+  if (real) {
+    try { if (real === fs.realpathSync(pluginLocalDir)) return true; } catch { /* 本地目录不在 → 看内容 */ }
+  }
+  try {
+    return fs.readFileSync(path.join(nmPlugin, "lib", "index.js"), "utf8")
+      === fs.readFileSync(path.join(pluginLocalDir, "lib", "index.js"), "utf8");
+  } catch { return false; }
+}
+
+/**
+ * 把插件挂到 `<profile>/node_modules/<PLUGIN_ID>`。
+ *
+ * 规格：已就绪返回 false（幂等）、重建成功返回 true、**任何情况下都没能挂好就抛错**。
+ * 抛错是刻意的 —— 调用方必须据此中止安装：写进 patch 的激活行会让 dsh web 按裸包名解析这个目录，
+ * 解析不到就 `Cannot find package '...\node_modules\dsh-remote-web\index.js'`，
+ * 而 cordis 的插件树加载失败 = **整个 dsh web 起不来**（用户连面板都打不开，没有自助修复入口）。
+ * 宁可不装，也不能写出一个起不来的 profile。
+ */
 function ensurePluginLinked(profileDir, pluginLocalDir) {
   const nmDir = path.join(profileDir, "node_modules");
   const nmPlugin = path.join(nmDir, PLUGIN_ID);
+  if (!fs.existsSync(path.join(pluginLocalDir, "package.json"))) {
+    throw new Error(`本地插件拷贝缺失或不完整：${pluginLocalDir}（应含 package.json）`);
+  }
   fs.mkdirSync(nmDir, { recursive: true });
   // 清理历史名链接（node_modules/dsh-remote-ui），避免解析到旧拷贝
   for (const id of PLUGIN_LEGACY_IDS) {
     try { fs.rmSync(path.join(nmDir, id), { recursive: true, force: true }); } catch { /* ignore */ }
   }
+  if (pluginLinkUsable(nmPlugin, pluginLocalDir)) return false; // 已就绪（拷贝形态也算就绪）
+
+  // ⚠️ Windows 上**不要用 symlinkSync(...,'dir')**：非特权进程下它产不出可用链接，
+  //    而且抛不抛错不确定、失败时还会留下空目录残留 —— 兜底链会因此整条失效（实测）。
+  //    junction（目录联接）免特权、realpath 正确、require.resolve 与 ESM 裸包名解析都正常。
+  const attempts = process.platform === "win32"
+    ? [
+        ["junction", () => fs.symlinkSync(path.resolve(pluginLocalDir), nmPlugin, "junction")], // junction 只接受绝对路径
+        ["copy", () => fs.cpSync(pluginLocalDir, nmPlugin, { recursive: true })],
+      ]
+    : [
+        ["dir", () => fs.symlinkSync(pluginLocalDir, nmPlugin, "dir")],
+        ["copy", () => fs.cpSync(pluginLocalDir, nmPlugin, { recursive: true })],
+      ];
+
+  const failures = [];
+  for (const [how, run] of attempts) {
+    // 每支开始前先清残留：上一支"没抛错但留了个空目录"时，不清就会让下一支撞 EEXIST 而失败
+    //（这正是原实现三级兜底退化成一级的原因）。
+    try { fs.rmSync(nmPlugin, { recursive: true, force: true }); } catch { /* ignore */ }
+    let err = null;
+    try { run(); } catch (e) { err = e; }
+    if (pluginLinkUsable(nmPlugin, pluginLocalDir)) return true;
+    failures.push(`${how}: ${err ? err.message : "未抛错但落盘结果不可用（读不到 package.json / lib/index.js）"}`);
+  }
+  throw new Error(`插件挂载失败：${nmPlugin}\n   ${failures.join("\n   ")}`);
+}
+
+
+/**
+ * 独立验收：复刻 dsh 客户端模块系统的真实动作 —— 从 profile 目录按**裸包名**解析到本插件。
+ *
+ * 与 pluginLinkUsable 是两道独立的闸门：前者看文件在不在、是不是真指向目标；
+ * 这条走 Node 的解析器（exports 字段、symlink 跟随、pnpm 布局），是"面板能不能被注入"的前提
+ * （@deepseek-ai/dsh-client-modules 就是 require.resolve('<name>/package.json') 读 dsh.client）。
+ */
+function probePluginResolve(profileDir) {
+  const base = path.join(profileDir, "__dsh_resolve_probe.cjs");
+  // 必须**另起一个 node 进程**做这次解析，不能在本进程里 require.resolve：
+  // 实测（Node 25 / macOS）：本进程里只要先失败过一次裸包名解析（例如"修复前诊断"那次），
+  // 链接随后修好了，同一个进程里的裸包名解析**仍会持续失败**（子路径却正常）——
+  // 进程内的解析缓存会把假阴性一直带下去，让"修复后验收"误判成没修好、拒绝恢复激活。
+  // 另起进程同时也更忠实：dsh 启动时就是在一个全新进程里解析这些裸包名的。
+  const script = [
+    'const { createRequire } = require("node:module");',
+    `const req = createRequire(${JSON.stringify(base)});`,
+    "process.stdout.write(JSON.stringify({",
+    `  pkgPath: req.resolve(${JSON.stringify(`${PLUGIN_ID}/package.json`)}),`,
+    `  entry: req.resolve(${JSON.stringify(PLUGIN_ID)})`,
+    "}));",
+  ].join("\n");
   try {
-    if (fs.realpathSync(nmPlugin) === pluginLocalDir) return false;
-  } catch { /* 缺失/悬空 → 重建 */ }
-  try { fs.rmSync(nmPlugin, { recursive: true, force: true }); } catch { /* ignore */ }
-  try {
-    fs.symlinkSync(pluginLocalDir, nmPlugin, "dir");
-  } catch {
-    fs.cpSync(pluginLocalDir, nmPlugin, { recursive: true });
+    const r = spawnSync(process.execPath, ["-e", script], { encoding: "utf8", timeout: 30_000, windowsHide: true });
+    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)) || "解析失败";
+      return { ok: false, reason: line.trim().slice(0, 200) };
+    }
+    const out = JSON.parse(String(r.stdout || "{}"));
+    const pkg = JSON.parse(fs.readFileSync(out.pkgPath, "utf8"));
+    return {
+      ok: true,
+      pkgPath: out.pkgPath,
+      entry: out.entry,
+      name: pkg.name,
+      clientPlatform: (pkg.dsh && pkg.dsh.client && pkg.dsh.client.platform) || "",
+    };
+  } catch (e) {
+    return { ok: false, reason: `${e.code || e.name}: ${e.message}` };
   }
-  try { return fs.realpathSync(nmPlugin) === pluginLocalDir; } catch { return false; }
+}
+
+/**
+ * 描述插件在 profile 里的挂载形态（供 status / repair 输出）。
+ * 用户报障时这三行就能区分"链接坏了"与"别的毛病"——不必再靠猜。
+ * @returns {{localExists:boolean, exists:boolean, usable:boolean, kind:"missing"|"broken"|"linked"|"copy"|"no-local-copy"}}
+ */
+function describePluginLink(profileDir) {
+  const nmPlugin = path.join(profileDir, "node_modules", PLUGIN_ID);
+  const localDir = path.join(profileDir, PLUGIN_LOCAL_DIR);
+  const localExists = fs.existsSync(path.join(localDir, "package.json"));
+  if (!fs.existsSync(nmPlugin)) return { localExists, exists: false, usable: false, kind: localExists ? "missing" : "no-local-copy" };
+  const usable = pluginLinkUsable(nmPlugin, localDir);
+  let isLink = false;
+  try { isLink = fs.lstatSync(nmPlugin).isSymbolicLink(); } catch { /* ignore */ }
+  return { localExists, exists: true, usable, kind: usable ? (isLink ? "linked" : "copy") : "broken" };
 }
 
 /** package.json 写入 file: 依赖(让后续任何 pnpm/npm install 也认可该插件,不会删链接)。 */
@@ -1244,8 +1674,26 @@ function activateLocalCopy(profileDir, pkgFile, patchFile, pluginDir, patch, pkg
     console.error(`❌ 插件入口缺失：${entryFile}（本包不完整？请用官方源重装：npx --registry=https://registry.npmjs.org @mrrisega/dsh-remote@latest）`);
     process.exit(1);
   }
+  // ⚠️ 顺序与"失败即中止"都是刻意的（0.6.7-beta.1 Windows 实测事故）：
+  //   老代码把 ensurePluginLinked 的返回值丢掉、patch 照写、还打印「✅ 插件已就绪」，
+  //   于是用户拿到的是**起不来的 dsh web**（cordis 按裸包名解析到空目录 → plugin tree failed to load，
+  //   整个 dsh web 启动失败，而面板/插件市场都在那个进程里 → 用户没有任何自助修复入口）。
+  //   现在：先挂载 → 独立验收 → 才写依赖与激活行；任何一步不过就中止，绝不留下坏 profile。
+  try {
+    ensurePluginLinked(profileDir, pluginLocalDir);   // node_modules 链接(name 才能被解析)
+  } catch (e) {
+    console.error(`❌ ${e.message}`);
+    console.error("   已中止安装：继续写 patch 会让 dsh web 因插件树加载失败而完全无法启动。");
+    console.error("   请把上面的错误整段反馈给作者（含平台 / 是否管理员 / 开发者模式是否开启）。");
+    process.exit(1);
+  }
+  const probe = probePluginResolve(profileDir);
+  if (!probe.ok) {
+    console.error(`❌ 验收失败：dsh 无法从 profile 按裸包名解析 ${PLUGIN_ID}（${probe.reason}）`);
+    console.error("   已中止安装（未写 patch）：否则 dsh web 会因插件树加载失败而完全无法启动。");
+    process.exit(1);
+  }
   declarePluginDep(pkgFile);                        // file: 依赖(包管理器 install 不误删)
-  ensurePluginLinked(profileDir, pluginLocalDir);    // node_modules 链接(name 才能被解析)
   const r = ensurePatchActivation(patchFile, pluginLocalDir, pkgFile, { forcePatch: !!opts.forcePatch });
   if (r.ok) {
     console.log(`✅ 插件已就绪: ${pluginLocalDir}${opts.forcePatch ? "（激活点已转为 patch 行，装完即热加载）" : ""}`);
@@ -1282,6 +1730,34 @@ function readInstalledPluginVersion(profileDir, name) {
   } catch { return null; }
 }
 
+/**
+ * 识别 profile 用哪个包管理器（市场装法「一键更新」要用它改源码）。
+ *
+ * ⚠️ 不能用 `sh("command -v pnpm && echo pnpm || echo npm")`：`sh()` 走 execSync，
+ * Windows 下是 cmd.exe，而 `command` 是 POSIX 内建 → 永远命中 `||` 分支，
+ * **Windows 上永远选 npm**。而 dsh profile 是 pnpm 管理的（pnpm-workspace.yaml + 虚拟 store），
+ * 用 npm 去改同一个 node_modules 会写出与 pnpm 不同的布局（污染/冲突风险）。
+ * 现在：先用**声明文件**判断（最可靠、零子进程），再用 where/which 探测可执行文件；
+ * 兜底选 pnpm 而不是 npm —— dsh profile 默认就是 pnpm，选错方向的代价不对称。
+ */
+function detectPackageManager(profileDir) {
+  try {
+    if (fs.existsSync(path.join(profileDir, "pnpm-lock.yaml"))
+      || fs.existsSync(path.join(profileDir, "pnpm-workspace.yaml"))) return "pnpm";
+    if (fs.existsSync(path.join(profileDir, "package-lock.json"))) return "npm";
+  } catch { /* 读不到就往下探测 */ }
+  const has = (bin) => {
+    try {
+      return process.platform === "win32"
+        ? spawnSync("where", [bin], { stdio: "ignore", windowsHide: true }).status === 0
+        : spawnSync("sh", ["-c", `command -v ${bin}`], { stdio: "ignore" }).status === 0;
+    } catch { return false; }
+  };
+  if (has("pnpm")) return "pnpm";
+  if (has("npm")) return "npm";
+  return "pnpm";
+}
+
 /**
  * 市场装法下把插件包升到最新。
  *
@@ -1295,7 +1771,7 @@ function readInstalledPluginVersion(profileDir, name) {
 function upgradeMarketManagedPlugin(profileDir, name, dep) {
   const spec = String(dep ?? "").trim();
   const isRegistryRange = /^[\^~><=v\d]/.test(spec);
-  const pm = sh("command -v pnpm >/dev/null 2>&1 && echo pnpm || echo npm").stdout.trim() || "npm";
+  const pm = detectPackageManager(profileDir);
   const args = isRegistryRange ? `add ${name}@latest` : `update ${name}`;
   const cmd = `${pm} ${args}`;
   const r = sh(cmd, 180000, profileDir);
@@ -1414,8 +1890,90 @@ async function pluginCmd(argv) {
   // 引导语只在 setup 汇总里打印一次(这里不再重复;单独跑 `dsh-remote plugin` 也无需引导)
 }
 
+/**
+ * 打印插件挂载诊断三行（供 status / repair 共用）。
+ * 用户报障时这三行就能区分「链接坏了」与「别的毛病」，不必靠猜：
+ *   link = 有没有真挂上（junction / 符号链接 / 整目录拷贝 / BROKEN）
+ *   resolve = dsh 的裸包名解析能不能走通（浏览器半注入面板就靠它）
+ *   client = dsh.client.platform 声明在不在
+ */
+function printPluginDiagnostics(profileDir) {
+  const nmPlugin = path.join(profileDir, "node_modules", PLUGIN_ID);
+  const link = describePluginLink(profileDir);
+  const probe = probePluginResolve(profileDir);
+  const kindText = { linked: "已挂载（链接）", copy: "已挂载（整目录拷贝）", broken: "BROKEN（存在但读不到内容）", missing: "缺失", "no-local-copy": "缺失（本地插件目录也没有）" }[link.kind] || link.kind;
+  console.log(`   [link]    ${nmPlugin}\n             → ${kindText}`);
+  console.log(`   [resolve] ${PLUGIN_ID}/package.json → ${probe.ok ? probe.pkgPath : `失败（${probe.reason}）`}`);
+  console.log(`   [client]  dsh.client.platform = ${probe.ok ? (probe.clientPlatform || "缺失") : "（解析失败，无法确认）"}`);
+  return { link, probe };
+}
+
+/**
+ * `dsh-remote repair` —— 只修 profile 里的插件挂载，不碰运行环境 / 不联网 / 不碰自启动。
+ *
+ * 为什么需要这个独立入口：插件挂载坏掉时 dsh web **整个起不来**（cordis 插件树加载失败），
+ * 而设置面板与插件市场都在那个进程里 —— 用户没有任何自助修复入口，只剩命令行。
+ * 执行顺序刻意是"先保命、再修复、最后恢复激活"：
+ *   ① patch 里引用了本插件但挂载不可用 → **先把 include 摘掉**（profile 立刻恢复可启动）；
+ *   ② 再重建挂载（失败会抛错，但①的结果保留 → 用户至少能打开 dsh web）；
+ *   ③ 只有①②都成功，才把激活行写回去。
+ */
+function repairProfile(argv = []) {
+  const profileDir = resolveProfileDir(argv);
+  const pkgFile = path.join(profileDir, "package.json");
+  const patchFile = path.join(profileDir, "cordis.patch.yml");
+  const localDir = path.join(profileDir, PLUGIN_LOCAL_DIR);
+  if (!fs.existsSync(pkgFile) || !fs.existsSync(patchFile)) {
+    console.error(`❌ 未找到 dsh web profile（${profileDir}）。`);
+    console.error("   先确认 dsh web 装好并初始化过 profile，或用 --profile <目录> 指定。");
+    process.exit(1);
+  }
+  console.log(`dsh-remote repair — ${profileDir}`);
+  const before = printPluginDiagnostics(profileDir);
+  if (!before.link.localExists) {
+    console.error(`❌ 本地插件目录缺失（${localDir}）：无法就地修复。`);
+    console.error("   请重新安装：npx @mrrisega/dsh-remote@latest");
+    process.exit(1);
+  }
+
+  const patch = fs.readFileSync(patchFile, "utf8");
+  const referenced = parsePatchInsertIds(patch).ids.some((id) => PLUGIN_ALL_IDS.includes(id));
+  if (referenced && !before.link.usable) {
+    // 保命动作：先摘掉激活行，让 dsh web 至少能启动（此时插件不可用，但用户进得去、能重装）
+    stripIncludeEntries(patchFile, patch, "挂载不可用，先摘掉 include 保命");
+    try { removeBundleEntry(pkgFile); } catch { /* ignore */ }
+    console.log("🛟 挂载不可用 → 已先摘掉插件激活行（dsh web 现在应该能启动了）。");
+  }
+
+  try {
+    ensurePluginLinked(profileDir, localDir);
+  } catch (e) {
+    console.error(`❌ 重建挂载失败：${e.message}`);
+    console.error("   profile 已处于「能启动、插件未激活」状态；请把上面错误反馈给作者。");
+    process.exit(1);
+  }
+  const after = printPluginDiagnostics(profileDir);
+  if (!after.probe.ok) {
+    console.error("❌ 挂载已重建，但 dsh 仍解析不到本插件 —— 请把上面的输出反馈给作者。");
+    process.exit(1);
+  }
+  const srcPluginDir = path.join(THIS_DIR, "packages", PLUGIN_ID);
+  if (!fs.existsSync(srcPluginDir)) {
+    console.error(`❌ 本包缺少 packages/${PLUGIN_ID}，无法就地恢复激活行。`);
+    console.error("   请重新安装：npx @mrrisega/dsh-remote@latest");
+    process.exit(1);
+  }
+  convergePluginActivation(profileDir, pkgFile, patchFile, srcPluginDir, fs.readFileSync(patchFile, "utf8"));
+  console.log("✅ 挂载与激活已修复 —— 重启一次 dsh web 生效。");
+}
+
 // ---------- main ----------
-// 无命令名（或首个参数以 - 开头）时默认执行 setup
+// 无命令名（或首个参数以 - 开头）时默认执行 setup —— 这样 `dsh-remote --no-autostart`
+// 这类「只给 flag」的用法才能装上去。
+//
+// 但有两个例外必须挡在前面：
+//   ① -h/--help：用户想先看用法,绝不该顺手把东西装上(此前会走 setup,直接安装);
+//   ② 不认识的 flag：拼错参数时静默安装比报错更糟,宁可停下来说清楚。
 const raw = process.argv[2];
 const cmd = raw && !raw.startsWith("-") ? raw : "setup";
 const args = raw && !raw.startsWith("-") ? process.argv.slice(3) : process.argv.slice(2);
@@ -1423,6 +1981,7 @@ if (cmd === "setup" || cmd === "install") await setup(args);
 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 === "status") {
   const cfg = loadConfig();
   const local = Boolean(cfg.local_key);
@@ -1430,22 +1989,15 @@ else if (cmd === "status") {
   console.log("连接模式:", local ? `自建服务（${cfg.tunnel_url || "未设置服务器地址"}）` : `SaaS 云端服务（${cfg.phone || "未配置账号"}）`);
   console.log("API:", cfg.api_url || (local ? "（自建模式无需账号 API）" : DEFAULT_API));
   console.log("远程地址/登录: 打开 dsh web → 设置 → 「远程控制」查看与操作");
+  // 插件挂载诊断：报障时一眼看出是"链接坏了"还是"别的毛病"
+  const profileDir = resolveProfileDir([]);
+  if (fs.existsSync(path.join(profileDir, "package.json"))) {
+    console.log("插件挂载:");
+    printPluginDiagnostics(profileDir);
+  } else {
+    console.log(`插件挂载: 未找到 profile（${profileDir}）`);
+  }
 } else {
-  console.log(`dsh-remote — 手机远程控制 dsh web（隧道模式）
-
-用法:
-  dsh-remote              一键安装（默认命令，无需任何参数；含插件与自启动）
-  dsh-remote settings     显示登录/连接配置指引（独立设置页已移除）
-  dsh-remote run          前台运行 bridge（调试）
-  dsh-remote status       查看配置与服务状态
-  dsh-remote plugin       手动安装 dsh web 远程控制插件（--uninstall 卸载）
-
-自建模式（可选）:
-  dsh-remote setup --server wss://你的域名:端口 --key 访问密钥
-
-登录/连接配置: 打开 dsh web → 设置 → 「远程控制」→ 注册或登录手机号即可
-（自建用户切「自建服务」标签或直接用上方 setup 命令，无需另开页面）。
-文档: ${REPO_URL}
-`);
-  process.exit(cmd === "help" ? 0 : 1);
+  printHelp();
+  process.exit(1);
 }