@guowenzhang/dsh-pocket 0.0.0-stage → 2.12.2

package/lib/restart.js

@@ -0,0 +1,118 @@
+// dsh-pocket 自重启：重新拉起启动本宿主的确切 dsh 调用（detached 交接），
+// 让更新后的插件代码生效——用户无需离开界面手动重启。
+//
+// 方案借鉴 dshmarket 的 self-restart（lib/restart.js，MIT）：不直接拉起新
+// 进程，而是先拉一个 detached 的 node 辅助进程，等旧进程退出、端口释放
+// 后再拉起新 dsh，并把新进程输出写入临时日志——避免端口竞争
+// （EADDRINUSE）导致新进程静默崩溃。
+//
+// 与 dshmarket 的差异：不赌固定 1.5s 延时，而是轮询探测端口真正释放
+// （ECONNREFUSED）再拉起，旧进程退出慢也不会撞端口。
+//
+// 注意：新进程 detached，不挂终端——停止方式：lsof -ti :3080 | xargs kill -9。
+
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** 从启动参数里解析 dsh web 端口（--port/-p，含 --port=3080 形式），默认 3080。 */
+export function dshPortFromArgs(args) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--port' || a === '-p') {
+      const n = Number(args[i + 1]);
+      if (Number.isInteger(n) && n > 0 && n < 65536) return n;
+    } else if (a.startsWith('--port=')) {
+      const n = Number(a.slice('--port='.length));
+      if (Number.isInteger(n) && n > 0 && n < 65536) return n;
+    }
+  }
+  return 3080;
+}
+
+/** 重建启动调用（与当前宿主相同的命令，含 node 运行参数）。 */
+export function restartLaunch() {
+  return {
+    file: process.argv[0], // node
+    args: [...process.execArgv, process.argv[1], ...process.argv.slice(2)], // [flags] <bin.js> + web [flags]
+    cwd: process.cwd(),
+  };
+}
+
+/** 辅助进程代码：等 dsh 端口真正释放（最多 20s）→ 拉起新 dsh → 输出写日志。 */
+function helperCode(launch, logOut, logErr, port) {
+  const spawn = "const { spawn } = require('node:child_process')";
+  const fs = "const fs = require('node:fs')";
+  const net = "const net = require('node:net')";
+  const file = `const file = ${JSON.stringify(launch.file)}`;
+  const args = `const args = ${JSON.stringify(launch.args)}`;
+  const cwd = `const cwd = ${JSON.stringify(launch.cwd)}`;
+  const o = `const logOut = ${JSON.stringify(logOut)}`;
+  const e = `const logErr = ${JSON.stringify(logErr)}`;
+  const body = [
+    'function portFree(p, cb) {',
+    '  const s = net.connect(p, "127.0.0.1")',
+    '  s.once("connect", () => { s.destroy(); cb(false) })', // 还能连上 = 端口仍被占用
+    '  s.once("error", () => cb(true))',                      // 连接被拒 = 已释放
+    '}',
+    'function waitPort(p, tries, cb) {',
+    '  portFree(p, (free) => {',
+    '    if (free || tries <= 0) cb(free)',
+    '    else setTimeout(() => waitPort(p, tries - 1, cb), 200)',
+    '  })',
+    '}',
+    `waitPort(${port}, 100, (free) => {`, // 最多 100×200ms = 20s；超时也照常拉起（宁可试拉、日志留痕，也不让 dsh 起不来）
+    '  setTimeout(() => {',
+    '    try {',
+    '      const out = fs.openSync(logOut, "a")',
+    '      const err = fs.openSync(logErr, "a")',
+    '      const child = spawn(file, args, { cwd, detached: true, stdio: ["ignore", out, err], env: process.env })',
+    '      child.unref()',
+    '    } catch (ex) {',
+    '      try { fs.appendFileSync(logErr, "restart helper failed: " + (ex && ex.message) + "\\n") } catch {}',
+    '    }',
+    '  }, 300)',
+    '})',
+  ].join('\n');
+  return [spawn, fs, net, file, args, cwd, o, e, body].join('\n');
+}
+
+/**
+ * 拉起替代宿主（detached 辅助进程交接），随后结束当前进程。
+ * @param {object} opts
+ * @param {number} [opts.handoffMs] 保留参数（兼容旧调用；现由端口探测接管）
+ * @param {object} [opts.internals] 测试注入：spawn / kill
+ * @returns {{helperPid:number|null, logOut:string, logErr:string}}
+ */
+export function restartHost({ handoffMs = 1500, internals = {} } = {}) {
+  const spawnFn = internals.spawn ?? spawn;
+  const killFn = internals.kill ?? ((pid) => process.kill(pid, 'SIGTERM'));
+  // Electron 桌面宿主里 pocket 跑在 Electron 的 node 上下文：杀 process.pid 会杀掉宿主，
+  // 并由 detached 孤儿进程抢宿主端口（19387）→ EADDRINUSE 崩溃循环（issue #177 / #167）。
+  // 桌面端应由 DSH Desktop 自己管理重启，这里直接拒绝，交还控制权。
+  if (Boolean(process.versions.electron) && internals.spawn === undefined) {
+    return { helperPid: null, logOut: '', logErr: '', error: 'desktop-host-restart-not-supported' };
+  }
+  const launch = restartLaunch();
+  const port = dshPortFromArgs(launch.args);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const logOut = join(tmpdir(), `dsh-pocket-restart-${stamp}.out.log`);
+  const logErr = join(tmpdir(), `dsh-pocket-restart-${stamp}.err.log`);
+
+  let helperPid = null;
+  try {
+    const helper = spawnFn(process.execPath, ['-e', helperCode(launch, logOut, logErr, port)], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
+    helper.unref?.();
+    helper.on?.('error', () => {}); // 参数异常等异步错误兜底，别让旧进程先崩
+    helperPid = helper.pid ?? null;
+    // 短暂等待后结束当前进程（释放端口）；由辅助进程探测到端口释放后拉起新宿主
+    setTimeout(() => { try { killFn(process.pid); } catch { /* 忽略 */ } }, 500);
+  } catch (err) {
+    return { helperPid: null, logOut, logErr, error: err?.message ?? String(err) };
+  }
+  return { helperPid, logOut, logErr };
+}

package/lib/service.mjs

@@ -0,0 +1,454 @@
+// dsh-pocket 服务：在 dsh web 进程内跑改头代理 + 公网隧道
+//
+// - 代理：监听 0.0.0.0:<port>（默认 3081），把入站 Host/Origin 改写成
+//   127.0.0.1:<dshPort>（dsh web 实际端口），HTTP + WebSocket 全透传。
+//   这样 DSH 的 /api 浏览器信任栅栏永远看到 loopback，局域网/公网都能进，
+//   且不需要改 dsh 的任何配置（0.0.0.0 绑定被 dsh 官方禁用）。
+// - 隧道：cloudflared 快速隧道（可选），公网 https URL，供人在外面访问。
+
+import { networkInterfaces } from 'node:os';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { createPocketProxy } from './proxy.mjs';
+import { startQuickTunnel, startNamedTunnel } from './tunnel.mjs';
+import { isValidIpv4 } from './ip.mjs';
+
+const require = createRequire(import.meta.url);
+
+/** URL → 二维码 data URL（浏览器 <img> 直接显示，全本地不依赖第三方）。 */
+export async function qrDataUrl(text, { width = 220, margin = 1 } = {}) {
+  const QRCode = require('qrcode');
+  return QRCode.toDataURL(text, { errorCorrectionLevel: 'M', margin, width, type: 'image/png' });
+}
+
+// RFC1918 私网地址：手机与电脑连同一局域网时通常可直连。
+// 另含 CGNAT 100.64/10（RFC 6598，Tailscale/ZeroTier 默认网段，公网不可路由），保持一致（issue #79）。
+const PRIVATE_IPV4_RE = /^(?:10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|100\.(?:6[4-9]|[7-9]\d|1(?:0\d|1\d|2[0-7]))\.)/;
+
+/** 名称像真实物理网卡的接口（WLAN / Wi-Fi / Ethernet / 以太网 / 有线 / 无线 / en / eth）。
+ *  注意：`本地连接` 用负前瞻 `(?!\*)` 排除 Windows 的「移动热点 / Internet 连接共享（ICS）」
+ *  虚拟适配器 `本地连接* N`（IP 固定 192.168.137.1，手机连真实 Wi-Fi 时与它不在同一网段，
+ *  扫码不可达）——issue #176。 */
+const PHYSICAL_IFACE_RE = /^(?:wlan|wi-?fi|wireless|ethernet|eth\d|en\d|wlp\d|以太网|有线|无线|本地连接(?!\*))/i;
+
+/** 常见的 VPN / 虚拟网卡名称：手机通常无法通过它们直连电脑。
+ *  含 Windows ICS / 移动热点（`本地连接*`）与承载网络 / Wi-Fi Direct 虚拟适配器——issue #176。 */
+const VPN_IFACE_RE = /(?:radmin|tailscale|zerotier|easytier|et_|tun|tap|vpn|vethernet|virtual|vmware|virtualbox|wsl|docker|teredo|hamachi|bluetooth|bridge|本地连接\*|hostednetwork|wifidirect)/i;
+
+/**
+ * 从 networkInterfaces() 返回的接口表里选出手机最可能可达的 IPv4。
+ *
+ * `os.networkInterfaces()` 的枚举顺序不可靠：Windows 上 Radmin VPN / Tailscale /
+ * vEthernet 等虚拟网卡常排在 WLAN 前面，旧实现直接取第一张非回环网卡，会生成
+ * 手机打不开的二维码。这里按以下规则打分排序：
+ *   - RFC1918 私网地址优先（10/8、172.16/12、192.168/16）；
+ *   - 名称像物理网卡再加分；
+ *   - 名称像 VPN/虚拟网卡减分；
+ *   - 同分保持原枚举顺序。
+ * 没有任何私网地址时回退到最高分地址（例如纯 VPN 环境仍可用）。
+ *
+ * @param {ReturnType<typeof networkInterfaces>} interfaces
+ * @returns {string|null}
+ */
+export function selectLanIPv4(interfaces) {
+  const candidates = [];
+  for (const [name, addrs] of Object.entries(interfaces ?? {})) {
+    for (const addr of addrs ?? []) {
+      if (addr.family !== 'IPv4' || addr.internal) continue;
+      const ip = addr.address;
+      // 排除 loopback 与 link-local；其余地址即使不是私网（如 Radmin 的 26.x）也保留兜底
+      if (!ip || ip.startsWith('127.') || ip.startsWith('169.254.')) continue;
+
+      let score = 0;
+      if (PRIVATE_IPV4_RE.test(ip)) score += 100;
+      if (PHYSICAL_IFACE_RE.test(name)) score += 20;
+      else if (VPN_IFACE_RE.test(name)) score -= 50;
+
+      candidates.push({ ip, score, order: candidates.length });
+    }
+  }
+
+  // 兜底：同分时不选 ICS 保留段 192.168.137.x（移动热点 / 共享虚拟网卡），避免误指向不可达地址。
+  const isIcsSubnet = (ip) => ip.startsWith('192.168.137.');
+  candidates.sort((a, b) =>
+    b.score - a.score ||
+    (isIcsSubnet(a.ip) === isIcsSubnet(b.ip) ? a.order - b.order : isIcsSubnet(a.ip) ? 1 : -1),
+  );
+  return candidates[0]?.ip ?? null;
+}
+
+// ---------- WSL 局域网 IP（issue #39） ----------
+// WSL2 是 NAT 模式：WSL 内部 os.networkInterfaces() 只能看到自己的虚拟网卡
+// （172.x.x.x），看不到 Windows 宿主机的物理网卡 IP（192.168.x.x）——手机在
+// 同一 WiFi 下访问的是 Windows 宿主机，拿 WSL 的 IP 生成的二维码必然打不开。
+// 解法：检测到 WSL 时，通过 WSL interop 直接执行 Windows 的 ipconfig.exe，
+// 解析出 Windows 侧非虚拟网卡的 IPv4 作为局域网地址；失败回退本机探测。
+
+/** WSL 检测：/proc/version 含 microsoft/wsl，或 WSL 专属环境变量存在。 */
+export function detectWsl() {
+  try {
+    const v = readFileSync('/proc/version', 'utf8').toLowerCase();
+    if (v.includes('microsoft') || v.includes('wsl')) return true;
+  } catch { /* 非 Linux：无 /proc/version */ }
+  // 注意：**不能**用 WSLENV 判据——Windows Terminal 在原生 Windows 上也会设置
+  // WSLENV（如 WT_SESSION:WT_PROFILE_ID:），会误判成 WSL。只认 WSL 内部才有的变量。
+  return Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+}
+
+/**
+ * 解析 ipconfig.exe 输出，默认取非虚拟网卡块的 IPv4 地址（保持输出顺序）。
+ * 支持中文（`IPv4 地址 . . . :`）与英文（`IPv4 Address. . . :`）两种格式。
+ * @param {string} text ipconfig.exe 的完整输出
+ * @param {{ includeVpn?: boolean }} [opts] 传 includeVpn 时保留 Tailscale/VPN 等候选
+ * @returns {string[]} 候选 IPv4 列表
+ */
+export function parseIpconfig(text, { includeVpn = false } = {}) {
+  const out = [];
+  // 网卡块：块标题行顶格（行首无缩进），其后内容行带缩进
+  const blocks = String(text).split(/\r?\n(?=\S)/);
+  const ipRe = /IPv4[^0-9]{0,40}((?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)/;
+  for (const block of blocks) {
+    const title = String(block.split(/\r?\n/)[0] ?? '');
+    // 跳过虚拟网卡块（vEthernet (WSL)、Docker、VirtualBox、VPN 等）
+    if (!includeVpn && VPN_IFACE_RE.test(title)) continue;
+    const m = block.match(ipRe);
+    if (m) out.push(m[0].replace(/^IPv4[^0-9]*/i, ''));
+  }
+  return out;
+}
+
+function runIpconfig() {
+  // WSL 内 PATH 可能不含 Windows System32；用绝对路径兜底
+  const candidates = ['ipconfig.exe', '/mnt/c/Windows/System32/ipconfig.exe'];
+  return new Promise((resolve) => {
+    const tryNext = (i) => {
+      if (i >= candidates.length) return resolve(null);
+      execFile(candidates[i], [], { timeout: 5000, windowsHide: true }, (err, stdout) => {
+        if (err || !stdout) return tryNext(i + 1);
+        resolve(String(stdout));
+      });
+    };
+    tryNext(0);
+  });
+}
+
+async function lanIPv4() {
+  // WSL：优先 Windows 物理网卡 IP（手机可达）；超时/失败回退本机探测
+  if (detectWsl()) {
+    try {
+      const out = await runIpconfig();
+      const candidates = parseIpconfig(out ?? '');
+      const ip = candidates.find((c) => PRIVATE_IPV4_RE.test(c)) ?? candidates[0];
+      if (ip) return ip;
+    } catch { /* 回退 */ }
+  }
+  return selectLanIPv4(networkInterfaces());
+}
+
+/** 收集所有可手动选择的局域网/Tailnet 候选 IP（WSL 下以 Windows ipconfig 为准）。 */
+async function listLanCandidates() {
+  if (detectWsl()) {
+    try {
+      const out = await runIpconfig();
+      const ips = parseIpconfig(out ?? '', { includeVpn: true });
+      if (ips.length) return [...new Set(ips)];
+    } catch { /* 回退 */ }
+  }
+  const ips = [];
+  for (const [name, addrs] of Object.entries(networkInterfaces())) {
+    for (const addr of addrs ?? []) {
+      if (addr.family !== 'IPv4' || addr.internal) continue;
+      const ip = addr.address;
+      if (!ip || ip.startsWith('127.') || ip.startsWith('169.254.')) continue;
+      if (!ips.includes(ip)) ips.push(ip);
+    }
+  }
+  return ips;
+}
+
+/**
+ * 创建 Pocket 服务。
+ * @param {object} opts
+ * @param {number} opts.dshPort   dsh web 实际端口（从 ctx.webServer.port 取）
+ * @param {number} [opts.port]    代理端口（默认 3081）
+ * @param {object} [opts.internals] 测试注入：createProxy / startTunnel / lanIPv4
+ * @returns {PocketService}
+ */
+export function createPocketService({
+  dshPort,
+  port = 3081,
+  home,
+  internals = {},
+  /** 局域网地址手动覆盖：返回 IPv4 字符串；空值表示自动选择 */
+  getLanIpOverride,
+  /** 局域网访问总开关：返回 boolean；默认开启。关闭后代理拒绝局域网 Host 请求 */
+  getLanEnabled = () => true,
+  /** 代理注入 HTML 的内容（桌面端补丁等由 lib/index.js 传入；默认 randomUUID polyfill） */
+  injectHtml,
+  /** 访问令牌认证配置（issue #13）：{ getToken, isProtected }，传给代理 */
+  auth,
+  /** @type {() => string} dsh web 浏览器会话启动 token（issue #77；老版本返回空字符串） */
+  launchToken = () => '',
+  /** 隧道配置（issue #66）：() => ({ mode:'quick'|'named', token, hostname })；named 用固定域名 */
+  getTunnelConfig,
+  /** 隧道就绪回调（lib/index.js 用它轮换公网密码；参数为 'quick'|'named'） */
+  onTunnelReady,
+  /** 日志（DSH 宿主 ctx.logger 有 info/warn/error；默认 console 无 info，自动退回 log）。
+   *  隧道自动恢复的成败必须走这里：console 输出在 DSH Desktop 里不进日志文件，
+   *  出问题时无法排查（2026-09-07 实测教训）。 */
+  log = console,
+} = {}) {
+  // ctx.logger 形状是 info/warn/error；console 只有 log/warn/error——info 做兜底兼容
+  const logInfo = (...args) => (log.info ?? log.log).call(log, ...args);
+  const logWarn = (...args) => log.warn(...args);
+  const createProxy = internals.createProxy ?? createPocketProxy;
+  const startTunnel = internals.startTunnel ?? startQuickTunnel;
+  const startNamed = internals.startNamedTunnel ?? startNamedTunnel;
+  const getLanOverride = () => {
+    const value = String(getLanIpOverride?.() ?? '').trim();
+    return isValidIpv4(value) ? value : '';
+  };
+  const getLan = async () => getLanOverride() || (internals.lanIPv4 ? internals.lanIPv4() : lanIPv4());
+  let lanCandidateCache = null;
+  const getLanCandidates = async () => {
+    if (internals.lanCandidates) return internals.lanCandidates();
+    const now = Date.now();
+    if (!lanCandidateCache || now - lanCandidateCache.at > 15000) {
+      lanCandidateCache = { at: now, ips: await listLanCandidates() };
+    }
+    return lanCandidateCache.ips;
+  };
+
+  let proxy = null;
+  let tunnel = null;
+  let tunnelAbort = null;
+  /** in-flight 隧道启动（单飞）：并发调用复用同一次，避免 spawn 多个 cloudflared 孤儿进程 */
+  let tunnelPromise = null;
+  /** 隧道进度：{ phase: idle|downloading|starting|registering|ready|error, detail, startedAt } */
+  const tunnelState = { phase: 'idle', detail: '', startedAt: null };
+  /** 二维码缓存：URL → data URL promise。status() 每 3 秒轮询一次，不能每次都重新生成（CPU 密集）。 */
+  const qrCache = new Map();
+  const encodeQr = internals.encodeQr ?? qrDataUrl;
+  async function qrCached(text) {
+    if (!text) return null;
+    if (!qrCache.has(text)) {
+      if (qrCache.size >= 8) {
+        // 只淘汰最旧一条（隧道 URL 每次重启换新），别殃及稳定的 LAN 二维码
+        const oldest = qrCache.keys().next().value;
+        qrCache.delete(oldest);
+      }
+      qrCache.set(text, encodeQr(text).catch(() => null));
+    }
+    return qrCache.get(text);
+  }
+
+  // 公网隧道自动恢复（issue #11）：DSH 重启后 cloudflared 子进程被杀、隧道消失，
+  // 插件无从知晓。启动时检查持久化的「隧道开启中」标记，自动重新拉起。
+  const autoStatePath = home ? join(home, 'dsh-pocket', 'tunnel-auto.json') : null;
+  // 写入与删除必须串行：隧道刚就绪就立即关闭时，异步写不能晚于删除重新落盘，
+  // 否则标记被晚到的写操作复活，下次启动误恢复（writeFile 与 rm 的完成顺序不保证）。
+  let autoStateQueue = Promise.resolve();
+  function persistAutoTunnel() {
+    if (!autoStatePath) return;
+    autoStateQueue = autoStateQueue.then(async () => {
+      try {
+        await mkdir(dirname(autoStatePath), { recursive: true });
+        await writeFile(autoStatePath, JSON.stringify({ at: Date.now() }), 'utf8');
+      } catch { /* 忽略 */ }
+    });
+    return autoStateQueue;
+  }
+  function clearAutoTunnel() {
+    if (!autoStatePath) return;
+    autoStateQueue = autoStateQueue.then(async () => {
+      try { await rm(autoStatePath, { force: true }); } catch { /* 忽略 */ }
+    });
+    return autoStateQueue;
+  }
+
+  return {
+    dshPort,
+    /** 启动局域网代理（幂等）。端口被占（EADDRINUSE，如桌面版与普通环境同时运行）时自动尝试下一个端口。 */
+    async startProxy() {
+      if (proxy) return proxy;
+      let lastErr = null;
+      for (let p = port; p < port + 10; p++) {
+        try {
+          proxy = await createProxy({
+            port: p,
+            host: '0.0.0.0',
+            upstream: { host: '127.0.0.1', port: dshPort },
+            ...(injectHtml ? { injectHtml } : {}),
+            ...(auth ? { auth } : {}),
+            // 每次请求实时读开关：设置页切换后立即生效，无需重启代理
+            lanAccessEnabled: () => getLanEnabled(),
+            // dsh web 浏览器会话启动 token（issue #77）：实时取，新版 dsh 才有
+            ...(launchToken ? { launchToken } : {}),
+          });
+          if (p !== port) {
+            logInfo(`dsh-pocket: port ${port} busy, proxy on ${p} | 端口 ${port} 被占用，代理改用 ${p}`);
+          }
+          break;
+        } catch (err) {
+          if (err?.code !== 'EADDRINUSE') throw err; // 非端口冲突直接失败
+          lastErr = err;
+        }
+      }
+      if (!proxy) throw lastErr ?? new Error('proxy start failed | 代理启动失败');
+      return proxy;
+    },
+
+    /** 启动公网隧道（幂等；返回公网 URL）。进度写进 tunnelState。并发调用单飞。 */
+    async startTunnel() {
+      await this.startProxy();
+      if (tunnel) return tunnel.url;
+      if (tunnelPromise) return tunnelPromise; // 复用 in-flight，防孤儿 cloudflared
+      const controller = new AbortController();
+      tunnelAbort = controller;
+      tunnelState.startedAt = Date.now();
+      const onPhase = (phase) => {
+        tunnelState.phase = phase;
+        if (phase === 'downloading') tunnelState.detail = '首次下载 cloudflared（约 20MB）| first run downloads cloudflared (~20MB)';
+        else if (phase === 'starting') tunnelState.detail = '启动隧道进程… | starting tunnel…';
+        else if (phase === 'registering') tunnelState.detail = '连接 Cloudflare 边缘（通常 5-30 秒）| connecting to Cloudflare edge (usually 5-30s)';
+        else if (phase === 'ready') tunnelState.detail = '隧道就绪 | ready';
+      };
+      // 先 `await null` 让函数体从微任务开始执行：否则在 `p` 初始化之前（getTunnelConfig
+      // 之类的同步抛错）就会走到 finally，引用未初始化的 const 触发 TDZ 报错，
+      // tunnelPromise 会永久停在 rejected —— 此后 startTunnel 一直复用这个失败的
+      // promise，隧道再也起不来。
+      const p = (async () => {
+        await null;
+        try {
+          // 命名隧道（issue #66）：固定域名模式——URL 由设置里的域名拼出（cloudflared 不打印）
+          const cfg = typeof getTunnelConfig === 'function' ? (getTunnelConfig() ?? {}) : {};
+          if (cfg?.mode === 'named') {
+            if (!cfg.token || !cfg.hostname) {
+              throw new Error(
+                '命名隧道未配置完整：需要 Tunnel Token 和固定域名（设置页「固定域名」里填写） | '
+                + 'named tunnel is incomplete — set the Tunnel Token and the fixed hostname in Settings',
+              );
+            }
+            const result = await startNamed({ token: cfg.token, home, signal: controller.signal, onPhase });
+            tunnel = { url: `https://${cfg.hostname}`, kill: result.kill, onExit: result.onExit };
+          } else {
+            const result = await startTunnel({ port: proxy.port, home, signal: controller.signal, onPhase });
+            // 归一化：startTunnel 契约返回 {url, kill}（字符串也兼容）
+            tunnel = typeof result === 'string' ? { url: result, kill: () => {} } : result;
+          }
+          tunnelState.phase = 'ready';
+          // M1：隧道进程运行中死亡（崩溃/被杀）→ 状态打回，别让 UI 永远显示"可用"
+          tunnel.onExit?.((code) => {
+            if (controller.signal.aborted) return; // 主动停止（stopTunnel）不算故障
+            tunnelState.phase = 'error';
+            tunnelState.detail = `隧道进程退出（code=${code}） | tunnel process exited (code=${code})`;
+          });
+          // 记录「隧道开启中」，供重启后自动恢复（issue #11）
+          void persistAutoTunnel();
+          // 公网隧道就绪 → 回调（快速模式轮换访问密码；命名模式不轮换，见 lib/index.js）
+          try { onTunnelReady?.(cfg?.mode === 'named' ? 'named' : 'quick'); } catch { /* 忽略 */ }
+          return tunnel.url;
+        } catch (err) {
+          // stopTunnel 触发的 abort 不算错误：保持 idle，别把状态刷成 error
+          if (!controller.signal.aborted) {
+            tunnelState.phase = 'error';
+            tunnelState.detail = err?.message ?? String(err);
+          }
+          tunnelState.startedAt = null; // 失败后清掉计时，避免 UI 误显"启动中"
+          throw err;
+        } finally {
+          // 只清自己的引用：stopTunnel 后立即 startTunnel 可能已建了新的 in-flight
+          // （tunnelPromise=B），A 的 finally 不能把 B 清掉，否则第三次调用会并发 spawn
+          if (tunnelPromise === p) tunnelPromise = null;
+        }
+      })();
+      tunnelPromise = p;
+      return p;
+    },
+
+    /**
+     * 停止公网隧道（代理保持）。
+     * @param {{ keepAutoMarker?: boolean }} [opts] - keepAutoMarker=true 用于进程退出/
+     *   自重启（dispose / pocketRestart）：隧道是随进程被动消失的，不是用户主动关闭，
+     *   必须保留 tunnel-auto.json，下次启动才能自动恢复（issue #11 的本意）。
+     *   默认（设置页手动关闭、恢复出厂）删除标记。
+     */
+    stopTunnel({ keepAutoMarker = false } = {}) {
+      tunnelAbort?.abort();
+      tunnelAbort = null;
+      tunnelPromise = null; // 丢弃已 abort 的 in-flight（其 finally 会再清一次，无害）
+      if (tunnel) tunnel.kill();
+      tunnel = null;
+      tunnelState.phase = 'idle';
+      tunnelState.detail = '';
+      tunnelState.startedAt = null;
+      if (!keepAutoMarker) void clearAutoTunnel(); // 手动关闭后不再自动恢复
+    },
+
+    /** 启动时自动恢复上次开启的公网隧道（DSH 重启后 cloudflared 子进程被杀，issue #11）。 */
+    async restoreTunnelIfNeeded() {
+      logInfo('dsh-pocket: auto-restore check | 自动恢复检查：读取上次隧道状态');
+      if (!autoStatePath || tunnel || tunnelPromise) return;
+      let has = false;
+      try {
+        const raw = await readFile(autoStatePath, 'utf8');
+        has = /"at"\s*:/.test(raw);
+      } catch { return; } // 无标记 → 不恢复
+      if (!has) return;
+      logInfo('dsh-pocket: auto-restore: marker found, starting tunnel | 发现上次开启标记，尝试自动恢复');
+      try {
+        await this.startTunnel();
+        logInfo('dsh-pocket: public tunnel auto-restored | 已自动恢复公网隧道');
+      } catch (err) {
+        // 恢复失败保留标记（下次启动再试）；网络问题见 README 排障
+        logWarn('dsh-pocket: tunnel auto-restore failed | 自动恢复隧道失败: %s', err?.message ?? err);
+      }
+    },
+
+    /** 状态快照（RPC 返回，不含敏感信息；二维码 data URL 本地生成 + 缓存）。 */
+    async status() {
+      const lan = await getLan();
+      const proxyPort = proxy?.port ?? null;
+      const lanUrl = lan && proxyPort ? `http://${lan}:${proxyPort}` : null;
+      const lanIpOverride = getLanOverride();
+      const lanCandidates = [...new Set(await getLanCandidates())];
+      if (lanIpOverride && !lanCandidates.includes(lanIpOverride)) lanCandidates.push(lanIpOverride);
+      return {
+        proxyRunning: proxy !== null,
+        proxyPort,
+        lanUrl,
+        lanQr: await qrCached(lanUrl),
+        lanCandidates,
+        lanIpOverride,
+        tunnelRunning: tunnel !== null,
+        tunnelUrl: tunnel?.url ?? null,
+        tunnelQr: await qrCached(tunnel?.url ?? null),
+        tunnelState: { ...tunnelState },
+        // 隧道配置脱敏视图（issue #66）：token 永不回显，只有 tokenSet 布尔值
+        tunnelConfig: (() => {
+          const cfg = typeof getTunnelConfig === 'function' ? (getTunnelConfig() ?? {}) : {};
+          return {
+            mode: cfg?.mode === 'named' ? 'named' : 'quick',
+            hostname: typeof cfg?.hostname === 'string' ? cfg.hostname : '',
+            tokenSet: Boolean(cfg?.token),
+          };
+        })(),
+        dshPort,
+      };
+    },
+
+    /** 停止一切（插件卸载时）。 */
+    /** 停止一切（插件卸载时）。进程退出不是用户手动关闭：保留自动恢复标记。 */
+    async dispose() {
+      this.stopTunnel({ keepAutoMarker: true });
+      if (proxy) {
+        const p = proxy;
+        proxy = null;
+        try { await p.close(); } catch { /* server 已关闭等边缘情况 */ }
+      }
+    },
+  };
+}