ghprobe 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,44 @@
 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.1.2] - 2026-10-11
+
+### Added
+
+- **配置升级机制（三方合并）**：解决「默认值的改进到不了老用户」——
+  用户配置是 `install` 时**整份复制**的、且优先于包内默认，所以默认文件里**已有键**的新值
+  永远不生效（数组是整体替换，不合并）。现在 `install` 会额外存一份**默认配置快照**
+  （`%LOCALAPPDATA%\ghprobe\config.default.snapshot.yaml`），`loadConfig` 做**三方合并**：
+  用户值 == 快照值 → 这个键他没动过 → 用**新默认**；否则保留用户值。
+  快照**只在缺失时创建、不随升级刷新**（一刷新基准就漂了，没改过的键会被误判成改过）。
+  新增 `ghprobe config-diff` 查看用户配置与当前默认的差异；`config-path` 一并打印快照路径。
+  ⚠️ 0.1.2 之前装的用户没有快照，跑一次 `ghprobe install` 之后才会建立；在那之前用
+  `config-diff` 看差异、手动采纳。
+- **兜底链支持多个候选，并挑当下能通的那个**：原来 `fallbacks` 每个主域名只能配一个替身，
+  而替身自己也会被封（实测同一时刻 `cdn.jsdelivr.net` 的 TCP 连得上、TLS 被掐）。
+  现在默认给三个：`cdn.jsdelivr.net`（jsDelivr 公共 CDN）、`ghproxy.net` / `gh-proxy.com`
+  （第三方 GitHub 代理，配置里已注明「请求会经过它们的服务器」，介意可删）。
+- **替身可以自带探测判据**：`fallbacks` 新增完整写法
+  `- { domain, path, mustContain }`，判据写在配置里而不是代码里 ——
+  因为不同替身的 URL 形态不同（CDN 映射 `/gh/<user>/<repo>@<ref>/<path>` vs 代理 `/<完整原始 URL>`），
+  用户新增替身不需要改源码。归一化在 `loadConfig()` 里做，下游（`targetDomains` /
+  `neededFallbacks`）拿到的仍是 `{ 主域名: [替身域名...] }`，无需改动。
+
+### Changed
+
+- `config.default.yaml` 头部补了升级说明：`install` 会把默认配置**整份**复制成用户配置，
+  而用户配置优先 —— 所以**默认值里已有的键，升级后新默认不会自动生效**（新增的键不受影响）。
+- README 第 6 节重写（原「关于为什么还会出现 cdn.jsdelivr.net」）：说明兜底链要解决的是
+  **换 IP 修不了**的那层封锁、为什么需要多个候选、第三方代理的隐私代价、以及怎么自己加替身。
+  并修正了原文「`raw` 被封锁后这类文件没有替代入口」的自相矛盾说法。
+
+### Fixed
+
+- README **中文版**修正两条过时 FAQ：还在说「每个域名只写一条 IP」「Windows 对同一域名只认第一条」——
+  这两个说法在 0.1.0 就被实测推翻了（hosts 里同名多条会被解析器**全部返回**、curl / 浏览器
+  **逐个尝试**，所以备选是真兜底）。**英文版当时改了、中文版漏了**，两边现在一致。
+- 单测 137 → **153**。
+
 ## [0.1.1] - 2026-10-11
 
 线上实测驱动的三个修复。都是「工具看着在干活、实际把用户搞断网」那一类。
@@ -160,5 +198,6 @@
 - 提权脚本以 UTF-8 BOM 落盘，杜绝编码解析歧义
 - 写入前校验块标记存在，失败自动回滚；还原时只移除本工具自己的行
 
+[0.1.2]: https://github.com/zmw-zmw/ghprobe/releases/tag/v0.1.2
 [0.1.1]: https://github.com/zmw-zmw/ghprobe/releases/tag/v0.1.1
 [0.1.0]: https://github.com/zmw-zmw/ghprobe/releases/tag/v0.1.0

