ghprobe 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -5,6 +5,38 @@
 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+> **版本号说明**：npm 发布采用 `0.1.x` 版本线（`npm i -g ghprobe` 装到的就是它）；
+> 0.1.5 及之前的 npm 包内含仓库内部 0.2~0.6 的全部能力（对应关系：npm 0.1.5 ≈ 内部 0.6.0）。
+> **自 0.1.6 起条目直接使用 npm 版本号**，内部版本号不再单独记录。
+
+## [0.1.6] - 2026-11-13
+
+### Added
+
+- **`ghprobe off` / `ghprobe on`：一键暂停与恢复（不卸载）**。off = 剥掉 hosts 块 +
+  暂停计划任务 + 落暂停标记，daemon / 健康检查见到标记直接跳过（连探测请求都不发）；
+  on = 反向恢复并当场触发一轮健康检查，约 1 分钟内重新写好 hosts。
+  适合出差、换网、临时装了代理工具的场景，不用整个 uninstall。
+  手动 `probe --apply` 是显式意图不受门约束，但会提示当前处于暂停状态。
+- **`ghprobe report`：报障诊断包**。版本 / 系统 / 暂停状态 / status / 配置差异 /
+  hosts 块 / 自愈日志尾部一次收集，自动复制到剪贴板并落盘
+  （`%LOCALAPPDATA%\ghprobe
+- **更新检查**：交互命令（install / status / doctor / probe / report）每天最多查一次
+  npm registry（npmmirror 优先、官方源兜底、5s 超时、失败静默），有新版提示
+  `npm i -g ghprobe`。只提示不自动升级；daemon / 计划任务静默路径绝不联网查版本。
+
+### Fixed
+
+- **自愈日志无限膨胀**（重要）：daemon / 监督者每 15~60s 追加一行，日志此前只增不减，
+  长跑机器实测可攒到几十 MB。现在追加前自动滚动：超过 2MB 只保留最后 256KB，
+  老用户升级后下次写入自动截断，无需手动清理。
+
+### Changed
+
+- `status` 在暂停状态下首行显示恢复指引；hosts 块被 off 剥掉时不再误导用户「先跑 install」。
+- `uninstall` 顺带清掉暂停标记（重装 = 全新开始）。
+
+
 ## [0.6.0] - 2026-10-31
 
 ### Added

package/README.md

@@ -22,6 +22,7 @@
 ```bash
 npm install -g ghprobe
 ghprobe install     # 探测一次 + 写入 hosts + 注册每分钟健康检查（全程只弹一次 UAC）
+ghprobe off         # 暂停：剥掉 hosts 块 + 停止自愈写入（不卸载；恢复用 ghprobe on）
 ghprobe uninstall   # 停止：删除计划任务并还原 hosts
 ```
 
@@ -360,6 +361,15 @@ ghprobe health --apply      # 检测到异常时写入系统 hosts（会弹 UAC
 # GitHub 连不上不知道哪坏了？先跑它。有 fail 项时退出码非零，方便脚本判断
 ghprobe doctor
 
+# 暂停 / 恢复（不卸载）：off = 剥掉 hosts 块 + 暂停计划任务 + 停止自愈写入，
+# 出差、换网、临时不想用时不用整个卸载；on = 恢复并当场触发一轮健康检查
+ghprobe off
+ghprobe on
+
+# 报障诊断包：版本 / status / 配置差异 / hosts 块 / 日志尾部，
+# 自动复制到剪贴板并落盘 —— 提 issue 时直接粘贴，报障成本最低
+ghprobe report
+
 # 从 GitHub 官方 api.github.com/meta 更新候选池缓存（每天一次即可）
 # 该 API 未认证限 60 次/小时，所以别频繁调；health 到点也会自动调，一般不用手动
 ghprobe update-pool
@@ -469,16 +479,19 @@ schedule:
 ```
 
 
