mslxdff 0.1.239 → 0.1.241

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

@@ -0,0 +1,244 @@
+// multi-ip-pool · 槽位 dispatcher：每槽一条隧道 + 一个把源地址绑到 tun 地址的 undici Agent。
+//
+// 契约与 v6pool/warp-pool 的 dispatcher 完全一致：`dispatch(opts, handler)` + `close()`，
+// 注入点同为 transport 的 extDispatcher（legacy 与 SDK 两条路共用同一个对象）。
+// 与 v6 池的差别只在「换出口」这一步里干了什么：
+//   v6  ：换个源地址（≈0 成本）
+//   这里：拆掉旧隧道 + 用下一个 VPNGate 节点起新隧道（秒级；所以**绝不用于请求内换址**）
+//
+// 判决表复用 warp-pool/verdict.js（403 FreeTierError 与 429 FreeUsageLimitError 同判、强制换，
+// BlackUsageLimitError 绝不换）——与生产同源，不自造一套。
+import { getUndici } from "../compat.js";
+import { headerValue, tapHandler } from "../warp-pool/rotate.js";
+import { createSelector } from "../warp-pool/strategy.js";
+import { SIGNAL_STATUSES, classifyWarpSignal } from "../warp-pool/verdict.js";
+import { fmtDirect, fmtExitIp, fmtExitIpFail, fmtFirstOk, fmtNoRotate, fmtSwap, fmtSwapFail, fmtVerdictNo } from "./report.js";
+
+const SESSION_HEADER = "x-opencode-session";
+
+/** 每槽 Agent 的连接池参数（与 v6pool 同口径：注入 dispatcher 后 transport 不自带池）。 */
+export const AGENT_OPTIONS = { connections: 4, pipelining: 1, keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000 };
+
+/** 误关旧 Agent 不影响新出口，但也不该静默吞掉（只在 debug 里报）。 */
+function closeQuietly(agent, log) {
+  try {
+    Promise.resolve(agent?.close?.()).catch((e) => log(`[multi-ip-pool] 关旧出口 Agent 失败：${String(e?.message || e)}`));
+  } catch (e) {
+    log(`[multi-ip-pool] 关旧出口 Agent 抛错：${String(e?.message || e)}`);
+  }
+}
+
+/**
+ * @param {{ slots?: object[], strategy?: "session"|"request", cooldownMs?: number, rotate?: boolean,
+ *           now?: () => number, log?: (s: string) => void,
+ *           agentFactory?: (addr: string) => object, fallbackAgent?: object, agentOptions?: object,
+ *           selector?: object, rebuild?: (index: number, prev: object) => Promise<object>,
+ *           verifyExit?: (t: object) => Promise<{ ok: boolean, ip?: string, ms?: number, error?: string }> }} [opts]
+ */
+export function createMultiIpDispatcher({
+  slots = [],
+  strategy = "session",
+  cooldownMs = 600_000,
+  rotate = true,
+  now = Date.now,
+  log = () => {},
+  agentFactory,
+  fallbackAgent,
+  agentOptions = AGENT_OPTIONS,
+  selector = createSelector({ strategy }),
+  rebuild = null,
+  verifyExit = null,
+} = {}) {
+  const { Agent } = getUndici();
+  if (typeof agentFactory !== "function") {
+    if (typeof Agent !== "function") throw new Error("undici Agent 不可用：无法建立多出口池");
+    agentFactory = (addr) => new Agent({ connect: { localAddress: addr }, ...agentOptions });
+  }
+  // 空池兜底 = 直连：池还没建好（或全槽不可用）时行为与未启用完全一致。
+  const fallback = fallbackAgent !== undefined ? fallbackAgent : typeof Agent === "function" ? new Agent(agentOptions) : null;
+
+  let list = [];
+  const history = [];
+  let directWarned = false;
+
+  function buildSlot(index, t) {
+    return {
+      index,
+      node: t.node || null,
+      dev: t.dev,
+      tunIp: t.tunIp || "",
+      table: t.table,
+      priority: t.priority,
+      stop: t.stop,
+      exitIp: t.exitIp || "",
+      agent: t.tunIp ? agentFactory(t.tunIp) : null,
+      cooldownUntil: 0,
+      swapping: false,
+      swaps: 0,
+      counts: {},
+      firstOkAt: 0,
+    };
+  }
+
+  /** 装上初始槽（bootstrap 探活通过后调用；空数组 = 池为空 ⇒ 直连兜底）。 */
+  async function setSlots(next = []) {
+    const old = list;
+    list = (next || []).map((t, i) => buildSlot(i, t));
+    for (const e of old) closeQuietly(e.agent, log);
+    return list.length;
+  }
+
+  function availableIndexes() {
+    const t = now();
+    return list.filter((e) => e.agent && e.cooldownUntil <= t && !e.swapping).map((e) => e.index);
+  }
+
+  function markFailure(index) {
+    const e = list[index];
+    if (!e) return;
+    e.cooldownUntil = now() + cooldownMs;
+  }
+
+  function markOk(index) {
+    const e = list[index];
+    if (e) e.cooldownUntil = 0;
+  }
+
+  /**
+   * 换该槽的出口：挑下一个候选节点起新隧道（rebuild 由 index.js 提供，含拆旧/起新/探活）。
+   * 失败时**绝不假装成功**：把该槽标记为无出口（tunIp 置空 ⇒ 不再被选中），并如实报错。
+   * @returns {Promise<{ok?: boolean, skipped?: boolean, from?: string, to?: string, reason?: string}>}
+   */
+  async function swap(index, verdict = {}) {
+    const e = list[index];
+    if (!e) return { skipped: true, reason: "槽不存在" };
+    if (e.swapping) return { skipped: true, reason: "该槽已在换出口中" };
+    if (!rebuild) return { skipped: true, reason: "没有配置换出口实现（rebuild）" };
+    e.swapping = true;
+    const prev = { dev: e.dev, tunIp: e.tunIp, node: e.node, agent: e.agent, stop: e.stop, exitIp: e.exitIp, counts: { ...e.counts }, swaps: e.swaps };
+    try {
+      const t = await rebuild(index, prev);
+      if (!t || !t.tunIp) throw new Error("换出口没拿到可用的新隧道");
+      const exit = verifyExit ? await verifyExit(t) : null;
+      e.node = t.node || null;
+      e.dev = t.dev || e.dev;
+      e.tunIp = t.tunIp;
+      e.table = t.table ?? e.table;
+      e.priority = t.priority ?? e.priority;
+      e.stop = t.stop || null;
+      e.exitIp = exit?.ip || t.exitIp || e.exitIp;
+      e.agent = agentFactory(t.tunIp);
+      e.cooldownUntil = 0;
+      e.swaps = prev.swaps + 1;
+      e.counts = {};
+      e.firstOkAt = 0;
+      closeQuietly(prev.agent, log);
+      log(fmtSwap({ dev: e.dev, from: prev.tunIp, to: e.tunIp, status: verdict.status, kind: verdict.kind, forced: verdict.forced, swaps: e.swaps }));
+      if (exit && !exit.ok) log(fmtExitIpFail({ dev: e.dev, error: exit.error }));
+      else if (exit) log(fmtExitIp({ dev: e.dev, ip: exit.ip, ms: exit.ms, prev: prev.exitIp }));
+      history.push({ dev: e.dev, tunIp: e.tunIp, swaps: e.swaps, counts: { ...prev.counts }, exitIp: e.exitIp });
+      if (history.length > 32) history.shift();
+      return { ok: true, from: prev.tunIp, to: e.tunIp, node: e.node };
+    } catch (err) {
+      // 旧隧道可能已经被拆掉了 ⇒ 这槽当前没有出口，必须置空（否则会被选中并挂到超时）
+      e.agent = null;
+      e.tunIp = "";
+      e.cooldownUntil = now() + cooldownMs;
+      log(fmtSwapFail({ dev: prev.dev, error: String(err?.message || err) }));
+      return { skipped: false, error: String(err?.message || err) };
+    } finally {
+      e.swapping = false;
+    }
+  }
+
+  /** 上游响应旁听：记账 → 换出口后首个 200 的取证行 → 配额信号才换出口。 */
+  function onTap(signal, e) {
+    const status = Number(signal?.status);
+    e.counts[status] = (e.counts[status] || 0) + 1;
+    if (status === 200 && !e.firstOkAt) {
+      e.firstOkAt = now();
+      log(fmtFirstOk({ dev: e.dev, ip: e.exitIp || e.tunIp, swaps: e.swaps, counts: e.counts }));
+    }
+    if (!SIGNAL_STATUSES.includes(status)) return;
+    const v = classifyWarpSignal(signal);
+    if (!rotate) {
+      log(fmtNoRotate({ dev: e.dev, status, kind: v.kind }));
+      return;
+    }
+    if (!v.rotate) {
+      log(fmtVerdictNo({ dev: e.dev, status, kind: v.kind, why: v.why }));
+      return;
+    }
+    const dev = e.dev;
+    void swap(e.index, { ...v, status }).catch((err) => log(fmtSwapFail({ dev, error: String(err?.message || err) })));
+  }
+
+  return {
+    /** 每次请求调一次 = 选槽粒度（session 策略下同会话粘同一出口）。 */
+    dispatch(opts, handler) {
+      const avail = availableIndexes();
+      if (!avail.length) {
+        // 空池/全槽不可用 ⇒ 直连兜底（行为与未启用一致），绝不硬派给已知不可用的槽。
+        if (!list.length || !list.some((e) => e.agent)) {
+          if (fallback) return fallback.dispatch(opts, handler);
+          throw new Error("multi-ip-pool：出口池为空且无直连兜底");
+        }
+        if (!directWarned) {
+          directWarned = true;
+          log(fmtDirect({ reason: `全部 ${list.length} 条隧道都在冷却/换出口中（下一条恢复后自动回到池内）` }));
+        }
+        return (fallback || list[0].agent).dispatch(opts, handler);
+      }
+      directWarned = false;
+      const sessionKey = strategy === "session" ? headerValue(opts?.headers, SESSION_HEADER) : "";
+      const e = list[selector.pick(avail, sessionKey)];
+      return e.agent.dispatch(opts, tapHandler(handler, (sig) => onTap(sig, e)));
+    },
+
+    setSlots,
+
+    /** 手动换某槽出口（供运维/测试；正常路径由配额信号触发）。 */
+    swap,
+
+    /** 只读快照（换出口后首个 200 是否出现 = 「换 IP 有没有换来新额度」的证据）。 */
+    stats() {
+      const t = now();
+      return {
+        slots: list.map((e) => ({
+          dev: e.dev,
+          tunIp: e.tunIp,
+          exitIp: e.exitIp,
+          node: e.node?.hostName || "",
+          cooling: e.cooldownUntil > t,
+          swapping: e.swapping,
+          swaps: e.swaps,
+          counts: { ...e.counts },
+          firstOk: !!e.firstOkAt,
+        })),
+        history: history.map((h) => ({ ...h, counts: { ...h.counts } })),
+      };
+    },
+
+    entries() {
+      return list.map((e) => ({ index: e.index, dev: e.dev, tunIp: e.tunIp, cooldownUntil: e.cooldownUntil, swaps: e.swaps }));
+    },
+
+    async close() {
+      const old = list;
+      list = [];
+      for (const e of old) closeQuietly(e.agent, log);
+      if (fallback) closeQuietly(fallback, log);
+    },
+
+    async destroy() {
+      return this.close();
+    },
+
+    markFailure,
+    markOk,
+
+    get size() {
+      return list.length;
+    },
+  };
+}

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

