mslxdff 0.1.242 → 0.1.243

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.242",
+  "version": "0.1.243",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/cli/commands/multi-ip-pool-test.js

@@ -0,0 +1,199 @@
+// mslxdff -multi-ip-pool 的 test / fetch 两条流程：全程 transcript（屏幕 + 文件），每步编号带耗时。
+//
+// 为什么要写成流水账（用户 2026-10-25 明确要求）：真机两轮排障都卡在「只看到最终判语、看不到环节」——
+// openvpn 的 argv、它的 stderr 原文、节点端口通不通、tun 地址有没有拿到、路由装没装上，
+// 每一项都必须是**一行一条**摆在屏幕上，并且整份落盘，贴一个文件就能定位。
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { runMultiIpCompare, VERDICT_ZH, MITEST_DEFAULT, MITEST_MAX } from "../../multi-ip-pool/selftest.js";
+import { resolveMultiIpConfig, resolveRole } from "../../multi-ip-pool/config.js";
+import { candidateNodes, loadNodeCache, materializeNode } from "../../multi-ip-pool/nodes.js";
+import { fetchNodes, fetchNodesToFile } from "../../multi-ip-pool/nodes-fetch.js";
+import { checkOpenvpn, isRoot, isSupportedPlatform } from "../../multi-ip-pool/tunnel.js";
+import { createTranscript, envSnapshotLines, probeTcp, residualHints, slotPlanLines } from "../../multi-ip-pool/diagnose.js";
+import { loadGroupsJoined } from "../../state.js";
+import { argValue } from "../policy.js";
+
+const FLAG = "-multi-ip-pool";
+
+const kindZh = { "free-quota": "429 额度耗尽", "free-tier": "403 免费层资格", "ip-limit": "429 限流", "black-quota": "账号日配额", network: "网络不可达", none: "非额度信号" };
+
+function flagValue(args, ...names) {
+  for (const name of names) {
+    const v = argValue(args, name);
+    if (v !== null && v !== undefined && !String(v).startsWith("-")) return v;
+    const eq = args.find((a) => a.startsWith(`${name}=`));
+    if (eq) return eq.slice(eq.indexOf("=") + 1);
+  }
+  return null;
+}
+
+const line = (r) => {
+  if (r.error) return `✗ 不可达（${String(r.error).replace(/\s+/g, " ").slice(0, 300)}）`;
+  if (r.ok) return `✅ HTTP ${r.status} 有额度`;
+  return `⛔ HTTP ${r.status} ${kindZh[r.kind] || r.kind}`;
+};
+
+/** 目录里已经有什么（auth.txt/nodes.json/node-*.conf）——很多失败就是这里少一个文件。 */
+function dirNotes(dir) {
+  try {
+    const names = readdirSync(dir);
+    const size = (f) => { try { return `${statSync(join(dir, f)).size}B`; } catch { return "?"; } };
+    const files = names.slice(0, 12).map((n) => `${n}(${size(n)})`);
+    files.push(names.length > 12 ? `…共 ${names.length} 个` : "");
+    files.push(`auth.txt ${names.includes("auth.txt") ? "在" : "**缺失**（拨号必挂，看第 4 步）"}`);
+    return files.filter(Boolean);
+  } catch (e) {
+    return [`目录读不到：${String(e?.code || e?.message || e)}`];
+  }
+}
+
+/** 取表（缓存优先，取不到就逐源试并把每个源的死因摆出来）。 */
+async function ensureRows(cfg, t) {
+  const cache = loadNodeCache({ dir: cfg.dir, ttlMs: cfg.nodesTtlMs });
+  if (cache?.rows?.length) {
+    t.say(`命中本地缓存：${cache.rows.length} 个节点（表源 ${cache.source}，缓存龄 ${Math.round((Date.now() - Number(cache.fetchedAt || 0)) / 1000)}s）`);
+    return cache.rows;
+  }
+  t.say("缓存没有或已过期 ⇒ 逐源取表（每源失败原因都会列出来）");
+  const got = await fetchNodes({ sources: cfg.sources, dir: cfg.dir, timeoutMs: cfg.probeTimeoutMs, log: (m) => t.say(m) });
+  t.say(`取到：${got.source} → ${got.rows.length} 个节点`);
+  return got.rows;
+}
+
+/**
+ * `-multi-ip-pool test`：五道门 → 取表 → 每槽 TCP 预检 → 基线 → 逐槽起隧道取证 → 判语 → 善后。
+ * 任何一步失败都会停在那一步并说清「下一步做什么」，不会攒到最后给你一个 unreachable。
+ */
+export async function runTest(args = []) {
+  const cfg = resolveMultiIpConfig(process.env);
+  const count = (() => { const v = flagValue(args, "--count", "-n"); return v === null ? MITEST_DEFAULT : Math.max(1, Math.min(MITEST_MAX, Number(v) || MITEST_DEFAULT)); })();
+  const model = flagValue(args, "--model", "-m") || "";
+  const t = createTranscript({ dir: cfg.dir });
+  console.log("=".repeat(70));
+  console.log("  多出口池取证 —— 全程 transcript（每一步都印，失败即停在原地）");
+  console.log("=".repeat(70));
+
+  t.step("① 环境快照");
+  const role = resolveRole({ mode: cfg.mode, joined: loadGroupsJoined() });
+  const root = isRoot();
+  const supported = isSupportedPlatform();
+  const openvpn = await checkOpenvpn(cfg.openvpnBin);
+  for (const l of envSnapshotLines({ cfg, platform: process.platform, root, openvpn, files: dirNotes(cfg.dir) })) t.say(l);
+  t.say(`角色门 role=${role.role} ⇒ ${role.active ? "通过" : "不建池"}（${role.why}）`);
+  if (!cfg.enabled || !role.active || !supported || !root || !openvpn.ok) {
+    t.say("五道门有不过的 ⇒ 后面不再动作（否则只会被 openvpn/内核报一堆看不懂的错）");
+    console.log(`\n❌ 前置不足：开关=${cfg.enabled} 角色=${role.active} Linux=${supported} root=${root} openvpn=${openvpn.ok}`);
+    console.log(`   下一步：mslxdff ${FLAG} status（逐门给人话结论）｜完整 transcript：${t.file}`);
+    process.exit(1);
+  }
+
+  t.step("② 节点表");
+  let rows = [];
+  try {
+    rows = await ensureRows(cfg, t);
+  } catch (e) {
+    t.say(String(e?.message || e));
+    console.log(`\n❌ 取不到节点表（原因见上一行）`);
+    console.log("   下一步：在能连的机器上 `mslxdff -multi-ip-pool fetch` 抓一份表带过来，");
+    console.log("          再 export MSLXDFF_MULTI_IP_NODES_FILE=<路径> 重跑 test");
+    console.log(`   完整 transcript：${t.file}`);
+    process.exit(1);
+    return true;
+  }
+
+  t.step(`③ 选槽与 TCP 预检（拨号前先确认端口通不通，省掉 3×20s 的瞎等）`);
+  const picked = candidateNodes({ rows, countries: cfg.countries, minScore: cfg.minScore, scan: count });
+  if (!picked.length) {
+    t.say(`Score≥${cfg.minScore} 且国家匹配的候选为 0（表里共 ${rows.length} 个节点）`);
+    console.log(`\n❌ 没有可用候选`);
+    console.log("   下一步：放宽 MSLXDFF_MULTI_IP_MIN_SCORE 或去掉 MSLXDFF_MULTI_IP_COUNTRY 再跑");
+    console.log(`   完整 transcript：${t.file}`);
+    process.exit(1);
+    return true;
+  }
+  const nodes = picked.map((row) => materializeNode({ dir: cfg.dir, row, name: `pre${picked.indexOf(row)}` })).filter(Boolean);
+  for (const l of slotPlanLines({ cfg, nodes })) t.say(l);
+  let reachable = 0;
+  for (const n of nodes) {
+    const p = await probeTcp({ host: n.host, port: n.port, timeoutMs: Math.min(6_000, cfg.connectTimeoutMs) });
+    const verdict = p.ok ? `✓ TCP 通（${p.ms}ms）` : `✗ TCP 不通（${p.error || "?"}，${p.ms}ms）`;
+    t.say(`  ${n.hostName} ${n.host}:${n.port} proto=${n.proto || "?"} → ${verdict}${String(n.proto).toLowerCase() === "udp" ? "　※ UDP 节点无握手，此探测仅供参考" : ""}`);
+    if (p.ok) reachable++;
+  }
+  if (!reachable) t.say("全部候选 TCP 都不通 ⇒ 多半是本机到公网节点被限制（不是本模块的配置问题），下面仍会真拨一次以留证据");
+
+  t.step("④ 基线 + 逐槽起隧道取证");
+  const onProgress = (ev) => {
+    if (ev.phase === "nodes") t.say(`（selftest 用的表：${ev.source}，${ev.total} 个节点）`);
+    else if (ev.phase === "baseline-start") t.say("基线：直连（系统默认出口）打一条免费层请求…");
+    else if (ev.phase === "baseline-done") t.say(`基线：${line(ev)}${ev.body ? ` ${String(ev.body).slice(0, 90).replace(/\s+/g, " ")}` : ""}`);
+    else if (ev.phase === "exit-start") t.say(`槽 ${ev.i}/${ev.n}：${ev.row.hostName}（${ev.row.countryShort || "?"}）开始`);
+    else if (ev.phase === "exit-done") t.say(`槽 ${ev.i}/${ev.n} 结果：${line(ev)}${ev.exitIp ? `｜出口 IP ${ev.exitIp}` : ""}`);
+  };
+  let r;
+  try {
+    r = await runMultiIpCompare({ count, ...(model ? { model } : {}), onProgress, deps: { log: (m) => t.say(m) } });
+  } catch (e) {
+    t.say(`测试执行抛错：${String(e?.stack || e?.message || e)}`);
+    console.log(`\n❌ 测试执行出错：${e?.message ?? e}`);
+    console.log(`   完整 transcript：${t.file}`);
+    process.exit(1);
+    return true;
+  }
+  if (r.status === "skip") {
+    t.say(`跳过：${r.reason}`);
+    console.log(`\n❌ 测不了：${r.reason}`);
+    console.log(`   下一步：${r.hint}`);
+    console.log(`   完整 transcript：${t.file}`);
+    process.exit(1);
+    return true;
+  }
+
+  t.step("⑤ 判语");
+  console.log("-".repeat(70));
+  console.log(`  基线（直连）：${line(r.baseline)}`);
+  console.log(`  VPN 出口：有额度 ${r.okCount}｜受限 ${r.limitedCount}｜不可达 ${r.netCount}（共 ${r.requested}）`);
+  const v = VERDICT_ZH[r.verdict] || { text: "未判定", next: "" };
+  const mark = r.verdict === "multi-ip-works" ? "✅" : r.verdict === "mixed" ? "△" : "⛔";
+  console.log(`  ${mark} ${v.text}：${r.okCount}/${r.requested} 条隧道拿到 200`);
+  if (v.next) console.log(`   ${v.next}`);
+  for (const e of r.exits || []) console.log(`   · ${e.hostName}（${e.country || "?"}）${e.exitIp ? `出口 ${e.exitIp}｜` : ""}${line(e)}`);
+
+  t.step("⑥ 善后与存档");
+  t.say(`隧道由本命令自造自拆；若中途 Ctrl+C，按下面几条查残留：`);
+  for (const h of residualHints()) t.say(`  ${h}`);
+  console.log("");
+  console.log(`  完整 transcript（贴这一个文件就够）：${t.file}`);
+  console.log(`  重试：mslxdff ${FLAG} test --count ${r.requested}${model ? ` --model ${model}` : ""}`);
+  process.exit(r.verdict === "multi-ip-works" || r.verdict === "mixed" ? 0 : 1);
+  return true;
+}
+
+/**
+ * `-multi-ip-pool fetch [路径]`：在**能连节点源**的机器上抓一份表落成文件，scp 到受限网络的组长机，
+ * 那边设 `MSLXDFF_MULTI_IP_NODES_FILE=<路径>` 即可完全跳过取表网络请求（2026-10-25 真机：华为云 ECS 到 vpngate.net 不通）。
+ */
+export async function runFetch(args = []) {
+  const cfg = resolveMultiIpConfig(process.env);
+  const out = flagValue(args, "--out", "-o") || join(cfg.dir, "vpngate.csv");
+  const t = createTranscript({ dir: cfg.dir, fileName: "fetch.log" });
+  t.step("逐源取表（失败原因逐条列出）");
+  t.say(`源列表：${cfg.sources.join(" → ")}`);
+  try {
+    const got = await fetchNodesToFile({ sources: cfg.sources, out, timeoutMs: cfg.probeTimeoutMs, log: (m) => t.say(m) });
+    const usable = got.rows.filter((r) => r.config).length;
+    t.say(`✅ ${got.rows.length} 个节点（${usable} 个配置可解码）→ ${out}`);
+    console.log("");
+    console.log("  带到受限网络的机器上：");
+    console.log(`     scp ${out} root@<组长机>:/root/.config/mslxdff/multi-ip-pool/vpngate.csv`);
+    console.log("     export MSLXDFF_MULTI_IP_NODES_FILE=/root/.config/mslxdff/multi-ip-pool/vpngate.csv");
+    console.log("     （之后取表零网络请求；表会旧，免费节点掉得快，建议隔几天重抓一次）");
+    process.exit(0);
+  } catch (e) {
+    t.say(`❌ ${String(e?.message || e)}`);
+    console.log("     下一步：换网络重试，或 MSLXDFF_MULTI_IP_SOURCES=<你自己能连的镜像/本地路径> 再跑一次");
+    process.exit(1);
+  }
+  return true;
+}

