ghprobe 0.0.0-stage → 0.1.1

package/src/hosts.js

@@ -0,0 +1,332 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// hosts 片段生成 + 事务化提权写入 + 还原 + DNS 缓存刷新
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+
+export const WIN_HOSTS = "C:\\Windows\\System32\\drivers\\etc\\hosts";
+const BEGIN = "# === ghprobe begin ===";
+const END = "# === ghprobe end ===";
+
+// 用户级数据目录（日志、无窗口包装器）。放 %LOCALAPPDATA% 而不是包目录：
+// npm 全局安装时包目录在 node_modules 下，npm 升级/重装会整个换掉。
+export function userDataDir() {
+  const base = process.env.LOCALAPPDATA || path.join(os.homedir(), ".ghprobe");
+  return path.join(base, "ghprobe");
+}
+
+// 写 hosts 跨进程锁：probe --apply 与计划任务（health --apply）可能并发，避免读改写互踩
+export const HOSTS_LOCK = path.join(os.tmpdir(), "ghprobe-hosts.lock");
+const LOCK_STALE_MS = 60000;
+
+function sleepSync(ms) {
+  const sab = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(sab), 0, 0, ms);
+}
+
+// 抢写锁：wx 独占创建，冲突每 retryMs 重试，最多 timeoutMs；超时返回 null 表示本轮放弃。
+// 锁文件带随机 PID+时间戳；超出 LOCK_STALE_MS 视为持有进程崩溃残留，强清后重试。
+export function acquireHostsLock(timeoutMs = 5000, retryMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const fd = fs.openSync(HOSTS_LOCK, "wx");
+      fs.writeSync(fd, `${process.pid} ${Date.now()}\n`);
+      return fd;
+    } catch (e) {
+      if (e.code !== "EEXIST") { throw e; }
+      try {
+        const st = fs.statSync(HOSTS_LOCK);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) { fs.unlinkSync(HOSTS_LOCK); continue; }
+      } catch { continue; } // 锁刚被持有者释放
+    }
+    if (Date.now() >= deadline) { return null; }
+    sleepSync(retryMs);
+  }
+}
+
+export function releaseHostsLock(fd) {
+  try { if (fd != null) { fs.closeSync(fd); } } catch { /* 忽略 */ }
+  try { fs.unlinkSync(HOSTS_LOCK); } catch { /* 忽略 */ }
+}
+
+// 从 ranked(域名->有序IP列表) 生成 hosts 块。
+// 🔴 每域名写 maxPer 条（默认 2）：**Windows 会把同名多条全部返回**（2026-10-11 实测，
+//    dns.lookup/all 与 curl 双证），且 curl / 浏览器会**逐个尝试** —— 黑洞 IP 排在前也能
+//    fallback 到后面的活 IP（实测 http=200 / 0.22s）。旧注释「只取第一条生效」是错的。
+//    所以多写 1 条备选 = 抖动时客户端自动兜底，不必干等下一轮健康检查（最长 1 分钟）。
+export function buildBlock(ranked, extraDomains, maxPer = 2) {
+  const lines = [BEGIN, `# generated ${new Date().toISOString()} by ghprobe`];
+  const put = (domain, rs) => {
+    for (const r of (rs || []).slice(0, Math.max(1, maxPer))) { lines.push(`${r.ip} ${domain}`); }
+  };
+  for (const [domain, rs] of ranked) {
+    if (rs.length) { put(domain, rs); }
+  }
+  for (const [domain, rs] of extraDomains || []) {
+    if (rs.length) { put(domain, rs); }
+  }
+  lines.push(END);
+  return lines.join("\n");
+}
+
+// 把新块合并进已有 hosts 内容：替换旧 ghprobe 块，其余行原样保留
+export function mergeHosts(current, block) {
+  const lines = String(current).split(/\r?\n/);
+  const out = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (line.startsWith(BEGIN)) { inBlock = true; continue; }
+    if (line.startsWith(END)) { inBlock = false; continue; }
+    if (!inBlock) { out.push(line); }
+  }
+  while (out.length && out[out.length - 1].trim() === "") { out.pop(); }
+  if (!block) { return out.join("\n") + (out.length ? "\n" : ""); }
+  const merged = [...out, "", block].join("\n");
+  return merged.endsWith("\n") ? merged : merged + "\n";
+}
+
+// 构造提权包装命令：Start-Process -Verb RunAs 拉起目标，并把被提升进程的退出码带回来。
+// 两个关键点（都踩过）：
+// ① 先把控制台输出编码设为 UTF-8 —— 否则 PowerShell 以 GBK 写 stderr，Node 按 UTF-8 解码会乱码，
+//    调用方 throw 出来的「提权写入失败: …」就变成一串问号。
+// ② 必须在 `exit $p.ExitCode` 之前判空：Start-Process 自身失败（典型是用户取消 UAC）时
+//    抛的是「非终止错误」，脚本会继续往下执行，$p 仍为 $null，而 `exit $null` 等价于
+//    退出码 0 —— 会把「提权失败」伪装成「成功」。-ErrorAction Stop 让它变成可捕获的终止错误。
+export function buildElevateCommand(file, args = []) {
+  const list = args.map((a) => `'${a}'`).join(",");
+  return `try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {};`
+    + ` try { $p = Start-Process -FilePath '${file}' -Verb RunAs -Wait -PassThru -ArgumentList ${list} -ErrorAction Stop }`
+    + ` catch { [Console]::Error.WriteLine('提权失败: ' + $_.Exception.Message); exit 1 };`
+    + ` if ($null -eq $p) { exit 1 };`
+    + ` exit $p.ExitCode`;
+}
+
+// 构造「删除计划任务」的提权脚本。单独导出是为了可单测、可独立执行验证。
+// 两个关键点：
+// ① 任务不存在时直接 exit 0（幂等）—— uninstall 重复跑不应报错。
+// ② 删除动作必须 -ErrorAction Stop：否则「拒绝访问」这类错误是非终止的，脚本会继续走到
+//    末尾的 exit 0，把「删除失败」伪装成「成功」。
+export function buildUninstallTaskScript(taskName = "ghprobe") {
+  return `try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {};`
+    + ` if (-not (Get-ScheduledTask -TaskName '${taskName}' -ErrorAction SilentlyContinue))`
+    + ` { [Console]::Error.WriteLine('计划任务 ${taskName} 不存在，跳过'); exit 0 };`
+    + ` try { Unregister-ScheduledTask -TaskName '${taskName}' -Confirm:$false -ErrorAction Stop }`
+    + ` catch { [Console]::Error.WriteLine('删除计划任务失败: ' + $_.Exception.Message); exit 1 };`
+    + ` exit 0`;
+}
+
+// 构造「写入 hosts + 注册计划任务」的提权脚本（install 用）：一次 UAC 完成两件事。
+// 与 buildApplyScript 的区别：中途不 exit，两件事都做完后再按综合结果返回退出码，
+// 这样 install 只需弹一次 UAC，且能拿到「两件事各自成功与否」的确定结果。
+export function buildInstallScript({ hostsPath, tmpPath, nodePath, binPath, cfgArg = "", minutes = 1, writeHosts = true, vbsPath = "" }) {
+  const bak = `${hostsPath}.ghprobe-bak`;
+  const hostsPart = writeHosts ? `
+try {
+  Copy-Item -Force $src $bak
+  Copy-Item -Force $tmp $src
+  $now = [IO.File]::ReadAllText($src, $enc)
+  if ($now -match [regex]::Escape($marker)) { $hostsOk = $true }
+  else { Copy-Item -Force $bak $src; [Console]::Error.WriteLine('hosts 校验失败：未找到 ghprobe 标记，已回滚') }
+} catch {
+  if (Test-Path $bak) { Copy-Item -Force $bak $src }
+  [Console]::Error.WriteLine('hosts 写入失败: ' + $_.Exception.Message)
+}
+if ($hostsOk) { ipconfig /flushdns | Out-Null }` : "";
+  // 任务动作二选一：
+  // ① 有 VBS 包装器（默认）→ 用 wscript.exe 跑它，VBS 内以 SW_HIDE 启动 node —— 全程无窗口；
+  // ② 没有（老调用方 / 包装器写失败）→ 直接跑 node，功能不受影响，但会闪一个控制台窗口。
+  const actionLine = vbsPath
+    ? `$a = New-ScheduledTaskAction -Execute "$env:SystemRoot\\System32\\wscript.exe" -Argument ('"' + '${vbsPath}' + '"')`
+    : `$a = New-ScheduledTaskAction -Execute '${nodePath}' -Argument '"${binPath}" health --apply${cfgArg}'`;
+  return `
+try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {}
+$src = '${hostsPath}'
+$tmp = '${tmpPath}'
+$bak = '${bak}'
+$marker = '${BEGIN}'
+$enc = [Text.Encoding]::Default
+$hostsOk = $${writeHosts ? "false" : "true"}
+${hostsPart}
+$taskOk = $false
+try {
+  ${actionLine}
+  $t = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes ${minutes})
+  $p = New-ScheduledTaskPrincipal -UserId "$env:COMPUTERNAME\\$env:USERNAME" -LogonType Interactive -RunLevel Highest
+  Register-ScheduledTask -TaskName ghprobe -Action $a -Trigger $t -Principal $p -Force | Out-Null
+  $taskOk = $true
+} catch {
+  [Console]::Error.WriteLine('注册计划任务失败: ' + $_.Exception.Message)
+}
+if ($hostsOk -and $taskOk) { exit 0 }
+exit 1
+`;
+}
+
+// 构造「无窗口运行」包装器（VBScript）。
+// 为什么需要它：Task Scheduler 在交互会话里启动控制台程序（node.exe）会**必然**新建一个
+// 控制台窗口，而 node.exe 没有任何「隐藏窗口」开关（不像 powershell 有 -WindowStyle Hidden）。
+// 唯一可靠的做法是让 wscript.exe 起一层：WScript.Shell.Run 的第二个参数是 ShowWindow 风格，
+// 传 0 = SW_HIDE，且该方式自 Win7 起一直有效。第三个参数 True = 等子进程结束再退出。
+// 🔴 注释必须**纯 ASCII**：这个文件以 "ascii" 编码落盘（wscript 对无 BOM 的 .vbs 按 ANSI 解析，
+//    写 UTF-8 中文会变乱码），中文字符会被掩掉高位变成一堆问号/方块。
+// VBS 字符串里 `"` 要写成 `""`（成对双写），所以路径里的引号要整体转义一遍。
+export function buildHiddenRunnerVbs(nodePath, binPath, args = "") {
+  const cmd = `"${nodePath}" "${binPath}"${args ? " " + args : ""}`;
+  return [
+    "' ghprobe hidden-runner wrapper - generated by \"ghprobe install\", removed by \"ghprobe uninstall\".",
+    "' Do not edit. ASCII-only on purpose (wscript reads BOM-less .vbs as ANSI).",
+    'Set sh = CreateObject("WScript.Shell")',
+    `sh.Run "${cmd.replace(/"/g, '""')}", 0, True`,
+    "",
+  ].join("\r\n");
+}
+
+// 判断当前进程是否已经有管理员权限：hosts 是只有管理员能写的系统文件，
+// 用「以读写方式打开」做探测，成功即已提权。比 spawn 一个 PowerShell 去查 token 便宜得多，
+// 而且不产生任何窗口。已提权时 applyHosts 直接跑脚本，不再走 Start-Process -Verb RunAs
+// （那条路会再拉一个新控制台窗口，无窗口运行就破了）。
+export function isElevated(hostsPath = WIN_HOSTS) {
+  try { fs.closeSync(fs.openSync(hostsPath, "r+")); return true; } catch { return false; }
+}
+
+// 跑一段 PowerShell 命令，回传 { code, out, err }
+function runPowerShellCommand(cmd) {
+  return new Promise((resolve, reject) => {
+    const child = execFile("powershell", ["-NoProfile", "-Command", cmd], { windowsVerbatimArguments: true, windowsHide: true });
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => { out += d; });
+    child.stderr?.on("data", (d) => { err += d; });
+    child.on("close", (code) => resolve({ code, out, err }));
+    child.on("error", reject);
+  });
+}
+
+// 直接执行一个 .ps1（调用方保证已经提权）。windowsHide 让 powershell 以 CREATE_NO_WINDOW
+// 启动，不闪窗；被提升的父进程若本身就在隐藏控制台里，子进程也是继承而非新建。
+function runPowerShellFile(file) {
+  return new Promise((resolve, reject) => {
+    const child = execFile("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", file], { windowsHide: true });
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => { out += d; });
+    child.stderr?.on("data", (d) => { err += d; });
+    child.on("close", (code) => resolve({ code, out, err }));
+    child.on("error", reject);
+  });
+}
+
+// 跑一次提权包装。单独导出是为了让回归测试能注入一个必然失败的 Start-Process 目标，
+// 从而验证「提权失败不会退化成退出码 0」。
+export function runElevationWrapper(file, args = []) {
+  return runPowerShellCommand(buildElevateCommand(file, args));
+}
+
+// 写提权脚本文件。🔴 必须带 UTF-8 BOM：PowerShell 5.1 对「无 BOM 的 .ps1」按系统 ANSI
+// 代码页（中文系统 = GBK）解析，脚本里的中文字面量（错误提示）会整段变乱码。
+// 加 BOM 后 PS 才按 UTF-8 解析。注意这条路径与 buildElevateCommand 不同 ——
+// 那条走 `-Command`，参数由 CreateProcessW 以 UTF-16 传递，本来就不受文件编码影响。
+export function writePs1WithBom(file, content) {
+  fs.writeFileSync(file, "\ufeff" + content, "utf8");
+}
+
+// 写临时 ps1 -> 提权执行 -> 取回退出码 -> 清理 ps1（apply/restore/install 复用）。
+// 已经提权时（计划任务 runlevel=highest）直接执行脚本，不走 Start-Process -Verb RunAs ——
+// 后者会再拉一个独立控制台窗口，是「无窗口运行」的第二个破口。
+export async function runElevated(content) {
+  const tmp = path.join(os.tmpdir(), `ghprobe-${Date.now()}.ps1`);
+  writePs1WithBom(tmp, content);
+  try {
+    if (isElevated()) { return await runPowerShellFile(tmp); }
+    return await runElevationWrapper("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", tmp]);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* 清理失败不管 */ }
+  }
+}
+
+// 构造 hosts 写入脚本（由 runElevated 提权执行）。两个要点：
+// ① 备份**每次刷新**（不是「只建一次」）—— 只建一次时，若 hosts 在安装后被第三方追加了
+//    条目，那份陈旧备份里没有它们，卸载/回滚时会把它们一起抹掉。
+// ② 读写统一用 [Text.Encoding]::Default（系统 ANSI 代码页），保证 hosts 里的非 ASCII
+//    注释（不少工具会写中文标记）编码不变。
+export function buildApplyScript(hostsPath, tmpPath) {
+  const bak = `${hostsPath}.ghprobe-bak`;
+  return `
+try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {}
+$src = '${hostsPath}'
+$tmp = '${tmpPath}'
+$bak = '${bak}'
+$marker = '${BEGIN}'
+$enc = [Text.Encoding]::Default
+try {
+  Copy-Item -Force $src $bak
+  Copy-Item -Force $tmp $src
+  $now = [IO.File]::ReadAllText($src, $enc)
+  if ($now -notmatch [regex]::Escape($marker)) {
+    Copy-Item -Force $bak $src
+    [Console]::Error.WriteLine('hosts 校验失败：未找到 ghprobe 标记，已回滚')
+    exit 1
+  }
+  ipconfig /flushdns | Out-Null
+  exit 0
+} catch {
+  if (Test-Path $bak) { Copy-Item -Force $bak $src }
+  [Console]::Error.WriteLine('hosts 写入失败: ' + $_.Exception.Message)
+  exit 1
+}
+`;
+}
+
+// 构造 hosts 还原脚本（由 runElevated 提权执行）：剥掉整个 ghprobe 块后写回。
+// 刻意**不**用 *.ghprobe-bak 直接覆盖 —— 备份是「写入前」的快照，可能含旧块，也可能
+// 早于第三方后来追加的条目。直接剥块才能保证「只移除 ghprobe 自己的行」。
+// 🔴 必须用状态机跳过 begin..end 之间的**所有行**：早期写法是 `Where-Object { $_ -notmatch
+//    '^# === ghprobe (begin|end) ===' }`，它只删标记行、把块内 IP 条目全留下 ——
+//    以前靠备份分支兜着没暴露，去掉备份分支后就会留下一堆孤儿条目。
+export function buildRestoreScript(hostsPath) {
+  return `
+try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {}
+$src = '${hostsPath}'
+$enc = [Text.Encoding]::Default
+try {
+  $current = [IO.File]::ReadAllText($src, $enc)
+  $keep = @()
+  $skip = $false
+  foreach ($line in ($current -split '\\r?\\n')) {
+    if ($line -match '^# === ghprobe begin ===') { $skip = $true; continue }
+    if ($line -match '^# === ghprobe end ===') { $skip = $false; continue }
+    if (-not $skip) { $keep += $line }
+  }
+  $clean = ($keep -join [Environment]::NewLine).TrimEnd() + [Environment]::NewLine
+  [IO.File]::WriteAllText($src, $clean, $enc)
+  ipconfig /flushdns | Out-Null
+  exit 0
+} catch {
+  [Console]::Error.WriteLine('hosts 还原失败: ' + $_.Exception.Message)
+  exit 1
+}
+`;
+}
+
+// 事务化提权写入：刷新备份 -> 覆盖 -> 校验含 BEGIN -> 失败回滚 -> 刷 DNS 缓存
+export async function applyHosts(merged, hostsPath = WIN_HOSTS) {
+  const tmp = path.join(os.tmpdir(), `ghprobe-hosts-${Date.now()}.tmp`);
+  fs.writeFileSync(tmp, merged, "utf8");
+  try {
+    const r = await runElevated(buildApplyScript(hostsPath, tmp));
+    if (r.code !== 0) { throw new Error(`提权写入失败: ${r.err || r.out}`); }
+    return { ok: true, backup: `${hostsPath}.ghprobe-bak` };
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* 清理失败不管 */ }
+  }
+}
+
+// 还原 hosts：剥掉 ghprobe 块后写回；最后刷 DNS 缓存
+export async function restoreHosts(hostsPath = WIN_HOSTS) {
+  const r = await runElevated(buildRestoreScript(hostsPath));
+  if (r.code !== 0) { throw new Error(`还原 hosts 失败: ${r.err || r.out}`); }
+  return { ok: true };
+}