@@ -0,0 +1,174 @@
+// multi-ip-pool · 装配入口（MODULES.md §0/§2）：只做「门 + 接线 + 生命周期」，
+// 拨号与体检在 dial.js、备选池在 standby.js、选槽与换槽在 dispatch.js（每件事各自可单测）。
+//
+// 定位：**只有组长启用的第三.种出口源**——用 VPNGate 免费 OpenVPN 节点换出口 IP，专供 opencode 免费层。
+// 用户 2026-10-25 的四条裁决（本文件的形状就是这四条）：
+//   ① 只有组长建池（组员与没带组的单机都不建，强开需显式 MODE=leader）；
+//   ② 只有 Linux（tun 设备 + ip rule）；
+//   ③ 定时预拨**不多于 5** 条备选 IP（缺省每小时重拨一批），429 一到立即启用备胎，不现场拨号；
+//   ④ 启用备用 IP 时**打一个 hi 到 opencode.ai，要它 200** —— 没 200 的出口不算可用，也不配当备用。
+//
+// 门（任一不过 ⇒ 返回 null，调用方据此不注入，行为与未启用完全一致）：
+//   开关 → 角色 → 平台 → root → openvpn 可执行（最后一条在 bootstrap 里判，绝不阻塞启动）。
+import { resolveMultiIpConfig, resolveRole } from "./config.js";
+import { createDialer } from "./dial.js";
+import { createStandby } from "./standby.js";
+import { createMultiIpDispatcher as createDispatcher } from "./dispatch.js";
+import { writeAuthFile } from "./nodes.js";
+import { checkOpenvpn, isRoot, isSupportedPlatform } from "./tunnel.js";
+import { fmtClose, fmtConfig, fmtDisabled, fmtNoOpenvpn, fmtNoRoot, fmtPlatformSkip, fmtPool, fmtPoolEmpty, fmtRoleOk, fmtRoleSkip } from "./report.js";
+import { loadGroupsJoined } from "../state.js";
+
+/**
+ * @param {{ env?: object, baseUrl?: string, log?: (s: string) => void,
+ *           deps?: { joined?, platform?, supported?, isRoot?, checkOpenvpn?, authFile?, schedule?, cancel?,
+ *                    bringUpTunnel?, tearDownTunnel?, materializeNode?, fetchNodes?, loadNodeCache?,
+ *                    probeExitIp?, probeHi?, agentFactory?, fetchImpl?, runCmdFn?, spawnFn?, wait?, exitHook? } }} [opts]
+ * @returns {null | { dispatcher, standby, ready, config, role, close, stats }}
+ */
+export function createMultiIpPool({ env = process.env, baseUrl = "https://opencode.ai", log = (m) => console.error(m), deps = {} } = {}) {
+  const cfg = resolveMultiIpConfig(env);
+  if (!cfg.enabled) {
+    log(fmtDisabled());
+    return null;
+  }
+  // ① 角色门：只有组长（裁决 2026-10-25，从"组长或单机"收紧为"只有组长"）
+  const role = resolveRole({ mode: cfg.mode, joined: deps.joined ?? loadGroupsJoined() });
+  if (!role.active) {
+    log(fmtRoleSkip(role));
+    return null;
+  }
+  // ② 平台门：只有 Linux
+  const platform = deps.platform || process.platform;
+  if (!(deps.supported ?? isSupportedPlatform(platform))) {
+    log(fmtPlatformSkip({ platform, why: "本功能只在 Linux 上可用" }));
+    return null;
+  }
+  // ③ 权限门
+  if (!(deps.isRoot ?? isRoot)()) {
+    log(fmtNoRoot());
+    return null;
+  }
+  log(fmtConfig(cfg));
+  log(fmtRoleOk(role));
+
+  const dialer = createDialer({ cfg, baseUrl, log, deps });
+  const standby = createStandby({ cfg, log, dialer, schedule: deps.schedule, cancel: deps.cancel, now: deps.now });
+  let closed = false;
+
+  const dispatcher = createDispatcher({
+    slots: [],
+    strategy: cfg.strategy,
+    cooldownMs: cfg.cooldownMs,
+    rotate: cfg.rotate,
+    log,
+    agentFactory: dialer.agentFactory,
+    /**
+     * 换出口（429 路径）：**先用备选池里已验通的备胎**（裁决③的"立即启用"），
+     * 备胎为空才现场拨一条新的（拨号内部同样要过 hi 200 闸门）。
+     * 旧隧道在拿到新出口**之后**才拆：换出口全程都有一条能用的出口，不把池打空。
+     */
+    rebuild: async (index, prev) => {
+      const spare = cfg.standby ? await standby.take() : null;
+      const opened = spare || (await dialer.openSlot(index, { dev: prev?.dev || "" }));
+      if (!opened) throw new Error("备选池为空且候选节点都没通过 hi 验，本槽暂时没有出口");
+      if (prev) await dialer.drop(prev, "换出口后拆旧隧道");
+      return opened;
+    },
+  });
+
+  async function bootstrap() {
+    if (closed) return;
+    const openvpn = await (deps.checkOpenvpn || checkOpenvpn)(cfg.openvpnBin, { runCmdFn: deps.runCmdFn });
+    if (!openvpn.ok) {
+      log(fmtNoOpenvpn({ bin: cfg.openvpnBin, why: openvpn.why }));
+      return;
+    }
+    dialer.setAuthFile(deps.authFile || writeAuthFile({ dir: cfg.dir, user: cfg.authUser, pass: cfg.authPass }));
+
+    try {
+      await dialer.ensureCandidates();
+    } catch (e) {
+      log(fmtPoolEmpty({ tried: 0, why: `节点表取不到：${String(e?.message || e)}` }));
+      return;
+    }
+
+    const slots = [];
+    for (let i = 0; i < cfg.count; i++) {
+      if (closed) return;
+      const opened = await dialer.openSlot(i);
+      if (!opened) break;
+      slots.push(opened);
+    }
+    if (slots.length) {
+      await dispatcher.setSlots(slots);
+      log(fmtPool({ pooled: slots.length, tried: dialer.used.size, exits: slots.map((s) => s.exitIp || "(未取证)") }));
+    } else {
+      log(fmtPoolEmpty({ tried: dialer.used.size, why: "候选节点都没起通、或起来后 hi 拿不到 200（可能被墙 / 节点已下线 / 额度被同出口的其他人吃光）" }));
+    }
+
+    // ③ 备选池：正式槽成没成都要起（备胎本身就是"下一次 429 的出口"），并按小时刷新
+    if (cfg.standby) {
+      standby.start();
+      void standby.refill({ force: true }).catch((e) => log(`[multi-ip-pool] 备选池首轮补位失败：${String(e?.message || e)}`));
+    }
+  }
+
+  // 退出兜底：daemon 被强杀时 `exit` 钩子仍会跑；这里只能做同步事——把每条隧道的子进程都收掉
+  // （openvpn 子进程留着 = 白占 tun 设备与策略路由表，下次启动还得人工清）。
+  if (deps.exitHook !== false) {
+    process.once("exit", () => {
+      closed = true;
+      for (const t of dialer.tunnels) {
+        try {
+          t.stop?.();
+        } catch {
+          /* 已经退了 */
+        }
+      }
+    });
+  }
+
+  const ready = bootstrap().catch((e) => log(`[multi-ip-pool] bootstrap 失败：${String(e?.message || e)}`));
+
+  return {
+    dispatcher,
+    standby,
+    ready,
+    config: cfg,
+    role,
+    async close() {
+      if (closed) return;
+      closed = true;
+      await standby.stop().catch(() => {}); // 先停定时器，免得收摊路上又补出一批
+      let failed = 0;
+      const all = [...dialer.tunnels];
+      for (const t of all) {
+        try {
+          await dialer.drop(t, "收摊");
+        } catch {
+          failed += 1;
+        }
+      }
+      await dispatcher.close();
+      log(fmtClose({ closed: all.length - failed, failed }));
+    },
+    stats() {
+      return {
+        enabled: true,
+        role: role.role,
+        count: cfg.count,
+        standbyWant: cfg.standby,
+        tunnels: dialer.tunnels.size,
+        dir: cfg.dir,
+        standby: standby.stats(),
+        ...dispatcher.stats(),
+      };
+    },
+  };
+}
+
+/** 只取 dispatcher 的便捷入口；未启用时返回 undefined（调用方直接透传即"关闭态"）。 */
+export function createMultiIpDispatcher(opts) {
+  return createMultiIpPool(opts)?.dispatcher;
+}