package/README.en.md

@@ -160,7 +160,8 @@ The last layer needs its own explanation, because it is the most easily misunder
 
 **Same IP, same hostname, only the client changes — and the success rate drops from 100% to 15%.** So the block keys on the **shape of the TLS ClientHello** (extension list, order, length) — not on the hostname itself, and not on the IP. Two consequences:
 
-1. **Changing the IP cannot fix it** — only changing the domain can (which is why there is a fallback chain: `raw.githubusercontent.com -> cdn.jsdelivr.net`).
+1. **Changing the IP cannot fix it** — only changing the domain can. That is why there is a **fallback chain**
+   with **several alternative candidates** (the fallbacks get blocked too): see section 6.
 2. **This tool's probe results do not fully represent your experience** — ghprobe is Node, and its TLS fingerprint differs from your browser's. Measured: `raw.githubusercontent.com` opens fine in a browser, while the Node probe gets `ECONNRESET` on every candidate. In that case the tool writes `# blocked` (not `# absent`), meaning **inconclusive** rather than "unreachable":
 
    ```text
@@ -478,26 +479,55 @@ If you deployed via `install.ps1`, you can also use `.\install.ps1 -Uninstall`.
 
 ---
 
-## 6. About "why is cdn.jsdelivr.net in there?"
+## 6. The fallback chain: why cdn.jsdelivr.net / ghproxy.net show up in hosts
 
-**`cdn.jsdelivr.net` is not a domestic mirror.** It is the jsDelivr public CDN (running on Cloudflare). It appears in hosts for exactly one reason: the **fallback chain**.
+Besides the primary domains like `github.com`, ghprobe maintains a **fallback chain** for
+hostname-blocked domains: when every primary candidate is dead, it probes alternative entry
+domains and writes **whichever works right now** into hosts.
 
-One fault type is the **SNI hostname blacklist** — what is blocked is the hostname itself. The SNI in the TLS handshake carries that domain, so **no IP will help**; the only way out is to **change the domain**. jsDelivr maps GitHub files directly:
+**Why the domain has to change**: one layer of blocking cannot be fixed by changing the IP —
+what is blocked is not the IP but the **shape of the ClientHello** in the TLS handshake
+(measurements in section 3, "Limits"). No IP will help there; only a **different, unblocked
+entry domain** will. GitHub file content has several equivalent entry points:
 
 ```text
-raw.githubusercontent.com/<user>/<repo>/<ref>/<path>
-cdn.jsdelivr.net/gh/<user>/<repo>@<ref>/<path>     <- same content
+raw.githubusercontent.com/<user>/<repo>/<ref>/<path>   <- the original (often blocked)
+cdn.jsdelivr.net/gh/<user>/<repo>@<ref>/<path>         <- jsDelivr public CDN, same content
+ghproxy.net/https://raw.githubusercontent.com/<...>    <- third-party GitHub proxy
 ```
 
-So when `raw.githubusercontent.com` is SNI-blocked and all primary candidates are dead, ghprobe falls back to it.
+**Why several candidates**: the fallback domains get blocked too. Measured at the same moment:
+`cdn.jsdelivr.net` accepted TCP but had its TLS handshake cut. So the config ships a set of
+candidates and the probe **picks whichever works right now** (if several work, all are written
+and the client chooses). Three by default:
 
-Caveats:
+| Fallback | Type | Note |
+| --- | --- | --- |
+| `cdn.jsdelivr.net` | jsDelivr public CDN (Cloudflare) | path mapping `/gh/<user>/<repo>@<ref>/<path>` |
+| `ghproxy.net` | third-party GitHub proxy | your requests go through their server |
+| `gh-proxy.com` | third-party GitHub proxy | same |
+
+> **A third-party proxy can see which files you requested.** Delete those two if that bothers
+> you and keep only `cdn.jsdelivr.net`.
+
+Behaviour and prerequisites:
 
 - By default only `raw.githubusercontent.com` has a fallback; `github.com` / `codeload.github.com` never use one.
-- It fires only when the primary candidates are **entirely dead** — any live IP and the fallback domain is never probed.
-- What gets written is the `cdn.jsdelivr.net` IP — this rescues "change the domain," not "change the IP."
+- It fires only when the primary candidates are **entirely dead** — any live IP and the fallback is never probed.
+- What gets written is the **fallback domain's** IP: this rescues "change the domain", not "change the IP".
+  You access it through the fallback URL form.
+- Fallbacks carry their **own probe signature** (path + required response content), declared in config
+  rather than code — so you can add your own without touching the source:
+
+```yaml
+fallbacks:
+  raw.githubusercontent.com:
+    - cdn.jsdelivr.net
+    # Add your own: gate 3 uses path + mustContain to verify this IP really serves this content
+    - { domain: my.mirror.example, path: "/gh/torvalds/linux@master/README", mustContain: ["Linux kernel"] }
+```
 
-To remove it, empty `fallbacks` (`--config` merges recursively, so an empty object works):
+To remove the fallback, empty it (`--config` merges recursively, so an empty object works):
 
 ```yaml
 fallbacks: {}