package/src/net.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 本地网络可用性检查：本机断网时直接跳过本轮 —— 不探测、不更新池、不写 hosts。
+// 为什么需要：断网时所有候选必然全灭，跑一轮纯属浪费，而且日志会被「stuck / 全灭」刷屏，
+// 掩盖真正的故障；更糟的是会让「网络故障」和「GitHub 被墙」两种情况混在一起无法区分。
+import os from "node:os";
+import net from "node:net";
+
+// 第一步（零成本）：有没有「已启用且带非回环 IPv4」的网卡。
+// 只能排除「网卡全禁用 / 只连了回环」这种最明显的情况，不能证明真能出去。
+export function hasInterface() {
+  const ifs = os.networkInterfaces();
+  for (const list of Object.values(ifs)) {
+    for (const a of list || []) {
+      if (!a.internal && (a.family === "IPv4" || a.family === 4)) { return true; }
+    }
+  }
+  return false;
+}
+
+// 第二步：TCP 连一下基准目标。只判断「本机能不能出去」，与 GitHub 是否可达无关 ——
+// 后者交给正常探测（换 IP 能救的属于 GitHub 侧，不在这里判）。
+export function canReach(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ host, port });
+    let done = false;
+    const fin = (ok) => {
+      if (done) { return; }
+      done = true;
+      try { sock.destroy(); } catch { /* 忽略 */ }
+      resolve(ok);
+    };
+    sock.setTimeout(timeoutMs, () => fin(false));
+    sock.on("connect", () => fin(true));
+    sock.on("error", () => fin(false));
+  });
+}
+
+// 基准目标默认用阿里公共 DNS 的 DoH 端点（223.5.5.5:443）：
+// 国内任何正常网络都该能连上，且它不是 GitHub —— 不会被 SNI 封锁影响判断。
+export async function hasLocalNetwork(cfg) {
+  const c = cfg.networkCheck || {};
+  if (c.enabled === false) { return true; }
+  if (!hasInterface()) { return false; }
+  const p = c.probe || {};
+  return canReach(p.host || "223.5.5.5", p.port ?? 443, p.timeoutMs ?? 2000);
+}