package/src/multi-ip-pool/nodes-fetch.js

@@ -0,0 +1,110 @@
+// multi-ip-pool · 节点表与出口的**网络侧**：取表（多源回退 + 本地表文件）/ 出口 IP 取证 / fetch 失败归因。
+//
+// 为什么单独一份：出口池的成败在受限网络里完全取决于「表取不取得到」，这一层的诊断信息
+// （DNS 污染 / 连接被掐 / 超时）必须与解析层分开演进。纯解析与落盘在 ./nodes.js，本文件只碰网络。
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { compatFetch, getUndici, timeoutSignal } from "../compat.js";
+import { EXIT_PROBE_URL, parseExitIp } from "../warp-pool/revive.js";
+import { parseVpnGateCsv, saveNodeCache } from "./nodes.js";
+
+/**
+ * fetch 失败的人话原因：undici 一律只回 `fetch failed`，真凶在 `e.cause`。
+ * 这个区分是**功能性的**：受限网络下 ENOTFOUND（DNS 污染）与 ECONNRESET（连接被掐）
+ * 与超时（IP 被墙）意味着完全不同的对策，糊成一句「fetch failed」等于没诊断。
+ */
+export function describeFetchError(e) {
+  const c = e?.cause || {};
+  const code = String(c.code || c.errno || "");
+  const msg = String(c.message || e?.message || "");
+  if (code === "ENOTFOUND") return "DNS 解析失败 ENOTFOUND（域名可能被污染或不存在）";
+  if (code === "EAI_AGAIN") return "DNS 暂时解析不了 EAI_AGAIN（当前网络解析不了这个域）";
+  if (code === "ECONNREFUSED") return "连接被拒 ECONNREFUSED（端口没开或服务已下线）";
+  if (code === "ECONNRESET" || code === "EPIPE") return "连接被重置 ECONNRESET（中途被掐断，常见于墙/防火墙）";
+  if (code === "ETIMEDOUT" || /timeout|timed out|deadline|abort/i.test(msg)) return "连接超时（IP 不可达或被静默丢包）";
+  if (/cert|self-signed|SSL|TLS|handshake/i.test(msg + code)) return `TLS 握手失败 ${code || msg}`.trim();
+  if (code) return `网络失败 ${code}`;
+  return (msg || String(e || "未知原因")).slice(0, 70);
+}
+
+/** 把任何异常归成人话（有 cause 走 fetch 归因，否则取 message）。 */
+export function errorWhy(e) {
+  return e && e.cause ? describeFetchError(e) : String(e?.message || e);
+}
+
+/** 节点源 scheme 判定：`http(s)://` 走 fetch；`file://` 与裸路径都当**本地表文件**（受限网络「抓一份带过去」）。 */
+export function sourceToLocalPath(url) {
+  const s = String(url || "").trim();
+  if (!s || /^https?:\/\//i.test(s)) return null;
+  if (/^file:\/\/\//i.test(s) || /^file:\/\//i.test(s)) {
+    try {
+      return fileURLToPath(s);
+    } catch {
+      return s.replace(/^file:\/\/\/?/i, "");
+    }
+  }
+  return s;
+}
+
+/**
+ * 逐源尝试取表；任一源返回可解析的 CSV 即成功（并顺手写缓存）。
+ * 全失败时**逐源原因都进异常**（受限网络下「为什么取不到」就是用户唯一的线索）。
+ * @returns {Promise<{ source: string, rows: object[], text: string }>} text 是原始 CSV，供 `fetchNodesToFile` 落盘
+ */
+export async function fetchNodes({ sources = [], dir = "", fetchImpl, timeoutMs = 20_000, now = () => Date.now(), log = () => {} } = {}) {
+  const f = fetchImpl || getUndici().fetch || compatFetch;
+  const fails = [];
+  for (const url of sources) {
+    try {
+      const local = sourceToLocalPath(url);
+      let text = "";
+      if (local !== null) {
+        text = readFileSync(local, "utf8");
+      } else {
+        const res = await f(url, { signal: timeoutSignal(timeoutMs) });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        text = await res.text();
+      }
+      const rows = parseVpnGateCsv(text);
+      if (!rows.length) throw new Error("返回体不是可解析的 VPNGate CSV");
+      log(`[multi-ip-pool] 节点表取自 ${url}（${rows.length} 个节点）`);
+      if (dir) saveNodeCache({ dir, source: url, rows, now });
+      return { source: url, rows, text };
+    } catch (e) {
+      const why = errorWhy(e);
+      fails.push(`${url}：${why}`);
+      log(`[multi-ip-pool] 节点源失败 ${url}：${why}`);
+    }
+  }
+  throw new Error(fails.length ? `全部 ${fails.length} 个节点源都失败 → ${fails.join(" ｜ ")}` : "没配任何节点源（MSLXDFF_MULTI_IP_SOURCES 为空）");
+}
+
+/**
+ * 取表并原样落一份 CSV（`-multi-ip-pool fetch` 的实现）：在能连的机器上抓，scp 进受限网络的组长机，
+ * 那边 `MSLXDFF_MULTI_IP_NODES_FILE=<路径>` 即可零网络取表。0600：表里是节点凭据，不该给同机用户读。
+ */
+export async function fetchNodesToFile({ sources = [], out, fetchImpl, timeoutMs = 20_000, log } = {}) {
+  const got = await fetchNodes({ sources, fetchImpl, timeoutMs, log });
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, got.text, { mode: 0o600 });
+  return { ...got, out, file: out };
+}
+
+/**
+ * 出口取证：从某槽的 tun 地址出网，读回真实出口 IP（照 warp-pool/revive.js 的同源判据）。
+ * 这是「换 IP 到底换没换动」的直接证据——没有它，日志只能说"起了隧道"，说不了"出口变了"。
+ * @returns {Promise<{ ok: boolean, ip: string, ms: number, error?: string }>}
+ */
+export async function probeExitIp({ agent, fetchImpl, timeoutMs = 12_000 } = {}) {
+  const t0 = Date.now();
+  try {
+    const f = fetchImpl || getUndici().fetch || compatFetch;
+    const res = await f(EXIT_PROBE_URL, { ...(agent ? { dispatcher: agent } : {}), signal: timeoutSignal(timeoutMs) });
+    const text = await res.text();
+    const ip = parseExitIp(text);
+    return { ok: Boolean(ip), ip, ms: Date.now() - t0, ...(ip ? {} : { error: `取证响应认不出出口 IP：${text.slice(0, 80)}` }) };
+  } catch (e) {
+    return { ok: false, ip: "", ms: Date.now() - t0, error: errorWhy(e) };
+  }
+}

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

