ghprobe 0.1.0 → 0.1.2

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";
@@ -60,7 +60,9 @@ if (process.platform !== "win32") {
   process.exit(1);
 }
 const program = new Command();
-program.name("ghprobe").description("GitHub 直连优选：本地 DoH + TLS 证书终审探测 + hosts 生成（无代理）").version("0.1.0");
+// 版本号从 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) {
@@ -271,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,140 +1,166 @@
-# 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 层封锁的域名全量也救不回，冷却内不重试
+# ghprobe 默认配置（用户可用 --config 覆盖，键名一致即可）
+#
+# ⚠️ 关于升级：`ghprobe install` 会把本文件**整份**复制成用户配置
+#    （%LOCALAPPDATA%\ghprobe\config.yaml），并同时存一份**快照**
+#    （config.default.snapshot.yaml，用来判断你到底改过哪些键）。
+#    加载时做**三方合并**：
+#      · 你**没改过**的键（值仍等于快照） -> 跟随本文件的最新值   ← 默认值的改进自动到达
+#      · 你**改过**的键                   -> 保留你的值
+#      · 你自己加的键 / 本文件新增的键     -> 都保留
+#    所以升级后不需要手动同步配置。想看有哪些差异：`ghprobe config-diff`。
+#    （本文件里的注释只是说明，不参与合并 —— 合并看的是键值。）
+# 目标域名族：每域名独立探测、独立写 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 }
+
+# 被主机名黑名单掐掉的域名走兜底链：主候选全灭时改探测这些替身域名，把能通的那个写进 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）。所以这里给**多个候选**，探测时挑当下能通的那个。
+# ⚠️ `ghproxy.net` / `gh-proxy.com` 是**第三方 GitHub 代理**：请求会经过它们的服务器。
+#    介意的话把这两条删掉，只留 `cdn.jsdelivr.net` 即可。
+fallbacks:
+  raw.githubusercontent.com:
+    - cdn.jsdelivr.net
+    - { domain: ghproxy.net,  path: "/https://raw.githubusercontent.com/torvalds/linux/master/README", mustContain: ["Linux kernel"] }
+    - { domain: gh-proxy.com, path: "/https://raw.githubusercontent.com/torvalds/linux/master/README", mustContain: ["Linux kernel"] }
+
+# 超时：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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghprobe",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "GitHub direct-connect optimizer: local DoH resolution + TLS-verified probing + hosts generation (no proxy)",
   "keywords": [
     "github",
@@ -25,9 +25,13 @@
   },
   "author": "zmw",
   "type": "module",
-  "bin": { "ghprobe": "bin/ghprobe.js" },
+  "bin": {
+    "ghprobe": "bin/ghprobe.js"
+  },
   "main": "bin/ghprobe.js",
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "license": "GPL-3.0-only",
   "files": [
     "bin/",

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;
 }