mslxdff 0.1.239 → 0.1.240

package/src/multi-ip-pool/report.js

@@ -0,0 +1,157 @@
+// multi-ip-pool · 日志文案（判据来自 warp-pool/report.js 的同一套纪律）：
+//   **「看完日志还需要的下一个命令，就是日志没写好的地方」**。
+//   行首符号：▸步骤 / ✓正常 / ✗失败 / ⚠警告；每条失败行都要带「为什么 + 下一步」。
+const SYM = { step: "▸", ok: "✓", bad: "✗", warn: "⚠" };
+const TAG = "[multi-ip-pool]";
+
+export function fmtConfig(cfg) {
+  return `${TAG} ${SYM.step} 多出口池配置：隧道 ${cfg.count} 条｜备选 ${cfg.standby} 条（每 ${Math.round((cfg.standbyEveryMs || 0) / 60_000)} 分钟重拨一批）｜打 hi 用 ${cfg.probeModel || "缺省免费模型"}｜国家 ${cfg.countries.length ? cfg.countries.join("/") : "不限"}｜Score ≥ ${cfg.minScore}｜表号 ${cfg.baseTable}+｜目录 ${cfg.dir}｜openvpn ${cfg.openvpnBin}｜轮换 ${cfg.rotate ? "开" : "关"}`;
+}
+
+export function fmtDisabled() {
+  return `${TAG} 出口池已关闭（MSLXDFF_MULTI_IP_POOL=0），请求走直连`;
+}
+
+export function fmtRoleSkip({ role, why }) {
+  return `${TAG} ${SYM.step} 跳过：本节点角色=${role}（${why}）—— 出口池只由组长建，组员与单机都不建`;
+}
+
+export function fmtRoleOk({ role, why }) {
+  return `${TAG} ${SYM.ok} 角色门通过：role=${role}（${why}）`;
+}
+
+export function fmtPlatformSkip({ platform, why }) {
+  return `${TAG} ${SYM.step} 跳过：${why}（当前平台 ${platform}）—— 本功能要 Linux 的 tun 设备与 ip rule，其它平台请用 v6 池或 WARP 池`;
+}
+
+export function fmtNoRoot() {
+  return `${TAG} ${SYM.step} 跳过：需要 root（要建 tun 设备 + 改策略路由 + 写 rp_filter）。下一步：sudo mslxdff -multi-ip-pool test（或让 root 起 daemon）`;
+}
+
+export function fmtNoOpenvpn({ bin, why }) {
+  return `${TAG} ${SYM.step} 跳过：没找到可用的 ${bin}（${why}）。下一步：apt install openvpn（或 MSLXDFF_MULTI_IP_OPENVPN 指到全路径）`;
+}
+
+export function fmtNodes({ source, total, countries, minScore }) {
+  return `${TAG} ${SYM.ok} 节点表来自 ${source}：共 ${total} 个节点（筛选：国家 ${countries.length ? countries.join("/") : "不限"}、Score ≥ ${minScore}）`;
+}
+
+export function fmtNodePick({ i, n, row, dev }) {
+  return `${TAG} ${SYM.step} [${i}/${n}] 尝试 ${row.hostName}（${row.countryShort || "?"} ${row.ip} Score=${row.score} ping=${row.ping}ms）→ ${dev}`;
+}
+
+export function fmtSpawn({ dev, pid, host, port, country, table }) {
+  return `${TAG} ${SYM.ok} ${dev} 隧道就绪（pid=${pid}，出口节点 ${host}:${port} ${country}，策略表 ${table}）`;
+}
+
+export function fmtTunAddrFail({ dev, out }) {
+  return `${TAG} ${SYM.bad} ${dev} 起来了但读不到 tun 地址（ip -4 addr show dev ${dev} 的输出：${(out || "(空)").slice(0, 200)}）—— 隧道建不起来，这槽换下一个节点`;
+}
+
+export function fmtRuleFail({ dev, cmd, error }) {
+  return `${TAG} ${SYM.bad} ${dev} 装策略路由失败：${cmd} → ${error}。下一步：ip rule show 看优先级、ip route show table all 看表号，是否被别人的规则/表号占了（可改 MSLXDFF_MULTI_IP_BASE_TABLE）`;
+}
+
+export function fmtRpf({ ok, skipped, changed = [], error = "" } = {}) {
+  if (skipped) return `${TAG} ${SYM.warn} rp_filter 未改（MSLXDFF_MULTI_IP_SYSCTL=0）：若隧道通了但请求全挂住，先查这里`;
+  if (ok && !changed.length) return `${TAG} ${SYM.ok} rp_filter 已是宽松模式（2），无需改动`;
+  if (ok) return `${TAG} ${SYM.warn} 已把 rp_filter 改为 2（宽松）：${changed.map((c) => `${c.path}: ${c.from}→2`).join("，")}｜还原命令：sysctl -w net.ipv4.conf.all.rp_filter=1`;
+  return `${TAG} ${SYM.warn} rp_filter 改不动（${error}）：可能隧道活着但请求挂住（不对称路由被内核丢了）。下一步：sysctl -w net.ipv4.conf.all.rp_filter=2`;
+}
+
+export function fmtProbe({ dev, url, ok, status, error, ms }) {
+  if (ok) return `${TAG} ${SYM.ok} ${dev} 探活通过：${url} → HTTP ${status}（${ms}ms）`;
+  return `${TAG} ${SYM.bad} ${dev} 探活不通：${url} → ${status ? `HTTP ${status}` : String(error || "无响应").slice(0, 120)}（${ms}ms）`;
+}
+
+export function fmtProbeGiveUp({ dev, attempts, url }) {
+  return `${TAG} ${SYM.bad} ${dev} 连续 ${attempts} 次探活都不过，本槽不进池（${url}）—— 隧道进程活着但转不动流量时进池会把请求挂到超时，比直连更糟`;
+}
+
+export function fmtExitIp({ dev, ip, ms, prev }) {
+  const what = prev ? (prev === ip ? `出口没变（仍是 ${ip}）` : `出口已换：${prev} → ${ip}`) : `出口 ${ip}`;
+  return `${TAG} ${SYM.ok} ${dev} 出口取证：${what}（${ms}ms）`;
+}
+
+export function fmtExitIpFail({ dev, error }) {
+  return `${TAG} ${SYM.bad} ${dev} 出口取证失败：${String(error || "").slice(0, 160)}—— 这条隧道的出口未知，不视为可用`;
+}
+
+export function fmtPool({ pooled, tried, exits }) {
+  return `${TAG} ${SYM.ok} 出口池就绪：${pooled}/${tried} 槽可用｜出口 IP：${exits.length ? exits.join("，") : "(待取证)"}`;
+}
+
+export function fmtPoolEmpty({ tried, why }) {
+  return `${TAG} ${SYM.bad} 出口池为空（试了 ${tried} 个节点都没起通）：${why}—— 请求继续走直连，不影响其它出口源`;
+}
+
+export function fmtSwap({ dev, from, to, status, kind, forced, swaps }) {
+  return `${TAG} ${SYM.step} ${dev} 上游 ${status} 判为「${kind}」⇒ 换出口${forced ? "（强制，跳过冷却）" : ""}：${from} → ${to}（第 ${swaps} 次换）`;
+}
+
+export function fmtSwapFail({ dev, error }) {
+  return `${TAG} ${SYM.bad} ${dev} 换出口失败：${String(error || "").slice(0, 200)}—— 原槽保持原状，不把池打空`;
+}
+
+export function fmtFirstOk({ dev, ip, swaps, counts }) {
+  return `${TAG} ${SYM.ok} ${dev} 换出口后首个 200（出口 ${ip}，换过 ${swaps} 次，本轮状态分布 ${JSON.stringify(counts)}）—— 这就是「换 IP 有没有换来新额度」的直接证据`;
+}
+
+export function fmtNoRotate({ dev, status, kind }) {
+  return `${TAG} ${SYM.warn} ${dev} 上游 ${status}（${kind}）—— 轮换开关关着（MSLXDFF_MULTI_IP_ROTATE=0），不换出口`;
+}
+
+export function fmtVerdictNo({ dev, status, kind, why }) {
+  return `${TAG} ${SYM.step} ${dev} 上游 ${status} 判为「${kind}」⇒ 不换出口：${why}`;
+}
+
+export function fmtDirect({ reason }) {
+  return `${TAG} ${SYM.warn} 全部槽都在冷却/换出口中，本发走直连兜底：${reason}`;
+}
+
+export function fmtExit({ dev, code, signal, pid, aliveMs, tail }) {
+  return `${TAG} ${SYM.warn} ${dev} 隧道进程退出（code=${code} signal=${signal} pid=${pid}${aliveMs ? ` 存活 ${Math.round(aliveMs / 1000)}s` : ""}）：${tail || "(无输出)"}`;
+}
+
+export function fmtClose({ closed, failed = 0 }) {
+  return `${TAG} ${SYM.step} 收摊：已关 ${closed} 条隧道${failed ? `，${failed} 条没关干净（下次启动查残留：ip link show | grep ${""}mltun）` : ""}`;
+}
+
+export function fmtResidual({ dev }) {
+  return `${TAG} ${SYM.warn} 发现上一代留下的设备 ${dev}（上次 daemon 被强杀时子进程不会自己退）：下一步 ip link del ${dev}`;
+}
+
+/** 免费层判决的人话名（与 `warp-pool/verdict.js` 的 kind 一一对应，不自造一套）。 */
+const KIND_ZH = { "free-quota": "429 额度耗尽", "free-tier": "403 免费层资格", "ip-limit": "429 限流", "black-quota": "账号日配额", network: "网络不可达", none: "非额度信号" };
+
+/** 「打一个 hi 到上游、要它 200」的读数行：只有 200 才算"这个出口此刻真有额度"。 */
+export function fmtHi({ dev, model, status, kind, ip, ms, error } = {}) {
+  const who = `${dev}${ip ? `（出口 ${ip}）` : ""}`;
+  if (status === 200) return `${TAG} ${SYM.ok} ${who} 打 hi 通过：${model} → HTTP 200（${ms}ms）—— 这个出口有额度`;
+  return `${TAG} ${SYM.bad} ${who} 打 hi 未通：${model} → ${status ? `HTTP ${status}（${KIND_ZH[kind] || kind || "?"}）` : String(error || "无响应").slice(0, 120)}（${ms}ms）—— 没额度的出口不当备用，换下一个`;
+}
+
+/** 备用出口收下：一条已验通（hi 200）的隧道躺在备选池里等 429。 */
+export function fmtStandbyAdd({ dev, node, exitIp, tunIp, have, want } = {}) {
+  return `${TAG} ${SYM.ok} 备选池 +1：${dev} ${node || "?"}（tun ${tunIp}，出口 ${exitIp || "未取证"}）→ 现有 ${have}/${want} 条待命`;
+}
+
+/** 补位结论行（每小时一次，也是"这轮找到几个新 IP"的读数）。 */
+export function fmtStandbyRefill({ added, have, want, dialed } = {}) {
+  return `${TAG} ${SYM.step} 备选池补位：本轮拨 ${dialed} 条、收下 ${added} 条 → ${have}/${want} 待命（标准是 hi 回 200，不是"隧道起来了"）`;
+}
+
+/** 取用备用出口那一刻的读数（429 后"立即启用"的证据）。 */
+export function fmtStandbyUse({ dev, tunIp, exitIp, node, left } = {}) {
+  return `${TAG} ${SYM.ok} 启用备用出口：${dev} ${node || "?"}（tun ${tunIp}，出口 ${exitIp || "未取证"}）→ 剩余备用 ${left} 条`;
+}
+
+/** 备用出口被丢弃的原因（复验没过 200 = 这一小时里那个 IP 的额度被别人吃光了）。 */
+export function fmtStandbyDrop({ dev, node, status, kind, error } = {}) {
+  return `${TAG} ${SYM.warn} 丢弃备用出口 ${dev} ${node || "?"}：复验 hi → ${status ? `HTTP ${status}（${KIND_ZH[kind] || kind || "?"}）` : String(error || "无响应").slice(0, 120)}—— 宁缺毋滥，不把没额度的 IP 交给请求`;
+}
+
+/** 备选池这轮没干成事（取不到候选 / 拨号异常）：必须留一行，否则"为什么没有备胎"无从判断。 */
+export function fmtStandbySkip({ why } = {}) {
+  return `${TAG} ${SYM.warn} 备选池本轮跳过：${why}—— 429 时若备胎为空只能现场拨号（慢），原因就是这条`;
+}

