mslxdff 0.1.245 → 0.1.246

package/src/v6pool/claim.js

@@ -1,157 +0,0 @@
-// v6pool · 让内核接受池里的源地址（bind 直用 / ip addr add 认领）+ 认领账 + 释放。
-//
-// 两条路（Linux 上 bind() 一个没分配给本机的源地址会直接 EADDRNOTAVAIL）：
-//   bind：net.ipv6.ip_nonlocal_bind=1 ⇒ 直接 bind 任意地址，**不碰网卡**（首选，零副作用）；
-//   add ：ip -6 addr add <addr>/128 dev <iface> nodad ⇒ 加进网卡（需 root）。
-//
-// 为什么要记账（本轮手工实测的教训）：加进网卡的地址会改变内核的**默认源地址选择**——
-// 我在 A 机上留了两个临时地址，结果不带 --interface 的请求也走了新地址（生产机上这是事故）。
-// 所以：每次 add/del 都落 `<dir>/claimed.json`（0600、非工作树）；close 时全部释放；
-// 启动时按这份账清上一代残留（崩溃 / 被 SIGKILL 时 close 跑不到）。
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { execFile, execFileSync } from "node:child_process";
-import { fmtClaim, fmtClaimFail, fmtSweep } from "./report.js";
-
-export const CLAIM_FILE = "claimed.json";
-
-/** 默认执行器：失败时把 stderr 原文带进 Error（不许把 stderr 吞掉——否则只剩「失败了」）。 */
-export function defaultExec(file, args, { timeoutMs = 10_000 } = {}) {
-  return new Promise((resolve, reject) => {
-    execFile(file, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
-      if (err) {
-        const e = new Error(`${file} ${args.join(" ")} 失败：${String(stderr || err.message || "").trim()}`);
-        e.code = err.code;
-        e.stderr = String(stderr || "");
-        reject(e);
-        return;
-      }
-      resolve({ stdout: String(stdout || ""), stderr: String(stderr || "") });
-    });
-  });
-}
-
-/** 退出钩子专用（同步）：`process.on("exit")` 里跑不了 async，但地址必须清。 */
-export function defaultExecSync(file, args, { timeoutMs = 10_000 } = {}) {
-  execFileSync(file, args, { timeout: timeoutMs, stdio: "ignore" });
-}
-
-/** 幂等判据：`ip addr add` 报 File exists = 已经在网卡上了，不算失败。 */
-export function isAlreadyThere(e) {
-  return /File exists|already assigned/i.test(String(e?.stderr || e?.message || ""));
-}
-
-/** 释放时「它已经不在了」也不算失败（上一代残留已被别处清掉 / 手工删掉）。 */
-export function isAlreadyGone(e) {
-  return /Cannot assign requested address|Cannot find device|does not exist/i.test(String(e?.stderr || e?.message || ""));
-}
-
-/**
- * @param {{ iface?: string, mode?: "bind"|"add", dir?: string, log?: (s:string)=>void, exec?: Function, fs?: object }} opts
- */
-export function createClaimer({ iface = "", mode = "bind", dir = "", log = () => {}, exec = defaultExec, fs = { mkdirSync, writeFileSync, chmodSync, readFileSync } } = {}) {
-  /** 只有 add 模式需要记账（bind 模式没改网卡，无残留可言）。 */
-  const claimed = new Set();
-
-  function persist() {
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-      const file = join(dir, CLAIM_FILE);
-      fs.writeFileSync(file, `${JSON.stringify({ iface, mode, addrs: [...claimed], updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
-      fs.chmodSync(file, 0o600); // mode 只在新建时生效，存量必须补
-    } catch (e) {
-      log(`[v6pool] ⚠ 认领账写盘失败（本次照跑，但崩溃后无法自动清残留）：${String(e?.message || e)}`);
-    }
-  }
-
-  async function ensure(addr) {
-    if (mode !== "add") return addr;
-    try {
-      await exec("ip", ["-6", "addr", "add", `${addr}/128`, "dev", iface, "nodad"]);
-      log(fmtClaim({ addr, iface }));
-    } catch (e) {
-      if (!isAlreadyThere(e)) {
-        log(fmtClaimFail({ addr, iface, error: String(e?.message || e) }));
-        throw e;
-      }
-    }
-    claimed.add(addr);
-    persist();
-    return addr;
-  }
-
-  async function release(addr) {
-    if (mode !== "add" || !claimed.has(addr)) return false;
-    claimed.delete(addr);
-    persist();
-    try {
-      await exec("ip", ["-6", "addr", "del", `${addr}/128`, "dev", iface]);
-      return true;
-    } catch (e) {
-      if (isAlreadyGone(e)) return false;
-      log(`[v6pool] ⚠ 释放源地址失败（重启时由启动清残留兜底）：${addr} — ${String(e?.stderr || e?.message || "").trim()}`);
-      return false;
-    }
-  }
-
-  async function releaseAll() {
-    const done = [];
-    for (const a of [...claimed]) if (await release(a)) done.push(a);
-    return done;
-  }
-
-  /** 退出钩子专用：进程正在退出，只能跑同步命令；清不掉的交给下次启动的 sweepStale。 */
-  function releaseAllSync({ execSync = defaultExecSync } = {}) {
-    if (mode !== "add" || !claimed.size) return [];
-    const done = [];
-    for (const a of [...claimed]) {
-      try {
-        execSync("ip", ["-6", "addr", "del", `${a}/128`, "dev", iface]);
-        done.push(a);
-      } catch {
-        /* 删不掉不抛：进程正在退出，抛了也没人接 */
-      }
-    }
-    claimed.clear();
-    return done;
-  }
-
-  /** 启动清残留：只删**上一代自己记在账上的**地址，绝不猜（不扫全表，不碰别人的地址）。 */
-  async function sweepStale() {
-    if (mode !== "add") return { removed: [], failed: [] };
-    let prev = [];
-    try {
-      prev = JSON.parse(fs.readFileSync(join(dir, CLAIM_FILE), "utf8"))?.addrs || [];
-    } catch {
-      return { removed: [], failed: [] };
-    }
-    const removed = [];
-    const failed = [];
-    for (const a of prev) {
-      if (typeof a !== "string" || !a) continue;
-      try {
-        await exec("ip", ["-6", "addr", "del", `${a}/128`, "dev", iface]);
-        removed.push(a);
-      } catch (e) {
-        if (!isAlreadyGone(e)) failed.push({ addr: a, error: String(e?.stderr || e?.message || "").trim() });
-      }
-    }
-    claimed.clear();
-    persist();
-    const r = { removed, failed };
-    if (removed.length || failed.length) log(fmtSweep({ iface, ...r }));
-    return r;
-  }
-
-  return {
-    ensure,
-    release,
-    releaseAll,
-    releaseAllSync,
-    sweepStale,
-    claimed: () => [...claimed],
-    get mode() {
-      return mode;
-    },
-  };
-}

package/src/v6pool/config.js

@@ -1,65 +0,0 @@
-// v6pool · 配置解析：env 优先，缺省值集中一处；纯函数，便于单测。
-import { join } from "node:path";
-import { logDir } from "../logs.js";
-
-/**
- * 缺省**开** + **自动判断**：本机有整段路由的 IPv6 前缀就启用（判据见 detect.js），
- * 没有就诚实跳过（行为与今天完全一致）。判据不靠 env，靠事实。
- */
-export const DEFAULTS = {
-  enabled: true,
-  count: 4,
-  strategy: "session",
-  cooldownMs: 600_000,
-  rotate: true,
-  minHostBits: 8,
-  claim: "auto",
-  probePath: "/zen/v1/models",
-  retireMs: 60_000,
-  debug: false,
-};
-
-const OFF = ["0", "off", "false", "no", "disable", "disabled"];
-const CLAIM_MODES = ["auto", "bind", "add"];
-
-function envBool(env, name, fallback) {
-  const raw = env[name];
-  if (raw === undefined || raw === null || raw === "") return fallback;
-  return !OFF.includes(String(raw).trim().toLowerCase());
-}
-
-function envInt(env, name, fallback) {
-  const v = Number(env[name]);
-  return Number.isInteger(v) && v > 0 ? v : fallback;
-}
-
-function envStr(env, name, fallback) {
-  const raw = env[name];
-  return typeof raw === "string" && raw.trim() ? raw.trim() : fallback;
-}
-
-/**
- * 解析 v6 出口池配置。
- * @param {Record<string,string|undefined>} env
- * @param {{ logDirFn?: () => string }} [deps] 测试可注入 logDir
- */
-export function resolveV6Config(env = process.env, { logDirFn = logDir } = {}) {
-  const strategy = envStr(env, "MSLXDFF_V6_STRATEGY", DEFAULTS.strategy) === "request" ? "request" : "session";
-  const claimRaw = envStr(env, "MSLXDFF_V6_CLAIM", DEFAULTS.claim).toLowerCase();
-  return {
-    enabled: envBool(env, "MSLXDFF_V6_POOL", DEFAULTS.enabled),
-    /** 显式池前缀（`2001:db8::/64`）；空 = 取本机全局地址的前缀 */
-    prefix: envStr(env, "MSLXDFF_V6_PREFIX", ""),
-    iface: envStr(env, "MSLXDFF_V6_IFACE", ""),
-    count: envInt(env, "MSLXDFF_V6_COUNT", DEFAULTS.count),
-    strategy,
-    cooldownMs: envInt(env, "MSLXDFF_V6_COOLDOWN_MS", DEFAULTS.cooldownMs),
-    rotate: envBool(env, "MSLXDFF_V6_ROTATE", DEFAULTS.rotate),
-    minHostBits: envInt(env, "MSLXDFF_V6_MIN_HOST_BITS", DEFAULTS.minHostBits),
-    claim: CLAIM_MODES.includes(claimRaw) ? claimRaw : DEFAULTS.claim,
-    dir: envStr(env, "MSLXDFF_V6_DIR", join(logDirFn(), "v6pool")),
-    probePath: envStr(env, "MSLXDFF_V6_PROBE_PATH", DEFAULTS.probePath),
-    retireMs: envInt(env, "MSLXDFF_V6_RETIRE_MS", DEFAULTS.retireMs),
-    debug: envBool(env, "MSLXDFF_V6_DEBUG", DEFAULTS.debug),
-  };
-}

package/src/v6pool/detect.js

@@ -1,130 +0,0 @@
-// v6pool · 自动判断本机有没有可用的 IPv6 池（纯解析 + 可注入 IO，便于单测）。
-//
-// 四关，任一不过就诚实跳过（并给出「下一步该跑什么」）：
-//   ① 平台：只有 Linux 能读 /proc 并用 ip 命令（与 wireproxy 预编译平台限制同口径）；
-//   ② 地址：/proc/net/if_inet6 里必须有 scope=global 的地址；
-//   ③ 前缀：该地址的前缀主机位 ≥ minHostBits（/128 只有 1 个地址，不构成池）；
-//   ④ 认领：ip_nonlocal_bind=1（直接 bind，零改动）或 root（能 ip addr add）。
-//
-// ⚠ 本模块**不假装知道**「整段有没有真路由到本机」——那只能靠 probe.js 从池里的地址实测。
-// 内核接受地址（bind 成功）≠ 机房把回包送回来；两者混为一谈正是「池看起来就绪、请求全黑洞」的根因。
-import { readFileSync } from "node:fs";
-import { formatV6, hostBitsOf, networkOf, parsePrefix, parseV6 } from "./prefix.js";
-
-/** /proc/net/if_inet6 的 scope 列：00=global、10=host、20=link、40=site（都是 hex）。 */
-export const SCOPE_GLOBAL = 0;
-
-/** 解析 /proc/net/if_inet6：`<32 位 hex 地址> <ifindex> <prefixlen> <scope> <flags> <网卡>`。 */
-export function parseIfInet6(raw) {
-  const out = [];
-  for (const line of String(raw ?? "").split("\n")) {
-    const f = line.trim().split(/\s+/);
-    if (f.length < 6 || !/^[0-9a-f]{32}$/i.test(f[0])) continue;
-    const addr = parseV6(f[0].toLowerCase().match(/.{4}/g).join(":"));
-    if (addr === null) continue;
-    out.push({
-      addr,
-      text: formatV6(addr),
-      ifindex: parseInt(f[1], 16),
-      bits: parseInt(f[2], 16),
-      scope: parseInt(f[3], 16),
-      iface: f[5],
-    });
-  }
-  return out;
-}
-
-function skip(reason, hint) {
-  return { ok: false, reason, hint };
-}
-
-/**
- * 四关判定：把「本机事实」变成「可用池 或 具体跳过原因」。
- * 全部依赖注入（测试不用真读 /proc、不用真 root）。
- */
-export function pickPool({
-  entries = [],
-  nonlocalBind = 0,
-  uid = -1,
-  platform = process.platform,
-  explicitPrefix = "",
-  explicitIface = "",
-  minHostBits = 8,
-  claim = "auto",
-} = {}) {
-  if (platform !== "linux") {
-    return skip(`本平台（${platform}）不支持：需要 Linux 的 /proc 与 ip 命令`, "非 Linux 机器不需要本功能（WARP 池同样只在 Linux 可用）");
-  }
-  const globals = entries.filter((e) => e.scope === SCOPE_GLOBAL);
-  let addr;
-  let bits;
-  let iface;
-  let source;
-  if (explicitPrefix) {
-    const p = parsePrefix(explicitPrefix);
-    if (!p) return skip(`MSLXDFF_V6_PREFIX 解析失败：${explicitPrefix}`, "格式形如 2001:db8:1:2::/64");
-    addr = p.addr;
-    bits = p.bits;
-    source = "env";
-    iface = explicitIface || globals[0]?.iface || "";
-  } else {
-    if (!globals.length) {
-      return skip("本机没有任何全局 IPv6 地址（只有 link-local / loopback）", "确认网卡上启用了 IPv6，且运营商或机房确实给了 IPv6");
-    }
-    const picked = (explicitIface && globals.find((e) => e.iface === explicitIface)) || globals[0];
-    addr = picked.addr;
-    bits = picked.bits;
-    iface = explicitIface || picked.iface;
-    source = "proc";
-  }
-  const hostBits = hostBitsOf(bits);
-  if (hostBits < minHostBits) {
-    return skip(
-      `前缀 /${bits} 只有 ${hostBits} 位主机位（< ${minHostBits}），不构成池`,
-      `该地址是 /${bits}：整段没路由到本机时换不了 IP。若确认整段可用，用 MSLXDFF_V6_PREFIX=<段>/<位数> 显式指定`,
-    );
-  }
-  const mode = claim === "auto" ? (nonlocalBind === 1 ? "bind" : uid === 0 ? "add" : "none") : claim;
-  if (mode === "bind" && nonlocalBind !== 1) {
-    return skip("MSLXDFF_V6_CLAIM=bind 但 net.ipv6.ip_nonlocal_bind≠1", "sysctl -w net.ipv6.ip_nonlocal_bind=1，或改用 MSLXDFF_V6_CLAIM=add");
-  }
-  if (mode === "add" && uid !== 0) {
-    return skip(`MSLXDFF_V6_CLAIM=add 需要 root（当前 uid=${uid}）`, "以 root 跑 daemon，或 sysctl -w net.ipv6.ip_nonlocal_bind=1 后设 MSLXDFF_V6_CLAIM=bind");
-  }
-  if (mode === "none") {
-    return skip("既没有 ip_nonlocal_bind=1，也不是 root ⇒ 内核会拒绝 bind 池里的地址（EADDRNOTAVAIL）", "二选一：sysctl -w net.ipv6.ip_nonlocal_bind=1，或以 root 跑（可 ip addr add）");
-  }
-  return {
-    ok: true,
-    addr,
-    bits,
-    iface,
-    hostBits,
-    mode,
-    source,
-    prefix: `${formatV6(networkOf(addr, bits))}/${bits}`,
-    /** 本机自己的全局地址：造池时避开它们（别把机器正在用的地址当池里的"新"地址） */
-    mine: globals.map((e) => e.text),
-  };
-}
-
-/** 真机路径：读 /proc 与 /proc/sys（可整体注入，测试零 IO）。 */
-export function detectPool({ cfg = {}, entries, nonlocalBind, uid, platform = process.platform, readFile = (p) => readFileSync(p, "utf8") } = {}) {
-  const read = (p, dflt) => {
-    try {
-      return readFile(p);
-    } catch {
-      return dflt;
-    }
-  };
-  return pickPool({
-    entries: entries ?? parseIfInet6(read("/proc/net/if_inet6", "")),
-    nonlocalBind: nonlocalBind ?? (Number(String(read("/proc/sys/net/ipv6/ip_nonlocal_bind", "0")).trim()) || 0),
-    uid: uid ?? (typeof process.getuid === "function" ? process.getuid() : -1),
-    platform,
-    explicitPrefix: cfg.prefix || "",
-    explicitIface: cfg.iface || "",
-    minHostBits: cfg.minHostBits || 8,
-    claim: cfg.claim || "auto",
-  });
-}

package/src/v6pool/index.js

@@ -1,157 +0,0 @@
-// v6pool · 装配入口（MODULES.md §0/§1）。
-//
-// 定位：**自动判断**本机有没有可用的 IPv6 池；有就启用（出口 = 池里的源地址），
-// 没有就诚实跳过一行日志（行为与今天完全一致）。缺省开，MSLXDFF_V6_POOL=0 关。
-//
-// 与 WARP 池的关系：v6 池可用 ⇒ 不建 WARP 池（v6 严格更优：地址无限、零子进程、换址成本≈0）；
-// 检测通过但探活全失败 ⇒ 池为空 ⇒ dispatcher 走直连兜底，日志点名 MSLXDFF_V6_POOL=0 可恢复 WARP。
-import { getUndici } from "../compat.js";
-import { resolveV6Config } from "./config.js";
-import { detectPool } from "./detect.js";
-import { createClaimer } from "./claim.js";
-import { createV6Dispatcher } from "./rotate.js";
-import { probeFrom } from "./probe.js";
-import { randomAddress } from "./prefix.js";
-import { fmtClose, fmtConfig, fmtDetect, fmtDisabled, fmtPool, fmtPoolEmpty, fmtProbe, fmtReadyFail, fmtSkip } from "./report.js";
-import { createWarpDispatcher } from "../warp-pool/index.js";
-import { createMultiIpDispatcher } from "../multi-ip-pool/index.js";
-
-/** 每槽 Agent 的连接池参数。注入 dispatcher 后 transport 不建自带池（transport/index.js L28），所以必须自带。 */
-export const AGENT_OPTIONS = { connections: 4, pipelining: 1, keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000 };
-
-/** 初始地址集的去重重试上限（前缀足够大时一次就成）。 */
-export const DISTINCT_TRIES = 16;
-
-/**
- * 建池。检测不过 / 平台不支持 / 无权限 / undici 缺失 ⇒ 返回 null（调用方据此不注入、退回原行为）。
- * @returns {null | { dispatcher: object, ready: Promise<void>, config: object, detect: object,
- *                    close: () => Promise<void>, stats: () => object }}
- */
-export function createV6Pool({ env = process.env, baseUrl = "https://opencode.ai", log = (m) => console.error(m), deps = {} } = {}) {
-  const cfg = resolveV6Config(env);
-  if (!cfg.enabled) {
-    log(fmtDisabled());
-    return null;
-  }
-  log(fmtConfig(cfg));
-
-  const d = deps.detect ? deps.detect(cfg) : detectPool({ cfg, env });
-  if (!d.ok) {
-    log(fmtSkip(d));
-    return null;
-  }
-  log(fmtDetect(d));
-
-  const { Agent } = getUndici();
-  if (typeof Agent !== "function") {
-    log(fmtReadyFail({ error: "undici Agent 不可用（未安装 undici 且 Node <18）" }));
-    return null;
-  }
-
-  const prefix = { addr: d.addr, bits: d.bits };
-  const mine = new Set(d.mine || []);
-  const agentFactory = deps.agentFactory || ((addr) => new Agent({ connect: { localAddress: addr }, ...AGENT_OPTIONS }));
-  const claimer = deps.claimer ? deps.claimer(d) : createClaimer({ iface: d.iface, mode: d.mode, dir: cfg.dir, log });
-  const probe = deps.probe || probeFrom;
-
-  /** 挑一个池内地址：避开本机自己的全局地址（别把机器正在用的地址当"新"地址）。 */
-  function pickAddress() {
-    for (let i = 0; i < DISTINCT_TRIES; i++) {
-      const a = randomAddress(prefix);
-      if (!mine.has(a)) return a;
-    }
-    return randomAddress(prefix);
-  }
-
-  const dispatcher = createV6Dispatcher({
-    addrs: [],
-    strategy: cfg.strategy,
-    retireMs: cfg.retireMs,
-    rotate: cfg.rotate,
-    debug: cfg.debug,
-    log,
-    claimer,
-    pickAddress,
-    agentFactory,
-  });
-
-  let closed = false;
-  const ready = (async () => {
-    try {
-      await claimer.sweepStale();
-      const addrs = [];
-      const taken = new Set();
-      for (let i = 0; i < cfg.count; i++) {
-        if (closed) return;
-        let a = pickAddress();
-        for (let k = 0; k < DISTINCT_TRIES && taken.has(a); k++) a = pickAddress();
-        await claimer.ensure(a);
-        taken.add(a);
-        addrs.push(a);
-      }
-      // 逐个实证探活：内核接受了地址 ≠ 机房把整段路由到本机。探不通的当场释放，绝不进池。
-      const passed = [];
-      for (let i = 0; i < addrs.length; i++) {
-        if (closed) return;
-        const r = await probe({ addr: addrs[i], baseUrl, path: cfg.probePath, agentFactory });
-        log(fmtProbe({ addr: addrs[i], i: i + 1, n: addrs.length, ...r }));
-        if (r.ok) passed.push(addrs[i]);
-        else await claimer.release(addrs[i]);
-      }
-      if (!passed.length) {
-        log(fmtPoolEmpty({ tried: addrs.length }));
-        return;
-      }
-      dispatcher.setAddresses(passed);
-      log(fmtPool({ prefix: d.prefix, addrs: passed, claimed: addrs.length, mode: d.mode }));
-    } catch (e) {
-      log(fmtReadyFail({ error: String(e?.message || e) }));
-    }
-  })();
-
-  // 退出钩子：`process.on("exit")` 里只能跑同步代码，但地址必须清——加进网卡的地址会改变内核的
-  // 默认源地址选择，影响同机其它服务（本轮手工实测踩过）。清不掉就交给下次启动的 sweepStale。
-  if (deps.exitHook !== false) {
-    process.once("exit", () => {
-      try {
-        claimer.releaseAllSync?.();
-      } catch {
-        /* 清残留兜底见 claim.js 的 sweepStale */
-      }
-    });
-  }
-
-  return {
-    dispatcher,
-    ready,
-    config: cfg,
-    detect: d,
-    async close() {
-      if (closed) return;
-      closed = true;
-      await dispatcher.close();
-      const released = await claimer.releaseAll();
-      log(fmtClose({ released }));
-    },
-    stats() {
-      return { enabled: true, mode: d.mode, prefix: d.prefix, iface: d.iface, claimed: claimer.claimed(), ...dispatcher.stats() };
-    },
-  };
-}
-
-/**
- * 出口池三选一（唯一接线点用）：v6 池 → 多出口池 → WARP 池。
- * 三者都只产出一个 dispatcher 对象，注入点与契约完全一致（见 MODULES.md §1）。
- * 放在这里而不是 providers-setup：那里是 10KB 硬门下的文件，多一行都是风险。
- */
-export function createPreferredDispatcher({ baseUrl = "https://opencode.ai", env = process.env, log, deps = {} } = {}) {
-  const pool = createV6Pool({ env, baseUrl, log, deps });
-  if (pool) return pool.dispatcher;
-  // 次选：多出口池（VPNGate 免费 OpenVPN 节点当出口，只组长/单机建）——它给的是**另一批真实出口 IP**，
-  // 而 v6 只是本机自带的那段地址，所以 v6 优先、它次之。任一不可用都安静跳过（各自打自己的日志）。
-  const multi = createMultiIpDispatcher({ env, baseUrl, log, deps: deps.multiIp });
-  if (multi) return multi;
-  // 单向依赖：warp-pool 不 import v6pool（见 MODULES.md §2「已知耦合」）。
-  return createWarpDispatcher({ baseUrl, env, log });
-}
-

package/src/v6pool/prefix.js

@@ -1,140 +0,0 @@
-// v6pool · IPv6 前缀算术（纯函数，零 IO）：解析 / 规范化 / 取网络号 / 随机主机号。
-//
-// 为什么自己写：Node 没有内建 IPv6 前缀算术（`net.isIPv6` 只判形状），
-// 而本功能的核心动作就是「在给定前缀里造一个合法、不与现有地址撞车的主机号」。
-// 卫生规则（跳过 0/1/全 1、扰动 EUI-64 的 ff:fe 标记）照抄 v6pool 的 sanitizeHost——
-// 那几条是为了让出口地址看起来不像 SLAAC 自生成的地址（v6pool 的「unlinkable exits」）。
-const M16 = 0xffffn;
-
-/** 解析 IPv6 字面量 → BigInt(128bit)。非法返回 null。支持 `::` 压缩、`[..]` 包裹、`%zone`、v4 尾巴。 */
-export function parseV6(raw) {
-  let s = String(raw ?? "").trim().toLowerCase();
-  if (!s) return null;
-  if (s.startsWith("[") && s.endsWith("]")) s = s.slice(1, -1);
-  const zone = s.indexOf("%");
-  if (zone >= 0) s = s.slice(0, zone);
-  if (s.includes(".")) {
-    const at = s.lastIndexOf(":");
-    if (at < 0) return null;
-    const v4 = s.slice(at + 1).split(".");
-    if (v4.length !== 4 || !v4.every((x) => /^\d{1,3}$/.test(x) && Number(x) <= 255)) return null;
-    const n = v4.reduce((a, x) => ((a << 8) | Number(x)) >>> 0, 0) >>> 0;
-    s = `${s.slice(0, at)}:${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
-  }
-  const halves = s.split("::");
-  if (halves.length > 2) return null;
-  const head = halves[0] ? halves[0].split(":") : [];
-  const tail = halves.length === 2 ? (halves[1] ? halves[1].split(":") : []) : [];
-  if (halves.length === 1 && head.length !== 8) return null;
-  if (head.length + tail.length > 8) return null;
-  const fill = 8 - head.length - tail.length;
-  const groups = [...head, ...Array(halves.length === 2 ? fill : 0).fill("0"), ...tail];
-  if (groups.length !== 8) return null;
-  let out = 0n;
-  for (const g of groups) {
-    if (!/^[0-9a-f]{1,4}$/.test(g)) return null;
-    out = (out << 16n) | BigInt(`0x${g}`);
-  }
-  return out;
-}
-
-/** BigInt → 规范化 IPv6 文本（小写；最长零段压缩成 `::`，RFC 5952 只压 ≥2 段）。 */
-export function formatV6(big) {
-  const groups = [];
-  for (let i = 7; i >= 0; i--) groups.push(Number((big >> BigInt(i * 16)) & M16));
-  let bestAt = -1;
-  let bestLen = 0;
-  let curAt = -1;
-  let curLen = 0;
-  for (let i = 0; i < 8; i++) {
-    if (groups[i] === 0) {
-      if (curAt < 0) curAt = i;
-      curLen += 1;
-      if (curLen > bestLen) {
-        bestLen = curLen;
-        bestAt = curAt;
-      }
-    } else {
-      curAt = -1;
-      curLen = 0;
-    }
-  }
-  const hex = groups.map((g) => g.toString(16));
-  if (bestLen < 2) return hex.join(":");
-  return `${hex.slice(0, bestAt).join(":")}::${hex.slice(bestAt + bestLen).join(":")}`;
-}
-
-/** `"2001:db8::/64"` → `{ addr: BigInt, bits: 64, text: "2001:db8::" }`；非法返回 null。 */
-export function parsePrefix(raw) {
-  const s = String(raw ?? "").trim();
-  const slash = s.lastIndexOf("/");
-  if (slash < 0) return null;
-  const bits = Number(s.slice(slash + 1));
-  if (!Number.isInteger(bits) || bits < 0 || bits > 128) return null;
-  const addr = parseV6(s.slice(0, slash));
-  if (addr === null) return null;
-  return { addr, bits, text: formatV6(networkOf(addr, bits)) };
-}
-
-/** /bits 前缀里有几位主机位（= 可用地址的指数）。 */
-export function hostBitsOf(bits) {
-  return 128 - Number(bits);
-}
-
-/** 该地址在 /bits 下的网络号（主机位清零）。 */
-export function networkOf(addr, bits) {
-  if (bits <= 0) return 0n;
-  if (bits >= 128) return addr;
-  return addr & ~((1n << BigInt(128 - bits)) - 1n);
-}
-
-/** 随机主机号（m 位）。用 rnd() 拼 32bit 块，避免一次 Math.random 只有 53 位精度。 */
-export function randomHost(m, rnd = Math.random) {
-  let v = 0n;
-  let got = 0;
-  while (got < m) {
-    const take = Math.min(32, m - got);
-    const r = Math.floor(rnd() * 0x100000000) >>> 0;
-    v = (v << BigInt(take)) | (BigInt(r) & ((1n << BigInt(take)) - 1n));
-    got += take;
-  }
-  return v;
-}
-
-/** 该 64 位 IID 是否带 EUI-64 的 ff:fe 标记（RFC 4291 附录 A：MAC 派生的 SLAAC 地址）。 */
-export function isEui64(iid) {
-  return ((iid >> 24n) & M16) === 0xfffen;
-}
-
-/**
- * 主机号卫生：m>2 时跳过 0/1/全 1；m>=40 时扰动 ff:fe 标记。循环有界（8 次）且确定。
- */
-export function sanitizeHost(v, m) {
-  const mask = m >= 128 ? (1n << 128n) - 1n : (1n << BigInt(m)) - 1n;
-  let x = v & mask;
-  for (let i = 0; i < 8; i++) {
-    if (m >= 40 && isEui64(x)) {
-      x = (x ^ 0x0000000200000000n) & mask;
-      continue;
-    }
-    if (m > 2 && (x === 0n || x === 1n || x === mask)) {
-      x = (x + 1n) & mask;
-      continue;
-    }
-    return x;
-  }
-  return x;
-}
-
-/** 在前缀里造一个随机地址（主机号随机 + 卫生规则）。m<=0（/128）时只能返回前缀自身。 */
-export function randomAddress(prefix, rnd = Math.random) {
-  const m = hostBitsOf(prefix.bits);
-  if (m <= 0) return formatV6(prefix.addr);
-  const host = sanitizeHost(randomHost(m, rnd), m);
-  return formatV6(networkOf(prefix.addr, prefix.bits) | host);
-}
-
-/** 地址是否落在该前缀里。 */
-export function inPrefix(addr, prefix) {
-  return networkOf(addr, prefix.bits) === networkOf(prefix.addr, prefix.bits);
-}