@@ -0,0 +1,150 @@
+// multi-ip-pool · VPNGate 节点表（**纯解析与落盘**侧）：解 CSV → 解 base64 配置 → 筛候选 → 落 conf/缓存。
+//
+// 为什么要拆开：出口 IP 的**来源**就是这些免费志愿者节点（参照实现 aimili-vpngate 用同一份 CSV），
+// 但「取表」在受限网络里是独立的成败关口，它的诊断逻辑单独住在 ./nodes-fetch.js（fetch/归因/出口取证）。
+// 纪律：候选的 conf / auth 一律 0600 落在**非工作树**目录（默认 logDir()/multi-ip-pool）。
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** CSV 列序（VPNGate `/api/iphone/`）：末列是 base64 配置，其余为节点元数据。 */
+export const VPNGATE_FIELDS = [
+  "hostName", "ip", "score", "ping", "speed", "countryLong", "countryShort",
+  "sessions", "uptime", "totalUsers", "totalTraffic", "logType", "operator", "message", "config",
+];
+
+const CACHE_FILE = "nodes.json";
+
+/** 0755 目录 + 0600 文件：conf 里有 VPNGate 的公证书与账号行，不该给同机其它用户读。 */
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writePrivate(file, text) {
+  writeFileSync(file, text, { mode: 0o600 });
+  // mode 只在新建时生效：存量文件补 chmod（照 AGENTS.md 的凭据落地纪律）
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* Windows / 不支持 chmod 的文件系统：忽略 */
+  }
+  return file;
+}
+
+/**
+ * 解析 VPNGate CSV。只认「首列是 hostName 的数据行」：
+ * 以 `*` 开头的是注释行、以 `#` 开头的是表头。
+ * Message 列理论上可能含逗号 ⇒ **末列永远是 config**（base64 不含逗号），中间多余的列并回 message。
+ */
+export function parseVpnGateCsv(text) {
+  const rows = [];
+  for (const rawLine of String(text || "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("*") || line.startsWith("#")) continue;
+    const parts = line.split(",");
+    if (parts.length < VPNGATE_FIELDS.length) continue;
+    const n = parts.length;
+    const row = {
+      hostName: parts[0],
+      ip: parts[1],
+      score: Number(parts[2]) || 0,
+      ping: Number(parts[3]) || 0,
+      speed: Number(parts[4]) || 0,
+      countryLong: parts[5],
+      countryShort: parts[6],
+      sessions: Number(parts[7]) || 0,
+      uptime: Number(parts[8]) || 0,
+      totalUsers: Number(parts[9]) || 0,
+      totalTraffic: Number(parts[10]) || 0,
+      logType: parts[11],
+      operator: parts[12],
+      message: parts.slice(13, n - 1).join(","),
+      config: parts[n - 1],
+    };
+    if (!row.hostName || !row.config) continue;
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** base64 → OpenVPN 配置文本；不是一份能用的 client 配置就返回空串（绝不猜）。 */
+export function decodeConfig(b64) {
+  let text = "";
+  try {
+    text = Buffer.from(String(b64 || ""), "base64").toString("utf8");
+  } catch {
+    return "";
+  }
+  if (!/\bclient\b/.test(text) || !/^\s*remote\s+\S+/m.test(text)) return "";
+  return text;
+}
+
+/** 从配置文本里读出 `remote <host> <port>`（缺端口按 OpenVPN 默认 1194）。 */
+export function parseRemote(conf) {
+  const m = /^\s*remote\s+(\S+)(?:\s+(\d+))?/m.exec(String(conf || ""));
+  if (!m) return null;
+  return { host: m[1], port: m[2] ? Number(m[2]) : 1194 };
+}
+
+/** 国家白名单判据：空 = 不限；否则比对 ISO 两字母或全称（大小写无关）。 */
+export function matchCountry(row, countries = []) {
+  if (!countries.length) return true;
+  const short = String(row?.countryShort || "").toUpperCase();
+  const long = String(row?.countryLong || "").toUpperCase();
+  return countries.some((c) => c === short || c === long);
+}
+
+/**
+ * 候选队列：按 Score 降序（Score 是 VPNGate 官方"还活着且跑得动"的综合分）。
+ * @param {{ rows?: object[], countries?: string[], minScore?: number, scan?: number, skip?: Set<string> }} opts
+ */
+export function candidateNodes({ rows = [], countries = [], minScore = 0, scan = 8, skip = new Set() } = {}) {
+  return rows
+    .filter((r) => r.config && r.score >= minScore && matchCountry(r, countries) && !skip.has(r.hostName))
+    .sort((a, b) => b.score - a.score || a.ping - b.ping)
+    .slice(0, scan);
+}
+
+/** 节点表缓存（TTL 内直接用，省一次外网请求；VPNGate 免费节点掉得快，默认 30min）。 */
+export function loadNodeCache({ dir, ttlMs = 0, now = () => Date.now() } = {}) {
+  try {
+    const raw = JSON.parse(readFileSync(join(dir, CACHE_FILE), "utf8"));
+    if (!Array.isArray(raw?.rows) || !raw.rows.length) return null;
+    if (ttlMs > 0 && now() - Number(raw.fetchedAt || 0) > ttlMs) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+export function saveNodeCache({ dir, source = "", rows = [], now = () => Date.now() } = {}) {
+  ensureDir(dir);
+  const payload = { fetchedAt: now(), source, rows };
+  writePrivate(join(dir, CACHE_FILE), JSON.stringify(payload));
+  return payload;
+}
+
+
+/** 落一份 node conf（设备名/路由由 CLI 覆盖，不改原配置文本）；返回文件路径。 */
+export function writeNodeConf({ dir, row, name = "" } = {}) {
+  ensureDir(dir);
+  const safe = String(row.hostName || "node").replace(/[^\w.-]/g, "_").slice(0, 48);
+  const alias = name || `${safe}-${row.ip}`;
+  return { path: writePrivate(join(dir, `node-${alias}.conf`), row.config), hostName: row.hostName };
+}
+
+/** writeNodeConf 落的是**解码后**的配置；这里显式解码一次，把「解不开」的节点挡在门外（绝不猜）。 */
+export function materializeNode({ dir, row, name = "" } = {}) {
+  const conf = decodeConfig(row.config);
+  if (!conf) return null;
+  const remote = parseRemote(conf);
+  if (!remote) return null;
+  const written = writeNodeConf({ dir, row: { ...row, config: conf }, name });
+  return { ...row, conf: written.path, host: remote.host, port: remote.port };
+}
+
+/** VPNGate 公共账号（vpn/vpn）；落在 0600 文件里，绝不入库。 */
+export function writeAuthFile({ dir, user = "vpn", pass = "vpn" } = {}) {
+  ensureDir(dir);
+  return writePrivate(join(dir, "auth.txt"), `${user}\n${pass}\n`);
+}