package/src/cli/commands/multi-ip-pool.js

@@ -1,35 +1,15 @@
-// mslxdff -multi-ip-pool [test|status|help]
-//   多出口池（VPNGate 免费 OpenVPN 节点当出口）：**组长/单机**专属，只服务 opencode 免费层。
+// mslxdff -multi-ip-pool [test|status|fetch|help]
+//   多出口池（VPNGate 免费 OpenVPN 节点当出口）：**组长**专属，只服务 opencode 免费层。
 //
-// 为什么需要这条命令（用户要的"取证"）：换出口到底有没有换来新额度，只有实测能回答。
-// 本命令做 A/B：直连打一条免费层请求取基线 → 逐条 VPN 隧道打**同一条**请求 → 对照判语。
-import { join } from "node:path";
-import { runMultiIpCompare, VERDICT_ZH, MITEST_DEFAULT, MITEST_MAX } from "../../multi-ip-pool/selftest.js";
-import { fetchNodesToFile } from "../../multi-ip-pool/nodes-fetch.js";
+// 本文件只做「分发 + status + 用法」；test / fetch 两条取证流程在 ./multi-ip-pool-test.js
+// （2026-10-25 起拆分：那边是全程 transcript 流水账，混在一起两边都顶过体积线）。
 import { resolveMultiIpConfig, resolveRole } from "../../multi-ip-pool/config.js";
 import { checkOpenvpn, isRoot, isSupportedPlatform } from "../../multi-ip-pool/tunnel.js";
 import { loadGroupsJoined } from "../../state.js";
