ghprobe 0.0.0-stage → 0.1.1

package/bin/ghprobe.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// ghprobe CLI：probe / serve / hosts / install / uninstall
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { loadConfig, ensureUserConfig, userConfigPath } from "../src/config.js";
+import { updatePool, poolNeedsUpdate, poolCachePath } from "../src/pool.js";
+import { hasLocalNetwork } from "../src/net.js";
+import { probeNow, startServer } from "../src/server.js";
+import { runHealth, blockFromProbeResult, shouldKeepOldBlock } from "../src/health.js";
+import { mergeHosts, applyHosts, restoreHosts, WIN_HOSTS, acquireHostsLock, releaseHostsLock, runElevated, buildUninstallTaskScript, buildInstallScript, buildHiddenRunnerVbs, userDataDir } from "../src/hosts.js";
+import { readFileSync } from "node:fs";
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+// 健康检查日志写到用户数据目录，而不是包目录：npm 全局安装时包目录位于 node_modules 下，
+// npm 升级/重装会整个换掉，日志放那儿会被清掉。
+function healthLogPath() {
+  return path.join(userDataDir(), "ghprobe.log");
+}
+
+// 无窗口运行包装器（VBScript）的落地路径。计划任务跑的是它，不是 node 本体。
+function hiddenRunnerPath() {
+  return path.join(userDataDir(), "run-hidden.vbs");
+}
+
+// 计划任务静默运行，stdout/stderr 都丢；每轮结果追加日志文件，跑挂了能查到。
+// stuck 单独记：它表示「探测跑了、但这个域名本轮一个活 IP 都没找到，只能保留旧值」——
+// 只看 action=none 会误以为工具没干活，其实可能是链路整体被黑洞了。
+function writeHealthLog(action, reason, extra = {}) {
+  const entry = `${new Date().toISOString()} health action=${action} reason=${reason}`
+    + `${extra.changed && extra.changed.length ? ` changed=${extra.changed.join(",")}` : ""}`
+    + `${extra.stuck && extra.stuck.length ? ` stuck=${extra.stuck.join(",")}` : ""}\n`;
+  try {
+    const f = healthLogPath();
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    // 新文件写 UTF-8 BOM：否则 PowerShell 5.1 的 Get-Content 会按系统 ANSI 解码，
+    // 中文日志在用户查看时变乱码（文件本身没错，是读取端猜错编码）。
+    const prefix = fs.existsSync(f) ? "" : "\ufeff";
+    fs.appendFileSync(f, prefix + entry);
+  } catch { /* 日志写失败不影响主流程 */ }
+}
+
+// 打印 hosts 块里的 IP 条目（install 完成后回显写入结果）
+function printHostsEntries() {
+  try {
+    const m = readFileSync(WIN_HOSTS, "utf8").match(/# === ghprobe begin ===[\s\S]*?# === ghprobe end ===/);
+    if (!m) { return; }
+    for (const l of m[0].split(/\r?\n/).filter((x) => /^\d+\.\d+\.\d+\.\d+\s/.test(x))) { console.log(`  ${l}`); }
+  } catch { /* 读不到就算了 */ }
+}
+
+// 严格仅 Windows：hosts 路径硬编码 + Start-Process 提权 + ipconfig，非 Windows 直接给清晰报错
+if (process.platform !== "win32") {
+  console.error("ghprobe 当前仅支持 Windows：hosts 路径与提权机制依赖 Windows 系统");
+  process.exit(1);
+}
+const program = new Command();
+// 版本号从 package.json 读，不写死 —— 否则 npm version 之后 --version 会漂移
+const PKG = JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8"));
+program.name("ghprobe").description("GitHub 直连优选：本地 DoH + TLS 证书终审探测 + hosts 生成（无代理）").version(PKG.version);
+
+// 打印一轮结果的可读摘要
+function printSummary(r) {
+  for (const [domain, rs] of r.ranked) {
+    if (!rs.length) { console.log(`[FAIL] ${domain} 主候选全灭（看兜底链）`); continue; }
+    const best = rs[0];
+    console.log(`[ OK ] ${domain}  best=${best.ip}  tcp=${best.tcpMs}ms tls=${best.tlsMs}ms ttfb=${best.ttfb}ms  备选 ${rs.length - 1}`);
+  }
+  for (const [domain, rs] of r.extra) {
+    if (rs.length) { console.log(`[FBKP] ${domain} -> 兜底命中 ${rs[0].ip} (${rs[0].score})`); }
+  }
+}
+
+program.command("probe")
+  .description("跑一轮探测并输出结果（不写 hosts）")
+  .option("-c, --config <path>", "用户配置覆盖")
+  .option("-j, --json", "输出 JSON")
+  .option("-a, --apply", "探测后写入系统 hosts（会弹 UAC）")
+  .action(async (opts) => {
+    const cfg = loadConfig(opts.config);
+    if (!(await hasLocalNetwork(cfg))) {
+      console.error("本地无网络连接，跳过探测（不写 hosts）");
+      process.exitCode = 1;
+      return;
+    }
+    const r = await probeNow(cfg, (m) => { if (!opts.json) { console.error(m); } });
+    if (opts.json) {
+      const out = { at: r.at, domains: [...r.ranked].map(([d, rs]) => ({ domain: d, alive: rs.map((x) => ({ ip: x.ip, tcpMs: x.tcpMs, tlsMs: x.tlsMs, ttfb: x.ttfb, score: x.score })) })), extra: [...r.extra].map(([d, rs]) => ({ domain: d, alive: rs.map((x) => x.ip) })) };
+      console.log(JSON.stringify(out, null, 2));
+    } else {
+      printSummary(r);
+    }
+    if (opts.apply) {
+      const lock = acquireHostsLock();
+      if (!lock) {
+        console.error("另一进程正在写 hosts，本轮跳过（下轮健康检查会自动补写）");
+      } else {
+        try {
+          const current = readFileSync(WIN_HOSTS, "utf8");
+          // 块格式与 health 保持一致（含 # absent 冷却），并走同一道全灭护栏
+          const block = blockFromProbeResult(cfg, r);
+          if (shouldKeepOldBlock(current, block)) {
+            console.error("本轮全部域名不可达（疑似网络故障），保留 hosts 中的旧条目不动");
+          } else {
+            const res = await applyHosts(mergeHosts(current, block));
+            console.log(`hosts 已写入，备份在 ${res.backup}`);
+          }
+        } finally { releaseHostsLock(lock); }
+      }
+    }
+  });
+
+program.command("serve")
+  .description("启动本地 HTTP API（默认 127.0.0.1:8930）")
+  .option("-c, --config <path>", "用户配置覆盖")
+  .action(async (opts) => {
+    const cfg = loadConfig(opts.config);
+    await startServer(cfg, (m) => console.error(`[serve] ${m}`));
+    console.log(`ghprobe serve -> http://${cfg.serve.host}:${cfg.serve.port}`);
+    console.log("POST /api/probe 触发探测 | GET /api/status /api/hosts /api/config");
+  });
+
+program.command("hosts")
+  .description("生成 hosts 块文本（先探测一次）")
+  .option("-c, --config <path>", "用户配置覆盖")
+  .action(async (opts) => {
+    const cfg = loadConfig(opts.config);
+    const r = await probeNow(cfg, (m) => console.error(m));
+    console.log(blockFromProbeResult(cfg, r));
+  });
+
+program.command("health")
+  .description("健康检查：只测已写入 IP，异常才全量重排换 IP（加 --apply 才写 hosts）")
+  .option("-c, --config <path>", "用户配置覆盖")
+  .option("-a, --apply", "检测到异常时写入系统 hosts（会弹 UAC）")
+  .action(async (opts) => {
+    let cfg = loadConfig(opts.config);
+    // 本地断网 -> 直接跳过：所有候选必然全灭，跑一轮只会刷屏并把真故障淹掉。
+    if (!(await hasLocalNetwork(cfg))) {
+      console.error("本地无网络连接，跳过本轮（不探测、不更新池、不写 hosts）");
+      writeHealthLog("skip", "本地无网络连接");
+      return;
+    }
+    // 到点先更新候选池（默认每天 1 次；成功失败同一档冷却，不会反复重试）。
+    // 放最前：池子新了，后面的重排才有更宽的候选可用；更新成功后重新加载配置以吃进新池。
+    if (poolNeedsUpdate(cfg)) {
+      try {
+        await updatePool(cfg, (m) => console.error(m));
+        cfg = loadConfig(opts.config);
+      } catch (e) {
+        console.error(`候选池更新失败（忽略，用现有池继续）: ${e.message}`);
+      }
+    }
+    const r = await runHealth(cfg, (m) => console.error(m), Boolean(opts.apply));
+    writeHealthLog(r.action, r.reason, r);
+  });
+
+program.command("install")
+  .description("一键开启：写一次 hosts + 注册计划任务（定时健康检查），全程只需一次 UAC")
+  .option("-c, --config <path>", "用户配置覆盖（间隔取 schedule.healthMin 分钟）")
+  .option("--skip-probe", "只注册计划任务，不立即探测写 hosts（等下一次定时触发）")
+  .action(async (opts) => {
+    // 生成用户可编辑的配置文件（已存在则不覆盖，保留用户改动）
+    const ucfg = ensureUserConfig();
+    const cfg = loadConfig(opts.config);
+    const minutes = cfg.schedule?.healthMin ?? 1;
+    console.log(`用户配置：${ucfg}`);
+    console.log("（可直接编辑：候选池 / 超时 / 调度间隔都在里面，优先级高于包内默认）");
+    // 断网时不探测（必然全灭），但**仍然注册计划任务** —— 有网后任务会自动跑起来
+    const online = await hasLocalNetwork(cfg);
+    const skipProbe = Boolean(opts.skipProbe) || !online;
+    if (!online) { console.log("本地无网络连接：本次跳过探测写 hosts（计划任务仍会注册，有网后自动生效）"); }
+    // 包内 bin 与当前 node 的绝对路径：npm 全局安装后二者都指向真实位置，
+    // 不依赖计划任务进程的 PATH（highest runlevel 下 PATH 未必含 %APPDATA%\npm）。
+    const bin = path.join(ROOT, "bin", "ghprobe.js");
+    const cfgArg = opts.config ? ` -c "${opts.config}"` : "";
+
+    // 无窗口运行：Task Scheduler 起 node.exe 必弹控制台窗口，而 node 没有隐藏窗口的开关。
+    // 写一个 VBS 包装器（wscript + WScript.Shell.Run(..., 0, True) = SW_HIDE），任务改成跑它。
+    // 写失败不阻断安装：退回直接跑 node，功能一样，只是会闪一下窗口。
+    let vbsPath = "";
+    try {
+      const v = hiddenRunnerPath();
+      fs.mkdirSync(path.dirname(v), { recursive: true });
+      fs.writeFileSync(v, buildHiddenRunnerVbs(process.execPath, bin, `health --apply${cfgArg}`), "ascii");
+      vbsPath = v;
+    } catch (e) {
+      console.error(`无窗口包装器写入失败（退回直接运行，可能会闪一下窗口）: ${e.message}`);
+    }
+
+    // 用 runHealth 的保守决策（只预览、不写）来算该写什么：
+    // 它会先测 hosts 里已写入的 IP，健康的保留，只有确认失效的才重排。
+    // 若直接拿全量探测结果覆盖，会把「本轮没抓到、但现有 IP 仍然健康」的域名误记成 absent。
+    let merged = null;
+    if (!opts.skipProbe) {
+      console.log("正在检查现有条目并探测（约 1 分钟）…");
+      const h = await runHealth(cfg, (m) => console.error(m), false);
+      if (h.block) { merged = mergeHosts(readFileSync(WIN_HOSTS, "utf8"), h.block); }
+      else { console.log(`hosts 无需改动：${h.reason}`); }
+    }
+
+    const tmp = path.join(os.tmpdir(), `ghprobe-install-${Date.now()}.tmp`);
+    fs.writeFileSync(tmp, merged || "", "utf8");
+    const writeHosts = merged != null;
+    try {
+      // 用 Register-ScheduledTask 而非 schtasks：/TR 的嵌套引号在 cmd 里必打架
+      // RunLevel Highest：任务以管理员权限静默运行，applyHosts 不再额外弹 UAC
+      // UserId 必须用 COMPUTERNAME\USERNAME（裸用户名非合法 UserId，会 E_INVALIDARG）
+      const res = await runElevated(buildInstallScript({
+        hostsPath: WIN_HOSTS, tmpPath: tmp, nodePath: process.execPath, binPath: bin, cfgArg, minutes, writeHosts, vbsPath,
+      }));
+      if (res.code !== 0) { console.error(`安装失败: ${res.err || res.out}`); process.exitCode = 1; return; }
+    } catch (e) {
+      console.error(`安装失败: ${e.message}`);
+      process.exitCode = 1;
+      return;
+    } finally {
+      try { fs.unlinkSync(tmp); } catch { /* 清理失败不管 */ }
+    }
+
+    console.log(`计划任务 ghprobe 已注册：每 ${minutes} 分钟健康检查（health --apply，runlevel=highest，无窗口）`);
+    if (opts.skipProbe) { console.log("未写 hosts（--skip-probe）；下一次定时到点会自动处理。"); return; }
+    if (merged == null) { console.log("hosts 未改动（现有条目仍然健康）。"); return; }
+    console.log("hosts 已写入 ✓");
+    printHostsEntries();
+    console.log("停止：ghprobe uninstall");
+  });
+
+program.command("uninstall")
+  .description("删除 ghprobe 计划任务并还原 hosts")
+  .action(async () => {
+    // 两步互相独立：任一步失败都不影响另一步，最后统一置 exitCode
+    try {
+      await restoreHosts();
+      console.log("hosts 已还原");
+    } catch (e) {
+      console.error(`还原 hosts 失败: ${e.message}`);
+      process.exitCode = 1;
+    }
+    // 删任务同样需要管理员权限：任务建在根目录且 RunLevel=Highest，非提权删会「拒绝访问」，
+    // 因此这里和 install 一样走 runElevated 自提权（已提权时会话内直接执行，不再弹 UAC）。
+    try {
+      const r = await runElevated(buildUninstallTaskScript());
+      if (r.code === 0) { console.log("计划任务 ghprobe 已删除（若本就不存在则跳过）"); }
+      else { console.error(`删除计划任务失败: ${r.err || r.out}`); process.exitCode = 1; }
+    } catch (e) {
+      console.error(`删除计划任务失败: ${e.message}`);
+      process.exitCode = 1;
+    }
+    // 包装器是 ghprobe 自己生成的临时产物，顺手清掉（删不掉也不影响，下次 install 会覆盖）
+    try { fs.unlinkSync(hiddenRunnerPath()); } catch { /* 不存在就算了 */ }
+  });
+
+program.command("update-pool")
+  .description("从 GitHub 官方 api.github.com/meta 更新候选池缓存（每天一次即可，该 API 限 60 次/小时）")
+  .option("-c, --config <path>", "用户配置覆盖")
+  .action(async (opts) => {
+    const cfg = loadConfig(opts.config);
+    try {
+      const r = await updatePool(cfg, (m) => console.error(m));
+      console.log(`候选池已更新：${r.count} 个 IP`);
+      console.log(`  经 ${r.via} 拉取 -> ${r.path}`);
+      console.log("下次 probe / health 会自动使用 auto 池");
+    } catch (e) {
+      console.error(`更新失败: ${e.message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program.command("config-path")
+  .description("打印用户配置文件与池缓存的路径（配置文件可直接编辑）")
+  .action(() => {
+    console.log(`配置：${userConfigPath()}`);
+    console.log(`池缓存：${poolCachePath()}`);
+  });
+
+program.parseAsync();

package/config.default.yaml

@@ -0,0 +1,140 @@
+# ghprobe 默认配置（用户可用 --config 覆盖，键名一致即可）
+# 目标域名族：每域名独立探测、独立写 hosts
+domains:
+  - github.com
+  - codeload.github.com
+  - objects.githubusercontent.com
+  - raw.githubusercontent.com
+  - gist.githubusercontent.com
+  - avatars.githubusercontent.com
+
+# DoH 端点（全部 IP 直连，绕开解析 DoH 域名的死锁；默认只放国内实测可达端点）
+# sni 填服务域名：TLS 握手按它验证书（RFC 6066 不允许拿 IP 当 SNI）
+doh:
+  - { name: alidns1, host: 223.5.5.5, sni: dns.alidns.com, path: /dns-query }
+  - { name: alidns2, host: 223.6.6.6, sni: dns.alidns.com, path: /dns-query }
+  - { name: dnspod, host: 1.12.12.12, sni: doh.pub, path: /dns-query }
+
+# 内置候选 IP 池：补足 DoH 拿不到的候选。
+# 🔴 池子必须够宽，否则会出现「明明有活 IP，工具却报 stuck」——见下面 azure 段的说明。
+ipPools:
+  # 种子池：**最稳定的入口，建议不要删**。属于 GitHub 自租段 140.82.112.0/20，多年未变。
+  # 两个用途：① github.com / codeload 的兜底候选；
+  #          ② 拉 api.github.com/meta 更新 auto 池时的**直连入口**（该域名 DNS 在国内被污染，
+  #             只能靠这些 IP + SNI 直连；而且这一步恰恰发生在「还没有可用 IP」的时候）。
+  seed:
+    - 140.82.112.3
+    - 140.82.112.4
+    - 140.82.113.3
+    - 140.82.113.4
+    - 140.82.114.3
+    - 140.82.114.4
+    - 140.82.116.3
+    - 140.82.116.4
+    - 140.82.121.3
+  # Fastly 段：服务 githubusercontent 系（raw / objects / gist / avatars），多年不变
+  fastly: [185.199.108.133, 185.199.109.133, 185.199.110.133, 185.199.111.133]
+  # GitHub 自租段：服务 github.com / codeload.github.com 主站。
+  # 🔴 2026-10 实测：这些 IP **在分钟级抖动** —— 同一批 IP 几分钟前全灭、现在 9/20 可用，
+  #    且「活的是哪几个」每次都不一样。所以池子必须宽（靠 tcpMs 短超时兜住成本），
+  #    只留少量 IP 必然出现「明明有活 IP 却报 stuck」。
+  # ⚠️ 这一池**会过期**（2026-10-11 实测：24 个里有 4 个已不在官方 web 段）——
+  #    它是「离线兜底」，真正跟得上变化的是下面 poolUpdate 自动维护的 `auto` 池。
+  azure:
+    # Azure 段（亚太/欧洲）
+    - 20.200.245.247
+    - 20.201.28.151
+    - 20.207.73.82
+    - 20.217.135.5
+    - 20.233.83.145
+    - 20.248.137.48
+    - 20.26.156.215
+    - 20.29.134.23
+    - 20.87.245.0
+    - 20.205.243.166
+    - 20.205.243.167
+    - 20.205.243.168
+    - 4.237.22.34
+    - 20.27.177.113
+    - 4.208.26.197
+    # 140.82.112.0/20（美国，web/api 走 .3 / .4）
+    - 140.82.112.3
+    - 140.82.112.4
+    - 140.82.113.3
+    - 140.82.113.4
+    - 140.82.114.3
+    - 140.82.114.4
+    - 140.82.116.3
+    - 140.82.116.4
+    - 140.82.121.3
+
+# 域名 -> 只探哪些池（不配 = 用全部池）。
+# 两个池互不相干：185.199.x.x 永远不给 github.com 服务，20.x 也不给 raw.githubusercontent.com
+# 服务。分开能省掉近一半候选（冷启动最明显）。池名写错时自动退回「用全部池」。
+# auto = poolUpdate 自动从 api.github.com/meta 拉下来的最新网段（缓存不存在时该池为空，自动跳过）。
+# 顺序有意义：靠前的池先占 maxPoolIps 名额。
+domainPools:
+  github.com: [auto, seed, azure]
+  codeload.github.com: [auto, seed, azure]
+  objects.githubusercontent.com: [fastly]
+  raw.githubusercontent.com: [fastly]
+  gist.githubusercontent.com: [fastly]
+  avatars.githubusercontent.com: [fastly]
+
+# 候选池自动更新：从 GitHub 官方 api.github.com/meta 拉最新网段，缓存到用户目录，供 `auto` 池使用。
+# 为什么需要：GitHub 的 Azure 段在变，内置 azure 池会过期（实测 24 个里 4 个已失效）。
+# 🔴 api.github.com/meta 未认证限 **60 次/小时** —— 所以 intervalHours 只能大（默认每天 1 次），
+#    绝不要调到 1 以下。
+# ⚠️ 若 api.github.com 被 SNI 层封锁（换 IP 也救不回），**失败后同样等满一个周期再试**，
+#    不会反复重试 —— 那种情况下继续重试没有意义，用现有池 + DoH 继续工作即可。
+# 手动触发：`ghprobe update-pool`（不受周期限制）；自动触发：每次 health（到点才真去拉）。
+# 缓存文件：%LOCALAPPDATA%\ghprobe\pool.cache.json（自动生成，不用手改）
+poolUpdate:
+  enabled: true
+  intervalHours: 24         # 更新间隔（小时）；成功与失败同一档
+  source: "https://api.github.com/meta"
+  host: api.github.com      # TLS SNI（实际连的是 ipPools.seed 里的 IP）
+  sections: [web, api]      # 取 meta 里的哪些段
+  maxIps: 48                # 缓存里最多保留几个 IP
+  perBigNet: 4              # 大网段（/20、/22）每个采样几个 IP（不能全展开，/20 = 4096 个）
+  timeoutMs: 8000
+
+# 本地网络检查：本机断网时直接跳过本轮（不探测、不更新池、不写 hosts）。
+# 为什么需要：断网时所有候选必然全灭，跑一轮纯属浪费，日志还会被「stuck / 全灭」刷屏，
+# 把「本机没网」和「GitHub 被墙」两种情况混在一起，反而看不出真故障。
+# 两步：① 有没有「已启用且带非回环 IPv4」的网卡（零成本）；② TCP 连一下基准目标。
+# 基准目标必须是**国内任何正常网络都该能连上**的（默认阿里公共 DNS 的 DoH 端点），
+# 它只用来判断「本机能不能出去」，与 GitHub 是否可达无关。
+networkCheck:
+  enabled: true
+  probe: { host: 223.5.5.5, port: 443, timeoutMs: 2000 }
+
+# 被主机名黑名单掐掉的域名走兜底链：主候选全灭时改探测这些替身域名并写入
+fallbacks:
+  raw.githubusercontent.com: [cdn.jsdelivr.net]
+
+# 超时：tcpMs 只管 TCP 握手阶段（死 IP 快速淘汰），握手成功后自动切到 tlsMs。
+# 黑洞 IP 会一直挂到超时，所以这两段必须分开 —— 否则每加一个候选都要多等 tlsMs。
+timeouts: { dohMs: 5000, tcpMs: 2500, tlsMs: 6000, httpMs: 6000 }
+probe:
+  maxCandidates: 8   # DoH 每域名最多取几个候选
+  maxPoolIps: 32     # 内置池每域名最多补几个。**与 DoH 各自限额，不共享总上限**（见 probe.js）
+  maxPerDomain: 4    # 每域名最多保留几个可用 IP（前 maxEntriesPerDomain 个会写进 hosts）
+  concurrency: 10    # 全局同时握手的 socket 上限（跨域名共享）
+# hosts 写入：每域名写几条候选。
+# 🔴 2026-10-11 实测推翻旧假设「Windows 同一域名只取第一条」—— hosts 里同名多条会被
+#    解析器**全部返回**（保持文件顺序），且 curl / 浏览器会**逐个尝试**：黑洞 IP 排在前
+#    也能 fallback 到后面的活 IP（实测 http=200 / 0.22s）。所以多写 1 条备选 = 抖动时
+#    客户端自动兜底，把「断最长 1 分钟」变成「多等一个连接超时」。
+#    不要贪多：每多一个死 IP 就多叠一个连接超时；2 条是收益/代价的平衡点。1 = 退回旧行为。
+hosts:
+  maxEntriesPerDomain: 2
+serve: { host: 127.0.0.1, port: 8930 }
+# 调度：固定频率健康检查，不做指数退避（哨兵一轮 <2s，退避省不下开销反而拉长最坏发现延迟）
+schedule:
+  # 哨兵间隔（分钟）：只测已写入 IP（3 条并发，健康时 ~1s），异常才触发全量重排。
+  # 🔴 取 1 是刻意的：这是「IP 死了到自动换掉」的**最坏等待**。5 分钟时代码本身只要 20s 就能修好，
+  #    但用户平均要多等 2.5 分钟 —— 卡在调度间隔上而不是卡在探测上。1 分钟是 Task Scheduler
+  #    重复间隔的下限（New-ScheduledTaskTrigger 最小 1 分钟），已经到底了。
+  healthMin: 1
+  absentCooldownHours: 1  # 缺失域名冷却（小时）：SNI 层封锁的域名全量也救不回，冷却内不重试

package/install.cmd

@@ -0,0 +1,8 @@
+@echo off
+rem ghprobe one-click deploy wrapper (ASCII only: cmd.exe reads .cmd as OEM codepage)
+chcp 65001 >nul
+setlocal
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" %*
+echo.
+echo ---- Done. Press any key to close. ----
+pause >nul

package/install.ps1

@@ -0,0 +1,119 @@
+#Requires -Version 5.1
+<#
+  ghprobe 一键部署（Windows / PowerShell 5.1+）
+
+  用法：
+    .\install.ps1                 部署：注册计划任务 + 立即写入一次 hosts
+    .\install.ps1 -SkipProbe      只注册计划任务，等首轮健康检查自己写 hosts
+    .\install.ps1 -Uninstall      卸载：删除计划任务 + 还原 hosts
+
+  也可以直接双击 install.cmd（等价）。
+  全程只弹一次 UAC：脚本先自提权，之后的注册/写 hosts 都在管理员会话内静默完成。
+#>
+[CmdletBinding()]
+param(
+  [switch]$Uninstall,
+  [switch]$SkipProbe,
+  [string]$LogFile,
+  [switch]$Inner
+)
+
+$ErrorActionPreference = 'Stop'
+$Root = $PSScriptRoot
+if ([string]::IsNullOrWhiteSpace($LogFile)) { $LogFile = Join-Path $env:TEMP 'ghprobe-deploy.log' }
+
+function Say([string]$m) {
+  $line = "[ghprobe] $m"
+  Write-Host $line
+  try { Add-Content -LiteralPath $LogFile -Value $line -Encoding UTF8 } catch { }
+}
+
+# ── 1. 自提权（注册计划任务需要管理员）────────────────────────────────
+# 只弹一次 UAC：子进程在管理员会话里跑完，父进程回显子进程写的日志。
+$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+if ((-not $isAdmin) -and (-not $Inner)) {
+  Say "需要管理员权限，正在申请提权（只会弹一次 UAC）…"
+  Remove-Item -LiteralPath $LogFile -ErrorAction SilentlyContinue
+  $psArgs = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', "`"$PSCommandPath`"", '-Inner', '-LogFile', "`"$LogFile`"")
+  if ($Uninstall) { $psArgs += '-Uninstall' }
+  if ($SkipProbe) { $psArgs += '-SkipProbe' }
+  $proc = Start-Process -FilePath 'powershell.exe' -Verb RunAs -Wait -PassThru -ArgumentList $psArgs
+  # 注意：Start-Process 被取消时 $proc 为 $null。若直接 exit $proc.ExitCode，
+  # PowerShell 会退化成 exit $null = 0，把"用户拒绝提权"伪装成成功。
+  if ($null -eq $proc) { Write-Host "[ghprobe] 提权被取消，未做任何改动。"; exit 1 }
+  if (Test-Path -LiteralPath $LogFile) { Get-Content -LiteralPath $LogFile | ForEach-Object { Write-Host $_ } }
+  exit $proc.ExitCode
+}
+
+Set-Location -LiteralPath $Root
+Say "工作目录：$Root"
+
+# ── 2. 环境检查：Node >= 18 ─────────────────────────────────────────
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+  Say "错误：未找到 Node.js（需要 >= 18）。请先安装：https://nodejs.org/"
+  exit 1
+}
+# 用 Out-String 兜底：node 异常时输出可能为 $null，直接 .Trim() 会抛「不能对 Null 值表达式调用方法」
+$nodeVer = (& node -p "process.versions.node" 2>$null | Out-String).Trim()
+if ([string]::IsNullOrWhiteSpace($nodeVer)) { Say "错误：无法执行 node -p，Node 安装可能损坏"; exit 1 }
+$okVer = $false
+try { $okVer = ([version]$nodeVer -ge [version]'18.0.0') } catch { Say "错误：无法识别 Node 版本：$nodeVer"; exit 1 }
+if (-not $okVer) { Say "错误：Node 版本 $nodeVer 过低（需要 >= 18）"; exit 1 }
+Say "Node $nodeVer OK"
+
+# ── 3. 依赖 ─────────────────────────────────────────────────────────
+if (-not (Test-Path -LiteralPath (Join-Path $Root 'node_modules'))) {
+  Say "安装依赖（npm install --omit=dev）…"
+  & npm install --omit=dev --no-audit --no-fund
+  if ($LASTEXITCODE -ne 0) { Say "错误：npm install 失败"; exit 1 }
+} else {
+  Say "依赖已就绪"
+}
+
+$Cli = Join-Path $Root 'bin\ghprobe.js'
+$Hosts = 'C:\Windows\System32\drivers\etc\hosts'
+
+# ── 4a. 卸载分支 ────────────────────────────────────────────────────
+if ($Uninstall) {
+  Say "删除计划任务并还原 hosts…"
+  & node $Cli uninstall
+  if ($LASTEXITCODE -ne 0) { Say "错误：卸载失败"; exit 1 }
+  if (Get-ScheduledTask -TaskName 'ghprobe' -ErrorAction SilentlyContinue) {
+    Say "自检失败：计划任务 ghprobe 仍然存在"; exit 1
+  }
+  Say "完成：计划任务已删除，hosts 已还原。"
+  exit 0
+}
+
+# ── 4b. 写 hosts + 注册计划任务（当前已是管理员，内部不会再弹 UAC）────
+# `ghprobe install` 先探测、再在一次提权里同时完成「写 hosts」与「注册任务」
+if ($SkipProbe) {
+  Say "注册计划任务（每 5 分钟健康检查，异常才全量换 IP）…"
+  & node $Cli install --skip-probe
+} else {
+  Say "探测并写入 hosts，同时注册计划任务（约 1 分钟）…"
+  & node $Cli install
+}
+if ($LASTEXITCODE -ne 0) { Say "错误：安装失败"; exit 1 }
+
+# ── 6. 自检：不信任命令行自报的成功 ──────────────────────────────────
+$task = Get-ScheduledTask -TaskName 'ghprobe' -ErrorAction SilentlyContinue
+if (-not $task) { Say "自检失败：未找到计划任务 ghprobe"; exit 1 }
+Say ("自检：计划任务存在（State={0}，重复间隔={1}，RunLevel={2}）" -f $task.State, $task.Triggers[0].Repetition.Interval, $task.Principal.RunLevel)
+
+$inBlock = $false
+$block = @()
+foreach ($line in (Get-Content -LiteralPath $Hosts)) {
+  if ($line -match '^# === ghprobe begin ===') { $inBlock = $true; continue }
+  if ($line -match '^# === ghprobe end ===') { $inBlock = $false; continue }
+  if ($inBlock) { $block += $line.Trim() }
+}
+if ($block.Count -gt 0) {
+  Say "自检：hosts 中的 ghprobe 块："
+  $block | ForEach-Object { Say "        $_" }
+} else {
+  Say "自检：hosts 暂无 ghprobe 块（计划任务首轮会自动写入）"
+}
+
+Say "全部完成。此后无需敲命令：每 5 分钟自动健康检查，IP 陈旧时自动重排。"
+Say "卸载：.\install.ps1 -Uninstall"

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "ghprobe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "GitHub direct-connect optimizer: local DoH resolution + TLS-verified probing + hosts generation (no proxy)",
+  "keywords": [
+    "github",
+    "hosts",
+    "hosts-file",
+    "dns",
+    "dns-over-https",
+    "doh",
+    "sni",
+    "acceleration",
+    "network",
+    "windows",
+    "cli"
+  ],
+  "homepage": "https://github.com/zmw-zmw/ghprobe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zmw-zmw/ghprobe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zmw-zmw/ghprobe/issues"
+  },
+  "author": "zmw",
+  "type": "module",
+  "bin": {
+    "ghprobe": "bin/ghprobe.js"
+  },
+  "main": "bin/ghprobe.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "GPL-3.0-only",
+  "files": [
+    "bin/",
+    "src/",
+    "config.default.yaml",
+    "install.ps1",
+    "install.cmd",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "serve": "node bin/ghprobe.js serve",
+    "probe": "node bin/ghprobe.js probe"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 配置加载：包内默认 YAML + 用户覆盖（对象递归合并：顶层用户键覆盖默认键，对象属性合并而非整体替换）
+// 用户配置放在用户数据目录（%LOCALAPPDATA%\ghprobe\config.yaml），install 时自动生成一份，
+// 用户可自由编辑 —— 放在包目录会被 npm 升级/重装整个换掉。
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "js-yaml";
+import { userDataDir } from "./hosts.js";
+import { readPoolCache } from "./pool.js";
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+// 用户可编辑的配置文件路径（install 时生成；不存在也不报错）
+export function userConfigPath() {
+  return path.join(userDataDir(), "config.yaml");
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date) && !(v instanceof RegExp);
+}
+
+function mergeDefaults(def, user) {
+  if (!isPlainObject(def) || !isPlainObject(user)) { return user === undefined ? def : user; }
+  const out = { ...def };
+  for (const key of Object.keys(user)) {
+    out[key] = isPlainObject(def[key]) && isPlainObject(user[key]) ? mergeDefaults(def[key], user[key]) : user[key];
+  }
+  return out;
+}
+
+// 把「自动更新的池缓存」并进 ipPools.auto（池名固定为 auto，供 domainPools 引用）。
+// 缓存不存在时什么都不做 —— 探测侧对缺失的池名是宽容的（会退回「用全部池」）。
+function withPoolCache(cfg) {
+  const cache = readPoolCache();
+  if (cache && Array.isArray(cache.ips) && cache.ips.length) {
+    cfg.ipPools = { ...(cfg.ipPools || {}), auto: cache.ips };
+  }
+  return cfg;
+}
+
+// 优先级：--config 显式指定 > 用户目录 config.yaml > 包内 config.default.yaml
+export function loadConfig(userPath) {
+  const def = yaml.load(fs.readFileSync(path.join(ROOT, "config.default.yaml"), "utf8"));
+  let user = null;
+  for (const p of [userPath, userConfigPath()]) {
+    if (!p) { continue; }
+    try { user = yaml.load(fs.readFileSync(p, "utf8")); break; } catch { /* 不存在 / 读不了 -> 下一个 */ }
+  }
+  return withPoolCache(user ? mergeDefaults(def, user) : def);
+}
+
+// 首次 install 时把包内默认配置复制成用户配置（已存在则不覆盖，保留用户改动）
+export function ensureUserConfig() {
+  const p = userConfigPath();
+  try {
+    if (!fs.existsSync(p)) {
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.copyFileSync(path.join(ROOT, "config.default.yaml"), p);
+    }
+  } catch { /* 写不了不阻塞安装 */ }
+  return p;
+}