package/src/pool.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 候选池自动更新：从 GitHub 官方 api.github.com/meta 拉最新网段 → 展开成候选 IP → 缓存到用户目录。
+// 为什么需要它：GitHub 的 Azure 段（20.x / 4.x）在变，内置静态池会过期
+// （2026-10-11 实测：内置 24 个里有 4 个已不在官方 web 段）。
+// 🔴 api.github.com/meta 未认证限 60 次/小时 —— 所以只能低频（默认每天 1 次），绝不能轮询。
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import { userDataDir } from "./hosts.js";
+
+export function poolCachePath() {
+  return path.join(userDataDir(), "pool.cache.json");
+}
+
+export function readPoolCache() {
+  try {
+    const o = JSON.parse(fs.readFileSync(poolCachePath(), "utf8"));
+    return o && typeof o === "object" ? o : null;
+  } catch { return null; }
+}
+
+function writePoolCache(obj) {
+  const p = poolCachePath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2), "utf8");
+  } catch { /* 写不了就算了，探测侧对缺缓存是宽容的 */ }
+}
+
+const toInt = (s) => s.split(".").reduce((a, o) => a * 256 + Number(o), 0) >>> 0;
+const toIp = (v) => [(v >>> 24) & 255, (v >>> 16) & 255, (v >>> 8) & 255, v & 255].join(".");
+
+// CIDR -> 候选 IP。
+// 🔴 不能全展开：meta 的 web 段里有 /20、/22，一个 /20 就是 4096 个地址，全展开会让探测成本爆炸。
+//    实际在用的是 /32 单播（GitHub 把它们逐个列出来就是给你白名单用的）与大段里的固定偏移
+//    （GitHub 习惯用段内 .3 / .4 做 web/api），所以大段只采样 perBigNet 个。
+export function expandCidr(cidr, perBigNet = 4) {
+  const raw = String(cidr || "").trim();
+  if (!raw || raw.includes(":")) { return []; } // 跳过 IPv6（本项目只探 v4）
+  const slash = raw.indexOf("/");
+  const net = slash === -1 ? raw : raw.slice(0, slash);
+  const bits = slash === -1 ? 32 : Number(raw.slice(slash + 1));
+  if (!Number.isFinite(bits) || bits < 0 || bits > 32) { return []; }
+  const parts = net.split(".");
+  if (parts.length !== 4 || parts.some((x) => !/^\d{1,3}$/.test(x) || Number(x) > 255)) { return []; }
+  if (bits === 32) { return [net]; }
+  const base = toInt(net);
+  const size = 2 ** (32 - bits);
+  const out = [];
+  for (let i = 0; i < perBigNet; i++) {
+    const v = (base + 3 + i) >>> 0;            // 从段内 .3 起
+    if (v >= base + size) { break; }
+    out.push(toIp(v));
+  }
+  return out;
+}
+
+// 用指定 IP + SNI 直连拉 meta。
+// 🔴 必须用 IP 直连：api.github.com 的 DNS 在国内被污染（实测直连拿不到响应），
+//    而这里恰恰是「还没有可用 IP 时」才需要它 —— 所以只能用配置里的种子池。
+// onReq：把底层 request 暴露给调用方，便于「某个种子先成功」时掐掉其余在飞的请求。
+function fetchMeta(ip, host, pathName, timeoutMs, onReq) {
+  return new Promise((resolve, reject) => {
+    const req = https.get({
+      host: ip,
+      port: 443,
+      servername: host,
+      path: pathName,
+      headers: { Host: host, "User-Agent": "ghprobe", Accept: "application/json" },
+      rejectUnauthorized: true,
+      timeout: timeoutMs,
+    }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+      let b = "";
+      res.setEncoding("utf8");
+      res.on("data", (d) => { b += d; });
+      res.on("end", () => { try { resolve(JSON.parse(b)); } catch (e) { reject(new Error("meta 不是合法 JSON")); } });
+    });
+    if (onReq) { onReq(req); }
+    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("error", reject);
+  });
+}
+
+// 并行试所有种子，**第一个成功的立刻返回**并掐掉其余在飞请求。
+// 为什么不用 Promise.allSettled：它要等**最慢**那个（黑洞种子会一直挂到 timeoutMs），
+// 实测总耗时 = 8s（正好一个 timeout），等于没并行。
+// 为什么不用 Promise.any：它只给第一个成功的值，拿不到「是哪个 IP 拉到的」，日志里就没法记 via。
+export function fetchFirstMeta(seeds, host, pathName, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    if (!seeds.length) { reject(new Error("没有可用种子 IP")); return; }
+    const reqs = [];
+    const errs = [];
+    let left = seeds.length;
+    let done = false;
+    const finish = (fn, arg) => {
+      if (done) { return; }
+      done = true;
+      for (const r of reqs) { try { r.destroy(); } catch { /* 忽略 */ } }
+      fn(arg);
+    };
+    for (const ip of seeds) {
+      fetchMeta(ip, host, pathName, timeoutMs, (r) => reqs.push(r)).then(
+        (json) => finish(resolve, { json, via: ip }),
+        (e) => {
+          errs.push(`${ip}:${e?.message || e}`);
+          left -= 1;
+          if (left === 0) { finish(reject, new Error(`所有种子 IP 都拉不到 ${host}（${errs.slice(0, 3).join(", ")}）`)); }
+        },
+      );
+    }
+  });
+}
+
+// 种子 IP：拉 meta 用的直连入口。优先用配置里的 seed 池，再退回 azure / fastly。
+export function seedIps(cfg) {
+  const p = cfg.ipPools || {};
+  return [...new Set([...(p.seed || []), ...(p.azure || []), ...(p.fastly || [])])];
+}
+
+// 一轮更新：拉 meta -> 展开 -> 写缓存。失败也会写 lastAttempt（冷却），避免每分钟重试撞 60 次/小时限制。
+export async function updatePool(cfg, log = () => {}) {
+  const u = cfg.poolUpdate || {};
+  const url = new URL(u.source || "https://api.github.com/meta");
+  const host = u.host || url.hostname;
+  const pathName = url.pathname || "/meta";
+  const timeoutMs = u.timeoutMs ?? 8000;
+  const attemptedAt = new Date().toISOString();
+  const prev = readPoolCache();
+  try {
+    const seeds = seedIps(cfg);
+    if (!seeds.length) { throw new Error("配置里没有种子 IP（ipPools.seed / azure / fastly 全为空）"); }
+    // 并行试所有种子，第一个成功的立刻返回（实测 8.2s -> 亚秒级；串行时是 2m13s）。
+    const { json, via } = await fetchFirstMeta(seeds, host, pathName, timeoutMs);
+
+    const sections = u.sections || ["web", "api"];
+    const maxIps = u.maxIps ?? 48;
+    const perBigNet = u.perBigNet ?? 4;
+    const cidrs = [];
+    for (const s of sections) { if (Array.isArray(json[s])) { cidrs.push(...json[s]); } }
+    // /32 优先：那些才是 GitHub 实际在用的入口；大段采样只是补充
+    const singles = cidrs.filter((c) => String(c).endsWith("/32")).flatMap((c) => expandCidr(c));
+    const bigs = cidrs.filter((c) => !String(c).endsWith("/32")).flatMap((c) => expandCidr(c, perBigNet));
+    const ips = [...new Set([...singles, ...bigs])].slice(0, maxIps);
+
+    const cache = { at: new Date().toISOString(), lastAttempt: attemptedAt, via, sections, count: ips.length, ips };
+    writePoolCache(cache);
+    log(`池已更新：${ips.length} 个 IP（via ${via}，段 ${sections.join("+")}）`);
+    return { ok: true, count: ips.length, via, path: poolCachePath() };
+  } catch (e) {
+    writePoolCache({ ...(prev || {}), lastAttempt: attemptedAt, lastError: String(e.message || e) });
+    throw e;
+  }
+}
+
+// 是否该更新。🔴 **成功与失败用同一档冷却**（intervalHours，默认 24h）：
+// 拉 meta 走的是 api.github.com —— 如果它被 SNI 层封锁，换任何 IP 都救不回，
+// 那种情况下反复重试毫无意义（还白撞 60 次/小时的 API 限制），所以失败后也等满一个周期再说。
+// 手动更新不受此限制：`ghprobe update-pool` 永远立即执行。
+export function poolNeedsUpdate(cfg) {
+  if (cfg.poolUpdate?.enabled === false) { return false; }
+  const intervalH = cfg.poolUpdate?.intervalHours ?? 24;
+  const c = readPoolCache();
+  const now = Date.now();
+  const fresh = (ts) => ts && now - new Date(ts).getTime() < intervalH * 3600_000;
+  if (fresh(c?.at)) { return false; }           // 成功过，没到点
+  if (fresh(c?.lastAttempt)) { return false; }  // 尝试过（成功或失败），没到点
+  return true;
+}