-import { argValue } from "../policy.js";
+import { runFetch, runTest } from "./multi-ip-pool-test.js";
 
 const FLAG = "-multi-ip-pool";
 
-function flagValue(args, ...names) {
-  for (const name of names) {
-    const v = argValue(args, name);
-    if (v !== null && v !== undefined && !String(v).startsWith("-")) return v;
-    const eq = args.find((a) => a.startsWith(`${name}=`));
-    if (eq) return eq.slice(eq.indexOf("=") + 1);
-  }
-  return null;
-}
-
-const kindZh = { "free-quota": "429 额度耗尽", "free-tier": "403 免费层资格", "ip-limit": "429 限流", "black-quota": "账号日配额", network: "网络不可达", none: "非额度信号" };
-const line = (r) => {
-  if (r.error) return `✗ 不可达（${String(r.error).replace(/\s+/g, " ").slice(0, 220)}）`;
-  if (r.ok) return `✅ HTTP ${r.status} 有额度`;
-  return `⛔ HTTP ${r.status} ${kindZh[r.kind] || r.kind}`;
-};
-
 export async function handleMultiIpPool(args = []) {
   const at = args.findIndex((x) => x === FLAG || x.startsWith(`${FLAG}=`));
   if (at < 0) return false;
@@ -40,86 +20,8 @@ export async function handleMultiIpPool(args = []) {
   return await runTest(args);
 }
 
-async function runTest(args) {
-  const count = (() => { const v = flagValue(args, "--count", "-n"); return v === null ? MITEST_DEFAULT : Math.max(1, Math.min(MITEST_MAX, Number(v) || MITEST_DEFAULT)); })();
-  const model = flagValue(args, "--model", "-m") || "";
-  console.log("=".repeat(66));
-  console.log("  多出口池取证 —— 「直连 429 时，换成 VPN 出口还有额度吗」");
-  console.log("=".repeat(66));
-  console.log("");
-  console.log(`  探测模型 ${model || "(默认免费模型)"}｜采样 ${count} 条隧道｜只换出口，其余请求完全相同`);
-  console.log("");
-
-  const onProgress = (ev) => {
-    if (ev.phase === "nodes") console.log(`  ▸ 节点表：${ev.source}（${ev.total} 个节点）`);
-    else if (ev.phase === "baseline-start") console.log("  ▸ 基线：直连（系统默认出口）打一条免费层请求…");
-    else if (ev.phase === "baseline-done") {
-      console.log(`    基线结果：${line(ev)}${ev.body ? `（${String(ev.body).slice(0, 80).replace(/\s+/g, " ")}）` : ""}`);
-      console.log("");
-    } else if (ev.phase === "exit-start") console.log(`  [${String(ev.i).padStart(2)}/${ev.n}] ${ev.row.hostName}（${ev.row.countryShort || "?"}）…`);
-    else if (ev.phase === "exit-done") console.log(`      ${line(ev)}${ev.exitIp ? `｜出口 IP ${ev.exitIp}` : ""}`);
-  };
-
-  let r;
-  try {
-    r = await runMultiIpCompare({ count, ...(model ? { model } : {}), onProgress });
-  } catch (e) {
-    console.log("");
-    console.log(`❌ 测试执行出错：${e?.message ?? e}`);
-    console.log(`   重试：mslxdff ${FLAG}`);
-    process.exit(1);
-    return true;
-  }
-  if (r.status === "skip") {
-    console.log(`❌ 测不了：${r.reason}`);
-    console.log(`   下一步：${r.hint}`);
-    process.exit(1);
-    return true;
-  }
-
-  console.log("");
-  console.log("-".repeat(66));
-  console.log(`  基线（直连）：${line(r.baseline)}`);
-  console.log(`  VPN 出口：有额度 ${r.okCount}｜受限 ${r.limitedCount}｜不可达 ${r.netCount}（共 ${r.requested}）`);
-  console.log("");
-  const v = VERDICT_ZH[r.verdict] || { text: "未判定", next: "" };
-  const mark = r.verdict === "multi-ip-works" ? "✅" : r.verdict === "mixed" ? "△" : "⛔";
-  console.log(`  ${mark} ${v.text}：${r.okCount}/${r.requested} 条隧道拿到 200`);
-  if (v.next) console.log(`   ${v.next}`);
-  console.log("");
-  console.log(`   重试：mslxdff ${FLAG} --count ${r.requested}${model ? ` --model ${model}` : ""}`);
-  process.exit(r.verdict === "multi-ip-works" || r.verdict === "mixed" ? 0 : 1);
-}
-
-/**
- * `-multi-ip-pool fetch [路径]`：在**能连节点源**的机器上抓一份 VPNGate 表落成文件，scp 到受限网络的组长机，
- * 那边设 `MSLXDFF_MULTI_IP_NODES_FILE=<路径>` 即可完全跳过取表网络请求（2026-10-25 真机：华为云 ECS 上 vpngate.net 不可达）。
- */
-async function runFetch(args) {
-  const cfg = resolveMultiIpConfig(process.env);
-  const out = flagValue(args, "--out", "-o") || join(cfg.dir, "vpngate.csv");
-  console.log(`  节点源（按序试）：${cfg.sources.join("\n              ")}`);
-  console.log("");
-  try {
-    const got = await fetchNodesToFile({ sources: cfg.sources, out, timeoutMs: cfg.probeTimeoutMs });
-    const usable = got.rows.filter((r) => r.config).length;
-    console.log(`  ✅ ${got.rows.length} 个节点（${usable} 个配置可解码）已写入：${out}`);
-    console.log(`     来源：${got.source}`);
-    console.log("");
-    console.log("  带到受限网络的机器上：");
-    console.log(`     scp ${out} root@<组长机>:/root/.config/mslxdff/multi-ip-pool/vpngate.csv`);
-    console.log("     export MSLXDFF_MULTI_IP_NODES_FILE=/root/.config/mslxdff/multi-ip-pool/vpngate.csv");
-    console.log("     （之后取表零网络请求；表会旧，免费节点掉得快，建议隔几天重抓一次）");
-    process.exit(0);
-  } catch (e) {
-    console.log(`  ❌ 一个源都没取到：${String(e?.message || e)}`);
-    console.log("     下一步：换网络重试，或 MSLXDFF_MULTI_IP_SOURCES=<你自己能连的镜像/本地路径> 再跑一次");
-    process.exit(1);
-  }
-  return true;
-}
-
-async function printStatus(args) {
+/** status：只回答「开没开、为什么」。**不建池不拨号**，所以只能报告配置与门，报不了 daemon 内存里的池。 */
+async function printStatus(args = []) {
   const cfg = resolveMultiIpConfig(process.env);
   const role = resolveRole({ mode: cfg.mode, joined: loadGroupsJoined() });
   const platform = process.platform;
@@ -148,10 +50,11 @@ async function printStatus(args) {
 function printUsage() {
   console.log(`用法: mslxdff ${FLAG} [test|status|fetch|help] [--count N] [--model <id>] [--out <路径>]`);
   console.log("");
-  console.log("  在多出口池上做 A/B：直连打一条 free 层请求取基线，再逐条 VPN 隧道打同一条，");
+  console.log("  test 在多出口池上做 A/B：直连打一条 free 层请求取基线，再逐条 VPN 隧道打同一条，");
   console.log("  对照判语：");
   console.log("    基线 429 + VPN 出口有 200 ⇒ 池有用（换 IP 换到新额度）");
   console.log("    基线 429 + VPN 出口也全 429 ⇒ 换 IP 抬不动（上游不按出口 IP 计额）");
+  console.log("  test 每一步都编号打印并整份落盘（结尾给出 transcript 路径），失败即停在原地。");
   console.log("");
   console.log("  前置：Linux + root + openvpn（tun 设备与策略路由必需）。非 Linux 如实跳过。");
   console.log("");
@@ -171,4 +74,4 @@ function printUsage() {
   console.log("    MSLXDFF_MULTI_IP_PROBE_MODEL=<id>     打 hi 探额度用的免费模型（空＝同款缺省）");
   process.exit(0);
   return true;
-}
+}

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

@@ -0,0 +1,112 @@
+// multi-ip-pool · 诊断层：openvpn 输出归因 / 节点 TCP 预检 / 取证全程 transcript（argv 原文由 report.js:fmtArgv 出）。
+//
+// 为什么单独一份：2026-10-25 真机两轮都栽在「看得见结果、看不见环节」——openvpn 用法错误的末行恒是
+// `Use --help`，真凶在它上面；而 selftest 的内部步骤日志在 CLI 里被接到了空函数上。
+// 本文件把「哪一步出问题」变成一等信息：每一步都有编号、耗时、原文，并整份落盘可粘贴。
+import { mkdirSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import net from "node:net";
+import { devNameFor, tableFor } from "./config.js";
+
+/** 值得单独成行的报错关键词（openvpn 的用法/握手/认证/网络失败都在这里）。 */
+const ERRORISH = /options error|unrecognized|missing or extra|fatal|error:|can ?not|cannot|denied|failed|refused|reset|auth failed|tls|write udp|bind|permission/i;
+
+/**
+ * openvpn 输出里挑「最能说明问题」的一行：用法错误的**末行恒是** `Use --help for more information.`，
+ * 真凶（`Options error: …`）在它上面。只报末行等于把病因盖住。
+ */
+export function openvpnErrorLine(text, max = 240) {
+  const lines = String(text || "").split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  if (!lines.length) return "";
+  const pick = lines.find((l) => ERRORISH.test(l));
+  return (pick || lines[lines.length - 1]).slice(0, max);
+}
+
+/**
+ * 一行内的**多行摘要**：真凶行 + 其余最多 3 行（用 ` ‖ ` 分隔）。
+ * 单行是为了日志文件仍可 grep；多行是为了人眼一次看完，不必再翻 openvpn 自己的输出。
+ */
+export function openvpnErrorBrief(text, max = 620) {
+  const lines = String(text || "").split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  if (!lines.length) return "";
+  const first = lines.find((l) => ERRORISH.test(l)) || "";
+  const rest = lines.filter((l) => l !== first && !/^Use --help/i.test(l)).slice(-3);
+  return [first || lines[lines.length - 1], ...rest].join(" ‖ ").slice(0, max);
+}
+
+/**
+ * 节点 TCP 预检：拨号前先确认「这台机能不能连到 host:port」。
+ * 判语口径：VPNGate 实测 91/97 是 `proto tcp`，TCP 连不上基本就是节点/防火墙问题；
+ * `proto udp` 的节点这条只作参考（UDP 无握手，连不上不代表隧道必挂），**必须如实分开说**。
+ */
+export function probeTcp({ host, port, timeoutMs = 6_000, connectFn } = {}) {
+  const t0 = Date.now();
+  return new Promise((resolve) => {
+    const done = (ok, extra) => resolve({ ok, ms: Date.now() - t0, host, port, ...extra });
+    if (!host || !port) return done(false, { error: "缺 host/port" });
+    if (connectFn) {
+      return connectFn(host, port, timeoutMs)
+        .then((r) => done(Boolean(r?.ok), { ...(r?.error ? { error: r.error } : {}) }))
+        .catch((e) => done(false, { error: String(e?.message || e) }));
+    }
+    const s = net.connect({ host, port });
+    const timer = setTimeout(() => { s.destroy(); done(false, { error: `连接超时（${timeoutMs}ms）` }); }, timeoutMs);
+    s.once("connect", () => { clearTimeout(timer); s.destroy(); done(true, {}); });
+    s.once("error", (e) => { clearTimeout(timer); done(false, { error: String(e?.code || e?.message || e) }); });
+  });
+}
+
+/**
+ * 取证全程 transcript：每行带 `[步骤号]` 与相对耗时，同时进屏幕与文件（0600）。
+ * 落盘是为了「一次跑完贴一个文件给我」，不必复现；写文件失败绝不影响测试本体。
+ */
+export function createTranscript({ dir, out = (s) => console.log(s), now = () => Date.now(), fs = { mkdirSync, appendFileSync }, fileName = "" } = {}) {
+  const t0 = now();
+  let step = 0;
+  const file = dir ? join(dir, fileName || `test-${new Date(t0).toISOString().replace(/[:.]/g, "-")}.log`) : "";
+  const emit = (raw) => {
+    const line = `[${String(step).padStart(2, "0")} +${((now() - t0) / 1000).toFixed(1)}s] ${raw}`;
+    out(line);
+    if (file) {
+      try { fs.appendFileSync(file, line + "\n"); } catch { /* 落盘失败只影响存档，不影响取证 */ }
+    }
+  };
+  try {
+    if (file) { fs.mkdirSync(dirname(file), { recursive: true }); fs.appendFileSync(file, `# multi-ip-pool 取证 transcript（本文件可整份粘贴）\n`); }
+  } catch { /* 同上 */ }
+  return {
+    file,
+    /** 一条步骤行（自动编号）。 */
+    step: (text) => { step += 1; emit(text); return step; },
+    /** 归属当前步骤的明细行（不占编号）。 */
+    say: (text) => emit(`      ${String(text).replace(/^\s+/, "")}`),
+    /** 小节标题。 */
+    section: (text) => { step += 1; emit(`—— ${text} ——`); return step; },
+  };
+}
+
+/** 环境快照：一眼看清「机器/权限/二进制/配置/磁盘上有什么」，省掉一轮来回。 */
+export function envSnapshotLines({ cfg, platform, root, openvpn, files = [], argvNode = "" } = {}) {
+  return [
+    `node ${argvNode || process.version}｜平台 ${platform}｜root ${root ? "是" : "否"}`,
+    `openvpn ${openvpn?.ok ? `可用：${openvpn.version}` : `不可用：${openvpn?.why || "?"}`}`,
+    `配置：隧道 ${cfg?.count} 条｜备胎 ${cfg?.standby} 条/每 ${Math.round((cfg?.standbyEveryMs || 0) / 60_000)} 分钟｜Score 下限 ${cfg?.minScore}｜国家 ${cfg?.countries?.length ? cfg.countries.join("/") : "不限"}｜策略 ${cfg?.strategy}`,
+    `目录 ${cfg?.dir}：${files.length ? files.join(" ") : "（空，本轮第一次跑）"}`,
+    `节点源（按序）：${(cfg?.sources || []).join(" → ")}`,
+  ];
+}
+
+/** 每槽的「设备名/路由表/优先级」对照表：内核侧出问题时按这张表查。 */
+export function slotPlanLines({ cfg, nodes = [] } = {}) {
+  return nodes.map((n, i) => `  槽 ${i}：${n.hostName}（${n.countryShort || "?"}）→ ${n.host}:${n.port}｜proto ${n.proto || "?"}｜设备 ${devNameFor(cfg.devPrefix, i)}｜表 ${tableFor(cfg.baseTable, i)}`);
+}
+
+/** 跑完（尤其是中途失败）后给全善后命令：设备与路由残留必须能一眼查清。 */
+export function residualHints() {
+  return [
+    "ip -brief addr show type tun",
+    "ip link show | grep -E 'mltun|tun'",
+    "ip rule show | grep -E 'from (10\\.|192\\.|172\\.)' | head",
+    "ip route show table all | grep -E 'mltun' | head",
+  ];
+}

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

@@ -140,7 +140,8 @@ export function materializeNode({ dir, row, name = "" } = {}) {
   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 };
+  // proto 一并带出：预检与判语要分清「TCP 节点连不上」与「UDP 节点无握手可探」两回事
+  return { ...row, conf: written.path, host: remote.host, port: remote.port, proto: (/^\s*proto\s+(\S+)/m.exec(conf) || [])[1] || "" };
 }
 
 /** VPNGate 公共账号（vpn/vpn）；落在 0600 文件里，绝不入库。 */

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

@@ -44,6 +44,11 @@ export function fmtSpawn({ dev, pid, host, port, country, table }) {
   return `${TAG} ${SYM.ok} ${dev} 隧道就绪（pid=${pid}，出口节点 ${host}:${port} ${country}，策略表 ${table}）`;
 }
 
+/** 实际执行的 openvpn 命令行（argv 原文）：真机排障第一问就是「你到底跑了什么」。 */
+export function fmtArgv({ bin, args }) {
+  return `${TAG} ${SYM.step} 执行：${bin} ${(args || []).join(" ")}`;
+}
+
 export function fmtTunAddrFail({ dev, out }) {
   return `${TAG} ${SYM.bad} ${dev} 起来了但读不到 tun 地址（ip -4 addr show dev ${dev} 的输出：${(out || "(空)").slice(0, 200)}）—— 隧道建不起来，这槽换下一个节点`;
 }

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

@@ -9,7 +9,8 @@
 // 平台纪律：只有 Linux 能干（tun + `ip rule`）；其它平台由调用方**诚实跳过一行**，不做半吊子。
 import { spawn } from "node:child_process";
 import { devNameFor, tableFor } from "./config.js";
-import { fmtExit, fmtRpf, fmtRuleFail, fmtSpawn, fmtTunAddrFail } from "./report.js";
+import { fmtArgv, fmtExit, fmtRpf, fmtRuleFail, fmtSpawn, fmtTunAddrFail } from "./report.js";
+import { openvpnErrorLine, openvpnErrorBrief } from "./diagnose.js";
 
 /** openvpn 就绪标志（配置文件里可能出现别的 "Sequence"，必须整串匹配）。 */
 export const READY_PATTERN = /Initialization Sequence Completed/;
@@ -58,16 +59,6 @@ export function buildOpenvpnArgs({ conf, dev, authFile, logFile = "", verb = 3 }
   ];
 }
 
-/**
- * openvpn 输出里挑「最能说明问题」的一行：用法错误的**末行恒是** `Use --help for more information.`，
- * 真凶（`Options error: …`）在它上面。只报末行等于把病因盖住——2026-10-25 真机就因为这样绕了一圈。
- */
-export function openvpnErrorLine(text, max = 240) {
-  const lines = String(text || "").split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-  if (!lines.length) return "";
-  const pick = lines.find((l) => /options error|unrecognized|missing or extra|fatal|error:|can ?not|cannot|denied|failed|refused|reset|auth failed/i.test(l));
-  return (pick || lines[lines.length - 1]).slice(0, max);
-}
 
 /** 从 `ip -4 addr show dev <dev>` 输出里取 tun 地址（VPNGate 推的是 10.x 内网地址）。 */
 export function parseTunAddr(text) {
@@ -138,6 +129,8 @@ export async function checkOpenvpn(bin, { runCmdFn = runCmd } = {}) {
  * tail 保留末 20 行：真机排障时"openvpn 为什么退"全在这几行里。
  */
 export function startTunnel({ bin, args, timeoutMs = 25_000, spawnFn = spawn, log = () => {}, onExit = null, dev = "" } = {}) {
+  // 「我到底跑了什么」必须是第一条信息：openvpn 的 argv 报错只有对着命令行原文才看得懂
+  log(fmtArgv({ bin, args }));
   let child;
   try {
     child = spawnFn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
@@ -157,12 +150,13 @@ export function startTunnel({ bin, args, timeoutMs = 25_000, spawnFn = spawn, lo
     }
   };
   const lastTail = () => openvpnErrorLine(tail.join("\n"));
+  const briefTail = () => openvpnErrorBrief(tail.join("\n"));
   const ready = new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
       try { child.kill("SIGTERM"); } catch { /* 已退 */ }
-      reject(new Error(`等 ${Math.round(timeoutMs / 1000)}s 没等到「Initialization Sequence Completed」（隧道没起来）：${lastTail()}`));
+      reject(new Error(`等 ${Math.round(timeoutMs / 1000)}s 没等到「Initialization Sequence Completed」（隧道没起来）：${briefTail()}`));
     }, timeoutMs);
     const onChunk = (buf) => {
       push(buf);
@@ -178,7 +172,7 @@ export function startTunnel({ bin, args, timeoutMs = 25_000, spawnFn = spawn, lo
       if (!settled) {
         settled = true;
         clearTimeout(timer);
-        reject(new Error(`openvpn 提前退出（code=${code} signal=${signal}）：${lastTail()}`));
+        reject(new Error(`openvpn 提前退出（code=${code} signal=${signal}）：${briefTail()}`));
       }
       // 主动关掉的隧道不算"意外退出"：收摊日志只该出现在真出事时（否则每次换槽都刷一行假警报）
       if (!stopping) log(fmtExit({ dev, code, signal, pid: child.pid, aliveMs, tail: lastTail() }));