tt-help-cli-ycl 1.4.155 → 1.4.157

package/src/clash/runtime.js

@@ -0,0 +1,823 @@
+/**
+ * mihomo 内核运行时 — runtime.js
+ *
+ * 职责:
+ *   1. 随包分发: 从 vendor/mihomo/ 解压对应平台内核 + metacubexd 面板到 ~/.tt-help/mihomo/
+ *   2. config.yaml 生成: proxy-providers（订阅）+ GLOBAL include-all 桥接 + external-ui 面板
+ *   3. 进程托管: 先发现后拉起（幂等，不会起双实例）、detached 运行（daemon 挂了代理不陪葬）、
+ *      拉起冷却（防崩溃循环）、端口预检（被 Verge 等占用时不抢）
+ *
+ * 订阅来源: ~/.tt-help.json → clash.subscriptions（setSubscription 命令应用后回写持久化）
+ * 端口/secret: 与 DISCOVER_DEFAULTS 一致（9097/abcdefg/7897），保证 daemon 发现逻辑零改动
+ *
+ * 被调用方: daemon.js（自动托管）、CLI（tt-help proxy，共用同一套）
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync, readdirSync, copyFileSync, openSync, renameSync } from "fs";
+import net from "net";
+import { homedir, platform, arch } from "os";
+import { join, dirname } from "path";
+import { spawn, spawnSync, execSync } from "child_process";
+import { gunzipSync } from "zlib";
+import { createHash } from "crypto";
+import { fileURLToPath } from "url";
+import { parseNetstatListeningPids } from "../lib/browser/cdp.js";
+import { DISCOVER_DEFAULTS } from "./discover.js";
+
+const IS_WIN = platform() === "win32";
+
+// ── 路径 ──
+
+/** 包根目录（src/clash/ → 上两级） */
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+/** 随包内核目录 */
+export const VENDOR_DIR = join(PKG_ROOT, "vendor", "mihomo");
+/** 运行时目录 */
+export const RUNTIME_DIR = join(homedir(), ".tt-help", "mihomo");
+
+export function runtimePaths() {
+  return {
+    dir: RUNTIME_DIR,
+    bin: join(RUNTIME_DIR, "bin", IS_WIN ? "mihomo.exe" : "mihomo"),
+    ui: join(RUNTIME_DIR, "ui"),
+    configFile: join(RUNTIME_DIR, "config.yaml"),
+    logFile: join(RUNTIME_DIR, "run.log"),
+    stampFile: join(RUNTIME_DIR, ".installed"),
+    providersDir: join(RUNTIME_DIR, "providers"),
+  };
+}
+
+// ── 平台标识与内核获取清单（npm 包不再内置二进制，运行时多级获取）──
+
+export const MIHOMO_VERSION = "v1.19.31";
+
+/** 内核/面板获取清单: 版本钉死 + sha256 强校验（升级 mihomo = 改此表 + 传服务器） */
+const VENDOR_MANIFEST = {
+  "darwin-arm64": { file: `mihomo-darwin-arm64-${MIHOMO_VERSION}.gz`, sha256: "d131f44b3deb2a8356f7ac75048ad67a10d53243323951c4f3cda7b672922963" },
+  "darwin-amd64": { file: `mihomo-darwin-amd64-${MIHOMO_VERSION}.gz`, sha256: "3546681ebef3415e5dcbe7210a61aa80748136e95e6552768fd883df345508ed" },
+  "windows-amd64": { file: `mihomo-windows-amd64-${MIHOMO_VERSION}.zip`, sha256: "38b2420799d9e7cde77ec1a19c7150dd17ca77f7fb82d9f62cb8763a307eee67" },
+};
+const UI_MANIFEST = { file: "metacubexd-dist.tgz", sha256: "93eb334af7e37d213317347c01de31bd28e6c591c9b90e86496d257f15135ed9" };
+
+/**
+ * 内核/面板下载源（顺序 failover）:
+ *   1. ~/.tt-help.json → clash.vendorBase 或环境变量 TT_VENDOR_BASE（覆盖）
+ *   2. 自建服务器公网（201 watch 静态路由 /scripts/vendor，免鉴权）
+ *   3. 自建服务器内网（农场机器直连）
+ *   4. GitHub Releases（仅海外/兜底；农场不可达属预期）
+ */
+export function vendorBases() {
+  const urls = [];
+  const push = (u) => {
+    if (u) urls.push(String(u).replace(/\/+$/, ""));
+  };
+  try {
+    const cfgPath = join(homedir(), ".tt-help.json");
+    if (existsSync(cfgPath)) {
+      const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+      push(cfg?.clash?.vendorBase);
+    }
+  } catch {}
+  push(process.env.TT_VENDOR_BASE);
+  push("http://117.71.53.99:17301/scripts/vendor");
+  push("http://172.18.154.201:3001/scripts/vendor");
+  push("https://github.com/MetaCubeX/mihomo/releases/download");
+  return [...new Set(urls)];
+}
+
+/** node 平台/arch → mihomo 发布命名（win32→windows, x64→amd64） */
+function platformKey() {
+  const p = platform() === "win32" ? "windows" : platform();
+  const a = arch() === "arm64" ? "arm64" : "amd64";
+  return `${p}-${a}`;
+}
+
+/** 定位 vendor 中当前平台的内核压缩包（.gz=unix 单文件 / .zip=windows） */
+export function findVendorCore() {
+  if (!existsSync(VENDOR_DIR)) return null;
+  const prefix = `mihomo-${platformKey()}-`;
+  for (const f of readdirSync(VENDOR_DIR)) {
+    if (f.startsWith(prefix) && (f.endsWith(".gz") || f.endsWith(".zip"))) {
+      const p = join(VENDOR_DIR, f);
+      const st = statSync(p);
+      return { path: p, file: f, size: st.size, mtimeMs: st.mtimeMs };
+    }
+  }
+  return null;
+}
+
+function findVendorUI() {
+  const p = join(VENDOR_DIR, "metacubexd-dist.tgz");
+  if (!existsSync(p)) return null;
+  const st = statSync(p);
+  return { path: p, size: st.size, mtimeMs: st.mtimeMs };
+}
+
+// ── 解压落位 ──
+
+function readStamp() {
+  const { stampFile } = runtimePaths();
+  try {
+    return JSON.parse(readFileSync(stampFile, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeStamp(stamp) {
+  const { stampFile } = runtimePaths();
+  writeFileSync(stampFile, JSON.stringify(stamp));
+}
+
+/** 已安装且与 vendor 一致（size+mtime 比对）→ 跳过重复解压 */
+function installUpToDate(art, stampKey) {
+  const stamp = readStamp();
+  if (!stamp || !stamp[stampKey]) return false;
+  return stamp[stampKey].size === art.size && stamp[stampKey].mtimeMs === art.mtimeMs && existsSync(stamp[stampKey].target);
+}
+
+function sha256File(file) {
+  return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+
+/**
+ * 从压缩包安装内核（sha256 强校验 + 临时文件原子替换，不伤及运行中的旧内核）
+ * @param {string} artPath 压缩包路径（vendor 或下载缓存）
+ * @param {{file:string, sha256:string}} entry 清单项
+ */
+async function installCoreFromArt(artPath, entry, { log = () => {} } = {}) {
+  const { bin } = runtimePaths();
+  const actual = sha256File(artPath);
+  if (actual !== entry.sha256) {
+    return { ok: false, error: `内核 sha256 校验失败（期望 ${entry.sha256.slice(0, 12)}…，实际 ${actual.slice(0, 12)}…）` };
+  }
+  mkdirSync(dirname(bin), { recursive: true });
+  if (entry.file.endsWith(".gz")) {
+    // unix 单文件: gunzip → 临时文件 → 原子替换（运行中旧内核不受影响）
+    const tmp = `${bin}.tmp-${Date.now()}`;
+    writeFileSync(tmp, gunzipSync(readFileSync(artPath)));
+    if (!IS_WIN) spawnSync("chmod", ["755", tmp]);
+    renameSync(tmp, bin);
+  } else {
+    // windows zip: tar(bsdtar) 解压 → 找 exe → 原子替换
+    const tmp = join(RUNTIME_DIR, `.extract-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    const r = spawnSync("tar", ["-xf", artPath, "-C", tmp], { encoding: "utf-8" });
+    const exe = findFileRecursive(tmp, /^mihomo[\w.-]*\.exe$/i);
+    if (!exe) {
+      rmSync(tmp, { recursive: true, force: true });
+      return { ok: false, error: `zip 中未找到 mihomo.exe（tar: ${r.stderr || r.stdout || "无输出"}）` };
+    }
+    copyFileSync(exe, bin);
+    rmSync(tmp, { recursive: true, force: true });
+  }
+  const stamp = readStamp() || {};
+  stamp.core = { version: MIHOMO_VERSION, sha256: entry.sha256, target: bin };
+  writeStamp(stamp);
+  log(`✓ 内核就位 (${MIHOMO_VERSION})`);
+  return { ok: true, bin };
+}
+
+/**
+ * 确保内核二进制就位（多级获取: 本地缓存 → 包内 vendor → 服务器下载 → GitHub 兼底）
+ * @returns {Promise<{ok:boolean, bin?:string, source?:string, error?:string}>}
+ */
+export async function ensureBinary({ log = () => {} } = {}) {
+  const { bin } = runtimePaths();
+  const entry = VENDOR_MANIFEST[platformKey()];
+  if (!entry) return { ok: false, error: `不支持的平台: ${platformKey()}` };
+
+  // 1) 本地缓存: 版本与清单一致 → 跳过（老机器平滑：无 version 字段的旧 stamp 会被后续步骤补齐）
+  const stamp = readStamp();
+  if (existsSync(bin) && stamp?.core?.version === MIHOMO_VERSION) {
+    return { ok: true, bin, source: "cache" };
+  }
+
+  // 2) 包内 vendor（dev / npm link / 手动放置）
+  const art = findVendorCore();
+  if (art) {
+    if (installUpToDate(art, "core") && existsSync(bin)) {
+      // 旧版 stamp 补写 version 字段，下次直接命中缓存
+      const s = readStamp() || {};
+      s.core = { ...(s.core || {}), version: MIHOMO_VERSION, target: bin };
+      writeStamp(s);
+      return { ok: true, bin, source: "vendor" };
+    }
+    log(`📦 使用包内内核: ${art.file}`);
+    return installCoreFromArt(art.path, entry, { log });
+  }
+
+  // 3) 下载链（自建服务器 → GitHub 兼底）
+  const dlFile = join(RUNTIME_DIR, `.dl-${entry.file}`);
+  mkdirSync(RUNTIME_DIR, { recursive: true });
+  for (const base of vendorBases()) {
+    const url = `${base}/${MIHOMO_VERSION}/${entry.file}`;
+    let ok = false;
+    for (let t = 1; t <= 2 && !ok; t++) {
+      try {
+        log(`⬇️ 下载内核(${t}/2): ${url}`);
+        const res = await fetch(url, { signal: AbortSignal.timeout(300000) });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length < 1024 * 1024) throw new Error(`文件过小 (${buf.length}B)，疑似错误页`);
+        writeFileSync(dlFile, buf);
+        ok = true;
+      } catch (e) {
+        log(`⚠ 下载失败: ${e.message}`);
+        if (t < 2) await delay(2000);
+      }
+    }
+    if (ok) {
+      const r = await installCoreFromArt(dlFile, entry, { log });
+      try {
+        rmSync(dlFile, { force: true });
+      } catch {}
+      if (r.ok) return { ...r, source: `download:${base}` };
+      log(`⚠ ${r.error}（来自 ${base}）`);
+    }
+  }
+  return {
+    ok: false,
+    error: `内核获取失败（已尝试 ${vendorBases().length} 个源）。可手动下载 ${entry.file} 放到 ${dirname(bin)}`,
+  };
+}
+
+/**
+ * 确保面板静态文件就位（metacubexd，多级获取；非关键路径，失败仅警告）
+ * @returns {Promise<{ok:boolean, ui?:string, error?:string}>}
+ */
+export async function ensureUI({ log = () => {} } = {}) {
+  const { ui } = runtimePaths();
+  const indexFile = join(ui, "index.html");
+
+  // 1) 本地缓存: 版本一致 → 跳过
+  const stamp = readStamp();
+  if (existsSync(indexFile) && stamp?.ui?.version === MIHOMO_VERSION) return { ok: true, ui };
+
+  // 2) 包内 vendor
+  const art = findVendorUI();
+  if (art) {
+    const r = installUIFromArt(art.path, { log });
+    if (r.ok) return { ok: true, ui };
+    return r;
+  }
+
+  // 3) 下载链（不含 GitHub，面板非关键）
+  const dlFile = join(RUNTIME_DIR, `.dl-${UI_MANIFEST.file}`);
+  mkdirSync(RUNTIME_DIR, { recursive: true });
+  for (const base of vendorBases().slice(0, 3)) {
+    const url = `${base}/${MIHOMO_VERSION}/${UI_MANIFEST.file}`;
+    try {
+      log(`⬇️ 下载面板: ${url}`);
+      const res = await fetch(url, { signal: AbortSignal.timeout(120000) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const buf = Buffer.from(await res.arrayBuffer());
+      if (buf.length < 1024) throw new Error("文件过小");
+      writeFileSync(dlFile, buf);
+      const r = installUIFromArt(dlFile, { log });
+      try {
+        rmSync(dlFile, { force: true });
+      } catch {}
+      return r;
+    } catch (e) {
+      log(`⚠ 面板下载失败: ${e.message}`);
+    }
+  }
+  return { ok: false, error: `面板获取失败（非关键，不影响代理）` };
+}
+
+function installUIFromArt(artPath, { log = () => {} } = {}) {
+  const { ui } = runtimePaths();
+  const actual = sha256File(artPath);
+  if (actual !== UI_MANIFEST.sha256) {
+    return { ok: false, error: `面板 sha256 校验失败` };
+  }
+  try {
+    rmSync(ui, { recursive: true, force: true });
+    mkdirSync(ui, { recursive: true });
+    const r = spawnSync("tar", ["-xzf", artPath, "-C", ui], { encoding: "utf-8" });
+    if (r.status !== 0 || !existsSync(join(ui, "index.html"))) {
+      return { ok: false, error: `面板解压失败: ${r.stderr || "未生成 index.html"}` };
+    }
+    const stamp = readStamp() || {};
+    stamp.ui = { version: MIHOMO_VERSION, sha256: UI_MANIFEST.sha256, target: join(ui, "index.html") };
+    writeStamp(stamp);
+    log("✓ 面板就位");
+    return { ok: true, ui };
+  } catch (e) {
+    return { ok: false, error: `面板解压失败: ${e.message}` };
+  }
+}
+
+function findFileRecursive(dir, regex) {
+  try {
+    for (const f of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, f.name);
+      if (f.isDirectory()) {
+        const hit = findFileRecursive(p, regex);
+        if (hit) return hit;
+      } else if (regex.test(f.name)) {
+        return p;
+      }
+    }
+  } catch {}
+  return null;
+}
+
+// ── 订阅配置（~/.tt-help.json → clash.subscriptions） ──
+
+/** 归一化: ["url" | {name,url}] → [{name,url}]；非法 URL 丢弃；中文名清洗后为空则自动编 sub-N */
+export function normalizeSubscriptions(list) {
+  const out = [];
+  for (const it of Array.isArray(list) ? list : []) {
+    const url = typeof it === "string" ? it.trim() : it && String(it.url || "").trim();
+    if (!url || !/^https?:\/\//.test(url)) continue;
+    let name = typeof it === "object" && it.name ? String(it.name).trim() : "";
+    name = name.replace(/[^\w-]/g, "").slice(0, 32);
+    if (!name || /^\d+$/.test(name)) name = ""; // 纯数字/空名回退自动命名
+    if (!name) name = `sub-${out.length + 1}`;
+    if (out.some((s) => s.name === name)) name = `${name}-${out.length + 1}`;
+    out.push({ name, url });
+  }
+  return out;
+}
+
+/** 读本机已持久化的订阅（~/.tt-help.json → clash.subscriptions） */
+export function readStoredSubscriptions() {
+  try {
+    const p = join(homedir(), ".tt-help.json");
+    if (!existsSync(p)) return [];
+    const cfg = JSON.parse(readFileSync(p, "utf-8"));
+    return normalizeSubscriptions((cfg.clash && cfg.clash.subscriptions) || []);
+  } catch {
+    return [];
+  }
+}
+
+/** 持久化订阅到 ~/.tt-help.json（应用成功后调用，保证 daemon 重启后自恢复） */
+export function storeSubscriptions(list) {
+  const p = join(homedir(), ".tt-help.json");
+  let cfg = {};
+  try {
+    cfg = JSON.parse(readFileSync(p, "utf-8"));
+  } catch {}
+  if (!cfg.clash || typeof cfg.clash !== "object") cfg.clash = {};
+  cfg.clash.subscriptions = normalizeSubscriptions(list);
+  writeFileSync(p, JSON.stringify(cfg, null, 2));
+  return cfg.clash.subscriptions;
+}
+
+// ── config.yaml 生成 ──
+
+/**
+ * 生成 mihomo 配置（与实测验证过的模板一致）:
+ *   global 模式 + GLOBAL include-all 桥接（provider 节点进 GLOBAL，daemon 切换零改动）
+ *   external-ui 挂面板（仅启动时生效，所以必须生成时就写入）
+ */
+export function buildConfig({ subscriptions, apiPort, secret, mixedPort }) {
+  const lines = [
+    "# 由 tt-help runtime 自动生成 — 手动修改会被覆盖",
+    `mixed-port: ${mixedPort}`,
+    `external-controller: 127.0.0.1:${apiPort}`,
+    `secret: "${secret}"`,
+    "mode: global",
+    "log-level: info",
+    "external-ui: ui",
+    "",
+  ];
+  if (subscriptions.length) {
+    lines.push("proxy-providers:");
+    for (const s of subscriptions) {
+      lines.push(
+        `  ${s.name}:`,
+        "    type: http",
+        `    url: ${s.url}`,
+        "    interval: 86400",
+        `    path: ./providers/${s.name}.yaml`,
+        "    proxy: DIRECT",
+        "    health-check:",
+        "      enable: true",
+        "      url: http://www.gstatic.com/generate_204",
+        "      interval: 3600",
+      );
+    }
+    lines.push("");
+  }
+  lines.push(
+    "proxy-groups:",
+    "  - name: GLOBAL",
+    "    type: select",
+    "    include-all: true",
+    "",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * 写 config.yaml（内容不变则跳过，返回是否变化）
+ * @returns {{ok:boolean, changed:boolean, error?:string}}
+ */
+export function writeConfig({ subscriptions, apiPort, secret, mixedPort }) {
+  const { configFile } = runtimePaths();
+  try {
+    mkdirSync(RUNTIME_DIR, { recursive: true });
+    mkdirSync(join(RUNTIME_DIR, "providers"), { recursive: true });
+    const content = buildConfig({ subscriptions, apiPort, secret, mixedPort });
+    const prev = existsSync(configFile) ? readFileSync(configFile, "utf-8") : "";
+    if (prev === content) return { ok: true, changed: false };
+    writeFileSync(configFile, content);
+    return { ok: true, changed: true, prevContent: prev };
+  } catch (e) {
+    return { ok: false, changed: false, error: e.message };
+  }
+}
+
+// ── 探测 ──
+
+/** TCP 端口是否有进程监听（跨平台，无外部依赖） */
+export function isPortListening(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host: "127.0.0.1" });
+    const done = (r) => {
+      sock.destroy();
+      resolve(r);
+    };
+    sock.setTimeout(timeoutMs);
+    sock.once("connect", () => done(true));
+    sock.once("timeout", () => done(false));
+    sock.once("error", () => done(false));
+  });
+}
+
+/** GET /version 探测（带 secret），返回 mihomo 是否可用 */
+export async function controllerAlive(apiPort, secret, timeoutMs = 2500) {
+  try {
+    const headers = {};
+    if (secret) headers.Authorization = `Bearer ${secret}`;
+    const res = await fetch(`http://127.0.0.1:${apiPort}/version`, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status !== 200) return false;
+    const j = await res.json().catch(() => null);
+    return typeof j?.version === "string";
+  } catch {
+    return false;
+  }
+}
+
+// ── 端口占用者识别与接管（订阅 = 接管授权，2026-09-25 设计）──
+
+/** 找到监听指定端口的 pid（跨平台；失败返回空数组） */
+function getListeningPids(port) {
+  try {
+    if (IS_WIN) {
+      const out = execSync("netstat -ano -p TCP", { encoding: "utf-8", timeout: 10000, windowsHide: true });
+      return parseNetstatListeningPids(out, port).map(Number);
+    }
+    const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -t`, { encoding: "utf-8", timeout: 8000 });
+    return out.split(/\s+/).filter(Boolean).map(Number);
+  } catch {
+    return [];
+  }
+}
+
+/** 读进程命令行（跨平台；失败返回空串） */
+function getProcessCmd(pid) {
+  try {
+    if (IS_WIN) {
+      // 优先 wmic（旧系统）；新系统已移除 wmic → 回退 PowerShell（2026-09-25 213 实测）
+      try {
+        const out = execSync(`wmic process where processid=${pid} get commandline /format:list`, {
+          encoding: "utf-8",
+          timeout: 10000,
+          windowsHide: true,
+        });
+        const m = out.match(/CommandLine=(.*)/i);
+        if (m && m[1].trim()) return m[1].trim();
+      } catch {}
+      const ps = execSync(
+        `powershell -NoProfile -Command "(Get-CimInstance Win32_Process -Filter \\"ProcessId=${pid}\\").CommandLine"`,
+        { encoding: "utf-8", timeout: 15000, windowsHide: true },
+      );
+      return ps.trim();
+    }
+    return execSync(`ps -p ${pid} -o command=`, { encoding: "utf-8", timeout: 8000 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+const CLASH_CORE_RE = /mihomo|clash|verge/i;
+const RUNTIME_DIR_RE = /[\\/]\.tt-help[\\/]mihomo[\\/]/;
+
+/**
+ * 清理端口上的 clash 内核签名占用者（Verge 内核等，仅在订阅接管时调用）。
+ * @returns {Promise<'killed'|'none'|'foreign'>} killed=已清理并等端口释放; none=端口已空; foreign=非内核程序，不动
+ */
+async function killClashCoreOnPort(port, { log = () => {} } = {}) {
+  const pids = getListeningPids(port).filter((pid) => pid !== process.pid);
+  if (!pids.length) return "none";
+  let foreign = false;
+  const killed = [];
+  for (const pid of pids) {
+    const cmd = getProcessCmd(pid);
+    if (!CLASH_CORE_RE.test(cmd)) {
+      foreign = true;
+      log(`⚠ 端口 ${port} 占用者非 clash 内核 (pid ${pid})，不自动清理`);
+      continue;
+    }
+    log(`🧹 接管: 清理端口 ${port} 上的 clash 内核 (pid ${pid}, ${cmd.slice(0, 80)})`);
+    try {
+      if (IS_WIN) {
+        execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore", timeout: 15000, windowsHide: true });
+      } else {
+        process.kill(pid, "SIGTERM");
+      }
+      killed.push(pid);
+    } catch {}
+  }
+  if (foreign) return "foreign";
+  if (!killed.length) return "none";
+  // unix TERM 可能被忽略 → 残留补 KILL；等端口释放
+  for (let i = 0; i < 10; i++) {
+    await delay(500);
+    if (!(await isPortListening(port))) break;
+    if (i === 5) {
+      for (const pid of killed) {
+        try {
+          if (!IS_WIN) process.kill(pid, "SIGKILL");
+        } catch {}
+      }
+    }
+  }
+  return "killed";
+}
+
+/** 当前 apiPort 控制端是否为我们 runtime 拉起的 mihomo（路径在 ~/.tt-help/mihomo 下） */
+export async function runtimeControllerIsOurs(apiPort = DISCOVER_DEFAULTS.port) {
+  for (const pid of getListeningPids(apiPort)) {
+    const cmd = getProcessCmd(pid);
+    if (cmd && RUNTIME_DIR_RE.test(cmd)) return true;
+  }
+  return false;
+}
+
+/** 回收我们拉起的内置 mihomo（清空订阅时调用；外来内核不动） */
+export async function stopRuntimeMihomo({
+  apiPort = DISCOVER_DEFAULTS.port,
+  mixedPort = DISCOVER_DEFAULTS.proxyPort,
+  log = () => {},
+} = {}) {
+  let killed = 0;
+  for (const port of [apiPort, mixedPort]) {
+    for (const pid of getListeningPids(port)) {
+      const cmd = getProcessCmd(pid);
+      if (!cmd || !RUNTIME_DIR_RE.test(cmd)) continue;
+      log(`🧹 回收内置 mihomo (pid ${pid})`);
+      try {
+        if (IS_WIN) {
+          execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore", timeout: 15000, windowsHide: true });
+        } else {
+          process.kill(pid, "SIGTERM");
+        }
+        killed++;
+      } catch {}
+    }
+  }
+  return killed;
+}
+
+// ── 进程托管 ──
+
+let _lastSpawnAt = 0;
+const SPAWN_COOLDOWN_MS = 60_000;
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * 确保 mihomo 运行（订阅 = 接管授权）:
+ *   - 未配置订阅 → no-subscription，不拉起不占位不碰任何现有代理（用户可自用 Verge）
+ *   - 控制端已可用（Verge / 上次拉起的 mihomo）→ adopted，不动（force 模式跳过）
+ *   - 端口被 clash 内核签名进程占用 → 清理后拉起（接管）；非内核程序 → port-busy 不抢
+ *   - 拉起冷却期内 → cooldown（force 绕过）
+ *   - 解压 + 生成配置 + detached 拉起 + 等 API → started / failed
+ *
+ * @returns {Promise<{status:'no-subscription'|'adopted'|'started'|'port-busy'|'cooldown'|'no-vendor'|'failed', error?:string, bin?:string}>}
+ */
+export async function ensureMihomoRunning({
+  subscriptions,
+  force = false,
+  apiPort = DISCOVER_DEFAULTS.port,
+  secret = DISCOVER_DEFAULTS.secret,
+  mixedPort = DISCOVER_DEFAULTS.proxyPort,
+  log = () => {},
+} = {}) {
+  // 1) 订阅 = 接管授权: 无订阅不拉起、不占位、不碰任何现有代理（用户可自用 Verge）
+  const subs = normalizeSubscriptions(subscriptions || readStoredSubscriptions());
+  if (!subs.length) {
+    log("⏭ 未配置订阅，内置 mihomo 不参与（后台配置订阅后自动接管）");
+    return { status: "no-subscription" };
+  }
+
+  // 2) 控制端已可用 → 认领（force=订阅接管模式跳过，用于换掉外来内核）
+  if (!force && (await controllerAlive(apiPort, secret))) return { status: "adopted" };
+
+  // 3) 冷却期（force=用户主动订阅动作，绕过）
+  const gap = Date.now() - _lastSpawnAt;
+  if (!force && gap < SPAWN_COOLDOWN_MS) {
+    return { status: "cooldown", error: `拉起冷却中 ${Math.ceil((SPAWN_COOLDOWN_MS - gap) / 1000)}s` };
+  }
+
+  // 4) 端口占用 → 仅清理 clash 内核签名占用者（Verge 内核等），其余不抢
+  for (const p of [apiPort, mixedPort]) {
+    if (await isPortListening(p)) {
+      const kr = await killClashCoreOnPort(p, { log });
+      if (kr !== "killed" && kr !== "none") {
+        return { status: "port-busy", error: `端口 ${p} 被非内核程序占用，不自动清理` };
+      }
+      if (await isPortListening(p)) {
+        return { status: "port-busy", error: `端口 ${p} 清理后仍被占用` };
+      }
+    }
+  }
+
+  // 5) 落位 + 生成配置
+  _lastSpawnAt = Date.now();
+  const coreR = await ensureBinary({ log });
+  if (!coreR.ok) return { status: "no-vendor", error: coreR.error };
+  const uiR = await ensureUI({ log });
+  if (!uiR.ok) log(`⚠ 面板就位失败（不影响代理）: ${uiR.error}`);
+  const cfgR = writeConfig({ subscriptions: subs, apiPort, secret, mixedPort });
+  if (!cfgR.ok) return { status: "failed", error: `config.yaml 写入失败: ${cfgR.error}` };
+
+  // 6) detached 拉起（daemon 退出不影响代理），日志追加到 run.log
+  const paths = runtimePaths();
+  let logFd;
+  try {
+    logFd = openSync(paths.logFile, "a");
+  } catch {
+    logFd = "ignore";
+  }
+  const child = spawn(coreR.bin, ["-d", RUNTIME_DIR, "-f", paths.configFile], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    windowsHide: true,
+  });
+  child.unref();
+
+  // 7) 等 API 就绪（并确认监听者确实是本次拉起的进程，防止旧内核仍在位造成假阳性）
+  const t0 = Date.now();
+  while (Date.now() - t0 < 20_000) {
+    await delay(600);
+    if (await controllerAlive(apiPort, secret, 1200)) {
+      if (!(await runtimeControllerIsOurs(apiPort))) {
+        return { status: "failed", error: "API 已就绪但监听进程非本次拉起的内置内核（端口被旧内核抢占）" };
+      }
+      log(`✓ 内置 mihomo 已拉起 (pid ${child.pid})，面板: http://127.0.0.1:${apiPort}/ui/`);
+      return { status: "started", pid: child.pid, bin: coreR.bin };
+    }
+    if (child.exitCode !== null) {
+      return { status: "failed", error: `mihomo 进程退出 (code ${child.exitCode})，见 ${paths.logFile}` };
+    }
+  }
+  return { status: "failed", error: "mihomo 启动后 API 20s 未就绪" };
+}
+
+/**
+ * 应用订阅变更: 写 config → 热加载（不重启进程）→ 校验 provider 上线
+ * 必须在目标控制端 API 可用时调用（由 daemon 在控制器上下文中调用）
+ * @returns {Promise<{ok:boolean, changed?:boolean, providers?:Array, error?:string}>}
+ */
+export async function applySubscriptions(
+  subscriptions,
+  { apiPort = DISCOVER_DEFAULTS.port, secret = DISCOVER_DEFAULTS.secret, mixedPort = DISCOVER_DEFAULTS.proxyPort, log = () => {} } = {},
+) {
+  const subs = normalizeSubscriptions(subscriptions);
+  if (!subs.length) return { ok: false, error: "订阅列表为空" };
+
+  const cfgR = writeConfig({ subscriptions: subs, apiPort, secret, mixedPort });
+  if (!cfgR.ok) return { ok: false, error: cfgR.error };
+
+  if (!cfgR.changed) {
+    log("订阅配置无变化，跳过热加载");
+    return { ok: true, changed: false };
+  }
+
+  // 热加载（带 path 明确指向运行时配置）；失败则回滚盘上配置与内核状态一致
+  try {
+    const headers = { "Content-Type": "application/json" };
+    if (secret) headers.Authorization = `Bearer ${secret}`;
+    const res = await fetch(`http://127.0.0.1:${apiPort}/configs?force=true`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({ path: runtimePaths().configFile }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (res.status !== 204) {
+      const t = await res.text().catch(() => "");
+      await rollbackConfig(cfgR.prevContent, { apiPort, secret });
+      return { ok: false, error: `热加载 HTTP ${res.status}: ${t.slice(0, 120)}（已回滚原配置）` };
+    }
+  } catch (e) {
+    await rollbackConfig(cfgR.prevContent, { apiPort, secret });
+    return { ok: false, error: `热加载失败: ${e.message}（已回滚盘上配置）` };
+  }
+
+  const v = await verifyProviders(subs, { apiPort, secret, log });
+  if (!v.ok && cfgR.prevContent) {
+    // 新订阅不可用（URL 失效/机场挂了）→ 回滚到上一个可用配置，保持代理不断
+    await rollbackConfig(cfgR.prevContent, { apiPort, secret });
+    log("⚠ 新订阅不可用，已回滚到原配置（持久化未变更，代理保持可用）");
+    return { ...v, rolledBack: true };
+  }
+  return v;
+}
+
+/** 回滚 config.yaml 并热加载（保持盘上配置与运行内核一致） */
+async function rollbackConfig(content, { apiPort = DISCOVER_DEFAULTS.port, secret = DISCOVER_DEFAULTS.secret } = {}) {
+  try {
+    if (!content) return;
+    writeFileSync(runtimePaths().configFile, content);
+    const headers = { "Content-Type": "application/json" };
+    if (secret) headers.Authorization = `Bearer ${secret}`;
+    await fetch(`http://127.0.0.1:${apiPort}/configs?force=true`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({ path: runtimePaths().configFile }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch {}
+}
+
+/** 等待并校验 provider 上线（热应用/接管共用） */
+export async function verifyProviders(
+  subs,
+  { apiPort = DISCOVER_DEFAULTS.port, secret = DISCOVER_DEFAULTS.secret, log = () => {}, waitMs = 3000 } = {},
+) {
+  await delay(waitMs);
+  try {
+    const headers = {};
+    if (secret) headers.Authorization = `Bearer ${secret}`;
+    const res = await fetch(`http://127.0.0.1:${apiPort}/providers/proxies`, {
+      headers,
+      signal: AbortSignal.timeout(10_000),
+    });
+    const data = await res.json();
+    const providers = [];
+    for (const [name, p] of Object.entries(data.providers || {})) {
+      if (p.vehicleType !== "HTTP") continue;
+      const si = p.subscriptionInfo || {};
+      providers.push({
+        name,
+        proxies: (p.proxies || []).length,
+        upload: si.Upload || 0,
+        download: si.Download || 0,
+        total: si.Total || 0,
+        expire: si.Expire || 0,
+      });
+    }
+    const got = new Map(providers.map((x) => [x.name, x]));
+    // 死 URL 的 provider 也会出现在列表里但 0 节点 → 必须节点数 > 0 才算上线
+    const missing = subs.filter((s) => !((got.get(s.name)?.proxies || 0) > 0)).map((m) => m.name);
+    if (missing.length) {
+      return { ok: false, error: `provider 未上线或 0 节点: ${missing.join(",")}`, providers };
+    }
+    log(`✓ 订阅应用完成: ${providers.map((p) => `${p.name}(${p.proxies}节点)`).join(", ")}`);
+    return { ok: true, changed: true, providers };
+  } catch (e) {
+    return { ok: false, error: `provider 校验失败: ${e.message}` };
+  }
+}
+
+/**
+ * 用户订阅应用入口（后台配置下发唯一路径）。
+ *
+ * 订阅 = 接管授权（2026-09-25 设计）:
+ *   - 内置内核在位 → 热应用（不中断代理；盘上配置一致则短路，顺便自愈崩溃残留）
+ *   - 外来内核（Verge 等）占位或无控制端 → 清理端口内核 + 带订阅拉起内置 mihomo
+ *   - 新订阅不可用（0 节点/热加载失败）→ 自动回滚上一个可用配置，代理不断
+ */
+export async function applyUserSubscriptions(
+  subs,
+  { apiPort = DISCOVER_DEFAULTS.port, secret = DISCOVER_DEFAULTS.secret, log = () => {} } = {},
+) {
+  subs = normalizeSubscriptions(subs);
+  if (!subs.length) return { ok: false, error: "订阅列表为空" };
+
+  const alive = await controllerAlive(apiPort, secret);
+  const ours = alive && (await runtimeControllerIsOurs(apiPort));
+
+  if (ours) {
+    // 热应用；盘上配置已一致时由 applySubscriptions 内部短路（顺便自愈崩溃残留）
+    return applySubscriptions(subs, { apiPort, secret, log });
+  }
+
+  // 外来内核占位或无控制端 → 接管
+  const r = await ensureMihomoRunning({ subscriptions: subs, force: true, apiPort, secret, log });
+  if (r.status !== "started") {
+    return { ok: false, error: `接管失败: ${r.status}${r.error ? ` ${r.error}` : ""}` };
+  }
+  const v = await verifyProviders(subs, { apiPort, secret, log });
+  return v.ok ? { ok: true, changed: true, providers: v.providers } : v;
+}