ghprobe 0.1.3 → 0.1.6

package/src/daemon.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// daemon：常驻自愈循环（0.5.0，无缝切换的核心）。
+//
+// 为什么需要：0.4.0 及以前的自愈靠计划任务**每分钟起一个新进程**，最坏检测延迟 60s +
+// 全量重排 ~30s，实测一次抖动窗口从断到修 ~6 分钟。常驻进程把检测压到 15~45s 自适应循环，
+// 故障发现→修复的全程都不再有「等下一分钟」的固定开销。
+//
+// 与监督者的契约（监督者 = 现有的每分钟 `health --apply` 任务，不需要重新注册）：
+//   · daemon 每轮循环写心跳文件（daemon.heartbeat）
+//   · 监督者看到心跳新鲜 -> 秒退（daemon 在干活）；陈旧/没有 -> 拉起新 daemon + 本轮照常兜底
+//   · daemon 崩溃 -> 下一分钟监督者自动复活它；旧版本 npm 用户没有心跳文件，行为完全不变
+import fs from "node:fs";
+import path from "node:path";
+import { userDataDir, applyHosts, mergeHosts, WIN_HOSTS, isPaused } from "./hosts.js";
+import { hasLocalNetwork } from "./net.js";
+import { loadConfig } from "./config.js";
+import { parseBlock, runHealth, shouldKeepOldBlock } from "./health.js";
+import { poolNeedsUpdate, updatePool } from "./pool.js";
+import { createSwitchGate } from "./algorithm.js";
+
+const HEARTBEAT_MAX_AGE_MS = 150_000;   // 心跳超过这个年龄视为陈旧（单轮最坏 ~90s，留余量）
+
+export function heartbeatPath() {
+  return path.join(userDataDir(), "daemon.heartbeat");
+}
+
+export function writeHeartbeat(file = heartbeatPath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ at: new Date().toISOString(), pid: process.pid }));
+  } catch { /* 写不了就算了，监督者会按陈旧处理并兜底 */ }
+}
+
+export function readHeartbeat(file = heartbeatPath()) {
+  try {
+    const o = JSON.parse(fs.readFileSync(file, "utf8"));
+    return o && typeof o === "object" && o.pid ? o : null;
+  } catch { return null; }
+}
+
+// 心跳是否新鲜（纯函数，now 可注入）
+export function heartbeatFresh(hb, now = Date.now(), maxAgeMs = HEARTBEAT_MAX_AGE_MS) {
+  if (!hb || !hb.at) { return false; }
+  const t = new Date(hb.at).getTime();
+  return Number.isFinite(t) && now - t >= 0 && now - t < maxAgeMs;
+}
+
+// 进程是否还活着：process.kill(pid, 0) 只查存在性；EPERM = 存在但无权限（也算活着）
+export function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) { return false; }
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+// 监督者决策（纯函数）：心跳新鲜且持有者活着 -> 秒退；否则需要拉起/兜底
+export function daemonRunning(hb, now = Date.now()) {
+  return heartbeatFresh(hb, now) && processAlive(hb.pid) && hb.pid !== process.pid;
+}
+
+// 自适应间隔（纯函数）：
+//   断网          -> 120s（断网时探测无意义，省唤醒；恢复由下一轮本地检查发现）
+//   有异常/有变更  -> 15s（刚经历故障，密集盯防确认稳定）
+//   全部健康      -> 45s（空闲基线；比 1 分钟任务更密，且没有进程启动开销）
+export function nextIntervalMs(result, intervals = {}) {
+  const { healthy = 45_000, fast = 15_000, offline = 120_000 } = intervals;
+  if (!result || result.offline) { return offline; }
+  const troubled = result.action !== "none" || (Array.isArray(result.stuck) && result.stuck.length > 0);
+  return troubled ? fast : healthy;
+}
+
+// 单轮自愈：断网跳过 -> 到点刷池（带 hosts 健康条目当种子）-> runHealth(写 hosts)。
+// deps.gate（0.6.0）：用户行为门控 —— 非紧急写入在「用户正用浏览器」时被推迟，
+// 攒进门控的 pendingBlock；健康轮结束后由 flushPending 空闲落地。
+export async function daemonCycle(cfg, log, deps = {}) {
+  // ghprobe off 后：不探测、不写 hosts。暂停检查必须放在最前 —— 连「断网跳过」都
+  // 不能先判，off 语义是「先别动我的网络」，探测请求本身也不该发。
+  // deps.isPaused 可注入（单测不碰真实用户目录）。
+  if ((deps.isPaused || isPaused)()) {
+    return { action: "skip", reason: "已暂停（ghprobe off 恢复）", offline: false, block: null, stuck: [] };
+  }
+  if (!(await (deps.hasNetwork || hasLocalNetwork)(cfg))) {
+    return { action: "skip", reason: "本地无网络连接", offline: true, block: null, stuck: [] };
+  }
+  if (poolNeedsUpdate(cfg)) {
+    try {
+      const cur = parseBlock(fs.readFileSync(WIN_HOSTS, "utf8"));
+      await updatePool(cfg, log, [...cur.entries.values()]);
+    } catch (e) {
+      log(`候选池更新失败（忽略，用现有池继续）: ${e.message}`);
+    }
+  }
+  const hooks = deps.gate ? { beforeApply: deps.gate.beforeApply } : {};
+  const result = await runHealth(cfg, log, true, WIN_HOSTS, undefined, hooks);
+  // 空闲落地：上轮被推迟的块，此刻成本低就写掉（含全灭护栏）
+  if (deps.gate && deps.gate.pending && (!result || result.action === "none" || result.action === "deferred")) {
+    try {
+      await flushPending(cfg, log, deps.gate, deps.hostsPath || WIN_HOSTS, deps.applyHosts);
+    } catch (e) {
+      log(`推迟块落地失败（下轮重试）: ${e.message}`);
+    }
+  }
+  return result;
+}
+
+// 把门控攒下的块落地：重读最新 hosts + 全灭护栏 + 合并写入。
+// deps.applyHosts 可注入（单测不写真 hosts）。
+export async function flushPending(cfg, log, gate, hostsPath = WIN_HOSTS, applyHostsImpl = applyHosts) {
+  return gate.maybeFlush(cfg, log, {
+    hostsPath,
+    applyHosts: (merged, p) => applyHostsImpl(merged, p),
+    mergeLatest: (block) => {
+      const latest = fs.readFileSync(hostsPath, "utf8");
+      if (shouldKeepOldBlock(latest, block)) {
+        throw new Error("全灭护栏：推迟块无有效 IP 而现有条目可用，放弃落地");
+      }
+      return mergeHosts(latest, block);
+    },
+  });
+}
+
+// 常驻主循环。返回条件：单实例让位（更年轻的 daemon 在跑）或 deps.maxCycles 用完（测试）。
+export async function runDaemon(cfg, log = () => {}, deps = {}) {
+  const gate = deps.gate !== undefined ? deps.gate : createSwitchGate();
+  const cycle = deps.cycle || ((c, l) => daemonCycle(c, l, { gate, applyHosts: deps.applyHosts, hostsPath: deps.hostsPath }));
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const intervals = deps.intervals || {};
+  const maxCycles = deps.maxCycles ?? Infinity;
+  const hb = readHeartbeat();
+  if (daemonRunning(hb)) { return { started: false, reason: "已有 daemon 在跑（心跳新鲜）" }; }
+  writeHeartbeat();
+  log(`daemon 已启动 (pid ${process.pid})`);
+  let cycles = 0;
+  for (;;) {
+    let result = null;
+    let cfgNow = cfg;
+    try {
+      cfgNow = loadConfig(); // 每轮重载：配置编辑与池缓存更新即时生效
+      result = await cycle(cfgNow, log);
+      if (result && result.action) { log(`daemon cycle action=${result.action} reason=${result.reason || ""}`); }
+    } catch (e) {
+      log(`daemon 循环异常（不退出，继续下一轮）: ${e.message}`);
+      result = { action: "error" }; // 异常按「有事」处理 -> fast 档，别在故障后睡满 2 分钟
+    }
+    writeHeartbeat();
+    cycles += 1;
+    if (cycles >= maxCycles) { return { started: true, cycles }; }
+    const newer = readHeartbeat();
+    if (newer && newer.pid !== process.pid && heartbeatFresh(newer) && processAlive(newer.pid)) {
+      return { started: true, cycles, yielded: true }; // 让位给更年轻的实例
+    }
+    await sleep(nextIntervalMs(result, intervals));
+  }
+}