package/src/multi-ip-pool/selftest.js

@@ -0,0 +1,162 @@
+// multi-ip-pool · 出口额度对照测试：回答「这台机器的直连出口撞 429 时，换成 VPNGate 出口还有没有额度」。
+//
+// 这才是多出口池的**唯一价值判据**（opencode 免费层按**出口 IP** 计额，见 docs/domain-notes.md §5）：
+//   基线（直连）429 而某个 VPN 出口 200 ⇒ 池有用；VPN 出口也全 429 ⇒ 换 IP 抬不动（上游按别的东西计额）。
+// 对照纪律：**除"从哪里出网"外一切相同** —— 同 URL / 同 UA / 同身份四件套 header / 同模型 /
+//   同 `stream:true` + 五核心工具名；整轮共用同一个 session（免费层按出口 IP 计额，共用 session 才测得干净）。
+// 请求形状**直接复用** `v6pool/selftest.js`（同一份免费层契约，绝不在两处各写一遍）。
+import { getUndici } from "../compat.js";
+import { genId } from "../opencode-identity.js";
+import { DEFAULT_PROBE_MODEL, probeUpstreamFrom } from "../v6pool/selftest.js";
+import { classifyWarpSignal } from "../warp-pool/verdict.js";
+import { resolveMultiIpConfig, resolveRole } from "./config.js";
+import { candidateNodes, fetchNodes, loadNodeCache, materializeNode, probeExitIp } from "./nodes.js";
+import { bringUpTunnel, checkOpenvpn, isRoot, isSupportedPlatform, tearDownTunnel } from "./tunnel.js";
+import { fmtExitIp, fmtNodePick, fmtNodes, fmtProbe } from "./report.js";
+import { loadGroupsJoined } from "../state.js";
+
+/** 采样上限：VPNGate 免费节点起隧道是秒级操作，别把测试拖成十几分钟。 */
+export const MITEST_MAX = 8;
+export const MITEST_DEFAULT = 3;
+
+/**
+ * 跑一次出口对照测试（本模块不打印，结构化返回给 CLI 渲染）。
+ *
+ * @param {{ env?: object, count?: number, model?: string, baseUrl?: string,
+ *           onProgress?: (ev: object) => void,
+ *           deps?: { joined?, platform?, supported?, isRoot?, checkOpenvpn?, loadNodeCache?, fetchNodes?,
+ *                    materializeNode?, bringUpTunnel?, tearDownTunnel?, agentFactory?, probeExitIp?,
+ *                    probeUpstream?, fetchImpl?, session?, log? } }} opts
+ */
+export async function runMultiIpCompare({ env = process.env, count = MITEST_DEFAULT, model = DEFAULT_PROBE_MODEL, baseUrl = "https://opencode.ai", onProgress, deps = {} } = {}) {
+  const cfg = resolveMultiIpConfig(env);
+  const tick = (ev) => { try { onProgress?.(ev); } catch { /* 渲染出错不打断测试 */ } };
+  const log = deps.log || (() => {});
+
+  if (!cfg.enabled) return { status: "skip", reason: "多出口池已关闭（MSLXDFF_MULTI_IP_POOL=0）", hint: "去掉该 env 或设为 1 再跑" };
+  const role = resolveRole({ mode: cfg.mode, joined: deps.joined ?? loadGroupsJoined() });
+  if (!role.active) return { status: "skip", reason: `本节点角色是 ${role.role}（${role.why}）`, hint: "本功能只给组长做取证；组员请用组长那条出口" };
+  const platform = deps.platform || process.platform;
+  if (!(deps.supported ?? isSupportedPlatform(platform))) {
+    return { status: "skip", reason: `本功能需要 Linux 的 tun 设备与策略路由（当前平台 ${platform}）`, hint: "在 Linux VPS 上跑；其它平台用 mslxdff -v6-pool 或 WARP 池" };
+  }
+  if (!(deps.isRoot ?? isRoot)()) {
+    return { status: "skip", reason: "需要 root（建 tun 设备 + 装策略路由 + 写 rp_filter）", hint: "sudo mslxdff -multi-ip-pool test" };
+  }
+  const openvpn = await (deps.checkOpenvpn || checkOpenvpn)(cfg.openvpnBin);
+  if (!openvpn.ok) return { status: "skip", reason: `${cfg.openvpnBin} 不可用（${openvpn.why}）`, hint: "apt install openvpn" };
+
+  const { Agent } = getUndici();
+  const agentFactory = deps.agentFactory || ((addr) => new Agent({ connect: { localAddress: addr }, connections: 1, keepAliveTimeout: 5_000 }));
+  const probe = deps.probeUpstream || probeUpstreamFrom;
+  const session = deps.session || genId("ses_");
+  const materialize = deps.materializeNode || materializeNode;
+  const startSlot = deps.bringUpTunnel || bringUpTunnel;
+  const stopSlot = deps.tearDownTunnel || tearDownTunnel;
+  const exitProbe = deps.probeExitIp || probeExitIp;
+
+  // 节点表：优先用缓存（不重复打 VPNGate），取不到再拉。
+  const cache = (deps.loadNodeCache || loadNodeCache)({ dir: cfg.dir, ttlMs: cfg.nodesTtlMs });
+  let rows = cache?.rows || [];
+  let source = cache?.source || "(本地缓存)";
+  if (!rows.length) {
+    try {
+      const got = await (deps.fetchNodes || fetchNodes)({ sources: cfg.sources, dir: cfg.dir, timeoutMs: cfg.probeTimeoutMs, log });
+      rows = got.rows;
+      source = got.source;
+    } catch (e) {
+      return { status: "skip", reason: `节点表取不到：${String(e?.message || e)}`, hint: "先在能连 vpngate.net 的网络里跑一次，或设 MSLXDFF_MULTI_IP_SOURCES" };
+    }
+  }
+  tick({ phase: "nodes", source, total: rows.length });
+  log(fmtNodes({ source, total: rows.length, countries: cfg.countries, minScore: cfg.minScore }));
+
+  // ① 基线：直连（系统默认出口）打一条免费层请求
+  tick({ phase: "baseline-start", model });
+  const baseline = await probe({ addr: "", model, baseUrl, agentFactory, fetchImpl: deps.fetchImpl, session });
+  tick({ phase: "baseline-done", ...baseline });
+
+  const picked = candidateNodes({ rows, countries: cfg.countries, minScore: cfg.minScore, scan: Math.max(1, Math.min(MITEST_MAX, Number(count) || MITEST_DEFAULT)) });
+  if (!picked.length) return { status: "skip", reason: "没有满足条件的候选节点（国家/Score 过滤后为空）", hint: "放宽 MSLXDFF_MULTI_IP_MIN_SCORE 或去掉 MSLXDFF_MULTI_IP_COUNTRY" };
+
+  const exits = [];
+  try {
+    for (let i = 0; i < picked.length; i++) {
+      const row = picked[i];
+      const dev = `${cfg.devPrefix}${i}`;
+      tick({ phase: "exit-start", i: i + 1, n: picked.length, row });
+      log(fmtNodePick({ i: i + 1, n: picked.length, row, dev }));
+      let slot = null;
+      try {
+        const node = materialize({ dir: cfg.dir, row });
+        if (!node) throw new Error("节点配置解不开（base64 或 remote 缺失）");
+        slot = await startSlot({ cfg, slotIndex: i, node, deps: { authFile: deps.authFile, runCmdFn: deps.runCmdFn, spawnFn: deps.spawnFn, wait: deps.wait, log } });
+        const exit = await exitProbe({ agent: agentFactory(slot.tunIp), timeoutMs: cfg.probeTimeoutMs });
+        if (exit.ok) log(fmtExitIp({ dev: slot.dev, ip: exit.ip, ms: exit.ms }));
+        // 从这条隧道的出口打**同一条**免费层请求
+        const r = await probe({ addr: slot.tunIp, model, baseUrl, agentFactory, fetchImpl: deps.fetchImpl, session });
+        log(fmtProbe({ dev: slot.dev, url: `${baseUrl.replace(/\/+$/, "")}/zen/v1/chat/completions`, ok: r.ok, status: r.status, error: r.error, ms: r.ms }));
+        const entry = { ...r, hostName: row.hostName, country: row.countryShort, dev: slot.dev, exitIp: exit.ip || "" };
+        exits.push(entry);
+        tick({ phase: "exit-done", i: i + 1, n: picked.length, ...entry });
+      } catch (e) {
+        const entry = { hostName: row.hostName, country: row.countryShort, dev, ok: false, status: 0, kind: "network", ms: 0, exitIp: "", error: String(e?.message || e) };
+        exits.push(entry);
+        tick({ phase: "exit-done", i: i + 1, n: picked.length, ...entry });
+      } finally {
+        if (slot) await stopSlot({ slot, runCmdFn: deps.runCmdFn, log }).catch(() => {});
+      }
+    }
+  } catch (e) {
+    return { status: "skip", reason: `测试中断：${String(e?.message || e)}`, hint: "看 daemon.log 里的 [multi-ip-pool] 行" };
+  }
+
+  // ③ 判语：对照基线（受限 = 有 HTTP 响应但拿不到额度；只有 status=0 才算"够不着"）
+  const baseLimited = baseline.status === 429 || ["free-quota", "free-tier", "ip-limit"].includes(baseline.kind);
+  const ok = exits.filter((r) => r.ok);
+  const limited = exits.filter((r) => !r.ok && r.status);
+  const net = exits.filter((r) => !r.status);
+  let verdict;
+  if (ok.length && ok.length === exits.length) verdict = "multi-ip-works";
+  else if (limited.length === exits.length) verdict = "multi-ip-also-limited";
+  else if (net.length === exits.length) verdict = "multi-ip-unreachable";
+  else verdict = "mixed";
+
+  return {
+    status: "ok",
+    source, model, baseUrl, session,
+    baseLimited,
+    baseline,
+    exits,
+    requested: picked.length,
+    okCount: ok.length,
+    limitedCount: limited.length,
+    netCount: net.length,
+    verdict,
+  };
+}
+
+/** 判语 → 人话（CLI 与测试共用一份，避免两处口径漂移）。 */
+export const VERDICT_ZH = {
+  "multi-ip-works": {
+    text: "VPN 出口**能换到新额度**",
+    next: "结论：多出口池对这台机器**有用**——直连出口耗尽时换隧道就能续。daemon 侧缺省已开。",
+  },
+  "multi-ip-also-limited": {
+    text: "VPN 出口**也全受限**（换 IP 没换来新额度）",
+    next: "结论：换出口治不了（要么上游不按出口 IP 计额，要么节点出口本身已被大量共用到撞额）。建议 MSLXDFF_MULTI_IP_POOL=0。",
+  },
+  "multi-ip-unreachable": {
+    text: "VPN 出口**全都够不着上游**（隧道没转起来）",
+    next: "结论：这些节点起不通或上游被墙。查 rp_filter / 节点可用性，或换 MSLXDFF_MULTI_IP_SOURCES / 加国家白名单。",
+  },
+  mixed: {
+    text: "部分可用（有的出口有额度、有的没有）",
+    next: "结论：池**部分可用**（免费节点质量参差，属正常）。够用即可开着。",
+  },
+};
+
+/** 判语里的免费层分类（与生产判决同源：warp-pool/verdict.js）。 */
+export function classifyOf(status, text = "") {
+  return classifyWarpSignal({ status, text });
+}