package/src/probe.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 一轮完整探测：DoH 候选 + 内置池 -> 三关并发探测 -> 排名 -> 兜底轮
+import { resolveAll } from "./doh.js";
+import { probeIp, pool } from "./prober.js";
+import { rank, neededFallbacks } from "./ranker.js";
+
+// 该域名该用哪些内置池。
+// 默认（未配 domainPools 或配了不存在的池名）用全部池 —— 保持「与域名无关地全量进候选」
+// 的老行为，由 TLS 证书终审 + 应用层终审判归属。
+// 配了 domainPools 就只取指定的池：185.199.x.x（Fastly）永远不给 github.com 服务，
+// 20.x 也不给 raw.githubusercontent.com 服务，互探纯属浪费——冷启动能省掉近一半候选。
+export function poolsForDomain(cfg, domain) {
+  const pools = cfg.ipPools || {};
+  const names = cfg.domainPools?.[domain];
+  if (!Array.isArray(names) || names.length === 0) { return Object.values(pools).flat(); }
+  const picked = names.flatMap((n) => pools[n] || []);
+  return picked.length ? picked : Object.values(pools).flat();
+}
+
+// 解析一批域名的候选 IP。域名之间并行 —— DoH 是纯网络等待，串行会把最坏耗时
+// 乘上域名数（6 个域名 × dohMs 5s = 30s），并行后压回一个 dohMs。
+async function resolveCandidates(cfg, domains, say, { usePool = true, prefix = "" } = {}) {
+  return Promise.all(domains.map(async (domain) => {
+    say(prefix ? `${prefix}探测 ${domain}` : `解析 ${domain}`);
+    const { ips } = await resolveAll(cfg.doh, domain, cfg.timeouts.dohMs);
+    // 🔴 两个来源**各自限额后再合并**，绝不能对合并结果做总限额。
+    // 实测（2026-10）：DoH 对 github.com 返回的 8 条里有一半是 Fastly 的 185.199.x.x
+    // ——那是 githubusercontent 的节点，根本不给 github.com 服务。按总限额截断时，
+    // 内置池会被这堆垃圾整个挤掉，于是出现「20.29.134.23 明明是活的，工具却报
+    // stuck=github.com」。分开限额后内置池一定拿得到名额。
+    const fromDoh = (ips || []).slice(0, cfg.probe.maxCandidates);
+    const fromPool = usePool ? poolsForDomain(cfg, domain).slice(0, cfg.probe.maxPoolIps ?? 12) : [];
+    const candidates = [...new Set([...fromDoh, ...fromPool])];
+    say(`  候选 ${candidates.length} 个: ${candidates.join(", ")}`);
+    return { domain, candidates };
+  }));
+}
+
+// 把所有 (域名, IP) 拍平成任务队列，交给一个**全局**并发池跑。
+// 每个域名各自开一个池的话，实际并发 = 域名数 × concurrency（6×6=36 条 socket），
+// 会把最坏耗时和瞬时连接数同时放大；全局单池才是真正的「同时最多 N 条」。
+function jobsOf(cfg, resolved) {
+  const jobs = [];
+  for (const { domain, candidates } of resolved) {
+    for (const ip of candidates) { jobs.push(() => probeIp(domain, ip, cfg)); }
+  }
+  return jobs;
+}
+
+// onlyDomains：只探这些域名。部分更新（health 只发现某 1 个域名坏了）时用它，
+// 避免「1 个域名失效却把 6 个域名、近 50 个候选全探一遍」——那是几十秒的纯浪费。
+// 传 null / 空数组 = 全量。注意兜底域名不在 cfg.domains 里，若被点名必须单独直探。
+export async function runProbe(cfg, log, onlyDomains = null) {
+  const say = log || (() => {});
+  const fbDomains = Object.values(cfg.fallbacks || {}).flat();
+  const want = onlyDomains && onlyDomains.length ? new Set(onlyDomains) : null;
+  const mainDomains = cfg.domains.filter((d) => !want || want.has(d));
+  const directFb = want ? [...want].filter((d) => fbDomains.includes(d) && !cfg.domains.includes(d)) : [];
+
+  const resolved = await resolveCandidates(cfg, mainDomains, say);
+  const all = await pool(jobsOf(cfg, resolved), cfg.probe.concurrency);
+  const ranked = rank(all, cfg);
+
+  // 兜底轮：主域名全灭且配了替身 -> 探测替身域名
+  const extra = new Map();
+  const alts = [...new Set([...neededFallbacks(ranked, cfg), ...directFb])];
+  if (alts.length) {
+    const altResolved = await resolveCandidates(cfg, alts, say, { usePool: false, prefix: "兜底" });
+    const rs = await pool(jobsOf(cfg, altResolved), cfg.probe.concurrency);
+    for (const [d, list] of rank(rs, cfg)) {
+      if (list.length) { extra.set(d, list); }
+    }
+  }
+  return { ranked, extra, raw: all, at: new Date().toISOString() };
+}