package/src/doctor.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// doctor：一键自检。把「网络 / DoH / 探测 / hosts / 计划任务」五层各查一遍，
+// 输出人话结论 + 下一步该做什么 —— 面向不想读日志的普通用户。
+// 评估逻辑全部拆成纯函数（输入状态、输出结论），编排函数 runDoctor 的依赖可注入，
+// 测试不打真网络。
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolveAll } from "./doh.js";
+import { runProbe } from "./probe.js";
+import { hasLocalNetwork } from "./net.js";
+import { parseBlock, targetDomains, blockedDomainsFromRaw } from "./health.js";
+import { WIN_HOSTS } from "./hosts.js";
+
+// 单条结论：status = ok（正常）/ warn（能用但要注意）/ fail（有问题）/ info（仅供参考）
+// hint 只在非 ok 时给「下一步做什么」，正常项不啰嗦
+export function check(id, title, status, detail, hint = "") {
+  return { id, title, status, detail, hint };
+}
+
+// 从一轮探测结果逐域名给结论。
+// 三类情形要分开说：有活 IP（ok）／候选全灭但疑似 TLS 指纹被阻断（warn：浏览器可能仍能用，
+// 换 IP 修不了）／候选全灭（fail：等自愈或查池）。
+// tlsBlockedDomains 由 blockedDomainsFromRaw() 算出，这里不重复判 —— 单一事实来源。
+export function evaluateProbe(ranked, tlsBlockedDomains, cfg) {
+  const out = [];
+  for (const domain of cfg.domains) {
+    const rs = ranked.get(domain) || [];
+    if (rs.length) {
+      const best = rs[0];
+      out.push(check(`probe:${domain}`, `探测 ${domain}`,
+        "ok", `最优 ${best.ip}（tcp ${best.tcpMs}ms / tls ${best.tlsMs}ms / 首字节 ${best.ttfb}ms），共 ${rs.length} 个可用`));
+    } else if (tlsBlockedDomains.has(domain)) {
+      out.push(check(`probe:${domain}`, `探测 ${domain}`, "warn",
+        "候选全部在 TLS 阶段被重置 —— 本机探测客户端（Node）的 TLS 指纹被识别，换 IP 修不了",
+        "你的浏览器很可能仍能正常访问该域名；若浏览器也不行，只能换域名入口（兜底链，见 README 第 6 节）"));
+    } else {
+      out.push(check(`probe:${domain}`, `探测 ${domain}`, "fail",
+        "所有候选 IP 都不可用",
+        "稍等几分钟让计划任务自动重排；持续如此先跑 `ghprobe update-pool` 刷新候选池，再不行就是该网络到 GitHub 的链路整体不可达"));
+    }
+  }
+  return out;
+}
+
+// hosts 块状态：有没有写、写的够不够。探测结果（ranked）与 hosts 是两回事 ——
+// 「本轮测出了活 IP」不等于「已经写进 hosts」，doctor 要把两者对上。
+export function evaluateHosts(content, cfg, probed = true) {
+  const current = parseBlock(content);
+  const n = current.entries.size;
+  if (n === 0) {
+    return { state: current, checks: [check("hosts", "hosts 写入状态", probed ? "fail" : "info",
+      "hosts 里还没有 ghprobe 块",
+      probed ? "运行 `ghprobe install`：写入 hosts 并注册每分钟自愈的计划任务（一次 UAC）" : "")] };
+  }
+  const targets = targetDomains(cfg);
+  const absent = [...current.absent.keys()];
+  const blocked = [...(current.blocked || new Map()).keys()];
+  // 「未写入」只算真正没写入的：absent/blocked 域名有专门的状态注释，不算缺失，
+  // 否则同一个域名会在 detail 里出现两遍，读起来像出了两个问题。
+  const cooling = new Set([...absent, ...blocked]);
+  const missing = targets.filter((d) => !current.entries.has(d) && !cooling.has(d));
+  const detail = `已写入 ${n} 个域名`
+    + `${absent.length ? `；缺（冷却中）: ${absent.join(", ")}` : ""}`
+    + `${blocked.length ? `；探测不可判: ${blocked.join(", ")}` : ""}`;
+  if (missing.length) {
+    return { state: current, checks: [check("hosts", "hosts 写入状态", "warn", detail + `；配置里有但未写入: ${missing.join(", ")}`,
+      "下一轮健康检查会自动补写；急用可手动跑 `ghprobe health --apply`")] };
+  }
+  return { state: current, checks: [check("hosts", "hosts 写入状态", "ok", detail)] };
+}
+
+// 计划任务在不在。用 schtasks 查（只读、不弹 UAC）；queryResult = { output, error } 或 null（非 Windows）。
+// 查询本身失败不等于没注册，单独标 warn 而不是 fail，避免把「权限/语法问题」夸大成「自愈失效」。
+export function evaluateTask(queryResult) {
+  if (queryResult === null || queryResult === undefined) {
+    return check("task", "计划任务（每分钟自愈）", "info", "跳过（仅 Windows 支持查询）");
+  }
+  if (queryResult.output && /ghprobe/i.test(queryResult.output)) {
+    return check("task", "计划任务（每分钟自愈）", "ok", "已注册（ghprobe）");
+  }
+  if (queryResult.error) {
+    return check("task", "计划任务（每分钟自愈）", "warn", `查询失败：${queryResult.error}`,
+      "无法确认自愈是否在跑；可重跑 `ghprobe install` 修复");
+  }
+  return check("task", "计划任务（每分钟自愈）", "fail", "未注册 —— IP 失效后不会自动换",
+    "运行 `ghprobe install` 注册（需要一次 UAC）");
+}
+
+// DoH 端点连通性：只要有一个端点解析成功就算过；全挂意味着候选只能靠内置池，
+// 池子一过期就彻底失明，属于要提醒的问题。
+export function evaluateDoh(sources, ips) {
+  const ok = (sources || []).filter((s) => s.ok);
+  const names = ok.map((s) => s.ep.name).join(", ");
+  if (ok.length) {
+    return check("doh", "DoH 解析", "ok", `${ok.length}/${sources.length} 个端点可用（${names}），解析出 ${ips.length} 个候选`);
+  }
+  return check("doh", "DoH 解析", "warn", "所有 DoH 端点都不可达，候选只能靠内置 IP 池",
+    "内置池会过期；检查防火墙是否拦了 443 出站，或在配置里更换 doh 端点");
+}
+
+// 汇总：有无 fail。warn 不算不健康 —— blocked 域名（浏览器可能仍可用）不该让 doctor 退出码非零。
+export function overall(checks) {
+  const failed = checks.filter((c) => c.status === "fail");
+  return { ok: failed.length === 0, failed: failed.map((c) => c.id) };
+}
+
+const MARK = { ok: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", info: "[INFO]" };
+
+export function formatReport(checks) {
+  const lines = [];
+  for (const c of checks) {
+    lines.push(`${MARK[c.status]} ${c.title} —— ${c.detail}`);
+    if (c.hint) { lines.push(`       ↳ ${c.hint}`); }
+  }
+  const o = overall(checks);
+  lines.push(o.ok ? "结论：一切正常。" : `结论：${o.failed.length} 项需要处理（见上）。`);
+  return lines.join("\n");
+}
+
+// 查计划任务（Windows）：schtasks 只读查询，不需要管理员。返回 { output, error }；
+// 非 Windows 返回 null（evaluateTask 据此跳过）。deps.taskQuery 可注入以便测试。
+export function queryTask(taskName = "ghprobe") {
+  if (process.platform !== "win32") { return Promise.resolve(null); }
+  return new Promise((resolve) => {
+    execFile("schtasks", ["/query", "/tn", taskName], { windowsHide: true }, (e, stdout, stderr) => {
+      resolve(e
+        ? { output: "", error: stderr ? String(stderr).trim().split(/\r?\n/)[0] : String(e.message).slice(0, 80) }
+        : { output: String(stdout), error: "" });
+    });
+  });
+}
+
+// 完整一轮自检。deps 全部可注入（测试用）；缺省用真实实现。
+// 返回 { ok, checks }，CLI 层负责打印与退出码。
+export async function runDoctor(cfg, log = () => {}, deps = {}) {
+  const d = {
+    hasNetwork: deps.hasNetwork || hasLocalNetwork,
+    dohResolve: deps.dohResolve || resolveAll,
+    probe: deps.probe || runProbe,
+    readHosts: deps.readHosts || (() => { try { return readFileSync(WIN_HOSTS, "utf8"); } catch { return ""; } }),
+    taskQuery: deps.taskQuery || queryTask,
+    blockedFromRaw: deps.blockedFromRaw || null,
+  };
+  const checks = [];
+
+  // ① 本地网络：断网时后面的探测全无意义，直接给结论收场
+  const online = await d.hasNetwork(cfg);
+  checks.push(online
+    ? check("network", "本地网络", "ok", "可上网")
+    : check("network", "本地网络", "fail", "本机无网络连接",
+      "ghprobe 修不了断网：先恢复联网，之后计划任务会自动继续"));
+  if (!online) { return { ok: false, checks }; }
+
+  // ② DoH 连通性：deps.probe 被注入（测试替身）时跳过，避免测试打真网络
+  if (!deps.probe) {
+    const { ips, sources } = await d.dohResolve(cfg.doh, cfg.domains[0], cfg.timeouts.dohMs);
+    checks.push(evaluateDoh(sources, ips));
+  }
+
+  // ③ 一轮完整探测
+  const r = await d.probe(cfg, log);
+  const blocked = (d.blockedFromRaw || blockedDomainsFromRaw)(r.raw || []);
+  checks.push(...evaluateProbe(r.ranked || new Map(), blocked, cfg));
+
+  // ④ hosts 块状态
+  const hosts = evaluateHosts(d.readHosts(), cfg, Boolean(deps.probe));
+  checks.push(...hosts.checks);
+
+  // ⑤ 计划任务
+  checks.push(evaluateTask(await d.taskQuery()));
+
+  return { ...overall(checks), checks };
+}

package/src/health.js

@@ -265,15 +265,17 @@ function sameExtras(a, b) {
 }
 
 // 完整一轮健康检查：读 -> 测已写入 -> 决策 -> （异常时）全量探测 + 部分更新
-// write=true 时才真正 applyHosts（会弹 UAC），否则仅预览
-export async function runHealth(cfg, log, write = false, hostsPath = WIN_HOSTS) {
+// write=true 时才真正 applyHosts（会弹 UAC），否则仅预览。
+// hooks.beforeApply（0.6.0，daemon 传）：写前门控 —— meta = { deadDomains, initial, changed,
+// reason, block, cfg }，返回 false 表示「按用户行为算法推迟」，本轮不落盘、块由门控方保存。
+export async function runHealth(cfg, log, write = false, hostsPath = WIN_HOSTS, promote = new Map(), hooks = {}) {
   const say = log || (() => {});
   const content = fs.readFileSync(hostsPath, "utf8");
   const current = parseBlock(content);
 
   if (current.entries.size === 0) {
     say("hosts 无 ghprobe 记录，触发首次全量");
-    return fullUpdate(cfg, log, content, current, targetDomains(cfg), write, hostsPath);
+    return fullUpdate(cfg, log, content, current, targetDomains(cfg), write, hostsPath, promote, hooks);
   }
 
   // 🔴 主条目 + 备选条目一起探活。旧版只探主条目 —— 于是「主 IP 挂了、备选还是好的」
@@ -296,14 +298,22 @@ export async function runHealth(cfg, log, write = false, hostsPath = WIN_HOSTS)
     return { action: "none", reason: decision.reason, block: null, stuck: [] };
   }
 
+  // 主备全死的域名数（0.6.0）：algorithm 门控的 P0 紧急度 —— 用户此刻真的断着
+  const byDomain = new Map();
+  for (const r of probeResults) {
+    if (!byDomain.has(r.domain)) { byDomain.set(r.domain, []); }
+    byDomain.get(r.domain).push(r);
+  }
+  const deadAll = [...byDomain.entries()].filter(([, rs]) => rs.every((r) => !r.ok)).map(([d]) => d);
+
   say(`异常：${decision.reason}`);
-  return fullUpdate(cfg, log, content, current, decision.domains, write, hostsPath, decision.promote);
+  return fullUpdate(cfg, log, content, current, decision.domains, write, hostsPath, decision.promote, hooks, deadAll);
 }
 
 // 全量探测 + 部分更新 + 写回；护栏与粘性都在 applyDelta 里体现。
 // 只探 diagnose 里的域名：典型场景是「github.com 的 IP 死了，codeload / jsdelivr 还活着」，
 // 此时探 1 个域名（~8 个候选）而不是 6 个（~48 个），失败发现到修好的时间从 ~90s 压到 ~20s。
-async function fullUpdate(cfg, log, content, current, diagnose, write, hostsPath = WIN_HOSTS, promote = new Map()) {
+async function fullUpdate(cfg, log, content, current, diagnose, write, hostsPath = WIN_HOSTS, promote = new Map(), hooks = {}, deadAll = []) {
   const say = log || (() => {});
   // diagnose 为空 = 只有「提上备选」要做，没有需要重排的域名 -> 跳过探测，直接写提升结果
   const r = diagnose.length ? await runProbe(cfg, log, diagnose) : { ranked: new Map(), extra: new Map(), raw: [] };
@@ -332,6 +342,18 @@ async function fullUpdate(cfg, log, content, current, diagnose, write, hostsPath
   if (d.sniBlocked.length) { parts.push(`指纹阻断: ${d.sniBlocked.join(", ")}`); }
   const msg = parts.length ? parts.join("；") : "更新缺失域名冷却记录";
   if (write) {
+    // 0.6.0 用户行为门控：P0（有主备全死的域名）/ 首次写入 直接过；
+    // 非紧急优化类在「用户正用浏览器」时被拒 —— 块由门控方保存，空闲后落地。
+    if (hooks.beforeApply) {
+      const ok = await hooks.beforeApply({
+        deadDomains: deadAll, initial: current.entries.size === 0,
+        changed: d.changed, reason: msg, block, cfg,
+      });
+      if (!ok) {
+        say(`按用户行为算法推迟写入（用户正在用浏览器；修复类不受限，上限 10 分钟）`);
+        return { action: "deferred", reason: "按 algorithm 推迟写入（浏览器使用中）", block, stuck: d.stuck };
+      }
+    }
     const lock = acquireHostsLock();
     if (!lock) {
       say("另一进程正在写 hosts，本轮跳过（下轮健康检查会自动补写）");
@@ -340,7 +362,7 @@ async function fullUpdate(cfg, log, content, current, diagnose, write, hostsPath
     try {
       // 锁内重读最新 hosts：探测耗时期间他人可能已改过，避免覆盖别人刚写的新值
       const latest = fs.readFileSync(hostsPath, "utf8");
-      await applyHosts(mergeHosts(latest, block));
+      await applyHosts(mergeHosts(latest, block), hostsPath);
       say(`已写入 hosts：${msg}${stuckNote}`);
     } finally { releaseHostsLock(lock); }
   } else {

package/src/hosts.js

@@ -17,6 +17,63 @@ export function userDataDir() {
   return path.join(base, "ghprobe");
 }
 
+// ---------- 暂停（ghprobe off / on，0.1.6） ----------
+// off 的语义是「先别动我的网络」，不是卸载：剥掉 hosts 块 + 暂停计划任务 + 落暂停标记。
+// daemon / health 见到标记直接跳过，不再探测也不写 hosts；on 反之并当场触发一轮。
+// 标记文件必须是第一动作 —— off 和计划任务正在跑的一轮是并发的，先落标记才能保证
+// 「正在跑的那轮也看到暂停」，不会出现 off 刚剥完块又被那一轮写回去。
+
+// 暂停标记路径（dir 可注入供单测，不碰真实用户目录）
+export function pausedFlagPath(dir = userDataDir()) {
+  return path.join(dir, "paused");
+}
+
+export function isPaused(file = pausedFlagPath()) {
+  try { return fs.existsSync(file); } catch { return false; }
+}
+
+export function setPaused(paused, file = pausedFlagPath()) {
+  try {
+    if (paused) {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, `${new Date().toISOString()}\n`);
+    } else {
+      fs.rmSync(file, { force: true });
+    }
+    return true;
+  } catch { return false; }
+}
+
+// ---------- 日志滚动（0.1.6） ----------
+// daemon/监督者每 15~60s 追加一行日志，此前只增不减 —— 长跑机器会无限膨胀
+// （2026-11-13 实测一台装了几天没动的机器已经 33MB）。滚动策略：超过 max 字节就把
+// 文件截成「保留最后 keep 字节」，控制权交还给追加方，不需要额外的滚动进程。
+export const LOG_MAX_BYTES = 2 * 1024 * 1024;   // 超过就滚
+export const LOG_KEEP_BYTES = 256 * 1024;       // 滚动时保留的尾部
+
+export function rotateLogIfNeeded(file, opts = {}) {
+  const max = opts.max ?? LOG_MAX_BYTES;
+  const keep = opts.keep ?? LOG_KEEP_BYTES;
+  let st;
+  try { st = fs.statSync(file); } catch { return false; }
+  if (st.size <= max) { return false; }
+  try {
+    const start = Math.max(0, st.size - keep);
+    const fh = fs.openSync(file, "r");
+    let buf;
+    try {
+      buf = Buffer.alloc(st.size - start);
+      fs.readSync(fh, buf, 0, buf.length, start);
+    } finally { fs.closeSync(fh); }
+    // 起点大概率落在半行上，掐掉第一行残片，避免留下一条读不懂的脏日志
+    const text = buf.toString("utf8").replace(/^[^\r\n]*\r?\n/, "");
+    const tmp = `${file}.rotating`;
+    fs.writeFileSync(tmp, "\ufeff" + text, "utf8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch { return false; } // 滚动失败不影响主流程：下一轮追加时再试
+}
+
 // 写 hosts 跨进程锁：probe --apply 与计划任务（health --apply）可能并发，避免读改写互踩
 export const HOSTS_LOCK = path.join(os.tmpdir(), "ghprobe-hosts.lock");
 const LOCK_STALE_MS = 60000;
@@ -118,6 +175,32 @@ export function buildUninstallTaskScript(taskName = "ghprobe") {
     + ` exit 0`;
 }
 
+// 构造「暂停/恢复计划任务」的提权脚本（ghprobe off / on 用）。任务不存在直接 exit 0（幂等）：
+// off 在没安装过的机器上跑不应报错；重复 off/on 同样幂等。
+// 与 buildUninstallTaskScript 同一条纪律：动作必须 -ErrorAction Stop，否则「拒绝访问」
+// 这类非终止错误会把失败伪装成 exit 0。
+export function buildPauseTaskScript(paused, taskName = "ghprobe") {
+  const verb = paused ? "Disable" : "Enable";
+  const cn = paused ? "暂停" : "恢复";
+  return `try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {};`
+    + ` if (-not (Get-ScheduledTask -TaskName '${taskName}' -ErrorAction SilentlyContinue))`
+    + ` { [Console]::Error.WriteLine('计划任务 ${taskName} 不存在，跳过'); exit 0 };`
+    + ` try { ${verb}-ScheduledTask -TaskName '${taskName}' -ErrorAction Stop | Out-Null }`
+    + ` catch { [Console]::Error.WriteLine('${cn}计划任务失败: ' + $_.Exception.Message); exit 1 };`
+    + ` exit 0`;
+}
+
+// 构造「立即触发一轮健康检查」的提权脚本（ghprobe on 用）：恢复后不等下一个间隔，
+// 当场跑一轮 —— on 之后用户应该在一分钟内看到 hosts 重新写好，而不是干等。
+export function buildStartTaskScript(taskName = "ghprobe") {
+  return `try { [Console]::OutputEncoding = [Text.Encoding]::UTF8 } catch {};`
+    + ` if (-not (Get-ScheduledTask -TaskName '${taskName}' -ErrorAction SilentlyContinue))`
+    + ` { [Console]::Error.WriteLine('计划任务 ${taskName} 不存在，跳过'); exit 0 };`
+    + ` try { Start-ScheduledTask -TaskName '${taskName}' -ErrorAction Stop }`
+    + ` catch { [Console]::Error.WriteLine('触发计划任务失败: ' + $_.Exception.Message); exit 1 };`
+    + ` exit 0`;
+}
+
 // 构造「写入 hosts + 注册计划任务」的提权脚本（install 用）：一次 UAC 完成两件事。
 // 与 buildApplyScript 的区别：中途不 exit，两件事都做完后再按综合结果返回退出码，
 // 这样 install 只需弹一次 UAC，且能拿到「两件事各自成功与否」的确定结果。

package/src/pool.js

@@ -118,13 +118,16 @@ export function fetchFirstMeta(seeds, host, pathName, timeoutMs) {
 }
 
 // 种子 IP：拉 meta 用的直连入口。优先用配置里的 seed 池，再退回 azure / fastly。
-export function seedIps(cfg) {
+// extra：调用方传入的**健康 hosts 条目**（0.4.0 自救）——它们刚通过三关 + HTTP 终审，
+// 是「当下确实能直连 GitHub」的 IP；当 seed 池被 SNI 整段封锁、静态种子全灭时，
+// 这批 IP 往往是唯一还拉得到 meta 的入口，池子不至于永久冻结。
+export function seedIps(cfg, extra = []) {
   const p = cfg.ipPools || {};
-  return [...new Set([...(p.seed || []), ...(p.azure || []), ...(p.fastly || [])])];
+  return [...new Set([...extra, ...(p.seed || []), ...(p.azure || []), ...(p.fastly || [])])];
 }
 
 // 一轮更新：拉 meta -> 展开 -> 写缓存。失败也会写 lastAttempt（冷却），避免每分钟重试撞 60 次/小时限制。
-export async function updatePool(cfg, log = () => {}) {
+export async function updatePool(cfg, log = () => {}, extraSeeds = []) {
   const u = cfg.poolUpdate || {};
   const url = new URL(u.source || "https://api.github.com/meta");
   const host = u.host || url.hostname;
@@ -133,8 +136,8 @@ export async function updatePool(cfg, log = () => {}) {
   const attemptedAt = new Date().toISOString();
   const prev = readPoolCache();
   try {
-    const seeds = seedIps(cfg);
-    if (!seeds.length) { throw new Error("配置里没有种子 IP（ipPools.seed / azure / fastly 全为空）"); }
+    const seeds = seedIps(cfg, extraSeeds);
+    if (!seeds.length) { throw new Error("配置里没有种子 IP（ipPools.seed / azure / fastly 全为空，也没有健康 hosts 条目）"); }
     // 并行试所有种子，第一个成功的立刻返回（实测 8.2s -> 亚秒级；串行时是 2m13s）。
     const { json, via } = await fetchFirstMeta(seeds, host, pathName, timeoutMs);
 

package/src/probe.js

@@ -3,7 +3,7 @@
 // 一轮完整探测：DoH 候选 + 内置池 -> 三关并发探测 -> 排名 -> 兜底轮
 import { resolveAll } from "./doh.js";
 import { probeIp, pool } from "./prober.js";
-import { rank, neededFallbacks } from "./ranker.js";
+import { rank, neededFallbacks, mergeSamples } from "./ranker.js";
 
 // 该域名该用哪些内置池。
 // 默认（未配 domainPools 或配了不存在的池名）用全部池 —— 保持「与域名无关地全量进候选」
@@ -59,8 +59,21 @@ export async function runProbe(cfg, log, onlyDomains = null) {
   const directFb = want ? [...want].filter((d) => fbDomains.includes(d) && !cfg.domains.includes(d)) : [];
 
   const resolved = await resolveCandidates(cfg, mainDomains, say);
-  const all = await pool(jobsOf(cfg, resolved), cfg.probe.concurrency);
-  const ranked = rank(all, cfg);
+  let all = await pool(jobsOf(cfg, resolved), cfg.probe.concurrency);
+  let ranked = rank(all, cfg);
+
+  // 复测抗抖动（0.3.0）：对每域名当前前 3 名各再采一枪，均值 + 失败罚分后重排名。
+  // 代价极小（≤24 个快候选、约 1~2s），换来「写进 hosts 的第一名是真的稳」——
+  // 单采样时同一 IP 相邻两轮分差可达数倍，排名近乎随机，而无谓的换 IP 要刷 DNS 缓存。
+  if ((cfg.probe.stableSamples ?? 2) >= 2) {
+    const jobs = [];
+    for (const [, rs] of ranked) {
+      for (const r of rs.slice(0, 3)) { jobs.push(() => probeIp(r.domain, r.ip, cfg)); }
+    }
+    const second = await pool(jobs, cfg.probe.concurrency);
+    all = mergeSamples(all, second);
+    ranked = rank(all, cfg);
+  }
 
   // 兜底轮：主域名全灭且配了替身 -> 探测替身域名
   const extra = new Map();