@@ -507,8 +537,6 @@ fallbacks: {}
 ghprobe install -c my.yaml
 ```
 
-The cost: once `raw.githubusercontent.com` is SNI-blocked, that class of files has no alternative entry point.
-
 ---
 
 ## 7. Requirements and FAQ
@@ -537,6 +565,22 @@ Two by default (`hosts.maxEntriesPerDomain`): the best IP plus one spare. Window
 **Q: What if an IP dies between two health checks?**
 The client falls through to the spare entry, so the cost is one extra connect timeout rather than a hard failure. Without a spare, the worst-case interruption would be about `schedule.healthMin` (1 minute by default).
 
+**Q: How do I upgrade?**
+```powershell
+npm install -g ghprobe@latest
+```
+The scheduled task runs a **fixed path** inside the npm global directory, and `npm install -g` replaces it in place — so the **next trigger (within a minute) picks up the new version**. No need to re-run `install`, no second UAC prompt.
+
+**Does the config update too?** Yes. At `install` time a **snapshot** of the then-current default config is stored, and loading does a **three-way merge**:
+
+- Keys you **never changed** (value still equals the snapshot) → follow the latest default
+- Keys you **did change** → your value is kept
+- Keys you added / keys newly added by a release → both kept
+
+So improvements to defaults (say, new fallback candidates) reach you **automatically**, and your customisations are never overwritten. To see what differs: `ghprobe config-diff`.
+
+> Note: users who installed before 0.1.2 have no snapshot; it is created on the next `ghprobe install`. Until then, use `ghprobe config-diff` and delete the keys you want to follow.
+
 **Q: Does the scheduled task run while the screen is locked?**
 The task registered by `install` uses `LogonType = Interactive`, so it won't fire while locked / logged off / not logged in; it resumes on the interval after logon.
 

package/README.md

@@ -160,7 +160,8 @@ ghprobe 的取舍是：**只做「优选 IP + 自动维护」，不碰系统网
 
 **同一个 IP、同一个主机名，只换客户端，结果从 100% 掉到 15%。** 说明拦截依据是 **TLS ClientHello 的形态**（扩展列表、顺序、长度），既不是主机名本身，也不是 IP。这带来两个后果：
 
-1. **换 IP 修不了它** —— 只能换域名（所以本工具有兜底链：`raw.githubusercontent.com → cdn.jsdelivr.net`）。
+1. **换 IP 修不了它** —— 只能换域名。所以本工具有**兜底链**，而且配了**多个替身候选**
+   （替身自己也会被封）：见第 6 节。
 2. **本工具的探测结果不能完全代表你的体验** —— 它自己是 Node，TLS 指纹和你用的浏览器不同。实测：`raw.githubusercontent.com` 在浏览器里能正常打开，而 Node 探测全部 `ECONNRESET`。遇到这种情况工具会写 `# blocked`（而不是 `# absent`），明确表示**探测不可判**，不是「该域名不可达」：
 
    ```text
@@ -471,26 +472,50 @@ ghprobe uninstall              # 删除计划任务 + 还原 hosts（只删自
 
 ---
 
-## 6. 关于「为什么还会出现 cdn.jsdelivr.net」
+## 6. 兜底链：为什么 hosts 里会出现 cdn.jsdelivr.net / ghproxy.net
 
-**`cdn.jsdelivr.net` 不是国内镜像**，它是 jsDelivr 的公共 CDN（走 Cloudflare）。它进 hosts 的唯一原因是**兜底链**。
+除了 `github.com` 这类主域名，ghprobe 还会给**被主机名封锁**的域名配一条**兜底链**：
+主候选全灭时改探测替身域名，并把**当下能通的那个**写进 hosts。
 
-有一种故障是 **SNI 主机名黑名单** —— 被封锁的是主机名本身，TLS 握手里的 SNI 带着那个域名，**换任何 IP 都没用**，只能**换域名**。jsDelivr 提供 GitHub 文件的直接映射：
+**为什么必须换域名**：有一层封锁是「换 IP 修不了」的 —— 被拦的不是 IP，而是 TLS 握手里
+ClientHello 的形态（实测数据见 §3「边界」）。这种时候换任何 IP 都没用，只能**换一个不被拦的入口域名**。
+而 GitHub 的文件内容有几个等价入口：
 
 ```text