-### 卸载 / 回滚与日志
+### 卸载 / 暂停 / 回滚与日志
 
 ```bash
+ghprobe off                    # 暂停：剥掉 hosts 块 + 暂停计划任务 + 停止自愈（不卸载）
+ghprobe on                     # 恢复：清暂停标记 + 恢复计划任务 + 当场触发一轮健康检查
 ghprobe uninstall              # 删除计划任务 + 还原 hosts（只删自己的行）
 ```
 
 如果你是用 `install.ps1` 部署的，也可以用 `.\install.ps1 -Uninstall`。
 
+- **只是临时不想用**（出差、换网络环境、装了别的代理工具）：用 `ghprobe off`，不用卸载 —— GitHub 立刻回到系统默认解析，自愈完全停手；`ghprobe on` 一键恢复（约 1 分钟内重新写好 hosts）。
 - **手动回滚 hosts**：写入前会备份到 `C:\Windows\System32\drivers\etc\hosts.ghprobe-bak`；但更推荐用 `ghprobe uninstall`（它按块剥离，不会误伤第三方后来追加的条目）。
-- **健康检查日志**：`%LOCALAPPDATA%\ghprobe\ghprobe.log`。计划任务静默运行、stdout/stderr 都被丢弃，所以每轮结果会追加到这里（含 `action` / `reason` / `changed`），跑挂了能查。
+- **健康检查日志**：`%LOCALAPPDATA%\ghprobe\ghprobe.log`。计划任务静默运行、stdout/stderr 都被丢弃，所以每轮结果会追加到这里（含 `action` / `reason` / `changed`），跑挂了能查。日志**自动滚动**：超过 2MB 只保留最后 256KB，不会无限膨胀（0.1.6 起；此前长跑机器能攒出几十 MB，升级后下次写入自动截断）。
 - **用户配置**：`%LOCALAPPDATA%\ghprobe\config.yaml`（可编辑，见上一节）。
 - **候选池缓存**：`%LOCALAPPDATA%\ghprobe\pool.cache.json`（`update-pool` 自动维护，不用手改）。
 - **部署日志**：用 `install.ps1` 时默认写到 `%TEMP%\ghprobe-deploy.log`。
@@ -559,6 +572,12 @@ ghprobe install -c my.yaml
 **Q：为什么有时候修不好？**  
 工具只能找到**当前网络、当前时刻**可用的 IP。如果遇到的是 SNI 主机名黑名单（换 IP 修不了）或 IP 黑洞，可能所有候选都不可用。此时会命中兜底链（如果配了），或者触发全灭护栏 —— **保留旧 IP、不写空块**，绝不会硬塞一个错误 IP 进去。
 
+**Q：点了 GitHub 一开始没反应，过一会又自己好了？**  
+这是**链路抖动 + 客户端自动兜底**在工作，不是坏了。ghprobe 每个域名写 2 条 IP（主 + 备选）：首条恰好在分钟级的抖动窗口里被拦时，浏览器 / git 会自动去试备选（代价是多等一个连接超时，所以「没反应」一下）；两条同时失效的话，常驻自愈 15~45s 内换 IP。「没反应」持续超过一分钟才需要管：跑 `ghprobe status` 看 hosts 与自愈日志，不行再 `ghprobe doctor` 定位。
+
+**Q：遇到问题怎么报？**  
+先跑 `ghprobe report`（生成诊断包并复制到剪贴板）和 `ghprobe doctor`，把两份输出贴到 <https://github.com/zmw-zmw/ghprobe/issues>。诊断包只含版本信息、hosts 块和自愈日志尾部，**不含任何个人数据**。
+
 **Q：会不会影响别的软件？**  
 不会。它**只写 hosts 文件**，不装代理、不改系统代理设置、不劫持流量。而且只操作 `# === ghprobe begin/end ===` 之间属于它自己的那一块，**你原有的 hosts 条目和第三方工具写的条目都不会被改动**；卸载时也只剥掉自己的块。
 

package/bin/ghprobe.js

