ghprobe 0.1.1 → 0.1.3

package/bin/ghprobe.js

@@ -7,7 +7,7 @@ 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 { loadConfig, ensureUserConfig, userConfigPath, userConfigSnapshotPath, configDiff } 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";
@@ -273,10 +273,33 @@ program.command("update-pool")
   });
 
 program.command("config-path")
-  .description("打印用户配置文件与池缓存的路径（配置文件可直接编辑）")
+  .description("打印用户配置文件、默认配置快照与池缓存的路径（配置文件可直接编辑）")
   .action(() => {
     console.log(`配置：${userConfigPath()}`);
+    console.log(`快照：${userConfigSnapshotPath()}（安装时的默认配置，用来判断你改过哪些键）`);
     console.log(`池缓存：${poolCachePath()}`);
   });
 
+program.command("config-diff")
+  .description("对比用户配置与当前默认配置（升级后看哪些默认改动还没生效）")
+  .action(() => {
+    const { hasUser, diff } = configDiff();
+    if (!hasUser) {
+      console.log("还没有用户配置 —— 先跑一次 `ghprobe install` 生成。");
+      return;
+    }
+    if (!diff.length) {
+      console.log("用户配置与当前默认一致，没有需要处理的差异。");
+      return;
+    }
+    console.log(`用户配置与当前默认有 ${diff.length} 处差异：\n`);
+    for (const d of diff) {
+      console.log(`  ${d.key}`);
+      console.log(`    你的值   : ${JSON.stringify(d.user)}`);
+      console.log(`    当前默认 : ${JSON.stringify(d.def)}`);
+    }
+    console.log("\n想让某处跟随新默认：把用户配置里对应的键**删掉**即可（没被改过的键会自动跟随默认）。");
+    console.log(`配置文件：${userConfigPath()}`);
+  });
+
 program.parseAsync();

package/config.default.yaml

@@ -1,4 +1,14 @@
 # ghprobe 默认配置（用户可用 --config 覆盖，键名一致即可）
+#
+# ⚠️ 关于升级：`ghprobe install` 会把本文件**整份**复制成用户配置
+#    （%LOCALAPPDATA%\ghprobe\config.yaml），并同时存一份**快照**
+#    （config.default.snapshot.yaml，用来判断你到底改过哪些键）。
+#    加载时做**三方合并**：
+#      · 你**没改过**的键（值仍等于快照） -> 跟随本文件的最新值   ← 默认值的改进自动到达
+#      · 你**改过**的键                   -> 保留你的值
+#      · 你自己加的键 / 本文件新增的键     -> 都保留
+#    所以升级后不需要手动同步配置。想看有哪些差异：`ghprobe config-diff`。
+#    （本文件里的注释只是说明，不参与合并 —— 合并看的是键值。）
 # 目标域名族：每域名独立探测、独立写 hosts
 domains:
   - github.com
@@ -109,9 +119,23 @@ networkCheck:
   enabled: true
   probe: { host: 223.5.5.5, port: 443, timeoutMs: 2000 }
 
-# 被主机名黑名单掐掉的域名走兜底链：主候选全灭时改探测这些替身域名并写入
+# 被主机名黑名单掐掉的域名走兜底链：主候选全灭时改探测这些替身域名，把能通的那个写进 hosts。
+#
+# 两种写法都支持：
+#   简写  raw.githubusercontent.com: [cdn.jsdelivr.net]
+#   完整  raw.githubusercontent.com:
+#           - { domain: my.mirror, path: "/gh/torvalds/linux@master/README", mustContain: ["Linux kernel"] }
+# 完整写法**自带探测判据** —— 第三关用它验证「这个 IP 真的在提供这份内容」。
+# 为什么判据必须跟着配置走：不同替身服务的 URL 形态不同，CDN 映射是
+# `/gh/<user>/<repo>@<ref>/<path>`，代理是 `/<完整原始 URL>`，写死在代码里就没法让用户自己加替身。
+#
+# 🔴 兜底域名本身也可能被封：实测 2026-10-11，`cdn.jsdelivr.net` 在当前网络下 TCP 连得上但 TLS 被掐
+#    （被识别的是 TLS ClientHello 的形态，不是 IP）。多候选机制就是为这种情况准备的。
+# 🔴 默认只保留公共 CDN：**不预置任何第三方代理 / 镜像域名**——本工具定位「无代理」，
+#    预置代理域名既与该定位矛盾，也有法律风险。需要更多兜底请自行添加（示例见 README 第 6 节）。
 fallbacks:
-  raw.githubusercontent.com: [cdn.jsdelivr.net]
+  raw.githubusercontent.com:
+    - cdn.jsdelivr.net
 
 # 超时：tcpMs 只管 TCP 握手阶段（死 IP 快速淘汰），握手成功后自动切到 tlsMs。
 # 黑洞 IP 会一直挂到超时，所以这两段必须分开 —— 否则每加一个候选都要多等 tlsMs。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghprobe",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "GitHub direct-connect optimizer: local DoH resolution + TLS-verified probing + hosts generation (no proxy)",
   "keywords": [
     "github",

package/src/config.js

@@ -17,10 +17,39 @@ export function userConfigPath() {
   return path.join(userDataDir(), "config.yaml");
 }
 
+// 「安装时的默认配置」快照路径。它的唯一用途：**判断用户到底改过哪些键**。
+// 为什么需要：用户配置是 install 时整份复制的，而用户配置优先于包内默认 ——
+// 于是**默认文件里已有键的新默认值，永远到不了老用户**（数组是整体替换，不合并）。
+// 有了快照就能做三方合并：用户值 == 快照值 → 他没动过这个键 → 用**新默认**。
+export function userConfigSnapshotPath() {
+  return path.join(userDataDir(), "config.default.snapshot.yaml");
+}
+
 function isPlainObject(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date) && !(v instanceof RegExp);
 }
 