-raw.githubusercontent.com/<user>/<repo>/<ref>/<path>
-cdn.jsdelivr.net/gh/<user>/<repo>@<ref>/<path>     ← 同一份内容
+raw.githubusercontent.com/<user>/<repo>/<ref>/<path>   ← 原始入口（常被拦）
+cdn.jsdelivr.net/gh/<user>/<repo>@<ref>/<path>         ← jsDelivr 公共 CDN，同一份内容
+ghproxy.net/https://raw.githubusercontent.com/<...>    ← 第三方 GitHub 代理
 ```
 
-所以当 `raw.githubusercontent.com` 被 SNI 封锁、主候选全灭时，ghprobe 用它兜底。
+**为什么配多个候选**：替身域名自己也会被封。实测同一时刻 `cdn.jsdelivr.net` 的 TCP 连得上、
+但 TLS 被掐 —— 所以配置里给一组候选，探测时**挑当下能通的**（能通多个就都写上，客户端自己选）。
+默认三个：
 
-前提：
+| 替身 | 类型 | 说明 |
+| --- | --- | --- |
+| `cdn.jsdelivr.net` | jsDelivr 公共 CDN（Cloudflare） | 路径映射 `/gh/<user>/<repo>@<ref>/<path>` |
+| `ghproxy.net` | ⚠️ 第三方 GitHub 代理 | 请求会经过它的服务器 |
+| `gh-proxy.com` | ⚠️ 第三方 GitHub 代理 | 同上 |
+
+> ⚠️ **第三方代理能看到你请求了哪些文件。** 介意的话把这两条删掉，只留 `cdn.jsdelivr.net`。
+
+行为与前提：
 
 - 默认只有 `raw.githubusercontent.com` 配了兜底；`github.com` / `codeload.github.com` 从不走兜底。
-- 只在主候选**全灭**时触发，有任一活 IP 就不探兜底。
-- 命中后写入的是 `cdn.jsdelivr.net` 的 IP —— 救的是「换域名」，不是「换 IP」。
+- 只在主候选**全灭**时触发；有任一活 IP 就不探兜底。
+- 写入的是**替身域名**的 IP —— 救的是「换域名」，不是「换 IP」。访问时要换成替身的 URL 形式。
+- 替身**自带探测判据**（路径 + 响应里必须出现的内容），写在配置里而不是代码里 ——
+  所以你可以自己加替身，不需要改源码：
 
-不想要就清空 `fallbacks`（`--config` 覆盖是递归合并，给空对象即可）：
+```yaml
+fallbacks:
+  raw.githubusercontent.com:
+    - cdn.jsdelivr.net
+    # 自己加一个：第三关用 path + mustContain 验证「这个 IP 真的在提供这份内容」
+    - { domain: my.mirror.example, path: "/gh/torvalds/linux@master/README", mustContain: ["Linux kernel"] }
+```
+
+不想要兜底就清空（`--config` 覆盖是递归合并，给空对象即可）：
 
 ```yaml
 fallbacks: {}
