@mrrisega/dsh-remote 0.6.14 → 0.6.16

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

@@ -170,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）
 
 自建模式（可选）:
@@ -202,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() {
@@ -764,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} 不支持自启动` };
 }
@@ -2332,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);
@@ -2417,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/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, /为什么连不上/, "要一句话说清它是干什么的");
+});