+// 读 YAML，读不到/解析失败都返回 null（不抛）
+function readYamlSafe(p) {
+  try { return yaml.load(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+// 深比较（只看结构，不看键顺序）—— 三方合并要靠它判断「用户值是否还等于安装时的默认值」
+export function deepEqual(a, b) {
+  if (a === b) { return true; }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) { return false; }
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+  if (isPlainObject(a) || isPlainObject(b)) {
+    if (!isPlainObject(a) || !isPlainObject(b)) { return false; }
+    const ka = Object.keys(a);
+    if (ka.length !== Object.keys(b).length) { return false; }
+    return ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+
 function mergeDefaults(def, user) {
   if (!isPlainObject(def) || !isPlainObject(user)) { return user === undefined ? def : user; }
   const out = { ...def };
@@ -30,6 +59,48 @@ function mergeDefaults(def, user) {
   return out;
 }
 
+// 三方合并：def = 当前包内默认，user = 用户配置，snap = 安装时的默认快照。
+//   用户值 == 快照值  -> 这个键用户没动过 -> 用**当前默认**（默认值的改进能自动到达老用户）
+//   用户值 != 快照值  -> 用户改过 -> 保留用户值
+//   快照里没有这个键   -> 用户自己加的 -> 保留
+//   默认里有、用户没有 -> 新键 -> 直接用默认（同 mergeDefaults）
+// 🔴 没有快照时（0.1.2 之前装的）**不敢猜**，退回「用户值优先」的老行为 —— 判断不了就别动用户的值。
+export function mergeThreeWay(def, user, snap) {
+  if (!snap) { return mergeDefaults(def, user); }
+  if (!isPlainObject(user)) { return user; }
+  const out = { ...(isPlainObject(def) ? def : {}) };
+  for (const k of Object.keys(user)) {
+    const d = isPlainObject(def) ? def[k] : undefined;
+    const u = user[k];
+    const hasSnap = isPlainObject(snap) && Object.prototype.hasOwnProperty.call(snap, k);
+    if (!hasSnap) { out[k] = u; continue; }
+    if (isPlainObject(u) && isPlainObject(snap[k])) { out[k] = mergeThreeWay(d ?? {}, u, snap[k]); continue; }
+    out[k] = deepEqual(u, snap[k]) ? (d === undefined ? u : d) : u;
+  }
+  return out;
+}
+
+// 用户配置与当前默认的差异（供 `ghprobe config-diff` 用）。
+// 对老用户来说，他配置里的值**全部**来自旧版默认 —— 所以任何差异都是「你可能想采纳的默认改动」。
+export function configDiff() {
+  const def = readYamlSafe(path.join(ROOT, "config.default.yaml"));
+  const user = readYamlSafe(userConfigPath());
+  if (!user) { return { hasUser: false, diff: [] }; }
+  const out = [];
+  const walk = (d, u, prefix) => {
+    const keys = new Set([...Object.keys(d || {}), ...Object.keys(u || {})]);
+    for (const k of keys) {
+      const path0 = prefix ? `${prefix}.${k}` : k;
+      const dv = isPlainObject(d) ? d[k] : undefined;
+      const uv = isPlainObject(u) ? u[k] : undefined;
+      if (isPlainObject(dv) && isPlainObject(uv)) { walk(dv, uv, path0); continue; }
+      if (!deepEqual(dv, uv)) { out.push({ key: path0, user: uv, def: dv }); }
+    }
+  };
+  walk(def, user, "");
+  return { hasUser: true, diff: out };
+}
+
 // 把「自动更新的池缓存」并进 ipPools.auto（池名固定为 auto，供 domainPools 引用）。
 // 缓存不存在时什么都不做 —— 探测侧对缺失的池名是宽容的（会退回「用全部池」）。
 function withPoolCache(cfg) {
@@ -40,25 +111,65 @@ function withPoolCache(cfg) {
   return cfg;
 }
 
+// fallbacks 归一化：既支持简写 `[域名]`，也支持完整写法 `[{ domain, path, mustContain }]`。
+// 归一化后：
+//   cfg.fallbacks    = { 主域名: [替身域名...] }          —— 下游（targetDomains / neededFallbacks）不用改
+//   cfg.fallbackSigs = { 替身域名: { path, mustContain } } —— 供 prober 用该替身自己的探测判据
+//
+// 🔴 为什么需要：兜底域名本身也可能被封（实测 2026-10-11：`cdn.jsdelivr.net` 在当前网络下
+//    TCP 连得上但 TLS 被掐），所以配置里要给**多个候选**、探测时挑当下能通的那个。
+//    而不同替身服务的 URL 形态不同 —— CDN 映射是 `/gh/<user>/<repo>@<ref>/<path>`，
+//    代理是 `/<完整原始 URL>` —— 判据没法写死在代码里，必须跟着配置走。
+export function normalizeFallbacks(cfg) {
+  const raw = cfg.fallbacks || {};
+  const fallbacks = {};
+  const fallbackSigs = {};
+  for (const [primary, list] of Object.entries(raw)) {
+    const domains = [];
+    for (const item of (Array.isArray(list) ? list : [])) {
+      if (typeof item === "string") { domains.push(item); continue; }
+      if (item && typeof item === "object" && item.domain) {
+        domains.push(item.domain);
+        const sig = {};
+        if (item.path) { sig.path = item.path; }
+        if (Array.isArray(item.mustContain) && item.mustContain.length) { sig.mustContain = item.mustContain; }
+        if (Object.keys(sig).length) { fallbackSigs[item.domain] = sig; }
+      }
+    }
+    fallbacks[primary] = domains;
+  }
+  cfg.fallbacks = fallbacks;
+  cfg.fallbackSigs = fallbackSigs;
+  return cfg;
+}
+
 // 优先级：--config 显式指定 > 用户目录 config.yaml > 包内 config.default.yaml
+// 用户目录那份走**三方合并**（见 mergeThreeWay）：用户没改过的键会跟随最新默认值。
 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 { /* 不存在 / 读不了 -> 下一个 */ }
+    const y = readYamlSafe(p);
+    if (y) { user = y; break; }
   }
-  return withPoolCache(user ? mergeDefaults(def, user) : def);
+  if (!user) { return withPoolCache(normalizeFallbacks(def)); }
+  const snap = readYamlSafe(userConfigSnapshotPath());
+  return withPoolCache(normalizeFallbacks(mergeThreeWay(def, user, snap)));
 }
 
-// 首次 install 时把包内默认配置复制成用户配置（已存在则不覆盖，保留用户改动）
+// 首次 install 时把包内默认配置复制成用户配置（已存在则不覆盖，保留用户改动）；
+// 快照缺失时补一份（= 当前默认），供三方合并判断「用户改过哪些键」。
+// ⚠️ 快照**只在缺失时创建，不随升级刷新** —— 它代表「用户拿到配置时默认长什么样」这个基准，
+//    一刷新基准就漂了，用户没改过的键也会被误判成改过。
 export function ensureUserConfig() {
   const p = userConfigPath();
+  const defPath = path.join(ROOT, "config.default.yaml");
   try {
-    if (!fs.existsSync(p)) {
-      fs.mkdirSync(path.dirname(p), { recursive: true });
-      fs.copyFileSync(path.join(ROOT, "config.default.yaml"), p);
-    }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    if (!fs.existsSync(p)) { fs.copyFileSync(defPath, p); }
+    const snap = userConfigSnapshotPath();
+    if (!fs.existsSync(snap)) { fs.copyFileSync(defPath, snap); }
   } catch { /* 写不了不阻塞安装 */ }
   return p;
 }

package/src/prober.js

@@ -140,10 +140,30 @@ export function checkHttpResponse(statusCode, body, location, sig) {
   return { ok: false, err: `status:${statusCode}` };
 }
 
+// 未在 DOMAIN_SIG 里声明、也没有配置判据时的兜底判据
+const DEFAULT_SIG = {
+  path: "/",
+  mustContain: [],
+  allow: [200, 204, 301, 302, 303, 304, 307, 308],
+  reject: ["unknown domain", "Fastly error", "bad request"],
+  redirectHosts: [],
+};
+
+// 取某域名的探测判据：**配置里 fallbackSigs 声明的优先于代码里的 DOMAIN_SIG**。
+// 🔴 为什么替身域名必须能自带判据：不同替身服务的 URL 形态不同 ——
+//    CDN 映射是 `/gh/<user>/<repo>@<ref>/<path>`，代理是 `/<完整原始 URL>` ——
+//    判据没法写死在代码里，用户新增一个替身也不该被要求改源码。
+export function sigFor(domain, cfg) {
+  const override = cfg?.fallbackSigs?.[domain];
+  const base = DOMAIN_SIG[domain];
+  if (!base && !override) { return DEFAULT_SIG; }
+  return { ...DEFAULT_SIG, ...(base || {}), ...(override || {}) };
+}
+
 // 第三关：HTTP GET（host=IP、SNI=域名、Host头=域名），读少量响应体做终审
-function httpProbe(ip, domain, httpMs) {
+function httpProbe(ip, domain, httpMs, cfg) {
   return new Promise((resolve) => {
-    const sig = DOMAIN_SIG[domain] || { path: "/", mustContain: [], allow: [200, 204, 301, 302, 303, 304, 307, 308], reject: ["unknown domain", "Fastly error", "bad request"], redirectHosts: [] };
+    const sig = sigFor(domain, cfg);
     const t0 = Date.now();
     const req = https.request({
       host: ip, servername: domain, method: "GET", path: sig.path, timeout: httpMs,
@@ -186,7 +206,7 @@ export async function probeIp(domain, ip, cfg) {
   if (!g.ok) {
     return { domain, ip, ok: false, stage: g.stage, err: g.err, tlsBlocked: looksLikeTlsBlocked(g) };
   }
-  const h = await httpProbe(ip, domain, httpMs);
+  const h = await httpProbe(ip, domain, httpMs, cfg);
   const tlsCost = g.tlsMs - g.tcpMs;
   const score = Math.round(g.tcpMs * 0.4 + tlsCost * 0.4 + (h.ok ? h.ttfb : httpMs) * 0.2);
   return {