@@ -500,8 +525,6 @@ fallbacks: {}
 ghprobe install -c my.yaml
 ```
 
-代价：`raw.githubusercontent.com` 被 SNI 封锁后，这类文件没有替代入口。
-
 ---
 
 ## 7. 系统要求与常见问题
@@ -524,11 +547,27 @@ ghprobe install -c my.yaml
 **Q：会不会影响别的软件？**  
 不会。它**只写 hosts 文件**，不装代理、不改系统代理设置、不劫持流量。而且只操作 `# === ghprobe begin/end ===` 之间属于它自己的那一块，**你原有的 hosts 条目和第三方工具写的条目都不会被改动**；卸载时也只剥掉自己的块。
 
-**Q：为什么每个域名只写一条 IP？**  
-Windows 对同一域名在 hosts 里只认第一条，写多条也不会轮询。所以 ghprobe 每个域名只写最优的一条；排名里的「备选」仅用于展示，不写入。
+**Q：每个域名写几条 IP？**  
+默认 **2 条**（最优 + 1 条备选），由 `hosts.maxEntriesPerDomain` 控制。这里推翻过一个流传很广的说法：Windows **不是**「同名只认第一条」—— hosts 里同名多条会被解析器**全部返回**（保持文件顺序），curl / 浏览器会**逐个尝试**（黑洞 IP 排在前也能 fallback，实测 `curl` 返回 200）。所以备选是真的兜底，不是摆设。设 1 可退回单条。
 
 **Q：两次健康检查之间 IP 失效了怎么办？**  
-每域名只写一条 IP，若它在两次检查之间失效，最坏中断时长 ≈ `schedule.healthMin`（默认 1 分钟）。这是 hosts 机制本身的限制，不是探测能规避的。
+每域名写 2 条（主 + 备选）。首条抖动失效时客户端会**自动试备选** —— 代价是多等一个连接超时，而不是中断。最坏情况（两条同时失效）中断时长 ≈ `schedule.healthMin`（默认 1 分钟）。
+
+**Q：怎么升级？**  
+```powershell
+npm install -g ghprobe@latest
+```
+计划任务跑的是 npm 全局目录里的**固定路径**，而 `npm install -g` 是**就地替换** —— 所以**下次触发（≤ 1 分钟）自动用新版**。不需要重跑 `install`，不需要再点 UAC。
+
+**配置也会跟着更新吗？** 会。`install` 时会把当时的默认配置存一份**快照**，加载时做**三方合并**：
+
+- 你**没改过**的键（值仍等于快照）→ 跟随最新默认值
+- 你**改过**的键 → 保留你的值
+- 你自己加的键 / 新版新增的键 → 都保留
+
+所以默认值的改进（比如新增的兜底候选）会**自动到达**，而你的自定义不会被覆盖。想看有哪些差异：`ghprobe config-diff`。
+
+> ⚠️ 0.1.2 之前装的用户没有快照，跑一次 `ghprobe install` 之后才会建立。在那之前用 `ghprobe config-diff` 看差异，把想采纳的键从用户配置里删掉即可。
 
 **Q：计划任务锁屏时会跑吗？**  
 `install` 注册的任务 `LogonType` 为 `Interactive`，锁屏 / 注销 / 未登录状态下不会触发，登录后按间隔继续。

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,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.1",
+  "version": "0.1.2",
   "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 {