@@ -13,9 +13,10 @@ import { hasLocalNetwork } from "../src/net.js";
 import { probeNow, startServer } from "../src/server.js";
 import { runHealth, blockFromProbeResult, shouldKeepOldBlock, parseBlock } from "../src/health.js";
 import { runDoctor, formatReport, queryTask } from "../src/doctor.js";
-import { runStatus } from "../src/status.js";
+import { runStatus, readLogTail } from "../src/status.js";
 import { runDaemon, readHeartbeat, heartbeatFresh, daemonRunning } from "../src/daemon.js";
-import { mergeHosts, applyHosts, restoreHosts, WIN_HOSTS, acquireHostsLock, releaseHostsLock, runElevated, buildUninstallTaskScript, buildInstallScript, buildHiddenRunnerVbs, userDataDir } from "../src/hosts.js";
+import { mergeHosts, applyHosts, restoreHosts, WIN_HOSTS, acquireHostsLock, releaseHostsLock, runElevated, buildUninstallTaskScript, buildInstallScript, buildHiddenRunnerVbs, userDataDir, isPaused, setPaused, buildPauseTaskScript, buildStartTaskScript, rotateLogIfNeeded } from "../src/hosts.js";
+import { maybeNotifyUpdate } from "../src/updates.js";
 import { readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 
@@ -47,6 +48,8 @@ function appendRawLog(line) {
   try {
     const f = healthLogPath();
     fs.mkdirSync(path.dirname(f), { recursive: true });
+    // 追加前先滚动：日志只增不减的话，长跑机器几个月能攒出几十 MB（0.1.6 前实测 33MB）
+    rotateLogIfNeeded(f);
     const prefix = fs.existsSync(f) ? "" : "\ufeff";
     fs.appendFileSync(f, prefix + line);
   } catch { /* 日志写失败不影响主流程 */ }
@@ -83,6 +86,11 @@ const program = new Command();
 const PKG = JSON.parse(readFileSync(path.join(ROOT, "package.json"), "utf8"));
 program.name("ghprobe").description("GitHub 直连优选：本地 DoH + TLS 证书终审探测 + hosts 生成（无代理）").version(PKG.version);
 
+// 交互命令开头的版本提示（内部每天最多查一次 registry；只提示不自动升级，失败静默）
+function notifyUpdate() {
+  return maybeNotifyUpdate(PKG.version, console.log);
+}
+
 // 打印一轮结果的可读摘要
 function printSummary(r) {
   for (const [domain, rs] of r.ranked) {
@@ -99,6 +107,7 @@ program.command("doctor")
   .description("一键自检：网络 / DoH / 探测 / hosts / 计划任务，人话结论 + 下一步建议")
   .option("-c, --config <path>", "用户配置覆盖")
   .action(async (opts) => {
+    await notifyUpdate();
     const cfg = loadConfig(opts.config);
     console.error("ghprobe 自检中（跑一轮完整探测，约 1 分钟）…");
     const r = await runDoctor(cfg, (m) => console.error(m));
@@ -119,6 +128,7 @@ program.command("status")
   .description("秒级速查：hosts 现状 + 自愈日志尾部 + 计划任务（不打任何网络请求）")
   .option("-c, --config <path>", "用户配置覆盖")
   .action(async (opts) => {
+    await notifyUpdate();
     const cfg = loadConfig(opts.config);
     const r = await runStatus(cfg, { taskQuery: () => queryTask() });
     console.log(r.lines.join("\n"));
@@ -140,10 +150,15 @@ program.command("probe")
     if (opts.json) {
       const out = { at: r.at, domains: [...r.ranked].map(([d, rs]) => ({ domain: d, alive: rs.map((x) => ({ ip: x.ip, tcpMs: x.tcpMs, tlsMs: x.tlsMs, ttfb: x.ttfb, score: x.score })) })), extra: [...r.extra].map(([d, rs]) => ({ domain: d, alive: rs.map((x) => x.ip) })) };
       console.log(JSON.stringify(out, null, 2));
-    } else {
-      printSummary(r);
+      return; // JSON 是给脚本消费的，不掺提示行
     }
+    await notifyUpdate();
+    printSummary(r);
     if (opts.apply) {
+      // 显式命令不受暂停门约束（那是给自动化设的），但要提醒用户自动化还停着
+      if (isPaused()) {
+        console.error("注意：当前处于暂停状态（ghprobe off），本轮按你的显式要求仍写入 hosts；恢复自动化跑 ghprobe on");
+      }
       const lock = acquireHostsLock();
       if (!lock) {
         console.error("另一进程正在写 hosts，本轮跳过（下轮健康检查会自动补写）");
@@ -188,6 +203,12 @@ program.command("health")
   .option("-a, --apply", "检测到异常时写入系统 hosts（会弹 UAC）")
   .option("-f, --force", "跳过 daemon 监督逻辑，本轮亲自跑（诊断用）")
   .action(async (opts) => {
+    // ghprobe off 后自愈彻底停手：不探测、不写 hosts、不拉 daemon（标记由 off/on 维护）
+    if (isPaused()) {
+      console.error("ghprobe 处于暂停状态（ghprobe off），本轮跳过 —— 恢复跑 ghprobe on");
+      writeHealthLog("skip", "已暂停（ghprobe off），本轮不探测不写 hosts");
+      return;
+    }
     let cfg = loadConfig(opts.config);
     // 0.5.0 监督者逻辑：daemon 心跳新鲜 -> 秒退（它在干活，重复探测纯属浪费）；
     // 心跳陈旧/没有 -> 拉起新 daemon（分离进程），本轮仍照常执行，作为 daemon 就位前的兜底。
@@ -231,6 +252,7 @@ program.command("install")
   .option("-c, --config <path>", "用户配置覆盖（间隔取 schedule.healthMin 分钟）")
   .option("--skip-probe", "只注册计划任务，不立即探测写 hosts（等下一次定时触发）")
   .action(async (opts) => {
+    await notifyUpdate();
     // 生成用户可编辑的配置文件（已存在则不覆盖，保留用户改动）
     const ucfg = ensureUserConfig();
     const cfg = loadConfig(opts.config);
@@ -297,9 +319,55 @@ program.command("install")
     console.log("停止：ghprobe uninstall");
   });
 
+program.command("off")
+  .description("一键暂停：剥掉 hosts 块 + 暂停计划任务 + 落暂停标记（自愈停止写入）。GitHub 回到系统默认解析；恢复用 ghprobe on")
+  .action(async () => {
+    // 先落标记：off 与计划任务正在跑的一轮是并发的，标记是第一动作才能保证
+    // 正在跑的那轮也看到暂停，不会刚剥完块又被那一轮写回去
+    setPaused(true);
+    let taskOk = true;
+    try {
+      const r = await runElevated(buildPauseTaskScript(true));
+      if (r.code !== 0) { taskOk = false; console.error(`暂停计划任务失败: ${r.err || r.out}`); }
+    } catch (e) { taskOk = false; console.error(`暂停计划任务失败: ${e.message}`); }
+    try {
+      await restoreHosts();
+      console.log("已暂停：hosts 块已剥离、DNS 缓存已刷新，GitHub 恢复系统默认解析");
+    } catch (e) {
+      console.error(`剥离 hosts 块失败: ${e.message}（暂停标记已落，自动化不会再写入；hosts 里可能还残留 ghprobe 条目，可手动删或重跑 ghprobe off）`);
+      process.exitCode = 1;
+    }
+    if (taskOk) { console.log("计划任务已暂停，常驻自愈停止写入"); }
+    console.log("恢复：ghprobe on（当场触发一轮健康检查，约 1 分钟内重新写好 hosts）");
+    if (!taskOk) { process.exitCode = 1; }
+  });
+
+program.command("on")
+  .description("恢复（ghprobe off 的逆操作）：清暂停标记 + 恢复计划任务 + 当场触发一轮健康检查")
+  .action(async () => {
+    setPaused(false);
+    let ok = true;
+    try {
+      const r = await runElevated(buildPauseTaskScript(false));
+      if (r.code !== 0) { ok = false; console.error(`恢复计划任务失败: ${r.err || r.out}`); }
+    } catch (e) { ok = false; console.error(`恢复计划任务失败: ${e.message}`); }
+    if (ok) {
+      try {
+        const r = await runElevated(buildStartTaskScript());
+        if (r.code !== 0) { console.error(`当场触发失败: ${r.err || r.out}（不致命，下一个间隔任务会自动跑）`); }
+        else { console.log("已当场触发一轮健康检查，约 1 分钟内 hosts 重新写好"); }
+      } catch (e) { console.error(`当场触发失败: ${e.message}（不致命，下一个间隔任务会自动跑）`); }
+    } else {
+      process.exitCode = 1;
+    }
+    console.log("已恢复：ghprobe 自动自愈回到工作状态");
+  });
+
 program.command("uninstall")
   .description("删除 ghprobe 计划任务并还原 hosts")
   .action(async () => {
+    // 暂停标记一并清掉：重装 = 全新开始，不要把上一次的 off 状态带进新装
+    setPaused(false);
     // 两步互相独立：任一步失败都不影响另一步，最后统一置 exitCode
     try {
       await restoreHosts();
@@ -370,4 +438,68 @@ program.command("config-diff")
     console.log(`配置文件：${userConfigPath()}`);
   });
 
+program.command("report")
+  .description("生成报障诊断包：版本/系统/暂停状态/status/配置差异/hosts 块/日志尾部，复制到剪贴板并落盘（贴 issue 用）")
+  .option("-o, --out <path>", "诊断包写入路径（默认 %LOCALAPPDATA%\\ghprobe\\report-<时间>.txt）")
+  .action(async (opts) => {
+    await notifyUpdate();
+    const cfg = loadConfig();
+    const lines = [];
+    lines.push(`ghprobe ${PKG.version} report`);
+    lines.push(`node ${process.version} / ${process.platform} / os=${os.release()} / ${new Date().toISOString()}`);
+    lines.push(`暂停状态：${isPaused() ? "已暂停（ghprobe off）" : "正常"}`);
+    lines.push("");
+    lines.push("== status ==");
+    try {
+      const r = await runStatus(cfg, { taskQuery: () => queryTask() });
+      lines.push(...r.lines);
+    } catch (e) { lines.push(`status 失败: ${e.message}`); }
+    lines.push("");
+    lines.push("== config-diff ==");
+    try {
+      const { hasUser, diff } = configDiff();
+      lines.push(hasUser ? (diff.length ? `用户配置与默认有 ${diff.length} 处差异：${diff.map((d) => d.key).join(", ")}` : "用户配置与当前默认一致") : "无用户配置（还没跑过 install）");
+    } catch (e) { lines.push(`config-diff 失败: ${e.message}`); }
+    lines.push("");
+    lines.push("== hosts 块 ==");
+    try {
+      const cur = readFileSync(WIN_HOSTS, "utf8");
+      const m = cur.match(/# === ghprobe begin ===[\s\S]*?(?:# === ghprobe end ===|$)/);
+      lines.push(m ? m[0].trimEnd() : "(无 ghprobe 块)");
+    } catch (e) { lines.push(`hosts 读取失败: ${e.message}`); }
+    lines.push("");
+    lines.push("== 自愈日志尾部（最近 50 行） ==");
+    const tail = readLogTail(50);
+    if (tail.length) { lines.push(...tail); } else { lines.push("(暂无日志)"); }
+    lines.push("");
+    lines.push("== 下一步 ==");
+    lines.push("再跑一次 `ghprobe doctor`，把它的输出也贴进 issue（约 1 分钟，report 里放不下探测过程）。");
+    const text = lines.join("\r\n") + "\r\n";
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const out = opts.out || path.join(userDataDir(), `report-${stamp}.txt`);
+    try {
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, text, "utf8");
+    } catch (e) {
+      console.error(`诊断包落盘失败: ${e.message}`);
+      process.exitCode = 1;
+    }
+    // 尝试复制到剪贴板：失败不影响落盘（诊断包已在文件里）
+    let copied = false;
+    try {
+      await new Promise((resolve) => {
+        const child = spawn("clip", [], { stdio: ["pipe", "ignore", "ignore"] });
+        child.on("error", () => resolve());
+        child.on("close", () => { copied = true; resolve(); });
+        child.stdin.on("error", () => { /* clip 不存在时 write 会 emit，别让它炸进程 */ });
+        child.stdin.write(text);
+        child.stdin.end();
+        setTimeout(resolve, 3000); // clip 偶发不回 close，兜底别挂着
+      });
+    } catch { /* 复制失败不影响落盘 */ }
+    console.log(copied
+      ? `诊断包已复制到剪贴板（可直接粘贴进 issue），同时写在 ${out}`
+      : `诊断包已写入 ${out}（剪贴板复制不可用，请手动打开复制）`);
+  });
+
 program.parseAsync();

package/package.json

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

package/src/daemon.js

@@ -12,7 +12,7 @@
 //   · daemon 崩溃 -> 下一分钟监督者自动复活它；旧版本 npm 用户没有心跳文件，行为完全不变
 import fs from "node:fs";
 import path from "node:path";
-import { userDataDir, applyHosts, mergeHosts, WIN_HOSTS } from "./hosts.js";
+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";
@@ -72,6 +72,12 @@ export function nextIntervalMs(result, intervals = {}) {
 // 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: [] };
   }

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/status.js

@@ -6,7 +6,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseBlock, targetDomains } from "./health.js";
-import { userDataDir, WIN_HOSTS } from "./hosts.js";
+import { userDataDir, WIN_HOSTS, isPaused } from "./hosts.js";
 import { readHeartbeat, heartbeatFresh, processAlive } from "./daemon.js";
 
 export function healthLogPath() {
@@ -28,15 +28,24 @@ function generatedAt(content) {
 }
 
 // 纯函数：由既有状态组装速查报告。全离线 —— 不探测、不解析、不查任务网络。
-export function buildStatusReport({ hostsContent = "", cfg, logTail = [], task = null, daemon = undefined }) {
+export function buildStatusReport({ hostsContent = "", cfg, logTail = [], task = null, daemon = undefined, paused = false }) {
   const current = parseBlock(hostsContent);
   const targets = targetDomains(cfg);
   const lines = [];
 
+  // ⓪ 暂停状态优先展示：off 会剥掉 hosts 块，如果不提示，下面「还没有 ghprobe 块」
+  // 的文案会误导用户以为没装好
+  if (paused) {
+    lines.push("状态：已暂停（ghprobe off）—— hosts 块已剥离，自愈停止写入；跑 ghprobe on 恢复");
+  }
+
   // ① hosts 块现状
   const gen = generatedAt(hostsContent);
   if (!current.entries.size) {
-    lines.push("hosts：还没有 ghprobe 块 —— 先跑 ghprobe install");
+    // off 会主动剥块：此时不能说「先跑 install」（那是装没装的问题），要说「恢复」
+    lines.push(paused
+      ? "hosts：ghprobe 块已剥离（暂停状态，正常现象）—— 跑 ghprobe on 重新写回"
+      : "hosts：还没有 ghprobe 块 —— 先跑 ghprobe install");
   } else {
     lines.push(`hosts：${current.entries.size} 个域名（块生成于 ${gen ?? "?"}）`);
     for (const [d, ip] of current.entries) {
@@ -83,6 +92,7 @@ export async function runStatus(cfg, deps = {}) {
   const hostsContent = deps.hostsContent ?? (() => { try { return fs.readFileSync(WIN_HOSTS, "utf8"); } catch { return ""; } })();
   const logTail = deps.logTail ?? readLogTail();
   const task = deps.taskQuery ? await deps.taskQuery() : null;
-  const lines = buildStatusReport({ hostsContent, cfg, logTail, task });
+  const paused = deps.paused ?? isPaused();
+  const lines = buildStatusReport({ hostsContent, cfg, logTail, task, paused });
   return { lines, entries: parseBlock(hostsContent).entries.size };
 }

package/src/updates.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 更新检查（0.1.6）：npm 全局包不会自动升级，用户停在旧版本就吃不到自愈能力与新候选池
+// 的改进 —— 而我们无从得知谁在用旧版。这里只做一件事：交互命令开头查一次 npm 上的
+// latest，有新版就提示一行 `npm i -g ghprobe`。只提示，绝不自动升级（升级是用户的决定）。
+//
+// 纪律：
+//   · 每天最多拉一次（缓存 24h），且只在**交互命令**里查 —— daemon / 计划任务静默路径
+//     绝不联网查版本，不能为提示增长每隔几十秒打一次 registry。
+//   · 查询源优先 npmmirror（国内网络可达性远好于 registry.npmjs.org），失败再试官方源。
+//   · 任何失败都静默 —— 提示功能本身不许打扰用户，更不许影响命令退出码。
+import fs from "node:fs";
+import path from "node:path";
+import { userDataDir } from "./hosts.js";
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+export function updateCheckPath(dir = userDataDir()) {
+  return path.join(dir, "update.check.json");
+}
+
+// 语义化版本比较：只认 x.y.z 纯数字段（v 前缀容忍）；带 prerelease / 解析不动的输入
+// 一律返回 false（宁可漏提示，不误报）。
+export function isNewer(latest, current) {
+  const parts = (v) => String(v || "").trim().replace(/^v/i, "").split(".").map((x) => parseInt(x, 10));
+  const a = parts(latest);
+  const b = parts(current);
+  if (a.length !== 3 || b.length !== 3 || a.some(Number.isNaN) || b.some(Number.isNaN)) { return false; }
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) { return a[i] > b[i]; }
+  }
+  return false;
+}
+
+// 拉 latest：npmmirror 优先（国内可达），官方源兜底。5s 超时，全败返回 null。
+async function fetchLatest(fetchImpl, pkgName) {
+  for (const url of [`https://registry.npmmirror.com/${pkgName}/latest`, `https://registry.npmjs.org/${pkgName}/latest`]) {
+    try {
+      const r = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+      if (!r || !r.ok) { continue; }
+      const o = await r.json();
+      if (o && typeof o.version === "string" && o.version) { return o.version; }
+    } catch { /* 换下一个源 */ }
+  }
+  return null;
+}
+
+// 查最新版本并写缓存。deps 全可注入（fetchImpl / now / cachePath / pkgName）供单测。
+export async function checkUpdate(deps = {}) {
+  const now = deps.now ?? Date.now();
+  const file = deps.cachePath ?? updateCheckPath();
+  const pkgName = deps.pkgName ?? "ghprobe";
+  let cache = null;
+  try { cache = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* 无缓存/坏缓存 */ }
+  if (cache && Number.isFinite(cache.at) && cache.latest && now - cache.at >= 0 && now - cache.at < CHECK_INTERVAL_MS) {
+    return { latest: cache.latest, cached: true };
+  }
+  const latest = await fetchLatest(deps.fetchImpl || fetch, pkgName);
+  if (latest) {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify({ at: now, latest }));
+    } catch { /* 缓存写失败不影响本次提示 */ }
+  }
+  return { latest, cached: false };
+}
+
+// 交互命令开头调一下：有新版打印一行提示；任何失败静默。
+export async function maybeNotifyUpdate(current, log = console.log, deps = {}) {
+  try {
+    const { latest } = await checkUpdate(deps);
+    if (latest && isNewer(latest, current)) {
+      log(`提示：ghprobe ${latest} 已发布，建议升级 —— npm i -g ghprobe（当前 ${current}）`);
+    }
+  } catch { /* 更新检查失败不打扰 */ }
+}