package/src/multi-ip-pool/standby.js

@@ -0,0 +1,157 @@
+// multi-ip-pool · 备选出口池：**定时预拨** 不多于 N 条已验通的隧道，429 一到立刻有干净 IP 可上。
+//
+// 用户 2026-10-25 的裁决（本模块存在的唯一理由）：
+//   「启用时定时准备不多于 5 个备选 IP（例如每小时找 5 个备用），一旦组长触发 429，
+//    可以**立即**启用其中的备用 IP；启用备用 IP 时要打一个 hi 到 opencode.ai，要它 200。」
+// ⇒ 换出口那一刻绝不能再现场拨号（openvpn 握手秒级 + 候选可能全不通，429 现场等 = 用户在等），
+//   而是**平时就把备用隧道起好、并逐条用 hi 验过有 200**，429 时只做"取一条"。
+//
+// 备用条目两条铁律：
+//   ① 只有 hi 回 200 的才算"备用"（有额度的 IP），429/403 的当场拆掉重拨下一条；
+//   ② 交付前**再验一次** hi——免费节点的出口 IP 是别人在用的，一小时里可能已经被别人吃光额度。
+//      验不过就丢掉取下一条（宁可少一条出口，也不把一个没额度的 IP 交给请求路径）。
+import { fmtStandbyAdd, fmtStandbyDrop, fmtStandbyRefill, fmtStandbySkip, fmtStandbyUse } from "./report.js";
+
+/** 备用槽的索引偏移：设备名/表号与正式槽彻底错开（正式槽 mltun0..、备用 mltun100..、表 baseTable+100..）。 */
+export const STANDBY_INDEX_BASE = 100;
+/** 备用槽索引循环上限（设备名 ≤15 字符：mltun + 3 位）。 */
+export const STANDBY_INDEX_SPAN = 100;
+/** 一轮补位最多拨多少次（防候选全不通时把 VPNGate 与本机刷成灾）。 */
+export const REFILL_DIAL_CAP = 12;
+
+/**
+ * @param {{ cfg: object, log?: Function, dialer: object,
+ *           schedule?: (fn: Function, ms: number) => any, cancel?: (h: any) => void, now?: () => number }} opts
+ *   dialer 需要提供：openSlot(index) / ensureCandidates({force}) / hiProbe(entry) / drop(entry) / tunnels(Set)
+ */
+export function createStandby({ cfg, log = () => {}, dialer, schedule = (fn, ms) => setInterval(fn, ms), cancel = (h) => clearInterval(h), now = Date.now } = {}) {
+  /** @type {object[]} 已验通的备用出口（FIFO，最旧的先交出去） */
+  const ready = [];
+  let timer = null;
+  let busy = null;
+  let counter = 0;
+
+  function want() {
+    return Math.max(0, Math.min(5, Number(cfg.standby) || 0)); // 用户定的硬上限：不多于 5
+  }
+
+  function stats() {
+    return {
+      want: want(),
+      have: ready.length,
+      everyMs: Number(cfg.standbyEveryMs) || 0,
+      exits: ready.map((e) => ({ dev: e.dev, node: e.node?.hostName || "", tunIp: e.tunIp, exitIp: e.exitIp || "", verifiedAt: e.verifiedAt || 0 })),
+    };
+  }
+
+  /** 拨一条新备用隧道并验它（不 200 就地拆掉，调用方继续下一条）。 */
+  async function dialOne() {
+    const index = STANDBY_INDEX_BASE + (counter++ % STANDBY_INDEX_SPAN);
+    const e = await dialer.openSlot(index, { dev: "" });
+    if (!e) return null;
+    e.verifiedAt = now();
+    ready.push(e);
+    log(fmtStandbyAdd({ dev: e.dev, node: e.node?.hostName || "", exitIp: e.exitIp || "", tunIp: e.tunIp, have: ready.length, want: want() }));
+    return e;
+  }
+
+  /**
+   * 补到 want() 条。同一时刻只跑一轮（定时器与 429 后的补位会撞车）；每轮开头强制重取节点表——
+   * 免费节点掉得快，一小时前的候选表多半已经拨不通了。
+   * @returns {Promise<{added: number, have: number, want: number}>}
+   */
+  function refill({ force = false } = {}) {
+    if (!want()) return Promise.resolve({ added: 0, have: 0, want: 0 });
+    if (busy) return busy;
+    const run = async () => {
+      if (force || ready.length < want()) {
+        try {
+          await dialer.ensureCandidates({ force: force || ready.length === 0 });
+        } catch (e) {
+          log(fmtStandbySkip({ why: `取节点表失败：${String(e?.message || e)}` }));
+        }
+      }
+      let dialed = 0;
+      const before = ready.length;
+      while (ready.length < want() && dialed < REFILL_DIAL_CAP) {
+        dialed++;
+        try {
+          const got = await dialOne();
+          if (!got) break; // 候选用尽（openSlot 内部已换过一轮）
+        } catch (e) {
+          log(fmtStandbySkip({ why: `拨备用隧道出错：${String(e?.message || e)}` }));
+        }
+      }
+      log(fmtStandbyRefill({ added: ready.length - before, have: ready.length, want: want(), dialed }));
+      return { added: ready.length - before, have: ready.length, want: want() };
+    };
+    busy = run().finally(() => {
+      busy = null;
+    });
+    return busy;
+  }
+
+  /** 复验一条备用出口：交出去之前必须**这一秒**还是 200。 */
+  async function verify(entry) {
+    const p = await dialer.hiProbe(entry);
+    if (p.status === 200) {
+      entry.exitIp = p.ip || entry.exitIp || "";
+      entry.verifiedAt = now();
+      return entry;
+    }
+    log(fmtStandbyDrop({ dev: entry.dev, node: entry.node?.hostName || "", status: p.status, kind: p.kind, error: p.error || "" }));
+    await dialer.drop(entry, "备用出口复验未过 200");
+    return null;
+  }
+
+  /**
+   * 取一条备用出口（429 路径调这个）：逐条复验、验不过就丢；池空了先补一轮再取。
+   * @returns {Promise<null | object>} 验通的出口条目（可直接当新槽用）
+   */
+  async function take() {
+    for (let guard = 0; guard < 2 && !ready.length; guard++) await refill();
+    while (ready.length) {
+      const e = ready.shift();
+      const okEntry = await verify(e);
+      if (okEntry) {
+        log(fmtStandbyUse({ dev: okEntry.dev, tunIp: okEntry.tunIp, exitIp: okEntry.exitIp || "", node: okEntry.node?.hostName || "", left: ready.length }));
+        void refill().catch(() => {}); // 用完立刻补位，下一发 429 还得有备胎
+        return okEntry;
+      }
+    }
+    return null;
+  }
+
+  /** 起定时器（每小时刷新）。`MSLXDFF_MULTI_IP_STANDBY=0` ⇒ 完全不起。 */
+  function start() {
+    const w = want();
+    const every = Number(cfg.standbyEveryMs) || 0;
+    if (!w || !every || timer) return;
+    timer = schedule(() => {
+      void refreshAll().catch((e) => log(fmtStandbySkip({ why: `定时刷新失败：${String(e?.message || e)}` })));
+    }, every);
+  }
+
+  /** 周期到点：把旧的备用全部拆掉重拨一批（出口 IP 换新，才叫"每小时找 5 个备用"）。 */
+  async function refreshAll() {
+    const stale = ready.splice(0, ready.length);
+    for (const e of stale) await dialer.drop(e, "备选池整批刷新");
+    return refill({ force: true });
+  }
+
+  /** 收摊：停定时器 + 拆掉所有备用隧道（一条都不许留给下次启动当残留）。 */
+  async function stop() {
+    if (timer) {
+      try {
+        cancel(timer);
+      } catch {
+        /* 忽略 */
+      }
+      timer = null;
+    }
+    const all = ready.splice(0, ready.length);
+    for (const e of all) await dialer.drop(e, "收摊");
+  }
+
+  return { refill, take, start, stop, refreshAll, stats, get size() { return ready.length; } };
+}